Debian Codegraph @

texmf-dist/source/support/bib2gls/bib2gls.tex

raw
1 % arara: lualatex
2 % arara: bib2gls: {group: on} if missing("glstex") || changed("bib") || found("log", "Warning: Glossary entry")
3 % arara: bibtex
4 % arara: lualatex if changed("glstex") || missing("toc")
5 % arara: bib2gls: {group: on, packages: [mfirstuc-english]}
6 % arara: lualatex
7 % arara: lualatex
8 \documentclass[titlepage=false,index=totoc,bibliography=totoc,
9 fontsize=12pt,captions=tableheading]{scrreprt}
10
11 \usepackage[autooneside=false]{scrlayer-scrpage}
12 \usepackage{pifont}
13
14 % Need support for less common extended characters
15 % and need a mono font that supports hyphenation
16 \usepackage[no-math]{fontspec}
17 \setmainfont{Linux Libertine O}
18
19 \newfontface\cyrillicmono{FreeMono}[Scale=MatchLowercase]
20 \newcommand{\textcyrillicmono}[1]{{\cyrillicmono #1}}
21
22 \newfontface\greekmono{FreeMono}[Scale=MatchLowercase]
23 \newfontface\freeserif{FreeSerif}
24 \newcommand{\devone}{{\freeserif\char"0967}}
25 \newcommand{\devtwo}{{\freeserif\char"0968}}
26 \newcommand{\devsix}{{\freeserif\char"096C}}
27 \newcommand{\insularG}{{\freeserif\char"A77D}}
28 \newcommand{\insularg}{{\freeserif\char"1D79}}
29 \newcommand{\longs}{\char"017F}
30 \newcommand{\Wynn}{\char"01F7}
31 \newcommand{\wynn}{\char"01BF}
32
33 \usepackage[x11names]{xcolor}
34 \usepackage{alltt}
35 \usepackage{array}
36 \usepackage{upquote}
37 \usepackage{etoolbox}
38
39 \usepackage{hologo}
40 \usepackage{amsmath}
41 \usepackage{accents}
42 \usepackage{tikz}
43 \usepackage{tcolorbox}
44 \usepackage{datetime2}
45 \usepackage{mfirstuc-english}
46 \usepackage{listings}
47 \usepackage{scrhack}
48 \usepackage[hidelinks]{hyperref}
49 \usepackage{cleveref}
50 \usepackage[% v1.47+
51 record,% use bib2gls
52 index,% create index glossary
53 entrycounter,% enable entry counting
54 subentrycounter,% enable entry counting
55 %debug=showtargets,% debugging information
56 %debug=showwrgloss,% debugging information
57 stylemods={mcols,bookindex},% adjust predefined styles and load glossary-mcols.sty and glossary-bookindex.sty
58 style=bookindex
59 ]
60 {glossaries-extra}
61
62 \lstset{language={[LaTeX]TeX},upquote,basicstyle={\ttfamily\small},
63 commentstyle={\color{gray}}}
64
65 \renewcommand*{\glsshowtarget}[1]{\texttt{\small [#1]}}
66
67 \glsxtrprovidestoragekey{note}{}{}
68 \glsxtrprovidestoragekey{package}{}{}
69 \glsxtrprovidestoragekey{nametitle}{}{}
70
71 \providecommand{\omicron}{o}
72
73 % put break before dash to avoid confusion with a hyphen
74 \newcommand{\dhyphen}{%
75 \texorpdfstring
76 {\discretionary{}{}{}\texttt{-}}%
77 {-}%
78 }
79
80 % Redefine \- (used in entry names) so that hyphenation in command names,
81 % switches options etc uses a serif hyphen to reduce confusion with an
82 % actual hyphen in the code.
83 \renewrobustcmd{\-}{%
84 \discretionary
85 {{\rmfamily\char\ifnum\hyphenchar\font<0
86 \defaulthyphenchar\else\hyphenchar\font\fi
87 }}%
88 {}{}%
89 }
90
91 \newcommand\dash{\,---\,}
92
93 \renewcommand{\glsentrycounterlabel}{}
94 \renewcommand{\glssubentrycounterlabel}{}
95 \renewcommand\glstreeitem{\par\hangindent10pt}
96 \renewcommand\glstreesubitem{\par\hangindent30pt\hspace*{15pt}}
97
98 \newcommand{\bibglsseealsosep}{\glstreesubitem}
99
100 \renewcommand*{\glsseesep}{, \glstreesubitem\quad}
101 \renewcommand*{\glsseelastsep}{\glstreesubitem\quad\strut\llap{\andname\space}}
102
103 \newcommand{\glsxtrpostnameabbreviation}{%
104 \space(\glsentrylong{\glscurrententrylabel})%
105 }
106
107 \newcommand{\glsxtrpostnameenvironment}{\space environment}
108 \newcommand{\glsxtrpostnamecounter}{\space counter}
109
110 \newcommand*{\csfmtfont}[1]{\texttt{#1}}
111 \newcommand*{\csfmtcolourfont}[1]{\texttt{\textcolor{cs}{#1}}}
112
113 \newcommand*{\csfmt}[1]{%
114 \texorpdfstring
115 {\csfmtfont{\char`\\ #1}}%
116 {\string\\#1}%
117 }
118
119 \newcommand{\texparserdefprefix}{}
120 \newcommand{\texparserdefnotetarget}{%
121 \raisebox{2ex}{\hypertarget{\texparserdefprefix texparserdef}{}}%
122 \textsuperscript{*}Indicates command is
123 recognised by \bibgls's interpreter although it may have
124 a slightly different implementation.
125 }
126 \newcommand{\texparserdefnote}{\hyperlink{\texparserdefprefix texparserdef}{*}}
127
128 \setabbreviationstyle{long-short-sc}
129 \setabbreviationstyle[common]{short-sc-nolong}
130
131 \glsxtrprovidestoragekey{unsortedprogeny}{}{}
132
133 \newcommand*{\longargfmt}[1]{%
134 \texorpdfstring{\texttt{\longswitch #1}}%
135 {\string-\string-#1}%
136 }
137
138 \GlsXtrLoadResources[
139 entry-type-aliases={
140 bibglscommand=dualindexentry,
141 mainglscommand=spawndualindexentry,
142 glscommand=spawnentry,
143 abbrvstylecommand=spawnentry,
144 glostylecommand=spawnentry,
145 resourceoption=dualindexentry,
146 packageoption=dualindexentry,
147 field=dualindexentry,
148 entrytype=dualindexentry,
149 switch=dualindexentry,
150 samplefile=dualindexentry,
151 examplecommand=dualindexentry,
152 examplesymbol=symbol,
153 exampleabbreviation=abbreviation,
154 exampleentry=entry
155 },
156 max-loc-diff={2},
157 see=omit,seealso=omit,alias=omit,
158 field-aliases={topics=adoptparents,annote=user2},
159 replicate-fields={name=nametitle,progeny=unsortedprogeny},
160 word-boundaries={white space,cs space,dash},
161 field-case-change={nametitle=title},
162 interpret-fields={nametitle},
163 no-case-change-cs={fieldfmt,abbrstylefmt,glostylefmt},
164 short-case-change={lc},
165 dual-short-case-change={lc},
166 unknown-entry-alias={index},
167 save-original-entrytype,
168 label-prefix={idx.},
169 save-loclist=false,
170 sort={letternumber-nocase},
171 sort-replace={{\glshex2423}{ },{\string\\([a-zA-Z])}{\glscapturedgroup1}},
172 type={index},
173 dual-field={dualid},
174 match-action={add},
175 match-op={or},
176 match={
177 {category}={.*field},
178 {original entrytype}={.*(gls|style)command},
179 {original entrytype}={.*option},
180 {original entrytype}={abbreviationstyle},
181 {original entrytype}={glossarystyle},
182 },
183 dual-prefix={},
184 dual-type={main},
185 ext-prefixes={},
186 combine-dual-locations={primary},
187 selection={recorded and deps and see not also},
188 symbol-sort-fallback={name},
189 sort-label-list={progeny:letter-nocase:glsxtrentryparentname},
190 strip-missing-parents,
191 save-child-count
192 ]
193
194 \newglossary*{terms}{Glossary}
195 \GlsXtrLoadResources[src=bib2gls-terms,
196 name-case-change=title,replicate-fields={name=text},
197 type=terms,save-locations=false,category=term]
198
199 \newcommand{\igls}[2][]{%
200 \glsxtrifhasfield{useri}{#2}{\glsadd{\glscurrentfieldvalue}}{}%
201 \gls[#1]{#2}%
202 }
203 \newcommand{\iglspl}[2][]{%
204 \glsxtrifhasfield{useri}{#2}{\glsadd{\glscurrentfieldvalue}}{}%
205 \glspl[#1]{#2}%
206 }
207 \newcommand{\primary}{\glsdisp{primaryentry}{primary}}
208 \newcommand{\dual}{\glsdisp{dualentry}{dual}}
209 \newcommand{\parent}{\glsdisp{parententry}{parent}}
210 \newcommand{\child}{\glsdisp{childentry}{child}}
211 \newcommand{\children}{\glsdisp{childentry}{children}}
212 \newcommand{\hierarchicallevel}{\glsdisp{hierarchicalglossary}{hierarchical level}}
213 \newcommand{\hierarchical}{\glsdisp{hierarchicalglossary}{hierarchical}}
214 \newcommand{\hierarchically}{\glsdisp{hierarchicalglossary}{hierarchically}}
215 \newcommand{\hierarchy}{\glsdisp{hierarchicalglossary}{hierarchy}}
216 \newcommand{\mainglossary}{\glsdisp{mainglossary}{\code{main} glossary}}
217 \newcommand{\supplementallocation}{\glsdisp{supplementalrecord}{supplemental
218 location}}
219 \newcommand{\supplementallocations}{\glsdisp{supplementalrecord}{supplemental
220 locations}}
221 \newcommand{\supplementarylocation}{\glsdisp{supplementalrecord}{supplementary
222 location}}
223 \newcommand{\supplementarylocations}{\glsdisp{supplementalrecord}{supplementary
224 locations}}
225 \newcommand{\supplementarydocument}{\glsdisp{supplementaldocument}{supplementary
226 document}}
227 \newcommand{\supplementarydocuments}{\glsdisp{supplementaldocument}{supplementary
228 documents}}
229 \newcommand{\supplemental}{\glsdisp{supplementaldocument}{supplemental}}
230 \newcommand{\supplementary}{\glsdisp{supplementaldocument}{supplementary}}
231
232 \glsxtraddlabelprefix{}
233 \glsxtraddlabelprefix{idx.}
234
235 \DTMsavetimestamp{creation}{2017-01-20T15:39:00Z}
236
237 \IfFileExists{../java/common/BibGlsTeXApp}
238 {
239 \DTMsavefilemoddate{moddate}{../java/common/BibGlsTeXApp.java}
240 }
241 {
242 \DTMsavenow{moddate}
243 }
244
245 \newif\ifmainmatter
246
247 % ignore locations outside of main matter
248 \GlsXtrSetDefaultNumberFormat{glsignore}
249
250 \GlsXtrSetPlusModifier{format=glsnumberformat}
251 \GlsXtrSetAltModifier{!}{format=glsignore}
252
253 \newcommand{\frontmatter}{%
254 \clearpage\pagenumbering{roman}%
255 \pagestyle{scrheadings}%
256 \automark[section]{chapter}%
257 \mainmatterfalse
258 }
259 \newcommand{\mainmatter}{%
260 \clearpage\pagenumbering{arabic}%
261 \GlsXtrSetDefaultNumberFormat{glsnumberformat}%
262 \mainmattertrue
263 }
264
265 \newcommand{\rightleftmark}[2]{\ifstrequal{#1}{#2}{#1}{#1: #2}}
266 \makeatletter
267 \newcommand{\setsecdepth}{\@ifstar\s@setsecdepth\@setsecdepth}
268 \newcommand{\s@setsecdepth}[1]{%
269 \setcounter{secnumdepth}{#1}%
270 \automark[section]{chapter}%
271 \let\@rightmark\rightleftmark
272 }
273 \newcommand{\@setsecdepth}[1]{%
274 \setcounter{secnumdepth}{#1}%
275 \ifnum#1 > 0
276 \automark[section]{chapter}%
277 \else
278 \automark{chapter}%
279 \fi
280 \let\@rightmark\@secondoftwo
281 }
282 \makeatother
283
284 \newtcolorbox{important}{colback=red!5!white,colframe=red}
285
286 \newcommand{\bibgls}{\appfmt{bib2gls}}
287
288 \newcommand*{\BibTeX}{\hologo{BibTeX}}
289 \newcommand*{\eTeX}{\hologo{eTeX}}
290 \newcommand*{\XeLaTeX}{\hologo{XeLaTeX}}
291 \newcommand*{\LuaLaTeX}{\hologo{LuaLaTeX}}
292 \newcommand*{\pdfLaTeX}{\hologo{pdfLaTeX}}
293
294 \newcommand{\langxml}{\hyperref[sec:lang.xml]{language resource file}}
295 \newcommand{\texparserlib}{\hyperref[sec:texparserlib]{\TeX\ Parser
296 Library}}
297
298 \newcommand{\hex}[1]{0x#1}
299 \newcommand{\hexsb}[1]{\textsubscript{\scriptsize\rmfamily#1}}
300 \newcommand{\subfigfmt}[1]{(\emph{#1})}
301
302 \newcommand{\qt}[1]{``#1''}
303
304 \newcommand{\qtt}[1]{\qt{\,\texttt{#1}\,}}
305
306 \newcommand{\qtdelim}[1]{\idx{doublequotechardelim}#1\idx{doublequotechardelim}}
307
308 \newcommand{\ifnumhex}[1]{\cs{ifnum}\idx{doublequotecharhex}#1}
309
310 \newcommand{\charhex}[1]{\cs{char}\idx{doublequotecharhex}#1}
311 \newcommand{\icharhex}[1]{\ics{char}\idx[format=glsnumberformat,noindex=false]{doublequotecharhex}#1}
312
313 \newcommand{\era}[1]{\texorpdfstring{\textsc{\MakeLowercase{#1}}}{#1}}
314
315 \newcommand{\dequals}{%
316 \texorpdfstring
317 {\discretionary{}{}{}\texttt{=}\discretionary{}{}{}}%
318 {=}%
319 }
320
321 \newcommand{\dcomma}{%
322 \texorpdfstring
323 {\texttt{,}\discretionary{}{}{}}%
324 {,}%
325 }
326
327 \newcommand{\dcolon}{%
328 \texorpdfstring
329 {\texttt{:}\discretionary{}{}{}}%
330 {:}%
331 }
332
333 \pdfstringdefDisableCommands{%
334 \def\dhyphen{-}%
335 \def\dcolon{:}%
336 \def\dcomma{,}%
337 \def\dequals{,}%
338 \let\-\empty
339 }
340
341 % Provide commands that work like \gls[#1]{idx.#2}[#3]
342
343 \glsxtrnewglslike{idx.}{\idx}{\idxpl}{\Idx}{\Idxpl}
344 \newcommand{\idxlink}[3][]{\glslink[#1]{idx.#2}{#3}}
345
346 \newcommand{\stringu}{\idx{cs.string}\gls{uhex}}
347
348 \newcommand*{\filefmt}[1]{\texorpdfstring{\texttt{#1}}{#1}}
349 \newcommand*{\metafilefmt}[3]{%
350 \filefmt{#1}\discretionary{}{}{}\meta{#2}\discretionary{}{}{}\filefmt{#3}%
351 }
352 \newcommand*{\metametafilefmt}[5]{%
353 \filefmt{#1}\discretionary{}{}{}\meta{#2}\discretionary{}{}{}\filefmt{#3}%
354 \discretionary{}{}{}\meta{#4}\discretionary{}{}{}\filefmt{#5}%
355 }
356
357 \newcommand*{\primaryresourcefmt}{%
358 \texorpdfstring
359 {\texttt{\char`\\ jobname.glstex}}%
360 {\string\\jobname.glstex}%
361 }
362
363 \newcommand*{\suppresourcefmt}[1]{%
364 \texorpdfstring
365 {\texttt{\char`\\ jobname-#1.glstex}}%
366 {\string\\jobname-#1.glstex}%
367 }
368
369 \definecolor{field}{named}{DarkSlateGray4}
370 \definecolor{cs}{named}{DarkSeaGreen4}
371 \definecolor{styopt}{named}{DarkOrchid4}
372 \definecolor{entry}{named}{SteelBlue4}
373 \definecolor{comment}{named}{gray}
374 \definecolor{attribute}{named}{Purple4}
375 \definecolor{style}{named}{Blue4}
376
377 \newcommand{\extstyopt}{\textsuperscript{\textdagger}}
378
379 \newcommand*{\appfmt}[1]{\texorpdfstring{\texttt{#1}}{#1}}
380 \newcommand*{\styfmt}[1]{\texorpdfstring{\textsf{#1}}{#1}}
381 \newcommand*{\envfmt}[1]{\texorpdfstring{\textsf{#1}}{#1}}
382 \newcommand*{\optfmt}[1]{\texorpdfstring{\texttt{#1}}{#1}}
383 \newcommand*{\csoptfmt}[1]{\texorpdfstring{\textcolor{cs}{\optfmt{#1}}}{#1}}
384 \newcommand*{\styoptfmt}[1]{\texorpdfstring{\textcolor{styopt}{\optfmt{#1}}}{#1}}
385 \newcommand*{\fieldfmt}[1]{\texorpdfstring{\texttt{\color{field}#1}}{#1}}
386 \newcommand*{\entryfmt}[1]{\texorpdfstring{\texttt{\color{entry}#1}}{#1}}
387 \newcommand*{\atentryfmt}[1]{\entryfmt{@#1}}
388 \newcommand*{\abbrstylefmt}[1]{\texorpdfstring{\textsf{#1}}{#1}}
389 \newcommand*{\glostylefmt}[1]{\texorpdfstring{\textsf{#1}}{#1}}
390 \newcommand*{\catattrfmt}[1]{\texorpdfstring{\textsf{#1}}{#1}}
391 \newcommand*{\counterfmt}[1]{\texorpdfstring{\textsf{#1}}{#1}}
392 \newcommand*{\idprefixfmt}[1]{%
393 \texorpdfstring{\texttt{#1\spacefactor999 .}}{#1.}}
394 \newcommand*{\xmltagfmt}[1]{\texorpdfstring{\texttt{#1}}{#1}}
395
396 \newcommand*{\argor}{\texorpdfstring{\protect\textbar}{|}}
397
398 \newrobustcmd*{\texmeta}[1]{{\normalfont\normalcolor$\langle$\emph{#1}$\rangle$}}
399
400 \newcommand*{\meta}[1]{%
401 \texorpdfstring{\ifmmode\text{\texmeta{#1}}\else\texmeta{#1}\fi}{#1}%
402 }
403
404 \newcommand*{\oarg}[1]{\discretionary{}{}{}[#1]}
405 \newcommand*{\oargm}[1]{\oarg{\meta{#1}}}
406
407 \newcommand*{\marg}[1]{\texorpdfstring
408 {\discretionary{}{}{}\char`\{#1\char`\} }%
409 {\{#1\}}%
410 }
411
412 \newcommand*{\margm}[1]{\marg{\meta{#1}}}
413
414 \newcommand*{\file}[1]{%
415 \texorpdfstring
416 {\idx{file.#1}}%
417 {#1}%
418 }
419
420 \newcommand{\texmfcnffmt}[1]{\texttt{#1}}
421
422 \glsxtrnewgls{idx.texmfcnf.}{\texmfcnf}
423
424 \newcommand*{\extfmt}[1]{\filefmt{.#1}}%
425
426 \glsxtrnewgls[format=glsignore]{idx.ext.}{\ext}
427
428 \newcommand*{\iext}[1]{%
429 \glsxtrtitleorpdforheading{\idx{ext.#1}}{.#1}{\extfmt{#1}}%
430 }
431
432 \glsxtrnewgls[format=glsignore]{idx.}{\sty}
433
434 \newcommand*{\isty}[1]{%
435 \texorpdfstring{\idx[noindex=false]{#1}}{#1}%
436 }
437
438 \newcommand*{\env}[1]{%
439 \texorpdfstring{\idx{env.#1}}{#1}%
440 }
441
442 \newcommand{\glsxtrpostdescenvironment}{environment}
443
444 \newcommand*{\abbrstyle}[1]{%
445 \texorpdfstring{\idx{abbrstyle.#1}}{#1}%
446 }
447
448 \newcommand*{\topicabbrstyle}[1]{%
449 %\texorpdfstring{\idx[prefix=topic.]{abbrstyle.#1}}{#1}%
450 \texorpdfstring{\idx{abbrstyle.#1}}{#1}%
451 }
452
453 \newcommand*{\glostyle}[1]{%
454 \texorpdfstring{\idx{glostyle.#1}}{#1}%
455 }
456
457 \newcommand*{\topicglostyle}[1]{%
458 %\texorpdfstring{\idx[prefix=topic.]{glostyle.#1}}{#1}%
459 \texorpdfstring{\idx{glostyle.#1}}{#1}%
460 }
461
462 \newcommand*{\iglostyle}[1]{%
463 \texorpdfstring{\idx[noindex=false]{glostyle.#1}}{#1}%
464 }
465
466 \newcommand*{\catattr}[1]{%
467 \texorpdfstring{\idx{catattr.#1}}{#1}%
468 }
469
470 \newcommand*{\counter}[1]{%
471 \texorpdfstring{\idx{ctr.#1}}{#1}%
472 }
473
474 \newcommand{\glsxtrpostdesccounter}{counter}
475
476 \newcommand*{\idprefix}[1]{%
477 \texorpdfstring{\idx{idprefix.#1}}{#1}%
478 }
479
480
481 \newcommand*{\styopt}[2][]{%
482 \texorpdfstring%
483 {%
484 \gls{styopt.#2}\styoptfmt{\ifblank{#1}{}{\dequals\marg{#1}}}%
485 }%
486 {#2\ifblank{#1}{}{=#1}}%
487 }
488
489 \newcommand*{\istyopt}[2][]{%
490 \texorpdfstring%
491 {%
492 \gls[noindex=false]{styopt.#2}\styoptfmt{\ifblank{#1}{}{\dequals\marg{#1}}}%
493 }%
494 {#2\ifblank{#1}{}{=#1}}%
495 }
496
497 \newcommand*{\styoptref}[1]{\gls[format=glsignore]{styopt.#1}}
498
499 \newcommand*{\keyval}{%
500 \texorpdfstring
501 {\meta{key}\dequals \meta{value}}%
502 {key=value}%
503 }
504
505 \newcommand*{\keyvallist}{%
506 \texorpdfstring
507 {key\dequals value list}%
508 {key=value list}%
509 }
510
511 \newcommand{\cssectioncmd}{\subsection}
512
513 \newcommand{\cssection}[2][\cssectioncmd]{%
514 #1{\texorpdfstring{\glsxtrglossentry{#2}}{\string\\#2}}%
515 }
516
517 \newcommand{\nameparen}[1]{ (#1)}
518 \newcommand{\prefixedcssection}[3][\cssectioncmd]{%
519 {%
520 \renewcommand{\nameparen}[1]{}%
521 #1{\texorpdfstring{\glsxtrglossentry{#2.#3}}{\string\\#3}}%
522 }%
523 }
524
525 \newcommand{\format}[1]{%
526 \gls{#1}\glsentryuseri{#1}%
527 }
528
529 \newcommand{\formatdef}[1]{%
530 \begin{definition}%
531 \gls[hyper=false]{#1}\glsentryuseri{#1}%
532 \end{definition}\ignorespaces
533 }
534
535 \newcommand{\nosecformatdef}[1]{%
536 \begin{definition}
537 \renewcommand{\GlsXtrStandaloneEntryName}[1]{\glstarget{##1}{\strut}\cs{##1}}%
538 \glsadd{#1}\glsxtrglossentry{#1}%
539 \glsentryuseri{#1}%
540 \end{definition}\ignorespaces
541 }
542
543 \newcommand{\nosecdef}[1]{%
544 \begin{flushleft}\ttfamily
545 \renewcommand{\GlsXtrStandaloneEntryName}[1]{\glstarget{##1}{\strut}\cs{##1}}%
546 \glsadd{#1}\glsxtrglossentry{#1}%
547 \glsentryuseri{#1}%
548 \end{flushleft}\ignorespaces
549 }
550
551 \newcommand{\inlinedef}[1]{%
552 \code
553 {%
554 \glsadd{#1}\glsxtrglossentry{#1}%
555 \glsentryuseri{#1}%
556 }%
557 }
558
559 \newcommand*{\csref}{\gls}
560
561 \newcommand*{\cs}[1]{%
562 \glsdoifexists{idx.#1}%
563 {\glsdohyperlink{\glolinkprefix cs.idx.#1}{\glsentryname{idx.#1}}}%
564 }
565
566 \glsxtridentifyglslike{idx.}{\cs}
567
568 \newcommand*{\ics}[2][]{\glsadd[#1]{idx.#2}\cs{#2}}
569
570 \newcommand*{\csdisp}[2]{%
571 \texorpdfstring
572 {\glsdohyperlink{\glolinkprefix cs.idx.#1}{\csfmt{#2}}}%
573 {\string\\#2}%
574 }
575
576 \newcommand*{\icsdisp}[3][]{%
577 \glsadd[#1]{idx.#2}\glsdohyperlink{\glolinkprefix cs.idx.#2}{\csfmt{#3}}%
578 }
579
580 \newcommand*{\encapdisp}[2]{%
581 \texorpdfstring
582 {\glsdohyperlink{\glolinkprefix cs.idx.#1}{\code{#2}}}%
583 {#2}%
584 }
585
586 \glsxtridentifyglslike{idx.}{\ics}
587
588 \newcommand*{\icswithargs}[2][]{\glsadd[#1]{idx.#2}\cs{#2}\glsentryuseri{#2}}
589
590 \newcommand*{\postdeschook}[1]{%
591 \glsdohyperlink{\glolinkprefix cs.idx.glsxtrpostdesccategory}{\csfmt{glsxtrpostdesc#1}}}
592 \newcommand*{\postnamehook}[1]{%
593 \glsdohyperlink{\glolinkprefix cs.idx.glsxtrpostnamecategory}{\csfmt{glsxtrpostname#1}}}
594 \newcommand*{\postlinkhook}[1]{%
595 \glsdohyperlink{\glolinkprefix cs.idx.glsxtrpostlinkcategory}{\csfmt{glsxtrpostlink#1}}}
596
597 \newcommand*{\encap}[2][]{\glsadd[#1]{idx.#2}%
598 {%
599 \let\csfmt\code
600 \glsdohyperlink{\glolinkprefix cs.idx.#2}{\glsentryname{idx.#2}}%
601 }%
602 }
603
604 \newcommand{\optsection}[2][\subsection]{%
605 \glsxtrifhasfield*{useri}{opt.#2}%
606 {%
607 #1[\texorpdfstring
608 {\glsxtrheadname{opt.#2}\csoptfmt{=\glscurrentfieldvalue}}%
609 {\glsentryname{opt.#2}=\glscurrentfieldvalue}]
610 {\glsadd{opt.#2}\glsxtrglossentry{opt.#2}%
611 \csoptfmt{=\glscurrentfieldvalue}%
612 }%
613 }%
614 {%
615 #1[\texorpdfstring{\glsxtrheadname{opt.#2}}{\glsentryname{opt.#2}}]
616 {\glsadd{opt.#2}\glsxtrglossentry{opt.#2}}%
617 }%
618 }
619
620 \glsxtrnewgls{file.}{\exfile}
621
622 \newcommand{\filesection}[2][\section]{%
623 #1[\texorpdfstring{\glsxtrheadname{file.#2}}{\glsentryname{file.#2}}]
624 {\glsadd{file.#2}\glsxtrglossentry{file.#2}}%
625 }
626
627 \newcommand*{\csopt}[2][]{\gencsopt{#1}{opt}{#2}}%
628 \newcommand*{\glsopt}[2][]{\gencsopt{#1}{idx.gls}{#2}}%
629 \newcommand*{\glsaddopt}[2][]{\gencsopt{#1}{idx.glsadd}{#2}}%
630 \newcommand*{\printglossopt}[2][]{\gencsopt{#1}{idx.printgloss}{#2}}%
631 \newcommand*{\iprintglossopt}[2][]{\glsadd{idx.printgloss.#2}\gencsopt{#1}{idx.printgloss}{#2}}%
632
633 \newcommand*{\gencsopt}[3]{%
634 \texorpdfstring%
635 {%
636 \gls{#2.#3}%
637 \csoptfmt{\ifblank{#1}{}{\dequals\marg{#1}}}%
638 }%
639 {#3\ifblank{#1}{}{=#1}}%
640 }
641
642 \newcommand*{\field}[1]{%
643 \texorpdfstring
644 {\gls{field.#1}}%
645 {#1}%
646 }
647
648 \newcommand*{\fielddisp}[2]{%
649 \texorpdfstring
650 {\glsdisp{field.#1}{\fieldfmt{#2}}}%
651 {#2}%
652 }
653
654 \newcommand*{\fielddef}[1]{%
655 \glsadd{field.#1}%
656 \glsxtrglossentry{field.#1}{}%
657 }
658
659 \newcommand*{\fieldref}[1]{\gls[format=glsignore]{field.#1}}
660
661 \newglossarystyle{fieldstyle}{%
662 \renewenvironment{theglossary}%
663 {%
664 \setlength{\glsdescwidth}{\dimexpr\linewidth-\maxnamewidth-4\tabcolsep}%
665 \begin{longtable}{l>{\raggedright}p{\glsdescwidth}}%
666 }%
667 {\end{longtable}}%
668 \renewcommand*{\glossaryheader}{%
669 \noalign{\xdef\dofieldtabcaption{%
670 \noexpand\caption\expandonce\fieldtablelotcaption
671 {\expandonce\fieldtablecaption}}}%
672 \dofieldtabcaption
673 \fieldtablecaptionlabel
674 \fieldtablepostcaption\tabularnewline
675 \bfseries Field & \bfseries Description\tabularnewline
676 \endfirsthead
677 \caption*{\fieldtablecaption\ (Continued)}\tabularnewline
678 \bfseries Field & \bfseries Description\tabularnewline
679 \endhead
680 }%
681 \renewcommand*{\glsgroupheading}[1]{}%
682 \renewcommand{\glossentry}[2]{%
683 \glsadd{##1}%
684 \glsentryitem{##1}\glstarget{##1}{\glossentryname{##1}} &
685 \glossentrydesc{##1}\tabularnewline
686 }%
687 \renewcommand{\subglossentry}[3]{\glossentry{##2}{##3}}%
688 \renewcommand*{\glsgroupskip}{}%
689 }
690
691 \newcommand*{\fieldhook}[1]{%
692 \edef\currentcategory{\glscategory{#1}}%
693 \glsxtriflabelinlist{\currentcategory}{\fieldcategories}%
694 {%
695 \settowidth{\dimen0}{\glsentryname{#1}}%
696 \ifdim\dimen0>\maxnamewidth \setlength{\maxnamewidth}{\dimen0}\fi
697 }%
698 {\printunsrtglossaryskipentry}%
699 }
700
701 \newlength\maxnamewidth
702
703 %\printfields[postcaption]{category list}[lot caption]{caption}{label}
704 \newcommand*{\printfields}[2][]{%
705 \ifstrempty{#1}%
706 {%
707 \def\fieldtablepostcaption{}%
708 }%
709 {%
710 \def\fieldtablepostcaption{%
711 \tabularnewline
712 \multicolumn{2}{p{\linewidth}}{#1}%
713 \tabularnewline
714 }%
715 }%
716 \def\fieldcategories{#2}%
717 \innerprintfields
718 }
719
720 \newcommand*{\innerprintfields}[3][]{%
721 \printunsrtglossary*[style=fieldstyle]{%
722 \renewcommand*\glossarysection[2][]{}%
723 \ifstrempty{#1}%
724 {%
725 \def\fieldtablelotcaption{}%
726 }%
727 {%
728 \def\fieldtablelotcaption{[#1]}%
729 }%
730 \def\fieldtablecaption{#2}%
731 \def\fieldtablecaptionlabel{\label{#3}}%
732 \setlength{\maxnamewidth}{0pt}%
733 \let\printunsrtglossaryentryprocesshook\fieldhook
734 }%
735 }
736
737 \renewcommand*{\glsxtrbookindexname}[1]{%
738 \glsxtrifhasfield{dualid}{#1}%
739 {%
740 \glshyperlink[\glossentryname{#1}]{\glscurrentfieldvalue}%
741 }
742 {%
743 \GlsXtrIfFieldEqStr{category}{#1}{command}%
744 {\glsdohyperlink{\glolinkprefix cs.#1}{\glossentryname{#1}}}%
745 {\glossentryname{#1}}%
746 }%
747 }
748
749 \newcommand{\summarysubheaderfont}[1]{\textbf{\sffamily #1}}
750
751 \newcommand{\summaryoptionhandler}[1]{%
752 \par\smallskip\nopagebreak
753 \par\noindent\hspace{1em}%
754 \code{\gls{#1}\glsxtrifhasfield{useri}{#1}{=\glscurrentfieldvalue}{}}%
755 \glsxtrifhasfield{note}{#1}%
756 {\nolinebreak\hfill\mbox{\footnotesize\glscurrentfieldvalue}}%
757 {}%
758 \nopagebreak\par\hangindent2em\noindent\hspace{2em}\Glossentrydesc{#1}%
759 }
760
761 \newrobustcmd{\donote}[1]{%
762 \glsxtrifhasfield{note}{#1}%
763 {\nolinebreak\hfill\mbox{\normalfont\footnotesize\glscurrentfieldvalue}}%
764 {}%
765 }
766
767 \newglossarystyle{commandsummary}%
768 {%
769 \setglossarystyle{index}%
770 \renewcommand*{\glossaryheader}{\raggedright}%
771 \renewcommand*{\glsgroupheading}[1]{%
772 \glsxtrgetgrouptitle{##1}{\thisgrptitle}%
773 \glsxtrbookindexbookmark{\thisgrptitle}{summary.##1}%
774 \glsxtrbookindexformatheader{\thisgrptitle}%
775 \nopagebreak\indexspace\nopagebreak\csuse{@afterheading}%
776 }%
777 \renewcommand*{\glossentry}[2]{%
778 \glstreeitem \glstarget{cs.##1}{\strut}%
779 \glsxtrifhasfield{dualid}{##1}%
780 {%
781 {%
782 \let\csfmtfont\csfmtcolourfont
783 \glshyperlink{\glscurrentfieldvalue}%
784 }%
785 \glsxtrifhasfield{useri}{##1}{\glscurrentfieldvalue}{}%
786 \donote{##1}%
787 \nopagebreak\par\hspace{10pt}%
788 \Glossentrydesc{\glscurrentfieldvalue}%
789 \ifglshasdesc{\glscurrentfieldvalue}{\@. }{}%
790 }%
791 {%
792 {\let\csfmtfont\csfmtcolourfont\gls[hyper=false]{##1}}%
793 \glsxtrifhasfield{useri}{##1}{\glscurrentfieldvalue}{}%
794 \donote{##1}%
795 \nopagebreak\par\hspace{10pt}%
796 \Glossentrydesc{##1}%
797 \ifglshasdesc{##1}{\@. }{}%
798 }%
799 \GlsXtrIfFieldEqStr{originalentrytype}{##1}{glscommand}%
800 {%
801 % Does this entry have options?
802 \GlsXtrIfHasNonZeroChildCount{##1}%
803 {%
804 \glspar\medskip\glspar
805 \summarysubheaderfont{Options:}
806 \glsxtrfieldforlistloop{##1}{childlist}{\summaryoptionhandler}%
807 }%
808 {}%
809 }%
810 {%
811 \GlsXtrIfHasNonZeroChildCount{##1}%
812 {This command has \glscurrentfieldvalue\ forms:}{}%
813 }%
814 %\listtopics{##1}%
815 \par\medskip
816 }%
817 \renewcommand*{\subglossentry}[3]{%
818 \glstreesubitem \glstarget{cs.##2}{\strut}%
819 \glsxtrifhasfield{dualid}{##2}%
820 {%
821 {%
822 \let\csfmtfont\csfmtcolourfont
823 \glshyperlink{\glscurrentfieldvalue}%
824 }%
825 \glsxtrifhasfield{useri}{##2}{\glscurrentfieldvalue}{}%
826 \donote{##2}%
827 \nopagebreak\par\hspace{20pt}%
828 \ifglshasdesc{\glscurrentfieldvalue}%
829 {\Glossentrydesc{\glscurrentfieldvalue}.}{}%
830 }%
831 {%
832 {\let\csfmtfont\csfmtcolourfont\gls[hyper=false]{##2}}%
833 \glsxtrifhasfield{useri}{##2}{\glscurrentfieldvalue}{}%
834 \donote{##2}%
835 \nopagebreak\par\hspace{20pt}%
836 \ifglshasdesc{##2}{\Glossentrydesc{##2}.}{}%
837 }%
838 \par\medskip
839 }%
840 }
841
842 \newcommand*{\commandsummaryhook}[1]{%
843 \edef\currentcategory{\glscategory{#1}}%
844 \ifdefstring{\currentcategory}{command}%
845 {%
846 \glsxtrifhasfield*{progenitor}{#1}%
847 {\printunsrtglossaryskipentry}{}%
848 }%
849 {\printunsrtglossaryskipentry}%
850 }
851
852 \newcommand*{\printcommandsummary}{%
853 \printunsrtglossary*[type=index,
854 style=commandsummary,
855 title={General Command Summary},
856 ]%
857 {%
858 \def\glossarypreamble{This is an alphabetical summary of
859 commands referenced in this document. See the
860 relevent user guides for further details.\endgraf\medskip
861 \texparserdefnotetarget}%
862 \let\printunsrtglossaryentryprocesshook\commandsummaryhook
863 \let\csref\cs
864 \glsxtrlocalsetgrouptitle{glssymbols}{}%
865 }%
866 }
867
868 \newcommand{\topicxrhandler}[1]{%
869 \glsxtrifhasfield{parent}{#1}%
870 {%
871 \let\field\fieldfmt
872 \hyperlink
873 {topic.\glscurrentfieldvalue}%
874 {\glsentryname{\glscurrentfieldvalue}}%
875 }%
876 {%
877 \hyperlink{topic.#1}{\glsentryname{#1}}%
878 }%
879 }
880
881 % \iffirstprogeny{entry label}{topic label}{true}{false}
882 \makeatletter
883 \newcommand{\iffirstprogeny}[2]{%
884 \let\doiffirstprogeny\@secondoftwo
885 \def\firstprogeny{}%
886 \glsxtrifhasfield*{unsortedprogeny}{#1}%
887 {%
888 \edef\suppliedprogeny{#2}%
889 \@for\thisprogeny:=\glscurrentfieldvalue\do{%
890 \let\firstprogeny\thisprogeny
891 \ifdefequal{\thisprogeny}{\suppliedprogeny}%
892 {\let\doiffirstprogeny\@firstoftwo}%
893 {\let\doiffirstprogeny\@secondoftwo}%
894 \@endfortrue
895 }%
896 }%
897 {}%
898 \doiffirstprogeny
899 }
900 \makeatother
901
902 \newcommand{\ifstylecommand}[1]{%
903 \letcs\doifstylecommand{@firstoftwo}%
904 \GlsXtrIfFieldEqStr{originalentrytype}{#1}{abbrvstylecommand}%
905 {}%
906 {%
907 \GlsXtrIfFieldEqStr{originalentrytype}{#1}{glostylecommand}%
908 {}%
909 {\global\letcs\doifstylecommand{@secondoftwo}}%
910 }%
911 \doifstylecommand
912 }
913
914 \newcommand{\listtopics}[1]{%
915 \glsxtrifhasfield{progeny}{#1}%
916 {%
917 \ifdefequal\glscurrentfieldvalue\glscurrententrylabel
918 {}%
919 {%
920 \par\nopagebreak\medskip\par\footnotesize
921 \sloppy
922 \ifstylecommand{#1}%
923 {\summarysubheaderfont{Styles:}}%
924 {\summarysubheaderfont{Topics:}}%
925 \space
926 \let\DTLlistformatitem\topicxrhandler
927 \DTLformatlist{\glscurrentfieldvalue}.\par
928 }%
929 }%
930 {}%
931 }
932
933 \newglossarystyle{commandtopic}%
934 {%
935 \setglossarystyle{index}%
936 %\renewcommand*{\glossaryheader}{\raggedright}%
937 \renewcommand*{\glsgroupheading}[1]{}%
938 \renewcommand*{\glossentry}[2]{%
939 \glsfieldfetch{##1}{nametitle}{\thisvalue}%
940 \section*{%
941 \raisebox{2ex}%
942 {\pdfbookmark[1]{\thisvalue}{topic.##1}\hypertarget{topic.##1}{}}%
943 \glsdisp{##1}{\thisvalue}\donote{##1}%
944 }%
945 \expandafter\sectionmark\expandafter{\thisvalue}%
946 \ifglshasdesc{##1}{\Glossentrydesc{##1}.}{}%
947 \glsxtrifhasfield{seealso}{##1}%
948 {%
949 \par\smallskip
950 \emph{See also:}
951 \let\DTLlistformatitem\topicxrhandler
952 \DTLformatlist{\glscurrentfieldvalue}.%
953 \par\medskip\par
954 }%
955 {}%
956 }%
957 \renewcommand*{\subglossentry}[3]{%
958 \glsifcategory{##2}{command}%
959 {%
960 \glsdohypertarget{topic.##2}{\strut}%
961 \glsxtrifhasfield*{progenitor}{##2}%
962 {\let\originallabel\glscurrentfieldvalue}%
963 {\def\originallabel{##2}}%
964 %
965 \ifstylecommand{##2}%
966 {%
967 \iffirstprogeny{\originallabel}{##2}%
968 {\letcs\dothisentry{@firstofone}}%
969 {%
970 \glspar
971 \ifdefempty\firstprogeny
972 {%
973 {\let\csfmtfont\csfmtcolourfont\gls[noindex]{\originallabel}}%
974 \glsxtrifhasfield{useri}{##2}{\glscurrentfieldvalue}{}%
975 }%
976 {%
977 {\let\csfmtfont\csfmtcolourfont
978 \hyperlink{topic.\firstprogeny}{\glsentryname{\firstprogeny}}}%
979 \glsxtrifhasfield{useri}{##2}{\glscurrentfieldvalue}{}%
980 \glsxtrifhasfield{parent}{\firstprogeny}%
981 {\hfill
982 {\footnotesize\emph{see} \hyperlink{topic.\glscurrentfieldvalue}%
983 {\glsentryname{\glscurrentfieldvalue}}.}}
984 {}%
985 }%
986 \letcs\dothisentry{@gobble}%
987 }%
988 }%
989 {\letcs\dothisentry{@firstofone}}%
990 \dothisentry
991 {%
992 \par\smallskip\par
993 % hyperlink to index:
994 {\let\csfmtfont\csfmtcolourfont\gls[format=glsignore]{\originallabel}}%
995 \glsxtrifhasfield{useri}{##2}{\glscurrentfieldvalue}{}%
996 \glsxtrifhasfield{note}{##2}%
997 {\nolinebreak\hfill\mbox{\footnotesize\glscurrentfieldvalue}}%
998 {}%
999 \nopagebreak\par\smallskip\par\nopagebreak
1000 \ifglshasdesc{##2}{\Glossentrydesc{##2}.}{}%
1001 % Topics
1002 \listtopics\originallabel
1003 \par\smallskip
1004 }%
1005 }%
1006 {%
1007 \glsfieldfetch{##2}{nametitle}{\thisvalue}%
1008 \subsection*{%
1009 \raisebox{2ex}%
1010 {\hypertarget{topic.##2}{}\pdfbookmark[2]{\thisvalue}{topic.##2}}%
1011 \glsdisp{##2}{\thisvalue}\donote{##2}%
1012 }%
1013 \expandafter\subsectionmark\expandafter{\thisvalue}%
1014 \ifglshasdesc{##2}{\Glossentrydesc{##2}.\glspar\nopagebreak\smallskip}{}%
1015 }%
1016 }%
1017 }
1018
1019 \newcommand*{\commandtopichook}[1]{%
1020 \glsxtrifhasfield*{progenitor}{#1}%
1021 {}%
1022 {%
1023 \GlsXtrIfFieldEqStr*{originalentrytype}{#1}{topic}%
1024 {}%
1025 {%
1026 \glsxtrifhasfield*{parent}{#1}%
1027 {%
1028 \GlsXtrIfFieldEqStr*{originalentrytype}{\glscurrentfieldvalue}{topic}%
1029 {}%
1030 {\printunsrtglossaryskipentry}%
1031 }%
1032 {\printunsrtglossaryskipentry}%
1033 }%
1034 }%
1035 }
1036
1037 \newcommand*{\printcommandtopic}{%
1038 \setsecdepth*{0}%
1039 \automark[subsection]{section}%
1040 \printunsrtglossary*[type=index,
1041 style=commandtopic,
1042 title={Summary by Topic of Glossary Commands},
1043 label={sec:topics},
1044 nogroupskip,
1045 nonumberlist
1046 ]%
1047 {%
1048 \def\texparserdefprefix{topic.}%
1049 \def\glossarypreamble{This is a summary of commands provided
1050 by \styfmt{glossaries}, \styfmt{glossaries-extra} and
1051 their supplementary packages that may be useful to
1052 \bibgls\ users. Commands specific to other indexing methods
1053 aren't listed unless they've been referenced in this manual.
1054 See the appropriate user guides for further details.
1055 \endgraf\medskip
1056 \texparserdefnotetarget}%
1057 \let\abbrstyle\topicabbrstyle
1058 \let\glostyle\topicglostyle
1059 \let\printunsrtglossaryentryprocesshook\commandtopichook
1060 \let\csref\cs
1061 }%
1062 \setsecdepth{0}%
1063 }
1064
1065 \newglossarystyle{styoptsummary}%
1066 {%
1067 \setglossarystyle{mcolindex}%
1068 \renewcommand{\glossarypreamble}{%
1069 Most options are in the form \meta{option}=\meta{value} and
1070 may have a default if \meta{value} is omitted,
1071 but some options don't have values and should not have
1072 one assigned. For boolean options,
1073 if the value is omitted \styoptfmt{true} is assumed.
1074 \extstyopt Indicates a value that's only provided by
1075 \styfmt{glossaries-extra} and not by the base
1076 \styfmt{glossaries} package. \par
1077 }%
1078 \renewcommand*{\glossaryheader}{}%
1079 \renewcommand*{\glsgroupheading}[1]{%
1080 \glsxtrgetgrouptitle{##1}{\thisgrptitle}%
1081 \glsxtrbookindexbookmark{\thisgrptitle}{styopt.##1}%
1082 \glsxtrbookindexformatheader{\thisgrptitle}%
1083 \nopagebreak\indexspace\nopagebreak\csuse{@afterheading}%
1084 }%
1085 \renewcommand*{\glossentry}[2]{%
1086 \item \glstarget{##1}{\strut}%
1087 \glsxtrifhasfield{dualid}{##1}%
1088 {%
1089 \gls{\glscurrentfieldvalue}%
1090 }%
1091 {%
1092 \gls[hyper=false]{##1}%
1093 }%
1094 \glsxtrifhasfield{useri}{##1}{=\glscurrentfieldvalue}{}%
1095 \nopagebreak\par\hspace{10pt}%
1096 \Glossentrydesc{##1}.%
1097 \glsxtrifhasfield{package}{##1}%
1098 {\nopagebreak\par \ding{43}Provided by
1099 \ifdefstring{\glscurrentfieldvalue}{glossaries,glossaries-extra}
1100 {\styfmt{glossaries} and modified by \styfmt{glossaries-extra}}%
1101 {\styfmt{\glscurrentfieldvalue}}.}%
1102 {}%
1103 \glsxtrifhasfield{note}{##1}%
1104 {\space \xmakefirstuc{\glscurrentfieldvalue}.}%
1105 {}%
1106 \par\medskip
1107 }%
1108 }
1109
1110 \newcommand*{\styoptsummaryhook}[1]{%
1111 \edef\currentcategory{\glscategory{#1}}%
1112 \ifdefstring{\currentcategory}{packageoption}%
1113 {}%
1114 {\printunsrtglossaryskipentry}%
1115 }
1116
1117 \newcommand*{\printstyoptsummary}{%
1118 \printunsrtglossary*[type=main,
1119 style=styoptsummary,
1120 title={Package Option Summary}
1121 ]%
1122 {%
1123 \let\printunsrtglossaryentryprocesshook\styoptsummaryhook
1124 \glsxtrlocalsetgrouptitle{glssymbols}{@}%
1125 }%
1126 }
1127
1128 \newcommand{\entrysection}[2][\subsection]{%
1129 #1[\texorpdfstring{\glsxtrheadname{entry.#2}}{\glsentryname{entry.#2}}]
1130 {\glsadd{entry.#2}\glsxtrglossentry{entry.#2}}%
1131 }
1132
1133 \newcommand{\entrydef}[1]{\glsadd{entry.#1}\glsxtrglossentry{entry.#1}}
1134
1135 \newcommand*{\atentry}[2][]{%
1136 \texorpdfstring
1137 {\gls[#1]{entry.#2}}%
1138 {#2}%
1139 }
1140
1141 \newcommand*{\atentrypageref}[1]{%
1142 \atentry{#1} (page~\glsxtrpageref{entry.#1})}%
1143
1144 \newcommand*{\atentryref}[1]{\gls[format=glsignore]{entry.#1}}
1145
1146 \newcommand*{\entryref}[1]{\glslink[format=glsignore]{entry.#1}{\entryfmt{#1}}}
1147
1148 \newcommand{\commonarg}[2][\subsection]{\argsection[#1]{common.#2}}
1149
1150 \newcommand{\converterarg}[2][\subsection]{\argsection[#1]{converter.#2}}
1151
1152 \newcommand{\convertglsbibarg}[2][\subsubsection]{\argsection[#1]{gls2bib.#2}}
1153
1154 \newcommand{\datatoolbibarg}[2][\subsubsection]{\argsection[#1]{datatool2bib.#2}}
1155
1156 \newcommand{\argsection}[2][\subsection]{%
1157 \def\switcharg{}%
1158 \def\switchalt{}%
1159 \def\switchaltpdf{}%
1160 \glsxtrifhasfield*{useri}{switch.#2}%
1161 {%
1162 \edef\switcharg{ \expandonce\glscurrentfieldvalue}%
1163 }%
1164 {}%
1165 \ifglshassymbol{switch.#2}%
1166 {%
1167 \def\switchalt{ (or \protect\glsentrysymbol{switch.#2}\switcharg)}%
1168 }%
1169 {}%
1170 #1[\texorpdfstring
1171 {\glsxtrheadname{switch.#2}}%
1172 {\glsentryname{switch.#2}}%
1173 \switcharg\switchalt
1174 ]
1175 {\glsadd{switch.#2}%
1176 \glsxtrglossentry{switch.#2}\switcharg\switchalt}%
1177 }
1178
1179 \newrobustcmd{\longswitch}{\string-{}\string-}
1180
1181 \newcommand*{\shortargfmt}[1]{%
1182 \texorpdfstring{\texttt{\string-#1}}%
1183 {\string-#1}%
1184 }
1185
1186 \newcommand*{\longarg}[1]{%
1187 \texorpdfstring
1188 {\gls{switch.#1}}%
1189 {\string-\string-#1}%
1190 }
1191
1192 \newcommand*{\commonlongarg}[1]{%
1193 \texorpdfstring
1194 {\gls{switch.common.#1}}%
1195 {\string-\string-#1}%
1196 }
1197
1198 \newcommand*{\converterlongarg}[1]{%
1199 \texorpdfstring
1200 {\gls{switch.converter.#1}}%
1201 {\string-\string-#1}%
1202 }
1203
1204 \newcommand*{\convertglsbiblongarg}[1]{%
1205 \texorpdfstring
1206 {\gls{switch.gls2bib.#1}}%
1207 {\string-\string-#1}%
1208 }
1209
1210 \newcommand*{\datatoolbiblongarg}[1]{%
1211 \texorpdfstring
1212 {\gls{switch.datatool2bib.#1}}%
1213 {\string-\string-#1}%
1214 }
1215
1216 \newcommand*{\longargpageref}[1]{%
1217 \longarg{#1} (page~\glsxtrpageref{switch.#1})}%
1218
1219 \newcommand*{\longargorshort}[1]{%
1220 \texorpdfstring
1221 {\gls{switch.#1}\ifglshassymbol{switch.#1}{ or \glssymbol{switch.#1}}{}}%
1222 {\string-\string-#1}%
1223 }
1224
1225 \newcommand*{\unicodecategoryfmt}[1]{\qt{\textsf{#1}}}
1226
1227 \definecolor{defbackground}{rgb}{1,1,0.75}
1228 \newsavebox\defsbox
1229 \newlength\defwidth
1230
1231 \newenvironment{definition}%
1232 {%
1233 \setlength{\fboxsep}{4pt}\setlength{\fboxrule}{1.25pt}%
1234 \begin{lrbox}{\defsbox}%
1235 \setlength\defwidth\linewidth
1236 \addtolength\defwidth{-2\fboxrule}%
1237 \addtolength\defwidth{-2\fboxsep}%
1238 \begin{minipage}{\defwidth}
1239 \flushleft\ttfamily\ignorespaces
1240 }%
1241 {%
1242 \end{minipage}%
1243 \end{lrbox}\par\medskip\noindent
1244 \fcolorbox{black}{defbackground}{\usebox\defsbox}%
1245 \medskip\par\noindent
1246 \ignorespacesafterend
1247 }
1248
1249 \newcommand{\introguide}{\href{bib2gls-begin.pdf}{\qt{\styfmt{glossaries-extra}
1250 and \bibgls: An Introductory Guide} (\filefmt{bib2gls-begin.pdf})}}
1251
1252 \setcounter{tocdepth}{4}
1253
1254 \newcommand*{\sectionref}[1]{\cref{#1}}
1255 \newcommand*{\Sectionref}[1]{\Cref{#1}}
1256 \newcommand*{\figureref}[1]{\hyperlink{#1-top}{figure~\ref*{#1}}}
1257 \newcommand*{\Figureref}[1]{\hyperlink{#1-top}{Figure~\ref*{#1}}}
1258 \newcommand*{\tableref}[1]{\cref{#1}}
1259 \newcommand*{\Tableref}[1]{\Cref{#1}}
1260
1261 \newcommand{\figcontents}[3]{%
1262 \hypertarget{#3-top}{}%
1263 \centering
1264 #1\par
1265 #2\label{#3}%
1266 }
1267
1268 \newlength\imagewidth
1269 \newcount\tmpctr
1270
1271 \newcommand*{\pdftwocol}[3][1]{%
1272 \renewcommand{\tabcolsep}{2pt}%
1273 \setlength{\imagewidth}{\dimexpr.5\linewidth-2\tabcolsep}%
1274 \def\tabcontents{\begin{tabular}{@{}cc@{}}}%
1275 \tmpctr\numexpr#1-1\relax
1276 \loop
1277 \advance\tmpctr by 1\relax
1278 \eappto\tabcontents{\noexpand\frame{%
1279 \noexpand\includegraphics[page=\the\tmpctr,width=\noexpand\imagewidth]{#2}}}%
1280 \ifodd\tmpctr
1281 \appto\tabcontents{&}%
1282 \else
1283 \appto\tabcontents{\\}%
1284 \fi
1285 \ifnum\tmpctr<#3
1286 \repeat
1287 \appto\tabcontents{\end{tabular}}%
1288 \tabcontents
1289 }
1290
1291 \makeatletter
1292 \newcommand*{\tablelistcs}[2]{%
1293 \tmpctr=0\relax
1294 \def\tabcontents{}%
1295 \loop
1296 \advance\tmpctr by 1\relax
1297 \appto\tabcontents{l}%
1298 \ifnum\tmpctr<#1
1299 \repeat
1300 %
1301 \edef\tabcontents{\noexpand\begin{tabular}{@{}\tabcontents @{}}}%
1302 \def\thislist{#2}%
1303 \dtlsortlist{\thislist}{\dtlicompare}%
1304 \tmpctr=1\relax
1305 \@for\thislabel:=\thislist\do{%
1306 \eappto\tabcontents{\noexpand\ics{\thislabel}}%
1307 \ifnum\tmpctr<#1\relax
1308 \appto\tabcontents{&}%
1309 \advance\tmpctr by 1\relax
1310 \else
1311 \appto\tabcontents{\\}%
1312 \tmpctr=1\relax
1313 \fi
1314 }%
1315 \appto\tabcontents{\end{tabular}}%
1316 \tabcontents
1317 }
1318 \makeatother
1319
1320 % This is a bit fiddly. Need to represent \vec{v} in typewriter
1321 % font for the interpreter examples. ($\mathtt{\vec{v}}$ doesn't
1322 % work)
1323 \newsavebox\varrow
1324 \sbox\varrow{$\mathtt{\accentset{\to}{v}}$}
1325
1326 \newcommand*{\mtx}[1]{\boldsymbol{#1}}
1327 \newcommand*{\set}[1]{\mathcal{#1}}
1328 \newcommand*{\card}[1]{|\set{#1}|}
1329 \newcommand*{\imaginary}{i}
1330
1331 \newcommand{\addr}[1]{\\\href{https://www.#1/}{\nolinkurl{#1}}}
1332 \title{\bibgls: a command line Java application to convert
1333 \filefmt{.bib} files to \filefmt{glossaries-extra.sty} resource
1334 files}
1335 \author{Nicola Talbot\addr{dickimaw-books.com}}
1336 \input{version}
1337
1338 \makeatletter
1339 \renewcommand{\fps@figure}{htbp}
1340
1341 \newcommand{\code}[1]{\texorpdfstring{{\ttfamily\obeyspaces #1}}{#1}}
1342
1343 \newcommand{\setupcodeenvfmts}{%
1344 \def\cmd{\char`\\}%
1345 \def\comment##1{\mbox{\textcolor{comment}{\idx{commentchar}\ ##1}}}%
1346 \renewcommand*{\styfmt}[1]{##1}%
1347 \renewcommand*{\counterfmt}[1]{##1}%
1348 \renewcommand*{\catattrfmt}[1]{\textcolor{attribute}{##1}}%
1349 \renewcommand*{\abbrstylefmt}[1]{\textcolor{style}{##1}}%
1350 \renewcommand*{\csfmtfont}[1]{\textcolor{cs}{##1}}%
1351 }
1352
1353 \newenvironment{codeenv}
1354 {%
1355 \GlsXtrStartUnsetBuffering
1356 \renewcommand{\glslinkpresetkeys}{\setkeys{glslink}{noindex}}%
1357 \setupcodeenvfmts
1358 \begin{flushleft}\ttfamily\obeylines\frenchspacing\@vobeyspaces
1359 \parindent\z@\parfillskip\@flushglue\parskip\z@skip
1360 }
1361 {\end{flushleft}\GlsXtrDiscardUnsetBuffering\ignorespacesafterend}
1362
1363 \newenvironment{codeenv*}
1364 {%
1365 \GlsXtrStartUnsetBuffering
1366 \setupcodeenvfmts
1367 \begin{flushleft}\ttfamily\obeylines\frenchspacing\@vobeyspaces
1368 \parindent\z@\parfillskip\@flushglue\parskip\z@skip
1369 }
1370 {\end{flushleft}\GlsXtrDiscardUnsetBuffering\ignorespacesafterend}
1371
1372 \begingroup
1373 \renewcommand{\addr}[1]{}
1374 \let\texorpdfstring\@secondoftwo
1375 \DTMsetstyle{pdf}
1376 \protected@edef\x{\endgroup
1377 \noexpand\hypersetup{%
1378 pdfinfo={
1379 Title={\@title},
1380 Author={\@author},
1381 CreationDate={\DTMuse{creation}},
1382 ModDate={\DTMuse{moddate}},
1383 }%
1384 }%
1385 }\x
1386
1387 \makeatother
1388
1389 \renewcommand{\titlepagestyle}{empty}
1390
1391 \begin{document}
1392 \maketitle
1393 \pagenumbering{alph}
1394 \pagestyle{empty}
1395
1396 \begin{abstract}
1397 The \bibgls\ command line application can be used to extract
1398 glossary information stored in a \ext{bib} file and convert it
1399 into glossary entry definitions that can be read using
1400 \styfmt{glossaries-extra}'s \gls{GlsXtrLoadResources} command. When used
1401 in combination with the \styoptfmt{record} package option, \bibgls\
1402 can select only those entries that have been used in the document,
1403 as well as any dependent entries, which reduces the \TeX\ resources
1404 required by not defining unnecessary commands.
1405
1406 Since \bibgls\ can also sort and collate the recorded \glspl{location}
1407 present in the \ext{aux} file, it can simultaneously by-pass the
1408 need to use \idx!{makeindex} or \idx!{xindy}, although \bibgls\
1409 can be used together with an external indexing application if required. (For
1410 example, if a custom \idx{xindy} rule is needed.)
1411
1412 An additional build may be required to ensure the \glspl{location} are
1413 up-to-date as the page-breaking may be slightly different on the
1414 first \LaTeX\ run due to the unknown references being replaced with
1415 ?? which can be significantly shorter than the actual text produced
1416 when the reference is known.
1417
1418 Note that \bibgls\ is a Java application, and requires at least
1419 Java~8. Additionally, \sty{glossaries-extra} must be at least
1420 version 1.12. These are minimum requirements, but the latest
1421 versions are recommended. This
1422 application was developed in response to the question
1423 \qt{\href{http://tex.stackexchange.com/q/342544}{Is there a program
1424 for managing glossary tags?}} on \TeX\ on
1425 StackExchange~\cite{tex.sx.2016}. The \ext{bib} file can be managed in an
1426 application such as JabRef.
1427
1428 If you already have a \ext{tex} file containing
1429 entry definitions using commands like \gls{newglossaryentry}
1430 then you can use the supplementary tool \idx{convertgls2bib}
1431 to convert the entries to the \ext{bib} format required by
1432 \bibgls. See \sectionref{sec:gls2bib} for further details.
1433
1434 The supplementary file \introguide\ is an
1435 introductory guide to the \isty{glossaries-extra} package, which you
1436 may prefer to start with if you are unfamiliar with the
1437 \sty{glossaries} and \sty{glossaries-extra} packages.
1438 \end{abstract}
1439
1440 Additional resources:
1441 \begin{itemize}
1442 \item
1443 \href{https://www.dickimaw-books.com/gallery/#bib2gls}{\bibgls\ gallery}.
1444 \item
1445 \href{https://www.dickimaw-books.com/faq.php?category=bib2gls}{\bibgls\ FAQ}
1446 \end{itemize}
1447 TUGboat articles:
1448 \begin{itemize}
1449 \item
1450 \href{http://tug.org/TUGboat/tb40-1/tb124talbot-bib2gls.pdf}{Glossaries
1451 with \bibgls}, issue 40:1, 2019.
1452 \item
1453 \href{http://tug.org/TUGboat/tb41-3/tb129talbot-bib2gls-more.pdf}{\bibgls:
1454 selection, cross-references and locations}, issue 41:3, 2020.
1455 \item \bibgls: sorting, issue \href{http://tug.org/TUGboat/Contents/contents42-2.html}{42:2, 2021}.
1456 \end{itemize}
1457
1458 \frontmatter
1459
1460 \tableofcontents
1461 \listoftables
1462 \listoffigures
1463 \printunsrtglossary*[type=terms,style=altlist,groups=false]
1464 {%
1465 \renewcommand{\glslistitem}[1]{%
1466 \item[\glsentryitem{#1}%
1467 \glstarget{#1}{\glossentryname{#1}}]%
1468 \glsxtrifhasfield{useri}{#1}%
1469 {\glsadd[format=glsnumberformat]{\glscurrentfieldvalue}}{}%
1470 }
1471 }
1472
1473 \mainmatter
1474 \chapter{Introduction}
1475
1476 If you have extensively used the \styfmt{glossaries}~\cite{glossaries} or
1477 \styfmt{glossaries-extra}~\cite{glossaries-extra} package,
1478 you may have found yourself creating a large \iext{tex} file
1479 containing many definitions that you frequently use in documents.
1480 This file can then simply be loaded using \ics{input} or
1481 \gls{loadglsentries}, but a large file like this can be difficult to
1482 maintain and if the document only actually uses a small proportion
1483 of those entries, the document build is unnecessarily slow due to
1484 the time and resources taken on defining the unwanted entries.
1485
1486 The aim of \bibgls\ is to allow the entries to be stored in a
1487 \iext{bib} file, which can be maintained using a reference system
1488 such as JabRef. The document build process
1489 can now be analogous to that used with \idx{bibtex} (or
1490 \appfmt{biber}), where only those entries that have been recorded in the
1491 document (and possibly their dependent entries) will be extracted
1492 from the \ext{bib} file. Since \bibgls\ can also perform
1493 \hierarchical\ sorting and can collate \glspl{locationlist}, it doubles as
1494 an indexing application, which means that the \idx{makeglossaries}
1495 step can be skipped.
1496 Note that \bibgls\ doesn't warn you if an entry that's referenced
1497 in the document doesn't exist in any of the supplied \ext{bib}
1498 files, but instead relies on the \styfmt{glossaries-extra} package
1499 to generate the warning. So at the end of the document build check
1500 the \ext{log} file for warnings.
1501
1502 You can't use \ics{glsaddall} with \bibgls\ as that command works
1503 by iterating over all defined entries and calling
1504 \code{\ics{glsadd}\margm{label}}. On the first \LaTeX\ run there are no
1505 entries defined, so \ics{glsaddall} does nothing. If you want to
1506 select all entries, just use \csopt[all]{selection} instead (which
1507 has the advantage over \ics{glsaddall} in that it doesn't create a
1508 redundant \gls{location} for each entry).
1509
1510 Note that \bibgls\ requires the extension package
1511 \isty{glossaries-extra} and can't be used with just the base
1512 \isty{glossaries} package, since it requires some of the extension
1513 commands. See the \styfmt{glossaries-extra} user
1514 manual~\cite{glossaries-extra} for information
1515 on the differences between the basic package and the extended
1516 package, as some of the default settings are different.
1517
1518 Since information required by \bibgls\ is
1519 written to the \iext{aux} file, it's not possible to run \bibgls\
1520 through \TeX's shell escape while the \ext{aux} file is open for
1521 write access. (The \ext{aux} file is closed \emph{after} the end
1522 document hook, so it can't be deferred with \ics{AtEndDocument}.)
1523 This means that if you really want to run \bibgls\
1524 through \ics{write18} it must be done in the preamble with
1525 \ics{immediate}. For example:
1526 \begin{verbatim}
1527 \immediate\write18{bib2gls \jobname}
1528 \end{verbatim}
1529 As from version 1.14 of \styfmt{glossaries-extra}, this can be done
1530 automatically with the \styopt{automake} option if the \ext{aux}
1531 file exists. (Remember that this will require the shell escape to be
1532 enabled.)
1533
1534 \section{Default Encoding}
1535 \label{sec:defencoding}
1536
1537 Both \XeLaTeX\ and \LuaLaTeX\ default to UTF-8 \igls{encoding}. With modern \TeX\
1538 distributions, \pdfLaTeX\ also defaults to UTF-8 but may be changed
1539 with the \sty{inputenc} package.
1540 The \sty{glossaries-extra} package writes the document encoding to
1541 the \ext{aux} file so that \bibgls\ can pick it up. However, if it
1542 doesn't match \bibgls\ expected encoding, it will have to close the
1543 file and reopen it.
1544
1545 The default encoding for Java applications, such as \bibgls, is the
1546 default encoding of the \idx{JVM}. This typically matches the
1547 operating system's default, but can be changed (see below). If you don't want
1548 to alter the \idx{JVM}['s] default, you can set the \bibgls\ default
1549 with \longarg{default-encoding}.
1550
1551 In general, UTF-8 works best with \bibgls, but you need to be careful if your
1552 \idx{JVM} isn't set up to use UTF-8 by default as you can end
1553 up with encoding mismatches. This can happen with some versions of
1554 Windows, so it's a good idea to double-check the \bibgls\ transcript
1555 file to make sure all the encoding information is correct.
1556
1557 The default encoding is written at the start of the \ext{glg} file.
1558 For example:
1559 \begin{verbatim}
1560 Default encoding: UTF-8
1561 \end{verbatim}
1562 When a file is opened, the associated encoding is written to the \ext{glg}
1563 file. For example, when the \ext{aux} file is opened:
1564 \begin{verbatim}
1565 Reading myDoc.aux
1566 Encoding: UTF-8
1567 \end{verbatim}
1568 If the document encoding is detected in the \ext{aux} file
1569 (which \bibgls\ should now be able to do), the encoding will
1570 be written to the transcript. For example:
1571 \begin{verbatim}
1572 TeX character encoding: UTF-8
1573 \end{verbatim}
1574 When a \ext{bib} file is read, the \csopt{charset} setting,
1575 the detected encoding (from the encoding comment line,
1576 see \sectionref{sec:bibencoding}), if found, and the encoding
1577 actually used are written. For example, where \csopt{charset} hasn't
1578 been set but an encoding comment line has been found:
1579 \begin{verbatim}
1580 Parsing bib files for resource myDoc.glstex.
1581 Default encoding: not set
1582 Detected encoding: UTF-8
1583 Reading symbols.bib
1584 Encoding: UTF-8
1585 \end{verbatim}
1586
1587 The file encodings used by \bibgls\ are as follows:
1588 \begin{itemize}
1589 \item Writing the \iext{glg} transcript file: default encoding.
1590
1591 \item Reading the document \iext{log} file: \longarg{log-encoding}
1592 setting, if supplied, otherwise the default encoding.
1593
1594 Note that the \ext{log} file may not have the same encoding as the
1595 \ext{tex} file~\cite{tex.sx.2013}. In the case of the T1 font
1596 encoding, the encoding will be close enough to ISO-8859-1 for that
1597 to be used with \bibgls. Any problematic character will trigger a
1598 warning and \bibgls\ will quit reading the file. This will most
1599 likely be in an overfull warning, by which point \bibgls\ should
1600 have gathered all the information it requires.
1601
1602 \item Reading the \iext{aux} file: the \longarg{tex-encoding}
1603 setting, if supplied, or UTF-8 if \sty{fontspec} is detected in the
1604 \ext{log} file, otherwise the default encoding.
1605
1606 \item Reading the \iext{bib} files: the \csopt{charset} resource
1607 option, if supplied, or the encoding specified by the encoding
1608 comment line in the \ext{bib} file (see
1609 \sectionref{sec:bibencoding}), otherwise the default encoding.
1610
1611 \item Writing the \iext{glstex} files: the \longarg{tex-encoding}
1612 setting, if supplied, or UTF-8 if \sty{fontspec} detected in the
1613 \ext{log} file, or the document encoding picked up from the
1614 \ext{aux} file, otherwise the default encoding.
1615 \end{itemize}
1616 For example:
1617 \begin{verbatim}
1618 bib2gls --log-encoding ISO-8859-1 --default-encoding UTF-8 myDoc
1619 \end{verbatim}
1620
1621 To change the default \igls{encoding} for the \idx{JVM} set the
1622 \code{JAVA\_TOOL\_OPTIONS} environment variable to include
1623 \code{-Dfile.encoding=\meta{encoding}} where \meta{encoding} is the
1624 desired default encoding (such as UTF-8). Note that this will
1625 affect all your installed Java applications, not just \bibgls, (for
1626 example, JabRef).
1627
1628 If you have a problem with non-ASCII characters not displaying
1629 correctly in your document:
1630 \begin{itemize}
1631 \item Check that the file \gls{encoding} of your document \ext{tex}
1632 and \ext{bib} files have been correctly set by your text editor.
1633 \item Check that your document supports that \gls{encoding} (for example,
1634 through the \isty{inputenc} package).
1635 \item Check \bibgls's transcript file for the encoding information
1636 to ensure that the settings are correct.
1637 \end{itemize}
1638
1639 \section{Example Use}
1640 The glossary entries are stored in a \ext{bib} file. For
1641 example, the file \filefmt{entries.bib} might contain:
1642 \begin{codeenv}
1643 \atentry{entry}\marg{bird,
1644 \field{name}=\marg{bird},
1645 \field{description} = \marg{feathered animal}
1646 }
1647 \strut
1648 \atentry{abbreviation}\marg{html,
1649 \field{short}=\qtdelim{html},
1650 \field{long}=\marg{hypertext markup language}
1651 }
1652 \strut
1653 \atentry{symbol}\marg{v,
1654 \field{name}=\marg{\idx!{mshiftchar}\cs{vec}\marg{v}\idx!{mshiftchar}},
1655 \field{text}=\marg{\cs{vec}\marg{v}},
1656 \field{description}=\marg{a vector}
1657 }
1658 \strut
1659 \atentry{index}\marg{goose,\field{plural}=\qtdelim{geese}}
1660 \end{codeenv}
1661 Here's an example document that uses this data:
1662 \begin{codeenv}
1663 \cmd{documentclass}\marg{article}
1664 \strut
1665 \cs{usepackage}\oarg{\styoptref{record}}\marg{glossaries-extra}
1666 \strut
1667 \gls{GlsXtrLoadResources}\oarg{
1668 \csopt[entries]{src},\comment{data in entries.bib}
1669 \csopt[en-GB]{sort}\comment{sort according to 'en-GB' locale}
1670 }
1671 \strut
1672 \cmd{begin}\marg{document}
1673 \cs{Gls}\marg{bird} and \cs{gls}\marg{goose}.
1674 Symbol: \idx{mshiftchar}\cs{gls}\marg{v}\idx{mshiftchar}.
1675 Abbreviation: \cs{gls}\marg{html}.
1676 \strut
1677 \cs{printunsrtglossaries}
1678 \cmd{end}\marg{document}
1679 \end{codeenv}
1680 If this document is called \filefmt{myDoc.tex}, the build
1681 process is:
1682 \begin{verbatim}
1683 pdflatex myDoc
1684 bib2gls myDoc
1685 pdflatex myDoc
1686 \end{verbatim}
1687 (This manual assumes \appfmt{pdflatex} for simplicity. Replace
1688 with \appfmt{latex}, \appfmt{xelatex} or \appfmt{lualatex} as
1689 appropriate.) If you want \idxpl{lettergroup} (either headed, with
1690 styles like \glostyle{indexgroup}, or just a blank line separator
1691 with \styopt[false]{nogroupskip}) then you need to use the
1692 \longarg{group} switch:
1693 \begin{verbatim}
1694 pdflatex myDoc
1695 bib2gls --group myDoc
1696 pdflatex myDoc
1697 \end{verbatim}
1698
1699 You can have multiple instances of \gls{GlsXtrLoadResources}. For
1700 example:
1701 \begin{codeenv}
1702 \cmd{documentclass}\marg{article}
1703 \strut
1704 \cmd{usepackage}\oarg{\styopt{record},\styopt{index},\styopt{abbreviations},\styopt{symbols}}\marg{glossaries-extra}
1705 \strut
1706 \gls{GlsXtrLoadResources}\oarg{
1707 \csopt[entries]{src},\comment{data in entries.bib}
1708 \csopt[en-GB]{sort},\comment{sort according to 'en-GB' locale}
1709 \csopt[entrytype=\marg{entry}]{match},\comment{only select \atentry{entry}}
1710 \csopt[main]{type}\comment{put these entries in the 'main' glossary}
1711 }
1712 \strut
1713 \gls{GlsXtrLoadResources}\oarg{
1714 \csopt[entries]{src},\comment{data in entries.bib}
1715 \csopt[en-GB]{sort},\comment{sort according to 'en-GB' locale}
1716 \csopt[entrytype=\marg{abbreviation}]{match},\comment{only select \atentry{abbreviation}}
1717 \csopt[abbreviations]{type}\comment{put these in the 'abbreviations' glossary}
1718 }
1719 \strut
1720 \gls{GlsXtrLoadResources}\oarg{
1721 \csopt[entries]{src},\comment{data in entries.bib}
1722 \csopt[letter-case]{sort},\comment{case-sensitive letter sort}
1723 \csopt[entrytype=\marg{symbol}]{match},\comment{only select \atentry{symbol}}
1724 \csopt[symbols]{type}\comment{put these entries in the 'symbols' glossary}
1725 }
1726 \strut
1727 \gls{GlsXtrLoadResources}\oarg{
1728 \csopt[entries]{src},\comment{data in entries.bib}
1729 \csopt[en-GB]{sort},\comment{sort according to 'en-GB' locale}
1730 \csopt[entrytype=\marg{index}]{match},\comment{only select \atentry{index}}
1731 \csopt[index]{type}\comment{put these entries in the 'index' glossary}
1732 }
1733 \strut
1734 \cmd{begin}\marg{document}
1735 \cs{Gls}\marg{bird} and \cs{gls}\marg{goose}.
1736 Symbol: \idx!{mshiftchar}\cs{gls}\marg{v}\idx!{mshiftchar}. Abbreviation: \cs{gls}\marg{html}.
1737 \cs{printunsrtglossaries}
1738 \cmd{end}\marg{document}
1739 \end{codeenv}
1740 There are more examples provided in \sectionref{sec:examples} and
1741 also in the \href{https://www.dickimaw-books.com/gallery/#bib2gls}{\bibgls\ gallery}.
1742
1743 Note that there's no need to called \idx!{xindy} or \idx!{makeindex}
1744 since \bibgls\ automatically sorts the entries and collates the \glspl{location}
1745 after selecting the required entries from the \ext{bib} file and
1746 before writing the temporary file that's input with
1747 \gls{GlsXtrLoadResources} (or the shortcut
1748 \gls{glsbibdata}).\footnote{This document will mostly use
1749 \gls{GlsXtrLoadResources}.} This
1750 means the entries are already defined in the correct order, and only
1751 those entries that are required in the document are defined, so
1752 \ics{printunsrtglossary} (or \ics{printunsrtglossaries}) may be used.
1753 (The \qtt{unsrt} part of the command name indicates that all
1754 defined entries should be listed in the order of definition from
1755 \styfmt{glossaries-extra}'s point of view, see the supplementary
1756 document \introguide\ for further details.)
1757
1758 If you don't provide a value with the \styopt{record} option, then
1759 \styopt[only]{record} is assumed. This saves the same indexing
1760 information that's used with the \ics{cs.makeglossaries} and
1761 \ics{makenoidxglossaries} methods (described in the main
1762 \styfmt{glossaries} user manual~\cite{glossaries}). As from
1763 \styfmt{glossaries-extra} version 1.37, you can instead use
1764 \styopt[nameref]{record}, which saves some extra information for
1765 each \gls{location} that's not available for the other indexing methods.
1766 See \longarg{merge-nameref-on} for further details.
1767
1768 If you additionally want to use an indexing application, such
1769 as \idx{xindy}, you need the package option
1770 \styopt[alsoindex]{record} and use \ics{cs.makeglossaries}
1771 and \ics{printglossary} (or the iterative \ics{printglossaries}) as usual.
1772 This requires a more complicated build process:
1773 \begin{verbatim}
1774 pdflatex myDoc
1775 bib2gls myDoc
1776 pdflatex myDoc
1777 makeglossaries myDoc
1778 pdflatex myDoc
1779 \end{verbatim}
1780 (The entries aren't defined until the second \LaTeX\ run, so the
1781 indexing files required by \idx!{xindy} or \idx!{makeindex} can't be
1782 created until then.) In this case, \bibgls\ is simply being used to
1783 fetch the entry definitions from one or more \ext{bib} files, with
1784 the sorting and collating performed by the other indexing
1785 application (so the resource option list would need
1786 \csopt[none]{sort} and \csopt[false]{save-locations}). In general,
1787 it's best to avoid this hybrid method unless you have a particular
1788 set of \idx{xindy} rules that can't be replicated with \bibgls.
1789
1790 \section{Logical Divisions: \field{type} vs \field{group} vs \field{parent}}
1791 \label{sec:logicaldivisions}
1792
1793 If you have a document with many terms that need listing, it's
1794 likely that you may want to divide the terms into separate blocks or
1795 units for easier reading. There are three fields that are used
1796 for this.
1797 \begin{description}
1798 \item[\field{type}] The highest division is the glossary to which
1799 the entry belongs. The glossary must first be defined (see
1800 \sectionref{sec:newglossary}) with an associated label used to
1801 identify it. The title is assigned to the glossary when it is
1802 defined or it can be overridden with the \printglossopt{title} key.
1803 The glossary is displayed using \cs{printunsrtglossary} and the
1804 title is placed in a sectioning command by default.
1805
1806 \begin{important}
1807 \bibgls\ does not provide any means of sorting glossary types. If
1808 you use \ics{printunsrtglossaries} the order will be according to
1809 the order in which the glossaries were defined. You may use
1810 \cs{printunsrtglossary} to list individual glossaries in your own
1811 preferred order.
1812 \end{important}
1813
1814 \item[\field{group}] The entries within a glossary can form \idxpl{group}
1815 as a by-product of the sorting method. This must be enabled with the
1816 \longarg{group} switch and isn't available for the sort methods
1817 listed in \tableref{tab:sortoptionsnosort}. The group label is
1818 stored in the \field{group} field. This is an internal field that
1819 typically shouldn't be set in the \ext{bib} file.
1820
1821 You can specify your own \idxpl{customgroup} but if you do so you must
1822 ensure that the terms are ordered in such a way that they are
1823 gathered according to group. This is typically done by splitting the
1824 glossary into blocks using a separate \gls{GlsXtrLoadResources} with
1825 the \csopt{group} option set. You control the order of the groups by
1826 your ordering of \gls{GlsXtrLoadResources}. The group title can be
1827 assigned using \gls{glsxtrsetgrouptitle} within the document.
1828
1829 \begin{important}
1830 \bibgls\ does not sort by group title. At most it can sort by the
1831 group label (by changing the \csopt{sort-field}) but this is usually
1832 an indication that you actually have a \gls{hierarchicalglossary} and you
1833 ought to be using the \field{parent} field instead. (Compare
1834 \exfile{sample-textsymbols.tex} and
1835 \exfile{sample-textsymbols2.tex}.)
1836 \end{important}
1837
1838 \item[\field{parent}] An entry may have one or more \glspl{sub-entry}.
1839 Most of the sort methods will produce a \hierarchical\ ordering that
1840 ensures that the \glspl{sub-entry} are listed immediately after their
1841 \gls{parententry}. The \gls{parententry} is identified by the \field{parent}
1842 field which should contain the \glsdisp{parententry}{parent's} label.
1843
1844 \begin{important}
1845 \bibgls\ sorts the \parent\ and \child\ entries using the same
1846 comparator. The sort methods listed in
1847 \tableref{tab:sortoptionsnosort} disregard the \hierarchicallevel,
1848 which can result in \glspl{childentry} becoming detached from their
1849 \gls{parententry}. The other methods sort \hierarchically\ using the
1850 same comparator but take the \hierarchicallevel\ into account.
1851 \end{important}
1852
1853 \end{description}
1854
1855 Suppose you have a mixture of terms, abbreviations and symbols, then
1856 you might want to have three glossaries that are listed in the table
1857 of contents. In this case, you use the \field{type} field or the
1858 \field{type} resource option. The ordering of the glossaries is
1859 determined by the ordering of the \cs{printunsrtglossary}
1860 commands within the document. For example:
1861 \begin{codeenv}
1862 \cs{printunsrtglossary}
1863 \cs{printunsrtglossary}\oarg{\printglossopt[abbreviations]{type}}
1864 \cs{printunsrtglossary}\oarg{\printglossopt[symbols]{type}}
1865 \end{codeenv}
1866
1867 Suppose that your list of terms spans many pages and you feel it
1868 would be helpful to the reader to split it up into letter groups
1869 then you would need to run \bibgls\ with the \longarg{group} switch
1870 and use a glossary style that supports \idxpl{lettergroup} for that
1871 glossary. For example:
1872 \begin{codeenv}
1873 \cs{printunsrtglossary}\oarg{\printglossopt[indexgroup]{style}}
1874 \end{codeenv}
1875
1876 Suppose that your list of symbols consists of pictographs, Latin characters
1877 and Greek characters and you want them grouped together
1878 in that order. Then you would use a separate
1879 \gls{GlsXtrLoadResources} for each block and assign your own custom
1880 group. This means ensuring that each \igls{resourceset} only selects
1881 the terms for that group. The simplest way of doing this is to
1882 have a separate \ext{bib} file for each set. For example:
1883 \begin{codeenv}
1884 \gls{glsxtrsetgrouptitle}\marg{pictographs}\marg{Pictographs}
1885 \gls{glsxtrsetgrouptitle}\marg{latinsymbols}\marg{Latin Characters}
1886 \gls{glsxtrsetgrouptitle}\marg{greeksymbols}\marg{Greek Characters}
1887 \gls{GlsXtrLoadResources}\oarg{
1888 \csopt[generalsymbols]{src},\comment{data in generalsymbols.bib}
1889 \csopt[pictographs]{group},
1890 \csopt[symbols]{type}
1891 }
1892 \gls{GlsXtrLoadResources}\oarg{
1893 \csopt[latinsymbols]{src},\comment{data in latinsymbols.bib}
1894 \csopt[latin]{group},
1895 \csopt[symbols]{type}
1896 }
1897 \gls{GlsXtrLoadResources}\oarg{
1898 \csopt[greeksymbols]{src},\comment{data in greeksymbols.bib}
1899 \csopt[greek]{group},
1900 \csopt[symbols]{type}
1901 }
1902 \end{codeenv}
1903
1904 Suppose instead that you have many of these logical blocks and you
1905 want them ordered according to the block title. In this case you
1906 have a \gls{hierarchicalglossary} and you need to use the \field{parent}
1907 field. You then need to select an appropriate \idx{glossarystyle}.
1908
1909 If you only want to have a single \ext{bib} file that contains all
1910 your entries and you want to share it across multiple documents then
1911 the most flexible approach is to use custom fields and \glspl{entrytype}
1912 that can be aliased according to the needs of the \glspl{resourceset}.
1913
1914 For example, the file \filefmt{entries.bib}:
1915 \begin{codeenv}
1916 \comment{Encoding: UTF-8}
1917 \strut
1918 \atentryfmt{indexplural}\marg{latin,\field{text}=\marg{Latin character}}
1919 \atentryfmt{indexplural}\marg{greek,\field{text}=\marg{Greek character}}
1920 \atentryfmt{indexplural}\marg{pictograph}
1921 \strut
1922 \atentry{symbol}\marg{fx,
1923 \field{name}=\marg{\cs{ensuremath}\marg{f(x)}},
1924 \field{description}=\marg{function of \idx{mshiftchar}x\idx{mshiftchar}},
1925 \fieldfmt{identifier}=\marg{latin}
1926 }
1927 \strut
1928 \atentry{symbol}\marg{f\idx{aposchar}x,
1929 \field{name}={\cs{ensuremath}\marg{f\idx{aposchar}(x)}},
1930 \field{description}=\marg{derivative of \cs{gls}\marg{fx}},
1931 \fieldfmt{identifier}=\marg{latin}
1932 }
1933 \strut
1934 \atentry{symbol}\marg{pi,
1935 \field{name}=\marg{\cs{ensuremath}\marg{\cs{pi}}},
1936 \field{description}=\marg{ratio of circumference to diameter},
1937 \fieldfmt{identifier}=\marg{greek}
1938 }
1939 \strut
1940 \atentry{symbol}\marg{heart,
1941 \field{name}=\marg{\cs{ensuremath}\marg{\ics{heartsuit}}},
1942 \field{description}=\marg{heart},
1943 \fieldfmt{identifier}=\marg{pictograph}
1944 }
1945 \strut
1946 \atentry{symbol}\marg{diamond,
1947 \field{name}=\marg{\cs{ensuremath}\marg{\ics{diamondsuit}}},
1948 \field{description}=\marg{diamond},
1949 \fieldfmt{identifier}=\marg{pictograph}
1950 }
1951 \strut
1952 \atentry{abbreviation}\marg{html,
1953 \field{short}=\marg{html},
1954 \field{long}=\marg{hypertext markup language},
1955 \fieldfmt{identifier}=\marg{markuplanguage}
1956 }
1957 \strut
1958 \atentry{abbreviation}\marg{xml,
1959 \field{short}=\marg{xml},
1960 \field{long}=\marg{extensible markup language},
1961 \fieldfmt{identifier}=\marg{markuplanguage}
1962 }
1963 \strut
1964 \atentry{entry}\marg{duck,
1965 \field{name}=\marg{duck},
1966 \field{description}=\marg{a waterbird with webbed feet},
1967 \fieldfmt{identifier}=\marg{animal}
1968 }
1969 \strut
1970 \atentry{entry}\marg{parrot,
1971 \field{name}=\marg{parrot},
1972 \field{description}=\marg{mainly tropical bird with bright plumage},
1973 \fieldfmt{identifier}=\marg{animal}
1974 }
1975 \end{codeenv}
1976 This has a custom field \fieldfmt{identifier}. This will be ignored
1977 by \bibgls\ unless defined or aliased in the document.
1978
1979 Here's an example document that creates three glossary types (the
1980 default \mainglossary\ and the glossaries created with the
1981 \styopt{abbreviations} and \styopt{symbols} options). They are
1982 listed in the order of \cs{printunsrtglossary} and their titles are
1983 added to the table of contents.
1984
1985 The custom \fieldfmt{identifier} fields are ignored for the
1986 \glsdisp{mainglossary}{main} and abbreviation glossaries, but they are aliased for the
1987 symbols to the \field{group} field. Since I've split the symbols
1988 glossary into blocks with each block only containing entries that
1989 have the same \field{group} value, this isn't a problem. It also
1990 won't trigger a warning with \longarg{warn-non-bib-fields} as it's
1991 being aliased rather than set in the \ext{bib} file. The blocks
1992 appear in the same order as the corresponding \gls{GlsXtrLoadResources}
1993 commands. The title for each block is provided in the document
1994 using \gls{glsxtrsetgrouptitle}.
1995 \begin{codeenv}
1996 \cmd{documentclass}\marg{article}
1997 \strut
1998 \cmd{usepackage}\oarg{\styopt{record},\styopt{abbreviations},\styopt{symbols}}\marg{glossaries-extra}
1999 \strut
2000 \cs{renewcommand}\marg{\gls{GlsXtrDefaultResourceOptions}}\marg{
2001 \csopt[all]{selection},\csopt[entries]{src},\csopt[false]{save-locations}}
2002 \strut
2003 \gls{GlsXtrLoadResources}\oarg{\csopt[main]{type},\csopt[entrytype=entry]{match}}
2004 \gls{GlsXtrLoadResources}\oarg{\csopt[abbreviations]{type},
2005 \csopt[entrytype=abbreviation]{match}}
2006 \strut
2007 \gls{glsxtrsetgrouptitle}\marg{pictograph}\marg{Pictographs}
2008 \gls{GlsXtrLoadResources}\oarg{\csopt[symbols]{type},
2009 \csopt[identifier=\field{group}]{field-aliases},
2010 \csopt[\field{group}=pictograph]{match}}
2011 \strut
2012 \gls{glsxtrsetgrouptitle}\marg{latin}\marg{Latin Characters}
2013 \gls{GlsXtrLoadResources}\oarg{\csopt[symbols]{type},
2014 \csopt[identifier=\field{group}]{field-aliases},
2015 \csopt[\field{group}=latin]{match}}
2016 \strut
2017 \gls{glsxtrsetgrouptitle}\marg{greek}\marg{Greek Characters}
2018 \gls{GlsXtrLoadResources}\oarg{\csopt[symbols]{type},
2019 \csopt[identifier=\field{group}]{field-aliases},
2020 \csopt[\field{group}=greek]{match}}
2021 \strut
2022 \cmd{begin}\marg{document}
2023 \cs{tableofcontents}
2024 \cs{printunsrtglossary}\oarg{\printglossopt[abbreviations]{type}}
2025 \cs{printunsrtglossary}
2026 \cs{printunsrtglossary}\oarg{\printglossopt[symbols]{type},\printglossopt[\glostyle{treegroup}]{style}}
2027 \cmd{end}\marg{document}
2028 \end{codeenv}
2029
2030 In the above example document, the symbols list is divided into
2031 three groups, listed in the order: Pictographs, Latin characters and
2032 Greek characters. If you want these titles ordered alphabetically
2033 then you need a \hierarchical\ structure instead. This can be obtained
2034 by aliasing the custom \fieldfmt{identifier} field to
2035 \field{parent}:
2036 \begin{codeenv}
2037 \cmd{documentclass}\marg{article}
2038 \strut
2039 \cmd{usepackage}\oarg{\styopt{record},\styopt[topic]{stylemods},\styopt{abbreviations},\styopt{symbols}}\marg{glossaries-extra}
2040 \strut
2041 \cs{renewcommand}\marg{\gls{GlsXtrDefaultResourceOptions}}\marg{\comment{}
2042 \csopt[all]{selection},\csopt[entries]{src},\csopt[false]{save-locations}}
2043 \strut
2044 \gls{GlsXtrLoadResources}\oarg{\csopt[main]{type},\csopt[entrytype=entry]{match}}
2045 \gls{GlsXtrLoadResources}\oarg{\csopt[abbreviations]{type},
2046 \csopt[entrytype=abbreviation]{match}}
2047 \strut
2048 \gls{GlsXtrLoadResources}\oarg{\csopt[symbols]{type},
2049 \csopt[identifier=\field{parent}]{field-aliases},
2050 \csopt[entrytype=symbol,entrytype=indexplural]{match}}
2051 \strut
2052 \cmd{begin}\marg{document}
2053 \cs{tableofcontents}
2054 \cs{printunsrtglossary}\oarg{\printglossopt[abbreviations]{type}}
2055 \cs{printunsrtglossary}
2056 \cs{printunsrtglossary}\oarg{\printglossopt[symbols]{type},\printglossopt[\glostyle{topic}]{style}}
2057 \cmd{end}\marg{document}
2058 \end{codeenv}
2059 The style used for the symbols list is now \glostyle{topic} rather
2060 than \glostyle{treegroup}. This results in a slightly different
2061 appearance. You can select the most appropriate style according to
2062 your needs (see the gallery of predefined
2063 styles~\cite{glossarystylesgallery}). The topic ordering is now:
2064 Greek characters, Latin characters and Pictographs.
2065
2066 \section{Defining a New Glossary}
2067 \label{sec:newglossary}
2068
2069 Some of the examples in this manual use \ics{newglossary*} to define
2070 a new glossary type and some use \ics{newignoredglossary} or
2071 \ics{newignoredglossary*}. You may be wondering why the starred
2072 forms and why define an \igls{ignoredglossary}?
2073
2074 The base \styfmt{glossaries} package was originally designed to work
2075 with \idx!{makeindex}. Support for \idx!{xindy} was later added, but
2076 both require three files per glossary type: the transcript file
2077 (created by the indexing application), the file written by \LaTeX\
2078 (and input by the indexing application) and the file input by
2079 \LaTeX\ (and written by the indexing application). So when a new glossary
2080 is defined with \ics{newglossary}, this not only defines internal
2081 control sequences that store the list of entry labels associated
2082 with that glossary, the title and the entry format but also has to
2083 define internal control sequences that store the three file
2084 extensions. The starred form \cs{newglossary*} is just a shortcut
2085 that forms the extensions from the glossary label. For the purposes
2086 of \bibgls, this is simpler than the unstarred version since the
2087 extensions are now irrelevant as they are only applicable to
2088 \idx!{makeindex} and \idx!{xindy}. (Unless, of course, you are using
2089 a hybrid method with \styopt[alsoindex]{record}.)
2090
2091 Since some users wanted the ability to define entries that were
2092 common enough to not be worth including in any glossary lists, the
2093 concept of an \igls{ignoredglossary} was introduced, defined with
2094 \cs{newignoredglossary}. This only requires an internal control
2095 sequence to store the list of entry labels associated with that
2096 glossary\footnote{All entries must be assigned to a glossary. If you
2097 don't use the \field{type} field the default is used.}\ and the
2098 associated internal command that governs the way that
2099 commands like \cs{gls} are displayed for that glossary type.
2100 Since this type of glossary has no associated files, it can't be
2101 used with \cs{printglossary} and therefore isn't included in the
2102 list of glossary labels that's iterated over by commands like
2103 \cs{printglossaries}. Since there's no glossary list (and therefore
2104 no targets), \cs{newignoredglossary} additionally disables hyperlinks for that
2105 glossary type, but it doesn't disable indexing. The indexing macro
2106 is still called, but because there's no associated file to write to,
2107 it has no effect. With \bibgls, the indexing is written to the
2108 \ext{aux} file and so does have an effect.
2109
2110 Although \iglspl{ignoredglossary} can't be used with
2111 \cs{printglossary}, they can be used with \cs{printunsrtglossary},
2112 which is designed to work without any indexing, but you need to
2113 explicitly set the title in the optional argument to override the
2114 default. \Idxpl{ignoredglossary} still can't be used in
2115 \cs{printunsrtglossaries}, since they're not included in the list
2116 that this command iterates over.
2117
2118 So \cs{newignoredglossary} (or \cs{provideignoredglossary}) is
2119 useful with \bibgls\ if you're happy to use \cs{printunsrtglossary}
2120 with the \printglossopt{type} and \printglossopt{title} options as it reduces the overall
2121 number of internal control sequences. \Idxpl{ignoredglossary} are
2122 also useful for stand-alone definitions (\ics{glsxtrglossentry}) or
2123 with \ics{printunsrtinnerglossary} as no title is required in those
2124 cases (see \exfile{sample-nested.tex} for an example).
2125
2126 Since there is now the possibility of targets (created within \cs{printunsrtglossary} or
2127 \cs{printunsrtinnerglossary} or \cs{glsxtrglossentry}), it's convenient to
2128 have an \igls{ignoredglossary} that doesn't suppress the hyperlinks,
2129 which can be obtained with the starred form \ics{newignoredglossary*}
2130 provided by \styfmt{glossaries-extra} (or \cs{provideignoredglossary*}).
2131
2132 Some resource options, such as \csopt{master}, \csopt{secondary},
2133 and \csopt{trigger-type}, need to ensure that a
2134 required glossary is defined. In this case, \bibgls\ uses
2135 \ics{provideignoredglossary*} in the \iext{glstex} file
2136 even if \longarg{no-provide-glossaries} is set.
2137 Note that only \csopt{ignored-type} uses the unstarred
2138 \ics{provideignoredglossary}.
2139
2140 If you haven't already defined that glossary in the document with \cs{newglossary*},
2141 you'll need to set the title in the optional argument of
2142 \cs{printunsrtglossary} if you don't want the default. The glossary
2143 won't be defined on the first run (if the definition is only
2144 provided in the \ext{glstex} file) but \cs{printunsrtglossary} will
2145 just give a warning if the type is undefined so it won't interrupt
2146 the document build.
2147
2148 If you want \bibgls\ to automatically provide unknown glossaries for
2149 all entries that have the \field{type} field set (unrelated to the
2150 \csopt{master}, \csopt{secondary}, \csopt{trigger-type}
2151 and \csopt{ignored-type} options)
2152 then use the \longarg{provide-glossaries} switch.
2153
2154 The base \sty{glossaries} package provides a command that can be
2155 used to test the existence of a glossary:
2156 \begin{codeenv}
2157 \ics{ifglossaryexists}\margm{label}\margm{true}\margm{false}
2158 \end{codeenv}
2159 The unstarred version considers \glspl{ignoredglossary} as non-existent
2160 (and so will do \meta{false} for an \gls{ignoredglossary}). As from
2161 v4.46, this command now has a starred version
2162 \ics{ifglossaryexists*} that considers \glspl{ignoredglossary} as
2163 existing (and so will do \meta{true} for an \gls{ignoredglossary}). In
2164 the event that you have an older version of \sty{glossaries}, the
2165 \sty{glossaries-extra} package (v1.44+) will provide the starred
2166 form if it hasn't been defined. (In general, it's best to have
2167 up-to-date versions of both \sty{glossaries} and
2168 \sty{glossaries-extra}.)
2169
2170 \section{Resource Sets}
2171 \label{sec:resourcesets}
2172
2173 Each instance of \gls{GlsXtrLoadResources} (or
2174 \gls{glsbibdata}) in the document represents a \igls{resourceset}. Each
2175 \igls{resourceset} has one or more associated \iext{bib} files
2176 that provides the data for that set. Command line switches
2177 (\sectionref{sec:switches}) are applied to all \iglspl{resourceset}.
2178 Resource options (\sectionref{sec:resourceopts}) are only applied to
2179 that specific \igls{resourceset}. Each \igls{resourceset} is processed
2180 in stages:
2181 \begin{description}
2182
2183 \item[Stage 1 (Initialisation)] Occurs after the \ext{aux} file has
2184 been read, this stage parses the resource option list and ensures
2185 options are valid and don't cause a conflict. The transcript will
2186 show the message
2187 \begin{alltt}
2188 Initialising resource \meta{resource-name}
2189 \end{alltt}
2190 at this point.
2191
2192 \item[Stage 2 (Parsing)] All the \iext{bib} files associated with
2193 the \igls{resourceset} are parsed. Entry aliases (identified by
2194 \csopt{entry-type-aliases}) are performed. The
2195 \hyperref[sec:multientry]{multi-entry types}, such as
2196 \atentry{bibtexentry} and \atentry{progenitor}, spawn their
2197 associated \glspl{primaryentry}. Preamble information (provided by
2198 \atentry{preamble}) is saved but is not interpreted at this stage.
2199 The transcript will show the message
2200 \begin{alltt}
2201 Parsing bib files for resource \meta{resource-name}
2202 \end{alltt}
2203 at this point.
2204
2205 \item[Stage 3 (Processing Entries)]
2206 The transcript will show the message
2207 \begin{alltt}
2208 Processing resource \meta{resource-name}
2209 \end{alltt}
2210 at this point.
2211 For each entry that was found in
2212 the corresponding set of \ext{bib} files:
2213 \begin{itemize}
2214 \item Records are transferred to aliases if required (\csopt{alias-loc}).
2215 \item Field checks and modifications are performed:
2216 \begin{itemize}
2217 \item field aliases are performed (\csopt{field-aliases});
2218
2219 \item known fields identified with \csopt{save-original-id} and
2220 \csopt{save-original-entrytype} are set (internal fields that
2221 don't have a corresponding key for use with \gls!{newglossaryentry} aren't
2222 set until the \ext{glstex} file is written);
2223
2224 \item ignored fields (identified by \csopt{ignore-fields}, not by \csopt{omit-fields}) are
2225 removed;
2226
2227 \item case-changes (for example, \csopt{short-case-change}) are
2228 performed, except for the \field{name} field and fields identified
2229 with \csopt{field-case-change};
2230
2231 \item suffixes are appended if required (for example, with
2232 \csopt{short-plural-suffix});
2233
2234 \item field replications are made (\csopt{replicate-fields}),
2235 and any of the above case-change or suffixes required
2236 on the replicated fields are performed;
2237
2238 \item the \field{group} field is assigned if \csopt[\meta{label}]{group}
2239 is set;
2240
2241 \item any variables (identified by \atentry{string}) are expanded
2242 (if not already done in any of the previous steps);
2243
2244 \item any fields that have been identified by
2245 \csopt{bibtex-contributor-fields} are converted;
2246
2247 \item any fields that have been identified with
2248 \csopt{encapsulate-fields} are converted;
2249
2250 \item any fields that have been identified with
2251 \csopt{encapsulate-fields*} are converted;
2252
2253 \item any fields that must be converted into a label form
2254 (\csopt{labelify} or \csopt{labelify-list}) are processed;
2255
2256 \item any fields identified by \csopt{dependency-fields} are parsed for
2257 dependent entries;
2258
2259 \item any fields whose value must be a label are interpreted
2260 if \csopt{interpret-label-fields} is set;
2261
2262 \item the \field{parent} field is adjusted according to the label prefix
2263 settings (\csopt{label-prefix} etc);
2264
2265 \item \ics{makefirstuc} protection is applied according to
2266 \longarg{mfirstuc-protection} and \longarg{mfirstuc-math-protection};
2267
2268 \item fields are parsed for commands like \cs{gls} or
2269 \cs{glshyperlink} and also checked for nested links if
2270 \longarg{nested-link-check} is set;
2271
2272 \item the \field{description} field is adjusted according to
2273 \csopt{strip-trailing-nopost};
2274
2275 \item end punctuation is checked according to
2276 \csopt{check-end-punctuation};
2277
2278 \item field assignments are made (\csopt{assign-fields}),
2279 and any of the above case-change or suffixes required
2280 by the destination fields are performed;
2281
2282 \item \field{name} adjustment is performed if
2283 \csopt{compound-adjust-name} is set (and the criteria is met);
2284
2285 \item \field{name} case-change is performed if
2286 \csopt{name-case-change} is set;
2287
2288 \item if \csopt[true]{copy-alias-to-see} the \field{alias} is copied
2289 to the \field{see} field;
2290
2291 \item general field case changes identified by
2292 \csopt{field-case-change} are performed;
2293
2294 \item any fields that have been identified with
2295 \csopt{interpret-fields} are replaced with their interpreted
2296 values;
2297
2298 \item any fields that have been identified with
2299 \csopt{hex-unicode-fields} will have Unicode characters replaced;
2300
2301 \item check for \field{nonumberlist}.
2302 \end{itemize}
2303 \item The dual version (if appropriate) is created.
2304 \item \Glspl{record} are added to the entry's \igls{locationlist} (or transferred
2305 to the \dual\slash\primary\ according to \csopt{combine-dual-locations}).
2306 \item The \field{type}, \field{category} and \field{counter} fields
2307 are set according to \csopt{type}, \csopt{dual-type},
2308 \csopt{category}, \csopt{dual-category}, \csopt{counter} and
2309 \csopt{dual-counter}.
2310 \item Filtering is applied (according to options like \csopt{match}
2311 but not \csopt{selection} or \csopt{limit}).
2312 \item Required fields are checked for existence.
2313 \item Dependencies are registered (if
2314 \csopt[recorded and deps]{selection} or \csopt[recorded and deps and
2315 see]{selection}).
2316 \item Any fields that have been identified by
2317 \csopt{date-time-fields}, \csopt{date-fields} or \csopt{time-fields}
2318 are converted.
2319 \end{itemize}
2320 If \csopt[recorded and deps and see]{selection} then any
2321 \glspl{recordedentry} that have been cross-referenced by an
2322 \gls{unrecordedentry}, will register a dependency with the
2323 \gls{unrecordedentry}.
2324
2325 The \gls{compoundentry} options \csopt{compound-dependent} and
2326 \csopt{compound-add-hierarchy} are implemented, if enabled.
2327
2328 Finally, \glspl{supplementalrecord} are added to entries.
2329
2330 \item[Stage 4 (Selection, Sorting, Writing)] Entries are selected
2331 from the list according to the \csopt{selection} setting, sorting is
2332 performed (if required), truncation is applied (if \csopt{limit} is
2333 set) and the \iext{glstex} file is written.
2334 The transcript will show the message
2335 \begin{alltt}
2336 Selecting entries for resource \meta{resource-name}
2337 \end{alltt}
2338 or (if \csopt{master})
2339 \begin{alltt}
2340 Processing master \meta{resource-name}
2341 \end{alltt}
2342 at this point.
2343
2344 Options such as \csopt{copy-to-glossary} and \csopt{omit-fields} are
2345 implemented when each entry has its definition written to the \ext{glstex}
2346 file. This means that the omitted fields will still be available for actions
2347 such as sorting, establishing dependencies, or field assignments.
2348
2349 \end{description}
2350
2351 Parent entries must always be in the same \igls{resourceset} as their
2352 \glspl{childentry}. (They may be defined in different \ext{bib} files as
2353 long as all those \ext{bib} files are listed in the same \csopt{src}.)
2354 Other forms of dependencies may be in a
2355 different \igls{resourceset} under certain circumstances. These types
2356 of dependencies are instances of commands such as \cs{gls} being
2357 found (for example, in the \field{description} field), or the
2358 \glspl{cross-referencefield} (\field{see}, \field{seealso} or
2359 \field{alias} or fields identified with \csopt{dependency-fields})
2360 in \glspl{recordedentry} that reference \glspl{unrecordedentry}.
2361
2362 The \qt{cross-referenced by} dependencies enabled with
2363 \csopt[recorded and deps and see]{selection} (where an
2364 \gls{unrecordedentry} references a \gls{recordedentry} through the
2365 \glspl{cross-referencefield}) \emph{aren't supported} across
2366 \iglspl{resourceset} (even with \longarg{force-cross-resource-refs}).
2367
2368 A \igls{crossresourceref} is a reference from a \gls{recordedentry}
2369 provided in one \igls{resourceset} to an \gls{unrecordedentry} in
2370 another \igls{resourceset}. Since the contents of each
2371 \igls{resourceset}['s] preamble must be processed before fields can
2372 be interpreted and one \igls{resourceset}['s] preamble may contain
2373 definitions that override another, \iglspl{crossresourceref} can't
2374 be supported if fields containing cross-referencing information need
2375 to be interpreted.
2376
2377 The \igls{crossresourceref} mode determines whether or not \bibgls\
2378 can support \iglspl{crossresourceref}. If enabled, the message
2379 \begin{verbatim}
2380 Cross-resource references allowed.
2381 \end{verbatim}
2382 will be written to the transcript otherwise the message is
2383 \begin{verbatim}
2384 Cross-resource references disabled.
2385 \end{verbatim}
2386 The mode can only be enabled if the following condition is satisfied:
2387 \begin{itemize}
2388 \item the interpreter is off (\longarg{no-interpret}), or
2389 \item every \igls{resourceset} either doesn't have a preamble
2390 (\atentry{preamble}) or has \csopt[false]{interpret-preamble} set.
2391 \end{itemize}
2392 If you know the preamble contents won't cause a problem, you
2393 can force the \iglspl{crossresourceref} mode on with
2394 \longarg{force-cross-resource-refs}.
2395
2396 If you don't use either \csopt[recorded and
2397 deps]{selection} or \csopt[recorded and deps and see]{selection}
2398 then the dependencies aren't picked up for that \igls{resourceset}
2399 (and so can't be cross-referenced from another \igls{resourceset}).
2400
2401 Trails don't work with \iglspl{crossresourceref}. For example, if
2402 entry $A$ has been recorded and depends on entry $B$ that hasn't been
2403 recorded, then $B$ can be picked up from a different
2404 \igls{resourceset}, but if $A$ and $B$ are in the same
2405 \igls{resourceset} and $B$ is dependent on $C$ which is in a
2406 different \igls{resourceset} then $C$ won't be picked up if it hasn't
2407 been recorded because $B$ hasn't been recorded and is in a different
2408 \igls{resourceset}.
2409
2410 If the \igls{crossresourceref} mode is enabled then stage~3 and
2411 stage~4 are processed in separate \idxpl{loop}, otherwise they are
2412 processed in the same \idx{loop}.
2413
2414 \section{\bibgls\ Quarks}
2415 \label{sec:quarks}
2416
2417 A \bibgls\ \idx{quark} is similar in principle to a \LaTeX3 quark,
2418 in that it is a token that looks like a control sequence but isn't
2419 intended to be interpreted as a \LaTeX\ command. Unlike \LaTeX3
2420 quarks, their name isn't prefixed with \csfmt{q\_} and can
2421 coincidentally look the same as a \LaTeX\ command. This is
2422 particularly the case with regular expressions that have escaped
2423 characters to indicate a literal character. For example, in a
2424 regular expression a pipe or vertical bar character \idx{regexpor}
2425 indicates \qt{or}. If you want to match a literal pipe, you need to
2426 identify this with \cs{quark.pipe}. This is distinct from, but
2427 visually identical to, the \LaTeX\ command used to create a double
2428 vertical bar in maths mode.
2429
2430 The resource options provided in \gls{GlsXtrLoadResources} expand as
2431 they are written to the \ext{aux} file. This allows commands to be
2432 used within the resource options that expand to a complex option
2433 that may be required multiple times. For example,
2434 \ics{GlsXtrBibTeXEntryAliases} or \ics{glsxtrhyphenrules}.
2435 Unfortunately, this means that quarks must be prevented from
2436 expansion as they form part of the option syntax and are not
2437 intended for use in the document.
2438
2439 This means that, unless they happen to coincidentally be robust
2440 commands, they must be preceded by either \ics{protect} or
2441 \idx{cs.string}. Since \cs{protect} adds a space afterwards,
2442 \idx{cs.string} is usually better if the syntax requires that spaces
2443 after quarks are significant.
2444
2445 This can lead to cumbersome expressions, but it's possible to
2446 redefine \ics{glsxtrresourceinit} to locally redefine these quarks
2447 to expand to detokenized forms of themselves. For example:
2448 \begin{codeenv}
2449 \cs{renewcommand}*\marg{\cs{glsxtrresourceinit}}\marg{\cmd{let}\cmd{u}\cs{glshex}}
2450 \end{codeenv}
2451 Since there are a number of these quarks, as from v1.51,
2452 \sty{glossaries-extra-bib2gls} (which is automatically loaded with
2453 \styopt{record}) provides \ics{GlsXtrResourceInitEscSequences},
2454 so you can change the above to the following:
2455 \begin{codeenv}
2456 \cs{renewcommand}*\marg{\cs{glsxtrresourceinit}}\marg{\comment{}
2457 \cs{GlsXtrResourceInitEscSequences}
2458 }
2459 \end{codeenv}
2460 Note that if new quarks, such as \gls{INTERPRETNOREPL} and \gls{REPLACESPCHARS},
2461 are added to \bibgls, they may not be included in \cs{GlsXtrResourceInitEscSequences} if they
2462 were introduced to \bibgls\ after the version date of the \sty{glossaries-extra}
2463 package installed on your system. In this case, you will need to add them. For example:
2464 \begin{codeenv}
2465 \cs{renewcommand}*\marg{\cs{glsxtrresourceinit}}\marg{\comment{}
2466 \cs{GlsXtrResourceInitEscSequences}
2467 \cmd{def}\gls{INTERPRETNOREPL}\marg{\idx{cs.string}\gls{INTERPRETNOREPL}}\comment{}
2468 \cmd{def}\gls{REPLACESPCHARS}\marg{\idx{cs.string}\gls{REPLACESPCHARS}}\comment{}
2469 }
2470 \end{codeenv}
2471
2472
2473 This will locally define the quarks listed below. Since
2474 \cs{glsxtrresourceinit} is used in a scoped context, the
2475 definitions only have an effect within the protected write, and so this
2476 shouldn't interfere with the corresponding commands that are
2477 required in the document. Note that these quarks should only be used
2478 in their designated contexts.
2479
2480 \begin{description}
2481
2482 \item[General] \inlinedef{uhex} is recognised in certain resource options
2483 (such as \csopt{field-concat-sep}) as indicating the Unicode
2484 character with the given hexadecimal code.
2485
2486 \item[Regular expressions] The following indicate a literal
2487 character:
2488 \glsadd{idx.periodchar}\inlinedef{quark.dot}
2489 \glsadd{idx.backslashchar}\inlinedef{quark.backslash}
2490 \glsadd{idx.slashchar}\inlinedef{quark.slash}
2491 \glsadd{idx.pipechar}\inlinedef{quark.pipe}
2492 \glsadd{idx.ampchar}\inlinedef{quark.amp}
2493 \glsadd{idx.pluschar}\inlinedef{quark.plus}
2494 \glsadd{idx.ltchar}\inlinedef{quark.lt}
2495 \glsadd{idx.gtchar}\inlinedef{quark.gt}
2496 \glsadd{idx.starchar}\inlinedef{quark.star}
2497 \glsadd{idx.dollarchar}\inlinedef{quark.dollar}
2498 \glsadd{idx.circumchar}\inlinedef{quark.circum}
2499 \glsadd{idx.tildechar}\inlinedef{quark.tilde}
2500 \glsadd{idx.openparenchar}\inlinedef{quark.openparen}
2501 \glsadd{idx.closeparenchar}\inlinedef{quark.closeparen}
2502 \glsadd{idx.opensqchar}\inlinedef{quark.opensq}
2503 \glsadd{idx.closesqchar}\inlinedef{quark.closesq}
2504 \glsadd{idx.doublequotechar}\inlinedef{quark.doublequote}
2505 \glsadd{idx.hyphenchar}\inlinedef{quark.hyphen}
2506 \glsadd{idx.questionchar}\inlinedef{quark.question}
2507 \glsadd{idx.colonchar}\inlinedef{quark.colon}
2508 \glsadd{idx.hashchar}\inlinedef{quark.hash}.
2509 Note that \idxpl{regex} in resource options are typically
2510 \gls{anchored}, so there shouldn't be any need to use \idx{regex.circum}
2511 or \idx{regex.dollar} to denote the start and end.
2512
2513 \item[Field assignments] The following commands may be used in the
2514 \meta{element-list} syntax of \csopt{assign-fields}:
2515 \gls{CS}, \gls{MGP}, \gls{LEN}, \gls{TRIM}, \gls{INTERPRET},
2516 \gls{INTERPRETNOREPL}, \gls{REPLACESPCHARS},
2517 \gls{LC}, \gls{UC}, \gls{FIRSTLC}, \gls{FIRSTUC}, and \gls{TITLE}.
2518
2519 \item[Conditionals] The \meta{condition} part of the \csopt{assign-fields}
2520 syntax recognises \gls{LEN}, \gls{CAT}, \gls{IN}, \gls{NIN}, \gls{PREFIXOF},
2521 \gls{NOTPREFIXOF}, \gls{SUFFIXOF}, \gls{NOTSUFFIXOF} and \gls{NULL}.
2522 \end{description}
2523
2524 Finally, this isn't actually a quark, but \inlinedef{cs} is defined
2525 to expand to the literal string \csfmt{\meta{csname}} so you can use it for any
2526 other escape sequences that aren't covered above. For example,
2527 \code{\gls{cs}\marg{n}} for a newline \ics{n}.
2528
2529 \section{Indexing}
2530
2531 The dual index entries such as \atentry{dualindexentry} (described in
2532 \sectionref{sec:dualentry}) are designed to provide a way of
2533 including an entry in a glossary (with a description) and also
2534 include the term (without the description) in an index. Additional
2535 terms that should only appear in the index can be defined with
2536 \atentry{index}. (See, for example, the \exfile{sample-multi1.tex}
2537 and \exfile{sample-multi2.tex} sample files.)
2538
2539 Although \bibgls\ is designed to create indexes as well as glossary
2540 lists using the same interface (\cs{gls} etc), it is
2541 possible to have a mixture of \bibgls\ and \ics{index}. For example:
2542 \begin{codeenv}
2543 \cmd{documentclass}\marg{report}
2544 \strut
2545 \cmd{usepackage}\marg{makeidx}
2546 \cmd{usepackage}\oarg{\styopt{record}}\marg{glossaries-extra}
2547 \strut
2548 \cmd{makeindex}
2549 \gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}}
2550 \strut
2551 \ics{glssetcategoryattribute}\marg{general}\marg{dualindex}\marg{true}
2552 \cs{glssetcategoryattribute}\marg{symbol}\marg{dualindex}\marg{true}
2553 \cs{glssetcategoryattribute}\marg{abbreviation}\marg{dualindex}\marg{true}
2554 \strut
2555 \cs{glssetcategoryattribute}\marg{general}\marg{indexname}\marg{hyperbf}
2556 \cs{glssetcategoryattribute}\marg{symbol}\marg{indexname}\marg{hyperbf}
2557 \cs{glssetcategoryattribute}\marg{abbreviation}\marg{indexname}\marg{hyperbf}
2558 \strut
2559 \cmd{begin}\marg{document}
2560 \cmd{chapter}\marg{Example}
2561 \cs{gls}\marg{bird}, \cs{gls}\marg{html}, \idx{mshiftchar}\cs{gls}\marg{v}\idx{mshiftchar} and \cs{glspl}\marg{goose}.
2562 \strut
2563 \cs{printunsrtglossaries}
2564 \cmd{printindex}
2565 \cmd{end}\marg{document}
2566 \end{codeenv}
2567 If the document is called \filefmt{myDoc.tex} then the document
2568 build is:
2569 \begin{verbatim}
2570 pdflatex myDoc
2571 bib2gls myDoc
2572 pdflatex myDoc
2573 makeindex myDoc.idx
2574 pdflatex myDoc
2575 \end{verbatim}
2576 This requires an additional \LaTeX\ call between \bibgls\ and
2577 \idx{makeindex} since the entries must be defined before they can be
2578 indexed (and they can't be defined until \bibgls\ creates the
2579 associated \ext{glstex} files).
2580
2581 Note that this method will use the \field{sort} value obtained by \bibgls\
2582 as the \meta{sort} part within
2583 \code{\cs{index}\marg{\meta{sort}@\meta{actual}}}.
2584 Be careful if you use \idx{makeindex} as this can result in Unicode
2585 characters appearing in the sort value, which \idx{makeindex}
2586 doesn't support.
2587 The \meta{actual} part is given by
2588 \code{\ics{glsentryname}\margm{label}}.
2589 (You can change the \meta{sort} and \meta{actual} parts by
2590 redefining \ics{glsxtrautoindexassignsort} and
2591 \ics{glsxtrautoindexentry}. See the \sty{glossaries-extra} manual
2592 for further details.)
2593
2594 \section{Security}
2595
2596 \TeX\ Live come with security settings
2597 \texmfcnf{openinany} and \texmfcnf{openoutany} that, respectively,
2598 govern read and write file access (in addition to the operating
2599 system's file permissions). \bibgls\ uses \idx{kpsewhich} to
2600 determine these values and honours them. MikTeX doesn't use these
2601 settings, so if these values are unset, \bibgls\ will default to
2602 \code{a} (any) for \texmfcnf{openinany} and \code{p} (paranoid) for
2603 \texmfcnf{openoutany}.
2604
2605 The only external processes that are run by \bibgls\ are calls to
2606 \idx{kpsewhich} to check the security settings and locate files on
2607 \TeX's path. These are started with Java's \code{ProcessBuilder}
2608 class so there should be no issues with spaces or shell special characters
2609 in the argument. The \commonlongarg{debug} switch will write the process
2610 call in the transcript file and will delimit the argument in the log
2611 with single quote characters for convenience, but the process isn't
2612 actually called in that way.
2613
2614 \bibgls\ creates files with the extension \ext{glstex}, which are
2615 input by \gls{GlsXtrLoadResources} (and therefore by the shortcut
2616 \gls{glsbibdata}). This extension is fixed and is imposed
2617 by both \bibgls\ and \gls{GlsXtrLoadResources}. \bibgls\ also creates
2618 a transcript file with the default extension \ext{glg}. This may be
2619 overridden by the \longarg{log-file} switch, but \bibgls\ always
2620 forbids write access to any file with the following extensions:
2621 \extfmt{tex}, \extfmt{ltx}, \extfmt{sty}, \extfmt{cls},
2622 \extfmt{bib}, \extfmt{dtx}, \extfmt{ins}, \extfmt{def} and
2623 \extfmt{ldf}.
2624
2625 \section{Localisation}
2626 \label{sec:lang.xml}
2627
2628 The messages produced by \bibgls\ are fetched from a resource file
2629 called \metafilefmt{bib2gls-}{lang}{.xml}, where \meta{lang} is a
2630 valid \idx{IETF} language tag.
2631
2632 The appropriate file is searched for in the following order, where
2633 \meta{locale} is the \gls{Java-locale} or the value supplied
2634 by the \commonlongarg{locale} switch:
2635 \begin{enumerate}
2636 \item \meta{lang} exactly matches \meta{locale}.
2637 For example, my locale is \code{en-GB}, so \bibgls\ will first search
2638 for \filefmt{bib2gls-en-GB.xml}. This file doesn't exist, so it will
2639 try again.
2640
2641 \item If \meta{locale} has an associated script, the
2642 next try is with \meta{lang} set to \meta{lang
2643 code}\code{-}\meta{script} where \meta{lang code} is the two
2644 letter ISO language code and \meta{script} is the script code.
2645 For example, if \meta{locale} is \code{sr-RS-Latn}
2646 then \bibgls\ will search for \filefmt{bib2gls-sr-Latn.xml} if
2647 \filefmt{bib2gls-sr-RS-Latn.xml} doesn't exist.
2648
2649 \item The final attempt is with \meta{lang} set to just the two
2650 letter ISO language code. For example, \filefmt{bib2gls-sr.xml}.
2651 \end{enumerate}
2652
2653 If there is no match, \bibgls\ will fallback on the English resource file
2654 \file{bib2gls-en.xml}.
2655 (Currently only \file{bib2gls-en.xml} exists as my language skills aren't up
2656 to translating it. Any volunteers who want to provide other language
2657 resource files would be much appreciated.)
2658
2659 In addition to the main language file, it's possible to have
2660 supplementary files that provide text that matches the
2661 \gls{resource-locale}. These are in files called
2662 \metafilefmt{bib2gls-extra-}{lang}{.xml}, which has the same format
2663 as \metafilefmt{bib2gls-}{lang}{.xml}. These supplementary files
2664 will be loaded automatically if they exist and if you have
2665 \styfmt{glossaries-extra} v1.51+ (which will save a list of all
2666 tracked languages for the document).
2667
2668 Note that if you use the \csopt[true]{loc-prefix} option, the
2669 textual labels (\qt{Page} and \qt{Pages} in English) will be
2670 first be attempted from the supplementary file with the tags
2671 \code{tag.\meta{lang}.page} and \code{tag.\meta{lang}.pages}
2672 (where \meta{lang} is the language code) and then, if not
2673 found, from the main resource file using the tags \code{tag.page}
2674 and \code{tag.pages}. In the event that the loaded resource file
2675 doesn't match the document language and there's no supplementary
2676 file, you will have to manually set
2677 the correct translation (in English, this would be
2678 \csopt[Page\dcomma Pages]{loc-prefix}). The default definition of
2679 \gls!{bibglspassim} is also obtained from the resource file in a
2680 similar manner.
2681
2682 There are also keys in the resource file to assist case-conversion.
2683 Currently, there's only support for the Dutch \qt{IJ} case.
2684
2685 \section{Conditional Document Build}
2686
2687 If you are using a document build method that tries to determine
2688 whether or not \bibgls\ should be run, you can find the information
2689 by searching the \iext{aux} file for instances of
2690 \nosecdef{glsxtr@resource}
2691 Each instance corresponds to an instance of \gls{GlsXtrLoadResources} (or \gls{glsbibdata})
2692 where \meta{filename} is the base name of the \iext{glstex} file
2693 that \bibgls\ needs to create for this resource set. If the
2694 \meta{options} part is missing the \csopt{src} option, then
2695 \meta{filename} also indicates the base name for the \iext{bib} file.
2696 In the case of \gls{glsbibdata}, the \csopt{src} option is
2697 automatically set to the mandatory argument.
2698
2699 So the simplest check to determine if \bibgls\ needs to be run is to test
2700 if the \iext{aux} file contains \gls{glsxtr@resource}. For
2701 example, with \idx{arara} version 4.0:
2702 \begin{codeenv}
2703 \% arara: bib2gls if found("aux", "glsxtr@resource")
2704 \end{codeenv}
2705 A sophisticated method could check if
2706 \meta{filename}\ext{glstex} is missing or is older than the document
2707 \ext{tex} file for each instance of \gls{glsxtr@resource} found in
2708 the \ext{aux} file.
2709
2710 It might also be possible, although far more complex, to
2711 parse the \meta{options} part in each instance of \gls{glsxtr@resource}
2712 for \csopt{src} and determine if the corresponding \ext{bib} file or
2713 files are newer than the \ext{tex} file.
2714
2715 It's not possible to determine if the \glspl{locationlist} require
2716 updating, just as it's not possible to do this for the
2717 \idx{toc}, list of figures, list of tables etc. (Or, if it could
2718 be implemented, the required code would make the document build far
2719 more complicated.)
2720
2721 In general, the basic algorithm is:
2722 \begin{enumerate}
2723 \item Run \LaTeX\ (or PDF\LaTeX\ etc).
2724
2725 \item If \gls{glsxtr@resource} is found in the \ext{aux} file then:
2726
2727 \begin{enumerate}
2728 \item run \bibgls;
2729 \item run \LaTeX\ (or PDF\LaTeX\ etc).
2730 \end{enumerate}
2731
2732 \item If \ics{@istfilename} is found in the \ext{aux} file then:
2733
2734 \begin{enumerate}
2735 \item run \idx{makeglossaries} (or \idx{makeglossaries-lite});
2736 \item run \LaTeX\ (or PDF\LaTeX\ etc).
2737 \end{enumerate}
2738
2739 \end{enumerate}
2740 This allows for the \styopt[alsoindex]{record} package option. See
2741 also
2742 \href{https://www.dickimaw-books.com/latex/buildglossaries}{\qt{Incorporating
2743 \idx[hyper=false,noindex]{makeglossaries} or
2744 \idx[hyper=false,noindex]{makeglossaries-lite} or \bibgls\ into
2745 the document build}}~\cite{buildglossaries}.
2746
2747 \section{Manual Installation}
2748
2749 In general it's best to install \bibgls\ via your \TeX\ package manager.
2750 However, if you are unable to do this or if you are testing a development version,
2751 you can install manually using the instructions below.
2752 Replace \meta{TEXMF} with the path to your local or home TEXMF tree
2753 (for example, \filefmt{\glstildechar/texmf}).
2754
2755 Copy the files provided to the following locations:
2756 \begin{itemize}
2757 \item \meta{TEXMF}\filefmt{/scripts/bib2gls/bib2gls.jar}
2758 (Java application.)
2759 \item \meta{TEXMF}\filefmt{/scripts/bib2gls/convertgls2bib.jar}
2760 (Java application.)
2761 \item \meta{TEXMF}\filefmt{/scripts/bib2gls/datatool2bib.jar}
2762 (Java application.)
2763 \item \meta{TEXMF}\filefmt{/scripts/bib2gls/bibglscommon.jar}
2764 (Java library.)
2765 \item \meta{TEXMF}\filefmt{/scripts/bib2gls/texparserlib.jar}
2766 (Java library.)
2767 \item \meta{TEXMF}\filefmt{/scripts/bib2gls/resources/bib2gls-en.xml}
2768 (English resource file.)
2769 \item \meta{TEXMF}\filefmt{/scripts/bib2gls/resources/bib2gls-extra-en.xml}
2770 (Extra English resource file.)
2771 \item \meta{TEXMF}\filefmt{/scripts/bib2gls/resources/bib2gls-extra-nl.xml}
2772 (Extra Dutch resource file.)
2773 \item \meta{TEXMF}\filefmt{/doc/support/bib2gls/bib2gls.pdf}
2774 (This document.)
2775 \item \meta{TEXMF}\filefmt{/doc/support/bib2gls/bib2gls-begin.pdf}
2776 (Introductory guide.)
2777 \end{itemize}
2778 If you use the Unix \appfmt{man} command, copy the
2779 \filefmt{bib2gls.1} and \filefmt{convertgls2bib.1} files to the
2780 appropriate location.
2781
2782 If you are using a Unix-like system, there are also bash scripts
2783 provided called \file{bib2gls.sh}, \file{convertgls2bib.sh} and \file{datatool2bib.sh}.
2784 Either copy them directly to somewhere on your path without the \iext{sh}
2785 extension, for example:
2786 \begin{verbatim}
2787 cp bib2gls.sh ~/bin/bib2gls
2788 cp convertgls2bib.sh ~/bin/convertgls2bib
2789 cp datatool2bib.sh ~/bin/datatool2bib
2790 \end{verbatim}
2791 or copy the files to
2792 \meta{TEXMF}\filefmt{/scripts/bib2gls/} and create a
2793 symbolic link to them called just \filefmt{bib2gls},
2794 \filefmt{convertgls2bib} and \filefmt{datatool2bib} from somewhere on
2795 your path, for example:
2796 \begin{verbatim}
2797 cp bib2gls.sh ~/texmf/scripts/bib2gls/
2798 cp convertgls2bib.sh ~/texmf/scripts/bib2gls/
2799 cp datatool2bib.sh ~/texmf/scripts/bib2gls/
2800 cd ~/bin
2801 ln -s ~/texmf/scripts/bib2gls/bib2gls.sh bib2gls
2802 ln -s ~/texmf/scripts/bib2gls/convertgls2bib.sh convertgls2bib
2803 ln -s ~/texmf/scripts/bib2gls/datatool2bib.sh datatool2bib
2804 \end{verbatim}
2805 The \file{texparserlib.jar} file isn't an application but is a
2806 library used by both \file{bib2gls.jar} and
2807 \file{convertgls2bib.jar}, and so needs to be in the same class path.
2808 (The library is in a separate
2809 \href{https://github.com/nlct/texparser}{GitHub
2810 repository}~\cite{texparser} as it's
2811 also used by some of my other applications.)
2812
2813 Windows users can create a \iext{bat} file that works in a
2814 similar way to the bash scripts. To do this, create a file called
2815 \file{bib2gls.bat} that contains the following:
2816 \begin{verbatim}
2817 @ECHO OFF
2818 FOR /F "tokens=*" %%I IN ('kpsewhich --progname=bib2gls --format=texmfscripts
2819 bib2gls.jar') DO SET JARPATH=%%I
2820 java -jar "%JARPATH%" %*
2821 \end{verbatim}
2822 Save this file to somewhere on your system's path.
2823 (Similarly for \filefmt{convertgls2bib} and \filefmt{datatool2bib}.) Note that \TeX\
2824 distributions for Windows usually convert \iext{jar} files to
2825 executables.
2826
2827 You may need to refresh \TeX's database to ensure that
2828 \idx{kpsewhich} can find the \iext{jar} files.
2829 To test that the application has been successfully installed, open a
2830 command prompt or terminal and run the following command:
2831 \begin{verbatim}
2832 bib2gls --version
2833 convertgls2bib --version
2834 datatool2bib --version
2835 \end{verbatim}
2836 This should display the version information for both applications.
2837
2838 \chapter{\texorpdfstring{\TeX}{TeX}\ Parser Library}
2839 \label{sec:texparserlib}
2840
2841 The \bibgls\ application requires the \TeX\ Parser Library
2842 \file{texparserlib.jar}\footnote{\url{https://github.com/nlct/texparser}}
2843 which is used to parse the \iext{aux} and \iext{bib} files.
2844
2845 With the \longarg{interpret} switch on (default), this library is
2846 also used to interpret the sort value when it contains a backslash
2847 \idx{escchar} or a tilde \idx{nbspchar} or a dollar symbol
2848 \idx{mshiftchar} or braces \idx{bgroupchar} \idx{egroupchar}
2849 (and when the \csopt{sort} option is not
2850 \optfmt{unsrt} or \optfmt{none} or \optfmt{use}).\footnote{The other
2851 special characters are omitted from the check: the comment symbol
2852 \idx{commentchar} is best avoided in field values, the subscript and
2853 superscript characters \idx{sbchar} and \idx{spchar} should
2854 either be encapsulated by \idx{mshiftchar} or by \cs{ensuremath}, which
2855 will be picked up by the check for \idx{mshiftchar} or
2856 \idx{escchar}, and the other special characters would
2857 indicate something too complex for the interpreter to handle.}
2858
2859 The other cases that the interpreter is used for are:
2860 \begin{itemize}
2861 \item when \csopt{set-widest} is used to determine the width of
2862 the \field{name} field;
2863 \item if \csopt{labelify} or \csopt{labelify-list} are set the
2864 identified field values are first interpreted (if they contain
2865 \idx{escchar} \idx{bgroupchar} \idx{egroupchar}
2866 \idx{nbspchar} or \idx{mshiftchar}) before being converted to labels;
2867 \item if \csopt[true]{interpret-label-fields} is set and the
2868 \field{parent}, \field{category}, \field{type}, \field{group},
2869 \field{seealso} or \field{alias} fields contain \idx{escchar}
2870 or \idx{bgroupchar} or \idx{egroupchar} the interpreter is used
2871 since these fields must be just a label
2872 (other special characters aren't checked as they won't expand to
2873 characters allowed in a label).
2874 \end{itemize}
2875
2876 Information in the \ext{aux} file is parsed for specific commands
2877 but the arguments of those commands are not interpreted so, for
2878 example, UTF-8 characters that occur in any resource options will
2879 need to be detokenized when using \sty{inputenc} to prevent
2880 expansion when they are written to the \ext{aux} file. (In some
2881 options, such as \csopt{sort-rule}, you can use \cs{glshex}\meta{hex}
2882 syntax to specify a UTF-8 character.) Note that newer \LaTeX\
2883 kernels have better support for UTF-8 and this issue is less likely
2884 to occur.
2885
2886 The \longarg{no-interpret} switch will turn off the interpreter, but
2887 the library will still be used to parse the \ext{aux} and \ext{bib}
2888 files. Note that the \field{see} field doesn't use the interpreter
2889 with \csopt[true]{interpret-label-fields} as
2890 it may legitimately contain \LaTeX\ code in the optional tag part
2891 (such as \cs{seealsoname} or \cs{alsoname}).
2892
2893 The parser has a different concept of expansion to \TeX\
2894 and will expand some things that aren't expanded by \LaTeX\
2895 (such as \ics{MakeUppercase} and \ics{char}) and won't expand other commands
2896 that would be expanded by \LaTeX\ (such as commands defined
2897 in terms of complicated internals).
2898
2899 If you get a \idx{StackOverflowError} while a field is being
2900 interpreted (with a long stack trace that contains repeated file names and
2901 line numbers) then it's likely you have an infinite \idx{loop}. For
2902 example, this can be triggered if a field contains \csfmt{foo} that
2903 has been defined as:
2904 \begin{codeenv}
2905 \cs{def}\cmd{foo}\marg{\cmd{foo}}
2906 \end{codeenv}
2907 This will obviously also cause an error in the \LaTeX\ document as
2908 well (unless the document has a different definition that doesn't
2909 have this unbounded recursion).
2910
2911 The \file{texparserlib.jar} library is not a \TeX\ engine and there
2912 are plenty of situations where it doesn't work. In particular, with
2913 \bibgls, it's being used in a fragmented context without knowing
2914 most of the packages used by the document or any custom commands or
2915 environments provided within the document.
2916
2917 \bibgls\ can detect from the log file a small
2918 number of packages that the parser recognises. Note that in
2919 some cases there's only very limited support. For example,
2920 \isty{siunitx}'s \ics{si} and \ics{unit} commands are recognised but other
2921 commands from that package aren't. See
2922 \longargpageref{list-known-packages} for further details.
2923
2924 Since the parser doesn't have a full set of commands available
2925 within the \LaTeX\ document, when it encounters \ics{renewcommand} it
2926 won't check if the command is undefined. If the command isn't
2927 defined, it will simply behave like \cs{newcommand}. Whereas
2928 with \ics{providecommand} the parser will only define the command
2929 if it's unrecognised.
2930
2931 The interpreter has its own internal implementation of the
2932 glossary-related commands listed in \tableref{tab:bibglsdefs}. These
2933 may be overridden by custom packages provided with the
2934 \longarg{custom-packages} switch. Note that commands that reference
2935 an entry, such as \cs{glsentryname}, aren't guaranteed to work
2936 across \iglspl{resourceset} and will only be able to look up field
2937 values that are known to \bibgls. (For example, the \field{name}
2938 field for abbreviations is typically set by the associated
2939 abbreviation style, which isn't available to \bibgls.)
2940
2941 \begin{table}[htbp]
2942 \caption{Glossary-Related Commands Implemented by the \bibgls\ Interpreter}
2943 \label{tab:bibglsdefs}
2944 \setlength{\tabcolsep}{4pt}%
2945 \centering
2946 \tablelistcs{3}{glsxtrprovidecommand,bibglsuppercase,bibglslowercase,bibglsfirstuc,%
2947 bibglstitlecase,GlsXtrEnableInitialTagging,bibglscontributorlist,%
2948 bibglshyperlink,glshyperlink,bibglscontributor,bibglsdatetime,%
2949 bibglsdate,bibglstime,glsentryname,glsentrytext,glsentryshort,%
2950 glsentrylong,glsentryfirst,glsentrysymbol,glsentryuseri,%
2951 glsentryuserii,glsentryuseriii,glsentryuseriv,glsentryuserv,%
2952 glsentryuservi,glsentryplural,glsentryfirstplural,glsentryshortpl,%
2953 glsentrylongpl,glsentrysymbolplural,Glsentryname,Glsentrytext,%
2954 Glsentryshort,Glsentrylong,Glsentryfirst,Glsentrysymbol,%
2955 Glsentryuseri,Glsentryuserii,Glsentryuseriii,Glsentryuseriv,%
2956 Glsentryuserv,Glsentryuservi,Glsentryplural,Glsentryfirstplural,Glsentryshortpl,%
2957 Glsentrylongpl,Glsentrysymbolplural,bibglshashchar,bibglsunderscorechar,%
2958 bibglsdollarchar,bibglsampersandchar,bibglscircumchar,glsbackslash,glstildechar,glsopenbrace,glsclosebrace,glspercentchar,%
2959 glsxtrusefield,Glsxtrusefield,GLSxtrusefield,glsentrytitlecase,%
2960 glsxtrhiernamesep,glsxtrhiername,Glsxtrhiername,GlsXtrhiername,%
2961 GLSxtrhiername,GLSXTRhiername}
2962 \end{table}
2963
2964 If a command isn't recognised, you can provide it in the
2965 \atentry{preamble} and use \ics{char} to map a symbol to the most
2966 appropriate Unicode character. For example, suppose your document
2967 loads a package that provides symbols for use on maps, such as
2968 \csfmt{Harbour}, \csfmt{Battlefield} and \csfmt{Stadium}, then you
2969 can provide versions of these commands just for \bibgls's
2970 use:\footnote{These commands won't work with PDF\LaTeX, as the
2971 \cs{char} values are too large, but they're fine for \bibgls.}
2972 \begin{codeenv}
2973 \atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{Harbour}}\marg{\charhex{2693}}
2974 \cs{providecommand}\marg{\cmd{Battlefield}}\marg{\charhex{2694}}
2975 \cs{providecommand}\marg{\cmd{Stadium}}\marg{\charhex{26BD}}}}
2976 \end{codeenv}
2977 Since these use \cs{providecommand}, they won't overwrite the
2978 document's version (provided these commands have been defined before
2979 \gls!{GlsXtrLoadResources}). Alternatively, you can instruct \bibgls\
2980 to not write the \atentry{preamble} contents to the resource file
2981 using \csopt[false]{write-preamble}. Now you can either sort these
2982 symbols by
2983 their Unicode values (\csopt[letter-case]{sort}) or provide a custom
2984 rule that recognises these Unicode characters (for example,
2985 \csopt[custom]{sort},
2986 \csopt[\cs{glshex}2694 \string< \cs{glshex}2693 \string< \cs{glshex}26BD]{sort-rule}).
2987
2988 Another approach is to use \ics{IfTeXParserLib}, which is defined by
2989 the \texparserlib\ to expand to its first argument. The
2990 \sty{glossaries-extra-bib2gls} package provides a definition that
2991 expands to its second argument, so that command may be used to
2992 provide alternative code. For example:
2993 \begin{codeenv}
2994 \atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{Ord}}[1]\marg{\comment{}
2995 \cs{IfTeXParserLib}
2996 \marg{\ics{bibglspaddigits}\marg{2}\marg{\idx{param}1}}\comment{interpreter}
2997 \marg{\cs{MakeUppercase}\marg{\cmd{romannumeral} \idx{param}1}}\comment{document}
2998 }}}
2999 \atentry{index}\marg{John-IV,
3000 \field{name}=\marg{John\idx{nbspchar}\cmd{Ord}\marg{4}}
3001 }
3002 \atentry{index}\marg{John-VI,
3003 \field{name}=\marg{John\idx{nbspchar}\cmd{Ord}\marg{6}}
3004 }
3005 \atentry{index}\marg{John-IX,
3006 \field{name}=\marg{John\idx{nbspchar}\cmd{Ord}\marg{9}}
3007 }
3008 \atentry{index}\marg{John-XII,
3009 \field{name}=\marg{John\idx{nbspchar}\cmd{Ord}\marg{12}}
3010 }
3011 \end{codeenv}
3012 The sort values for these entries will be: \qt{John 04}, \qt{John
3013 06}, \qt{John 09} and \qt{John 12}, but in the document text they
3014 will be typeset as \qt{John~IV}, \qt{John~VI}, \qt{John~IX} and
3015 \qt{John~XII}. Note that \ics{bibglspaddigits} is only recognised by
3016 the \bibgls\ interpreter. Alternatively, you can use the
3017 \csopt{sort-number-pad} option to pad the numbers (or use
3018 \ics{dtlpadleadingzeros} which is also recognised by the
3019 \texparserlib\ and \sty{datatool-base} v3.0+).
3020
3021 There is a similar command with reversed syntax \ics{IfNotBibGls},
3022 which is defined by \sty{glossaries-extra-bib2gls} to expand to its
3023 first argument. The \bibgls\ interpreter defines this command to
3024 expand to its second argument.
3025
3026 \TeX\ syntax can be quite complicated and, in some cases, far too
3027 complicated for simple \idxpl!{regex}. The \texparserlib\ performs
3028 better than a simple pattern match, and that's the purpose of
3029 \file{texparserlib.jar} and why it's used by \bibgls\ (and by
3030 \idx!{convertgls2bib}). When the \commonlongarg{debug} mode is on, any
3031 warnings or errors triggered by the interpreter will be written to
3032 the transcript prefixed with \code{texparserlib:} (the results of
3033 the conversions will be included in the transcript as informational
3034 messages prefixed with \code{texparserlib:} even with
3035 \commonlongarg{no-debug}).
3036
3037 For example, suppose the \ext{bib} file includes:
3038 \begin{codeenv}
3039 \atentry{preamble}\marg{
3040 \qtdelim{\cs{providecommand}\marg{\cmd{mtx}}[1]\marg{\cs{boldsymbol}\marg{\idx{param}1}}
3041 \cs{providecommand}\marg{\cmd{set}}[1]\marg{\ics{mathcal}\marg{\idx{param}1}}
3042 \cs{providecommand}\marg{\cmd{card}}[1]\marg{|\cmd{set}\marg{\idx{param}1}|}
3043 \cs{providecommand}\marg{\cmd{imaginary}}\marg{i}}}
3044 \strut
3045 \atentry{entry}\marg{M,
3046 \field{name}=\marg{\marg{}\idx{mshiftchar}\cmd{mtx}\marg{M}\idx{mshiftchar}},
3047 \field{text}=\marg{\cmd{mtx}\marg{M}},
3048 \field{description}=\marg{a matrix}
3049 }
3050 \strut
3051 \atentry{entry}\marg{v,
3052 \field{name}=\marg{\marg{}\idx{mshiftchar}\cs{vec}\marg{v}\idx{mshiftchar}},
3053 \field{text}=\marg{\cs{vec}\marg{v}},
3054 \field{description}=\marg{a vector}
3055 }
3056 \strut
3057 \atentry{entry}\marg{S,
3058 \field{name}=\marg{\marg{}\idx{mshiftchar}\cmd{set}\marg{S}\idx{mshiftchar}},
3059 \field{text}=\marg{\cmd{set}\marg{S}},
3060 \field{description}=\marg{a set}
3061 }
3062 \strut
3063 \atentry{entry}\marg{card,
3064 \field{name}=\marg{\marg{}\idx{mshiftchar}\cmd{card}\marg{S}\idx{mshiftchar}},
3065 \field{text}=\marg{\cmd{card}\marg{S}},
3066 \field{description}=\marg{the cardinality of the set \idx{mshiftchar}\cmd{set}\marg{S}\idx{mshiftchar}}
3067 }
3068 \strut
3069 \atentry{entry}\marg{i,
3070 \field{name}=\marg{\marg{}\idx{mshiftchar}\cmd{imaginary}\idx{mshiftchar}},
3071 \field{text}=\marg{\cmd{imaginary}},
3072 \field{description}=\marg{square root of minus one (\idx{mshiftchar}\cmd{sqrt}\marg{-1}\idx{mshiftchar})}
3073 }
3074 \end{codeenv}
3075 (The empty group at the start of the \field{name} fields
3076 protects against the possibility that the \catattr{glossname}
3077 category attribute might be set to \optfmt{firstuc}, which
3078 automatically converts the first letter of the name to
3079 \idx{uppercase} when displaying the glossary. See also
3080 \longarg{mfirstuc-protection} and
3081 \longarg{mfirstuc-math-protection}.)
3082
3083 None of these entries have a \field{sort} field so the \field{name}
3084 is used (see \sectionref{sec:fallbacks}). If the \gls{entrytype} had
3085 been \atentry{symbol} instead, the fallback would be the entry's
3086 label. This means that with \atentry{symbol} instead of
3087 \atentry{entry}, and the default \csopt[sort]{sort-field}, and with
3088 \csopt[letter-case]{sort}, these entries will be defined in the
3089 order: \code{M}, \code{S}, \code{card}, \code{i}, \code{v} (since
3090 this is the case-sensitive letter order of the labels) whereas with
3091 \csopt[letter-nocase]{sort-field}, the order will be: \code{card},
3092 \code{i}, \code{M}, \code{S}, \code{v} (since this is the
3093 case-insensitive letter order of the labels).
3094
3095 However, with \atentry{entry}, the fallback field will be taken from
3096 the \field{name} which in the above example contains \TeX\ code, so
3097 \bibgls\ will use \file{texparserlib.jar} to interpret this code.
3098 The library has several different ways of writing the processed
3099 code. For simplicity, \bibgls\ uses the library's HTML output and
3100 then strips the HTML markup and trims any leading or trailing
3101 spaces. The library method that writes \idx{non-ASCII} characters
3102 using \qtt{\&x\meta{hex};} markup is overridden by \bibgls\ to just
3103 write the actual Unicode character, which means that the letter-based
3104 sorting options will sort according to the integer value \meta{hex}
3105 rather than the string \qtt{\&x\meta{hex};}.
3106
3107 The interpreter is first passed the code provided with
3108 \atentry{preamble}:
3109 \begin{codeenv}
3110 \cs{providecommand}\marg{\cmd{mtx}}[1]\marg{\cs{boldsymbol}\marg{\idx{param}1}}
3111 \cs{providecommand}\marg{\cmd{set}}[1]\marg{\cs{mathcal}\marg{\idx{param}1}}
3112 \cs{providecommand}\marg{\cmd{card}}[1]\marg{|\cmd{set}\marg{\idx{param}1}|}
3113 \cs{providecommand}\marg{\cmd{imaginary}}\marg{i}
3114 \end{codeenv}
3115 (unless \csopt[false]{interpret-preamble}).
3116 This means that the provided commands are now recognised by the
3117 interpreter when it has to parse the fields later.
3118
3119 In the case of the \code{M} entry in the example above, the
3120 code that's passed to the interpreter is:
3121 \begin{verbatim}
3122 {}$\mtx{M}$
3123 \end{verbatim}
3124 The transcript (\iext{glg}) file will show the results of the
3125 conversion:
3126 \begin{verbatim}
3127 texparserlib: {}$\mtx{M}$ -> M
3128 \end{verbatim}
3129 So the \field{sort} value for this entry is set to \qtt{M}. The font
3130 change (caused by math-mode and \ics{boldsymbol}) has been
3131 ignored. The sort value therefore consists of a single Unicode
3132 character \hex{4D} (Latin \idx!{uppercase} letter \qtt{M}, decimal value 77).
3133
3134 For the \code{v} entry, the code is:
3135 \begin{verbatim}
3136 {}$\vec{v}$
3137 \end{verbatim}
3138 The transcript shows:
3139 \begin{alltt}
3140 texparserlib: \marg{}\$\ics{vec}\marg{v}\$ -> \usebox\varrow
3141 \end{alltt}
3142 So the \field{sort} value for this entry is set to \qtt{\usebox\varrow},
3143 which consists of two Unicode characters \hex{76}
3144 (Latin \idx!{lowercase} letter \qtt{v}, decimal value 118) and
3145 \hex{20D7} (combining right arrow above, decimal value 8407).
3146
3147 For the \code{set} entry, the code is:
3148 \begin{verbatim}
3149 {}$\set{S}$
3150 \end{verbatim}
3151 The transcript shows:
3152 \begin{verbatim}
3153 texparserlib: {}$\set{S}$ -> S
3154 \end{verbatim}
3155 So the \field{sort} value for this entry is set to \qtt{S} (again
3156 ignoring the font change). This consists of a single Unicode
3157 character \hex{53} (Latin \idx!{uppercase} letter \qtt{S}, decimal value~83).
3158
3159 For the \code{card} entry, the code is:
3160 \begin{verbatim}
3161 {}$\card{S}$
3162 \end{verbatim}
3163 The transcript shows:
3164 \begin{verbatim}
3165 texparserlib: {}$\card{S}$ -> |S|
3166 \end{verbatim}
3167 So the \field{sort} value for this entry is set to \qtt{|S|}
3168 (the \textbar\ characters from the definition of \csfmt{card} provided
3169 in \atentry{preamble} have been included, but the
3170 font change has been discarded). In this case the sort value
3171 consists of three Unicode characters \hex{7C} (vertical line, decimal
3172 value 124),
3173 \hex{53} (Latin \idx!{uppercase} letter \qtt{S}, decimal value 83) and
3174 \hex{7C} again.
3175 If \csopt[false]{interpret-preamble} had been used, \csfmt{card}
3176 wouldn't be recognised and would be discarded leaving just \qtt{S}
3177 as the sort value.
3178
3179 (Note that if \ics{vert} is used instead of \textbar\ then it would
3180 be converted into the mathematical operator \hex{2223} and result in
3181 a different order.)
3182
3183 For the \code{i} entry, the code is:
3184 \begin{verbatim}
3185 {}$\imaginary$
3186 \end{verbatim}
3187 The transcript shows:
3188 \begin{verbatim}
3189 texparserlib: {}$\imaginary$ -> i
3190 \end{verbatim}
3191 So the \field{sort} value for this entry is set to \qtt{i}.
3192 If \csopt[false]{interpret-preamble} had been used, \csfmt{imaginary}
3193 wouldn't be recognised and would be discarded, leaving an empty sort
3194 value.
3195
3196 This means that in the case of the default \csopt[sort]{sort-field} with
3197 \csopt[letter-case]{sort}, these entries will be defined in
3198 the order: \code{M} ($\mtx{M}$), \code{S} ($\set{S}$),
3199 \code{i} ($\imaginary$), \code{v} ($\vec{v}$) and
3200 \code{card} ($\card{S}$).
3201 In this case, the entries have been sorted according to
3202 the character codes. If you run \bibgls\ with \commonlongarg{verbose}
3203 the decimal character codes will be included in the transcript.
3204 For this example:
3205 \begin{alltt}
3206 i -> 'i' [105]
3207 card -> '|S|' [124 83 124]
3208 M -> 'M' [77]
3209 S -> 'S' [83]
3210 v -> '\usebox\varrow' [118 8407]
3211 \end{alltt}
3212
3213 The \longarg{group} option (in addition to \commonlongarg{verbose})
3214 will place the letter group in
3215 parentheses before the character code list:
3216 \begin{alltt}
3217 i -> 'i' (i) [105]
3218 card -> '|S|' [124 83 124]
3219 M -> 'M' (M) [77]
3220 S -> 'S' (S) [83]
3221 v -> '\usebox\varrow' (v) [118 8407]
3222 \end{alltt}
3223 (Note that the \code{card} entry doesn't have a letter
3224 group since the vertical bar character isn't considered a
3225 letter.)
3226
3227 If \csopt[letter-nocase]{sort} is used instead then, after conversion
3228 by the interpreter, the sort values will all be changed to
3229 \idx{lowercase}. The order is now: \code{i} ($\imaginary$),
3230 \code{M} ($\mtx{M}$), \code{S} ($\set{S}$),
3231 \code{v} ($\vec{v}$) and \code{card} ($\card{S}$).
3232 The transcript (with \commonlongarg{verbose}) now shows
3233 \begin{alltt}
3234 i -> 'i' [105]
3235 card -> '|s|' [124 115 124]
3236 M -> 'm' [109]
3237 S -> 's' [115]
3238 v -> '\usebox\varrow' [118 8407]
3239 \end{alltt}
3240 With \longarg{group} (in addition to \commonlongarg{verbose})
3241 the letter groups are again included:
3242 \begin{alltt}
3243 i -> 'i' (I) [105]
3244 card -> '|s|' [124 115 124]
3245 M -> 'm' (M) [109]
3246 S -> 's' (S) [115]
3247 v -> '\usebox\varrow' (V) [118 8407]
3248 \end{alltt}
3249 Note that the letter groups are \idx{uppercase} not \idx{lowercase}.
3250 Again the \code{card} entry doesn't have an associated
3251 letter group.
3252
3253 If a locale-based sort is used, the ordering will follow the
3254 locale's alphabet rules. For example, with \csopt[en]{sort}
3255 (English, no region or variant), the order becomes:
3256 \code{card} ($\card{S}$), \code{i} ($\imaginary$),
3257 \code{M} ($\mtx{M}$), \code{S} ($\set{S}$) and
3258 \code{v} ($\vec{v}$). The transcript (with \commonlongarg{verbose})
3259 shows the collation keys instead:
3260 \begin{alltt}
3261 i -> 'i' [0 92 0 0 0 0]
3262 card -> '|S|' [0 66 0 102 0 66 0 0 0 0]
3263 M -> 'M' [0 96 0 0 0 0]
3264 S -> 'S' [0 102 0 0 0 0]
3265 v -> '\usebox\varrow' [0 105 0 0 0 0]
3266 \end{alltt}
3267 Again the addition of the \longarg{group} switch will show
3268 the letter groups.\footnote{For more information on collation keys see the
3269 \href{http://docs.oracle.com/javase/8/docs/api/java/text/CollationKey.html}{CollationKey}
3270 class in Java's API~\cite{collationkey}.}
3271
3272 Suppose I add a new symbol to my \ext{bib} file:
3273 \begin{codeenv}
3274 \atentry{symbol}\marg{angstrom,
3275 \field{name}=\marg{\ics{AA}},
3276 \field{description}=\marg{\cs{AA} ngstr\ics{umlaut}om}
3277 }
3278 \end{codeenv}
3279 and I also use this entry in the document.\footnote{A better method
3280 is to use \sty{siunitx} instead.} Then with
3281 \csopt[en]{sort}, the order is: \code{card} ($\card{S}$),
3282 \code{angstrom} (\AA), \code{i} ($\imaginary$), \code{M}
3283 ($\mtx{M}$), \code{S} ($\set{S}$), and \code{v} ($\vec{v}$).
3284 The \longarg{group} switch shows that the \code{angstrom} entry
3285 (\AA) has been placed in the \qt{A} letter group.
3286
3287 However, if I change the locale to \csopt[sv]{sort}, the
3288 \code{angstrom} entry is moved to the end of the list and the
3289 \longarg{group} switch shows that it's been placed in the \qt{\AA}
3290 letter group.
3291
3292 \label{locale.provider}If you are using Java~8, you can set the
3293 \code{java.locale.providers} property~\cite{javacldr} to use
3294 the \idx{CLDR} \idx{localeprovider}, which has more extensive
3295 support for locales than the native \idx{JRE}. For example:
3296 \begin{verbatim}
3297 java.locale.providers=CLDR,JRE
3298 \end{verbatim}
3299 This should be enabled by default for Java~9. The property
3300 can either be set in a script that runs \bibgls, for example,
3301 \begin{verbatim}
3302 java -Djava.locale.providers=CLDR,JRE,SPI -jar "$jarpath" "$@"
3303 \end{verbatim}
3304 (where \verb|$jarpath| is the path to the \file{bib2gls.jar}
3305 file and \verb|"$@"| is the argument list) or you can set the
3306 property as the default for all Java applications by adding
3307 the definition to the \code{JAVA\_TOOL\_OPTIONS} environment
3308 variable~\cite{javaoptions}.
3309 For example, in a bash shell:
3310 \begin{verbatim}
3311 export JAVA_TOOL_OPTIONS='-Djava.locale.providers=CLDR,JRE,SPI'
3312 \end{verbatim}
3313 or in Windows:
3314 \begin{verbatim}
3315 set JAVA_TOOL_OPTIONS=-Djava.locale.providers=CLDR,JRE,SPI
3316 \end{verbatim}
3317 Note that newer versions of Java support \idx{CLDR} by
3318 default, and the \idx{JRE} synonym for the \code{COMPAT} provider is now
3319 deprecated.\footnote{https://www.oracle.com/java/technologies/javase/jdk21-suported-locales.html}
3320
3321 \chapter{Command Line Options}
3322 \label{sec:switches}
3323 \setsecdepth{1}
3324
3325 The syntax of \bibgls\ is:
3326 \begin{alltt}
3327 bib2gls \oargm{options} \meta{filename}
3328 \end{alltt}
3329 where \meta{filename} is the name of the \ext{aux} file. (The
3330 extension may be omitted.) Only one \meta{filename} is permitted.
3331 Available options are listed below.
3332
3333 If you are using an automated build system that makes it difficult
3334 to change the command line options and you have at least version
3335 1.54 of \sty{glossaries-extra} and at least version 4.0 of \bibgls,
3336 then most (but not all) switches can be specified within the
3337 argument of
3338 \nosecformatdef{BibGlsOptions}
3339 This command may be placed anywhere within the preamble, but the
3340 options will always be processed before the resource commands. This
3341 command may be used multiple times.
3342 Unlike the resource options, which are local to the resource set, the options
3343 described here are global and are applied to all resource sets,
3344 where applicable.
3345 For example:
3346 \begin{codeenv}
3347 \gls{BibGlsOptions}\marg{replace-quotes=true}
3348 \gls{GlsXtrLoadResources}
3349 \gls{BibGlsOptions}\marg{collapse-same-location-range=true}
3350 \end{codeenv}
3351 This is equivalent to:
3352 \begin{codeenv}
3353 \gls{BibGlsOptions}\marg{replace-quotes=true,collapse-same-location-range=true}
3354 \gls{GlsXtrLoadResources}
3355 \end{codeenv}
3356 The \meta{options} list should be a \keyvallist\ where the \meta{key}
3357 is the same as the long switch without the preceding
3358 \code{\longswitch} and any \code{\longswitch no-\meta{option}} should
3359 be specified as \code{\meta{option}=false} within
3360 \gls{BibGlsOptions}.
3361 For example, to set global options via the command line:
3362 \begin{verbatim}
3363 bib2gls --group --no-replace-quotes myDoc
3364 \end{verbatim}
3365 Alternatively, the document may contain:
3366 \begin{codeenv}
3367 \gls{BibGlsOptions}\marg{group=true,replace-quotes=false}
3368 \end{codeenv}
3369 You can omit the value if it is \code{true}, so the above can also
3370 be written:
3371 \begin{codeenv}
3372 \gls{BibGlsOptions}\marg{group,replace-quotes=false}
3373 \end{codeenv}
3374
3375 \begin{important}
3376 Options that must be set before the \ext{log} and \ext{aux} file are read can
3377 only be set via the command line switch.
3378 \end{important}
3379
3380 \section{Common Options}
3381 \label{sec:commonswitches}
3382
3383 These command line switches are common to \bibgls\ and the
3384 supplementary command line conversion tools
3385
3386 \commonarg{help}
3387
3388 Display the help message and quit.
3389 This option cannot be set in \gls{BibGlsOptions}.
3390
3391 \commonarg{version}
3392
3393 Display the version information and quit. As from v2.5, this now
3394 includes the version number of the \file{texparserlib.jar} library.
3395 This option cannot be set in \gls{BibGlsOptions}.
3396
3397 \commonarg{verbose}
3398
3399 Switches on the verbose mode. This writes extra information to the
3400 terminal and transcript file.
3401 This option cannot be set in \gls{BibGlsOptions}.
3402
3403 \commonarg{no-verbose}
3404
3405 Switches off the verbose mode. This is the default behaviour.
3406 Some messages are written to the terminal. To completely suppress
3407 all messages (except errors), switch on the silent mode.
3408 For additional information messages, switch on the verbose mode.
3409 This option cannot be set in \gls{BibGlsOptions}.
3410
3411 \commonarg{quiet}
3412
3413 Suppresses all messages except for errors that would normally be
3414 written to the terminal. Warnings and informational messages are
3415 written to the transcript file, which can be inspected afterwards.
3416 This option cannot be set in \gls{BibGlsOptions}.
3417
3418 \commonarg{silent}
3419
3420 Synonym of \commonlongarg{quiet}.
3421 This option cannot be set in \gls{BibGlsOptions}.
3422
3423 \commonarg{locale}
3424
3425 Specify the preferred \langxml, where \meta{lang} is a valid \idx{IETF} language tag.
3426 This option requires an appropriate \metafilefmt{bib2gls-}{lang}{.xml}
3427 resource file otherwise \bibgls\ will fallback on English.
3428 This also sets the default \gls{document-locale} when the \optfmt{doc}
3429 keyword (in options such as \csopt[doc]{sort}) is
3430 used and the document doesn't have any language support.
3431 Note that the \optfmt{locale} keyword (in options such as \csopt[locale]{sort})
3432 uses the \gls{Java-locale} and is not governed by this switch.
3433 This option cannot be set in \gls{BibGlsOptions}.
3434
3435 If a document doesn't have any locale support or has support
3436 for more than one language then it's best to explicitly set
3437 the required locale in the appropriate \idx{resourceset} using
3438 the \csopt{locale} resource option, to specify the default
3439 \gls{resource-locale}, or set the locale for individual options,
3440 such as \csopt{sort}.
3441
3442 \commonarg{debug}
3443
3444 Sometimes when things go wrong it can be hard to diagnose the problem
3445 from the normal messages. If you report an issue, you may be asked
3446 to switch on debugging mode to help identify a non-reproducible
3447 error and provide the transcript file.
3448
3449 The \commonlongarg{debug} optional value can be used to adjust the level of
3450 debugging information. If \meta{n} is present, it must be a non-negative
3451 integer indicating the debugging mode. If omitted, 1 is assumed. This option
3452 also switches on the verbose mode. A value of 0 is equivalent to
3453 \commonlongarg{no-debug}. This option cannot be set in \gls{BibGlsOptions}.
3454
3455 The value of \meta{n} determines how much extra information is
3456 provided. If \meta{n} is greater than 0 then all \bibgls\ debugging
3457 information is written. The amount of debugging information provided
3458 by the \texparserlib\ is determined by a bitwise operation on
3459 \meta{n}. For example, if \meta{n} is 1 then I/O information is
3460 included. If \meta{n} is 2 then information is included when an
3461 object is popped off a stack. If \meta{n} is 3 then both I/O and
3462 popped information is provided.
3463
3464 Note that messages such as \qt{Can't find language resource} or
3465 about a failed \idx{kpsewhich} call are informational and don't
3466 necessarily mean an error has occurred. Error messages will always
3467 be written to the transcript regardless of the debug or verbose
3468 setting. An error message will start with \qt{Error:~} and a warning
3469 message will start with \qt{Warning:~}. Unknown commands will throw
3470 an exception with a stack trace in debug mode.
3471
3472 \commonarg{debug-mode}
3473
3474 This option is an alternative to \commonlongarg{debug} where the value
3475 of \meta{n} needs to be calculated.
3476 This option cannot be set in \gls{BibGlsOptions}.
3477 Debugging mode requires a
3478 transcript file, which is automatically created with \bibgls, but is
3479 optional for the converter tools (see \sectionref{sec:tex2bib}). The
3480 \meta{setting} is required and should be a comma-separated list of
3481 any of the following keywords.
3482
3483 \begin{itemize}
3484 \item\optfmt{all}: enable all debugging information
3485 (likely to result in a very large transcript file).
3486
3487 \item\optfmt{catcode}: \texparserlib\ category code changes.
3488
3489 \item\optfmt{cs}: \texparserlib\ command definitions.
3490
3491 \item\optfmt{decl}: information about declarations.
3492
3493 \item\optfmt{expansion}: \texparserlib\ expansions
3494 (may result in a large transcript file).
3495
3496 \item\optfmt{expansion-list}: \texparserlib\ stack expansions
3497 (may result in a large transcript file).
3498
3499 \item\optfmt{expansion-once}: \texparserlib\ one-level expansions
3500 (may result in a large transcript file).
3501
3502 \item\optfmt{expansion-once-list}: \texparserlib\ one-level list expansions
3503 (may result in a large transcript file).
3504
3505 \item\optfmt{io}: I/O information, such as opening or closing files
3506 and fetching tokens.
3507
3508 \item\optfmt{popped}: information about objects popped from stacks.
3509
3510 \item\optfmt{process}: \texparserlib\ macro process
3511 (may result in a large transcript file).
3512
3513 \item\optfmt{process-generic-cs}: \texparserlib\ generic command process.
3514
3515 \item\optfmt{process-stack}: \texparserlib\ stack process
3516 (may result in a large transcript file).
3517
3518 \item\optfmt{process-stack-list}: \texparserlib\ stack process with
3519 list detail (may result in a large transcript file).
3520
3521 \item\optfmt{read}: \texparserlib\ file codepoint read
3522 (likely to result in a very large transcript file).
3523
3524 \item\optfmt{settings}: \texparserlib\ settings information.
3525
3526 \item\optfmt{sty-data}: data associated with packages used to store
3527 information that may not exactly correspond to the way the
3528 information is stored in \LaTeX. In the case of \bibgls, this will
3529 typically just be data read from recognised \iext{aux} commands.
3530
3531 \end{itemize}
3532
3533 For example:
3534 \begin{codeenv}
3535 bib2gls \commonlongarg{debug-mode} catcode,sty-data \meta{filename}
3536 \end{codeenv}
3537
3538 \commonarg{no-debug}
3539
3540 Switches off the debugging mode.
3541 This option cannot be set in \gls{BibGlsOptions}.
3542
3543 \section{File Options}
3544
3545 \argsection{aux-input-action}
3546
3547 Determines what \bibgls\ should do if it encounters \ics{@input} in
3548 the \ext+{aux} file. The \meta{setting} may be one of the following:
3549 \begin{description}
3550 \item[\optfmt{follow}] follow the reference (that is, input the file).
3551
3552 \item[\optfmt{skip after bibglsaux}] follow the reference until
3553 \gls{@bibgls@input} is encountered, after which skip all remaining
3554 instances of \ics{@input} (default). If there is no
3555 \styopt{bibglsaux} file, this setting is no different from
3556 \optfmt{follow}.
3557
3558 \item[\optfmt{skip-after-bibglsaux}] synonym of \optfmt{skip after
3559 bibglsaux}.
3560
3561 \item[\optfmt{skip}] skip the reference. Be careful with this
3562 setting if you haven't used \styopt{bibglsaux} or
3563 \gls{glsxtrsetbibglsaux} as you may cause \bibgls\ to miss records.
3564 However, if you are using \csopt[all]{selection} and you're not
3565 interested in locations then this might help speed up \bibgls's
3566 processing time.
3567 \end{description}
3568
3569 This setting is designed to work with \sty{glossaries-extra}['s]
3570 \styopt{bibglsaux} package option or with
3571 \nosecdef{glsxtrsetbibglsaux}
3572 which does the same thing.
3573 This specifies a special \ext{aux} file containing the records that
3574 \bibgls\ will read but \LaTeX\ will skip.
3575 The reference will be written to the \ext{aux} file with
3576 \nosecdef{@bibgls@input}
3577 which is defined by \sty{glossaries-extra} to simply ignore its
3578 argument but \bibgls\ will input the file (regardless of the
3579 \longarg{aux-input-action} setting).
3580
3581 Since the \styopt{bibglsaux} file contains all records and is
3582 typically written to the \ext{aux} file after all the commands that
3583 \bibgls\ is interested in, it's unlikely that the additional
3584 \ext{aux} files (created by \ics{include}) will be of any interest
3585 to \bibgls. Therefore the default setting is to ignore all
3586 \cs{@input} after \gls{@bibgls@input}.
3587
3588 \argsection{dir}
3589
3590 This option cannot be set in \gls{BibGlsOptions}.
3591
3592 By default \bibgls\ assumes that the output files should be written
3593 in the current working directory. The input \iext{bib} files are assumed to be
3594 either in the current working directory or on \TeX's path (in which
3595 case \idx{kpsewhich} will be used to find them).
3596
3597 If your \iext{aux} file isn't in the current working directory (for
3598 example, you have run \TeX\ with \shortargfmt{output-directory})
3599 then you need to take care how you invoke \bibgls.
3600
3601 Suppose I have a file called \filefmt{test-entries.bib} that
3602 contains my entry definitions and a document called
3603 \filefmt{mydoc.tex} that selects the \ext{bib} file using:
3604 \begin{codeenv}
3605 \gls{GlsXtrLoadResources}\oarg{\csopt[test-entries]{src}}
3606 \end{codeenv}
3607 (\filefmt{test-entries.bib} is in the same directory as
3608 \filefmt{mydoc.tex}).
3609 If I compile this document using
3610 \begin{verbatim}
3611 pdflatex -output-directory tmp mydoc
3612 \end{verbatim}
3613 then the auxiliary file \filefmt{mydoc.aux} will be written to the
3614 \filefmt{tmp} sub-directory. The resource information is listed in
3615 the \ext{aux} file as
3616 \begin{codeenv}
3617 \gls{glsxtr@resource}\marg{\csopt[test-entries]{src}}\marg{mydoc}
3618 \end{codeenv}
3619 If I run \bibgls\ from the \filefmt{tmp} directory, then it won't
3620 be able to find the \filefmt{test-entries.bib} file (since it's in
3621 the parent directory).
3622
3623 If I run \bibgls\ from the same directory as \filefmt{mydoc.tex}
3624 using
3625 \begin{verbatim}
3626 bib2gls tmp/mydoc
3627 \end{verbatim}
3628 then the \ext{aux} file is found and the transcript file is
3629 \filefmt{tmp/mydoc.glg} (since the default path name is the same as the
3630 \ext{aux} file but with the extension changed to \iext{glg}) but the
3631 output file \filefmt{mydoc.glstex} will be written to the current
3632 directory.
3633
3634 This works fine from \TeX's point of view as it can find the
3635 \iext{glstex} file, but it may be that you'd rather the \ext{glstex}
3636 file was tidied away into the \filefmt{tmp} directory along with all
3637 the other files. In this case you need to invoke \bibgls\ with the
3638 \longargorshort{dir} option:
3639 \begin{verbatim}
3640 bib2gls -d tmp mydoc
3641 \end{verbatim}
3642
3643 \argsection{log-file}
3644
3645 Sets the name of the \bibgls\ transcript file. By default, the name is the
3646 same as the \iext{aux} file but with a \iext{glg} extension. Note that
3647 if you use \bibgls\ in combination with \idx{xindy} or
3648 \idx{makeindex}, you will need to change the transcript file name to
3649 prevent conflict.
3650 This option cannot be set in \gls{BibGlsOptions}.
3651
3652 The transcript file encoding is governed by
3653 \longarg{log-encoding}.
3654
3655 \argsection{tex-encoding}
3656
3657 This option cannot be set in \gls{BibGlsOptions}.
3658
3659 In general, it's best to have all your files (\ext{aux}, \ext{bib}
3660 and \iext{glstex}) in the same \igls{encoding} that matches your
3661 default encoding (see \sectionref{sec:defencoding}). However, if
3662 your \iext{aux} and \iext{glstex} files have a different encoding to
3663 your default, you can use \longarg{tex-encoding} to specify the
3664 \TeX\ encoding. If omitted the default encoding is used. See
3665 \sectionref{sec:defencoding}.
3666
3667 Note that \bibgls\ will try to detect the document encoding from the
3668 \ext{aux} file to ensure that the \iext{glstex} files match it.
3669 However, at that point, it's too late to establish the encoding of
3670 the \ext{aux} file, which has already been opened. So if the
3671 \ext{aux} file encoding doesn't match the default encoding, you can
3672 specify the correct encoding to use with \longarg{tex-encoding}.
3673
3674 If you are using \sty{fontspec}, \bibgls\ can detect this
3675 from the \ext{log} file instead and will assume UTF-8.
3676
3677 \argsection{log-encoding}
3678
3679 The \igls{encoding} of the \iext{log} file. If omitted, the default
3680 encoding will be used. See \sectionref{sec:defencoding}. (Note
3681 that the \ext{log} file may not have the same encoding as the
3682 \ext{tex} file~\cite{tex.sx.2013}.)
3683 This option cannot be set in \gls{BibGlsOptions}.
3684
3685 \argsection{default-encoding}
3686
3687 The default \igls{encoding} used by \bibgls\ to read and write files is
3688 governed by the \idx{JVM}. This typically matches your operating
3689 system's default encoding. If this is incorrect, you can either
3690 globally change the encoding for the \idx{JVM}, which will affect
3691 all Java applications installed on your device, or you can use
3692 \longarg{default-encoding} just to set the default for \bibgls.
3693 See \sectionref{sec:defencoding}.
3694 This option cannot be set in \gls{BibGlsOptions}.
3695
3696 \argsection{date-in-header}
3697
3698 The comment header block at the start of the \iext{glstex} files
3699 will include the file modification date in the first line (after the
3700 version information). This setting can interfere with
3701 the document build process or version control if you are testing for
3702 file differences rather than file modification dates when only the
3703 timestamp changes.
3704
3705 \argsection{no-date-in-header}
3706
3707 The comment header block at the start of the \iext{glstex} files
3708 won't include the file modification date (default).
3709 If used in \gls{BibGlsOptions}, this option should be specified as
3710 \begin{codeenv}
3711 \gls{BibGlsOptions}\marg{date-in-header=false}
3712 \end{codeenv}
3713
3714 \section{Interpreter Options}
3715
3716 \argsection{break-space}
3717
3718 The interpreter treats a tilde character \idx{nbspchar} as a normal
3719 space. Similarly \ics{nobreakspace} just produces a space.
3720
3721 \argsection{no-break-space}
3722
3723 The interpreter treats a tilde character \idx{nbspchar} as a non-breakable
3724 space (default). Similarly the interpreter will define
3725 \ics{nobreakspace} to produce a non-breakable space character (\hex{00A0}).
3726 If used in \gls{BibGlsOptions}, this option should be specified as
3727 \begin{codeenv}
3728 \gls{BibGlsOptions}\marg{break-space=false}
3729 \end{codeenv}
3730
3731 \argsection{custom-packages}
3732
3733 Instruct the interpreter to parse the package files identified in
3734 \meta{list}. The package files need to be quite simple. When this
3735 switch is used, the interpreter can recognise \ics{ProvidesPackage},
3736 \ics{DeclareOption} (and \ics{DeclareOption*}),
3737 \ics{ProcessOptions}, \ics{PackageError} and \ics{RequirePackage},
3738 but it can't deal with complicated code. In the case of
3739 \ics{RequirePackage}, support will also be governed by
3740 \longarg{custom-packages}. This option has a cumulative action.
3741
3742 Multiple instances of this switch can occur on the command line.
3743 If used in \gls{BibGlsOptions}, the nature of the \keyvallist\
3744 parser means that multiple instances within the same option list
3745 will override each other. Instead, you will need a comma-separated
3746 list as the argument.
3747 For example, from the command line:
3748 \begin{verbatim}
3749 bib2gls --custom-packages 'pkg1,pkg2,pkg3' myDoc
3750 \end{verbatim}
3751 This is equivalent to:
3752 \begin{verbatim}
3753 bib2gls --custom-packages pkg1 --custom-packages pkg2 --custom-packages pkg3 myDoc
3754 \end{verbatim}
3755 Alternatively, within the document:
3756 \begin{codeenv}
3757 \gls{BibGlsOptions}\marg{custom-packages=\marg{pkg1,pkg2,pkg3}}
3758 \end{codeenv}
3759
3760 \argsection{datatool-sort-markers}
3761
3762 The \sty{datatool-base} package provides some marker commands
3763 designed for use with \ics{DTLsortwordlist}: \ics{datatoolasciistart},
3764 \ics{datatoolpersoncomma}, \ics{datatoolplacecomma},
3765 \ics{datatoolsubjectcomma}, \ics{datatoolparenstart},
3766 \ics{datatoolctrlboundary}, \ics{datatoolasciiend}, and
3767 \ics{datatoolparen}. These commands by default will be defined by the
3768 interpreter to match their normal \sty{datatool-base} behaviour (see the
3769 \sty{datatool} documentation for further details). Additionally,
3770 \ics{dtltexorsort} will be redefined to expand to its \emph{first} argument.
3771
3772 Note that you don't need to request the \sty{datatool-base} package,
3773 unless you require support for other commands provided by that
3774 package.
3775
3776 The \longarg{datatool-sort-markers} switch will instead define these
3777 commands to match their localised definitions within
3778 \cs{DTLsortwordlist}. This means that \ics{dtltexorsort} will be
3779 defined to expand to its \emph{second} argument and the marker
3780 commands will expand to content that includes special control codes.
3781 Note that language-sensitive sort methods typically ignore control
3782 codes, so these would either need to be used with a character-code
3783 comparator or a custom sort method would need to be used.
3784 For example:
3785 \begin{codeenv}
3786 \csopt[\ics{glsxtrcontrolIrules}
3787 ;\cs{glshex} 0
3788 ;\cs{glsxtrspacerules}
3789 ;\cs{glsxtrnonprintablerules}
3790 ;\cs{glsxtrcombiningdiacriticrules}
3791 ,\cs{glsxtrhyphenrules}
3792 <\ics{glsxtrcontrolIIrules}
3793 <\cs{glsxtrgeneralpuncrules}
3794 <\cs{glsxtrdigitrules}
3795 <\cs{glsxtrfractionrules}
3796 <\ics{glsxtrGeneralLatinIrules}
3797 <\cs{glshex} 7F
3798 ]{sort-rule}
3799 \end{codeenv}
3800
3801 Instead of \ics{dtltexorsort} (which varies according to this setting), you may
3802 prefer to use \ics{IfTeXParserLib} or \ics{IfNotBibGls}.
3803
3804 \argsection{no-datatool-sort-markers}
3805
3806 Define the \sty{datatool-base} marker commands
3807 (including \cs{dtltexorsort}) to match their normal definition.
3808
3809 \argsection{ignore-packages}
3810
3811 This option is cumulative. When the document \iext{log} file is
3812 parsed for known packages, \bibgls\ will skip the check for any
3813 listed in \meta{list}. Note that this option simply instructs
3814 \bibgls\ to ignore the package information in the log file. Any packages
3815 that are identified with \longarg{packages} will be passed to the
3816 interpreter if support is available, even if the package is also
3817 listed in \longarg{ignore-packages}. Note that
3818 unknown packages can't be included in the ignored \meta{list}.
3819 This option cannot be set in \gls{BibGlsOptions}.
3820
3821 \argsection{interpret}
3822
3823 Switch on the interpreter mode (default). See \sectionref{sec:texparserlib}
3824 for more details.
3825
3826 \argsection{no-interpret}
3827
3828 Switch off the interpreter mode. See \sectionref{sec:texparserlib}
3829 for more details about the interpreter.
3830 If used in \gls{BibGlsOptions}, this option should be specified as
3831 \begin{codeenv}
3832 \gls{BibGlsOptions}\marg{interpret=false}
3833 \end{codeenv}
3834
3835 \argsection{list-known-packages}
3836
3837 This option will list all the packages supported by the \texparserlib\
3838 and will then exit \bibgls.
3839 This option cannot be set in \gls{BibGlsOptions}.
3840
3841 The results are divided into two
3842 sections: those packages that are searched for in the \iext{log}
3843 file and those packages that aren't searched for in the \iext{log}
3844 file but have some support available. Some of the support is very
3845 limited. Package options aren't detected.
3846 The transcript file is always searched for \isty{glossaries-extra}
3847 to ensure that the version is new enough to support \bibgls.
3848
3849 Packages that fall into the first category are:
3850 \isty{amsmath}, \isty{amssymb}, \isty{bpchem}, \isty{fontenc},
3851 \isty{fontspec}, \isty{fourier},
3852 \isty{hyperref}, \isty{lipsum}, \isty{MnSymbol}, \isty{mhchem}, \isty{natbib},
3853 \isty{pifont}, \isty{siunitx} (limited), \isty{stix},
3854 \isty{textcase}, \isty{textcomp}, \isty{tipa}, \isty{upgreek} and
3855 \isty{wasysym}. (You can omit checking for specific packages with
3856 \longarg{ignore-packages}.) These are packages that provide commands
3857 that might be needed within entry fields. The check for
3858 \isty{fontspec} is to simply determine whether or not UTF-8
3859 characters are allowed in labels (for \csopt{labelify} and
3860 \csopt{labelify-list}). (Now that there is better support for UTF-8
3861 with \pdfLaTeX, UTF-8 characters will be allowed in labels if the
3862 detected versions of \isty{glossaries} and \isty{glossaries-extra}
3863 are new enough, but note that you will also need a relatively new
3864 \LaTeX\ kernel as well.)
3865
3866 Packages that fall into the second category are:
3867 \isty{booktabs}, \isty{color}, \isty{datatool-base} (very limited),
3868 \isty{datatool} (very limited), \isty{etoolbox} (very limited), \isty{graphics},
3869 \isty{graphicx}, \isty{ifthen}, \isty{jmlrutils},
3870 \isty{mfirstuc-english}, \isty{probsoln}, \isty{shortvrb},
3871 and \isty{xspace}. These are less likely to be needed within fields
3872 and so aren't checked for by default. If they are needed then you
3873 can instruct \bibgls\ to support them with \longarg{packages}.
3874
3875 Note that \sty{mfirstuc} is always automatically loaded, but
3876 \sty{mfirstuc-english} is not implemented unless explicitly
3877 requested with \code{\longarg{packages} mfirstuc-english}.
3878
3879 If you're wondering about the selection, the \file{texparserlib.jar}
3880 library was originally written for another application that required
3881 support for some of them.
3882
3883 \argsection{packages}
3884
3885 Instruct the interpreter to assume the packages listed
3886 in \meta{list} have been used by the document.
3887 This option has a cumulative action so \code{\longarg{packages}
3888 "wasysym,pifont"} is the same as \code{\longarg{packages} wasysym
3889 \longarg{packages} pifont}.
3890
3891 This option may also be used in \gls{BibGlsOptions} but, as with
3892 \longarg{custom-packages}, multiple instances of the \code{packages}
3893 key in the same option list will override each other.
3894
3895 Note that there's only a limited number of packages supported by the
3896 \texparserlib. This option is provided for cases where you're
3897 using a command from a package that the interpreter doesn't support
3898 but it happens to have the same name and meaning as a command from
3899 a package that the interpreter does support. You can also use it to
3900 provide support for known packages that aren't checked for when the
3901 \ext{log} file is parsed. If you want \bibgls\ to parse an
3902 unsupported package use \longarg{custom-packages}.
3903
3904 \argsection{support-unicode-script}
3905
3906 Text superscript (\ics{textsuperscript}) and subscript
3907 (\ics{textsubscript}) will use Unicode super/subscript characters
3908 if available (default). For example,
3909 \begin{codeenv}
3910 \cs{textsuperscript}\marg{(2)}
3911 \end{codeenv}
3912 will be converted to \code{\textsuperscript{(2)}}, which consists
3913 of: \hex{207D} (superscript left parenthesis)
3914 \hex{00B2} (superscript two) \hex{207E} (superscript right
3915 parenthesis). If the entire contents of the argument can't be
3916 represented by Unicode characters, the interpreter uses \verb|<sup>|
3917 and \verb|<sub>| markup, which is then stripped by \bibgls. For
3918 example,
3919 \begin{codeenv}
3920 \cs{textsuperscript}\marg{(2,3)}
3921 \end{codeenv}
3922 will be converted to
3923 \begin{verbatim}
3924 <sup>(2,3)</sup>
3925 \end{verbatim}
3926 (since there's no superscript comma). The markup is stripped leaving
3927 just \code{(2,3)}.
3928
3929 Superscripts and subscripts in maths mode always use markup
3930 regardless of this setting. Some supported packages that use
3931 \idx{spchar} or \idx{sbchar} as shortcuts within an encapsulating
3932 command may internally use the same code as \cs{textsuperscript} and
3933 \cs{textsubscript}, in which case they will be sensitive to this
3934 setting.
3935
3936 \argsection{no-support-unicode-script}
3937
3938 Text superscript (\cs{textsuperscript}) and subscript
3939 (\cs{textsubscript}) won't use Unicode super/subscript characters.
3940 Note that if other commands are provided that expand to Unicode
3941 superscript or subscript characters, then they won't be affected by
3942 this setting. For example, if \csfmt{superiortwo} is defined as
3943 \begin{codeenv}
3944 \cs{providecommand}\marg{\cmd{superiortwo}}\marg{\charhex{B2}}
3945 \end{codeenv}
3946 then it will be interpreted as \hex{00B2} (superscript two) even if
3947 this setting is on.
3948
3949 If used in \gls{BibGlsOptions}, this option should be specified as
3950 \begin{codeenv}
3951 \gls{BibGlsOptions}\marg{support-unicode-script=false}
3952 \end{codeenv}
3953
3954 \argsection{obey-aux-catcode}
3955
3956 By default, the \ext{aux} parser ignores category code changing
3957 commands. This option will instruct the parser to implement the
3958 category code, but note that it can only do this for known commands
3959 that the parser is able to implement.
3960 This option cannot be set in \gls{BibGlsOptions}.
3961
3962 \argsection{no-obey-aux-catcode}
3963
3964 Instructs the \ext{aux} parser to ignore category code changing
3965 commands. (Default.)
3966 This option cannot be set in \gls{BibGlsOptions}.
3967
3968 \section{Record Options}
3969
3970 \argsection{cite-as-record}
3971
3972 Treat instances of \code{\ics{citation}\margm{label}} found in the
3973 \ext{aux} file as though it was actually an \idx{ignoredrecord}:
3974 \begin{codeenv}
3975 \gls{glsxtr@record}\margm{label}\marg{}\marg{\counter{page}}\marg{\encap{glsignore}}\marg{}
3976 \end{codeenv}
3977 Note that \code{\cs{citation}\marg{*}} will always be skipped. Use
3978 \csopt[all]{selection} to select all entries.
3979 This switch is most useful in conjunction with
3980 \atentrypageref{bibtexentry}.
3981
3982 \argsection{no-cite-as-record}
3983
3984 Don't check for instances of \ics{citation} in the \ext{aux} file
3985 (default).
3986 If used in \gls{BibGlsOptions}, this option should be specified as
3987 \begin{codeenv}
3988 \gls{BibGlsOptions}\marg{cite-as-record=false}
3989 \end{codeenv}
3990
3991 \argsection{collapse-same-location-range}
3992
3993 Collapse any \idx{explicit-range} into a normal \gls{record} if
3994 the start and end \glspl{location} are the same (default).
3995 This record will be treated as a normal \gls{location} that can be
3996 merged with neighbouring \glspl{location}, regardless of
3997 \csopt{merge-ranges}.
3998
3999 \argsection{no-collapse-same-location-range}
4000
4001 Don't collapse any \idx{explicit-range} into a normal
4002 \gls{record} if the start and end \glspl{location} are the same.
4003 The \idx{explicit-range} will only be able to merge with
4004 neighbouring \glspl{location} if \csopt[true]{merge-ranges}.
4005 If used in \gls{BibGlsOptions}, this option should be specified as
4006 \begin{codeenv}
4007 \gls{BibGlsOptions}\marg{collapse-same-location-range=false}
4008 \end{codeenv}
4009
4010 \argsection{shift-zero-sections}
4011
4012 Shift up \glspl{location} ending with \qtt{.0} for any section counters
4013 deeper than \counter{chapter}. This action is applied recursively.
4014 \strong{The setting is ignored for \glspl{location} with other types of
4015 counter.}
4016
4017 For example, suppose the indexing counter has been set to
4018 \counter{subsection}. This could be done globally through the
4019 \styopt{counter} package option:
4020 \begin{codeenv}
4021 \cmd{usepackage}\oarg{\styopt{counter}=\counter{subsection},\styopt{record}}\marg{glossaries-extra}
4022 \end{codeenv}
4023 or set for a specific glossary:
4024 \begin{codeenv}
4025 \cs{newglossary*}\marg{samples}\marg{Samples}\oarg{\counter{subsection}}
4026 \end{codeenv}
4027 or automatically for a particular format:
4028 \begin{codeenv}
4029 \cs{GlsXtrAutoAddOnFormat}\marg{primaryfmt}\marg{\glsopt{counter}=\counter{subsection},\glsopt{format}=primaryfmt}
4030 \end{codeenv}
4031 or for an individual entry:
4032 \begin{codeenv}
4033 \cs{gls}\oarg{\glsopt{counter}=\counter{subsection}}\margm{sample}
4034 \end{codeenv}
4035
4036 If, however, entries are referenced before the first subsection of a
4037 section (or chapter), this can lead to locations that end with \qtt{.0} (because
4038 the \counter{subsection} counter is zero at that point).
4039 Suppose the package option \code{\styopt{counter}=\counter{subsection}}
4040 is in effect and the document starts with:
4041 \begin{codeenv}
4042 \cmd{chapter}\marg{Sample Chapter}
4043 \cs{gls}\marg{sample}.
4044 \cmd{section}\marg{Sample Section}
4045 \cs{gls}\marg{sample}.
4046 \cmd{subsection}\marg{Sample Sub-Section}
4047 \cs{gls}\marg{sample}.
4048 \end{codeenv}
4049 Then the \gls{locationlist} for the \qtt{sample} entry will be:
4050 1.0.0, 1.1.0, 1.1.1 and, if \sty{hyperref} is also loaded, the anchors
4051 will be \code{subsection.1.0.0}, \code{subsection.1.1.0}
4052 and \code{subsection.1.1.1}, but of these, only the last one is
4053 defined. The transcript will contain warnings such as:
4054 \begin{quote}
4055 pdfTeX warning (dest): name\marg{subsection.1.0.0} has been referenced but does not
4056 exist, replaced by a fixed one
4057 \end{quote}
4058
4059 There are two ways to deal with this. The first is quite tedious and
4060 involves changing the \glsopt{counter} setting according to the
4061 current sectioning level:
4062 \begin{codeenv}
4063 \cmd{chapter}\marg{Sample Chapter}
4064 \cs{gls}\oarg{\glsopt{counter}=\counter{chapter}}\marg{sample}.
4065 \cmd{section}\marg{Sample Section}
4066 \cs{gls}\oarg{\glsopt{counter}=\counter{section}}\marg{sample}.
4067 \cmd{subsection}\marg{Sample Sub-Section}
4068 \cs{gls}\oarg{\glsopt{counter}=\counter{subsection}}\marg{sample}.
4069 \end{codeenv}
4070 This method is not only tedious but doesn't lend itself well to
4071 editing where the document structure changes with new sections
4072 introduced or removed.
4073
4074 An easier solution is to use the \longarg{shift-zero-sections}
4075 switch. This setting can also be used in \gls{BibGlsOptions}:
4076 \begin{codeenv}
4077 \gls{BibGlsOptions}\marg{shift-zero-sections}
4078 \end{codeenv}
4079
4080 Each \gls{record} that has a \gls{location} ending with \qtt{.0} and has a
4081 sectioning counter below \counter{chapter} will have the \qtt{.0}
4082 removed and the counter will be changed to the counter for the next
4083 level up. So the \gls{record} with counter \counter{subsection} and
4084 \gls{location} \qtt{1.0.0} will have the counter changed to \counter{section}
4085 and the \gls{location} will be changed to \qtt{1.0} but this function is
4086 performed recursively. Since \qtt{1.0} also ends with \qtt{.0} and
4087 the counter level is still less than \counter{chapter}, the function is
4088 repeated: the counter is now changed from \counter{section} to \counter{chapter}
4089 and the \gls{location} is changed from \qtt{1.0} to \qtt{1}.
4090
4091 For the above example, this action will change the
4092 \gls{locationlist} for the \qtt{sample} entry to: 1, 1.1, 1.1.1 and,
4093 if \sty{hyperref} is also loaded, the anchors will be
4094 \code{chapter.1}, \code{section.1.1} and \code{subsection.1.1.1}
4095 which are now all valid.
4096
4097 \argsection{no-shift-zero-sections}
4098
4099 Don't adjust records with sectioning locations ending in \qtt{.0} (default).
4100 If used in \gls{BibGlsOptions}, this option should be specified as:
4101 \begin{codeenv}
4102 \gls{BibGlsOptions}\marg{shift-zero-sections=false}
4103 \end{codeenv}
4104
4105 \argsection{map-format}
4106
4107 This sets up the rule of precedence for partial \gls{location}
4108 matches (see \sectionref{sec:locationopts}). The argument may be
4109 a comma-separated list of \meta{map}\code{:}\meta{value} pairs.
4110 Alternatively, you can have multiple instances of
4111 \longarg{map-format} \meta{map}\dcolon\meta{value} which have a
4112 cumulative effect on the command line. You can also use
4113 \code{map-format} as an option within \gls{BibGlsOptions}, but
4114 multiple instances of this key in the same option list will override
4115 each other.
4116
4117 For example,
4118 \begin{verbatim}
4119 bib2gls --map-format "emph:hyperbf" mydoc
4120 \end{verbatim}
4121 This essentially means that if there's a \gls{record} conflict
4122 involving \encap{emph}, try replacing \encap{emph} with
4123 \encap{hyperbf} and see if that resolves the conflict.
4124
4125 Note that if the conflict includes a \idx{range} formation, the
4126 \idx{range} takes precedence.
4127 The mapping tests are applied as the records are
4128 read. For example, suppose the records are listed in the \ext{aux}
4129 file as:
4130 \begin{codeenv}
4131 \gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{emph}}\marg{3}
4132 \gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{hypersf}}\marg{3}
4133 \gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{hyperbf}}\marg{3}
4134 \end{codeenv}
4135 and \bibgls\ is invoked with
4136 \begin{verbatim}
4137 bib2gls --map-format "emph:hyperbf,hypersf:hyperit" mydoc
4138 \end{verbatim}
4139 or
4140 \begin{verbatim}
4141 bib2gls --map-format emph:hyperbf --map-format hypersf:hyperit mydoc
4142 \end{verbatim}
4143 then \bibgls\ will process these \glspl{record} as follows:
4144 \begin{enumerate}
4145 \item Accept the first \gls{record} (\encap{emph}) since there's
4146 currently no conflict. (This is the first \gls{record} for page~3 for the
4147 entry given by \code{gls.sample}.)
4148 \item The second \gls{record} (\encap{hypersf}) conflicts
4149 with the existing \gls{record} (\encap{emph}). Neither has
4150 the format \encap{glsnumberformat} or \encap{glsignore} so \bibgls\ consults
4151 the mappings provided by \longarg{map-format}.
4152 \begin{itemize}
4153 \item The \encap{hypersf} format (from the new record) is mapped to
4154 \encap{hyperit},
4155 so \bibgls\ checks if the existing \gls{record}
4156 has this format. In this case it doesn't (the format is
4157 \code{emph}). So \bibgls\ moves on to the next test:
4158
4159 \item The \encap{emph} format (from the existing record) is mapped
4160 to \encap{hyperbf},
4161 so \bibgls\ checks if the new record has this format.
4162 In this case it doesn't (the format is \encap{hypersf}).
4163
4164 Since the provided mappings haven't resolved this conflict,
4165 the new record is discarded with a warning. Note that there's
4166 no look ahead to the next record. (There may be other
4167 records for other entries also used on page~3 interspersed between these records.)
4168 \end{itemize}
4169 \item The third \gls{record} (\encap{hyperbf}) conflicts
4170 with the existing \gls{record} (\encap{emph}). Neither has
4171 the format \encap{glsnumberformat} or \encap{glsignore} so \bibgls\ again consults
4172 the mappings provided by \longarg{map-format}.
4173 \begin{itemize}
4174 \item The new \gls{record}['s] \encap{hyperbf} format has no mapping provided,
4175 so \bibgls\ moves on to the next test:
4176
4177 \item The existing \gls{record}['s] \encap{emph} format has a mapping
4178 provided (\encap{hyperbf}). This matches the new \gls{record}['s] format,
4179 so the new \gls{record} takes precedence.
4180
4181 This means that the \gls{locationlist} ends up with the \encap{hyperbf}
4182 location for page~3.
4183 \end{itemize}
4184 \end{enumerate}
4185
4186 If, on the other hand, the mappings are given as
4187 \begin{verbatim}
4188 --map-format "emph:hyperit,hypersf:hyperit,hyperbf:hyperit"
4189 \end{verbatim}
4190 then all the three conflicting \glspl{record} (\encap{emph},
4191 \encap{hypersf} and \encap{hyperbf}) will end up being replaced
4192 by a single \gls{record} with \encap{hyperit} as the format.
4193
4194 Multiple conflicts will typically be rare as there's usually little
4195 reason for more than two or three different \gls{location} formats within
4196 the same list. (For example, \encap{glsnumberformat} as the default
4197 and \encap{hyperbf} or \encap{hyperit} for a
4198 \gls{principallocation}.)
4199
4200 \argsection{merge-nameref-on}
4201
4202 The \styopt[nameref]{record} package option (introduced to
4203 \sty{glossaries-extra} version 1.37) provides extra information
4204 in the record when indexing, obtained from \ics{@currentlabelname},
4205 \ics{@currentHref} and \ics{theHentrycounter}. Instead of writing the record as:
4206 \begin{codeenv}
4207 \format{glsxtr@record}
4208 \end{codeenv}
4209 the record is written as:
4210 \nosecdef{glsxtr@record@nameref}
4211 If \isty{hyperref} hasn't been loaded \meta{title} and \meta{href}
4212 will always be empty. The most reliable target is given by
4213 \code{\meta{counter}.\meta{hcounter}}, where \meta{counter} is the
4214 associated counter name and \meta{hcounter} is
4215 obtained from \cs{theHentrycounter}, which is set to the hyper
4216 target command \csfmt{theH}\meta{counter} during indexing. Since
4217 this information can't be included in the \gls{location} when indexing
4218 with \idx!{makeindex} or \idx!{xindy}, the base \sty{glossaries}
4219 package tries to obtain a prefix from which the target name can be
4220 formed. This doesn't work if \csfmt{theH}\meta{counter} can't be
4221 formed from \meta{prefix}\csfmt{the}\meta{counter}, which results in
4222 broken links. Since \bibgls\ doesn't have the same restrictions, the
4223 actual target can be included in the record. You can then customize
4224 the document to choose whether to use \meta{href} (to link to the
4225 nearest anchor) or \meta{hcounter} to link to the place where the
4226 indexing counter was incremented.
4227
4228 The \code{nameref} record will be written to the \igls{locationlist} using:
4229 \nosecdef{glsxtrdisplaylocnameref}
4230 The \meta{file} part will be empty for normal internal \glspl{location},
4231 and will be set to the corresponding file name for
4232 \glsdisp{supplementalrecord}{supplemental locations}.
4233
4234 With \sty{hyperref}, \meta{title} is initially empty. The \meta{href} will be
4235 \code{Doc-Start} at the start of the document and is updated
4236 globally on every instance of \ics{refstepcounter}. The
4237 \meta{title} is updated locally by certain commands, such as
4238 \ics{section} or \ics{caption}. This means that the \meta{href}
4239 may not always correspond to the \meta{title}, so using
4240 the \styopt[nameref]{record} package option can have unpredictable
4241 results if the \meta{title} is used as link text with \meta{href} as
4242 the target.
4243
4244 For compactness, \bibgls\ tries to merge duplicate or near
4245 duplicate records. There are four possible rules that it will
4246 use for \code{nameref} records, identified by \meta{rule} in the
4247 \longarg{merge-nameref-on} switch:
4248 \begin{itemize}
4249 \item \optfmt{location}: merge records that match on the
4250 \meta{prefix}, \meta{counter} and \meta{location} parts (as regular
4251 records);
4252 \item \optfmt{title}: merge records that match on the \meta{counter}
4253 and \meta{title} parts;
4254 \item \optfmt{href}: merge records that match on the \meta{counter}
4255 and \meta{href} parts;
4256 \item \optfmt{hcounter}: merge records that match on the \meta{counter}
4257 and \meta{hcounter} parts.
4258 \end{itemize}
4259 The default \meta{rule} is \optfmt{hcounter}. Note that for all
4260 rules the \meta{counter} must match. See the \qt{Nameref Record}
4261 section of the \sty{glossaries-extra} user manual for further
4262 details.
4263
4264 \argsection{merge-wrglossary-records}
4265
4266 For use with the \styopt{indexcounter} package option
4267 (\styfmt{glossaries-extra} v1.29+), this switch merges an entry's
4268 \counter{wrglossary} records for the same page \gls{location}. This is the
4269 default setting. (See also \csopt{save-index-counter}.)
4270
4271 \argsection{no-merge-wrglossary-records}
4272
4273 Don't merge an entry's \counter{wrglossary} records. This means that you
4274 may end up with duplicate page numbers in the entry's \gls{locationlist},
4275 but they will link to different parts of the page.
4276 If used in \gls{BibGlsOptions}, this option should be specified as
4277 \begin{codeenv}
4278 \gls{BibGlsOptions}\marg{merge-wrglossary-records=false}
4279 \end{codeenv}
4280
4281 \argsection{record-count}
4282
4283 Switch on record counting. This will ensure that when each entry
4284 is written to the \iext{glstex} file, \bibgls\ will additionally
4285 set the following fields
4286 \begin{itemize}
4287 \item \field{recordcount}: set to the total
4288 number of records found for the entry;
4289 \item \field{recordcount.counter}: set to the total
4290 number of records found for the entry for the given counter.
4291 \end{itemize}
4292 These fields can then be used with the \gls{rgls}-like commands.
4293
4294 This option is governed by the \longarg{record-count-rule}, which
4295 can be used to exclude certain types of records from the count. The
4296 default rule is \optfmt{all}, which includes all
4297 \idxpl{ignoredrecord}.
4298
4299 The default behaviour of
4300 \nosecdef{rgls}
4301 is to check the \field{recordcount} field against the \catattr{recordcount}
4302 attribute value. This attribute can be set with
4303 \nosecdef{GlsXtrSetRecordCountAttribute}
4304 where \meta{category list} is a comma-separated list
4305 of category labels and \meta{value} is a positive integer.
4306 If the value of the \field{recordcount} field is greater than
4307 \meta{value} then \gls{rgls} behaves like \ics{gls}, otherwise
4308 it does
4309 \nosecdef{rglsformat}
4310 instead.
4311 If the use of \gls{rglsformat} is triggered in this way,
4312 then \gls{rgls} writes a \gls{record} to the \iext{aux} file
4313 with the \glsopt{format} set to \encap{glstriggerrecordformat}.
4314 This ensures that the \gls{recordcount} is correct on the next run,
4315 but the \gls{record} isn't added to the \gls{locationlist} as
4316 \bibgls\ recognises it as a special \igls{ignoredrecord}.
4317 Note that the entry will still appear in the usual glossary unless
4318 you assign it to a different one with \csopt{trigger-type}.
4319
4320 If the \catattr{recordcount} attribute hasn't been set
4321 \gls{rgls} behaves like \ics{gls}. (That is, \gls{rgls}
4322 uses the same internal command used by \ics{gls}.) You can use
4323 \ics{glsxtrenablerecordcount} to redefine \ics{gls}
4324 to \gls{rgls}, so that you can continue to use \ics{gls}
4325 without having to switch command name.
4326
4327 For example:
4328 \begin{codeenv}
4329 \gls{GlsXtrLoadResources}\oarg{
4330 \csopt[abbrevs]{src},\comment{entries defined in abbrevs.bib}
4331 \csopt[ignored]{trigger-type},
4332 \csopt[abbreviation]{category}
4333 }
4334 \cs{glsxtrenablerecordcount}
4335 \gls{GlsXtrSetRecordCountAttribute}\marg{abbreviation}\marg{1}
4336 \end{codeenv}
4337 See the \sty{glossaries-extra} user manual~\cite{glossaries-extra}
4338 for further details.
4339
4340 \begin{important}
4341 Take care not to confuse the \field{recordcount} field with the \field{indexed}
4342 field. The \field{indexed} field keeps a running total of the number of times an
4343 entry has been recorded \emph{so far}, and is updated every time the entry is
4344 indexed during the current \LaTeX\ run. The \field{recordcount} field stores the total number of records
4345 obtained by \bibgls\ from the \ext{aux} file.
4346 \end{important}
4347
4348 \argsection{no-record-count}
4349
4350 Switch off record counting. (Default.)
4351 If used in \gls{BibGlsOptions}, this option should be specified as
4352 \begin{codeenv}
4353 \gls{BibGlsOptions}\marg{record-count=false}
4354 \end{codeenv}
4355
4356 \argsection{record-count-unit}
4357
4358 Automatically implements \longarg{record-count} and additionally
4359 sets the \field{recordcount.counter.location} fields.
4360 These fields can then be used with the \gls{rgls}-like
4361 commands. This option is governed by \longarg{record-count-rule},
4362 to determine which records should be counted.
4363
4364 \argsection{no-record-count-unit}
4365
4366 Switches off unit record counting. (Default.)
4367 Note that you need \longarg{no-record-count} to completely
4368 switch off record counting.
4369 If used in \gls{BibGlsOptions}, this option should be specified as
4370 \begin{codeenv}
4371 \gls{BibGlsOptions}\marg{record-count-unit=false}
4372 \end{codeenv}
4373
4374 \argsection{record-count-rule}
4375
4376 Automatically implements \longarg{record-count} and sets the rule
4377 that determines which records should contribute to the count.
4378 The \meta{rule} may be one of:
4379 \begin{itemize}
4380 \item \code{all} or \code{a}: these keywords indicate that all
4381 records should be included in the count (default).
4382 \item \code{non-ignored} or \code{n}: these keywords indicate that
4383 \idxpl{ignoredrecord} should be excluded in the count.
4384 \item \code{c/\meta{regex}/}: only records where the associated
4385 counter name matches the regular expression \meta{regex} should be
4386 included in the count.
4387 \item \code{f/\meta{regex}/}: only records where the associated
4388 format matches the regular expression \meta{regex} should be
4389 included in the count.
4390 \item \code{f/\meta{format-regex}/c/\meta{counter-regex}/\meta{op}}:
4391 this combines the format and counter name match. The trailing
4392 \meta{op} is optional. If present, it should be one of the keywords:
4393 \code{and} (boolean AND) or \code{or} (boolean OR). If omitted,
4394 \code{and} is assumed.
4395 \end{itemize}
4396
4397 For example:
4398 \begin{verbatim}
4399 bib2gls --record-count-rule 'f/.*(bf|it)/c/(sub)?section/or' myDoc
4400 \end{verbatim}
4401 This will only count records where the format matches the regular
4402 expression \code{.*(bf|it)} (for example, \code{hyperbf} or
4403 \code{hyperit}) or the counter name matches \code{section} or
4404 \code{subsection} (but not \code{subsubsection}, since the
4405 expressions are \gls{anchored}).
4406
4407 This syntax doesn't permit the use of the sequence \code{/c/}
4408 appearing in the regular expressions, but both the format and
4409 counter name are either control sequence names or are a substring of
4410 a control sequence name, so they should typically just be
4411 alphabetical strings.
4412 \argsection{retain-formats}
4413
4414 It's possible that you may not want to lose certain \gls{location}
4415 formats, even if it means having duplicate \glspl{location}. For example,
4416 if you want to move a \gls{principallocation} using
4417 \csopt[remove]{save-principal-locations}. In which case, use this
4418 switch with a comma-separated list of formats that should be
4419 retained. Note that exact duplicates will still be merged.
4420 This switch has a cumulative effect.
4421
4422 Take care if you use this switch and you have an \idx{explicit-range} with
4423 coincident start and end locations. If the
4424 \glsdisp{principallocation}{principal record} is between
4425 the start and end format markers then the \idx{range} can't collapse
4426 to an ordinary \gls{record}. (You may need to use
4427 \csopt[true]{merge-ranges}.)
4428
4429 \argsection{no-retain-formats}
4430
4431 Normal \gls{location} merging rules apply (default).
4432 If used in \gls{BibGlsOptions}, this option should be specified as
4433 \begin{codeenv}
4434 \gls{BibGlsOptions}\marg{retain-formats=false}
4435 \end{codeenv}
4436
4437 \section{Bib File Options}
4438
4439 \argsection{warn-non-bib-fields}
4440
4441 If any internal fields are found in the \ext{bib} file, this setting
4442 will issue a warning as their use can cause unexpected results.
4443 The fields checked for are those listed in Tables~\ref{tab:internalfields}
4444 and \ref{tab:baseinternalfields} with a few exceptions, notably
4445 \field{type} and \field{sort}. Ideally you shouldn't need to use
4446 \field{sort} as there should be an appropriate fallback set up to
4447 use if \field{sort} isn't set, such as the label for symbols or the
4448 name for terms or the short form for abbreviations (see \sectionref{sec:fallbacks}).
4449
4450 This is the default setting and was added as some users were
4451 confused over which fields could be used in the \ext{bib} file.
4452 The use of these fields can break \bibgls's normal behaviour and
4453 cause unexpected results.
4454
4455 The check is performed before field aliasing, so it's possible to
4456 alias a field to an internal field, such as \field{group}, without
4457 triggering this warning. If you do this you need to make sure you
4458 have taken appropriate precautions to avoid unexpected results.
4459
4460 \argsection{no-warn-non-bib-fields}
4461
4462 Switches off the check for non-bib fields. If you use this option
4463 you need to make sure you have taken appropriate precautions to
4464 avoid unexpected results.
4465 If used in \gls{BibGlsOptions}, this option should be specified as
4466 \begin{codeenv}
4467 \gls{BibGlsOptions}\marg{warn-non-bib-fields=false}
4468 \end{codeenv}
4469
4470 \argsection{warn-unknown-entry-types}
4471
4472 If any unknown \glspl{entrytype} are found in the \ext{bib} file, \bibgls\
4473 will issue a warning with this option set (default).
4474
4475 \argsection{no-warn-unknown-entry-types}
4476
4477 This option will suppress the warning if an unknown \glspl{entrytype} are
4478 found in the \ext{bib} file.
4479 If used in \gls{BibGlsOptions}, this option should be specified as
4480 \begin{codeenv}
4481 \gls{BibGlsOptions}\marg{warn-unknown-entry-types=false}
4482 \end{codeenv}
4483
4484 \section{Field Options}
4485
4486 \argsection{group}
4487
4488 The \styfmt{glossaries-extra} \styopt{record} package option
4489 automatically creates a new internal field called \field{group}. If the
4490 \longarg{group} switch is used with the default \csopt[auto]{group}
4491 option then, when sorting, \bibgls\ will try
4492 to determine the \idx{group} for each entry and assign it to the
4493 \field{group} field. (Some \csopt{sort} options ignore this
4494 setting.) This value will be picked up by \ics{printunsrtglossary}
4495 if group headings are required (for example with the
4496 \glostyle{indexgroup} style) or if group separators are required
4497 (for example, the \glostyle{index} style with the default
4498 \styopt[false]{nogroupskip}). If you don't require grouping within
4499 the glossary, there's no need to use this switch. Note that this
4500 switch doesn't automatically select an appropriate glossary style.
4501
4502 If you want \idxpl{sub-group}, you will need to use the \csopt{group-level}
4503 resource option and ensure you have \sty{glossaries-extra} v1.49+.
4504 \Idxpl{smallgroup} can be merged with the \csopt{merge-small-groups}
4505 resource option.
4506
4507 \begin{important}
4508 The \field{group} field should typically not be set in the \ext{bib}
4509 file and will trigger a warning if found. The explicit use of the
4510 \field{group} key will override \bibgls's normal group formation
4511 behaviour, which can cause unexpected results. The custom use of the
4512 \field{group} field requires some care. As a general rule, if you
4513 find yourself wanting to use the \field{group} field in the
4514 \ext{bib} file, then the chances are that what you actually have is
4515 a \gls{hierarchicalglossary} (list of topics) and what you really
4516 need is the \field{parent} field. Compare the example files
4517 \exfile{sample-textsymbols.tex} and
4518 \exfile{sample-textsymbols2.tex}. See also
4519 \sectionref{sec:logicaldivisions}.
4520 \end{important}
4521 There are eight types of groups:
4522 \begin{description}
4523 \item[\idx{lettergroup}] The first non-ignored character of the
4524 sort value is alphabetic. This type of group occurs when using the
4525 alphabetic sort methods listed in \tableref{tab:sortoptionsrule} or
4526 with the letter sort methods listed in
4527 \tableref{tab:sortoptionsletter} or with the letter-number sort
4528 methods listed in \tableref{tab:sortoptionsletternumber}. The group
4529 label is obtained from \gls!{bibglslettergroup}.
4530
4531 \item[\idx{nonlettergroup} (or \idx{symbolgroup})]
4532 The first non-ignored character of all the sort values within this group
4533 are non-alphabetical. This type of group occurs when using the
4534 alphabetic sort methods listed in \tableref{tab:sortoptionsrule} or
4535 with the letter sort methods listed in
4536 \tableref{tab:sortoptionsletter} or with the letter-number sort
4537 methods listed in \tableref{tab:sortoptionsletternumber}.
4538 The alphabetic sort methods ignore many punctuation
4539 characters, so an entry that has a non-alphabetic initial
4540 character in the sort value may actually be placed in a
4541 \idx{lettergroup}.
4542 The group label is obtained from \gls!{bibglsothergroup}.
4543
4544 \item[\idx{emptygroup}] The sort value is empty when sorting with an
4545 alphabetical, letter or letter-number method, typically a
4546 result of the original value consisting solely of commands that \bibgls\
4547 can't interpret. The group label is obtained from \gls!{bibglsemptygroup}.
4548
4549 \item[\idx{numbergroup}] The entries were sorted by one of the
4550 numeric comparisons listed in \tableref{tab:sortoptionsnumerical}.
4551 The group label is obtained from \gls!{bibglsnumbergroup}.
4552
4553 \item[\idx{datetimegroup}] The entries were sorted by one of the date-time
4554 comparisons listed in \tableref{tab:sortoptionsdatetime} (where both
4555 date and time are present).
4556 The group label is obtained from \gls!{bibglsdatetimegroup}.
4557
4558 \item[\idx{dategroup}] The entries were sorted by one of the date
4559 comparisons (where the time is omitted).
4560 The group label is obtained from \gls!{bibglsdategroup}.
4561
4562 \item[\idx{timegroup}] The entries were sorted by one of the time
4563 comparisons (where the date is omitted).
4564 The group label is obtained from \gls!{bibglstimegroup}.
4565
4566 \item[\idx{customgroup}] The group label is explicitly set either by
4567 aliasing a field (with \csopt{field-aliases}) or by using the
4568 \csopt[\meta{label}]{group} resource option. You will need to use
4569 \gls{glsxtrsetgrouptitle} in the document to provide an associated title if the
4570 \meta{label} isn't the same as the title. Remember that with older
4571 \LaTeX\ kernels, the label can't contain any active characters, so
4572 you can't use non-ASCII characters in \meta{label} with
4573 \sty{inputenc} (but you can use non-ASCII alphanumerics with
4574 \sty{fontspec}). To ensure better support for UTF-8 with \pdfLaTeX, make sure you
4575 have a recent \TeX\ distribution and up-to-date versions of
4576 \sty{glossaries} and \sty{glossaries-extra}.
4577
4578 \end{description}
4579
4580 The \idx{lettergroup} titles will typically have the first character
4581 converted to \idx{uppercase} for the alphabet sort methods
4582 (\tableref{tab:sortoptionsrule}). A \qt{letter} may not necessarily
4583 be a single character (depending on the sort rule), but may be
4584 composed of multiple characters, such as a \idx{digraph} (two
4585 characters) or \idx{trigraph} (three characters).
4586
4587 For example, if the sort rule recognises the digraph \qt{dz} as a
4588 letter, then it will be converted to \qt{Dz} for the group title.
4589 There are some exceptions to this. For example, the Dutch digraph
4590 \qt{ij} should be \qt{IJ} rather than \qt{Ij}. This is indicated
4591 by the following line in the \langxml:
4592 \begin{verbatim}
4593 <entry key="grouptitle.case.ij">IJ</entry>
4594 \end{verbatim}
4595 If there isn't a \idx{grouptitle.case.lc} key (where
4596 \meta{lc} is the \idx!{lowercase} version), then only the first character
4597 will be converted to \idx{uppercase} otherwise the value supplied by the
4598 resource file is used. This resource key is only checked for
4599 the alphabetical comparisons listed in
4600 \tableref{tab:sortoptionsrule}. If the initial part of the sort
4601 value isn't recognised as a letter according to the sort rule, then
4602 the entry will be in a \idx{nonlettergroup} (even if the character is
4603 alphabetical).
4604
4605 The letter (\tableref{tab:sortoptionsletter}) and letter-number
4606 (\tableref{tab:sortoptionsletternumber}) methods only select the
4607 first character of the sort value for the group. If the character is
4608 alphabetical\footnote{according to Java's
4609 \code{Character.isAlphabetic(int)} method} then it will be a
4610 \idx{lettergroup} otherwise it's a \idx{nonlettergroup}. The case-insensitive
4611 ordering (such as \csopt[letter-nocase]{sort}) will convert the
4612 letter group character to \idx{uppercase}. The case-sensitive ordering
4613 (such as \csopt[letter-case]{sort}) won't change the case.
4614
4615 Glossary styles with navigational links to groups (such as
4616 \glostyle{indexhypergroup}) require an extra run for the ordinary
4617 \cs{cs.makeglossaries} and \cs{makenoidxglossaries} methods. For
4618 example, for the document \filefmt{myDoc.tex}:
4619 \begin{verbatim}
4620 pdflatex myDoc
4621 makeglossaries myDoc
4622 pdflatex myDoc
4623 pdflatex myDoc
4624 \end{verbatim}
4625 On the first \appfmt{pdflatex} call, there's no glossary. On the second
4626 \appfmt{pdflatex}, there's a glossary but the glossary must be
4627 processed to find the group information, which is written to the
4628 \iext{aux} file as
4629 \nosecdef{@gls@hypergroup}
4630 The third \appfmt{pdflatex} reads this information and is then able
4631 to create the navigation links.
4632
4633 With \bibgls, if the \optfmt{type} is provided (through the
4634 \field{type} field or via options such as \csopt{type} and
4635 \csopt{dual-type}) then this information can be determined when
4636 \bibgls\ is ready to write the \iext{glstex} file, which means that
4637 the extra \LaTeX\ run isn't necessary. If \bibgls\ doesn't know
4638 the glossary type then it will fallback on the original method
4639 which requires an extra \LaTeX\ run.
4640
4641 For example:
4642 \begin{codeenv}
4643 \cmd{documentclass}\marg{article}
4644 \cmd{usepackage}\oarg{colorlinks}\marg{hyperref}
4645 \cmd{usepackage}\oarg{\styopt{record},\styopt{abbreviations},\styopt[indexhypergroup]{style}}\marg{glossaries-extra}
4646 \strut
4647 \gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\comment{data in entries.bib}
4648 \csopt[main]{type}\comment{put these entries in the 'main' glossary}
4649 }
4650 \strut
4651 \gls{GlsXtrLoadResources}\oarg{\csopt[abbrvs]{src},\comment{data in abbrvs.bib}
4652 \csopt[abbreviations]{type}\comment{put entries in the 'abbreviations' glossary}
4653 }
4654 \end{codeenv}
4655 Here the \csopt{type} is set and \bibgls\ can detect that
4656 \isty{hyperref} has been loaded, so if the \longarg{group} switch
4657 is used, then the group hyperlinks can be set (using
4658 \gls!{bibglshypergroup}). This means that the build process is
4659 just:
4660 \begin{verbatim}
4661 pdflatex myDoc
4662 bibtex --group myDoc
4663 pdflatex myDoc
4664 \end{verbatim}
4665 Note that this requires \isty{glossaries} v4.53+ and
4666 \isty{glossaries-extra} v1.53. If your version of \sty{glossaries}
4667 or \sty{glossaries-extra} is too old, an extra \LaTeX\ run is
4668 required.
4669
4670 If \isty{hyperref} isn't loaded or the \longarg{group} switch
4671 isn't used or the \field{type} isn't set or your version of
4672 \sty{glossaries} is too old, then the information can't be saved in
4673 the \ext{glstex} file.
4674
4675 For example:
4676 \begin{codeenv}
4677 \cmd{documentclass}\marg{article}
4678 \cmd{usepackage}\oarg{colorlinks}\marg{hyperref}
4679 \cmd{usepackage}\oarg{\styopt{record},\styopt{abbreviations},\styopt[indexhypergroup]{style}}\marg{glossaries-extra}
4680 \strut
4681 \gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}}\comment{data in entries.bib}
4682 \gls{GlsXtrLoadResources}\oarg{\csopt[abbrvs]{src}}\comment{data in abbrvs.bib}
4683 \end{codeenv}
4684 This requires the build process:
4685 \begin{verbatim}
4686 pdflatex myDoc
4687 bibtex --group myDoc
4688 pdflatex myDoc
4689 pdflatex myDoc
4690 \end{verbatim}
4691 because the group hyperlink information can't be determined by
4692 \bibgls, so it's best to always set the \optfmt{type} if you want
4693 hyper-group styles, and make sure you have an up-to-date version of
4694 \styfmt{glossaries} (and \styfmt{glossaries-extra}).
4695
4696 \argsection{no-group}
4697
4698 Don't automatically set the \field{group} field with
4699 \csopt[auto]{group} (default). The glossary won't have groups even if a
4700 group style, such as \glostyle{indexgroup}, is used (unless the
4701 \field{group} field is set to a custom value).
4702 If used in \gls{BibGlsOptions}, this option should be specified as
4703 \begin{codeenv}
4704 \gls{BibGlsOptions}\marg{group=false}
4705 \end{codeenv}
4706
4707 \argsection{no-expand-fields}
4708
4709 By default, \gls{newglossaryentry} and similar commands expand field values
4710 (except for \field{name}, \field{symbol} and \field{description}).
4711 This is useful if constructing field values programmatically
4712 (for example in a \idx!{loop}) but can cause a problem if certain fragile
4713 commands are included in the field.
4714
4715 The switch \longarg{no-expand-fields} makes \bibgls\ write
4716 \gls{glsnoexpandfields} to the \iext{glstex} file, which
4717 switches off the expansion. Since \bibgls\ is simply
4718 fetching the data from \iext{bib} files, it's unlikely
4719 that this automatic expansion is required and since it can
4720 also be problematic this option is on by default. You can
4721 switch it off with \longarg{expand-fields}.
4722
4723 If used in \gls{BibGlsOptions}, this option should be specified as
4724 \begin{codeenv}
4725 \gls{BibGlsOptions}\marg{expand-fields=false}
4726 \end{codeenv}
4727
4728 \argsection{expand-fields}
4729
4730 Don't write \gls{glsnoexpandfields} to the \iext{glstex} file,
4731 allowing fields to expand when the entries are defined.
4732 Remember that this doesn't include the \field{name}, \field{symbol}
4733 or \field{description} fields, which need to have their
4734 expansion switched on with \gls{glssetexpandfield}
4735 before the entries are defined (that is, before using
4736 \gls!{GlsXtrLoadResources}).
4737
4738 \argsection{mfirstuc-protection}
4739
4740 If you have \isty{mfirstuc} v2.08+, \isty{glossaries} v4.50+
4741 and \isty{glossaries-extra} v1.49+ then this setting shouldn't be
4742 required any more as there's now better \idx{sentencecase} handling.
4743 If these versions are detected in the \ext{log} file then the
4744 default will switch to \longarg{no-mfirstuc-protection}
4745 otherwise the default is \longarg{mfirstuc-protection}. If this causes any
4746 problems, use \longarg{mfirstuc-protection} to re-enable this
4747 setting. The information below relates to older versions.
4748
4749 Commands like \ics{Gls} use \ics{makefirstuc} provided by the
4750 \isty{mfirstuc} package. This command has limitations and one of the
4751 things that can break it is the use of a referencing command
4752 at the start of its argument. The \sty{glossaries-extra} package has
4753 more detail about the problem in the \qt{Nested Links} section of
4754 the user manual~\cite{glossaries-extra}. If a glossary field starts
4755 with one of these problematic commands, the recommended method (if
4756 the command can't be replaced) is to insert an empty group in front
4757 of it.
4758
4759 For example, the following definition
4760 \begin{codeenv}
4761 \gls{newabbreviation}\marg{shtml}\marg{shtml}\marg{\ics{glsps}\marg{ssi} enabled \cs{glsps}\marg{short}\marg{html}}
4762 \end{codeenv}
4763 will cause a problem for \code{\cs{Gls}\marg{shtml}} on first use.
4764 The above example would be written in a \ext{bib} file as:
4765 \begin{codeenv}
4766 \atentry{abbreviation}\marg{shtml,
4767 \field{short}=\marg{shtml},
4768 \field{long}=\marg{\cs{glsps}\marg{ssi} enabled \cs{glsps}\marg{html}}
4769 }
4770 \end{codeenv}
4771 The default \sty{mfirstuc} protection will automatically insert an empty
4772 group before \code{\cs{glsps}\marg{ssi}} when writing the definition
4773 in the \ext{glstex} file.
4774
4775 The argument for this switch should either be a comma-separated list
4776 of fields or the keyword \code{all} (which indicates all fields).
4777 \bibgls\ will automatically insert an empty group at the start of
4778 the listed fields that start with a problematic command, and a
4779 warning will be written to the transcript. Unknown fields are
4780 skipped even if they're included in the list. An empty argument is
4781 equivalent to \longarg{no-mfirstuc-protection}. The default value is
4782 \code{all}.
4783
4784 \argsection{no-mfirstuc-protection}
4785
4786 Switches off the \isty{mfirstuc} protection mechanism described
4787 above.
4788 If used in \gls{BibGlsOptions}, this option should be specified as
4789 \begin{codeenv}
4790 \gls{BibGlsOptions}\marg{mfirstuc-protection=false}
4791 \end{codeenv}
4792
4793 \argsection{mfirstuc-math-protection}
4794
4795 If you have \isty{mfirstuc} v2.08+, \isty{glossaries} v4.50+ and
4796 \isty{glossaries-extra} v1.49+ then this setting shouldn't be
4797 required any more as there's now better \idx{sentencecase} handling. If
4798 these versions are detected in the \ext{log} file then the default
4799 will switch to \longarg{no-mfirstuc-math-protection}. If this causes
4800 any problems, use \longarg{mfirstuc-math-protection} to re-enable
4801 this setting. The information below relates to older versions.
4802
4803 This setting works in the same way as \longarg{mfirstuc-protection} but
4804 guards against fields starting with inline maths
4805 (\idx{mshiftchar}\ldots\idx{mshiftchar}). For example, if the
4806 \field{name} field starts with
4807 \code{\idx{mshiftchar}x\idx{mshiftchar}} and the glossary style
4808 automatically tries to convert the first letter of the name to
4809 \idx{uppercase}, then this will cause a problem.
4810
4811 With \longarg{mfirstuc-math-protection} set, \bibgls\ will
4812 automatically insert an empty group at the start of the field and
4813 write a warning in the transcript. This setting is on by default.
4814
4815 \argsection{no-mfirstuc-math-protection}
4816
4817 Switches off the above.
4818 If used in \gls{BibGlsOptions}, this option should be specified as
4819 \begin{codeenv}
4820 \gls{BibGlsOptions}\marg{mfirstuc-math-protection=false}
4821 \end{codeenv}
4822
4823 \argsection{nested-link-check}
4824
4825 By default, \bibgls\ will parse certain fields for potential nested links.
4826 (See the section \qt{Nested Links} in the \sty{glossaries-extra}
4827 user manual~\cite{glossaries-extra}.)
4828
4829 The default set of fields to check are: \field{name}, \field{text},
4830 \field{plural}, \field{first}, \field{firstplural}, \field{long},
4831 \field{longplural}, \field{short}, \field{shortplural} and
4832 \field{symbol}.
4833
4834 You can change this set of fields using
4835 \longarg{nested-link-check} \meta{value} where \meta{value} may be
4836 \optfmt{none} (don't parse any of the fields) or a comma-separated
4837 list of fields to be checked.
4838
4839 \argsection{no-nested-link-check}
4840
4841 Equivalent to \longarg{nested-link-check} \optfmt{none}.
4842 If used in \gls{BibGlsOptions}, this option should be specified as
4843 \begin{codeenv}
4844 \gls{BibGlsOptions}\marg{nested-link-check=none}
4845 \end{codeenv}
4846 or
4847 \begin{codeenv}
4848 \gls{BibGlsOptions}\marg{nested-link-check=false}
4849 \end{codeenv}
4850
4851 \argsection{shortcuts}
4852
4853 Some entries may reference another entry within a field, using
4854 commands like \ics{gls}, so \bibgls\ parses the fields for these
4855 commands to determine dependent entries to allow them to be selected
4856 even if they haven't been used within the document.
4857 The \styopt{shortcuts} package option provided by
4858 \styfmt{glossaries-extra} defines various synonyms, such as \ics{ac}
4859 which is equivalent to \ics{gls}. By default the value of the
4860 \styopt{shortcuts} option will be picked up by \bibgls\ when parsing the
4861 \iext{aux} file. This then allows \bibgls\ to additionally search for
4862 those shortcut commands while parsing the fields.
4863
4864 You can override the \styopt{shortcuts} setting using
4865 \longarg{shortcuts} \meta{value} (where \meta{value} may take
4866 any of the allowed values for the \styopt{shortcuts} package option),
4867 but in general there is little need to use this switch.
4868
4869 \argsection{trim-fields}
4870
4871 Trim leading and trailing spaces from all field values. For example,
4872 if the \ext{bib} file contains:
4873 \begin{codeenv}
4874 \atentry{entry}\marg{sample,
4875 \field{name} = \marg{sample},
4876 \field{description} = \marg{
4877 an example
4878 }
4879 }
4880 \end{codeenv}
4881 This will cause spurious spaces in the \field{description} field.
4882 Using \longarg{trim-fields} will automatically trim the values
4883 before writing the \iext{glstex} file.
4884
4885 Note that even without this trimming option on, fields that are
4886 set as keys within \cs{longnewglossaryentry} or the optional
4887 argument of \cs{newabbreviation} will automatically have the leading and
4888 trailing spaces internally trimmed by the \isty{xkeyval} package, so
4889 this trimming action only affects fields that aren't set in this
4890 way, such as the \field{description}, \field{long} and \field{short}
4891 fields. If you specifically require a space at the start or end of a
4892 field then use a spacing command, such as \cs{cs.space} or \cs{space}
4893 or \idx{nbspchar}.
4894
4895 \argsection{trim-only-fields}
4896
4897 Only trim leading and trailing spaces from the fields identified in
4898 the comma-separated \meta{list}. This option has a cumulative effect
4899 but is cancelled by \longarg{no-trim-fields} (which switches off all
4900 trimming) and by \longarg{trim-fields} (which switches on trimming
4901 for all fields). This option may not be used with
4902 \longarg{trim-except-fields}.
4903
4904 For example, to only trim the \field{description} field:
4905 \begin{verbatim}
4906 bib2gls --trim-only-fields description myDoc
4907 \end{verbatim}
4908
4909 \argsection{trim-except-fields}
4910
4911 Trim all leading and trailing spaces from fields except those identified in
4912 the comma-separated \meta{list}. This option has a cumulative effect
4913 but is cancelled by \longarg{no-trim-fields} (which switches off all
4914 trimming) and by \longarg{trim-fields} (which switches on trimming
4915 for all fields). This option may not be used with
4916 \longarg{trim-only-fields}. See the above note about \sty{xkeyval}.
4917
4918 For example, to trim all fields except \field{short} and
4919 \field{long}:
4920 \begin{verbatim}
4921 bib2gls --trim-except-fields short,long myDoc
4922 \end{verbatim}
4923 Or
4924 \begin{verbatim}
4925 bib2gls --trim-except-fields short --trim-except-fields long myDoc
4926 \end{verbatim}
4927
4928 \argsection{no-trim-fields}
4929
4930 Don't trim any leading or trailing spaces from field values (but see
4931 the above note about \sty{xkeyval}). This is the default setting.
4932 If used in \gls{BibGlsOptions}, this option should be specified as
4933 \begin{codeenv}
4934 \gls{BibGlsOptions}\marg{trim-fields=false}
4935 \end{codeenv}
4936
4937 \section{Other Options}
4938
4939 \argsection{force-cross-resource-refs}
4940
4941 Force \igls{crossresourceref} mode on (see
4942 \sectionref{sec:resourcesets}).
4943
4944 \argsection{no-force-cross-resource-refs}
4945
4946 Don't force \igls{crossresourceref} mode on (default).
4947 The mode will be enabled if applicable (see
4948 \sectionref{sec:resourcesets}).
4949 If used in \gls{BibGlsOptions}, this option should be specified as
4950 \begin{codeenv}
4951 \gls{BibGlsOptions}\marg{force-cross-resource-refs=false}
4952 \end{codeenv}
4953
4954 \argsection{provide-glossaries}
4955
4956 This setting will make \bibgls\ add the line
4957 \begin{codeenv}
4958 \ics{provideignoredglossary*}\margm{type}
4959 \end{codeenv}
4960 to the \ext{glstex} file before an entry is defined where that entry
4961 has the \field{type} field set to an unknown glossary type (\bibgls\
4962 can detect from the \ext{aux} file all glossaries that have been
4963 defined with \cs{newglossary} but not those defined with \cs{newignoredglossary}).
4964
4965 This ensures that the glossary exists, but the use of
4966 \ics{provideignoredglossary} (rather than \cs{newignoredglossary})
4967 will prevent an error if the glossary has already been defined.
4968
4969 \argsection{no-provide-glossaries}
4970
4971 This setting prevents \bibgls\ from providing unknown glossaries,
4972 except in a few documented situations (the \csopt{master},
4973 \csopt{trigger-type}, \csopt{ignored-type} and \csopt{secondary} options). This is the
4974 default since it's a useful way of detecting misspelt glossary
4975 labels. It's harder to detect the problem if a misspelt label has
4976 caused an entry to be added to a hidden glossary.
4977 If used in \gls{BibGlsOptions}, this option should be specified as
4978 \begin{codeenv}
4979 \gls{BibGlsOptions}\marg{provide-glossaries=false}
4980 \end{codeenv}
4981
4982 \argsection{replace-quotes}
4983
4984 Single and double-quote characters (\idx{aposchar} and
4985 \idx{doublequotechar}) will be written as \cs{bibglsaposchar} and
4986 \cs{bibglsdoublequotechar} in field values and group information
4987 written to the \ext{glstex} file.
4988
4989 \argsection{no-replace-quotes}
4990
4991 Single and double-quote characters (\idx{aposchar} and
4992 \idx{doublequotechar}) will be written as those actual characters
4993 (default).
4994 If used in \gls{BibGlsOptions}, this option should be specified as
4995 \begin{codeenv}
4996 \gls{BibGlsOptions}\marg{replace-quotes=false}
4997 \end{codeenv}
4998
4999 \chapter{\iext{bib} Format}
5000 \label{sec:bib}
5001 \setsecdepth{1}
5002
5003 \bibgls\ recognises certain \glspl{entrytype}. Any unrecognised types will
5004 be ignored and a warning will be written to the transcript file.
5005 Bib file entry types can be divided into: special entry types and
5006 glossary entry types. The resource options mostly apply only to
5007 the glossary entry types (except where noted).
5008
5009 The glossary entry types correspond to glossary entries that can be
5010 referenced in the document with commands like \ics{gls}.
5011 They are defined in the usual \ext{bib} format:
5012 \begin{codeenv*}
5013 \idx{atchar}\meta{entry-type}\marg{\meta{id},
5014 \meta{field-name-1} = \margm{text},
5015 \ldots
5016 \meta{field-name-n} = \margm{text}
5017 }
5018 \end{codeenv*}
5019 where \meta{entry-type} is the \gls{entrytype} (listed below),
5020 \meta{field-name-1}, \ldots, \meta{field-name-n} are the field names and
5021 \meta{id} is a unique label. The label can't contain any spaces or
5022 commas, and most special characters are forbidden. The hyphen character and
5023 some other punctuation characters are allowed by \bibgls, but you need to make
5024 sure that your document hasn't made them active. In general it's best to
5025 stick with alpha-numeric labels. The field values may be delimited by braces
5026 \margm{text} or double-quotes \code{\qtdelim{\meta{text}}}.
5027
5028 The \csopt{label-prefix} option can be used to instruct \bibgls\ to
5029 insert prefixes to the labels (\meta{id}) when the data is read.
5030 Remember to use these prefixes when you reference the entries in the
5031 document, but don't include them when you reference them in the
5032 \ext{bib} file. There are some special prefixes that have a
5033 particular meaning to \bibgls: \qt{\idprefix{dual}} and
5034 \qt{\idprefix{extn}} where \meta{n} is a positive integer.
5035 In the first case, \idprefix{dual} references the dual element of a
5036 dual entry (see \atentry{dualentry}). This prefix will be
5037 replaced by the value of the \csopt{dual-prefix} option. The
5038 \idprefix{extn} prefix is used to reference an entry from a
5039 different set of resources (loaded by another
5040 \gls{GlsXtrLoadResources} command). This prefix is replaced by the
5041 corresponding element of the list supplied by \csopt{ext-prefixes},
5042 but this is only supported if the \igls{crossresourceref} mode is enabled
5043 (see \sectionref{sec:resourcesets}).
5044
5045 In the event that the \field{sort} value falls back on the label,
5046 the original label supplied in the \ext{bib} file is used, not the
5047 prefixed label.
5048
5049 \section{Encoding}
5050 \label{sec:bibencoding}
5051
5052 If you are using \XeLaTeX\ or \LuaLaTeX\ (which are natively UTF-8)
5053 or if you are using a modern \TeX\ distribution \pdfLaTeX\ with
5054 UTF-8 support, then you can have UTF-8 characters in the \meta{id}
5055 of your entries. (Avoid \TeX\ special characters, active characters
5056 or characters that are part of the \ext{bib} syntax.)
5057
5058 You can set the character \igls{encoding} in the \ext{bib} file using:
5059 \begin{codeenv}
5060 \idx{commentchar} Encoding: \meta{encoding-name}
5061 \end{codeenv}
5062 where \meta{encoding-name} is the name of the character \gls{encoding}.
5063 For example:
5064 \begin{verbatim}
5065 % Encoding: UTF-8
5066 \end{verbatim}
5067 You can also set the \gls{encoding} using the \csopt{charset} option,
5068 but it's simpler to include the above comment on the first line of
5069 the \ext{bib} file. (This comment is also searched for by JabRef
5070 to determine the \gls{encoding}, so it works for both applications.)
5071 If you don't use either method \bibgls\ will
5072 have to search the entire \ext{bib} file, which is inefficient and
5073 you may end up with a mismatched \gls{encoding}.
5074
5075 \begin{important}
5076 The encoding comment line must come before any non-ASCII content
5077 otherwise a malformed input error may occur while parsing the file
5078 for the comment line.
5079 \end{important}
5080
5081 If there is no encoding line in the \ext{bib} file and the
5082 \csopt{charset} option hasn't been used, then the default encoding
5083 will be assumed (see \sectionref{sec:defencoding}).
5084
5085 \section{Fields}
5086 \label{sec:fields}
5087
5088 Each \gls{entrytype} may have required fields, optional fields and
5089 ignored fields. These are set using a \keyvallist\ within
5090 \code{@\meta{entry-type}\marg{\meta{id},\meta{fields}}} in the
5091 \ext{bib} file. Most keys recognised by
5092 \gls{newglossaryentry} may be used as a field unless \bibgls\
5093 considers them an internal field (see below). In general, you
5094 shouldn't need to use the \field{sort} field.
5095
5096 If an optional field is missing and \bibgls\ needs to access it for
5097 some reason, \bibgls\ will try to fallback on another value. The
5098 actual fallback value depends on the \gls{entrytype}. The most common
5099 fallback is that used if the \field{sort} field is missing, which is
5100 typically the case. This approach allows different \glspl{entrytype} to
5101 have different fields used for sorting (see \sectionref{sec:fallbacks}).
5102
5103 Predefined fields for use in \ext{bib} files are listed in
5104 Tables~\ref{tab:fields}, \ref{tab:bib2glsfields},
5105 \ref{tab:prefixfields} and~\ref{tab:accsuppfields}. If you add any
5106 custom keys in your document using \ics{glsaddkey} or
5107 \ics{glsaddstoragekey}, those commands must be placed before the
5108 first use of \gls{GlsXtrLoadResources} to ensure that \bibgls\
5109 recognises them as a valid field name.
5110
5111 \begin{important}
5112 If you define your own custom keys, ensure that they don't contain
5113 spaces, commas (\idx{commasep}), equal signs (\idx{equalsassign}) or
5114 any other character that isn't supported by the \ext{bib} format.
5115 Additionally, if you want to use \csopt{assign-fields}, ensure
5116 that you don't use any of the assignment special characters, such as
5117 plus (\idx{concat-plus}), within any
5118 field names.
5119 \end{important}
5120
5121 Internal fields that may be assigned within the document (the
5122 \LaTeX\ assignment code having been written by \bibgls\ in the
5123 \iext{glstex} file) are listed in Table~\ref{tab:internalfields}.
5124 These typically shouldn't be used in the \ext{bib} file. Some of
5125 these fields can be set for a particular document using a resource
5126 option, such as \csopt{type} or \csopt{group}. With
5127 \longarg{warn-non-bib-fields} set, \bibgls\ will check for internal
5128 fields that can cause interference with its normal operations and
5129 will warn if any are found in the \ext{bib} file.
5130
5131 There are also some fields that are set and used by
5132 \styfmt{glossaries} or \styfmt{glossaries-extra} listed in
5133 Table~\ref{tab:baseinternalfields} that aren't recognised by \bibgls.
5134 In most cases these fields don't have a designated key and are only
5135 intended for internal use by \bibgls\ or by the \styfmt{glossaries} or
5136 \styfmt{glossaries-extra} package. Note that the value of the \field{sort} field
5137 written to the \ext{bib} file doesn't always exactly match the sort
5138 value used by \bibgls\ (which is stored in \field{bib2gls@sort}).
5139 Any special characters found in the sort value are always substituted
5140 before writing the \ext{bib} file to avoid syntax errors.
5141
5142 Any unrecognised fields will be ignored by \bibgls. This is more
5143 convenient than using \ics{input} or \gls{loadglsentries}, which
5144 requires all the keys used in the file to be defined, regardless of
5145 whether or not you actually need them in the document.
5146
5147 Other entries can be cross-referenced using the \field{see},
5148 \field{seealso} or \field{alias} fields or
5149 by using commands like \ics{gls} or \ics{glsxtrp} in any of the
5150 recognised fields. These will automatically be selected if the
5151 \csopt{selection} setting includes dependencies, but you may need to
5152 rebuild the document to ensure the \glspl{locationlist} are correct. Use
5153 of the \ics{glssee} command will create an \igls{ignoredrecord} and the
5154 \field{see} field will be set to the relevant information. If an
5155 entry has the \field{see} field already set, any instance of
5156 \ics{glssee} in the document for that entry will be appended to the
5157 \field{see} field (provided you have at least v1.14 of
5158 \sty{glossaries-extra}). In general, it's best just to use the
5159 \field{see} field and not use \ics{glssee}.
5160
5161 The \field{seealso} key was only added to \sty{glossaries-extra}
5162 v1.16, but this field may be used with \bibgls\ even if you only
5163 have version 1.14 or 1.15. If the key isn't available,
5164 \code{\field{seealso}=\margm{xr-list}} will be treated as
5165 \code{\field{see}=\marg{[\ics{seealsoname}]\meta{xr-list}}} (the resource
5166 option \csopt{seealso} won't have an effect). You can't use both
5167 \field{see} and \field{seealso} for the same entry with \bibgls.
5168 Note that the \field{seealso} field doesn't allow for the optional
5169 \oargm{tag} part. If you need a different tag, either use \field{see}
5170 or change the definition of \ics{seealsoname} or
5171 \ics{glsxtruseseealsoformat}. Note that, unless you are using
5172 \idx!{xindy}, \ics{glsxtrindexseealso} just does
5173 \ics{glssee}\oarg{\ics{seealsoname}}, and so will be treated as \field{see}
5174 rather than \field{seealso} by \bibgls. Again, it's better to just
5175 use the \field{seealso} field directly.
5176
5177 You can identify an arbitrary field as containing a list of dependent entry
5178 labels with \csopt{dependency-fields}. This instructs \bibgls\ to parse the
5179 listed fields for dependencies in a similar manner to the \field{see} field,
5180 but it doesn't add any information to the cross-referencing part of the
5181 \gls{locationlist}. The option may be used in combination with the \field{see} or
5182 \field{seealso} fields.
5183
5184 \clearpage
5185
5186 \printfields
5187 {basefield,extrafield}
5188 {Fields Provided by \styfmt{glossaries-extra}}
5189 {tab:fields}
5190
5191 \clearpage
5192
5193 \printfields
5194 {bib2glsfield}
5195 {Fields Provided by \bibgls}
5196 {tab:bib2glsfields}
5197
5198 \printfields
5199 {prefixfield}%
5200 [Fields Provided by \styfmt{glossaries-prefix}]%
5201 {Fields Provided by \isty{glossaries-prefix}}
5202 {tab:prefixfields}
5203
5204 \printfields
5205 [%
5206 Don't load \isty{glossaries-accsupp} directly (with \ics{usepackage})
5207 when using \styfmt{glossaries-extra}. Load using the
5208 \glsadd{idx.accsupp}\styopt{accsupp}
5209 package option instead.
5210 %\begin{codeenv}
5211 %\cs{usepackage}\oarg{\styopt{record},\styopt{accsupp}}\marg{glossaries-extra}
5212 %\end{codeenv}
5213 ]%
5214 {accessfield}%
5215 [Fields Provided by \styfmt{glossaries-accsupp}]%
5216 {Fields Provided by \isty{glossaries-accsupp}}
5217 {tab:accsuppfields}
5218
5219 \printfields
5220 [%
5221 You may define and assign \field{bibtextype} as a key (although it's more
5222 likely to be aliased). Don't define any of the others listed in this
5223 table, and don't use any of them in the \ext{bib} file. A possible
5224 exception is the \field{type} field, but it's more flexible to set
5225 that through a resource option. The explicit use of \field{group}
5226 within a \ext{bib} file can cause unpredictable
5227 results and is best set through a resource option or by \bibgls.
5228 In general, you shouldn't need to set the \field{sort} field as
5229 appropriate fallbacks should produce useful sort values
5230 (see \sectionref{sec:fallbacks}).%
5231 ]%
5232 {internalfield}%
5233 [Fields Set by \bibgls]%
5234 {Fields Sometimes Set by \bibgls\ in the \iext{glstex} File}%
5235 {tab:internalfields}
5236
5237 \printfields
5238 [%
5239 Don't define any of these as keys and don't use any of them in the \ext{bib}
5240 file.%
5241 ]%
5242 {baseinternalfield}%
5243 [Internal Fields Set by \styfmt{glossaries} or \styfmt{glossaries-extra}
5244 or \bibgls]%
5245 {Internal Fields Set by \isty{glossaries} or \isty{glossaries-extra}
5246 or \bibgls}%
5247 {tab:baseinternalfields}
5248
5249 \printfields
5250 [%
5251 Only available for \atentry{compoundset}. These correspond to the
5252 arguments of \ics{multiglossaryentry}.%
5253 ]%
5254 {compoundsetfield}%
5255 {Compound Set Fields}%
5256 {tab:compoundsetfields}
5257
5258 \clearpage
5259
5260 \section{String Concatenation}
5261 \label{sec:bibstringconcat}
5262
5263 The \ext{bib} format allows you to perform string \gls{concatenation}.
5264 That is, join fragments together to form a single value.
5265 The \gls{concatenation} operator in \ext{bib} files is
5266 \idx{stringconcat}.
5267 For example, if the following string is defined:
5268 \begin{codeenv}
5269 \atentry{string}\marg{markuplang=\marg{markup language}}
5270 \end{codeenv}
5271 Then values can be obtained by concatenating this string with other
5272 strings. For example:
5273 \begin{codeenv}
5274 \atentry{abbreviation}\marg{xml,
5275 \field{short}=\marg{XML},
5276 \field{long}=\marg{extensible } \idx{stringconcat} markuplang
5277 }
5278 \atentry{abbreviation}\marg{html,
5279 \field{short}=\marg{HTML},
5280 \field{long}=\marg{hypertext } \idx{stringconcat} markuplang
5281 }
5282 \end{codeenv}
5283 This is equivalent to:
5284 \begin{codeenv}
5285 \atentry{abbreviation}\marg{xml,
5286 \field{short}=\marg{XML},
5287 \field{long}=\marg{extensible markup language}
5288 }
5289 \atentry{abbreviation}\marg{html,
5290 \field{short}=\marg{HTML},
5291 \field{long}=\marg{hypertext markup language}
5292 }
5293 \end{codeenv}
5294
5295 Note that some resource options allow string \gls{concatenation} in
5296 their syntax. That uses a different operator. See
5297 \sectionref{sec:optstringconcat} for further details.
5298
5299 \section{Special Entry Types}
5300 \label{sec:specialentrytypes}
5301
5302 The bib entry types described in this section don't correspond to
5303 any glossary entry type. They aren't affected by most of the
5304 resource options, including sorting or filtering.
5305
5306 \subsection{Comments}
5307 \label{sec:bibcomments}
5308
5309 The original \ext{bib} file format as defined by \BibTeX\ doesn't
5310 have a designated comment character, but instead treats anything
5311 outside of \code{@\meta{entry}\margm{data}} as unwanted material
5312 that's ignored. This can catch out users who try to do something
5313 like:
5314 \begin{verbatim}
5315 %@misc{sample, title={Sample} }
5316 \end{verbatim}
5317 In this case, the percent character is simply discarded and the
5318 line is treated as:
5319 \begin{verbatim}
5320 @misc{sample, title={Sample} }
5321 \end{verbatim}
5322 Some applications that parse \ext{bib} files are less tolerant of
5323 unwanted material. In the case of \bibgls, the percent character is
5324 treated as a comment character and other unwanted material
5325 should be omitted. Avoid using comments within field values.
5326 Comments are best placed outside of entry definitions.
5327
5328 The most common type of comment is the \gls{encoding} comment, described
5329 above. \BibTeX's \entrydef{comment} is also supported by \bibgls\
5330 for general comments, but not for the \gls{encoding}.
5331
5332 \subsection{Preamble}
5333 \label{sec:preamble}
5334
5335 As with \BibTeX, \atentry{preamble} is also supported by \bibgls.
5336 This will be written to the \ext{glstex} file unless
5337 prevented with \csopt[false]{write-preamble}.
5338 The \texparserlib\ used by \bibgls\ will parse the contents of
5339 \atentry{preamble} unless \csopt[false]{interpret-preamble}
5340 (or the interpreter is switched off with \longarg{no-interpret}).
5341
5342 \subsection{Compound Entry Sets}
5343 \label{sec:compoundsetentry}
5344
5345 A \gls{compoundentry} isn't a normal glossary entry
5346 but corresponds to a multi-entry (compound or combined) set provided
5347 by \sty{glossaries-extra} v1.48+, which is defined by the command
5348 \ics{multiglossaryentry} (or \ics{providemultiglossaryentry}).
5349 These are referred to as multi-entries in \sty{glossaries-extra} but
5350 are referred to as \glspl{compoundentry} here to avoid confusion
5351 with the \glspl{multientrytype}. They are referenced with commands
5352 like \ics{mgls} not with the \cs{gls} set of commands.
5353 As such, they don't belong in any glossary list, although their
5354 component elements do.
5355
5356 \begin{important}
5357 Most resource options don't apply to this \gls{entrytype}. Options
5358 specific to \glspl{compoundentry} are listed in
5359 \sectionref{sec:compoundentries}.
5360 \end{important}
5361
5362 Essentially, a label is defined that refers to a set of labels
5363 corresponding to entries that \emph{have already been defined}. One
5364 element in the set is considered the \gls{compmainlabel}. Entry
5365 labels may appear in multiple sets.
5366
5367 \begin{important}
5368 Although the \sty{glossaries-extra} package allows the same label to
5369 be used for a regular entry and a compound entry, the \ext{bib}
5370 format doesn't allow this.
5371 \end{important}
5372
5373 A \gls{compoundentry} provides a convenient way to apply commands
5374 like \ics{gls} to multiple entries in one command (such as \ics{mgls}).
5375 \Gls{compoundentry} labels may only be used in the \cs{mgls}-like
5376 commands or in a \gls{cross-referencefield}.
5377
5378 For example, consider the following document:
5379 \begin{codeenv}
5380 \cmd{documentclass}\marg{article}
5381 \cmd{usepackage}\marg{hyperref}
5382 \cmd{usepackage}[\styopt{record},\styopt[tree]{style}]\marg{glossaries-extra}
5383 \cs{setabbreviationstyle}\marg{long-only-short-only}
5384 \cs{renewcommand}*\marg{\cs{glsxtronlyname}}\marg{\comment{}
5385 \cs{protect}\cs{glslongonlyfont}\marg{\cs{the}\cs{glslongtok}}\comment{}
5386 }
5387 \cs{newabbreviation}\marg{clostridium}\marg{C.}\marg{Clostridium}
5388 \gls{newglossaryentry}\marg{botulinum}\marg{name=botulinum,
5389 description=\marg{},parent=clostridium}
5390 \gls{newglossaryentry}\marg{perfringens}\marg{name=perfringens,
5391 description=\marg{},parent=clostridium}
5392 \cmd{begin}\marg{document}
5393 \cs{gls}\marg{clostridum} \cs{gls}\marg{botulinum},
5394 \cs{gls}\marg{clostridum} \cs{gls}\marg{perfringens},
5395 \cs{gls}\marg{clostridum} \cs{gls}\marg{botulinum}.
5396 \cs{printunsrtglossary}
5397 \cmd{end}\marg{document}
5398 \end{codeenv}
5399 This produces:
5400 \begin{quote}
5401 Clostridium botulinum,
5402 C. perfringens,
5403 C. botulinum.
5404 \end{quote}
5405 followed by the glossary. This is very cumbersome. Defining a
5406 \gls{compoundentry} label simply provides a shortcut:
5407 \begin{codeenv*}
5408 \ics{multiglossaryentry}\marg{cbot}\marg{clostridium,botulinum}
5409 \ics{multiglossaryentry}\marg{cperf}\marg{clostridium,perfringens}
5410 \end{codeenv*}
5411 (This has to be done after the entries have been defined.) Now the
5412 entries can be more compactly referenced:
5413 \begin{codeenv*}
5414 \ics{mgls}\marg{cbot},
5415 \ics{mgls}\marg{cperf},
5416 \ics{mgls}\marg{cbot}.
5417 \end{codeenv*}
5418 Each \gls{compoundentry} set must contain at least two elements. The
5419 \gls{compmainlabel} is the label of the element that is considered
5420 the main entry of the set. If the \gls{compmainlabel} isn't
5421 identified in \cs{multiglossaryentry} then it's assumed to be the
5422 last element in the set.
5423
5424 In the above example, \code{botulinum} is the \gls{compmainlabel} of
5425 the \code{cbot} set, and \code{perfringens} is the
5426 \gls{compmainlabel} of the \code{cperf} set. In both sets,
5427 \code{clostridium} is the \qt{\gls{compotherlabel}}. If there are
5428 more than two elements in the set then \qt{others} refers to all the
5429 elements except for the \gls{compmainlabel}. An entry can be a
5430 \gls{compmainlabel} of one set and an \gls{compotherlabel} of
5431 another set.
5432
5433 The options, which can be applied to all sets with
5434 \ics{multiglossaryentrysetup} or to a specific set using the
5435 first optional argument of \ics{multiglossaryentry}, determine
5436 if each element of the list has a separate hyperlink to their
5437 own target, or if only the main element should have a hyperlink, or
5438 if the entire content of \ics{mgls} should be a single hyperlink to
5439 the main entry's target.
5440
5441 With \bibgls, the component entries that form the set should be in \ext{bib} files as usual.
5442 The \gls{compoundentry} set may either be defined in the document \ext{tex}
5443 file using \ics{multiglossaryentry} (or \ics{providemultiglossaryentry})
5444 or they can be defined in the \ext{bib} file using
5445 \atentry{compoundset}. Remember that the set can only be defined
5446 after the entries that make up the elements of the set have been
5447 defined. If any \ext{bib} files in a \gls{resourceset} contain
5448 \atentry{compoundset}, the definitions will be added at the end of
5449 the \ext{glstex} file (using \gls{bibglsdefcompoundset}).
5450
5451 If you have multiple \glspl{resourceset} that reuse the same
5452 \ext{bib} file containing \atentry{compoundset} then either redefine
5453 \gls{bibglsdefcompoundset} to use \ics{providemultiglossaryentry} or
5454 prevent duplicate definitions with \csopt[false]{compound-write-def}.
5455
5456 The elements of the set will still need to be indexed as usual to
5457 ensure that they have \glspl{record} to enable selection.
5458 If any element hasn't been selected, the \gls{compoundentry} define won't
5459 be written to the \ext{glstex} file, regardless of the
5460 \csopt{compound-write-def} setting.
5461
5462 The above example can be converted to \bibgls\ as follows
5463 (\glspl{compoundentry} defined in the document \ext{tex} file):
5464 \begin{codeenv}
5465 \cmd{documentclass}\marg{article}
5466 \cmd{usepackage}\marg{hyperref}
5467 \cmd{usepackage}[\styopt{record},\styopt[tree]{style}]\marg{glossaries-extra}
5468 \cs{setabbreviationstyle}\marg{long-only-short-only}
5469 \cs{renewcommand}*\marg{\cs{glsxtronlyname}}\marg{\comment{}
5470 \cs{protect}\cs{glslongonlyfont}\marg{\cs{the}\cs{glslongtok}}\comment{}
5471 }
5472 \gls{GlsXtrLoadResources}\oarg{\csopt[bacteria]{src}}
5473 \cs{multiglossaryentry}\marg{cbot}\marg{clostridium,botulinum}
5474 \cs{multiglossaryentry}\marg{cperf}\marg{clostridium,perfringens}
5475 \cmd{begin}\marg{document}
5476 \cs{mgls}\marg{cbot}, \cs{mgls}\marg{cperf}, \cs{mgls}\marg{cbot}.
5477 \cs{printunsrtglossary}
5478 \cmd{end}\marg{document}
5479 \end{codeenv}
5480 Note that \cs{multiglossaryentry} must come after \gls{GlsXtrLoadResources}.
5481
5482 The \file{bacteria.bib} contains the definitions in the usual way:
5483 \begin{codeenv}
5484 \atentry{abbreviation}\marg{clostridium,
5485 \field{short}=\marg{C.},
5486 \field{long}=\marg{Clostridium}
5487 }
5488 \atentry{index}\marg{botulinum,
5489 \field{parent}=\marg{clostridium}
5490 }
5491 \atentry{index}\marg{perfringens,
5492 \field{parent}=\marg{clostridium}
5493 }
5494 \end{codeenv}
5495
5496 Alternatively, the \glspl{compoundentry} can be defined in the
5497 \ext{bib} file instead:
5498 \begin{codeenv}
5499 \atentry{compoundset}\marg{cbot,
5500 \field{elements}=\marg{clostridium,botulinum}
5501 }
5502 \atentry{compoundset}\marg{cperf,
5503 \field{elements}=\marg{clostridium,perfringens}
5504 }
5505 \end{codeenv}
5506 The \cs{multiglossaryentry} commands should now be removed from the
5507 \ext{tex} file.
5508
5509 There's a difference between these two methods on the first \LaTeX\
5510 build. In the first example, \code{cbot} is known, so
5511 \code{\cs{mgls}\marg{cbot}} can perform
5512 \code{\cs{gls}\marg{clostridum} \cs{gls}\marg{botulinum}}. These
5513 commands aren't yet defined so they are both replaced by \qt{??}
5514 (resulting in \qt{?? ??}). As usual, the \gls{locationlist} is
5515 unreliable until entries are defined and the unknown markers \qt{??}
5516 can be replaced with the correct content. If the document is in a
5517 file called \filefmt{myDoc.tex} then the document build:
5518 \begin{codeenv}
5519 pdflatex myDoc
5520 bib2gls myDoc
5521 pdflatex myDoc
5522 \end{codeenv}
5523 will have \glspl{location} in the resulting PDF file, but they may
5524 be incorrect if the associated temporary files were initially
5525 missing.
5526
5527 In the second example, \code{cbot} is unknown, so
5528 \code{\cs{mgls}\marg{cbot}} is simply displayed as \qt{??}.
5529 In this case, the \ext{aux} file contains information that
5530 \code{cbot} has been referenced, but there are no associated
5531 \glspl{record}. The entries that belong to the \code{cbot} set will
5532 be selected as they are considered dependent on the
5533 \gls{compoundentry}. In this case, if you are starting from scratch
5534 (no associated temporary files), you will need:
5535 \begin{codeenv}
5536 pdflatex myDoc
5537 bib2gls myDoc
5538 pdflatex myDoc
5539 bib2gls myDoc
5540 pdflatex myDoc
5541 \end{codeenv}
5542 At this point, the \glspl{locationlist} will appear.
5543 After that, you can reduce the document build to:
5544 \begin{codeenv}
5545 pdflatex myDoc
5546 bib2gls myDoc
5547 pdflatex myDoc
5548 \end{codeenv}
5549 (Until you later add new entries.)
5550
5551 If you don't want \glspl{location} for the
5552 \glslink{compotherlabel}{other elements} then set the
5553 \idx{encap} to \encap{glsignore}:
5554 \begin{codeenv*}
5555 \ics{multiglossaryentrysetup}\marg{encapothers=\encap{glsignore}}
5556 \end{codeenv*}
5557
5558 \entrysection{compoundset}
5559 The following fields are available:
5560 \begin{description}
5561 \item[\field{elements}] The comma-separated list of element labels.
5562 This corresponds to the final argument of \cs{multiglossaryentry}.
5563 (Required.)
5564 \item[\field{main}] The \gls{compmainlabel}. This field is optional.
5565 If omitted, the main label is assumed to be the last element.
5566 \item[\field{options}] A comma-separated list of options. This
5567 corresponds to the first optional argument of
5568 \cs{multiglossaryentry}. This field may be omitted.
5569 \end{description}
5570 These fields can only be used in this \gls{entrytype}.
5571
5572 \section{Glossary Entry Types}
5573 \label{sec:glossaryentrytypes}
5574
5575 Each of the bib entry types listed below corresponds to one or more glossary
5576 entries, which may be referenced in the document with commands such
5577 as \cs{gls}.
5578
5579 \subsection{Standard Entry Types}
5580 \label{sec:standardentry}
5581
5582 \entrysection{string}
5583
5584 The standard \atentry{string} is available and can be used to define
5585 variables that may be used in field values. Don't include braces or
5586 double-quote delimiters when referencing a variable. You can use
5587 \idx{stringconcat} to concatenate strings.
5588 For example:
5589 \begin{codeenv}
5590 \atentry{string}\marg{ssi=\marg{server-side includes}}
5591 \atentry{string}\marg{html=\marg{hypertext markup language}}
5592 \strut
5593 \atentry{abbreviation}\marg{shtml,
5594 \field{short}=\qtdelim{shtml},
5595 \field{long}=ssi \idx{stringconcat} \qtdelim{ enabled } \idx{stringconcat} html,
5596 \field{see}=\marg{ssi,html}
5597 }
5598 \strut
5599 \atentry{abbreviation}\marg{html,
5600 \field{short}=\qtdelim{html},
5601 \field{long}=html
5602 }
5603 \strut
5604 \atentry{abbreviation}\marg{ssi,
5605 \field{short}=\qtdelim{ssi},
5606 \field{long}=ssi
5607 }
5608 \end{codeenv}
5609 Note the difference between \code{=\qtdelim{ssi}} (a field value delimited by
5610 double-quotes), the undelimited \code{=ssi} (a reference to the
5611 variable), the grouped \code{=\marg{ssi,html}} (a field value
5612 delimited by braces) and \code{ssi} the entry label.
5613
5614 \entrysection{preamble}
5615
5616 The standard \atentry{preamble} is available and can be used to
5617 provide command definitions used within field values.
5618 For example:
5619 \begin{codeenv}
5620 \atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{mtx}}[1]\marg{\cs{boldsymbol}\marg{\idx{param}1}}}}
5621 \strut
5622 \atentry{entry}\marg{matrix,
5623 \field{name}=\marg{matrix},
5624 \field{plural}=\marg{matrices},
5625 \field{description}=\marg{rectangular array of values, denoted \idx{mshiftchar}\cmd{mtx}\marg{M}\idx{mshiftchar}}
5626 }
5627 \end{codeenv}
5628 Alternatively you can use \ics{glsxtrprovidecommand} which behaves
5629 the same as \ics{providecommand} within the document but behaves
5630 like \ics{renewcommand} within \bibgls, which allows you to change
5631 \bibgls's internal definition of a command without affecting the
5632 definition within the document (if it's already been defined before
5633 the resource file is input). In general, it's best to just use
5634 \cs{providecommand}.
5635
5636 The \texparserlib\ used by \bibgls\ will parse the contents of
5637 \atentry{preamble} before trying to interpret the field value used
5638 as a \hyperref[sec:fallbacks]{fallback} when \field{sort} is omitted (unless
5639 \csopt[false]{interpret-preamble} is set in the resource options).
5640 For example:
5641 \begin{codeenv}
5642 \atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{set}}[1]\marg{\cs{mathcal}\marg{\idx{param}1}}
5643 \cs{providecommand}\marg{\cmd{card}}[1]\marg{|\cmd{set}\marg{\idx{param}1}|}}}
5644 \strut
5645 \atentry{entry}\marg{S,
5646 \field{name}=\marg{\marg{}\idx{mshiftchar}\cmd{set}\marg{S}\idx{mshiftchar}},
5647 \field{text}=\marg{\cmd{set}\marg{S}},
5648 \field{description}=\marg{a set}
5649 }
5650 \atentry{entry}\marg{card,
5651 \field{name}=\marg{\marg{}\idx{mshiftchar}\cmd{card}\marg{S}\idx{mshiftchar}},
5652 \field{text}=\marg{\cmd{card}\marg{S}},
5653 \field{description}=\marg{the cardinality of \cs{gls}\marg{S}}
5654 }
5655 \end{codeenv}
5656 Neither entry has the \field{sort} field, so \bibgls\ has to fall
5657 back on the \field{name} field and, since this contains the special
5658 characters \idx{escchar} (backslash), \idx{mshiftchar} (maths
5659 shift), \idx{bgroupchar} (begin group) and
5660 \idx{egroupchar} (end group), the \texparserlib\ is used to interpret it.
5661 The definitions provided by \atentry{preamble} allow \bibgls\ to
5662 deduce that the \field{sort} value of the \code{S} entry is just
5663 \code{S} and the \field{sort} value of the \code{card} entry is
5664 \verb"|S|" (see \sectionref{sec:texparserlib}).
5665
5666 What happens if you also need to use these commands in the document?
5667 The definitions provided in \atentry{preamble} won't be available
5668 until the \iext{glstex} file has been created, which means the
5669 commands won't be defined on the first \LaTeX\ run.
5670
5671 There are several approaches:
5672 \begin{enumerate}
5673 \item Just define the commands in the document. This means the
5674 commands are available, but \bibgls\ won't be able to correctly
5675 interpret the \field{name} fields.
5676
5677 \item Define the commands in both the document and in
5678 \atentry{preamble}. For example:
5679 \begin{codeenv}
5680 \cs{newcommand}\marg{\cmd{set}}[1]\marg{\cs{mathcal}\marg{\idx{param}1}}
5681 \cs{newcommand}\marg{\cmd{card}}[1]\marg{|\cmd{set}\marg{\idx{param}1}|}
5682 \gls{GlsXtrLoadResources}\oarg{\csopt[my-data]{src}}
5683 \end{codeenv}
5684 Alternatively:
5685 \begin{codeenv}
5686 \gls{GlsXtrLoadResources}\oarg{\csopt[my-data]{src}}
5687 \cs{providecommand}\marg{\cmd{set}}[1]\marg{\cs{mathcal}\marg{\idx{param}1}}
5688 \cs{providecommand}\marg{\cmd{card}}[1]\marg{|\cmd{set}\marg{\idx{param}1}|}
5689 \end{codeenv}
5690 If the provided definitions match those given in the \ext{bib} file,
5691 there's no difference. If they don't match then in the first example
5692 the document definitions will take precedence (but the interpreter
5693 will use the \atentry{preamble} definitions) and in the second
5694 example the \atentry{preamble} definitions will take precedence.
5695 For example, the document may define \csfmt{card} as:
5696 \begin{codeenv}
5697 \cs{newcommand}\marg{\cmd{card}}[1]\marg{\ics{vert}\cmd{set}\marg{\idx{param}1}\cs{vert}}
5698 \end{codeenv}
5699
5700 \item Make use of \gls{glsxtrfmt} provided by \styfmt{glossaries-extra} which
5701 allows you to store the name of the formatting command in a field.
5702 The default is the \field{user1} field, but this can be changed to
5703 another field by redefining \ics{GlsXtrFmtField}.
5704
5705 The \ext{bib} file can now look like this:
5706 \begin{codeenv}
5707 \atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{set}}[1]\marg{\cs{mathcal}\marg{\idx{param}1}}
5708 \cs{providecommand}\marg{\cmd{card}}[1]\marg{|\cmd{set}\marg{\idx{param}1}|}}}
5709 \strut
5710 \atentry{symbol}\marg{S,
5711 \field{name}=\marg{\marg{}\idx{mshiftchar}\cmd{set}\marg{S}\idx{mshiftchar}},
5712 \field{text}=\marg{\cmd{set}\marg{S}},
5713 \field{user1}=\marg{set},
5714 \field{description}=\marg{a set}
5715 }
5716 \atentry{symbol}\marg{cardS,
5717 \field{name}=\marg{\marg{}\idx{mshiftchar}\cmd{card}\marg{S}\idx{mshiftchar}},
5718 \field{text}=\marg{\cmd{card}\marg{S}},
5719 \field{user1}=\marg{card},
5720 \field{description}=\marg{the cardinality of \cs{gls}\marg{S}}
5721 }
5722 \end{codeenv}
5723 Within the document, you can format \meta{text} using the formatting
5724 command provided in the \field{user1} field with:
5725 \nosecformatdef{glsxtrfmt}
5726 (which internally uses \ics{glslink}) or
5727 \nosecformatdef{glsxtrentryfmt}
5728 which just applies the appropriate formatting command to
5729 \meta{text}. Version 1.23+ of \sty{glossaries-extra} also provides a
5730 starred form of the linking command:
5731 \nosecformatdef{glsxtrfmt*}
5732 which inserts additional material inside the link text but outside
5733 the formatting command.
5734
5735 If the entry given by \meta{label} hasn't been defined,
5736 then \gls!{glsxtrfmt} just does \meta{text} (followed by \meta{insert} for
5737 the starred version) and a warning is issued. (There's no warning
5738 if the entry is defined but the field hasn't been set.)
5739 The \meta{options} are as for \ics{glslink} but \ics{glslink} will
5740 actually be using:
5741 \begin{codeenv}
5742 \ics{glslink}\oarg{\meta{def-options},\meta{options}}\margm{label}\marg{\cmd{}\meta{csname}\margm{text}\meta{insert}}
5743 \end{codeenv}
5744 where the default options \meta{def-options} are given by
5745 \ics{GlsXtrFmtDefaultOptions}. The default definition of this is
5746 just \code{noindex} which suppresses the automatic indexing or
5747 recording action. (See the \sty{glossaries-extra}
5748 manual~\cite{glossaries-extra} for further details.) The
5749 \meta{insert} part is omitted for the unstarred form.
5750
5751 This means that the document doesn't need to actually provide
5752 \verb|\set| or \verb|\card| but can instead use, for example,
5753 \begin{codeenv}
5754 \gls{glsxtrfmt}\marg{S}\marg{A}
5755 \gls{glsxtrentryfmt}\marg{cardS}\marg{B}
5756 \end{codeenv}
5757 instead of:
5758 \begin{verbatim}
5759 \set{A}
5760 \card{B}
5761 \end{verbatim}
5762 The first \LaTeX\ run will simply ignore the formatting and produce
5763 a warning.
5764
5765 Since this is a bit cumbersome to write, you can provide shortcut
5766 commands. For example:
5767 \begin{codeenv}
5768 \gls{GlsXtrLoadResources}\oarg{\csopt[my-data]{src}}
5769 \cs{newcommand}\marg{\cmd{gset}}[2][]\marg{\gls{glsxtrfmt}\oarg{\idx{param}1}\marg{S}\marg{\idx{param}2}}
5770 \cs{newcommand}\marg{\cmd{gcard}}[2][]\marg{\gls{glsxtrfmt}\oarg{\idx{param}1}\marg{cardS}\marg{\idx{param}2}}
5771 \end{codeenv}
5772 Whilst this doesn't seem a great deal different from simply
5773 providing the definitions of \csfmt{set} and \csfmt{card} in the
5774 document, this means you don't have to worry about remembering
5775 the names of the actual commands provided in the \ext{bib} file
5776 (just the entry labels) and the use of \gls{glsxtrfmt} will
5777 automatically produce a hyperlink to the glossary entry if the
5778 \isty{hyperref} package has been loaded.
5779 \end{enumerate}
5780
5781 Here's an alternative \ext{bib} that defines entries with a term, a
5782 description and a symbol:
5783 \begin{codeenv}
5784 \atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{setfmt}}[1]\marg{\cs{mathcal}\marg{\idx{param}1}}
5785 \cs{providecommand}\marg{\cmd{cardfmt}}[1]\marg{|\cmd{setfmt}\marg{\idx{param}1}|}}}
5786 \strut
5787 \atentry{entry}\marg{set,
5788 \field{name}=\marg{set},
5789 \field{symbol}=\marg{\cmd{setfmt}\marg{S}},
5790 \field{user1}=\marg{setfmt},
5791 \field{description}=\marg{collection of values}
5792 }
5793 \atentry{entry}\marg{cardinality,
5794 \field{name}=\marg{cardinality},
5795 \field{symbol}=\marg{\cmd{cardfmt}\marg{S}},
5796 \field{user1}=\marg{cardfmt},
5797 \field{description}=\marg{the number of elements in the \cs{gls}\marg{set} \idx{mshiftchar}\cs{glssymbol}\marg{set}\idx{mshiftchar}}
5798 }
5799 \end{codeenv}
5800 I've changed the entry labels and the names of the formatting commands.
5801 The definitions in the document need to reflect the change in label
5802 but not the change in the formatting commands:
5803 \begin{codeenv}
5804 \cs{newcommand}\marg{\cmd{gset}}[2][]\marg{\gls{glsxtrfmt}\oarg{\idx{param}1}\marg{set}\marg{\idx{param}2}}
5805 \cs{newcommand}\marg{\cmd{gcard}}[2][]\marg{\gls{glsxtrfmt}\oarg{\idx{param}1}\marg{cardinality}\marg{\idx{param}2}}
5806 \end{codeenv}
5807
5808 Here's another approach that allows for a more complicated argument
5809 for the cardinality. (For example, if the argument is an expression
5810 involving set unions or intersections.)
5811 The \ext{bib} file is now:
5812 \begin{codeenv}
5813 \atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{setfmt}}[1]\marg{\cs{mathcal}\marg{\idx{param}1}}
5814 \cs{providecommand}\marg{\cmd{cardfmt}}[1]\marg{|\idx{param}1|}}}
5815 \strut
5816 \atentry{entry}\marg{set,
5817 \field{name}=\marg{set},
5818 \field{symbol}=\marg{\cmd{setfmt}\marg{S}},
5819 \field{user1}=\marg{setfmt},
5820 \field{description}=\marg{collection of values}
5821 }
5822 \atentry{entry}\marg{cardinality,
5823 \field{name}=\marg{cardinality},
5824 \field{symbol}=\marg{\cmd{cardfmt}\marg{\cmd{setfmt}\marg{S}}},
5825 \field{user1}=\marg{cardfmt},
5826 \field{description}=\marg{the number of elements in the \cs{gls}\marg{set} \idx{mshiftchar}\cs{glssymbol}\marg{set}\idx{mshiftchar}}
5827 }
5828 \end{codeenv}
5829 This has removed the \csfmt{setfmt} command from the definition of
5830 \csfmt{cardfmt}. Now the definitions in the document are:
5831 \begin{codeenv}
5832 \cs{newcommand}\marg{\cmd{gset}}[1]\marg{\gls{glsxtrentryfmt}\marg{set}\marg{\idx{param}1}}
5833 \cs{newcommand}\marg{\cmd{gcard}}[2][]\marg{\gls{glsxtrfmt}\oarg{\idx{param}1}\marg{cardinality}\marg{\idx{param}2}}
5834 \end{codeenv}
5835 This allows for code such as:
5836 \begin{verbatim}
5837 \[ \gcard{\gset{A} \cap \gset{B}} \]
5838 \end{verbatim}
5839 which will link back to the \code{cardinality} entry in the
5840 glossary and avoids any hyperlinking with \csfmt{gset}.
5841 Alternatively to avoid links with \csfmt{gcard} as well:
5842 \begin{codeenv}
5843 \cs{newcommand}\marg{\cmd{gset}}[1]\marg{\gls{glsxtrentryfmt}\marg{set}\marg{\idx{param}1}}
5844 \cs{newcommand}\marg{\cmd{gcard}}[1]\marg{\gls{glsxtrentryfmt}\marg{cardinality}\marg{\idx{param}1}}
5845 \end{codeenv}
5846 Now \csfmt{gset} and \csfmt{gcard} are simply formatting commands,
5847 but their actual definitions are determined in the \ext{bib} file.
5848
5849 \subsection{Single Entry Types}
5850 \label{sec:singleentry}
5851
5852 The \glspl{entrytype} described in this section create a single glossary
5853 definition per entry (from \styfmt{glossaries-extra}'s point of view).
5854 For example:
5855 \begin{codeenv}
5856 \atentry{entry}\marg{matrix,
5857 \field{name}=\marg{matrix},
5858 \field{plural}=\marg{matrices},
5859 \field{description}=\marg{rectangular array of values}
5860 }
5861 \end{codeenv}
5862 is analogous to:
5863 \begin{codeenv}
5864 \gls{newglossaryentry}\marg{matrix}\comment{label}
5865 \marg{\comment{fields}
5866 \field{name}=\marg{matrix},
5867 \field{plural}=\marg{matrices},
5868 \field{description}=\marg{rectangular array of values}
5869 }
5870 \end{codeenv}
5871 The \csopt{secondary} option allows the creation of a fake glossary
5872 with the entry labels in its internal list in a different order.
5873 This means that the same data can be displayed in two separate lists
5874 without duplicating the resources required by each glossary entry.
5875
5876 \Sectionref{sec:dualentry} describes \bibgls\ \glspl{entrytype}
5877 that create two separate (but related) \styfmt{glossaries-extra}
5878 definitions per \ext{bib} entry.
5879
5880 \entrysection{entry}
5881
5882 Regular terms are defined by the \atentry{entry} field. This requires the
5883 \field{description} field and either \field{name} or \field{parent}.
5884 For example:
5885 \begin{codeenv}
5886 \atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{mtx}}[1]\marg{\cs{boldsymbol}\marg{\idx{param}1}}}}
5887 \strut
5888 \atentry{entry}\marg{matrix,
5889 \field{name}=\marg{matrix},
5890 \field{plural}=\marg{matrices},
5891 \field{description}=\marg{rectangular array of values, denoted \cs{gls}\marg{M}},
5892 \field{seealso}=\marg{vector}
5893 }
5894 \strut
5895 \atentry{entry}\marg{M,
5896 \field{name}=\marg{\cs{ensuremath}\marg{M}},
5897 \field{description}=\marg{a \cs{gls}\marg{matrix}}
5898 }
5899 \strut
5900 \atentry{entry}\marg{vector,
5901 \field{name} = \qtdelim{vector},
5902 \field{description} = \marg{column or row of values, denoted \cs{gls}\marg{v}},
5903 \field{seealso}=\marg{matrix}
5904 }
5905 \strut
5906 \atentry{entry}\marg{v,
5907 \field{name}=\marg{\cs{ensuremath}\marg{\cs{vec}\marg{v}}},
5908 \field{description}=\marg{a \cs{gls}\marg{vector}}
5909 }
5910 \end{codeenv}
5911
5912 If the \field{sort} field is missing the default is obtained from
5913 the \field{name} field (unless overridden by options like
5914 \csopt{entry-sort-fallback}). For \hierarchical\ entries, if the
5915 \field{name} field is omitted it will be obtained from the
5916 \glsdisp{parententry}{parent's} \field{name}.
5917 See \sectionref{sec:fallbacks}.
5918
5919 Terms defined using \atentry{entry} will be written to the output
5920 (\ext{glstex}) file using the command \gls!{bibglsnewentry}.
5921
5922 \entrysection{symbol}
5923
5924 The \atentry{symbol} \gls{entrytype} is much like \atentry{entry}, but it's
5925 designed specifically for symbols, so in the previous example, the
5926 \code{M} and \code{v} terms would be better defined using the
5927 \atentry{symbol} \gls{entrytype} instead. For example:
5928 \begin{codeenv}
5929 \atentry{symbol}\marg{M,
5930 \field{name}=\marg{\cs{ensuremath}\marg{M}},
5931 \field{description}=\marg{a \cs{gls}\marg{matrix}}
5932 }
5933 \end{codeenv}
5934
5935 The required fields are \field{name} or \field{parent}. The
5936 \field{description} field is required if the \field{name} field is
5937 missing. If the \field{sort} field is omitted, the default fallback is
5938 given by the entry label (unless overridden by options like
5939 \csopt{symbol-sort-fallback}). Note that this is different from
5940 \atentry{entry} where the sort defaults to \field{name} if omitted.
5941 See \sectionref{sec:fallbacks}.
5942
5943 Terms that are defined using \atentry{symbol} will be written to
5944 the output file using the command \gls!{bibglsnewsymbol}.
5945
5946 \entrysection{number}
5947
5948 The \atentry{number} \gls{entrytype} is like \atentry{symbol}, but it's for
5949 numbers. The numbers don't have to be explicit digits and may have a
5950 symbolic representation. There's no real difference between the
5951 behaviour of \atentry{number} and \atentry{symbol} except that terms
5952 defined using \atentry{number} will be written to the output file
5953 using the command \gls!{bibglsnewnumber}.
5954
5955 For example, the file \filefmt{constants.bib} might define
5956 mathematical constants like this:
5957 \begin{codeenv}
5958 \atentry{number}\marg{pi,
5959 \field{name}=\marg{\cs{ensuremath}\marg{\ics{pi}}},
5960 \field{description}=\marg{the ratio of the length of the circumference
5961 of a circle to its diameter},
5962 \field{user1}=\marg{3.14159}
5963 }
5964 \strut
5965 \atentry{number}\marg{e,
5966 \field{name}=\marg{\cs{ensuremath}\marg{e}},
5967 \field{description}=\marg{base of natural logarithms},
5968 \field{user1}=\marg{2.71828}
5969 }
5970 \end{codeenv}
5971 This stores the approximate value in the \field{user1} field. This
5972 can be used to sort the entries in numerical order according to the
5973 values rather than the symbols:
5974 \begin{codeenv}
5975 \gls{GlsXtrLoadResources}\oarg{
5976 \csopt[constants]{src},\comment{constants.bib}
5977 \csopt[number]{category},\comment{set the category for all selected entries}
5978 \csopt[double]{sort},\comment{numerical double-precision sort}
5979 \csopt[user1]{sort-field}\comment{sort according to 'user1' field}
5980 }
5981 \end{codeenv}
5982 The \csopt[number]{category} option makes it easy to adjust the
5983 glossary format to include the \field{user1} field:
5984 \begin{codeenv}
5985 \ics{glsdefpostdesc}\marg{number}\marg{\comment{}
5986 \cs{ifglshasfield}\marg{useri}\marg{\cs{glscurrententrylabel}}\comment{}
5987 \marg{ (approximate value: \cs{glscurrentfieldvalue})}\comment{}
5988 \marg{}\comment{}
5989 }
5990 \end{codeenv}
5991
5992 \entrysection{index}
5993
5994 The \atentry{index} \gls{entrytype} is designed for entries that don't
5995 have a description. Only the label is required. If \field{name} is
5996 omitted, it's assumed to be the same as the label, even if
5997 \field{parent} is present. (Note this is different to the fallback
5998 behaviour of \atentry{entry}, which fetches the name from the
5999 \gls{parententry}.) If the name contains any characters that can't be used in
6000 the label, you must use the \field{name} field. If the \field{sort}
6001 field is missing the default fallback is obtained from the \field{name}.
6002 Note that the \atentry{index} \gls{entrytype} is \emph{not} governed by
6003 \csopt{entry-sort-fallback} (but it is governed by
6004 \csopt{custom-sort-fallbacks}). This allows \atentry{index} and
6005 \atentry{entry} to have different fallbacks if the \field{sort}
6006 field is missing.
6007 See \sectionref{sec:fallbacks}.
6008
6009 Example:
6010 \begin{codeenv}
6011 \atentry{index}\marg{duck}
6012 \atentry{index}\marg{goose,\field{plural}=\marg{geese}}
6013 \atentry{index}\marg{sealion,\field{name}=\marg{sea lion}}
6014 \atentry{index}\marg{facade,\field{name}=\marg{fa\ics{c}\marg{c}ade}}
6015 \end{codeenv}
6016
6017 Terms that are defined using \atentry{index} will be written to the output
6018 file using the command \gls!{bibglsnewindex}.
6019
6020 \entrysection{indexplural}
6021
6022 The \atentry{indexplural} \gls{entrytype} is similar to the
6023 \atentry{index} \gls{entrytype} except that the \field{name} field, if
6024 missing, is obtained from the \field{plural} field. If the
6025 \field{plural} field is missing it's obtained from the \field{text}
6026 field with the plural suffix appended. If the \field{text} field is
6027 missing, it's obtained from the original entry label. If the
6028 \field{sort} field is missing the default is obtained from the
6029 \field{name} field. (As with \atentry{index}, \atentry{indexplural}
6030 is \emph{not} governed by \csopt{entry-sort-fallback}, but it is
6031 governed by \csopt{custom-sort-fallbacks}.)
6032 See \sectionref{sec:fallbacks}.
6033 All fields are optional. For example:
6034 \begin{codeenv}
6035 \atentry{indexplural}\marg{goose,
6036 \field{plural} = \marg{geese}
6037 }
6038 \strut
6039 \atentry{indexplural}\marg{duck}
6040 \strut
6041 \atentry{indexplural}\marg{chateau,
6042 \field{text} = \marg{ch\ics{cs.circum}ateau},
6043 \field{plural} = \marg{ch\cs{cs.circum}ateaux}
6044 }
6045 \end{codeenv}
6046 This is equivalent to:
6047 \begin{codeenv}
6048 \atentry{indexplural}\marg{goose,
6049 \field{name} = \marg{geese},
6050 \field{text} = \marg{goose},
6051 \field{plural} = \marg{geese}
6052 }
6053 \strut
6054 \atentry{indexplural}\marg{duck,
6055 \field{name} = \marg{ducks},
6056 \field{text} = \marg{duck},
6057 \field{plural} = \marg{ducks}
6058 }
6059 \strut
6060 \atentry{indexplural}\marg{chateau,
6061 \field{name} = \marg{ch\cs{cs.circum}ateaux},
6062 \field{text} = {ch\cs{cs.circum}ateau},
6063 \field{plural} = {ch\cs{cs.circum}ateaux}
6064 }
6065 \end{codeenv}
6066
6067 Terms that are defined using \atentry{indexplural} will be written to the output
6068 file using the command \gls!{bibglsnewindexplural}.
6069
6070 \entrysection{abbreviation}
6071
6072 The \atentry{abbreviation} \gls{entrytype} is designed for abbreviations.
6073 The required fields are \field{short} and \field{long}. If the
6074 \field{sort} key is missing, \bibgls\ will use the field given by
6075 \csopt{abbreviation-sort-fallback}, which defaults to the \field{short} field.
6076 (If you want an equivalent of \gls!{newdualentry}, use
6077 \atentry{dualabbreviationentry} instead.)
6078
6079 If you use \csopt[name]{sort-field} (rather than the default
6080 \csopt[sort]{sort-field}), then the fallback for the
6081 \field{name} field is always the \field{short} field, regardless of
6082 the \csopt{abbreviation-sort-fallback} setting, unless you use
6083 \csopt{abbreviation-name-fallback} to change the fallback for the
6084 \field{name} field.
6085 See \sectionref{sec:fallbacks}.
6086
6087 Note that you must set the abbreviation style before loading the
6088 resource file to ensure that the abbreviations are defined
6089 correctly, however \bibgls\ has no knowledge of the abbreviation
6090 style so it doesn't know if the \field{description} field must be
6091 included or if the default \field{sort} value isn't simply the value
6092 of the \field{short} field.
6093
6094 You can instruct \bibgls\ to sort by the \field{long} field instead
6095 using \csopt[long]{abbreviation-sort-fallback}. You can also tell \bibgls\ to
6096 ignore certain fields using \csopt{ignore-fields}, so you can
6097 include a \field{description} field in the \ext{bib} file if
6098 you sometimes need it, and then instruct \bibgls\ to ignore it when
6099 you don't want it.
6100
6101 For example:
6102 \begin{codeenv}
6103 \atentry{abbreviation}\marg{html,
6104 \field{short} = \marg{html},
6105 \field{long} = \marg{hypertext markup language},
6106 \field{description} = \marg{a markup language for creating web pages}
6107 }
6108 \end{codeenv}
6109 If you want the \abbrstyle{long-noshort-desc} style, then you can put
6110 the following in your document (where the \ext{bib} file is called
6111 \filefmt{entries-abbrv.bib}):
6112 \begin{codeenv}
6113 \ics{setabbreviationstyle}\marg{long-noshort-desc}
6114 \gls{GlsXtrLoadResources}\oarg{\csopt[entries-abbrv]{src},
6115 \csopt[long]{abbreviation-sort-fallback}}
6116 \end{codeenv}
6117 Whereas, if you want the \abbrstyle{long-short-sc} style, then you can
6118 instead do:
6119 \begin{codeenv}
6120 \cs{setabbreviationstyle}\marg{long-short-sc}
6121 \gls{GlsXtrLoadResources}\oarg{\csopt[entries-abbrv]{src},\csopt[description]{ignore-fields}}
6122 \end{codeenv}
6123 or to convert the short value to \idx{uppercase} and use the
6124 \abbrstyle{long-short-sm} style instead:
6125 \begin{codeenv}
6126 \cs{setabbreviationstyle}\marg{long-short-sm}
6127 \gls{GlsXtrLoadResources}\oarg{\csopt[entries-abbrv]{src},
6128 \csopt[uc]{short-case-change},\comment{convert short value to upper case}
6129 \csopt[description]{ignore-fields}}
6130 \end{codeenv}
6131
6132 Case-changing can be applied with \csopt{short-case-change} to
6133 convert the case of the \field{short} field, as illustrated above.
6134 If you use a style that obtains the \field{description} from the
6135 \field{long} form, but you want to apply a case-change to the
6136 \field{description} field with \csopt{description-case-change}, then
6137 you can copy the \field{long} field to the \field{description} with
6138 \csopt[\field{long}=\field{description}]{replicate-fields}.
6139
6140 For example, if \filefmt{entries-abbrv.bib} contains:
6141 \begin{codeenv}
6142 \atentry{abbreviation}\marg{html,
6143 \field{short} = \marg{html},
6144 \field{long} = \marg{hypertext markup language}
6145 }
6146 \end{codeenv}
6147 then the document may include:
6148 \begin{codeenv}
6149 \cs{setabbreviationstyle}\marg{long-short-sc}
6150 \gls{GlsXtrLoadResources}\oarg{\csopt[entries-abbrv]{src},
6151 \csopt[firstuc]{description-case-change},
6152 \csopt[\field{long}=\field{description}]{replicate-fields}}
6153 \end{codeenv}
6154 Note that this can cause a problem for styles that set the
6155 \field{description} field to the \field{long} form encapsulated by a
6156 style command (such as with the \abbrstyle{long-em-short-em} style)
6157 as this will override the style setting.
6158
6159 Similarly, if you want to change the case of the \field{name} field:
6160 \begin{codeenv}
6161 \cs{setabbreviationstyle}\marg{long-short-sc}
6162 \gls{GlsXtrLoadResources}\oarg{\csopt[entries-abbrv]{src},
6163 \csopt[firstuc]{description-case-change},
6164 \csopt[uc]{name-case-change},
6165 \csopt[\field{long}=\field{description},\field{short}=\field{name}]{replicate-fields}}
6166 \end{codeenv}
6167 Again, this will lose any custom formatting command that would
6168 usually be applied by the abbreviation style to the \field{name}
6169 field (and \field{description}, if applicable).
6170
6171 Terms defined using \atentry{abbreviation} will be written to the output
6172 file using the command \gls!{bibglsnewabbreviation}.
6173
6174 \entrysection{acronym}
6175
6176 The \atentry{acronym} \gls{entrytype} is like \atentry{abbreviation} except that
6177 the term is written to the output file using the command
6178 \gls!{bibglsnewacronym}.
6179
6180 \entrysection{contributor}
6181
6182 The \atentry{contributor} \gls{entrytype} is primarily provided for
6183 use by the \atentry{bibtexentry} type. You may use it explicitly if
6184 you want, but you need to take care that it doesn't clash with
6185 \atentry{bibtexentry}. It behaves much like \atentry{index} except
6186 that the term is written to the \ext{glstex} file using the command
6187 \gls!{bibglsnewcontributor}. There are no required fields. As with
6188 \atentry{index}, if the \field{name} field is missing, the fallback
6189 value is the entry's label (see \sectionref{sec:fallbacks}). When
6190 this \gls{entrytype} is automatically created by
6191 \atentry{bibtexentry}, the \field{name} is set to
6192 \begin{codeenv}
6193 \gls{bibglscontributor}\margm{forenames}\margm{von}\margm{surname}\margm{suffix}
6194 \end{codeenv}
6195
6196 If you do explicitly use \atentry{contributor} you need to make sure it's
6197 defined \emph{before} the first instance of \atentry{bibtexentry} that
6198 tries to access it, but within the same resource set. If you ensure that
6199 the label of \atentry{contributor} matches the contributor label generated by
6200 \atentry{bibtexentry} then they can have their dependency lists
6201 updated, and
6202 the \field{bibtexentry} and \field{bibtexentry@entrytype} internal
6203 fields can be set for the
6204 \atentry{contributor} entry. For example:
6205 \begin{codeenv}
6206 \atentry{contributor}\marg{KnuthDonaldE,
6207 \field{name}=\marg{\gls{bibglscontributor}\marg{Donald E.}\marg{}\marg{Knuth}\marg{}},
6208 \field{description}=\marg{Famous mathematician and computer scientist who
6209 created \cmd{TeX}}
6210 }
6211 \strut
6212 @book\marg{texbook,
6213 title = \marg{The {\cmd{TeX} book}},
6214 author = \marg{Donald E. Knuth},
6215 publisher = \marg{Addison-Wesley},
6216 year = 1986
6217 }
6218 \end{codeenv}
6219 The resource options then need to include:
6220 \begin{codeenv}
6221 \csopt[\ics{GlsXtrBibTeXEntryAliases}]{entry-type-aliases},
6222 \csopt[
6223 \marg{[ \cs{cs.string}\csfmt{-}\cs{cs.string}\csfmt{.}]}\marg{}
6224 ]{labelify-replace}
6225 \end{codeenv}
6226
6227 If the \atentry{contributor} entry is deferred until after the
6228 corresponding \atentry{bibtexentry} then you will end up with a label clash.
6229
6230 \subsection{Dual Entry Types}
6231 \label{sec:dualentry}
6232
6233 The \glspl{entrytype} described in this section create two separate (but
6234 related) \styfmt{glossaries-extra} entry definitions per \ext{bib}
6235 entry. The first of these entries is considered the
6236 \igls{primaryentry}, and the second is the \igls{dualentry}.
6237 The naming scheme is \code{@dual}\meta{entry-type} where both the
6238 \primary\ and \dual\ are considered to have the same type of entry
6239 (such as \atentry{dualsymbol} where both the \primary\ and \dual\
6240 are functionally like \atentry{symbol}) or
6241 \code{@dual}\meta{primary}\meta{dual} where the \primary\ is
6242 functionally like \code{@}\meta{primary} and the \dual\ is
6243 functionally like \code{@}\meta{dual}.
6244
6245 If you need a field to store the \glsdisp{dualentry}{dual}
6246 description in (and you're not simply swapping known fields around),
6247 then you can use the special \field{dualdescription} field and add
6248 it to your map.
6249
6250 If the fields provided by the \isty{glossaries-prefix} are defined,
6251 there will be additional mappings for the special internal fields
6252 \field{dualprefix}, \field{dualprefixfirst},
6253 \field{dualprefixplural}, and \field{dualprefixfirstplural}.
6254
6255 For example:
6256 \begin{codeenv}
6257 \atentry{dualabbreviationentry}\marg{svm,
6258 \field{short} = \marg{SVM},
6259 \field{long} = \marg{support vector machine},
6260 \field{description} = \marg{statistical pattern recognition technique}
6261 }
6262 \end{codeenv}
6263 is like:
6264 \begin{codeenv}
6265 \atentry{abbreviation}\marg{svm,
6266 \field{short} = \marg{SVM},
6267 \field{long} = \marg{support vector machine},
6268 }
6269 \atentry{entry}\marg{dual.svm,
6270 \field{text} = \marg{SVM},
6271 \field{name} = \marg{support vector machine},
6272 \field{description} = \marg{statistical pattern recognition technique}
6273 }
6274 \end{codeenv}
6275 and is analogous to:
6276 \begin{codeenv}
6277 \gls{newabbreviation}\marg{svm}\marg{SVM}\marg{support vector machine}
6278 \gls{newglossaryentry}\marg{dual.svm}\marg{\field{name}=\marg{support vector machine},\field{text}=\marg{SVM},
6279 \field{description}=\marg{statistical pattern recognition technique}}
6280 \end{codeenv}
6281 but both entries are considered dependent on each other. This means
6282 that if you only reference the \gls{primaryentry} (using \ics{gls} etc)
6283 then the \gls{dualentry} will still be selected if the \csopt{selection}
6284 setting includes dependencies.
6285
6286 The creation of the \gls{dualentry} involves mapping or copying
6287 fields from the \gls{primaryentry}. Each \gls{dualentry} type has a
6288 set of mappings. If a field in the set of mappings is missing, its
6289 fallback value is used (see \sectionref{sec:fallbacks}). Any fields
6290 that aren't listed in the mappings are simply copied, except for the
6291 \field{alias} field, which will never be copied to the
6292 \gls{dualentry}, nor can it be mapped. The alias will only apply to
6293 the \gls{primaryentry}. The \gls{dualentry} is given the label
6294 \meta{prefix}\meta{id} where \meta{prefix} is set by the
6295 \csopt{dual-prefix} option and \meta{id} is the label supplied in
6296 the \ext{bib} file.
6297
6298 If \csopt[combine]{dual-sort} then the \glspl{dualentry} will be sorted
6299 along with the \glspl{primaryentry}, otherwise the \csopt{dual-sort}
6300 indicates how to sort the dual entries and the dual entries will be
6301 appended to the end of the \ext{glstex} file. The
6302 \csopt{dual-sort-field} determines what field to use for the sort
6303 value if the dual entries should be sorted separately.
6304
6305 Take care if you have a mixture of \glspl{entrytype} (such as
6306 \atentry{dualindexentry}, \atentry{dualindexsymbol}
6307 and \atentry{index}) and you're not
6308 using the default \csopt[combine]{dual-sort}. Remember that the
6309 \glspl{primaryentry} are all sorted together along with the single
6310 entries types described in \sectionref{sec:dualentry} (but they may
6311 be assigned to different glossary types), and then the dual entries
6312 are sorted together (but may be assigned to different glossary
6313 types). This may result in an odd ordering if some of the primaries
6314 and some of the duals are assigned to the same glossary. For
6315 example, don't mix \atentry{dualindexabbreviation} (duals are
6316 abbreviations) with \atentry{dualabbreviationentry} (primaries
6317 are abbreviations) when you aren't using \csopt[combine]{dual-sort}
6318 (unless you have two different glossaries for the \primary\ vs
6319 \dual\ abbreviations).
6320
6321 Remember that \bibgls\ is designed to take advantage of
6322 \ics{printunsrtglossary}, which simply iterates over all defined
6323 entries in the order in which they were defined (or, more precisely,
6324 the order of the internal list of entry labels associated with that
6325 glossary). The aim of \bibgls\ is to write the entry definitions to
6326 the \ext{glstex} file so that the internal list of labels is in the
6327 appropriate order.
6328
6329 For example, suppose the file \filefmt{entries.bib} contains:
6330 \begin{codeenv}
6331 \atentry{index}\marg{aardvark}
6332 \atentry{index}\marg{mouse}
6333 \atentry{index}\marg{zebra}
6334 \atentry{dualindexabbreviation}\marg{xml,
6335 \field{short}=\marg{XML},
6336 \field{long}=\marg{extensible markup language}
6337 }
6338 \atentry{dualabbreviationentry}\marg{ssi,
6339 \field{short}=\marg{SSI},
6340 \field{long}=\marg{server-side includes},
6341 \field{description}=\marg{directives placed in \cs{gls}\marg{html} pages
6342 evaluated by the server}
6343 }
6344 \atentry{dualindexabbreviation}\marg{html,
6345 \field{short}=\marg{HTML},
6346 \field{long}=\marg{hypertext markup language}
6347 }
6348 \atentry{dualabbreviationentry}\marg{css,
6349 \field{short}=\marg{CSS},
6350 \field{long}=\marg{cascading stylesheets},
6351 \field{description}=\marg{a language that describes the style of an
6352 \cs{gls}\marg{html} document}
6353 }
6354 \end{codeenv}
6355 This contains a mixture of \glspl{entrytype}, including
6356 \atentry{dualindexabbreviation} (where the \dual\ is the
6357 abbreviation) and \atentry{dualabbreviationentry} (where the
6358 \primary\ is the abbreviation).
6359
6360 Now consider the following document:
6361 \begin{codeenv}
6362 \cmd{documentclass}\marg{article}
6363 \strut
6364 \cmd{usepackage}[\styopt{record},\styopt{abbreviations}]\marg{glossaries-extra}
6365 \strut
6366 \gls{GlsXtrLoadResources}\oarg{\csopt[all]{selection},\csopt[entries]{src}}
6367 \strut
6368 \cmd{begin}\marg{document}
6369 \cs{printunsrtglossaries}
6370 \cmd{end}\marg{document}
6371 \end{codeenv}
6372 This uses the default \csopt[combine]{sort}, so all the entries are
6373 sorted together, resulting in the order:
6374 \code{aardvark},
6375 \code{dual.css},
6376 \code{css},
6377 \code{html},
6378 \code{dual.html},
6379 \code{mouse},
6380 \code{dual.ssi},
6381 \code{ssi},
6382 \code{xml},
6383 \code{dual.xml},
6384 \code{zebra}.
6385
6386 The \LaTeX\ code written to the \iext{glstex} file is essentially
6387 (but not exactly):
6388 \begin{codeenv}
6389 \comment{from \atentry{index}\marg{aardvark}:}
6390 \gls{newglossaryentry}\marg{aardvark}\marg{\field{name}=\marg{aardvark},\field{description}=\marg{}}
6391 \strut
6392 \comment{\dual\ of \atentry{dualabbreviationentry}\marg{css,\ldots}:}
6393 \gls{newglossaryentry}\marg{dual.css}\marg{\field{name}=\marg{cascading stylesheets},\marg{text}=\marg{CSS},
6394 \field{description}=\marg{a language that describes the style of an
6395 \cs{glsxtrshort}\marg{html} document}}
6396 \strut
6397 \comment{\primary\ of \atentry{dualabbreviationentry}\marg{css,\ldots}:}
6398 \gls{newabbreviation}\marg{css}\marg{CSS}\marg{cascading stylesheets}
6399 \strut
6400 \comment{\primary\ of \atentry{dualindexabbreviation}\marg{html,\ldots}:}
6401 \gls{newglossaryentry}\marg{html}\marg{\field{name}=\marg{HTML},\field{description}=\marg{}}
6402 \strut
6403 \comment{\dual\ of \atentry{dualindexabbreviation}\marg{html,\ldots}:}
6404 \gls{newabbreviation}\marg{dual.html}\marg{HTML}\marg{hypertext markup language}
6405 \strut
6406 \comment{from \atentry{index}\marg{mouse}:}
6407 \gls{newglossaryentry}\marg{mouse}\marg{\marg{name}=\marg{mouse},\field{description}=\marg{}}
6408 \strut
6409 \comment{\dual\ of \atentry{dualabbreviationentry}\marg{ssi,\ldots}:}
6410 \gls{newglossaryentry}\marg{dual.ssi}\marg{\field{name}=\marg{server-side includes},\field{text}=\marg{SSI},
6411 \field{description}=\marg{directives placed in \cs{glsxtrshort}\marg{html} pages
6412 evaluated by the server}}
6413 \strut
6414 \comment{\primary\ of \atentry{dualabbreviationentry}\marg{ssi,\ldots}:}
6415 \gls{newabbreviation}\marg{ssi}\marg{SSI}\marg{server-side includes}
6416 \strut
6417 \comment{\primary\ of \atentry{dualindexabbreviation}\marg{xml,\ldots}:}
6418 \gls{newglossaryentry}\marg{xml}\marg{\field{name}=\marg{XML},\field{description}=\marg{}}
6419 \strut
6420 \comment{\dual\ of \atentry{dualindexabbreviation}\marg{xml,\ldots}:}
6421 \gls{newabbreviation}\marg{dual.xml}\marg{XML}\marg{extensible markup language}
6422 \strut
6423 \comment{from \atentry{index}\marg{zebra}:}
6424 \gls{newglossaryentry}\marg{zebra}\marg{\field{name}=\marg{zebra},\field{description}=\marg{}}
6425 \end{codeenv}
6426 Since the document uses the \styopt{abbreviations} package option,
6427 \gls{newabbreviation} automatically assigns the abbreviation
6428 to the \code{abbreviations} glossary (created through that package
6429 option). This means that the \glsdisp{mainglossary}{\code{main} (default) glossary}
6430 contains the entries (in order):
6431 \begin{itemize}
6432 \item \code{aardvark} (name: aardvark),
6433 \item \code{dual.css} (name: cascading stylesheets),
6434 \item \code{html} (name: HTML),
6435 \item \code{mouse} (name: mouse),
6436 \item \code{dual.ssi} (name: server-side includes),
6437 \item \code{xml} (name: XML),
6438 \item \code{zebra} (name: zebra).
6439 \end{itemize}
6440 The \code{abbreviations} glossary contains:
6441 \begin{itemize}
6442 \item \code{css} (short: CSS),
6443 \item \code{dual.html} (short: HTML),
6444 \item \code{ssi} (short: SSI),
6445 \item \code{dual.xml} (short: XML).
6446 \end{itemize}
6447
6448 Since all the entries were combined and sorted together, the
6449 resulting glossaries are both ordered alphabetically (using
6450 \field{short} for the abbreviations and \field{name} for the rest),
6451 but note that you need to take care when referencing the
6452 abbreviations if you want to make use of the abbreviation style. You
6453 need \verb|\gls{css}| and \verb|\gls{ssi}| for the \primary\
6454 abbreviations created with \atentry{dualabbreviationentry} and
6455 \verb|\gls{dual.html}| and \verb|\gls{dual.xml}| for the \dual\
6456 abbreviations created with \atentry{dualindexabbreviation}. Also
6457 the \field{name} of the \primary\slash \dual\ alternative of the
6458 abbreviations is also inconsistent (short form for \code{html} and
6459 \code{xml} and long form for \code{dual.css} and \code{dual.ssi}),
6460 as different field mappings are used.
6461
6462 If the document is changed so that the \glspl{dualentry} are now
6463 sorted and written after all the \glspl{primaryentry} have been dealt
6464 with:
6465 \begin{codeenv}
6466 \gls{GlsXtrLoadResources}\oarg{
6467 \csopt[entries]{src},
6468 \csopt[letter-nocase]{dual-sort},
6469 \csopt[all]{selection}
6470 }
6471 \end{codeenv}
6472 then \bibgls\ first orders the \glsdisp{primaryentry}{primaries}:
6473 \begin{itemize}
6474 \item \code{aardvark} (name: aardvark),
6475 \item \code{css} (short: CSS),
6476 \item \code{html} (name: HTML),
6477 \item \code{mouse} (name: mouse),
6478 \item \code{ssi} (short: SSI),
6479 \item \code{xml} (name: XML),
6480 \item \code{zebra} (name: zebra)
6481 \end{itemize}
6482 and writes them to the \ext{glstex} file
6483 (functionally like):
6484 \begin{codeenv}
6485 \comment{from \atentry{index}\marg{aardvark}:}
6486 \gls{newglossaryentry}\marg{aardvark}\marg{\field{name}=\marg{aardvark},\field{description}=\marg{}}
6487 \strut
6488 \comment{\primary\ of \atentry{dualabbreviationentry}\marg{css,\ldots}:}
6489 \gls{newabbreviation}\marg{css}\marg{CSS}\marg{cascading stylesheets}
6490 \strut
6491 \comment{\primary\ of \atentry{dualindexabbreviation}\marg{html,\ldots}:}
6492 \gls{newglossaryentry}\marg{html}\marg{\field{name}=\marg{HTML},\field{description}=\marg{}}
6493 \strut
6494 \comment{from \atentry{index}\marg{mouse}:}
6495 \gls{newglossaryentry}\marg{mouse}\marg{\field{name}=\marg{mouse},\field{description}=\marg{}}
6496 \strut
6497 \comment{\primary\ of \atentry{dualabbreviationentry}\marg{ssi,\ldots}:}
6498 \gls{newabbreviation}\marg{ssi}\marg{SSI}\marg{server-side includes}
6499 \strut
6500 \comment{\primary\ of \atentry{dualindexabbreviation}\marg{xml,\ldots}:}
6501 \gls{newglossaryentry}\marg{xml}\marg{\field{name}=\marg{XML},\field{description}=\marg{}}
6502 \strut
6503 \comment{from \atentry{index}\marg{zebra}:}
6504 \gls{newglossaryentry}\marg{zebra}\marg{\field{name}=\marg{zebra},\field{description}=\marg{}}
6505 \end{codeenv}
6506 Then \bibgls\ orders the \glsdisp{dualentry}{duals}:
6507 \begin{itemize}
6508 \item \code{dual.css} (name: cascading stylesheets),
6509 \item \code{dual.html} (short: HTML),
6510 \item \code{dual.ssi} (name: server-side includes),
6511 \item \code{dual.xml} (short: XML)
6512 \end{itemize}
6513 and writes them to the \ext{glstex} file
6514 (functionally like):
6515 \begin{codeenv}
6516 \comment{\dual\ of \atentry{dualabbreviationentry}\marg{css,\ldots}:}
6517 \gls{newglossaryentry}\marg{dual.css}\marg{\field{name}=\marg{cascading stylesheets},\field{text}=\marg{CSS},
6518 \field{description}=\marg{a language that describes the style of an
6519 \cs{glsxtrshort}\marg{html} document}}
6520 \strut
6521 \comment{\dual\ of \atentry{dualindexabbreviation}\marg{html,\ldots}:}
6522 \gls{newabbreviation}\marg{dual.html}\marg{HTML}\marg{hypertext markup language}
6523 \strut
6524 \comment{\dual\ of \atentry{dualabbreviationentry}\marg{ssi,\ldots}:}
6525 \gls{newglossaryentry}\marg{dual.ssi}\marg{\field{name}=\marg{server-side includes},\field{text}=\marg{SSI},
6526 \field{description}=\marg{directives placed in \cs{glsxtrshort}\marg{html} pages
6527 evaluated by the server}}
6528 \strut
6529 \comment{\dual\ of \atentry{dualindexabbreviation}\marg{xml,\ldots}:}
6530 \gls{newabbreviation}\marg{dual.xml}\marg{XML}\marg{extensible markup language}
6531 \end{codeenv}
6532 When the \ext{glstex} file is input (during the next \LaTeX\ run)
6533 the entries are defined in the order:
6534 \begin{enumerate}
6535 \item \code{aardvark} (type: \code{main}),
6536 \item \code{css} (type: \code{abbreviations}),
6537 \item \code{html} (type: \code{main}),
6538 \item \code{mouse} (type: \code{main}),
6539 \item \code{ssi} (type: \code{abbreviations}),
6540 \item \code{xml} (type: \code{main}),
6541 \item \code{zebra} (type: \code{main}),
6542 \item \code{dual.css} (type: \code{main}),
6543 \item \code{dual.html} (type: \code{abbreviations}),
6544 \item \code{dual.ssi} (type: \code{main}),
6545 \item \code{dual.xml} (type: \code{abbreviations}).
6546 \end{enumerate}
6547 This means that the \glsdisp{mainglossary}{\code{main} glossary's} internal list is in the
6548 order:
6549 \begin{itemize}
6550 \item \code{aardvark} (aardvark),
6551 \item \code{html} (HTML),
6552 \item \code{mouse} (mouse),
6553 \item \code{xml} (XML),
6554 \item \code{zebra} (zebra),
6555 \item \code{dual.css} (cascading stylesheets),
6556 \item \code{dual.ssi} (server-side includes)
6557 \end{itemize}
6558 and the \code{abbreviations} glossary's internal list is in the order:
6559 \begin{itemize}
6560 \item \code{css} (CSS),
6561 \item \code{ssi} (SSI),
6562 \item \code{dual.html} (HTML),
6563 \item \code{dual.xml} (XML).
6564 \end{itemize}
6565 The lists are no longer in alphabetical order as they have a mixture
6566 of \primary\ and \dual\ entries that were separated before sorting.
6567
6568 The above is a fairly contrived example as it wouldn't make sense
6569 in a real document to have glossary terms (that include a
6570 description) mixed with index terms (that don't include a
6571 description).
6572 A better solution would be to use
6573 \atentry{tertiaryindexabbreviationentry} instead of
6574 \atentry{dualabbreviationentry}.
6575
6576 \entrysection{dualentry}
6577
6578 The \atentry{dualentry} \gls{entrytype} is similar to \atentry{entry} but
6579 actually defines two entries.
6580 The \gls{dualentry} contains the same information as the \gls{primaryentry}
6581 but some of the fields are swapped around.
6582 The default mappings are:
6583 \begin{itemize}
6584 \item \field{name} $\mapsto$ \field{description}
6585 \item \field{plural} $\mapsto$ \field{descriptionplural}
6586 \item \field{description} $\mapsto$ \field{name}
6587 \item \field{descriptionplural} $\mapsto$ \field{plural}
6588 \end{itemize}
6589 If the prefix fields are defined, then the default mappings
6590 additionally include:
6591 \begin{itemize}
6592 \item \field{prefix} $\mapsto$ \field{dualprefix}
6593 \item \field{prefixplural} $\mapsto$ \field{dualprefixplural}
6594 \item \field{prefixfirst} $\mapsto$ \field{dualprefixfirst}
6595 \item \field{prefixfirstplural} $\mapsto$ \field{dualprefixfirstplural}
6596 \item \field{dualprefix} $\mapsto$ \field{prefix}
6597 \item \field{dualprefixplural} $\mapsto$ \field{prefixplural}
6598 \item \field{dualprefixfirst} $\mapsto$ \field{prefixfirst}
6599 \item \field{dualprefixfirstplural} $\mapsto$ \field{prefixfirstplural}
6600 \end{itemize}
6601 The required fields are as for \atentry{entry}.
6602
6603 For example:
6604 \begin{codeenv}
6605 \atentry{dualentry}\marg{child,
6606 \field{name}=\marg{child},
6607 \field{plural}=\marg{children},
6608 \field{description}=\marg{enfant}
6609 }
6610 \end{codeenv}
6611 is like:
6612 \begin{codeenv}
6613 \atentry{entry}\marg{child,
6614 \field{name}=\marg{child},
6615 \field{plural}=\marg{children},
6616 \field{description}=\marg{enfant}
6617 \field{descriptionplural}=\marg{enfants}
6618 }
6619 \strut
6620 \atentry{entry}\marg{dual.child,
6621 \field{description}=\marg{child},
6622 \field{descriptionplural}=\marg{children},
6623 \field{name}=\marg{enfant}
6624 \field{plural}=\marg{enfants}
6625 }
6626 \end{codeenv}
6627 where \idprefix{dual} is replaced by the value of the
6628 \csopt{dual-prefix} option. However, instead of defining the entries
6629 with \csfmt{bibglsnewentry} both the \primary\ and \dual\ entries are
6630 defined using \gls!{bibglsnewdualentry}. The \field{category}
6631 and \field{type} fields can be set for the \gls{dualentry} using the
6632 \csopt{dual-category} and \csopt{dual-type} options.
6633
6634 For example:
6635 \begin{codeenv}
6636 \cs{newglossary*}\marg{english}\marg{English}
6637 \cs{newglossary*}\marg{french}\marg{French}
6638 \strut
6639 \gls{GlsXtrLoadResources}\oarg{
6640 \csopt[entries-dual]{src},\comment{data in entries-dual.bib}
6641 \csopt[english]{type},\comment{put \glspl{primaryentry} in glossary 'english'}
6642 \csopt[french]{dual-type},\comment{put \glspl{dualentry} in glossary 'french'}
6643 \csopt[dictionary]{category},\comment{set the \primary\ category to 'dictionary'}
6644 \csopt[dictionary]{dual-category},\comment{set the \dual\ category to 'dictionary'}
6645 \csopt[en]{sort},\comment{sort \glspl{primaryentry} according to language 'en'}
6646 \csopt[fr]{dual-sort}\comment{sort \glspl{dualentry} according to language 'fr'}
6647 }
6648 \end{codeenv}
6649
6650 If you need to keep the same name but have different descriptions
6651 then you can use \field{dualdescription} and set up a mapping to use
6652 it. For example:
6653 \begin{codeenv}
6654 \atentry{dualentry}\marg{sample,
6655 \field{name}=\marg{sample},
6656 \field{description}=\marg{\primary\ sample description},
6657 \field{dualdescription}=\marg{\dual\ sample description}
6658 }
6659 \end{codeenv}
6660 The mapping can then be:
6661 \begin{codeenv}
6662 \csopt[\marg{\field{description}},
6663 \marg{\field{dualdescription}}]{dual-entry-map}
6664 \end{codeenv}
6665
6666 \entrysection{dualindexentry}
6667
6668 There are no required fields. The \gls{primaryentry} behaves like
6669 \atentry{index} and the \gls{dualentry} behaves
6670 like \atentry{entry}. The default field mapping is:
6671 \begin{itemize}
6672 \item \field{name} $\mapsto$ \field{name}
6673 \end{itemize}
6674 If the prefix fields are defined, then the default mappings
6675 additionally include:
6676 \begin{itemize}
6677 \item \field{prefix} $\mapsto$ \field{dualprefix}
6678 \item \field{prefixplural} $\mapsto$ \field{dualprefixplural}
6679 \item \field{prefixfirst} $\mapsto$ \field{dualprefixfirst}
6680 \item \field{prefixfirstplural} $\mapsto$ \field{dualprefixfirstplural}
6681 \item \field{dualprefix} $\mapsto$ \field{prefix}
6682 \item \field{dualprefixplural} $\mapsto$ \field{prefixplural}
6683 \item \field{dualprefixfirst} $\mapsto$ \field{prefixfirst}
6684 \item \field{dualprefixfirstplural} $\mapsto$ \field{prefixfirstplural}
6685 \end{itemize}
6686 This doesn't actually perform any swapping of fields, but it
6687 provides the field used for backlinks (if
6688 \csopt{dual-indexentry-backlink} is set). The reason that the
6689 \primary\ (rather than the \dual) is like \atentry{index} is to allow the
6690 primaries to merge with any \atentry{index} entries found in the
6691 resource set, since glossary entries with descriptions are likely to
6692 be a subset of all indexed entries.
6693
6694 If no \field{name} is given, the \gls{dualentry} is assigned the
6695 (unprefixed) entry label. For example:
6696 \begin{codeenv}
6697 \atentry{dualindexentry}\marg{array,
6698 \field{description}=\marg{ordered list of values}
6699 }
6700 \end{codeenv}
6701 This is effectively like:
6702 \begin{codeenv}
6703 \atentry{index}\marg{array}
6704 \strut
6705 \atentry{entry}\marg{dual.array,
6706 \field{name}=\marg{array},
6707 \field{description}=\marg{ordered list of values}
6708 }
6709 \end{codeenv}
6710 The \glspl{primaryentry} are defined using
6711 \gls!{bibglsnewdualindexentry},
6712 which by default sets the \field{category} to \optfmt{index}
6713 (although this may be overridden, for example, by the \csopt{category} option).
6714 The \glspl{dualentry} are defined with
6715 \gls!{bibglsnewdualindexentrysecondary}.
6716
6717 This is the most convenient way of having an entry that's also
6718 automatically indexed. For example, suppose the file
6719 \filefmt{terms.bib} contains:
6720 \begin{codeenv}
6721 \atentry{index}\marg{duck}
6722 \atentry{index}\marg{zebra}
6723 \atentry{index}\marg{aardvark}
6724 \end{codeenv}
6725 and suppose the file \filefmt{entries.bib} contains:
6726 \begin{codeenv}
6727 \atentry{dualindexentry}\marg{array,
6728 \field{description}=\marg{ordered list of values}
6729 }
6730 \strut
6731 \atentry{dualindexentry}\marg{vector,
6732 \field{name}=\marg{vector},
6733 \field{description}=\marg{column or row of values}
6734 }
6735 \strut
6736 \atentry{dualindexentry}\marg{set,
6737 \field{description}=\marg{collection of values}
6738 }
6739 \strut
6740 \atentry{dualindexentry}\marg{matrix,
6741 \field{plural}=\marg{matrices},
6742 \field{description}=\marg{rectangular array of values}
6743 }
6744 \end{codeenv}
6745 These entries can be used in an example document that has an
6746 index and a glossary:
6747 \begin{codeenv}
6748 \cmd{documentclass}\marg{article}
6749 \strut
6750 \cmd{usepackage}[colorlinks]\marg{hyperref}
6751 \cmd{usepackage}[\styopt{record},\styopt{index},\styopt[mcols]{stylemods}]\marg{glossaries-extra}
6752 \strut
6753 \gls{GlsXtrLoadResources}\oarg{
6754 \csopt[terms,entries]{src},
6755 \csopt[index]{type},
6756 \csopt[idx.]{label-prefix},
6757 \csopt[gls.]{dual-prefix},
6758 \csopt[primary]{combine-dual-locations},
6759 \csopt[main]{dual-type}
6760 }
6761 \strut
6762 \cmd{begin}\marg{document}
6763 \cs{gls}\marg{gls.array}, \cs{gls}\marg{gls.vector}, \cs{gls}\marg{gls.set}, \cs{gls}\marg{gls.matrix}.
6764 \strut
6765 \cs{gls}\marg{idx.duck}, \cs{gls}\marg{idx.aardvark}, \cs{gls}\marg{idx.zebra}.
6766 \strut
6767 \cs{renewcommand}\marg{\cs{glstreenamefmt}}[1]\marg{\ics{textsc}\marg{\idx{param}1}}
6768 \cs{printunsrtglossary}\oarg{\printglossopt[main]{type},\printglossopt[index]{style},\iprintglossopt{nogroupskip}}
6769 \strut
6770 \cs{renewcommand}\marg{\cs{glstreenamefmt}}[1]\marg{\idx{param}1}
6771 \cs{renewcommand}\marg{\cs{glstreegroupheaderfmt}}[1]\marg{\cs{textbf}\marg{\idx{param}1}}
6772 \cs{printunsrtglossary}\oarg{\printglossopt[index]{type},\printglossopt[mcolindexgroup]{style}}
6773 \cmd{end}\marg{document}
6774 \end{codeenv}
6775 This uses \csopt{combine-dual-locations} to combine the \glspl{location}
6776 for the \primary\ and \dual\ entries so that they only appear in the
6777 index.
6778
6779 To avoid the inconvenience of remembering which prefix to use, you can
6780 set up the prefixes with \ics{glsxtraddlabelprefix} and reference entries
6781 with \ics{dgls}, \ics{dGls} etc instead of \cs{gls}, \cs{Gls} etc.
6782
6783 \entrysection{dualindexabbreviation}
6784
6785 The \atentry{dualindexabbreviation} \gls{entrytype} is similar to
6786 \atentry{dualindexentry} and again, by default, the
6787 field mapping is:
6788 \begin{itemize}
6789 \item \field{name} $\mapsto$ \field{name}
6790 \end{itemize}
6791 If the prefix fields are defined, then the default mappings
6792 additionally include:
6793 \begin{itemize}
6794 \item \field{prefix} $\mapsto$ \field{dualprefix}
6795 \item \field{prefixplural} $\mapsto$ \field{dualprefixplural}
6796 \item \field{prefixfirst} $\mapsto$ \field{dualprefixfirst}
6797 \item \field{prefixfirstplural} $\mapsto$ \field{dualprefixfirstplural}
6798 \item \field{dualprefix} $\mapsto$ \field{prefix}
6799 \item \field{dualprefixplural} $\mapsto$ \field{prefixplural}
6800 \item \field{dualprefixfirst} $\mapsto$ \field{prefixfirst}
6801 \item \field{dualprefixfirstplural} $\mapsto$ \field{prefixfirstplural}
6802 \end{itemize}
6803 However in this case the required fields are \field{short} and
6804 \field{long}. The \field{name} for the \gls{primaryentry} defaults to
6805 \field{short} if omitted. (This may be changed with the
6806 \csopt{abbreviation-name-fallback} option.) The fallback for the
6807 \field{sort} field is given by \csopt{abbreviation-sort-fallback},
6808 which defaults to the \field{short} field (see \sectionref{sec:fallbacks}).
6809
6810 For example:
6811 \begin{codeenv}
6812 \atentry{dualindexabbreviation}\marg{html,
6813 \field{short} = \marg{HTML},
6814 \field{long} = \marg{hypertext markup language}
6815 }
6816 \end{codeenv}
6817 is like:
6818 \begin{codeenv}
6819 \atentry{index}\marg{html,\field{name}=\marg{HTML}}
6820 \strut
6821 \atentry{abbreviation}\marg{dual.html,
6822 \field{short} = \marg{HTML},
6823 \field{long} = \marg{hypertext markup language}
6824 }
6825 \end{codeenv}
6826 The \primary\ term is defined using
6827 \gls!{bibglsnewdualindexabbreviation}, which encapsulates the
6828 \field{name} to match the font used by
6829 the \dual\ abbreviation. The encapsulation command depends
6830 on the \csopt{abbreviation-name-fallback} value. If it's
6831 the \field{short} field then \gls{bibglsuseabbrvfont} is
6832 used, otherwise \gls{bibglsuselongfont} is used.
6833
6834 The \primary\ definition also
6835 by default sets the \field{category} to \optfmt{index} (although
6836 this again may be overridden).
6837 The \dual\ term is defined using
6838 \gls!{bibglsnewdualindexabbreviationsecondary}.
6839
6840 \entrysection{dualindexsymbol}
6841
6842 The \atentry{dualindexsymbol} \gls{entrytype} is similar to
6843 \atentry{dualindexentry}, but by default the
6844 field mappings are:
6845 \begin{itemize}
6846 \item \field{symbol} $\mapsto$ \field{name}
6847 \item \field{name} $\mapsto$ \field{symbol}
6848 \item \field{symbolplural} $\mapsto$ \field{plural}
6849 \item \field{plural} $\mapsto$ \field{symbolplural}
6850 \end{itemize}
6851 If the prefix fields are defined, then the default mappings
6852 additionally include:
6853 \begin{itemize}
6854 \item \field{prefix} $\mapsto$ \field{dualprefix}
6855 \item \field{prefixplural} $\mapsto$ \field{dualprefixplural}
6856 \item \field{prefixfirst} $\mapsto$ \field{dualprefixfirst}
6857 \item \field{prefixfirstplural} $\mapsto$ \field{dualprefixfirstplural}
6858 \item \field{dualprefix} $\mapsto$ \field{prefix}
6859 \item \field{dualprefixplural} $\mapsto$ \field{prefixplural}
6860 \item \field{dualprefixfirst} $\mapsto$ \field{prefixfirst}
6861 \item \field{dualprefixfirstplural} $\mapsto$ \field{prefixfirstplural}
6862 \end{itemize}
6863 The required field is: \field{symbol}.
6864 If the \field{name} field is omitted, the \dual\ entry is assigned a
6865 symbol from the original (unprefixed) label.
6866 The \glspl{primaryentry} are defined using
6867 \gls!{bibglsnewdualindexsymbol},
6868 which by default sets the \field{category} to \optfmt{index},
6869 and the \glspl{dualentry} are defined using
6870 \gls!{bibglsnewdualindexsymbolsecondary},
6871 which by default sets the \field{category} to \optfmt{symbol}.
6872 For example:
6873 \begin{codeenv}
6874 \atentry{dualindexsymbol}\marg{pi,
6875 \field{symbol}=\marg{\cs{ensuremath}\marg{\ics{pi}}},
6876 \field{description}=\marg{ratio of a circle's circumference to its diameter}
6877 }
6878 \end{codeenv}
6879 is like:
6880 \begin{codeenv}
6881 \atentry{index}\marg{pi,\field{symbol}=\marg{\cs{ensuremath}\marg{\cs{pi}}}}
6882 \strut
6883 \atentry{symbol}\marg{dual.pi,
6884 \field{name}=\marg{\cs{ensuremath}\marg{\cs{pi}}},
6885 \field{symbol}=\marg{pi},
6886 \field{description}=\marg{ratio of a circle's circumference to its diameter}
6887 }
6888 \end{codeenv}
6889
6890 For example, suppose I have a file called \filefmt{symbols.bib} that
6891 contains:
6892 \begin{codeenv}
6893 \atentry{dualindexsymbol}\marg{pi,
6894 \field{symbol}=\marg{\cs{ensuremath}\marg{\cs{pi}}},
6895 \field{description}=\marg{ratio of a circle's circumference to its diameter}
6896 }
6897 \strut
6898 \atentry{dualindexsymbol}\marg{e,
6899 \field{name}=\marg{Euler's number},
6900 \field{symbol}=\marg{\cs{ensuremath}\marg{e}},
6901 \field{description}=\marg{base of the natural logarithm}
6902 }
6903 \end{codeenv}
6904 Then the previous example document can be modified to have an index,
6905 a glossary and a list of symbols:
6906 \begin{codeenv}
6907 \cmd{documentclass}\marg{report}
6908 \strut
6909 \cmd{usepackage}[colorlinks]\marg{hyperref}
6910 \cmd{usepackage}[\styopt{record},\styopt{symbols},\styopt{index},\styopt[mcols]{stylemods}]\marg{glossaries-extra}
6911 \strut
6912 \cs{newcommand}\marg{\gls{bibglsnewdualindexsymbolsecondary}}[5]\marg{\comment{}
6913 \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{category}=symbol,\comment{}
6914 \field{symbol}=\marg{\idx{param}4},\idx{param}2,\field{type}=\marg{symbols}}\marg{\idx{param}5}\comment{}
6915 }
6916 \strut
6917 \cs{newcommand}\marg{\cmd{indexprimary}}[1]\marg{\ics{glsadd}\oarg{\glsaddopt[\encap{hyperbf}]{format}}\marg{idx.\idx{param}1}}
6918 \strut
6919 \cs{glsdefpostdesc}\marg{symbol}\marg{\cmd{indexprimary}\marg{\cs{glscurrententrylabel}}}
6920 \cs{glsdefpostdesc}\marg{general}\marg{\cmd{indexprimary}\marg{\cs{glscurrententrylabel}}}
6921 \strut
6922 \gls{GlsXtrLoadResources}\oarg{
6923 \csopt[entries,terms,symbols]{src},
6924 \csopt[index]{type},
6925 \csopt{set-widest},
6926 \csopt[idx.]{label-prefix},
6927 \csopt[\empty]{dual-prefix},
6928 \csopt[primary]{combine-dual-locations},
6929 \csopt[letter-case]{dual-sort},
6930 \csopt[main]{dual-type}
6931 }
6932 \strut
6933 \gls{glsxtrnewglslike}\oarg{\glsopt[false]{hyper}}\marg{idx.}\marg{\cmd{idx}}\marg{\cmd{idxpl}}\marg{\cmd{Idx}}\marg{\cmd{Idxpl}}
6934 \strut
6935 \cmd{begin}\marg{document}
6936 \cs{gls}\marg{array}, \cs{gls}\marg{vector}, \cs{gls}\marg{set}, \cs{glspl}\marg{matrix}.
6937 \cmd{idx}\marg{duck}, \cmd{idx}\marg{aardvark}, \cmd{idx}\marg{zebra}.
6938 \cs{gls}\marg{e} and \cs{gls}\marg{pi}.
6939 \strut
6940 \cmd{newpage}
6941 \cs{gls}\marg{array}, \cmd{idx}\marg{vector}, \cmd{idx}\marg{set}, \cs{gls}\marg{matrix}.
6942 \strut
6943 \cmd{newpage}
6944 \cs{gls}\marg{array}, \cs{gls}\marg{vector}, \cs{gls}\marg{set}, \cs{gls}\marg{matrix}.
6945 \strut
6946 \cs{renewcommand}\marg{\cs{glstreenamefmt}}[1]\marg{\cs{textsc}\marg{\idx{param}1}}
6947 \cs{printunsrtglossary}\oarg{\printglossopt[main]{type},\printglossopt{nogroupskip},\printglossopt[\glostyle{alttree}]{style}}
6948 \strut
6949 \cs{renewcommand}\marg{\cs{glstreenamefmt}}[1]\marg{\idx{param}1}
6950 \cs{printunsrtglossary}\oarg{\printglossopt[symbols]{type},\printglossopt{nogroupskip},\printglossopt[index]{style}}
6951 \strut
6952 \cs{renewcommand}\marg{\cs{glstreenamefmt}}[1]\marg{\idx{param}1}
6953 \cs{renewcommand}\marg{\cs{glstreegroupheaderfmt}}[1]\marg{\cs{textbf}\marg{\idx{param}1}}
6954 \cs{printunsrtglossary}\oarg{\printglossopt[index]{type},\printglossopt[\glostyle{mcolindexgroup}]{style}}
6955 \strut
6956 \cmd{end}\marg{document}
6957 \end{codeenv}
6958 Here I've provided some convenient commands for referencing the
6959 \primary\ (index) terms (\csfmt{idx}, \csfmt{idxpl}, \csfmt{Idx}
6960 and \csfmt{Idxpl}). This means I don't need to worry about the
6961 label prefix and it also switches off the hyperlinks (with
6962 \code{\glsopt[false]{hyper}}). These custom
6963 commands are defined using:
6964 \nosecformatdef{glsxtrnewglslike}
6965 which, in this case, essentially does:
6966 \begin{codeenv}
6967 \cs{newcommand}\marg{\cmd{idx}}[2][]\marg{\cs{gls}\oarg{\glsopt[false]{hyper},\idx{param}1}\marg{idx.\idx{param}2}}
6968 \cs{newcommand}\marg{\cmd{Idx}}[2][]\marg{\cs{Gls}\oarg{\glsopt[false]{hyper},\idx{param}1}\marg{idx.\idx{param}2}}
6969 \cs{newcommand}\marg{\cmd{idxpl}}[2][]\marg{\cs{glspl}\oarg{\glsopt[false]{hyper},\idx{param}1}\marg{idx.\idx{param}2}}
6970 \cs{newcommand}\marg{\cmd{Idxpl}}[2][]\marg{\cs{Glspl}\oarg{\glsopt[false]{hyper},\idx{param}1}\marg{idx.\idx{param}2}}
6971 \end{codeenv}
6972 but the new commands will also recognise the \ics{gls} modifiers, so
6973 \verb|\idx+| will behave like \verb|\gls+| which wouldn't be
6974 possible if \csfmt{idx} was defined using \ics{newcommand} in the
6975 above manner. There's a similar command:
6976 \nosecformatdef{glsxtrnewgls}
6977 if no case-changing versions are required.
6978
6979 I've also redefined \gls!{bibglsnewdualindexsymbolsecondary} to put
6980 the dual entries created with \atentry{dualindexsymbol} into
6981 the \code{symbols} glossary (which is created with the
6982 \styopt{symbols} package option), so it overrides the
6983 \csopt[main]{dual-type} setting.
6984
6985 This command also sets the \field{category}
6986 to \code{symbol}, so I can redefine the post-description hook
6987 for symbols (\ics{glsxtrpostdescsymbol}) to automatically index
6988 the symbol definition. Similarly for the \code{general}
6989 post-description hook \ics{glsxtrpostdescgeneral}.
6990
6991 Since the post-description hook isn't done until the glossary has
6992 been created, this requires a slightly longer build process. If the
6993 document file is called \filefmt{myDoc.tex}, then the complete
6994 document build is:
6995 \begin{verbatim}
6996 pdflatex myDoc
6997 bib2gls -g myDoc
6998 pdflatex myDoc
6999 bib2gls -g myDoc
7000 pdflatex myDoc
7001 \end{verbatim}
7002
7003 As from \sty{glossaries-extra-bib2gls} version 1.37, an alternative
7004 method is to identify possible label prefixes with
7005 \ics{glsxtraddlabelprefix} or \ics{glsxtrprependlabelprefix} and use
7006 \ics{dgls}, \ics{dglspl}, \ics{dGls} or \ics{dGlspl}. See the
7007 \styfmt{glossaries-extra} user manual~\cite{glossaries-extra} for
7008 further details.
7009
7010 \entrysection{dualindexnumber}
7011
7012 The \atentry{dualindexnumber} \gls{entrytype} is almost identical to
7013 \atentry{dualindexsymbol}, but the \glspl{primaryentry} are defined using
7014 \gls!{bibglsnewdualindexnumber},
7015 which by default sets the \field{category} to \optfmt{index},
7016 and the \glspl{dualentry} are defined using
7017 \gls!{bibglsnewdualindexnumbersecondary},
7018 which by default sets the \field{category} to \optfmt{number}.
7019
7020 \entrysection{dualabbreviationentry}
7021
7022 The \atentry{dualabbreviationentry} \gls{entrytype} is similar to
7023 \atentry{dualentry}, but by default the
7024 field mappings are:
7025 \begin{itemize}
7026 \item \field{long} $\mapsto$ \field{name}
7027 \item \field{longplural} $\mapsto$ \field{plural}
7028 \item \field{short} $\mapsto$ \field{text}
7029 \end{itemize}
7030 If the prefix fields are defined, then the default mappings
7031 additionally include:
7032 \begin{itemize}
7033 \item \field{prefix} $\mapsto$ \field{dualprefix}
7034 \item \field{prefixplural} $\mapsto$ \field{dualprefixplural}
7035 \item \field{prefixfirst} $\mapsto$ \field{dualprefixfirst}
7036 \item \field{prefixfirstplural} $\mapsto$ \field{dualprefixfirstplural}
7037 \item \field{dualprefix} $\mapsto$ \field{prefix}
7038 \item \field{dualprefixplural} $\mapsto$ \field{prefixplural}
7039 \item \field{dualprefixfirst} $\mapsto$ \field{prefixfirst}
7040 \item \field{dualprefixfirstplural} $\mapsto$ \field{prefixfirstplural}
7041 \end{itemize}
7042 You may need to add a mapping from \field{shortplural} to
7043 \field{plural} if the default is inappropriate.
7044 (In \bibgls\ version 1.0 this \gls{entrytype} was originally called
7045 \atentry{dualentryabbreviation}. In version 1.1, it was renamed
7046 \atentry{dualabbreviationentry} which makes for a more consistent naming scheme
7047 \code{@dual}\meta{primary}\meta{dual}.)
7048
7049 The required fields are: \field{short}, \field{long} and
7050 \field{description}. This \gls{entrytype} is designed to emulate the
7051 example \gls{newdualentry} command given in the \sty{glossaries}
7052 user manual~\cite{glossaries}. The \gls{primaryentry} is an abbreviation with the given
7053 \field{short} and \field{long} fields (but not the
7054 \field{description}) and the secondary entry is a regular entry with
7055 the \field{name} copied from the \field{long} field.
7056 The fallback for the \field{sort} is given by
7057 \csopt{abbreviation-sort-fallback}, which defaults to the
7058 \field{short} field (see \sectionref{sec:fallbacks}).
7059
7060 For example:
7061 \begin{codeenv}
7062 \atentry{dualabbreviationentry}\marg{svm,
7063 \field{long} = \marg{support vector machine},
7064 \field{short} = \marg{SVM},
7065 \field{description} = \marg{statistical pattern recognition technique}
7066 }
7067 \end{codeenv}
7068 is rather like doing:
7069 \begin{codeenv}
7070 \atentry{abbreviation}\marg{svm,
7071 \field{long} = \marg{support vector machine},
7072 \field{short} = \marg{SVM}
7073 }
7074 \strut
7075 \atentry{entry}\marg{dual.svm,
7076 \field{name} = \marg{support vector machine},
7077 \field{description} = \marg{statistical pattern recognition technique}
7078 }
7079 \end{codeenv}
7080 but \code{dual.svm} will automatically be selected if \code{svm}
7081 is indexed in the document. If \code{dual.svm} isn't explicitly
7082 indexed, it won't have a \gls{locationlist}.
7083
7084 If the \field{sort} field is missing \bibgls\ by default falls back
7085 on the \field{name} field. If this is missing, this sort value will
7086 fallback on the \field{short} field. This means that if \field{name}
7087 isn't explicitly given in \atentry{dualabbreviationentry}, then the
7088 \gls{primaryentry} will be sorted according to \field{short} but the
7089 \dual\ will be sorted according its \field{name} (which has been copied
7090 from the \primary\ \field{long}).
7091
7092 Entries provided using \atentry{dualabbreviationentry} will be defined
7093 with:
7094 \begin{codeenv}
7095 \gls{bibglsnewdualabbreviationentry}
7096 \end{codeenv}
7097 (which uses \gls{newabbreviation}) for the \glspl{primaryentry} and with :
7098 \begin{codeenv}
7099 \gls{bibglsnewdualabbreviationentrysecondary}
7100 \end{codeenv}
7101 (which uses \gls{longnewglossaryentry}) for the secondary entries.
7102 This means that if the \styopt{abbreviations} package option is
7103 used, the \gls{primaryentry} will be put in the
7104 \optfmt{abbreviations} glossary and the secondary entry in the
7105 \mainglossary\. Use the \csopt{type} and \csopt{dual-type} options
7106 to override this.
7107
7108 \entrysection{dualentryabbreviation}
7109
7110 This \gls{entrytype} is deprecated as from \bibgls\ version 1.1. It's functionally
7111 equivalent to \atentry{dualabbreviationentry} but its name
7112 doesn't fit the general dual entry naming scheme.
7113
7114 \entrysection{dualsymbol}
7115
7116 This is like \atentry{dualentry} but the default mappings are:
7117 \begin{itemize}
7118 \item \field{name} $\mapsto$ \field{symbol}
7119 \item \field{plural} $\mapsto$ \field{symbolplural}
7120 \item \field{symbol} $\mapsto$ \field{name}
7121 \item \field{symbolplural} $\mapsto$ \field{plural}
7122 \end{itemize}
7123 If the prefix fields are defined, then the default mappings
7124 additionally include:
7125 \begin{itemize}
7126 \item \field{prefix} $\mapsto$ \field{dualprefix}
7127 \item \field{prefixplural} $\mapsto$ \field{dualprefixplural}
7128 \item \field{prefixfirst} $\mapsto$ \field{dualprefixfirst}
7129 \item \field{prefixfirstplural} $\mapsto$ \field{dualprefixfirstplural}
7130 \item \field{dualprefix} $\mapsto$ \field{prefix}
7131 \item \field{dualprefixplural} $\mapsto$ \field{prefixplural}
7132 \item \field{dualprefixfirst} $\mapsto$ \field{prefixfirst}
7133 \item \field{dualprefixfirstplural} $\mapsto$ \field{prefixfirstplural}
7134 \end{itemize}
7135 The \field{name} and \field{symbol} fields are required.
7136 For example:
7137 \begin{codeenv}
7138 \atentry{dualsymbol}\marg{pi,
7139 \field{name}=\marg{pi},
7140 \field{symbol}=\marg{\cs{ensuremath}\marg{\cs{pi}}},
7141 \field{description}=\marg{the ratio of the length of the circumference
7142 of a circle to its diameter}
7143 }
7144 \end{codeenv}
7145
7146 Entries are defined using \gls!{bibglsnewdualsymbol}, which by
7147 default sets the \field{category} to \optfmt{symbol}.
7148
7149 \entrysection{dualnumber}
7150
7151 This is almost identical to \atentry{dualsymbol} but entries are
7152 defined using \gls!{bibglsnewdualnumber}, which by default sets
7153 the \field{category} to \optfmt{number}.
7154
7155 The above example could be defined as a number since $\pi$ is a
7156 constant:
7157 \begin{codeenv}
7158 \atentry{dualnumber}\marg{pi,
7159 \field{name}=\marg{pi},
7160 \field{symbol}=\marg{\cs{ensuremath}\marg{\cs{pi}}},
7161 \field{description}=\marg{the ratio of the length of the circumference
7162 of a circle to its diameter},
7163 \field{user1}=\marg{3.14159}
7164 }
7165 \end{codeenv}
7166
7167 This has stored the approximate value in the \field{user1} field.
7168 The post-description hook could then be adapted to show this.
7169 \begin{codeenv}
7170 \cs{glsdefpostdesc}\marg{number}\marg{\comment{}
7171 \cs{ifglshasfield}\marg{useri}\marg{\cs{glscurrententrylabel}}
7172 \marg{ (approximate value: \cs{glscurrentfieldvalue})}\comment{}
7173 \marg{}\comment{}
7174 }
7175 \end{codeenv}
7176
7177 This use of the \field{user1} field means that the dual entries
7178 could be sorted numerically according to the approximate value:
7179 \begin{codeenv}
7180 \cmd{usepackage}[\styopt{record},\styopt{postdot},\styopt{numbers},\styopt[index]{style}]\marg{glossaries-extra}
7181 \strut
7182 \gls{GlsXtrLoadResources}\oarg{
7183 \csopt[entries]{src},\comment{entries.bib}
7184 \csopt[numbers]{dual-type},
7185 \csopt[double]{dual-sort},\comment{decimal sort}
7186 \csopt[user1]{dual-sort-field}
7187 }
7188 \end{codeenv}
7189
7190 \entrysection{dualabbreviation}
7191
7192 The \atentry{dualabbreviation} \gls{entrytype} is similar to
7193 \atentry{dualentry}, but by default the
7194 field mappings are:
7195 \begin{itemize}
7196 \item \field{short} $\mapsto$ \field{dualshort}
7197 \item \field{shortplural} $\mapsto$ \field{dualshortplural}
7198 \item \field{long} $\mapsto$ \field{duallong}
7199 \item \field{longplural} $\mapsto$ \field{duallongplural}
7200 \item \field{dualshort} $\mapsto$ \field{short}
7201 \item \field{dualshortplural} $\mapsto$ \field{shortplural}
7202 \item \field{duallong} $\mapsto$ \field{long}
7203 \item \field{duallongplural} $\mapsto$ \field{longplural}
7204 \end{itemize}
7205 If the prefix fields are defined, then the default mappings
7206 additionally include:
7207 \begin{itemize}
7208 \item \field{prefix} $\mapsto$ \field{dualprefix}
7209 \item \field{prefixplural} $\mapsto$ \field{dualprefixplural}
7210 \item \field{prefixfirst} $\mapsto$ \field{dualprefixfirst}
7211 \item \field{prefixfirstplural} $\mapsto$ \field{dualprefixfirstplural}
7212 \item \field{dualprefix} $\mapsto$ \field{prefix}
7213 \item \field{dualprefixplural} $\mapsto$ \field{prefixplural}
7214 \item \field{dualprefixfirst} $\mapsto$ \field{prefixfirst}
7215 \item \field{dualprefixfirstplural} $\mapsto$ \field{prefixfirstplural}
7216 \end{itemize}
7217 The required fields are: \field{short}, \field{long},
7218 \field{dualshort} and \field{duallong}.
7219 This includes some new fields: \field{dualshort},
7220 \field{dualshortplural}, \field{duallong} and
7221 \field{duallongplural}. If these aren't already defined, they
7222 will be provided in the \iext{glstex} file with
7223 \begin{codeenv}
7224 \ics{glsxtrprovidestoragekey}\margm{key}\marg{}\marg{}
7225 \end{codeenv}
7226 Note that this use with an empty third argument prevents
7227 the creation of a field access command (analogous to
7228 \ics{glsentrytext}). The value can be accessed with
7229 \ics{glsxtrusefield} instead. Remember that the field won't be
7230 available until the \ext{glstex} file has been created.
7231
7232 Note that \bibgls\ doesn't know what abbreviation styles
7233 are in used, so if the \field{sort} field is missing
7234 it will fallback on the \field{short} field. If the abbreviations
7235 need to be sorted according to the \field{long} field instead,
7236 use \csopt[long]{abbreviation-sort-fallback} (see \sectionref{sec:fallbacks}).
7237
7238 Terms that are defined using \atentry{dualabbreviation} will be
7239 written to the output file using \gls!{bibglsnewdualabbreviation}.
7240
7241 If the \csopt{dual-abbrv-backlink} option is on, the default field
7242 used for the backlinks is the \field{dualshort} field, so you'll need
7243 to make sure you adapt the glossary style to show that field. The
7244 simplest way to do this is through the category \idx{postdescriptionhook}.
7245
7246 For example, if the entries all have the \field{category} set
7247 to \optfmt{abbreviation}, then this requires redefining
7248 \ics{glsxtrpostdescabbreviation} (either with \cs{renewcommand}
7249 or via \cs{glsdefpostdesc}).
7250
7251 Here's an example dual abbreviation for a document where English is
7252 the primary language and German is the secondary language:
7253 \begin{codeenv}
7254 \atentry{dualabbreviation}\marg{rna,
7255 \field{short}=\marg{RNA},
7256 \field{dualshort}=\marg{RNS},
7257 \field{long}=\marg{ribonucleic acid},
7258 \field{duallong}=\marg{Ribonukleins\"aure}
7259 }
7260 \end{codeenv}
7261 If the abbreviation is in the file called
7262 \filefmt{entries-dual-abbrv.bib}, then here's an example document:
7263 \begin{codeenv}
7264 \cmd{documentclass}\marg{article}
7265 \strut
7266 \cmd{usepackage}[T1]\marg{fontenc}
7267 \cmd{usepackage}[utf8]\marg{inputenc}
7268 \strut
7269 \cmd{usepackage}[ngerman,main=english]\marg{babel}
7270 \cmd{usepackage}[colorlinks]\marg{hyperref}
7271 \cmd{usepackage}[\styopt{record},\styopt{nomain}]\marg{glossaries-extra}
7272 \strut
7273 \cs{newglossary*}\marg{english}\marg{English}
7274 \cs{newglossary*}\marg{german}\marg{German}
7275 \strut
7276 \cs{setabbreviationstyle}\marg{long-short}
7277 \strut
7278 \cs{glsdefpostdesc}\marg{abbreviation}\marg{\comment{}
7279 \cs{ifglshasfield}\marg{dualshort}\marg{\cs{glscurrententrylabel}}
7280 \marg{\comment{}
7281 \cmd{space}(\cs{glscurrentfieldvalue})\comment{}
7282 }\comment{}
7283 \marg{}\comment{}
7284 }
7285 \strut
7286 \gls{GlsXtrLoadResources}\oarg{
7287 \csopt[entries-dual-abbrv]{src},\comment{entries-dual-abbrv.bib}
7288 \csopt[english]{type},\comment{put \primary\ entries in glossary 'english'}
7289 \csopt[german]{dual-type},\comment{put \dual\ entries in glossary 'german'}
7290 \csopt[en.]{label-prefix},\comment{\primary\ label prefix}
7291 \csopt[de.]{dual-prefix},\comment{\dual\ label prefix}
7292 \csopt[en]{sort},\comment{sort \glspl{primaryentry} according to language 'en'}
7293 \csopt[de-1996]{dual-sort},\comment{sort \glspl{dualentry} according to 'de-1996'}
7294 \comment{(German new orthography)}
7295 \csopt{dual-abbrv-backlink}\comment{add links in the glossary to the opposite entry}
7296 }
7297 \strut
7298 \cmd{begin}\marg{document}
7299 \strut
7300 English: \cs{gls}\marg{en.rna}; \cs{gls}\marg{en.rna}.
7301 \strut
7302 German: \cs{gls}\marg{de.rna}; \cs{gls}\marg{de.rna}.
7303 \strut
7304 \cs{printunsrtglossaries}
7305 \cmd{end}\marg{document}
7306 \end{codeenv}
7307 If the \csopt{label-prefix} is omitted, then only the dual entries
7308 will have a prefix:
7309 \begin{codeenv}
7310 English: \cs{gls}\marg{rna}; \cs{gls}\marg{rna}.
7311 \strut
7312 German: \cs{gls}\marg{de.rna}; \cs{gls}\marg{de.rna}.
7313 \end{codeenv}
7314 Another variation is to use the \abbrstyle{long-short-user}
7315 abbreviation style and modify the associated \ics{glsxtruserfield} so that
7316 the \field{duallong} field is selected for the parenthetical
7317 material:
7318 \begin{codeenv}
7319 \cs{renewcommand}*\marg{\cs{glsxtruserfield}}\marg{duallong}
7320 \end{codeenv}
7321 This means that the first use of the \gls{primaryentry} is displayed as
7322 \begin{quote}
7323 ribonucleic acid (RNA, Ribonukleins\"aure)
7324 \end{quote}
7325 and the first use of the dual entry is displayed as:
7326 \begin{quote}
7327 Ribonukleins\"aure (RNS, ribonucleic acid)
7328 \end{quote}
7329
7330 Here's an example to be used with the \abbrstyle{long-short-desc}
7331 style:
7332 \begin{codeenv}
7333 \atentry{dualabbreviation}\marg{rna,
7334 \field{short}=\marg{RNA},
7335 \field{dualshort}=\marg{RNS},
7336 \field{long}=\marg{ribonucleic acid},
7337 \field{duallong}=\marg{Ribonukleins\"aure}
7338 \field{description}=\marg{a polymeric molecule},
7339 \field{user1}=\marg{Ein polymeres Molek\"ul}
7340 }
7341 \end{codeenv}
7342 This stores the dual description in the \field{user1} field,
7343 so this needs a mapping.
7344 The new example document is much the same as the previous one, except
7345 that the \csopt{dual-abbrv-map} option is needed to include the
7346 mapping between the \field{description} and \field{user1} fields:
7347 \begin{codeenv}
7348 \cmd{documentclass}\marg{article}
7349 \strut
7350 \cmd{usepackage}[T1]\marg{fontenc}
7351 \cmd{usepackage}[utf8]\marg{inputenc}
7352 \strut
7353 \cmd{usepackage}[ngerman,main=english]\marg{babel}
7354 \cmd{usepackage}[colorlinks]\marg{hyperref}
7355 \cmd{usepackage}[\styopt{record},\styopt{nomain}]\marg{glossaries-extra}
7356 \strut
7357 \cs{newglossary*}\marg{english}\marg{English}
7358 \cs{newglossary*}\marg{german}\marg{German}
7359 \strut
7360 \cs{setabbreviationstyle}\marg{long-short-desc}
7361 \strut
7362 \cs{glsdefpostdesc}\marg{abbreviation}\marg{\comment{}
7363 \cs{ifglshasfield}\marg{dualshort}\marg{\cs{glscurrententrylabel}}
7364 \marg{\comment{}
7365 \cmd{space}(\cs{glscurrentfieldvalue})\comment{}
7366 }\comment{}
7367 \marg{}\comment{}
7368 }
7369 \strut
7370 \gls{GlsXtrLoadResources}\oarg{
7371 \csopt[entries-dual-abbrv-desc]{src},\comment{entries-dual-abbrv-desc.bib}
7372 \csopt[english]{type},\comment{put \glspl{primaryentry} in glossary 'english'}
7373 \csopt[german]{dual-type},\comment{put \glspl{dualentry} in glossary 'german'}
7374 \csopt[en.]{label-prefix},\comment{\primary\ label prefix}
7375 \csopt[de.]{dual-prefix},\comment{\dual\ label prefix}
7376 \csopt[en]{sort},\comment{sort \glspl{primaryentry} according to language 'en'}
7377 \csopt[long]{abbreviation-sort-fallback},\comment{fallback on 'long' field}
7378 \csopt[de-1996]{dual-sort},\comment{sort \glspl{dualentry} according to 'de-1996'}
7379 \comment{(German new orthography)}
7380 \csopt{dual-abbrv-backlink},\comment{add links in the glossary to the opposite entry}
7381 \comment{ dual key mappings:}
7382 \csopt[\comment{}
7383 \marg{short,shortplural,long,longplural,dualshort,dualshortplural,
7384 duallong,duallongplural,description,user1},
7385 \marg{dualshort,dualshortplural,duallong,duallongplural,short,shortplural,
7386 long,longplural,user1,description}
7387 ]{dual-abbrv-map}
7388 }
7389 \strut
7390 \cmd{begin}\marg{document}
7391 \strut
7392 English: \cs{gls}\marg{en.rna}; \cs{gls}\marg{en.rna}.
7393 \strut
7394 German: \cs{gls}\marg{de.rna}; \cs{gls}\marg{de.rna}.
7395 \strut
7396 \cs{printunsrtglossaries}
7397 \cmd{end}\marg{document}
7398 \end{codeenv}
7399 Note that since this document uses the \abbrstyle{long-short-desc}
7400 abbreviation style, the \csopt{abbreviation-sort-fallback} needs to be changed
7401 to \optfmt{long}.
7402
7403 If I change the order of the mapping to:
7404 \begin{codeenv}
7405 \csopt[\comment{}
7406 \marg{long,longplural,short,shortplural,dualshort,dualshortplural,
7407 duallong,duallongplural,description,user1},
7408 \marg{duallong,duallongplural,dualshort,dualshortplural,short,shortplural,
7409 long,longplural,user1,description}
7410 ]{dual-abbrv-map}
7411 \end{codeenv}
7412 Then the back-link field will switch to \field{duallong}. The
7413 \idx{postdescriptionhook} can be modified to allow for this:
7414 \begin{codeenv}
7415 \cs{glsdefpostdesc}\marg{abbreviation}\marg{\comment{}
7416 \cs{ifglshasfield}\marg{duallong}\marg{\cs{glscurrententrylabel}}
7417 \marg{\comment{}
7418 \cmd{space}(\cs{glscurrentfieldvalue})\comment{}
7419 }\comment{}
7420 \marg{}\comment{}
7421 }
7422 \end{codeenv}
7423
7424 An alternative is to use the \abbrstyle{long-short-user-desc} style
7425 without the \idx!{postdescriptionhook}:
7426 \begin{codeenv}
7427 \cs{setabbreviationstyle}\marg{long-short-user-desc}
7428 \cs{renewcommand}*\marg{\cs{glsxtruserfield}}\marg{duallong}
7429 \end{codeenv}
7430 However be careful with this approach as it can cause nested
7431 hyperlinks. In this case it's better to use the
7432 \abbrstyle{long-postshort-user-desc} style which defers the
7433 parenthetical material until after the link-text:
7434 \begin{codeenv}
7435 \cs{setabbreviationstyle}\marg{long-postshort-user-desc}
7436 \cs{renewcommand}*\marg{\cs{glsxtruserfield}}\marg{duallong}
7437 \end{codeenv}
7438 If the back-link field has been switched to \field{duallong} then
7439 the \idx!{postdescriptionhook} is no longer required.
7440
7441 \entrysection{dualacronym}
7442
7443 As \atentry{dualabbreviation} but defines the entries with
7444 \gls!{bibglsnewdualacronym}.
7445
7446 \subsection{Tertiary Entry Types}
7447 \label{sec:tertiaryentry}
7448
7449 A \igls{tertiaryentry} type is essentially a \gls{dualentry} that creates three
7450 separate (but related) \styfmt{glossaries-extra} entry definitions per
7451 \ext{bib} entry. As with \glspl{dualentry}, the first of these
7452 is the \gls{primaryentry}. The second and third are referred to as the
7453 \igls{secondaryentry} and \igls{tertiaryentry}.
7454
7455 The \gls{tertiaryentry} is effectively an appendage of the
7456 \gls{secondaryentry}{secondary}, and is defined by the same associated
7457 \csfmt{bibglsnew\ldots secondary} command that defines the
7458 \gls{secondaryentry}. Therefore the \glsdisp{secondaryentry}{secondary}
7459 and \glsdisp{tertiaryentry}{tertiary} are both considered the
7460 \dual\ and are treated as a single entry for the purposes of sorting
7461 and collating.
7462
7463 The \gls{tertiaryentry} will never have any \glspl{location}. Any \glspl{record}
7464 found will be assigned to the \glsdisp{secondaryentry}{secondary}
7465 (and may then be moved to the \primary\ with
7466 \csopt[primary]{combine-dual-locations}). The
7467 \glsdisp{tertiaryentry}{tertiary} will always have the same order as
7468 the \glsdisp{secondaryentry}{secondary} and will have the same
7469 \field{group} value. You can set the \field{type} for the
7470 \glsdisp{tertiaryentry}{tertiary} with \csopt{tertiary-type} and the
7471 \field{category} with \csopt{tertiary-category}. The label prefix
7472 defaults to \idprefix{tertiary} and can be changed with
7473 \csopt{tertiary-prefix}.
7474
7475 \entrysection{tertiaryindexabbreviationentry}
7476
7477 This \gls{entrytype} is very similar to
7478 \atentry{dualindexabbreviation} but creates a \gls{tertiaryentry} as
7479 well. The required fields are: \field{short} and \field{long} (as for
7480 \atentry{dualindexabbreviation}) and also \field{description}. The
7481 mappings are shared by both \glspl{entrytype}. For example:
7482 \begin{codeenv}
7483 \atentry{tertiaryindexabbreviationentry}\marg{html,
7484 \field{short} = \marg{HTML},
7485 \field{long} = \marg{hypertext markup language},
7486 \field{description} = \marg{a markup language for creating web pages}
7487 }
7488 \end{codeenv}
7489 is analogous to:
7490 \begin{codeenv}
7491 \gls{newglossaryentry}\marg{html,\field{name}=\marg{HTML},\field{description}=\marg{}}
7492 \strut
7493 \gls{newabbreviation}\marg{dual.html}\marg{HTML}\marg{hypertext markup language}
7494 \strut
7495 \gls{newglossaryentry}\marg{tertiary.html,
7496 \field{name}=\marg{hypertext markup language},
7497 \field{description}=\marg{a markup language for creating web pages}
7498 }
7499 \end{codeenv}
7500 The last two are actually defined using one command:
7501 \begin{codeenv}
7502 \gls{bibglsnewtertiaryindexabbreviationentrysecondary}
7503 \marg{dual.html}\comment{\glsdisp{secondaryentry}{secondary} label}
7504 \marg{tertiary.html}\comment{\glsdisp{tertiaryentry}{tertiary} label}
7505 \marg{\ldots}\comment{\glsdisp{secondaryentry}{secondary} fields}
7506 \marg{\ldots}\comment{\glsdisp{tertiaryentry}{tertiary} fields}
7507 \marg{HTML}\comment{\primary\ name}
7508 \marg{HTML}\comment{short}
7509 \marg{hypertext markup language}\comment{long}
7510 \marg{a markup language for creating web pages}\comment{description}
7511 \end{codeenv}
7512 The \gls!{bibglsnewtertiaryindexabbreviationentrysecondary}
7513 command is provided in the \iext{glstex} file as:
7514 \begin{codeenv}
7515 \cs{providecommand}\marg{\gls{bibglsnewtertiaryindexabbreviationentrysecondary}}[8]\marg{\comment{}
7516 \gls{newabbreviation}\oarg{\idx{param}3}\marg{\idx{param}1}\marg{\idx{param}6}\marg{\idx{param}7}\comment{}
7517 \cs{longnewglossaryentry*}\marg{\idx{param}2}\comment{}
7518 \marg{\field{name}=\marg{\cmd{protect}\gls{bibglsuselongfont}\marg{\idx{param}7}\marg{\ics{glscategory}\marg{\idx{param}1}}},\idx{param}4}\comment{}
7519 \marg{\idx{param}8}\comment{}
7520 }
7521 \end{codeenv}
7522 which defines the \glsdisp{secondaryentry}{secondary} as an
7523 abbreviation using \csfmt{newabbreviation} and the
7524 \glsdisp{tertiaryentry}{tertiary} as a regular entry using
7525 \csfmt{longnewglossaryentry}. This means that the
7526 \gls{tertiaryentry} is always defined immediately after the
7527 corresponding \gls{secondaryentry}. The \primary\ may be defined
7528 earlier or later in the file depending on the way the entries are
7529 sorted and on the \csopt{dual-sort} setting.
7530
7531 \subsection{Multi-Entry Types}
7532 \label{sec:multientry}
7533
7534 A \gls{multientrytype} is an entry that may spawn multiple
7535 \glspl{primaryentry}. This means that both the \gls{mainentry} and the
7536 \glspl{spawnedentry} are sorted together along with all the other
7537 \glspl{primaryentry}. In the case of \atentry{spawndualindexentry},
7538 the \glsdisp{mainentry}{main} and \glspl{spawnedentry} are \primary.
7539 The \gls{mainentry}['s] \dual\ is created as per \atentry{dualindexentry}.
7540
7541 \entrysection{bibtexentry}
7542
7543 The \atentry{bibtexentry} type will typically need to be aliased
7544 as it's designed for converting \BibTeX\ entries into \bibgls\
7545 entries. For example, to make \bibgls\ treat \atentryfmt{article}
7546 and \atentryfmt{book} as though they were both
7547 \atentry{bibtexentry}:
7548 \begin{codeenv}
7549 \csopt[
7550 article=bibtexentry,
7551 book=bibtexentry
7552 ]{entry-type-aliases}
7553 \end{codeenv}
7554 For convenience, \isty{glossaries-extra-bib2gls} v1.29+
7555 provides \ics{GlsXtrBibTeXEntryAliases} which covers all the
7556 standard \BibTeX\ \glspl{entrytype}. Alternatively, you can use
7557 \csopt[bibtexentry]{unknown-entry-alias} to alias all entries
7558 that aren't recognised by \bibgls. If you use
7559 \csopt[same as original entry]{category}, the \field{category}
7560 field will be set to the original \gls{entrytype} (for example,
7561 \code{article} or \code{book}). Similarly you can use
7562 \csopt[same as original entry]{type} to set the \field{type}
7563 field (but remember that the glossary types will need to be defined
7564 in the document).
7565
7566 There are no required fields. The fallback for the \field{sort}
7567 field is given by \csopt{bibtexentry-sort-fallback} (see
7568 \sectionref{sec:fallbacks}). If you want to access any of the
7569 \BibTeX\ fields, you will need to alias or define them. For
7570 example:
7571 \begin{codeenv}
7572 \csopt[
7573 \fieldfmt{title}=\field{name}
7574 ]{field-aliases}
7575 \end{codeenv}
7576 Since \BibTeX's \fieldfmt{type} field conflicts with \bibgls's
7577 \field{type} field, when \bibgls\ parses \atentry{bibtexentry}
7578 if will convert \fieldfmt{type} to \field{bibtextype}, so you
7579 must use \field{bibtextype} as the identifier when aliasing.
7580
7581 Alternatively, you can use \ics{GlsXtrProvideBibTeXFields} which
7582 uses \ics{glsaddstoragekey} to provide all the standard \BibTeX\
7583 fields. (Remember that new fields must be defined before the first
7584 \igls{resourceset}.)
7585
7586 The \atentry{bibtexentry} essentially creates an \atentry{index}
7587 form of entry, but it additionally defines a \atentry{contributor}
7588 entry for each listed author or editor
7589 and updates the dependency lists: each \atentry{contributor} is
7590 added to the \glsdisp{mainentry}{main}
7591 \atentry{bibtexentry}'s list of dependencies (so if the
7592 \atentry{bibtexentry} has a \gls{record} then all its satellite
7593 \atentry{contributor}s are selected with the default
7594 \csopt[recorded and deps]{selection}), and
7595 each \atentry{contributor} is treated as having a cross-reference to
7596 the \glsdisp{mainentry}{main} \atentry{bibtexentry} (so if a \atentry{contributor}
7597 has a \gls{record} then all the linked \atentry{bibtexentry} terms will
7598 be selected if \csopt[recorded and deps and see]{selection}).
7599 You can instruct \bibgls\ to treat \ics{citation} as an
7600 \igls{ignoredrecord} using \longarg{cite-as-record}.
7601
7602 Each contributor is effectively defined as:
7603 \begin{codeenv}
7604 \atentry{contributor}\marg{\meta{label},
7605 \field{name}=\marg{\gls{bibglscontributor}\margm{forenames}\margm{von}\margm{surname}\margm{suffix}}
7606 }
7607 \end{codeenv}
7608 The label is obtained by converting the \field{name}
7609 to a label, using the same function as \csopt{labelify} (which
7610 means it's governed by \csopt{labelify-replace}).
7611
7612 The \fieldfmt{author} and \fieldfmt{editor} fields are always
7613 checked, even if those fields aren't recognised by \bibgls, (which
7614 they aren't by default). These checks are performed before field
7615 aliases are applied. If neither field is present, no additional
7616 entries are spawned. If the dependent \atentry{contributor} entry
7617 has already been defined, it won't be redefined, but will have the
7618 new \atentry{bibtexentry} added to its internal \field{bibtexentry}
7619 field.
7620
7621 The \glsdisp{mainentry}{main} \atentry{bibtexentry} is defined using
7622 \gls{bibglsnewbibtexentry} and is followed by:
7623 \begin{codeenv}
7624 \gls{glsxtrfieldlistadd}\margm{id}\marg{bibtexcontributor}\margm{contributor-id}
7625 \end{codeenv}
7626 where \meta{id} is the label identifying the \glsdisp{mainentry}{main}
7627 \atentry{bibtexentry} and \meta{contributor-id} is the
7628 label identifying the contributor, for each contributor that has
7629 been selected.
7630
7631 Each contributor is defined using \gls{bibglsnewcontributor}. The definition
7632 is followed by:
7633 \begin{codeenv}
7634 \gls{glsxtrfieldlistadd}\margm{contributor-id}\marg{bibtexentry}\margm{id}
7635 \gls{glsxtrfieldlistadd}\margm{contributor-id}\marg{bibtexentry@\meta{entry-type}}\margm{id}
7636 \end{codeenv}
7637 for each selected \atentry{bibtexentry} associated with that contributor. The
7638 second line provides the internal list field
7639 \field{bibtexentry@entrytype}, where \meta{entry-type} is the
7640 original \gls{entrytype} (before it was aliased to
7641 \atentry{bibtexentry} and converted to \idx!{lowercase}).
7642 For example \code{article} or \code{book}.
7643
7644 You can iterate over these internal list fields using
7645 \glsadd{idx.loop}\ics{glsxtrfielddolistloop} or \ics{glsxtrfieldforlistloop}.
7646 For example:
7647 \begin{codeenv}
7648 \cs{newcommand}\marg{\csfmt{contributorhandler}}[1]\marg{\csfmt{par}\cs{glsentryname}\marg{\#1}}
7649
7650 \cs{newcommand}\marg{\postdeschook{contributor}}\marg{\comment{}
7651 \cs{glsxtrifhasfield}\marg{bibtexentry}\marg{\cs{glscurrententrylabel}}\comment{}
7652 \marg{\comment{}
7653 \cs{glsxtrfieldforlistloop}
7654 \marg{\cs{glscurrententrylabel}}\marg{bibtexentry}\comment{}
7655 \marg{\csfmt{contributorhandler}}\comment{}
7656 }\comment{}
7657 \marg{\csfmt{par} No titles.}\comment{}
7658 }
7659 \end{codeenv}
7660 (where the resource option \csopt[\fieldfmt{title}=\field{name}]{field-aliases}
7661 has been used).
7662
7663 Here's an example that uses the test \file{xampl.bib} file that's
7664 provided with \TeX\ distributions:
7665 \begin{codeenv}
7666 \cmd{documentclass}\marg{article}
7667 \strut
7668 \cmd{usepackage}[\styopt{record},\styopt{nomain}]\marg{glossaries-extra}
7669 \strut
7670 \cs{newglossary*}\marg{contributors}\marg{Authors/Editors}
7671 \cs{newglossary*}\marg{titles}\marg{Titles}
7672 \strut
7673 \cs{newcommand}\marg{\gls{bibglsnewbibtexentry}}[4]\marg{\comment{}
7674 \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}={\idx{param}3},\idx{param}2,\field{type}=\marg{titles}}\marg{\idx{param}4}\comment{}
7675 }
7676 \strut
7677 \gls{GlsXtrLoadResources}\oarg{
7678 \csopt[xampl]{src},
7679 \csopt[false]{write-preamble},
7680 \csopt[
7681 \ics{GlsXtrBibTeXEntryAliases}
7682 ]{entry-type-aliases},
7683 \csopt[
7684 \fieldfmt{title}=\field{name}
7685 ]{field-aliases},
7686 \csopt[
7687 \fieldfmt{note}=\field{name}
7688 ]{replicate-fields},
7689 \csopt[
7690 \marg{[ \cs{cs.string}\csfmt{-}\cs{cs.string}\csfmt{.}]}\marg{}
7691 ]{labelify-replace},
7692 \csopt[contributors]{type},
7693 \csopt[same as original entry]{category},
7694 \csopt[\field{category}]{sort-field},
7695 \csopt[\field{name}]{sort-suffix}
7696 }
7697 \strut
7698 \gls{glsxtrsetgrouptitle}\marg{article}\marg{Articles}
7699 \gls{glsxtrsetgrouptitle}\marg{booklet}\marg{Booklets}
7700 \gls{glsxtrsetgrouptitle}\marg{book}\marg{Books}
7701 \gls{glsxtrsetgrouptitle}\marg{inbook}\marg{Book Chapters}
7702 \gls{glsxtrsetgrouptitle}\marg{misc}\marg{Miscellaneous}
7703 \strut
7704 \cs{newcommand}\marg{\csfmt{contributorhandler}}[1]\marg{\csfmt{par}\ics{glsentryname}\marg{\idx{param}1} (\idx{param}1)}
7705 \strut
7706 \cs{newcommand}\marg{\postdeschook{contributor}}{\comment{}
7707 \cs{glsxtrifhasfield}\marg{bibtexentry}\marg{\cs{glscurrententrylabel}}\comment{}
7708 \marg{\comment{}
7709 \ics{glsxtrfieldforlistloop}
7710 \marg{\cs{glscurrententrylabel}}\marg{bibtexentry}\comment{}
7711 \marg{\csfmt{contributorhandler}}\comment{}
7712 }\comment{}
7713 \marg{\csfmt{par} No titles.}\comment{}
7714 }
7715 \strut
7716 \csfmt{begin}\marg{document}
7717 Sample\idx{nbspchar}\ics{cite}\marg{book-minimal,article-full,inbook-full,misc-minimal}.
7718 Another sample\idx{nbspchar}\cs{cite}\marg{booklet-minimal,misc-full,article-minimal}.
7719 \strut
7720 \csfmt{bibliographystyle}\marg{plain}
7721 \ics{bibliography}\marg{xampl}
7722 \strut
7723 \cs{printunsrtglossary}[\printglossopt[contributors]{type},\printglossopt[altlist]{style}]
7724 \cs{printunsrtglossary*}[\printglossopt[titles]{type},\printglossopt[indexgroup]{style}]
7725 \marg{\comment{}
7726 \cs{renewcommand}\marg{\ics{glsxtrgroupfield}}\marg{category}\comment{}
7727 \cs{renewcommand}\marg{\cs{glstreenamefmt}}[1]\marg{\cs{emph}\marg{\idx{param}1}}\comment{}
7728 \cs{renewcommand}\marg{\cs{glstreegroupheaderfmt}}[1]\marg{\cs{textbf}\marg{\idx{param}1}}\comment{}
7729 }
7730 \strut
7731 \csfmt{end}\marg{document}
7732 \end{codeenv}
7733 If the file is called \filefmt{myDoc.tex} then the document build
7734 is:
7735 \begin{codeenv}
7736 pdflatex myDoc
7737 bib2gls \longarg{cite-as-record} myDoc
7738 bibtex myDoc
7739 pdflatex myDoc
7740 pdflatex myDoc
7741 \end{codeenv}
7742
7743 \entrysection{progenitor}
7744
7745 The \atentryfmt{progenitor} type of entries are the only place where
7746 the \field{adoptparents} field is permitted. The value should be a
7747 comma-separated list of labels. The \field{adoptparents} field
7748 must be set and must contain a least one label. If the value
7749 contains any of the characters \idx{backslashchar} (backslash),
7750 \idx{bgroupchar} (open brace) or \idx{egroupchar} (close brace) then
7751 the field will be interpreted (if the default \longarg{interpret} settings
7752 is on).
7753
7754 Since entries are spawned before fields are processed, the
7755 \field{adoptparents} field is parsed before any field aliases
7756 (\csopt{field-aliases}) or replication (\csopt{replicate-fields})
7757 takes place. However, if the \field{adoptparents} field isn't found,
7758 \bibgls\ will check for a simple mapping in both the
7759 \csopt{field-aliases} and \csopt{replicate-fields} settings.
7760
7761 This \gls{entrytype} creates a \glsdisp{mainentry}{main} \igls[textformat=emph]{progenitor}
7762 term (with all the given fields except \field{adoptparents})
7763 and $n$ spawned \igls[textformat=emph]{progeny} terms, where
7764 $n$ is the number of elements in the \field{adoptparents} field,
7765 that are dependent on the \glsdisp{mainentry}{main term}.
7766
7767 Each of the spawned \gls{progeny} entries have the field identified by
7768 \csopt{adopted-parent-field} (\field{parent} by default) set to the
7769 corresponding element in the \field{adoptparents} field.
7770
7771 All fields from the original definition are copied except for the
7772 \field{adoptparents}, \field{alias} and \field{parent} fields. The
7773 \field{parent} field is never copied, regardless of the value of
7774 \csopt{adopted-parent-field}. If the adopted parent field is
7775 changed to one that's contained in the original entry, it's value
7776 will be from \field{adoptparents} not the value from the original
7777 entry.
7778
7779 The copied fields follow the same conditions as normal
7780 entries. (For example, unknown fields are ignored, case-changes are
7781 applied, if appropriate, and the \field{type} field must reference a
7782 valid glossary, if set.) If \csopt{progenitor-type} is set, then
7783 this assignment is made after the \igls{progeny} are created
7784 and only applies to the \glsdisp{mainentry}{main} \igls{progenitor} entry. The
7785 type for the \gls{progeny} can be set with \csopt{progeny-type}.
7786 For example, \csopt[same as parent]{progeny-type} will ensure
7787 that the \igls{progeny} are in the same glossary type as
7788 their \gls{parententry}.
7789
7790 For example, an entry defined as:
7791 \begin{codeenv}
7792 \atentry{progenitor}\marg{\meta{id},
7793 \field{adoptparents} = \marg{\meta{parent-1 id},\ldots,\meta{parent-N id}},
7794 \meta{field-name-1} = \margm{text},
7795 \ldots
7796 \meta{field-name-n} = \margm{text}
7797 }
7798 \end{codeenv}
7799 is essentially like:
7800 \begin{codeenv}
7801 \atentry{index}\marg{\meta{id},
7802 \field{progeny} = \marg{\meta{parent-1 id}.\meta{id},\ldots,\meta{parent-N id}.\meta{id}},
7803 \meta{field-name-1} = \margm{text},
7804 \ldots
7805 \meta{field-name-n} = \margm{text}
7806 }
7807 \strut
7808 \atentry{index}\marg{\meta{parent-1 id}.\meta{id},
7809 \field{progenitor} = \margm{id},
7810 \field{parent} = \margm{parent-1 id},
7811 \meta{field-name-1} = \margm{text},
7812 \ldots
7813 \meta{field-name-n} = \margm{text}
7814 }
7815 \strut
7816 \ldots
7817 \strut
7818 \atentry{index}\marg{\meta{parent-N id}.\meta{id},
7819 \field{progenitor} = \margm{id},
7820 \field{parent} = \margm{parent-N id},
7821 \meta{field-name-1} = \margm{text},
7822 \ldots
7823 \meta{field-name-n} = \margm{text}
7824 }
7825 \end{codeenv}
7826 This creates the \glsdisp{mainentry}{main} (\gls{progenitor}) \meta{id} entry, which
7827 contains all the fields (except for \field{adoptparents}) that were
7828 in the original \atentry{progenitor} definition and has the new
7829 field \field{progeny} set to the comma-separated list of
7830 \gls{spawnedentry} labels. The \glspl{mainentry} are defined in the \ext{glstex} file
7831 with \gls{bibglsnewprogenitor}.
7832
7833 In addition to the \glsdisp{mainentry}{main} \meta{id} entry, the
7834 above also creates the spawned \gls{progeny} entries
7835 \code{\meta{parent-1 id}.\meta{id}}, \ldots, \code{\meta{parent-N
7836 id}.\meta{id}} that are dependent on the \glsdisp{mainentry}{main} \meta{id} entry.
7837
7838 The \glspl{spawnedentry} have the \field{parent} field set to the
7839 corresponding label obtained from the \field{adoptparents} list.
7840 This \gls{parententry} must also be defined, as usual for the
7841 \field{parent} field. (This restriction obviously doesn't apply if
7842 \csopt{adopted-parent-field} is changed from the default
7843 \field{parent}.) The spawned entries are defined in the \ext{glstex}
7844 file with \gls{bibglsnewspawnedindex}
7845
7846 If the \glsdisp{mainentry}{main} \gls{progenitor} entry is referenced in the document
7847 then (assuming the default selection criteria) the
7848 \glspl{spawnedentry} will also be automatically selected. You can
7849 check for the existence of the \field{progenitor} field using
7850 \cs{glsxtrifhasfield} and fetch the \field{location} field from the
7851 \gls{mainentry}, if required.
7852
7853 Although the \glspl{spawnedentry} are considered dependents of the
7854 \gls{mainentry}, the reverse doesn't apply. If a \gls{spawnedentry} is referenced
7855 in the document (with \code{\meta{parent-id}.\meta{id}}) then the
7856 \gls{mainentry} and its other spawned entries aren't automatically
7857 selected.
7858
7859 For example, suppose the file \filefmt{entries.bib} contains:
7860 \begin{codeenv}
7861 \atentry{indexplural}\marg{stylesheet, \field{text}=\marg{stylesheet language}}
7862 \strut
7863 \atentry{index}\marg{webdesign, \field{name}=\marg{web design}}
7864 \strut
7865 \atentry{indexplural}\marg{markup, \field{text}=\marg{markup language}}
7866 \strut
7867 \atentry{progenitor}\marg{xml,
7868 \field{name}=\marg{XML},
7869 \field{adoptparents}=\marg{markup}
7870 }
7871 \strut
7872 \atentry{progenitor}\marg{css,
7873 \field{name}=\marg{CSS},
7874 \field{adoptparents}=\marg{stylesheet,webdesign}
7875 }
7876 \strut
7877 \atentry{progenitor}\marg{html,
7878 \field{name}=\marg{HTML},
7879 \field{adoptparents}=\marg{markup,webdesign}
7880 }
7881 \strut
7882 \atentry{progenitor}\marg{xsl,
7883 \field{name}=\marg{XSL},
7884 \field{adoptparents}=\marg{stylesheet}
7885 }
7886 \end{codeenv}
7887 and if the document contains:
7888 \begin{codeenv}
7889 \cmd{documentclass}\marg{article}
7890 \strut
7891 \cmd{usepackage}\oarg{\styopt{record},\styopt[tree]{stylemods},\styopt[index]{style}}\marg{glossaries-extra}
7892 \strut
7893 \gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[all]{selection}}
7894 \strut
7895 \cs{newcommand}*\marg{\cs{glstreenamefmt}}[1]\marg{\idx{param}1}
7896 \cmd{begin}\marg{document}
7897 \cs{printunsrtglossaries}
7898 \cmd{end}\marg{document}
7899 \end{codeenv}
7900 Then the resulting list will be:
7901 \begin{quote}
7902 \setlength{\parindent}{0pt}%
7903 \setlength{\parskip}{0pt plus 0.3pt}%
7904 \glstreeitem CSS\par
7905 \glstreeitem HTML\par
7906 \glstreeitem markup language\par
7907 \glstreesubitem HTML\par
7908 \glstreesubitem XML\par
7909 \glstreeitem stylesheet language\par
7910 \glstreesubitem CSS\par
7911 \glstreesubitem XSL\par
7912 \glstreeitem web design\par
7913 \glstreesubitem CSS\par
7914 \glstreesubitem HTML\par
7915 \glstreeitem XML\par
7916 \glstreeitem XSL\par
7917 \end{quote}
7918 This allows the HTML and CSS entries to be listed under multiple
7919 parents.
7920
7921 The following \atentryfmt{spawn\meta{single-type}} commands are all forms
7922 of \atentry{progenitor} that create the given
7923 \atentryfmt{\meta{single-type}} of entry. The \glspl{spawnedentry} are actually
7924 created with the private \gls{entrytype} \atentryfmt{spawned\meta{type}}. In the
7925 case of \atentry{progenitor}, the \glspl{spawnedentry} are defined as
7926 a \atentryfmt{spawnedindex} entry. These special
7927 \atentryfmt{spawned\meta{type}} \glspl{entrytype} aren't intended for use
7928 in the \ext{bib} file, but if you reference the \gls{entrytype} (for
7929 example, with \csopt[same as entry]{category}) you will get
7930 \atentryfmt{spawned\meta{type}} as the \gls{entrytype}. The
7931 original \gls{entrytype} for the \glspl{spawnedentry} is the same as
7932 the original entry for the \glsdisp{mainentry}{main} \atentry{progenitor} entry.
7933
7934 There is currently only one form of \dual\ \atentry{progenitor} entry and that's
7935 \atentry{spawndualindexentry}. Only the \glsdisp{mainentry}{main} \gls{progenitor} entry
7936 is a \gls{dualentry}. The spawned \gls{progeny} are all \atentry{index}
7937 \glspl{primaryentry}.
7938
7939 \entrysection{spawnindex}
7940
7941 As \atentry{progenitor}, but the \glspl{mainentry} are defined in the
7942 \ext{glstex} file with \gls{bibglsnewspawnindex} and the
7943 spawned entries are defined with \gls{bibglsnewspawnedindex}.
7944
7945 \entrysection{spawnindexplural}
7946
7947 As \atentry{progenitor}, except that it creates
7948 \atentry{indexplural} terms instead of \atentry{index}.
7949 As with \atentry{indexplural}, if the \field{name} field isn't set,
7950 it's assigned to the same value as the \field{plural} field (or the
7951 \hyperref[sec:fallbacks]{fallback} for the \field{plural}, if not defined).
7952
7953 The \glspl{mainentry} are defined in the
7954 \ext{glstex} file with \gls{bibglsnewspawnindexplural} and the
7955 \glspl{spawnedentry} are defined with \gls{bibglsnewspawnedindexplural}.
7956
7957 \entrysection{spawnentry}
7958
7959 As \atentry{progenitor}, except that it creates
7960 \atentry{entry} terms instead of \atentry{index}.
7961 As with \atentry{entry}, the \field{description} field is required
7962 and either \field{name} or \field{parent}.
7963
7964 The \glspl{mainentry} are defined in the
7965 \ext{glstex} file with \gls{bibglsnewspawnentry} and the
7966 \glspl{spawnedentry} are defined with \gls{bibglsnewspawnedentry}.
7967
7968 \entrysection{spawnabbreviation}
7969
7970 As \atentry{progenitor}, except that it creates
7971 \atentry{abbreviation} terms instead of \atentry{index}.
7972 As with \atentry{abbreviation}, the \field{short} and \field{long}
7973 fields are required.
7974
7975 The \glspl{mainentry} are defined in the
7976 \ext{glstex} file with \gls{bibglsnewspawnabbreviation} and the
7977 \glspl{spawnedentry} are defined with \gls{bibglsnewspawnedabbreviation}.
7978
7979 \entrysection{spawnacronym}
7980
7981 As \atentry{progenitor}, except that it creates
7982 \atentry{acronym} terms instead of \atentry{index}.
7983 As with \atentry{acronym}, the \field{short} and \field{long}
7984 fields are required.
7985
7986 The \glspl{mainentry} are defined in the
7987 \ext{glstex} file with \gls{bibglsnewspawnacronym} and the
7988 \glspl{spawnedentry} are defined with \gls{bibglsnewspawnedacronym}.
7989
7990 \entrysection{spawnsymbol}
7991
7992 As \atentry{progenitor}, except that it creates
7993 \atentry{symbol} terms instead of \atentry{index}.
7994 As with \atentry{symbol}, the required fields are \field{name} or
7995 \field{parent}, and the \field{description} field is required if the
7996 \field{name} field is missing.
7997
7998 The \glspl{mainentry} are defined in the
7999 \ext{glstex} file with \gls{bibglsnewspawnsymbol} and the
8000 \glspl{spawnedentry} are defined with \gls{bibglsnewspawnedsymbol}.
8001
8002 \entrysection{spawnnumber}
8003
8004 As \atentry{progenitor}, except that it creates
8005 \atentry{number} terms instead of \atentry{index}.
8006 As with \atentry{number}, the required fields are \field{name} or
8007 \field{parent}, and the \field{description} field is required if the
8008 \field{name} field is missing.
8009
8010 The \glspl{mainentry} are defined in the
8011 \ext{glstex} file with \gls{bibglsnewspawnnumber} and the
8012 \glspl{spawnedentry} are defined with \gls{bibglsnewspawnednumber}.
8013
8014 \entrysection{spawndualindexentry}
8015
8016 As \atentry{progenitor}, except that the \glsdisp{mainentry}{main} (\gls{progenitor})
8017 entry behaves like \atentry{dualindexentry}. The spawned
8018 \gls{progeny} behave like \atentry{index} are so are all considered
8019 \glspl{primaryentry}. The \field{adoptparents} field should therefore reference
8020 \glspl{primaryentry} with the default \csopt[parent]{adopted-parent-field}.
8021
8022 The \glsdisp{mainentry}{main} \primary\ and
8023 \glsdisp{secondaryentry}{secondary} (\dual) entries are defined in
8024 the \ext{glstex} file with \gls{bibglsnewspawndualindexentry} and
8025 \gls{bibglsnewspawndualindexentrysecondary}. The spawned
8026 \gls{progeny} are defined with \gls{bibglsnewspawnedindex}.
8027
8028 \chapter{Resource File Options}
8029 \label{sec:resourceopts}
8030
8031 Make sure that you use \isty{glossaries-extra} with the
8032 \styopt{record} package option. This ensures that \bibgls\ can pick
8033 up the required information from the \iext{aux} file, and both
8034 \styopt[only]{record} and \styopt[nameref]{record} additionally
8035 load the supplementary \isty{glossaries-extra-bib2gls} package.
8036 These two \styopt{record} option values also
8037 switch on the \styopt[none]{sort} package option (if you have a new
8038 enough version of the base \isty{glossaries} package), which means
8039 that there's no attempt to assign or process the \field{sort} key if
8040 it's omitted from \gls{newglossaryentry} (or similar commands). The
8041 \field{sort} key will be provided by \bibgls\ for informational
8042 purposes, but there's no need for \LaTeX\ to write it to any
8043 external files (unless you use \styopt[hybrid]{record},
8044 in which case you need to prevent \bibgls\ from sorting using the
8045 \csopt[none]{sort} resource option).
8046
8047 The \iext{glstex} resource files created by \bibgls\ are loaded in
8048 the document using:
8049 \nosecformatdef{GlsXtrLoadResources}
8050 You can have multiple \gls{GlsXtrLoadResources} commands within your
8051 document. The associated data for each
8052 resource file is called the \igls{resourceset} (see
8053 \sectionref{sec:resourcesets}).
8054
8055 There's a shortcut command:
8056 \nosecformatdef{glsbibdata}
8057 This simply does:
8058 \begin{codeenv}
8059 \gls{GlsXtrLoadResources}\oarg{\csopt[\margm{bib-list}]{src},\meta{options}}
8060 \end{codeenv}
8061
8062 Note that the older command \inlinedef{glsxtrresourcefile} is deprecated
8063 as from \sty{glossaries-extra} v1.55 because it has the potential to cause
8064 a filename clash. If you actually intend to share
8065 \glspl{resourceset}\dash as opposed to sharing \ext{bib} files\dash
8066 across multiple documents then you need to use the \csopt{master}
8067 resource option (see \sectionref{sec:master}).
8068
8069 The optional argument \meta{options} is a comma-separated
8070 \keyvallist. Allowed options are listed below. The option list
8071 applies only to that specific \meta{filename}\ext{glstex} and are
8072 not carried over to the next instance of \gls{GlsXtrLoadResources}.
8073 Only the definitions provided in \atentry{preamble} (if the
8074 interpreter is on and \csopt[true]{interpret-preamble}) are carried
8075 over to the next resource set and, possibly,
8076 \iglspl{crossresourceref} if permitted (see
8077 \sectionref{sec:resourcesets}). The \sty{glossaries-extra} package
8078 doesn't parse the options, but just writes the information to the
8079 \ext{aux} file. This means that any invalid options will be reported
8080 by \bibgls\ not by \sty{glossaries-extra}.
8081
8082 As from \sty{glossaries-extra} v1.40 you can provide a default set
8083 of options by redefining:
8084 \nosecdef{GlsXtrDefaultResourceOptions}
8085 This command will be inserted at the start of the options list for
8086 all resource commands (and will expand as it's written to
8087 the \ext{aux} file). For example:
8088 \begin{codeenv}
8089 \cs{renewcommand}\marg{\gls{GlsXtrDefaultResourceOptions}}\marg{\comment{}
8090 \csopt[all]{selection},\csopt[entries]{src}}
8091 \gls{GlsXtrLoadResources}\oarg{
8092 \csopt[symbols]{type},
8093 \csopt[entrytype=symbol]{match}}
8094 \gls{GlsXtrLoadResources}\oarg{
8095 \csopt[abbreviations]{type},
8096 \csopt[entrytype=abbreviation]{match}}
8097 \end{codeenv}
8098 This acts like:
8099 \begin{codeenv}
8100 \gls{GlsXtrLoadResources}\oarg{
8101 \csopt[all]{selection},\csopt[entries]{src},
8102 \csopt[symbols]{type},
8103 \csopt[entrytype=symbol]{match}}
8104 \gls{GlsXtrLoadResources}\oarg{
8105 \csopt[all]{selection},\csopt[entries]{src},
8106 \csopt[abbreviations]{type},
8107 \csopt[entrytype=abbreviation]{match}}
8108 \end{codeenv}
8109
8110 If you have multiple \ext{bib} files you can either select them all
8111 using \csopt[\meta{bib list}]{src} in a single
8112 \gls{GlsXtrLoadResources} call, if they all require the same settings,
8113 or you can load them separately with different settings applied.
8114
8115 For example, if the files \filefmt{entries-terms.bib} and
8116 \filefmt{entries-symbols.bib} have the same settings:
8117 \begin{codeenv}
8118 \gls{GlsXtrLoadResources}\oarg{\csopt[entries-terms,entries-symbols]{src}}
8119 \end{codeenv}
8120 Alternatively, if they have different settings:
8121 \begin{codeenv}
8122 \gls{GlsXtrLoadResources}\oarg{\csopt[entries-terms]{src},\csopt[main]{type}}
8123 \gls{GlsXtrLoadResources}\oarg{\csopt[entries-symbols]{src},\csopt[use]{sort},\csopt[symbols]{type}}
8124 \end{codeenv}
8125
8126 Note that the sorting is applied to each \igls{resourceset} independently
8127 of other \iglspl{resourceset}. This means that if you have multiple instances
8128 of \gls{GlsXtrLoadResources} but only one glossary type, the glossary
8129 will effectively contain blocks of sorted entries. For example, if
8130 \filefmt{file1.bib} contains:
8131 \begin{codeenv}
8132 \atentry{index}\marg{duck}
8133 \atentry{index}\marg{zebra}
8134 \atentry{index}\marg{aardvark}
8135 \end{codeenv}
8136 and \filefmt{file2.bib} contains:
8137 \begin{codeenv}
8138 \atentry{index}\marg{caterpillar}
8139 \atentry{index}\marg{bee}
8140 \atentry{index}\marg{wombat}
8141 \end{codeenv}
8142 then
8143 \begin{codeenv}
8144 \gls{GlsXtrLoadResources}\oarg{\csopt[file1,file2]{src}}
8145 \end{codeenv}
8146 will result in the list: aardvark, bee, caterpillar, duck, wombat,
8147 zebra. These six entries are all defined when
8148 \csfmt{jobname}\filefmt{.glstex} is read.
8149 Whereas
8150 \begin{codeenv}
8151 \gls{GlsXtrLoadResources}\oarg{\csopt[file1]{src}}
8152 \gls{GlsXtrLoadResources}\oarg{\csopt[file2]{src}}
8153 \end{codeenv}
8154 will result in the list: aardvark, duck, zebra, bee, caterpillar,
8155 wombat. The first three (aardvark, duck, zebra) are defined when
8156 \csfmt{jobname}\filefmt{.glstex} is read. The second three (bee,
8157 caterpillar, wombat) are defined when \csfmt{jobname}\filefmt{-1.glstex}
8158 is read. Since \ics{printunsrtglossary} simply iterates over all
8159 defined entries, this is the ordering used.
8160
8161 Abbreviation styles must be set (using \ics{setabbreviationstyle})
8162 before the resource command that selects the abbreviations from the
8163 appropriate \ext{bib} file, since the entries are defined (through
8164 \gls{newabbreviation} or \gls{newacronym}) when
8165 \gls{GlsXtrLoadResources} inputs the \ext{glstex} file. (Similarly for any
8166 associated abbreviation style commands that must be set before
8167 abbreviations are defined, such as \cs{glsxtrlongshortdescname}.)
8168
8169 Note \bibgls\ allows \iext{bib} files that don't provide any entries.
8170 This can be used to provide commands in \atentry{preamble}.
8171 For example, suppose I have \filefmt{defs.bib} that just contains:
8172 \begin{codeenv}
8173 \atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{strong}}[1]\marg{\cs{textbf}\marg{\ics{cs.color}\marg{red}\idx{param}1}}
8174 \cs{providecommand}\marg{\cmd{parenswap}}[2]\marg{\idx{param}2 (\idx{param}1)}}}
8175 \end{codeenv}
8176 This provides two commands:
8177 \nosecdef{strong}
8178 (which sets the font weight and colour) and
8179 \nosecdef{parenswap}
8180 (which just displays its second argument followed by the first in parentheses).
8181
8182 Suppose I also have \filefmt{entries.bib} that contains:
8183 \begin{codeenv}
8184 \atentry{index}\marg{example,
8185 \field{name}=\marg{\gls{strong}\marg{\gls{parenswap}\marg{stuff}\marg{example}}}
8186 }
8187 \atentry{index}\marg{sample}
8188 \atentry{index}\marg{test}
8189 \atentry{index}\marg{foo}
8190 \atentry{index}\marg{bar}
8191 \end{codeenv}
8192 This contains an entry that requires the commands provided in
8193 \filefmt{defs.bib}, so to ensure those commands are defined, I can
8194 do:
8195 \begin{codeenv}
8196 \gls{GlsXtrLoadResources}\oarg{\csopt[defs,entries]{src}}
8197 \end{codeenv}
8198 Unfortunately this results in the sort value for \code{example} being
8199 set to \code{redexample (stuff)} because the interpreter has
8200 detected the provided commands and expanded:
8201 \begin{codeenv}
8202 \gls{strong}\marg{\gls{parenswap}\marg{stuff}\marg{example}}
8203 \end{codeenv}
8204 to:
8205 \begin{codeenv}
8206 \cs{textbf}\marg{\cs{cs.color}\marg{red}example (stuff)}
8207 \end{codeenv}
8208 It discards font changes, so \cs{textbf} is ignored, but it doesn't
8209 recognise \cs{cs.color} and so doesn't know that the first argument is
8210 just the colour specifier and therefore doesn't discard it.
8211 This means that \qt{\textbf{\color{red}example (stuff)}} is placed
8212 between \qt{foo} and \qt{sample} instead of between \qt{bar} and
8213 \qt{foo}.
8214
8215 I can prevent the interpreter from parsing \atentry{preamble}:
8216 \begin{codeenv}
8217 \gls{GlsXtrLoadResources}\oarg{\csopt[defs,entries]{src},\csopt[false]{interpret-preamble}}
8218 \end{codeenv}
8219 Now when the sort value for \code{example} is obtained from:
8220 \begin{codeenv}
8221 \gls{strong}\marg{\gls{parenswap}\marg{stuff}\marg{example}}
8222 \end{codeenv}
8223 no expansion occurs (since \gls{strong} and \gls{parenswap} are now
8224 unrecognised) so the sort value ends up as:
8225 \code{stuffexample}
8226 which places \qt{\textbf{\color{red}example (stuff)}} between
8227 \qt{sample} and \qt{test}, which is again incorrect.
8228
8229 The best thing to do in this situation is to split the provided
8230 commands into two \iext{bib} files: one that shouldn't be interpreted
8231 and one that should.
8232
8233 For example, \filefmt{defs-nointerpret.bib}:
8234 \begin{codeenv}
8235 \atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\gls{strong}}[1]\marg{\cs{textbf}\marg{\cs{cs.color}\marg{red}\idx{param}1}}}}
8236 \end{codeenv}
8237 and \filefmt{defs-interpret.bib}:
8238 \begin{codeenv}
8239 \atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\gls{parenswap}}[2]\marg{\idx{param}2 (\idx{param}1)}}}
8240 \end{codeenv}
8241 Now the first one can be loaded with \csopt[false]{interpret-preamble}:
8242 \begin{codeenv}
8243 \gls{GlsXtrLoadResources}\oarg{\csopt[defs-nointerpret]{src},\csopt[false]{interpret-preamble}}
8244 \end{codeenv}
8245 This creates a \iext{glstex} file that provides \gls{strong} but
8246 doesn't define any entries. The other file \filefmt{defs-interpret.bib} can
8247 then be loaded with the default \csopt[true]{interpret-preamble}:
8248 \begin{codeenv}
8249 \gls{GlsXtrLoadResources}\oarg{\csopt[defs-interpret,entries]{src}}
8250 \end{codeenv}
8251 The provided commands are remembered by the interpreter, so you can
8252 also do:
8253 \begin{codeenv}
8254 \gls{GlsXtrLoadResources}\oarg{\csopt[defs-interpret]{src}}
8255 \gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}}
8256 \end{codeenv}
8257 The \emph{contents} of \atentry{preamble} are only written to the
8258 associated \iext{glstex} file, but the definitions contained within
8259 the \atentry{preamble} are retained by the interpreter for subsequent
8260 \iglspl{resourceset}.
8261
8262 \section{String Concatenation}
8263 \label{sec:optstringconcat}
8264
8265 Some resource options allow string \gls{concatenation} in their
8266 syntax. This is where fragments or substrings can be joined together
8267 to form a value. This is similar to the way \gls{concatenation}
8268 occurs in \ext{bib} files, but a different operator is used. In
8269 \ext{bib} files, the concatenation operator is \idx{stringconcat} (hash)
8270 but, since this is a problematic character to use in the optional
8271 argument of \gls{GlsXtrLoadResources}, the operator for string
8272 \gls{concatenation} in resource options is \idx{concat-plus} (plus).
8273
8274 A string \gls{concatenation} \meta{element-list} in a resource option
8275 has the following syntax:
8276 \begin{codeenv}
8277 \meta{element-list} ::= \meta{element-value} | \meta{element-value} \idx{concat-plus} \meta{element-list}
8278 \meta{element-value} ::= \meta{string} | \meta{field-ref} | \meta{element-quark}\margm{element-list} | \meta{match-ref}
8279 \meta{match-ref} ::= \gls{MGP}\margm{group-ref}
8280 \meta{group-ref} ::= \meta{index} | \meta{name}
8281 \meta{string} ::= \qtdelim{\meta{tokens}} | \margm{tokens}
8282 \end{codeenv}
8283 The \meta{field-ref} syntax is described below in \sectionref{sec:fieldref}, and is used to
8284 reference a field value.
8285 The element quarks (\meta{element-quark}, described below in
8286 \sectionref{sec:elementquarks}) take an
8287 \meta{element-list} argument. If the \meta{element-list} argument evaluates
8288 to null, they will return null.
8289
8290 \begin{important}
8291 Remember that the argument of \gls{GlsXtrLoadResources} is expanded
8292 as it's written to the \ext{aux} file. This means that care must be
8293 taken to prevent premature expansion of \idxpl{quark} or any
8294 commands that need to be present in a string.
8295 \end{important}
8296
8297 As from \styfmt{glossaries-extra} v1.51, the
8298 \sty{glossaries-extra-bib2gls} package (which is automatically
8299 loaded with the \styopt{record} option) provides the command
8300 \ics{GlsXtrResourceInitEscSequences} which will locally redefine
8301 these \idx{quark} commands to expand to their detokenized form.
8302 So you can do:
8303 \begin{codeenv}
8304 \cs{renewcommand}*\marg{\cs{glsxtrresourceinit}}\marg{\comment{}
8305 \ics{GlsXtrResourceInitEscSequences}
8306 }
8307 \end{codeenv}
8308 This means that you can simply write the \idx{quark} in the resource
8309 option without needing to use \ics{protect} or \idx{cs.string}.
8310 The remainder of this section assumes that \ics{glsxtrresourceinit}
8311 has been redefined to use \ics{GlsXtrResourceInitEscSequences}, as
8312 in the above example.
8313
8314 As with the \ext{bib} format, strings (\meta{string}) can be delimited by braces
8315 \code{\margm{text}} or double-quotes \code{\qtdelim{\meta{text}}}. If you
8316 need a literal double-quote (\idx{doublequotechar}) then either use
8317 brace delimiters or use \gls{quark.doublequote}. If you need the
8318 actual \LaTeX\ accent command \ics{umlaut} then use brace
8319 delimiters. If you need braces that start and end in different
8320 strings then use double-quote delimiters. For example:
8321 \begin{codeenv}
8322 \csopt[
8323 \field{first} = "\gls{cs}\marg{emph}\idx{bgroupchar}" \idx{concat-plus} \field{name} \idx{concat-plus} "\idx{egroupchar}"
8324 ]{assign-fields}
8325 \end{codeenv}
8326
8327 The \meta{element-list} may just contain a single element, such as a
8328 field reference or a constant string, but it must still conform to
8329 the element syntax. For example, if you want to use
8330 \csopt{copy-to-glossary} to copy all entries to a specific glossary,
8331 such as \code{index}, then you will need to markup \code{index} as a
8332 string. For example:
8333 \begin{codeenv}
8334 \csopt[\qtdelim{index}]{copy-to-glossary}
8335 \end{codeenv}
8336 or
8337 \begin{codeenv}
8338 \csopt[\marg{index}]{copy-to-glossary}
8339 \end{codeenv}
8340 Note that the outer braces are stripped by the resource option
8341 parser before the content is parsed as an \meta{element-list}.
8342 If only a single set of braces was used, those braces would be
8343 stripped leaving a bare \code{index}, which would be parsed as a
8344 field reference.
8345
8346 \subsection{Element Quarks}
8347 \label{sec:elementquarks}
8348
8349 The element \idxpl{quark} are uppercase tokens that start with a leading
8350 backslash. They have no meaning to \bibgls's interpreter nor are
8351 they defined in the \LaTeX\ document outside of the scope of
8352 the resource command (unless they happen to coincidentally be
8353 defined by another package or are a custom command). \Idxpl{quark}
8354 occur outside of strings. Any escape sequences occurring within a
8355 string are considered to be \LaTeX\ commands.
8356
8357 \nosecdef{CS}
8358 Returns a control sequence with the control sequence
8359 name obtained from concatenating \meta{element-list}.
8360 Note that this is different from
8361 \gls{cs} which expands to the detokenized control sequence name as
8362 the resource options are written to the \ext{aux} file.
8363
8364 For example, if the \LaTeX\ file has:
8365 \begin{codeenv}
8366 \gls{GlsXtrLoadResources}\oarg{
8367 \csopt[
8368 \field{name} = "\gls{cs}\marg{foo}\marg{" \idx{concat-plus} \field{user1} \idx{concat-plus} "}"
8369 ]{assign-fields}
8370 }
8371 \end{codeenv}
8372 then this will expand the options to the \ext{aux} file as
8373 \begin{codeenv}
8374 \csopt[
8375 \field{name} = "\csfmt{foo}\marg{" \idx{concat-plus} \field{user1} \idx{concat-plus} "}"
8376 ]{assign-fields}
8377 \end{codeenv}
8378 Compare this with:
8379 \begin{codeenv}
8380 \gls{GlsXtrLoadResources}\oarg{
8381 \csopt[
8382 \field{name} = \gls{CS} \marg{ \field{user1} }
8383 ]{assign-fields}
8384 }
8385 \end{codeenv}
8386 which will set the \field{name} value to \csfmt{\meta{csname}} (no
8387 arguments) where \meta{csname} is the value obtained from the
8388 \field{user1} field for that entry. Note that \csfmt{\meta{csname}}
8389 will need to be defined in the document to ensure that the document
8390 compiles without error but will also need to be recognised by
8391 \bibgls\ if the field value needs to be interpreted (such as when
8392 obtaining the \field{sort} value).
8393
8394 \nosecdef{MGP}
8395 The \meta{match-ref} element should only be used with a
8396 \gls{regular-expression} from an associated conditional (see
8397 \sectionref{sec:conditionals}).
8398 For example, the \meta{condition} part of an assignment rule in
8399 \csopt{assign-fields}.
8400
8401 If a match was found, \gls{MGP} can be used to reference a group within the match.
8402 The \meta{group-ref} argument may be either an integer (the group
8403 index) or the group name. For example, suppose a custom field called
8404 \fieldfmt{ordinal} may contain content such as \code{1st} or
8405 \code{10th} and I want to encapsulate the suffix part without
8406 altering the \ext{bib} file. This can be done as follows:
8407 \begin{codeenv}
8408 \csopt[
8409 \fieldfmt{ordinal} =\oarg{o} \gls{MGP}\marg{1} + " \gls{cs}\marg{ord}\marg{" + \gls{MGP}\marg{2} + "}"
8410 \oarg{ ordinal=/(\gls{cs}\marg{d}+)(st|nd|rd|th)/ }
8411 ]{assign-fields}
8412 \end{codeenv}
8413 Alternatively, using named groups:
8414 \begin{codeenv*}
8415 \csopt[
8416 ordinal =\oarg{o} \gls{MGP}\marg{num} + " \gls{cs}\marg{ord}\marg{" + \gls{MGP}\marg{suffix} + "}"
8417 \oarg{ ordinal=/(\idx{regex.question}\idx{regex.lt}num\idx{regex.gt}\gls{cs}\marg{d}+)(\idx{regex.question}\idx{regex.lt}suffix\idx{regex.gt}st|nd|rd|th)/ }
8418 ]{assign-fields}
8419 \end{codeenv*}
8420 Note that the group name shouldn't be delimited with double-quotes.
8421
8422 \begin{important}
8423 The \gls{MGP} quark (which expands to the \gls{MGP} identifier for
8424 \csopt{assign-fields}) isn't the same as \ics{glscapturedgroup}
8425 (which expands to \cs{cs.string}\idx{dollarchar}, allowing a dollar
8426 character to be written to the \ext{aux} file within
8427 the replacement part of \csopt{labelify-replace}).
8428 \end{important}
8429
8430 \nosecdef{TRIM}
8431 Returns its argument with any leading and trailing spaces removed.
8432
8433 \nosecdef{INTERPRET}
8434 Interprets the contents of \meta{element-list} using \bibgls's
8435 interpreter and returns the result, which may be an empty string if
8436 the content only contains unknown commands. Note that the result is
8437 a string with any special characters replaced by detokenized commands, such as
8438 \ics{glsbackslash}. This ensures that the value is suitable to be written
8439 in the entry definition in the \ext{glstex} file.
8440
8441 It's important to remember that the result of \gls{INTERPRET} is a detokenized string.
8442 In general, it's therefore best to have \gls{INTERPRET} as the outermost quark.
8443
8444 Suppose I have a \ext{bib} file that contains:
8445 \begin{codeenv}
8446 \atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{csfmt}}[1]\marg{\cs{glsbackslash} \idx{param}1}}}
8447 \atentry{index}\marg{relax,\field{name}=\marg{\cmd{csfmt}\marg{relax}}}
8448 \atentry{index}\marg{comment,\field{name}=\marg{\cs{cs.percent} comment}}
8449 \end{codeenv}
8450 If the resource options include:
8451 \begin{codeenv}
8452 \csopt[
8453 \field{user1} = \gls{INTERPRET} \marg{ \field{name} } ,
8454 ]{assign-fields}
8455 \end{codeenv}
8456 Then the definitions in the \ext{glstex} file will be:
8457 \begin{codeenv}
8458 \gls{bibglsnewindex}\marg{comment}\comment{}
8459 \marg{\field{user1}=\marg{\cs{glspercentchar} \cs{space} comment},
8460 \field{name}=\marg{\cs{cs.percent} comment},
8461 \field{sort}=\marg{comment|}}
8462 \strut
8463 \gls{bibglsnewindex}\marg{relax}\comment{}
8464 \marg{\field{user1}=\marg{\cs{glsbackslash} relax},
8465 \field{name}=\marg{\cmd{csfmt}\marg{relax}},
8466 \field{sort}=\marg{relax|}}
8467 \end{codeenv}
8468 This ensures that the \LaTeX\ syntax in the \ext{glstex} definitions is valid and
8469 the \field{user1} field can expand to a literal string. (Remember that the document
8470 definition of the custom \csfmt{csfmt} command may be different from the one provided
8471 in the \atentry{preamble} content.)
8472
8473 The \gls{INTERPRET} quark converts \code{\cs{cs.percent} comment} to
8474 \qtt{\% comment} since the interpreter recognises \ics{cs.percent}. However,
8475 if this value is written to the \ext{glstex} file:
8476 \begin{codeenv}
8477 \field{user1}=\marg{\% comment},
8478 \end{codeenv}
8479 then this is invalid. When the \ext{glstex} file is input by \gls{GlsXtrLoadResources},
8480 \LaTeX\ will interpret the percent symbol \code{\%} as a comment and the rest of the
8481 line, including the closing brace, will be ignored. This leads to a missing closing brace error.
8482
8483 In the case of the \qt{relax} entry, since a definition of the custom \csfmt{csfmt}
8484 is provided in \atentry{preamble}, the interpreter will convert \code{\csfmt{csfmt}\marg{relax}}
8485 to the string \qtt{\csfmt{relax}}. If this value is written to the \ext{glstex} file:
8486 \begin{codeenv}
8487 \field{user1}=\marg{\csfmt{relax}},
8488 \end{codeenv}
8489 then this would be parsed as the command \csfmt{relax} when the file is input
8490 by \gls{GlsXtrLoadResources}.
8491
8492 Therefore, \gls{INTERPRET} automatically replaces all the \TeX\ special characters
8493 in the resulting string to ensure that they expand to their literal meanings
8494 in the \LaTeX\ document.
8495
8496 Now suppose instead that the resource options include:
8497 \begin{codeenv}
8498 \csopt[
8499 \field{user1} = \gls{FIRSTUC} \marg{ \gls{INTERPRET} \marg{ \field{name} } },
8500 ]{assign-fields}
8501 \end{codeenv}
8502 This first interprets the value of the \field{name} field and substitutes the special
8503 characters (so \code{\csfmt{relax}} becomes the string \qtt{\csfmt{glsbackslash} relax}).
8504 The resulting string is then converted to \idx{sentencecase}, which results in
8505 \qtt{\csfmt{Glsbackslash} relax} because the initial backslash is now a literal character,
8506 and since it's a non-letter character it's skipped by the case-conversion.
8507 So now the code written to the \ext{glstex} file is:
8508 \begin{codeenv}
8509 \gls{bibglsnewindex}\marg{comment}\comment{}
8510 \marg{\field{user1}=\marg{\csfmt{Glspercentchar} \cs{space} comment},
8511 \field{name}=\marg{\cs{cs.percent} comment},
8512 \field{sort}=\marg{comment|}}
8513 \strut
8514 \gls{bibglsnewindex}\marg{relax}\comment{}
8515 \marg{\field{user1}=\marg{\csfmt{Glsbackslash} relax},
8516 \field{name}=\marg{\cmd{csfmt}\marg{relax}},
8517 \field{sort}=\marg{relax|}}
8518 \end{codeenv}
8519 This is invalid because \csfmt{Glspercentchar} and \csfmt{Glsbackslash} are not defined.
8520
8521 Suppose the order of the quarks is swapped:
8522 \begin{codeenv}
8523 \csopt[
8524 \field{user1} = \gls{INTERPRET} \marg{ \gls{FIRSTUC} \marg{ \field{name} } },
8525 ]{assign-fields}
8526 \end{codeenv}
8527 This results in valid \LaTeX\ code:
8528 \begin{codeenv}
8529 \gls{bibglsnewindex}\marg{comment}\comment{}
8530 \marg{\field{user1}=\marg{\cs{glspercentchar} \cs{space} comment},
8531 \field{name}=\marg{\cs{cs.percent} comment},
8532 \field{sort}=\marg{comment|}}
8533 \strut
8534 \gls{bibglsnewindex}\marg{relax}\comment{}
8535 \marg{\field{user1}=\marg{\cs{glsbackslash} Relax},
8536 \field{name}=\marg{\cmd{csfmt}\marg{relax}},
8537 \field{sort}=\marg{relax|}}
8538 \end{codeenv}
8539 If you don't want the argument of a command to be affected by case-changing
8540 commands, you can use \ics{MFUblocker} or \ics{MFUexcl}. The
8541 \sty{glossaries-extra} package writes this information in the \ext{aux}
8542 file for the benefit of \bibgls. See the \sty{mfirstuc}
8543 manual for further details of those commands.
8544
8545 \nosecdef{INTERPRETNOREPL}
8546 As \gls{INTERPRET} but doesn't replace special characters.
8547 Consider an adjustment to the previous example:
8548 \begin{codeenv}
8549 \csopt[
8550 \field{user1} = \gls{FIRSTUC} \marg{ \gls{INTERPRETNOREPL} \marg{ \field{name} } },
8551 ]{assign-fields}
8552 \end{codeenv}
8553 Now \code{\csfmt{csfmt}\marg{relax}} is converted into the literal string
8554 \qtt{\csfmt{relax}} and then the case-conversion is performed,
8555 which results in the literal string \qtt{\csfmt{Relax}} but this will become
8556 an undefined command in the \ext{glstex} file:
8557 \begin{codeenv}
8558 \field{user1}=\marg{\csfmt{Relax}},
8559 \end{codeenv}
8560 In the case of the \qt{comment} entry, \code{\cs{cs.percent} comment} will
8561 be converted to the literal string \qtt{\% comment}, which will then have the case-conversion
8562 applied, but the \ext{glstex} file will be invalid:
8563 \begin{codeenv}
8564 \field{user1}=\marg{\% Comment},
8565 \end{codeenv}
8566
8567 \nosecdef{REPLACESPCHARS}
8568 Detokenises and replaces special characters with commands like \ics{glsbackslash}.
8569 For example:
8570 \begin{codeenv}
8571 \csopt[
8572 \field{user1} = \gls{REPLACESPCHARS} \marg{
8573 \gls{FIRSTUC} \marg{ \gls{INTERPRETNOREPL} \marg{ \field{name} } } },
8574 ]{assign-fields}
8575 \end{codeenv}
8576 This rather long-winded assignment produces the same result as:
8577 \begin{codeenv}
8578 \csopt[
8579 \field{user1} = \gls{INTERPRET} \marg{ \gls{FIRSTUC} \marg{ \field{name} } },
8580 ]{assign-fields}
8581 \end{codeenv}
8582 A difference can be observed if the custom command is made a blocker or exclusion
8583 using \ics{MFUblocker} or \ics{MFUexcl}.
8584
8585 \nosecdef{LABELIFY}
8586 Converts the contents of \meta{element-list} into a label string,
8587 according to the \csopt{labelify} criteria.
8588
8589 \nosecdef{LABELIFYLIST}
8590 Converts the contents of \meta{element-list} into a label-list string,
8591 according to the \csopt{labelify-list} criteria.
8592
8593 \nosecdef{LEN}
8594 When used within an element list, \gls{LEN} returns the length of
8595 its \meta{element-list} argument as a string or null if \meta{element-list}
8596 evaluates to null. Note that this is different from using \gls{LEN}
8597 in a numerical condition where the result is always an integer (see
8598 \sectionref{sec:conditionals}).
8599 This means that \code{\gls{LEN}\margm{list1} \idx{concat-plus}
8600 \gls{LEN}\margm{list2}} performs string \gls{concatenation} not numerical
8601 addition. Instead, use \code{\gls{LEN}\marg{\meta{list1}
8602 \idx{concat-plus} \meta{list2}}} for the combined length.
8603
8604 The length is the detokenised length, for example,
8605 if the \field{name} field has the value \code{\cs{emph}\marg{x}}
8606 then \code{\gls{LEN}\marg{\field{name}}} will evaluate to the string
8607 \qtdelim{8}. You can use
8608 \begin{codeenv}
8609 \gls{LEN}\marg{\gls{INTERPRET}\margm{element-list}}
8610 \end{codeenv}
8611 to find the length without \LaTeX\ commands.
8612
8613 The \idxpl{quark} below identify case-changing functions. The
8614 \meta{element-list} argument will be converted using the appropriate
8615 function and the result will be returned. If \meta{element-list}
8616 evaluates to null then null will be returned.
8617
8618 The case-changing functions will use the \gls{resource-locale}, but
8619 whether or not \bibgls\ recognises the correct rules for the locale
8620 depends on whether or not the locale is correctly supported by the
8621 Java locale provider. The \langxml\ may provide assistance with
8622 case-conversion (see \sectionref{sec:lang.xml}). Note that the
8623 case-change is performed by \bibgls\ not by inserting \LaTeX\
8624 case-changing commands into the code.
8625
8626 \begin{itemize}
8627 \item \inlinedef{LC} converts \meta{element-list} to \idx{lowercase};
8628 \item \inlinedef{UC} converts \meta{element-list} to \idx{uppercase};
8629 \item \inlinedef{FIRSTLC} converts the first letter of
8630 \meta{element-list} to \idx{lowercase};
8631 \item \inlinedef{FIRSTUC} converts the first letter of
8632 \meta{element-list} to \idx{uppercase} (\idx{sentencecase});
8633 \item \inlinedef{TITLE} converts \meta{element-list} to \idx{titlecase}.
8634 \end{itemize}
8635
8636 There is an additional token \inlinedef{NOCHANGE} which simply
8637 evaluates \meta{element-list} and returns it
8638 unchanged.\footnote{The \gls{NOCHANGE} support wasn't
8639 intentional, but was simply a by-product of the original
8640 implementation of the case-changing commands.} This isn't
8641 like \cs{NoCaseChange} but is more like \cs{@firstofone}. There is
8642 little need for it so it's not defined by
8643 \ics{GlsXtrResourceInitEscSequences}. The only plausible use for it
8644 is if you have a class or package that contains something like:
8645 \begin{codeenv}
8646 \csfmt{newcommand}\marg{\csfmt{mycase}}\marg{NOCHANGE}
8647 \comment{later as the result of some condition:}
8648 \csfmt{renewcommand}\marg{\csfmt{mycase}}\marg{FIRSTUC}
8649 \comment{later on:}
8650 \gls{GlsXtrLoadResources}\oarg{
8651 \csopt[
8652 \field{name}=\oarg{o} \gls{cs}\marg{\csfmt{mycase}}\marg{\field{name}},
8653 \comment{other assignments \ldots}
8654 ]{assign-fields}
8655 }
8656 \end{codeenv}
8657 In most cases, it should be possible to achieve the same result with a
8658 conditional associated with the resource option or by adjusting the
8659 content passed to the resource command. For example:
8660 \begin{codeenv}
8661 \csfmt{newcommand}\marg{\csfmt{nameassign}}\marg{}
8662 \comment{later as the result of some condition:}
8663 \csfmt{renewcommand}\marg{\csfmt{nameassign}}\marg{name=\oarg{o}\gls{FIRSTUC}\marg{name},}
8664 \comment{later on:}
8665 \gls{GlsXtrLoadResources}\oarg{
8666 \csopt[
8667 \csfmt{nameassign}
8668 \comment{other assignments \ldots}
8669 ]{assign-fields}
8670 }
8671 \end{codeenv}
8672
8673 \subsection{Field Reference}
8674 \label{sec:fieldref}
8675
8676 The \idx{field-reference} (\meta{field-ref}) syntax is more complicated:
8677 \begin{codeenv}
8678 \meta{field-ref} ::= \meta{value-ref} | \meta{entry-ref} \idx{follow} \meta{field-ref}
8679 \meta{entry-ref} ::= self | parent | root
8680 \meta{value-ref} ::= \meta{field-name} | \meta{label-ref}
8681 \meta{label-ref} ::= \meta{label-type} \idx{follow} \meta{label-delineator}
8682 \meta{label-type} ::= entrytype | entrylabel | entrybib
8683 \meta{label-delineator} ::= original | actual
8684 \end{codeenv}
8685 where \meta{field-name} is the required field name. Note that field
8686 names (which need to be used in a string \gls{concatenation}) can't include
8687 any of the \gls{concatenation} or conditional markup special characters:
8688 \idx{concat-plus} \idx{startoptional} \idx{endoptional}
8689 \idx{equalsassign} \idx{commasep} \idx{ltcmp} \idx{gtcmp} or
8690 \idx{doublequotechardelim}.
8691
8692 The \meta{entry-ref} part indicates which entry the referenced field
8693 belongs to. The keywords are: \code{self} (the entry itself),
8694 \code{parent} (the entry's \parent), and \code{root} (the entry's
8695 \glsdisp{hierarchicalglossary}{hierarchical root}, not including the
8696 entry itself). Note that with options such as
8697 \csopt{assign-fields} the entry's \glspl{ancestor} must be
8698 defined before the entry in the \ext{bib} file because their fields
8699 can only be referenced after they have been processed. A
8700 grandparent entry can be referenced with \code{parent \idx{follow}
8701 parent \idx{follow}}. Since \qt{parent} is also a field name, if
8702 the keyword \code{parent} is followed by \idx{follow} then the
8703 keyword refers to the \gls{parententry} otherwise it refers to the
8704 \field{parent} field. For example,
8705 \code{self \idx{follow} parent} refers to the value of the entry's
8706 \field{parent} field, which is the \gls{parententry}['s] label, whereas
8707 \code{parent \idx{follow} name} refers to the value of the entry's parent's
8708 \field{name} field.
8709
8710
8711 The special keywords identify values that aren't normally stored in
8712 a field. The keyword must be followed by the \meta{delineator},
8713 which may be \code{original} or \code{actual}. Available keywords:
8714
8715 \begin{description}
8716
8717 \item[\code{entrytype}] the \gls{entrytype}, without the leading
8718 \code{@}, where \code{original} refers to the original
8719 \gls{entrytype} used in the \ext{bib} file and \code{actual} refers
8720 to the actual \gls{entrytype}, which may have changed as a result of
8721 \csopt{entry-type-aliases} (but remember that you can't match the
8722 special entry types described in \sectionref{sec:specialentrytypes});
8723
8724 \item[\code{entrylabel}] the entry label, where \code{original}
8725 refers to the original label used in the \ext{bib} file and
8726 \code{actual} refers to the actual label, which may have been
8727 altered by options such as \csopt{label-prefix};
8728
8729 \item[\code{entrybib}] the \ext{bib} file the entry was defined in,
8730 where \code{original} refers to the basename (without the
8731 \code{.bib} extension, regardless of whether or not it was included
8732 in \csopt{src}) and \code{actual} refers to the file name
8733 (including the extension and path).
8734
8735 \end{description}
8736
8737 If a syntax error occurs, the error message will show how \bibgls\
8738 has scanned the information so far. For example, in the case of
8739 \code{\csopt[parent \field{name}]{assign-fields}} the message will be:
8740 \begin{quote}\ttfamily
8741 Error: Invalid syntax for option '\csopt{assign-fields}': Expected
8742 one of \idx{follow} \idx{concat-plus} \idx{startoptional} after
8743 ' self \idx{follow} parent', found 'n'
8744 \end{quote}
8745 This indicates that it has read \qt{parent} as meaning the
8746 \field{parent} field of the current entry since it isn't followed by
8747 \qt{\idx{follow}}.
8748
8749 \section{Complex Conditionals}
8750 \label{sec:conditionals}
8751
8752 Some options may have a conditional in their value. In certain
8753 cases, such as \csopt{match}, the condition is provided as a
8754 \gls{regular-expression}, but other conditionals (such as in
8755 \csopt{assign-fields}) are complex. This section describes that
8756 complex conditional syntax.
8757
8758 For example, suppose you want to use \csopt{post-description-dot}
8759 to automatically append a dot to descriptions but not to entries
8760 that have been defined with \atentry{symbol} or \atentry{number}:
8761 \begin{codeenv}
8762 \csopt[check]{post-description-dot},
8763 \csopt[
8764 entrytype \idx{follow} original = \qtdelim{symbol}
8765 \idx{pipeor} entrytype \idx{follow} original = \qtdelim{number}
8766 ]{post-description-dot-exclude}
8767 \end{codeenv}
8768
8769 The tokens \idx{ampand} and \idx{pipeor} indicate logical
8770 \qt{AND} and \qt{OR}, respectively, and \idx{exclamnot} indicates
8771 negation. Parentheses \idx{openparenchar} and \idx{closeparenchar}
8772 may be used to control the order of precedence. For example,
8773 \begin{codeenv}
8774 \meta{boolean1} \idx{pipeor} (\meta{boolean2} \idx{ampand} \idx{exclamnot} \meta{boolean3})
8775 \end{codeenv}
8776
8777 Available boolean functions are in the form:
8778 \begin{codeenv}
8779 \meta{value1} \meta{cmp} \meta{value2}
8780 \end{codeenv}
8781 where \meta{value1} is the left-hand value and \meta{value2} is the
8782 right-hand value. The middle \meta{cmp} operator identifies the comparison
8783 function.
8784
8785 The left-hand \meta{value1} may be a field reference \meta{field-ref} or
8786 the integer \idx{quark} \code{\gls{LEN}\margm{element-list}} or
8787 the concatenate \idx{quark} \code{\gls{CAT}\margm{element-list}},
8788 where \meta{field-ref} references a field value and
8789 \meta{element-list} is an element list, using the same
8790 syntax described in \sectionref{sec:optstringconcat}.
8791
8792 The right-hand \meta{value2} may be a field reference
8793 \meta{field-ref} or \code{\gls{CAT}\margm{element-list}} or
8794 \gls{NULL} or a constant string (\qtdelim{\meta{string}} or
8795 \margm{string}) or a number or a \gls{regular-expression}. You can't
8796 use \gls{LEN} on the right-hand as a numeric value (but it may occur
8797 inside the argument \gls{CAT}). You can't use \gls{NULL} or a
8798 \gls{regular-expression} on the left-hand side.
8799
8800 Where \meta{value1} is \code{\gls{LEN}\margm{element-list}}, the length
8801 evaluates to an integer and may only be used in the numerical
8802 comparisons. If \meta{element-list} is null, then the length will be~0.
8803 The \gls{LEN} \idx{quark} can't be used in the right hand
8804 \meta{value2} part of a numerical comparison. Note that if \gls{LEN}
8805 occurs inside the argument of \gls{CAT} then it becomes a string not
8806 a number.
8807
8808 \nosecdef{CAT}
8809 Where \meta{value1} or \meta{value2} is \code{\gls{CAT}\margm{element-list}}, the
8810 \meta{element-list} will be evaluated and treated as a string, which
8811 will be null if \meta{element-list} evaluates to null.
8812
8813 \nosecdef{NULL}
8814 The null \idx{quark} may only be used as \meta{value2} for the
8815 equality and inequality comparisons. It can't be used in any other
8816 context. Note that the numeric \gls{LEN} doesn't return null.
8817
8818 Where a field value is referenced (\meta{field-ref}), if the field
8819 value is undefined (either the field isn't set or the referenced
8820 ancestor entry hasn't been defined) then, if the designated action
8821 is \qt{fallback} (for example,
8822 \csopt[fallback]{assign-missing-field-action}), the fallback value
8823 is obtained (see \sectionref{sec:fallbacks}). If the value is still
8824 undefined it will be considered a null value for the purposes of the
8825 comparison. Note that if the designated action is \qt{empty} (for
8826 example, \csopt[empty]{assign-missing-field-action}) there will be
8827 no null values.
8828
8829 \begin{codeenv*}
8830 \meta{value1}\idx{equalscmp}\gls{NULL}
8831 \end{codeenv*}
8832 Evaluates to true if \meta{value1} is null.
8833
8834 \begin{codeenv*}
8835 \meta{value1}\idx{notequalscmp}\gls{NULL}
8836 \end{codeenv*}
8837 Evaluates to true if \meta{value1} is not null.
8838
8839 For the remaining comparisons, null values will be treated as an
8840 empty string. Once the \meta{field-ref} or \gls{CAT} references have
8841 been evaluated, their returned value will be turned into a
8842 detokenized string for the purposes of the comparison.
8843
8844 The detokenized values from a field reference may contain any TAB or
8845 newline characters or additional spacing that are present in the
8846 \ext{bib} file (unless they have already been stripped by other
8847 resource options or field assignments). However, redundant spacing
8848 in any literal strings (\qtdelim{\meta{string}} or \code{\margm{string}})
8849 are likely to be lost when the resource options are written to the
8850 \ext{aux} file.
8851
8852 \begin{codeenv}
8853 \meta{value1}=\idx{slashchar}\meta{regex}\idx{slashchar}
8854 \meta{value1}=\idx{slashchar}\meta{regex}\idx{slashchar}i
8855 \end{codeenv}
8856 Evaluates to true if the value matches the given \gls{anchored}
8857 \gls{regular-expression} \meta{regex}. If \qtt{i} follows the terminating
8858 \idx{slashchar} then the match is case-insensitive. No other modifiers
8859 are recognised, but you can use embedded flag expressions, such as
8860 \code{?s} for \qt{single-line} mode.
8861
8862 In the following string comparisons, the right-hand \meta{string} is
8863 a constant string that must be delimited with double-quotes or braces. The
8864 comparisons are according to the Unicode code points (not
8865 locale-sensitive), but if the string is followed by \qtt{i}, a
8866 case-insensitive comparison is used.
8867
8868 \begin{codeenv*}
8869 \meta{value1}\idx{equalscmp}\meta{string}
8870 \meta{value1}\idx{equalscmp}\meta{string}i
8871 \end{codeenv*}
8872 Evaluates to true if the value is equal to the string.
8873 For example:
8874 \begin{codeenv}
8875 \field{category}\idx{equalscmp}\qtdelim{abbreviation}
8876 \end{codeenv}
8877
8878 \begin{codeenv*}
8879 \meta{value1}\idx{notequalscmp}\meta{string}
8880 \meta{value1}\idx{notequalscmp}\meta{string}i
8881 \end{codeenv*}
8882 Evaluates to true if the value is not equal to the string.
8883
8884 \begin{codeenv*}
8885 \meta{value1}\idx{ltcmp}\meta{string}
8886 \meta{value1}\idx{ltcmp}\meta{string}i
8887 \end{codeenv*}
8888 Evaluates to true if the value is lexicographically less than the string.
8889
8890 \begin{codeenv*}
8891 \meta{value1}\idx{lecmp}\meta{string}
8892 \meta{value1}\idx{lecmp}\meta{string}i
8893 \end{codeenv*}
8894 Evaluates to true if the value is lexicographically less than or
8895 equal to the string.
8896
8897 \begin{codeenv*}
8898 \meta{value1}\idx{gtcmp}\meta{string}
8899 \meta{value1}\idx{gtcmp}\meta{string}i
8900 \end{codeenv*}
8901 Evaluates to true if the value is lexicographically greater than the string.
8902
8903 \begin{codeenv*}
8904 \meta{value1}\idx{gecmp}\meta{string}
8905 \meta{value1}\idx{gecmp}\meta{string}i
8906 \end{codeenv*}
8907 Evaluates to true if the value is lexicographically greater than or
8908 equal to the string.
8909
8910 In the following numerical comparisons, the given \meta{number}
8911 should use \qtt{.} for the decimal point and no number group
8912 separators. If the \meta{number} doesn't contain a decimal point or
8913 if \meta{value1} is the \code{\gls{LEN}\margm{element-list}} quark
8914 then an integer comparison is assumed. If \meta{value1} is
8915 empty or isn't numeric it will be treated as 0. The number
8916 shouldn't be delimited by quotes or braces.
8917
8918 \begin{codeenv*}
8919 \meta{value1}\idx{equalscmp}\meta{number}
8920 \end{codeenv*}
8921 Evaluates to true if the value is equal to \meta{number}.
8922 For example:
8923 \begin{codeenv}
8924 \gls{LEN}\marg{\field{user1}}\idx{equalscmp}0.9
8925 \end{codeenv}
8926 This will return true if the \field{user1} field length is 0 and
8927 false otherwise. This is because \gls{LEN} enforces an integer
8928 comparison which means that 0.9 is converted to 0.
8929 Similarly:
8930 \begin{codeenv}
8931 \gls{CAT}\marg{\qtdelim{0.9}}\idx{equalscmp}0
8932 \end{codeenv}
8933 This will return true because the \meta{number} 0 is an integer
8934 which enforces an integer comparison so the string \qtdelim{0.9}
8935 will be converted to the number~0.
8936 Compare this with:
8937 \begin{codeenv}
8938 \gls{CAT}\marg{\qtdelim{0.9}}\idx{equalscmp}0.0
8939 \end{codeenv}
8940 This will return false because the \meta{number} 0.0 is a decimal,
8941 so a decimal comparison will be used.
8942
8943 \begin{codeenv*}
8944 \meta{value1}\idx{notequalscmp}\meta{number}
8945 \end{codeenv*}
8946 Evaluates to true if the value is not equal to \meta{number}.
8947
8948 \begin{codeenv*}
8949 \meta{value1}\idx{ltcmp}\meta{number}
8950 \end{codeenv*}
8951 Evaluates to true if the value is less than \meta{number}.
8952
8953 \begin{codeenv*}
8954 \meta{value1}\idx{lecmp}\meta{number}
8955 \end{codeenv*}
8956 Evaluates to true if the value is less than or equal to \meta{number}.
8957
8958 \begin{codeenv*}
8959 \meta{value1}\idx{gtcmp}\meta{number}
8960 \end{codeenv*}
8961 Evaluates to true if the value is greater than \meta{number}.
8962
8963 \begin{codeenv*}
8964 \meta{value1}\idx{gecmp}\meta{number}
8965 \end{codeenv*}
8966 Evaluates to true if the value is greater than or equal to \meta{number}.
8967
8968 Finally, the following are string comparisons made after
8969 evaluating and detokenizing both \meta{value1} and \meta{value2}. The
8970 comparisons are case-sensitive and according to the Unicode code
8971 points (not locale-sensitive).
8972
8973 \begin{codeenv*}
8974 \meta{value1}\idx{equalscmp}\meta{value2}
8975 \end{codeenv*}
8976 Evaluates to true if \meta{value1} is equal to \meta{value2}.
8977 For example:
8978 \begin{codeenv}
8979 \field{name} \idx{equalscmp} parent \idx{follow} \field{name}
8980 \end{codeenv}
8981
8982 \begin{codeenv*}
8983 \meta{value1}\idx{notequalscmp}\meta{value2}
8984 \end{codeenv*}
8985 Evaluates to true if \meta{value1} is not equal to \meta{value2}.
8986
8987 \begin{codeenv*}
8988 \meta{value1}\idx{ltcmp}\meta{value2}
8989 \end{codeenv*}
8990 Evaluates to true if \meta{value1} is lexicographically less than
8991 \meta{value2}.
8992
8993 \begin{codeenv*}
8994 \meta{value1}\idx{lecmp}\meta{value2}
8995 \end{codeenv*}
8996 Evaluates to true if \meta{value1} is lexicographically less than or
8997 equal to \meta{value2}.
8998
8999 \begin{codeenv*}
9000 \meta{value1}\idx{gtcmp}\meta{value2}
9001 \end{codeenv*}
9002 Evaluates to true if \meta{value1} is lexicographically greater than
9003 \meta{value2}.
9004
9005 \begin{codeenv*}
9006 \meta{value1}\idx{gecmp}\meta{value2}
9007 \end{codeenv*}
9008 Evaluates to true if \meta{value} is lexicographically greater than or
9009 equal to \meta{value2}.
9010
9011 \begin{codeenv*}
9012 \meta{value1} \inlinedef{IN} \meta{value2}
9013 \end{codeenv*}
9014 Evaluates to true if \meta{value1} is a substring of \meta{value2}.
9015 If \meta{value1} is empty or null it's considered
9016 not a substring regardless of the value of \meta{value2}.
9017
9018 \begin{codeenv*}
9019 \meta{value1} \inlinedef{NIN} \meta{value2}
9020 \end{codeenv*}
9021 The negation of the \gls{IN} test. Evaluates to true if \meta{value1} is
9022 not a substring of \meta{value2}. This is equivalent to:
9023 \begin{codeenv}
9024 \idx{exclamnot} \meta{value1} \gls{IN} \meta{value2}
9025 \end{codeenv}
9026
9027 \begin{codeenv*}
9028 \meta{value1} \inlinedef{PREFIXOF} \meta{value2}
9029 \end{codeenv*}
9030 Evaluates to true if \meta{value1} is a prefix of \meta{value2}
9031 (that is, \meta{value2} starts with \meta{value1}).
9032 If \meta{value1} is empty or null it's considered
9033 not a prefix regardless of \meta{value2}.
9034
9035 \begin{codeenv*}
9036 \meta{value1} \inlinedef{NOTPREFIXOF} \meta{value2}
9037 \end{codeenv*}
9038 Evaluates to true if \meta{value1} is not a prefix of \meta{value2}.
9039 This is equivalent to:
9040 \begin{codeenv}
9041 \idx{exclamnot} \meta{value1} \gls{PREFIXOF} \meta{value2}
9042 \end{codeenv}
9043
9044 \begin{codeenv*}
9045 \meta{value1} \inlinedef{SUFFIXOF} \meta{value2}
9046 \end{codeenv*}
9047 Evaluates to true if \meta{value1} is a suffix of \meta{value2}
9048 (that is, \meta{value2} ends with \meta{value1}).
9049 If \meta{value1} is empty or null it's considered
9050 not a suffix regardless of \meta{value2}.
9051
9052 \begin{codeenv*}
9053 \meta{value1} \inlinedef{NOTSUFFIXOF} \meta{value2}
9054 \end{codeenv*}
9055 Evaluates to true if \meta{value1} is not a suffix of \meta{value2}.
9056 This is equivalent to:
9057 \begin{codeenv}
9058 \idx{exclamnot} \meta{value1} \gls{SUFFIXOF} \meta{value2}
9059 \end{codeenv}
9060
9061
9062 \section{General Options}
9063 \label{sec:generalopts}
9064
9065 \optsection{charset}
9066
9067 If the character \igls{encoding} hasn't been supplied in the \iext{bib} file
9068 with the \gls{encoding} comment
9069 \begin{alltt}
9070 \idx{commentchar} Encoding: \meta{encoding-name}
9071 \end{alltt}
9072 then you can supply the correct \gls{encoding} using
9073 \csopt[encoding-name]{charset}. In general, it's better to include
9074 the \gls{encoding} in the \ext{bib} file where it can also be read by
9075 a \ext{bib} managing systems, such as JabRef.
9076
9077 See \longarg{tex-encoding} for the \gls{encoding} used to write the \ext{glstex}
9078 file, and see \sectionref{sec:defencoding} for information about the
9079 default encoding.
9080
9081 \optsection{locale}
9082
9083 Sets the default \glsdisp{resource-locale}{locale} for the current
9084 \gls{resourceset}. In general, it's best to set this at the start of
9085 the resource option list, if required. If not set, the default
9086 will be the \gls{document-locale}, if supplied, otherwise the
9087 \gls{Java-locale} will be used.
9088
9089 \optsection{wordify-math-greek}
9090
9091 Instructs the interpreter to replace known math Greek commands with
9092 words instead of the applicable symbol. For example, if an entry has
9093 been defined as:
9094 \begin{codeenv}
9095 \atentry{index}\marg{a-Fe,
9096 \field{name}=\marg{\cs{ensuremath}\marg{\ics{alpha}}-iron}
9097 }
9098 \end{codeenv}
9099 Then with \csopt[true]{wordify-math-greek} the interpreter will obtain
9100 the sort value \qt{alpha-iron}. This only works for commands
9101 recognised by the \texparserlib\ as Math Greek commands.
9102
9103 With the default \csopt[false]{wordify-math-greek}, the interpreter
9104 will convert \cs{alpha} into the nearest appropriate Unicode
9105 character.
9106
9107 The textual replacement depends on whether or not a corresponding
9108 entry is available in the language file \metafilefmt{bib2gls-extra-}{lang}{.xml}
9109 for the current resource locale. If no entry is found, the control
9110 sequence name (or substring) will typically be used.
9111
9112 \optsection{wordify-math-symbol}
9113
9114 Similar to \csopt{wordify-math-greek}, this option will apply to
9115 other known math symbol commands. Again, this only works for a
9116 limited set of commands recognised by the \texparserlib. An
9117 alternative is to provide alternative definitions for \bibgls\ that
9118 aren't picked up by \LaTeX, or use \ics{IfNotBibGls}, or use a more
9119 appropriate field for sorting.
9120
9121 \optsection{interpret-preamble}
9122
9123 This is a boolean option that determines whether or not the
9124 interpreter should parse the contents of \atentry{preamble}.
9125 The default is \optfmt{true}. If \optfmt{false}, the preamble
9126 contents will still be written to the \iext{glstex} file, but any
9127 commands provided in the preamble won't be recognised by the
9128 interpreter (see \sectionref{sec:texparserlib}).
9129
9130 Related options are: \csopt{set-widest} (which uses the interpreter to determine
9131 the widest name for the \glostyle{alttree} style or the
9132 \isty{glossary-longextra} styles), \csopt{interpret-label-fields} (which governs
9133 whether or not fields that must only contain a label should be interpreted),
9134 \csopt{labelify} (which converts a field into a string suitable for use as a
9135 label), and \csopt{labelify-list} (which converts a field into a string suitable
9136 for use as a comma-separated list of labels).
9137
9138 \optsection{write-preamble}
9139
9140 This is a boolean option that determines whether or not the
9141 preamble should be written to the \ext{glstex} file. The default
9142 is \optfmt{true}. Note that the preamble will
9143 still be parsed if \csopt[true]{interpret-preamble} even if
9144 \csopt[false]{write-preamble}. This means it's possible to
9145 provide \bibgls\ command definitions in \atentry{preamble}
9146 that don't get seen by \LaTeX.
9147
9148 \optsection{set-widest}
9149
9150 The \glostyle{alttree} glossary style needs to know the widest
9151 \field{name} (for each level, if \hierarchical). This can be set
9152 using \ics{glssetwidest} provided by the \isty{glossary-tree}
9153 package (or similar commands like \ics{glsupdatewidest} provided by
9154 \isty{glossaries-extra-stylemods}), but this requires knowing
9155 which name is the widest. Alternatively, one of the iterative commands
9156 such as \ics{glsFindWidestTopLevelName} can be used, which slows the
9157 document build as it has to iterate over all defined entries.
9158
9159 The \isty{glossary-longextra} package, provided with
9160 \sty{glossaries-extra} v1.37+, also needs to know the widest name,
9161 but in this case only the \gls{top-levelentry}{top-level} is needed.
9162 If this has already been found through the commands provided with
9163 the \glostyle{alttree} style then that value will be used as the
9164 default, but you can set another value that's only used for the
9165 \sty{glossary-longextra} styles with \ics{glslongextraSetWidest}.
9166
9167 The \sty{glossaries-extra-bib2gls} package provides \ics{glsxtrSetWidest},
9168 which sets the widest name for those styles that need it. As from version
9169 1.8, \bibgls\ now checks for the existence of this command and will use it with
9170 \csopt{set-widest} to allow for the new styles provided by the
9171 \sty{glossary-longextra} package.
9172
9173 The boolean option \csopt[true]{set-widest} will try to calculate
9174 the widest names for each \hierarchicallevel\ to help remove the need
9175 to determine the correct value within the document.
9176 Since \bibgls\ doesn't know the fonts that will be used
9177 in the document or if there are any non-standard commands that
9178 aren't provided in the \ext{bib} files preamble, \emph{this option may not
9179 work}. For example, if one entry has the \field{name} defined as:
9180 \begin{codeenv}
9181 \field{name}=\marg{some \marg{\cmd{Huge} huge} text}
9182 \end{codeenv}
9183 and another entry has the \field{name} defined as:
9184 \begin{codeenv}
9185 \field{name}=\marg{some \marg{\cmd{small} small} text}
9186 \end{codeenv}
9187 then \bibgls\ will determine that the second name is the widest
9188 although the first will actually be wider when it's rendered in the
9189 document.
9190
9191 When using this option, the transcript file will include the message:
9192 \begin{alltt}
9193 Calculated width of '\meta{text}': \meta{number}
9194 \end{alltt}
9195 where \meta{text} is \bibgls's interpretation of the contents of the
9196 \field{name} field and \meta{number} is a rough guide to the width
9197 of \meta{text} assuming the operating system's default serif font.
9198 The entry that has the largest \meta{number} is the one that will be
9199 selected. This will then be implemented as follows:
9200 \begin{itemize}
9201 \item If the \field{type} is unknown then:
9202 \begin{itemize}
9203 \item if the interpreter resolves all \field{name} fields to the
9204 empty string (that is the \field{name} fields all consist of
9205 unknown commands) then
9206 \begin{itemize}
9207 \item if there are \glspl{childentry} \gls{bibglssetwidestfallback}
9208 is used,
9209 \item otherwise \gls{bibglssetwidesttoplevelfallback} is used;
9210 \end{itemize}
9211 \item otherwise \gls{bibglssetwidest} is used.
9212 \end{itemize}
9213 \item If the \field{type} is known then:
9214 \begin{itemize}
9215 \item if the interpreter resolves all \field{name} fields for that
9216 type to the empty string (that is the \field{name} fields all consist of
9217 unknown commands) then
9218 \begin{itemize}
9219 \item if there are \glspl{childentry} \gls{bibglssetwidestfortypefallback}
9220 is used,
9221 \item otherwise
9222 \gls{bibglssetwidesttoplevelfortypefallback} is used;
9223 \end{itemize}
9224 \item otherwise \gls{bibglssetwidestfortype} is used.
9225 \end{itemize}
9226 \end{itemize}
9227 This leaves \TeX\ to compute the width according to the document
9228 fonts. If \bibgls\ can't correctly determine the widest entry then
9229 you will need to use one of the commands provided by
9230 \sty{glossary-tree}, \sty{glossary-longextra} or
9231 \sty{glossaries-extra-stylemods} to set it.
9232
9233 In general, if you have more than one glossary it's best to
9234 set the \field{type} using options like \csopt{type} and
9235 \csopt{dual-type} if you use \csopt{set-widest}.
9236
9237 \optsection{entry-type-aliases}
9238
9239 In the \ext{bib} file, the data is identified by
9240 \code{@\meta{entry-type}}, such as \atentry[noindex]{abbreviation}.
9241 It may be that you want to replace all instances of
9242 \code{@\meta{entry-type}} with a different
9243 type of entry. For example, suppose my \ext{bib} file
9244 contains abbreviations defined in the form:
9245 \begin{codeenv}
9246 \atentry{abbreviation}\marg{html,
9247 \field{short} = \marg{html},
9248 \field{long} = \marg{hypertext markup language},
9249 \field{description} = \marg{a markup language for creating web pages}
9250 }
9251 \end{codeenv}
9252 but suppose in one of my documents I actually want all these
9253 abbreviations defined with \atentry[noindex]{dualabbreviationentry}
9254 instead of \atentry[noindex]{abbreviation}. Instead of editing
9255 the \ext{bib} file I can just supply a mapping:
9256 \begin{codeenv}
9257 \gls{GlsXtrLoadResources}\oarg{
9258 \csopt[entries]{src},\comment{data in entries.bib}
9259 \csopt[abbreviation=dualabbreviationentry]{entry-type-aliases}
9260 }
9261 \end{codeenv}
9262 This makes all instances of \atentry[noindex]{abbreviation}
9263 behave as \atentry[noindex]{dualabbreviationentry}. You can have more than
9264 one mapping. For example:
9265 \begin{codeenv}
9266 \gls{GlsXtrLoadResources}\oarg{
9267 \csopt[entries]{src},\comment{data in entries.bib}
9268 \csopt[
9269 \comment{\atentry{abbreviation} -> \atentry{dualabbreviationentry}:}
9270 abbreviation=dualabbreviationentry,
9271 \comment{\atentry{entry} -> \atentry{index}:}
9272 entry=index
9273 ]{entry-type-aliases}
9274 }
9275 \end{codeenv}
9276 This option isn't cumulative. Multiple instances of
9277 \csopt{entry-type-aliases} override previous instances.
9278 If \meta{\keyvallist} is empty there will be no mappings.
9279 You can save the original \gls{entrytype} in the
9280 \field{originalentrytype} field with
9281 \csopt{save-original-entrytype}.
9282
9283 Here's another example entry in a \ext{bib} file:
9284 \begin{codeenv}
9285 @foo\marg{html,
9286 \field{name} = \marg{HTML},
9287 \field{short} = \marg{HTML},
9288 \field{long} = \marg{hypertext markup language},
9289 \field{description} = \marg{hypertext markup language}
9290 }
9291 \end{codeenv}
9292 Ordinarily this entry would be ignored since \code{@foo}
9293 isn't recognised, but it can be mapped like this:
9294 \begin{codeenv}
9295 \gls{GlsXtrLoadResources}\oarg{
9296 \csopt[entries]{src},\comment{data in entries.bib}
9297 \csopt[short,long]{ignore-fields},
9298 \csopt[foo=entry]{entry-type-aliases}
9299 }
9300 \end{codeenv}
9301 This treats the entry as though it had been defined as:
9302 \begin{codeenv}
9303 \atentry{entry}\marg{html,
9304 \field{name} = \marg{HTML},
9305 \field{description} = \marg{hypertext markup language}
9306 }
9307 \end{codeenv}
9308 whereas:
9309 \begin{codeenv}
9310 \gls{GlsXtrLoadResources}\oarg{
9311 \csopt[entries]{src},\comment{data in entries.bib}
9312 \csopt[name,description]{ignore-fields},
9313 \csopt[foo=abbreviation]{entry-type-aliases}
9314 }
9315 \end{codeenv}
9316 treats the entry as though it had been defined as:
9317 \begin{codeenv}
9318 \atentry{abbreviation}\marg{html,
9319 \field{short} = \marg{HTML},
9320 \field{long} = \marg{hypertext markup language}
9321 }
9322 \end{codeenv}
9323
9324 \optsection{unknown-entry-alias}
9325
9326 If this option is set, the \meta{value} is used as the alias for any
9327 unknown \glspl{entrytype} (after any aliases provided with
9328 \csopt{entry-type-aliases} have been applied). If the value is
9329 missing or empty, unknown \glspl{entrytype} will be ignored with a
9330 warning.
9331
9332 \optsection{action}
9333
9334 This governs how the entries are written in the \iext{glstex} file.
9335 The \meta{value} may be one of:
9336 \begin{itemize}
9337 \item\code{define}: define the entries;
9338 \item\code{provide}: provide the entries;
9339 \item\code{copy}: copy the entries;
9340 \item\code{define or copy}: copy existing entries and define
9341 non-existing entries.
9342 \end{itemize}
9343 The default setting is \csopt[define]{action}, which writes the entry
9344 definition to the \ext{glstex} file using one of the commands
9345 described in \sectionref{sec:newentrydefs}. Since the \styopt{record}
9346 package option automatically switches on the \styopt[warn]{undefaction}
9347 option, any attempt at defining an entry that's already been defined
9348 will generate a warning rather than an error. The duplicate
9349 definition will be ignored. (The warnings can be found in the
9350 \ext{log} file since they are warnings produce by
9351 \sty{glossaries-extra} not by \bibgls.)
9352
9353 If you have multiple \iglspl{resourceset} to help group different types of
9354 entry for the same glossary, the \csopt[provide]{action} setting can
9355 be used to suppress any warnings if the selection criteria is too
9356 complex to filter out entries that were selected by a previous
9357 \gls{resourceset}. If, however, you want duplicate entries so that
9358 you can have the same entry listed in multiple glossary, you need a
9359 different approach.
9360
9361 For example, if you try:
9362 \begin{codeenv}
9363 \cs{newglossary*}\marg{copies}\marg{Copies}
9364 \gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}}
9365 \gls{GlsXtrLoadResources}\oarg{\csopt[use]{sort},\csopt[copies]{type},\csopt[entries]{src}}
9366 \end{codeenv}
9367 you'll find that the \code{copies} glossary is empty and there will
9368 be warnings in the \ext{log} file when the second resource file is
9369 loaded.
9370
9371 There are various ways of having the same entries in multiple
9372 glossaries. The simplest method is to use \csopt{secondary}, but
9373 another method is to use \csopt[copy]{action} which simply writes
9374 \nosecformatdef{glsxtrcopytoglossary}
9375 instead of using one of the commands listed in
9376 \sectionref{sec:newentrydefs}. This copies the entries rather than
9377 defining them, which means the entries must already have been
9378 defined. You can select entries that were selected in earlier
9379 \iglspl{resourceset} with \csopt[selected before]{selection}.
9380
9381 The \meta{type} is determined as follows:
9382 \begin{itemize}
9383 \item if the entry has the \field{type} field set, that's used;
9384 \item if the entry is a tertiary and \csopt{tertiary-type} is set, that's
9385 used;
9386 \item if the entry is a dual and \csopt{dual-type} is set, that's
9387 used;
9388 \item otherwise the value of the \csopt{type} option is used.
9389 \end{itemize}
9390 If you're not sure whether the entries may already be defined, you
9391 can use \csopt[define or copy]{action} which will use
9392 \ics{ifglsentryexists} in the resource file to determine whether to
9393 define or copy the entry.
9394
9395 Options that set or modify fields, such as \csopt{category},
9396 \csopt{group}, \csopt{save-locations}, \csopt{flatten} or
9397 \csopt{name-case-change}, will be ignored if entries are copied.
9398 However the \csopt{copy-action-group-field} may be used to copy
9399 the \field{group} field (which may have been locally set by the
9400 \csopt{sort} method) to another field. This ensures that the
9401 original \field{group} value from the entry definition in an earlier
9402 resource set won't be overwritten (unless you set
9403 \csopt[group]{copy-action-group-field}).
9404
9405 Remember that \gls{glsxtrcopytoglossary} simply copies the entry's
9406 label to the glossary's internal list. The only checks that \bibgls\
9407 performs if \csopt{action} is not \code{define} is to ensure that
9408 the \csopt{master} or \csopt{secondary} options have not been used,
9409 since they're incompatible, and that the \csopt{type} option is set,
9410 since it's required as a fallback for any entries that don't have
9411 the \field{type} field set. (There are too many options that alter
9412 field values to check them all and some may be used to alter the
9413 sorting.) The purpose of the copy action is simply to provide a
9414 duplicate list in a different order.
9415
9416 Remember that if you are using \sty{hyperref}, you need to use
9417 \code{\printglossopt[false]{target}} in the optional argument of
9418 \ics{printunsrtglossary} for the glossary containing the copies to
9419 prevent duplicate hypertargets. Commands like \cs{gls} will link to
9420 the original entries. For example, in the preamble:
9421 \begin{codeenv}
9422 \cs{newignoredglossary}\marg{copies}
9423 \strut
9424 \gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}}
9425 \strut
9426 \gls{GlsXtrLoadResources}\oarg{
9427 \csopt[use]{sort},
9428 \csopt[copy]{action},
9429 \csopt[copies]{type},
9430 \csopt[entries]{src}
9431 }
9432 \end{codeenv}
9433 and later in the document:
9434 \begin{codeenv}
9435 \cs{printunsrtglossary}\oarg{\printglossopt[Glossary (Alphabetical)]{title},\printglossopt[\glostyle{indexgroup}]{style}}
9436 \cs{printunsrtglossary}\oarg{\printglossopt[copies]{type},\printglossopt[Glossary (Order of Use)]{title},
9437 \printglossopt[index]{style},\printglossopt{nogroupskip},\comment{no grouping}
9438 \printglossopt[false]{target}}
9439 \end{codeenv}
9440 Note also the need to use \code{nogroupskip} and a non-group style
9441 for the duplicates since the \field{group} field will have been
9442 assigned in the first resource set if \bibgls\ was invoked with
9443 \longarg{group}. The grouping is appropriate for alphabetical
9444 ordering but not for order of use.
9445
9446 If you want different grouping for the duplicates, you can specify
9447 the field name to use in which to store the group information using
9448 \csopt{copy-action-group-field}. Unlike \csopt{secondary}, you
9449 will need to redefine \ics{glsxtrgroupfield} to the relevant field
9450 before you display the glossary. The simplest way to do this is with
9451 the starred form of \cs{printunsrtglossary}.
9452 For example, if \csopt[dupgroup]{copy-action-group-field} is added to
9453 the options for the second resource set:
9454 \begin{codeenv}
9455 \ics{printunsrtglossary*}\oarg{\printglossopt[copies]{type},\printglossopt[Duplicates]{title},\printglossopt[\glostyle{indexgroup}]{style}}
9456 \marg{\cs{renewcommand}\marg{\cs{glsxtrgroupfield}}\marg{dupgroup}}
9457 \end{codeenv}
9458 This just does:
9459 \begin{codeenv}
9460 \cmd{begingroup}
9461 \cs{renewcommand}\marg{\ics{glsxtrgroupfield}}\marg{dupgroup}\comment{}
9462 \cs{printunsrtglossary}\oarg{\printglossopt[copies]{type},\printglossopt[Duplicates]{title},
9463 \printglossopt[indexgroup]{style}}
9464 \cmd{endgroup}
9465 \end{codeenv}
9466
9467 \optsection{copy-to-glossary}
9468
9469 This option can selectively copy an entry to a glossary after it has
9470 been defined. If the supplied value \meta{list} is empty, no copying is
9471 performed (except as a result of other options, such as
9472 \csopt{action} or \csopt{secondary}). If set, the \meta{list}
9473 argument is a list of string \glspl{concatenation} with optional
9474 conditionals. Take care that constant strings are correctly
9475 delimited, as described below, to ensure that they are not mistaken
9476 for field labels.
9477
9478 The evaluation of the target glossary label for each entry is
9479 performed while the \ext{glstex} file is being written (after
9480 sorting) so all field values should be available in any field reference.
9481 The \csopt{action} option is implemented first, so the
9482 selected entry will first either be defined or copied according to
9483 \csopt{action}. If the \csopt{copy-to-glossary} instruction is
9484 successful, the entry will then be copied to the target glossary using
9485 \gls{bibglscopytoglossary}.
9486
9487 The \csopt{copy-to-glossary} value should be a comma-separated list,
9488 where the syntax for each item in the list is in the form:
9489 \begin{codeenv}
9490 \meta{element-list} \oargm{condition}
9491 \end{codeenv}
9492 where \meta{element-list} is a string \gls{concatenation} (see
9493 \sectionref{sec:optstringconcat}) and \meta{condition} is a complex
9494 conditional (see \sectionref{sec:conditionals}). For each
9495 \meta{element-list} \oargm{condition} specification, if the
9496 condition evaluates to false or if the \meta{element-list} evaluates
9497 to null then the copy instruction won't be added.
9498
9499 For example, the following first sets the \field{type} to
9500 \qt{ignored} for any entries that only have \glspl{ignoredrecord}
9501 and then copies all entries that don't have the \field{type} field
9502 set to \qt{ignored} to the glossary labelled \qt{index}:
9503 \begin{codeenv}
9504 \gls{GlsXtrLoadResources}\oarg{
9505 \csopt[ignored]{ignored-type},
9506 \csopt[\qtdelim{index} \oarg{ \field{type} \idx{notequalscmp} \qtdelim{ignored}} ]{copy-to-glossary}
9507 }
9508 \end{codeenv}
9509
9510 The fallback action for a missing field value is governed by the
9511 \csopt{copy-to-glossary-missing-field-action} setting. The result of
9512 the string concatenation (if not null) is the label of the target
9513 glossary.
9514
9515 You can have multiple copy instructions to copy an entry to multiple
9516 glossaries. The definition of \gls{bibglscopytoglossary} will ensure
9517 that an entry will only be copied to the designated glossary if it
9518 isn't already in the glossary's internal list and will silently do
9519 nothing if the glossary doesn't exist.
9520
9521 Remember that constant strings need to be marked with braces or
9522 double-quote delimiters. For example, if you want to copy \emph{all}
9523 entries to the \code{index} glossary then either do:
9524 \begin{codeenv}
9525 \csopt[\qtdelim{index}]{copy-to-glossary}
9526 \end{codeenv}
9527 or
9528 \begin{codeenv}
9529 \csopt[\marg{index}]{copy-to-glossary}
9530 \end{codeenv}
9531 Note that the outer braces are stripped by the resource option
9532 parser, which first splits the \code{\meta{option}\dequals\margm{value}} list supplied via
9533 \gls{GlsXtrLoadResources} into \meta{option} and \meta{value} pairs, and then
9534 parses each \meta{option}. So by the time that the
9535 \csopt{copy-to-glossary} option has its value parsed, the value has
9536 become \code{\qtdelim{index}} or \code{\marg{index}}, respectively,
9537 in the above two examples.
9538
9539 Remember that the \meta{value} itself may be a comma-separated list.
9540 The outer grouping hides the inner list comma from the initial
9541 \code{\meta{option}\dequals\margm{value}} split. For example, to copy all entries
9542 to the \code{index} and \code{symbols} glossaries:
9543 \begin{codeenv}
9544 \csopt[\qtdelim{index}, \qtdelim{symbols}]{copy-to-glossary}
9545 \end{codeenv}
9546 or
9547 \begin{codeenv}
9548 \csopt[\marg{index}, \marg{symbols}]{copy-to-glossary}
9549 \end{codeenv}
9550
9551 The following example will only copy entries to the \code{index}
9552 glossary if their actual entry type is \code{index}:
9553 \begin{codeenv}
9554 \csopt[\qtdelim{index} \oarg{ entrytype \idx{follow} actual \idx{equalscmp} \qtdelim{index} }]{copy-to-glossary}
9555 \end{codeenv}
9556 Alternatively, to copy aliased custom entry types
9557 \atentryfmt{person} entries to a custom glossary \code{person} and
9558 \atentryfmt{place} to a custom glossary \code{place}:
9559 \begin{codeenv}
9560 \csopt[
9561 entrytype \idx{follow} original
9562 \oarg{ entrytype \idx{follow} original =\idx{slashchar}person\idx{regexpor}place\idx{slashchar} }
9563 ]{copy-to-glossary}
9564 \end{codeenv}
9565
9566 If the glossary types don't conveniently match the entry type,
9567 the instructions can be split into a list.
9568 For example:
9569 \begin{codeenv}
9570 \csopt[
9571 \qtdelim{abbreviations} \oarg{ entrytype \idx{follow} actual = \qtdelim{abbreviation} },
9572 \qtdelim{symbols} \oarg{ entrytype \idx{follow} actual = \qtdelim{symbol} },
9573 \qtdelim{numbers} \oarg{ entrytype \idx{follow} actual = \qtdelim{number} },
9574 ]{copy-to-glossary}
9575 \end{codeenv}
9576 Each instruction in the list will be tried and the copy instruction
9577 will only be written if the condition evaluates to true and a
9578 non-null value is successfully returned.
9579
9580 \optsection{copy-to-glossary-missing-field-action}
9581
9582 This option indicates what to do if a source field identified in
9583 \csopt{copy-to-glossary} is missing. The value may be one of:
9584 \begin{itemize}
9585 \item \optfmt{skip}: return null;
9586 \item \optfmt{fallback}: use the fallback for the missing field
9587 (see \sectionref{sec:fallbacks}), if
9588 one is available, otherwise return null (default);
9589 \item \optfmt{empty}: treat the missing value as empty.
9590 \end{itemize}
9591 Returning null will result in the copy instruction being omitted.
9592
9593 \section{Selection Options}
9594 \label{sec:selectionopts}
9595
9596 \optsection{src}
9597
9598 This identifies the \iext{bib} files containing the entry
9599 definitions. The value should be a comma-separated list of the
9600 required \ext{bib} files. These may either be in the current working
9601 directory or in the directory given by the \longarg{dir} switch or on
9602 \TeX's path (in which case \idx{kpsewhich} will be used to find
9603 them). The \ext{bib} extension may be omitted. Remember that if
9604 \meta{list} contains multiple files it must be grouped to protect
9605 the comma from the \meta{options} list.
9606
9607 For example:
9608 \begin{codeenv}
9609 \gls{GlsXtrLoadResources}\oarg{\csopt[entries-terms,entries-symbols]{src}}
9610 \end{codeenv}
9611 indicates that \bibgls\ must read the files
9612 \filefmt{entries-terms.bib} and \filefmt{entries-symbols.bib}.
9613
9614 If \csopt{src} is omitted or if the value is empty, it's assumed to
9615 be the same as the basename of the \ext{glstex} file. This is
9616 \ics{jobname} for the first instance of \gls{GlsXtrLoadResources}.
9617 Remember that subsequent uses of \gls{GlsXtrLoadResources} append a
9618 suffix \code{\cs{jobname}-\meta{n}}, so in general it's best to
9619 always supply \csopt{src} (or use \gls{glsbibdata}), except for
9620 small test cases with a single \gls{resourcecommand}.
9621
9622 With old \LaTeX\ kernels, if you have non-ASCII characters in the
9623 \ext{bib} filename but aren't using \XeLaTeX\ or \LuaLaTeX, then you
9624 will need to use \ics{detokenize} to prevent expansion when the
9625 information is written to the \ext{aux} file. Newer \LaTeX\ kernels
9626 have better support for UTF-8. Similarly for any special characters
9627 that need protecting (although it's better not to use special
9628 characters in filenames). For example:
9629 \begin{codeenv}
9630 \cmd{documentclass}\marg{article}
9631 \strut
9632 \cmd{usepackage}\oarg{T2A}\marg{fontenc}
9633 \cmd{usepackage}\oarg{utf8}\marg{inputenc}
9634 \cmd{usepackage}\oarg{russian}\marg{babel}
9635 \cmd{usepackage}\oarg{record}\marg{glossaries-extra}
9636 \strut
9637 \gls{GlsXtrLoadResources}\oarg{
9638 \csopt[\cs{detokenize}\marg{\textcyrillicmono{кириллица}}]{src},\comment{data in \textcyrillicmono{кириллица.bib}}
9639 \csopt[all]{selection}
9640 }
9641 \strut
9642 \cmd{begin}\marg{document}
9643 \cs{printunsrtglossary}
9644 \cmd{end}\marg{document}
9645 \end{codeenv}
9646
9647 \optsection{selection}
9648
9649 By default all entries that have records in the \iext{aux} file will
9650 be selected as well as all their dependent entries. The dependent
9651 entries that don't have corresponding records on the first \LaTeX\
9652 run, may need an additional build to ensure their \glspl{locationlist}
9653 are updated.
9654
9655 Remember that on the first \LaTeX\ run the \iext{glstex} files don't
9656 exist. This means that the entries aren't defined at that point. The
9657 \styopt{record} package option additionally switches on the
9658 \styopt[warn]{undefaction} option, which means that you'll only get
9659 warnings rather than errors when you reference entries in the
9660 document. You can't use \ics{glsaddall} with
9661 \bibgls\ because the glossary lists are empty on the first run, so
9662 there's nothing for \ics{glsaddall} to iterate over.
9663 Instead, if you want to add all defined entries, you need to
9664 instruct \bibgls\ to do this with the \csopt{selection} option. The
9665 following values are allowed:
9666 \begin{itemize}
9667 \item \optfmt{recorded and deps}: add all recorded entries and
9668 their dependencies (default).
9669
9670 \item \optfmt{recorded and deps and see}: as above but will also
9671 add unrecorded entries whose \field{see}, \field{seealso} or
9672 \field{alias} field refers to a recorded entry.
9673
9674 \item \optfmt{recorded and deps and see not also}: as above but will
9675 add unrecorded entries whose \field{see} or \field{alias} (but not
9676 \field{seealso}) field refers to a recorded entry.
9677
9678 \item \optfmt{recorded no deps}: add all recorded entries but not
9679 their dependencies. The dependencies include those referenced in the
9680 \field{see} or \field{seealso} field or fields identified by
9681 \csopt{dependency-fields}, \field{parent} entries and those found
9682 referenced with commands like \ics{gls} in the field values that are
9683 parsed by \bibgls. With this setting, \glsdisp{parententry}{parents}
9684 will be omitted unless they've been referenced in the document
9685 through commands like \ics{gls}. This setting won't add any
9686 \field{see} or \field{seealso} lists to the \igls{locationlist}. The
9687 given field will be set, so you can access the information, but
9688 there's no guarantee that the cross-referenced entry will have been
9689 selected. The \field{alias} cross-reference will be added to the
9690 \igls{locationlist} but you will need to ensure that the target is
9691 also selected (or use \csopt[omit]{alias} to suppress it).
9692
9693 \item \optfmt{recorded and ancestors}: this is like the previous
9694 setting but \glsdisp{parententry}{parents} are added even if they
9695 haven't been referenced in the document. The other dependent entries
9696 are omitted if they haven't been referenced in the document. The
9697 above notes regarding the cross-reference lists also applies.
9698
9699 \item \optfmt{deps but not recorded}: this first selects entries as
9700 though \optfmt{recorded and deps} had been used, but after all
9701 \glspl{ancestor} and dependencies have been added it then removes all
9702 entries that have records. This means that you end up with only the
9703 unrecorded dependencies. (Recorded entries will need to be selected
9704 in a different resource set.)
9705
9706 \item \optfmt{ancestors but not recorded}: this first selects
9707 entries as though \optfmt{recorded and ancestors} had been used, but
9708 after all \glspl{ancestor} have been added it then removes all entries that
9709 have records. This means that you end up with only the unrecorded
9710 \glspl{ancestor}. (Recorded entries will need to be selected
9711 in a different resource set.) See the \exfile{sample-nested.tex}
9712 example document.
9713
9714 \item \optfmt{selected before}: select any entries that have been
9715 selected in a previous \igls{resourceset}. This is intended
9716 for use with \csopt[copy]{action} to copy entries to another
9717 glossary as an alternative to (or in addition to) the
9718 \csopt{secondary} option. Note that if you make any modifications to
9719 the fields (such as case-changing) the modification won't be saved
9720 to the \ext{glstex} file. This option can't be used in the first
9721 \igls{resourceset}.
9722
9723 \item \optfmt{all}: add all entries found in the \ext{bib} files
9724 supplied in the \csopt{src} option.
9725 \end{itemize}
9726 The \meta{value} must be supplied.
9727
9728 For example, suppose the file \filefmt{entries.bib} contains:
9729 \begin{codeenv}
9730 \atentry{index}\marg{run}
9731 \atentry{index}\marg{sprint,\field{see}=\marg{run}}
9732 \atentry{index}\marg{dash,\field{see}=\marg{sprint}}
9733 \end{codeenv}
9734 If the document only references the \qt{run} entry (for example,
9735 using \code{\cs{gls}\marg{run}}) then:
9736 \begin{itemize}
9737 \item If \csopt[recorded and deps]{selection}, only the \qt{run}
9738 entry is selected. The \qt{run} entry has a record, so it's
9739 selected, but it has no dependencies. Neither \qt{sprint} nor
9740 \qt{dash} have records, so they're not selected.
9741 \item If \csopt[recorded and deps and see]{selection}, the \qt{run}
9742 and \qt{sprint} entries are selected, but not the \qt{dash} entry.
9743 The \qt{run} entry is selected because it has a record. The
9744 \qt{sprint} entry doesn't have a record but its \field{see} field
9745 includes \qt{run}, which does have a record, so \qt{sprint} is also
9746 selected. The \qt{dash} entry doesn't have a record. Its
9747 \field{see} field references \qt{sprint}. Although \qt{sprint} has
9748 been selected, it doesn't have any records, so \qt{dash} isn't
9749 selected.
9750 \end{itemize}
9751 The above is just an example. The circuitous redirection of
9752 \qt{dash} to \qt{sprint} to \qt{run} is unhelpful to the reader and
9753 is best avoided (especially for an index where there are no accompanying
9754 descriptions and no \igls{locationlist} for the intermediate \qt{sprint}).
9755 A better method would be:
9756 \begin{codeenv}
9757 \atentry{index}\marg{run}
9758 \atentry{index}\marg{sprint,\field{see}=\marg{run}}
9759 \atentry{index}\marg{dash,\field{see}=\marg{run}}
9760 \end{codeenv}
9761 The \csopt[recorded and deps and see]{selection} in this case will
9762 select all three entries, and the document won't send the reader on a
9763 long-winded detour.
9764
9765 Now suppose that the file \filefmt{entries.bib} contains:
9766 \begin{codeenv}
9767 \atentry{entry}\marg{run,
9768 \field{name} = \marg{run},
9769 \field{description}=\marg{move fast using legs}
9770 }
9771 \strut
9772 \atentry{entry}\marg{sprint,
9773 \field{name} = \marg{sprint},
9774 \field{description}=\marg{run at full speed over short distance},
9775 \field{seealso}=\marg{run}
9776 }
9777 \strut
9778 \atentry{entry}\marg{dash,
9779 \field{name} = \marg{dash},
9780 \field{description}=\marg{run in a great hurry},
9781 \field{seealso}=\marg{sprint}
9782 }
9783 \end{codeenv}
9784 and suppose the document only references \qt{dash} (for example, with
9785 \code{\cs{gls}\marg{dash}}), then with the default \csopt[recorded and deps]{selection}
9786 \qt{dash} will be selected because it has a record, and \qt{sprint}
9787 will be selected because \qt{dash} requires it (for the cross-reference),
9788 and \qt{run} will be selected because \qt{sprint} requires it
9789 (for the cross-reference). In this case, neither \qt{sprint} nor \qt{run}
9790 have a \igls{locationlist} but they do both provide additional information
9791 for the reader in their descriptions.
9792
9793 A better method here would be for each entry to have a cross-reference
9794 list that includes all related terms:
9795 \begin{codeenv}
9796 \atentry{entry}\marg{run,
9797 \field{name} = \marg{run},
9798 \field{description}=\marg{move fast using legs},
9799 \field{seealso}=\marg{sprint,dash}
9800 }
9801 \strut
9802 \atentry{entry}\marg{sprint,
9803 \field{name} = \marg{sprint},
9804 \field{description}=\marg{run at full speed over short distance},
9805 \field{seealso}=\marg{run,dash}
9806 }
9807 \strut
9808 \atentry{entry}\marg{dash,
9809 \field{name} = \marg{dash},
9810 \field{description}=\marg{run in a great hurry},
9811 \field{seealso}=\marg{sprint,run}
9812 }
9813 \end{codeenv}
9814 Now, whichever one is indexed in the document, the other two will automatically
9815 be selected.
9816
9817 \optsection{match}
9818
9819 It's possible to filter the selection by matching field values.
9820 The value is required for this key but may be empty, which indicates
9821 that the setting is switched off, otherwise
9822 \meta{\keyvallist} should be a \meta{key}=\meta{regexp} list, where
9823 \meta{key} is the name of a field or \optfmt{id} for the entry's
9824 label or \optfmt{entrytype} for the \bibgls\ \gls{entrytype} (as in
9825 the part after \verb|@| identifying the entry not the \field{type}
9826 field identifying the glossary label). If you've used
9827 \csopt{entry-type-aliases}, this refers to the target \gls{entrytype} not
9828 the original \gls{entrytype} specified in the \ext{bib} file.
9829
9830 \begin{important}
9831 Filtering options don't apply directly to \atentry{compoundset}
9832 entries (or any of the other special entry types described in
9833 \sectionref{sec:specialentrytypes}), so you can't
9834 match the entry type to \atentry{compoundset}.
9835 However, if any elements within a \gls{compoundentry} are filtered
9836 then the \gls{compoundentry} won't be written to the \ext{glstex}
9837 file. Use the \csopt{compound-write-def} option to determine whether
9838 or not to write the \gls{compoundentry} to the resource file.
9839 \end{important}
9840
9841 The \meta{regexp} part should be a \gls{regular-expression} conforming
9842 to
9843 \href{http://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html}{Java's
9844 Pattern class}~\cite{pattern}. The pattern is \gls{anchored}
9845 (\code{oo}\idx{matchanydot}\idx{zeroormore} matches
9846 \code{oops} but not \code{loops}) and \meta{regexp} can't be
9847 empty. Remember that \TeX\ will expand the option list as
9848 it writes the information to the \ext{aux} file so take
9849 care with special characters. For example, to match a literal
9850 period use \cs{cs.string}\idx{cs.period} not \idx{cs.period} (backslash dot).
9851
9852 If the field is missing its value it is assumed to be empty for
9853 the purposes of the pattern match even if it will be assigned a
9854 non-empty default value when the entry is defined. If the field is
9855 unrecognised by \bibgls\ any reference to it in \meta{\keyvallist} will
9856 be ignored.
9857
9858 If a field is listed multiple times, the pattern for that
9859 field is concatenated using:
9860 \begin{alltt}
9861 (?:\meta{pattern-1})|(?:\meta{pattern-2})
9862 \end{alltt}
9863 where \meta{pattern-1} is the current pattern for that field
9864 and \meta{pattern-2} is the new pattern. This means it performs a
9865 logical OR\@. For the non-duplicate
9866 fields the logical operator is given by \csopt{match-op}.
9867 For example:
9868 \begin{codeenv}
9869 \csopt[and]{match-op},
9870 \csopt[
9871 \field{category}=animals,
9872 \fieldfmt{topic}=biology,
9873 \field{category}=vegetables
9874 ]{match}
9875 \end{codeenv}
9876 This will keep all the selected entries that satisfy:
9877 \begin{itemize}
9878 \item \field{category} matches \verb"(?:animals)|(?:vegetables)"
9879
9880 (the \field{category} is either \optfmt{animals} or
9881 \optfmt{vegetables})
9882
9883 \item[AND]
9884
9885 \item \fieldfmt{topic} (custom key provided by user) is \code{biology}.
9886 \end{itemize}
9887 and will discard any entries that don't satisfy this condition.
9888 A message will be written to the log file for each entry
9889 that's discarded.
9890
9891 Patterns for unknown fields will be ignored. If the entire
9892 list consists of patterns for unknown fields it will be
9893 treated as \csopt[\empty]{match}. That is, no filtering will be
9894 applied. In the above example, the custom \fieldfmt{topic} key must
9895 be provided before the first \gls{GlsXtrLoadResources} with
9896 \ics{glsaddkey} or \ics{glsaddstoragekey}.
9897
9898 \optsection{match-op}
9899
9900 If the value of \csopt{match} contains more than one
9901 \meta{key}=\meta{pattern} element, the \csopt{match-op}
9902 determines whether to apply a logical AND or a logical OR.
9903 The \meta{value} may be either \optfmt{and} or \optfmt{or}.
9904 The default is \csopt[and]{match-op}.
9905
9906 \optsection{not-match}
9907
9908 If \csopt[\meta{\keyvallist}]{match} would cause an entry to be
9909 selected then \csopt[\meta{\keyvallist}]{not-match} would cause that
9910 entry to be ignored. The value is required for this key but may be
9911 empty, which indicates that the setting is switched off. If you
9912 have both \csopt{match} and \csopt{not-match} in the same resource
9913 set, the last one listed takes precedence.
9914
9915 \begin{important}
9916 Filtering options don't apply directly to \atentry{compoundset}
9917 entries (or any of the other special entry types described in
9918 \sectionref{sec:specialentrytypes}), so you can't match the entry type to \atentry{compoundset}.
9919 However, if any elements within a \gls{compoundentry} are filtered
9920 then the \gls{compoundentry} won't be written to the \ext{glstex}
9921 file. Use the \csopt{compound-write-def} option to determine whether
9922 or not to write the \gls{compoundentry} to the resource file.
9923 \end{important}
9924
9925 \optsection{match-action}
9926
9927 The default behaviour with \csopt{match} or \csopt{not-match}
9928 is to filter the selection. This may be changed to append to the
9929 selection instead. The \meta{value} may be one of:
9930 \begin{itemize}
9931 \item\optfmt{filter}: (default) filter selection;
9932 \item\optfmt{add}: append any matches (with \csopt{match}) or
9933 non-matches (with \csopt{not-match}) to the selection.
9934 This setting can't be used with \csopt[use]{sort}.
9935 \end{itemize}
9936 For example, if I want to select all record entries and their
9937 dependencies, but I also want to make sure that any entries with
9938 the category set to \code{important} are always selected regardless
9939 of whether or not they have any records:
9940 \begin{codeenv}
9941 \gls{GlsXtrLoadResources}\oarg{
9942 \csopt[entries]{src},\comment{data in entries.bib}
9943 \csopt[add]{match-action},
9944 \csopt[\field{category}=important]{match}
9945 }
9946 \end{codeenv}
9947
9948 \optsection{limit}
9949
9950 If \meta{number} is greater than 0 then this will truncate the
9951 list of selected entries after sorting to \meta{number} (if the list
9952 size is greater than that value). The transcript will show the
9953 message:
9954 \begin{alltt}
9955 Truncating according to limit=\meta{number}
9956 \end{alltt}
9957 When used with \csopt{shuffle}, this provides a means of randomly
9958 selecting at most \meta{number} entries. The default setting is
9959 \csopt[0]{limit} (no truncation). A negative value of \meta{number} is not
9960 permitted.
9961
9962 If you have any \glspl{dualentry}, then the truncation will be
9963 applied to the combined list of \primary\ and
9964 \glsdisp{dualentry}{duals} if \csopt[combine]{dual-sort} otherwise
9965 each list will be truncated separately by \meta{number}, which
9966 results in a maximum of $2 \times \meta{number}$. Remember that
9967 \glspl{tertiaryentry} are created when \glspl{dualentry} are defined
9968 in the \ext{glstex} file, so this will increase the total number of
9969 entries.
9970
9971 \section{Hierarchical Options}
9972 \label{sec:hierarchicalopts}
9973
9974 Hierarchy is established by setting the \field{parent} field to the
9975 label of the parent entry. The parent and child entries are
9976 sorted together, but hierarchical comparators will place child
9977 entries after their corresponding parent.
9978
9979 The \sty{glossaries} package provides \ics{ifglshasparent} to
9980 determine whether or not an entry has the \field{parent} field set.
9981 If also provides \ics{ifglshaschildren}, but this command is
9982 inefficient as it has to iterate over all entries to find an entry
9983 with the \field{parent} field set to the relevant label. It's also
9984 non-trivial to determine which child entries have been included in
9985 the glossary with \idx!{makeindex} or \idx!{xindy}. \bibgls\ can
9986 provide this information with some of the options described in this
9987 section.
9988
9989 It's also possible to \glsdisp{flatglossary}{flatten entries} (that is, remove the
9990 hierarchical information) or just flatten \glspl{lonelychildentry}.
9991
9992 \optsection{save-child-count}
9993
9994 This is a boolean option. The default setting is
9995 \csopt[false]{save-child-count}.
9996 If \csopt[true]{save-child-count}, each entry will be assigned a
9997 field called \field{childcount} with the value equal to the number
9998 of \glspl{childentry} that have been selected. As from version 1.5,
9999 this option also creates the \field{childlist} field for entries
10000 that have \glsdisp{childentry}{children} selected. This field is in
10001 \sty{etoolbox}'s internal list format and can be iterated over using
10002 \glsadd{idx.loop}\ics{glsxtrfieldforlistloop}.
10003
10004 The assignment is done using \ics{GlsXtrSetField} so there's
10005 no associated key. You can test if the field is set and non-zero
10006 using:
10007 \nosecformatdef{GlsXtrIfHasNonZeroChildCount}
10008 which is provided with \sty{glossaries-extra-bib2gls} v1.31+.
10009 Within \meta{true}, you can access the actual value with
10010 \ics{glscurrentfieldvalue}. If \csopt[false]{save-child-count},
10011 this command will do \meta{false} as the \field{childcount} field
10012 won't be set.
10013
10014 For example, suppose \filefmt{entries.bib} contains:
10015 \begin{codeenv}
10016 \atentry{index}\marg{birds}
10017 \atentry{index}\marg{duck,\field{parent}=\marg{birds}}
10018 \atentry{index}\marg{goose,\field{plural}=\marg{geese},\field{parent}=\marg{birds}}
10019 \atentry{index}\marg{swan,\field{parent}=\marg{birds}}
10020 \strut
10021 \atentry{index}\marg{minerals}
10022 \atentry{index}\marg{quartz,\field{parent}=\marg{minerals}}
10023 \atentry{index}\marg{corundum,\field{parent}=\marg{minerals}}
10024 \atentry{index}\marg{amethyst,\field{parent}=\marg{minerals}}
10025 \atentry{index}\marg{gypsum,\field{parent}=\marg{minerals}}
10026 \atentry{index}\marg{gold,\field{parent}=\marg{minerals}}
10027 \end{codeenv}
10028 and the document contains:
10029 \begin{codeenv}
10030 \cmd{documentclass}\marg{article}
10031 \strut
10032 \cmd{usepackage}[\styopt{record},\styopt[indexgroup]{style}]\marg{glossaries-extra}
10033 \strut
10034 \gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt{save-child-count}}
10035 \strut
10036 \cmd{begin}\marg{document}
10037 \cs{gls}\marg{duck} and \cs{gls}\marg{goose}.
10038 \cs{gls}\marg{quartz}, \cs{gls}\marg{corundum}, \cs{gls}\marg{amethyst}.
10039 \strut
10040 \cs{printunsrtglossaries}
10041 \cmd{end}\marg{document}
10042 \end{codeenv}
10043 Then the \ext{glstex} file will contain:
10044 \begin{codeenv}
10045 \cs{GlsXtrSetField}\marg{birds}\marg{childcount}\marg{2}
10046 \cs{GlsXtrSetField}\marg{duck}\marg{childcount}\marg{0}
10047 \gls{glsxtrfieldlistadd}\marg{birds}\marg{childlist}\marg{duck}
10048 \cs{GlsXtrSetField}\marg{goose}\marg{childcount}\marg{0}
10049 \gls{glsxtrfieldlistadd}\marg{birds}\marg{childlist}\marg{goose}
10050 \cs{GlsXtrSetField}\marg{minerals}\marg{childcount}\marg{3}
10051 \cs{GlsXtrSetField}\marg{amethyst}\marg{childcount}\marg{0}
10052 \gls{glsxtrfieldlistadd}\marg{minerals}\marg{childlist}\marg{amethyst}
10053 \cs{GlsXtrSetField}\marg{corundum}\marg{childcount}\marg{0}
10054 \gls{glsxtrfieldlistadd}\marg{minerals}\marg{childlist}\marg{corundum}
10055 \cs{GlsXtrSetField}\marg{quartz}\marg{childcount}\marg{0}
10056 \gls{glsxtrfieldlistadd}\marg{minerals}\marg{childlist}\marg{quartz}
10057 \end{codeenv}
10058 Note that although \code{birds} has three \children\ defined in the
10059 \ext{bib} file, only two have been selected, so the \child\ count is
10060 set to~2. Similarly the \code{minerals} entry has five \children\
10061 defined in the \ext{bib} file, but only three have been selected, so
10062 the \child\ count is~3.
10063
10064 The following uses the post-description hook to show the \child\ count
10065 in parentheses:
10066 \begin{codeenv}
10067 \gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[general]{category},\csopt{save-child-count}}
10068 \strut
10069 \cs{glsdefpostdesc}\marg{general}\marg{\comment{}
10070 \cs{glsxtrifhasfield}\marg{childcount}\marg{\cs{glscurrententrylabel}}\comment{}
10071 \marg{ (child count: \cs{glscurrentfieldvalue}.)}\comment{}
10072 \marg{}\comment{}
10073 }
10074 \end{codeenv}
10075 \ics{glsxtrifhasfield} requires at least \sty{glossaries-extra} v1.19.
10076 It's slightly more efficient than \ics{ifglshasfield} provided by
10077 the base \styfmt{glossaries} package, and it doesn't complain if the
10078 entry or field don't exist, but note that \ics{glsxtrifhasfield}
10079 implicitly scopes its content. Use the starred version to omit the
10080 grouping. With \sty{glossaries-extra} v1.31+ you can perform a
10081 numerical test with \ics{GlsXtrIfFieldNonZero} or
10082 \ics{GlsXtrIfFieldEqNum}.
10083
10084 \optsection{save-sibling-count}
10085
10086 This is a boolean option. The default setting is
10087 \csopt[false]{save-sibling-count}. This is like
10088 \csopt{save-child-count} but saves the \gls{sibling} count in
10089 \field{siblingcount} and the \gls{sibling} list in
10090 \field{siblinglist}. As with the \child list, the \gls{sibling}
10091 list is in \sty{etoolbox}['s] internal list format. The
10092 \gls{sibling} information is only saved for entries that have a
10093 \parent.
10094
10095 The advantage with \field{siblinglist} over accessing the
10096 \glsdisp{parententry}{parent's} \field{childlist} is that the entry
10097 itself is excluded from the list.
10098
10099 \optsection{save-root-ancestor}
10100
10101 This is a boolean option. The default setting is
10102 \csopt[false]{save-root-ancestor}. If true, the entry's top-most
10103 \gls{ancestor} will be saved in the entry's \field{rootancestor} internal
10104 field. If the entry doesn't have a \parent\ (that it, the entry itself
10105 is the root) then the \field{rootancestor} field won't be set.
10106
10107 \optsection{flatten}
10108
10109 This is a boolean option. The default value is \csopt[false]{flatten}.
10110 If \csopt[true]{flatten}, the sorting will ignore \hierarchy\ and
10111 the \field{parent} field will be omitted when writing
10112 the definitions to the \ext{glstex} file, but the \glspl{parententry}
10113 will still be considered a dependent \gls{ancestor} from the
10114 \csopt{selection} point of view.
10115
10116 Note the difference between this option and using
10117 \csopt[parent]{ignore-fields} which will remove the dependency
10118 (unless a dependency is established through another field).
10119
10120 \optsection{flatten-lonely}
10121
10122 This may take one of three values: \optfmt{false} (default),
10123 \optfmt{presort} and \optfmt{postsort}. The value must be supplied.
10124
10125 Unlike the \csopt{flatten} option, which completely
10126 removes the \hierarchy, the \csopt{flatten-lonely} option can be used
10127 to selectively alter the \hierarchy. In this case only those entries
10128 that have a \parent\ but have no \glspl{sibling} are considered. This option
10129 is affected by the \csopt{flatten-lonely-rule} setting. The conditions for
10130 moving a \child\ up one \hierarchicallevel\ are as follows:
10131 \begin{itemize}
10132 \item The \child\ must have a \parent, and
10133 \item the \child\ can't have any selected \glspl{sibling}, and
10134 \item if \csopt[only unrecorded parents]{flatten-lonely-rule}
10135 then the \parent\ can't have a \gls{locationlist}, where the
10136 \gls{locationlist} includes \glspl{record} and \field{see} or \field{seealso}
10137 cross-references (for the other rules the \parent\
10138 may have a \gls{locationlist} as long as it only has the one \child\ selected).
10139 \end{itemize}
10140 If the \child\ is selected for \hierarchical\ adjustment,
10141 the \parent\ will be removed if:
10142 \begin{itemize}
10143 \item The \parent\ has no \gls{locationlist}, and
10144 \item \csopt{flatten-lonely-rule} isn't set to \optfmt{no discard}.
10145 \end{itemize}
10146
10147 The value of \csopt{flatten-lonely} determines whether the
10148 adjustment should be made before sorting (\optfmt{presort})
10149 or after sorting (\optfmt{postsort}). To disable this function
10150 use \csopt[false]{flatten-lonely}.
10151
10152 For example, suppose the file \filefmt{entries.bib} contains:
10153 \begin{codeenv}
10154 \atentry{index}\marg{birds}
10155 \atentry{index}\marg{duck,\field{parent}=\marg{birds}}
10156 \atentry{index}\marg{goose,\field{plural}=\marg{geese},\field{parent}=\marg{birds}}
10157 \atentry{index}\marg{swan,\field{parent}=\marg{birds}}
10158 \atentry{index}\marg{chicken,\field{parent}=\marg{birds}}
10159 \strut
10160 \atentry{index}\marg{vegetable}
10161 \atentry{index}\marg{cabbage,\field{parent}=\marg{vegetable}}
10162 \strut
10163 \atentry{index}\marg{minerals}
10164 \atentry{index}\marg{quartz,\field{parent}=\marg{minerals}}
10165 \atentry{index}\marg{corundum,\field{parent}=\marg{minerals}}
10166 \atentry{index}\marg{amethyst,\field{parent}=\marg{minerals}}
10167 \atentry{index}\marg{gypsum,\field{parent}=\marg{minerals}}
10168 \strut
10169 \atentry{index}\marg{aardvark}
10170 \atentry{index}\marg{bard}
10171 \atentry{index}\marg{buzz}
10172 \strut
10173 \atentry{index}\marg{item}
10174 \atentry{index}\marg{subitem,\field{parent}=\marg{item}}
10175 \atentry{index}\marg{subsubitem,\field{parent}=\marg{subitem}}
10176 \end{codeenv}
10177 and suppose the document contains:
10178 \begin{codeenv}
10179 \cmd{documentclass}\marg{article}
10180 \strut
10181 \cmd{usepackage}[\styopt{record},\styopt[indexgroup]{style}]\marg{glossaries-extra}
10182 \strut
10183 \gls{GlsXtrLoadResources}\oarg{\csopt[entries.bib]{src}}
10184 \strut
10185 \cmd{begin}\marg{document}
10186 \cs{gls}\marg{duck}.
10187 \cs{gls}\marg{quartz}, \cs{gls}\marg{corundum}, \cs{gls}\marg{amethyst}.
10188 \cs{gls}\marg{aardvark}, \cs{gls}\marg{bard}, \cs{gls}\marg{buzz}.
10189 \cs{gls}\marg{vegetable}, \cs{gls}\marg{cabbage}.
10190 \cs{gls}\marg{subsubitem}.
10191 \strut
10192 \cs{printunsrtglossaries}
10193 \cmd{end}\marg{document}
10194 \end{codeenv}
10195 Although the \code{duck} entry has \glspl{sibling} in the
10196 \filefmt{entries.bib} file, none of them have been
10197 \glsdisp{recordedentry}{recorded} in the document, nor has the
10198 \parent\ \code{birds} entry.
10199
10200 This document hasn't used \csopt{flatten-lonely}, so the default
10201 \csopt[false]{flatten-lonely} is assumed. This results in the
10202 \hierarchical\ structure:
10203 \begin{description}\setlength\itemsep{0pt}%
10204 \item[A] \null
10205 \item[aardvark] 1
10206 \item[B] \null
10207 \item[bard] 1
10208 \item[birds] \mbox{}
10209 \begin{description}\setlength\itemsep{0pt}%
10210 \item[duck] 1
10211 \end{description}
10212 \item[buzz] 1
10213 \item[I] \null
10214 \item[item] \mbox{}
10215 \begin{description}\setlength\itemsep{0pt}%
10216 \item[subitem] \mbox{}
10217 \begin{description}\setlength\itemsep{0pt}%
10218 \item[subsubitem] 1
10219 \end{description}
10220 \end{description}
10221 \item[M] \null
10222 \item[minerals] \mbox{}
10223 \begin{description}\setlength\itemsep{0pt}%
10224 \item[amethyst] 1
10225 \item[corundum] 1
10226 \item[quartz] 1
10227 \end{description}
10228 \item[V] \null
10229 \item[vegetable] 1
10230 \begin{description}\setlength\itemsep{0pt}%
10231 \item[cabbage] 1
10232 \end{description}
10233 \end{description}
10234 (The \qt{1} in the above indicates the page number.)
10235 There are some entries here that look a little odd: \code{duck},
10236 \code{cabbage} and \code{subsubitem}. In each case they are a
10237 \glsdisp{lonelychildentry}{lone child entry}. It would look better
10238 if they could be compressed, but I don't want to use the
10239 \csopt{flatten} option, as I still want to keep the mineral
10240 \hierarchy.
10241
10242 If I now add \csopt[postsort]{flatten-lonely}:
10243 \begin{codeenv}
10244 \gls{GlsXtrLoadResources}\oarg{\csopt[entries.bib]{src},\csopt[postsort]{flatten-lonely}}
10245 \end{codeenv}
10246 the \hierarchy\ becomes:
10247 \begin{description}\setlength\itemsep{0pt}%
10248 \item[A] \null
10249 \item[aardvark] 1
10250 \item[B] \null
10251 \item[bard] 1
10252 \item[birds, duck] 1
10253 \item[buzz] 1
10254 \item[I] \null
10255 \item[item, subitem, subsubitem] 1
10256 \item[M] \null
10257 \item[minerals] \mbox{}
10258 \begin{description}\setlength\itemsep{0pt}%
10259 \item[amethyst] 1
10260 \item[corundum] 1
10261 \item[quartz] 1
10262 \end{description}
10263 \item[V] \null
10264 \item[vegetable] 1
10265 \begin{description}\setlength\itemsep{0pt}%
10266 \item[cabbage] 1
10267 \end{description}
10268 \end{description}
10269 The \field{name} field of the \code{duck} entry has been
10270 set to:
10271 \begin{codeenv}
10272 \field{name}=\marg{\gls{bibglsflattenedchildpostsort}\marg{birds}\marg{duck}}
10273 \end{codeenv}
10274 the \field{text} field has been set to:
10275 \begin{codeenv}
10276 \field{text}=\marg{duck}
10277 \end{codeenv}
10278 the \field{group} field is copied over from the \gls{parententry} (\qt{B}),
10279 and the \field{parent} field has been adjusted, moving \code{duck}
10280 up one \hierarchicallevel.
10281 Finally, the former \parent\ \code{birds} entry has been removed (the default
10282 \csopt[only unrecorded parents]{flatten-lonely-rule} is in effect).
10283
10284 The default definition of \gls!{bibglsflattenedchildpostsort}
10285 formats its arguments so that they are separated by a comma and
10286 space (\qt{birds, duck}). If the \field{text} field had been set
10287 in the original \atentry{index} definition of \text{duck}, it
10288 wouldn't have been altered. This adjustment ensures that in the
10289 document \code{\cs{gls}\marg{duck}} still produces \qt{duck} rather than
10290 \qt{birds, duck}.
10291 (If the \child\ and \parent\ \field{name} fields are identical,
10292 the terms are considered \glspl{homograph}. See below for further details.)
10293
10294 The \code{subsubitem} entry has also been adjusted. This was done
10295 in a multi-stage process, starting with sub-items and then moving down
10296 the \hierarchical\ levels:
10297 \begin{itemize}
10298 \item The \code{subitem} entry was adjusted, moving it from a
10299 \gls{sub-entry} to a \gls{top-levelentry}. The \field{name} field was then
10300 modified to:
10301 \begin{codeenv}
10302 \field{name}=\marg{\gls{bibglsflattenedchildpostsort}\marg{item}\marg{subitem}}
10303 \end{codeenv}
10304 This now means that the \code{subsubitem} entry is now a \gls{sub-entry}
10305 (rather than a sub-sub-entry). The \code{subitem} entry now has no
10306 \parent, but at this stage the \code{subsubitem} entry still has
10307 \code{subitem} as its \parent.
10308 \item The \code{subsubitem} entry is then adjusted moving from a
10309 \gls{sub-entry} to a \gls{top-levelentry}. The \field{name} field was then
10310 modified to:
10311 \begin{codeenv}
10312 \field{name}=
10313 \marg{\comment{}
10314 \gls{bibglsflattenedchildpostsort}
10315 \marg{\comment{}
10316 \comment{name from former parent}
10317 \gls{bibglsflattenedchildpostsort}\marg{item}\marg{subitem}\comment{}
10318 }\comment{}
10319 \marg{subsubitem}\comment{original name}
10320 }
10321 \end{codeenv}
10322 The first argument of \gls!{bibglsflattenedchildpostsort} is
10323 obtained from the \field{name} field of the entry's former \parent\
10324 (which is removed from the \glsdisp{childentry}{child's} set of
10325 \glspl{ancestor}). This field value was changed in the previous
10326 step, and the change is reflected here.
10327
10328 This means that the name for \code{subitem} will be displayed as
10329 \qt{item, subitem} and the name for \code{subsubitem} will be
10330 displayed as \qt{item, subitem, subsubitem}.
10331
10332 \item The \glspl{parententry} \code{item} and \code{subitem}
10333 are removed from the selection as they have no \glspl{locationlist}.
10334 \end{itemize}
10335
10336 Note that the \code{cabbage} \gls{sub-entry} hasn't been adjusted. It
10337 doesn't have any \glspl{sibling} but its \gls{parententry} (\code{vegetable})
10338 has a \gls{locationlist} so it can't be discarded.
10339 If I change the rule:
10340 \begin{codeenv}
10341 \gls{GlsXtrLoadResources}\oarg{\csopt[entries.bib]{src},
10342 \csopt[discard unrecorded]{flatten-lonely-rule},
10343 \csopt[postsort]{flatten-lonely}
10344 }
10345 \end{codeenv}
10346 then this will move the \code{cabbage} entry up a level but the
10347 original \gls{parententry} \code{vegetable} will remain:
10348 \begin{description}\setlength\itemsep{0pt}%
10349 \item[A] \null
10350 \item[aardvark] 1
10351 \item[B] \null
10352 \item[bard] 1
10353 \item[birds, duck] 1
10354 \item[buzz] 1
10355 \item[I] \null
10356 \item[item, subitem, subsubitem] 1
10357 \item[M] \null
10358 \item[minerals] \mbox{}
10359 \begin{description}\setlength\itemsep{0pt}%
10360 \item[amethyst] 1
10361 \item[corundum] 1
10362 \item[quartz] 1
10363 \end{description}
10364 \item[V] \null
10365 \item[vegetable] 1
10366 \item[vegetable, cabbage] 1
10367 \end{description}
10368
10369 Remember that \csopt[postsort]{flatten-lonely} performs the
10370 adjustment after sorting. This means that the entries are still in
10371 the same relative location that they were in with the original
10372 \csopt[false]{flatten-lonely} setting. For example, \code{duck}
10373 remains in the B letter group before \qt{buzz}.
10374
10375 With \csopt[presort]{flatten-lonely} the adjustments are made before
10376 the sorting is performed. For example, using:
10377 \begin{codeenv}
10378 \gls{GlsXtrLoadResources}\oarg{\csopt[entries.bib]{src},
10379 \csopt[discard unrecorded]{flatten-lonely-rule},
10380 \csopt[presort]{flatten-lonely}
10381 }
10382 \end{codeenv}
10383 the \hierarchical\ order is now:
10384 \begin{description}\setlength\itemsep{0pt}%
10385 \item[A] \null
10386 \item[aardvark] 1
10387 \item[B] \null
10388 \item[bard] 1
10389 \item[buzz] 1
10390 \item[C] \null
10391 \item[cabbage] 1
10392 \item[D] \null
10393 \item[duck] 1
10394 \item[M] \null
10395 \item[minerals] \mbox{}
10396 \begin{description}\setlength\itemsep{0pt}%
10397 \item[amethyst] 1
10398 \item[corundum] 1
10399 \item[quartz] 1
10400 \end{description}
10401 \item[S] \null
10402 \item[subsubitem] 1
10403 \item[V] \null
10404 \item[vegetable] 1
10405 \end{description}
10406 This method uses a different format for the modified \field{name}
10407 field. For example, the \code{duck} entry now has:
10408 \begin{codeenv}
10409 \field{name}=\marg{\gls{bibglsflattenedchildpresort}\marg{duck}\marg{birds}}
10410 \end{codeenv}
10411 The default definition of \gls{bibglsflattenedchildpresort} simply
10412 does the first argument and ignores the second. The sorting is then
10413 performed, but the interpreter recognises this command and can
10414 deduce that the sort value for this entry should be \code{duck},
10415 so \qt{duck} now ends up in the D letter group.
10416
10417 If you provide a definition of \gls{bibglsflattenedchildpresort} in
10418 the \atentry{preamble}, it will be picked up by the interpreter.
10419 For example:
10420 \begin{codeenv}
10421 \atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\gls{bibglsflattenedchildpresort}}[2]\marg{\idx{param}1 (\idx{param}2)}}}
10422 \end{codeenv}
10423
10424 Note that the \field{text} field is only changed if not already set.
10425 This option may have unpredictable results for abbreviations as the
10426 \field{name} field (and sometimes the \field{text} field) is
10427 typically set by the abbreviation style. Remember that
10428 if the \gls{parententry} doesn't have a \igls{locationlist} and the rule isn't
10429 set to \optfmt{no discard} then the \gls{parententry} will be discarded
10430 after all relevant entries and their dependencies have been
10431 selected, so any cross-references within the \gls{parententry} (such as
10432 \ics{gls} occurring in the description) may end up being selected
10433 even if they wouldn't be selected if the \gls{parententry} didn't exist.
10434
10435 With both \optfmt{presort} and \optfmt{postsort}, if the \parent\ \field{name}
10436 is the same as the \glsdisp{childentry}{child's} \field{name}
10437 then the \child\ is considered a \igls{homograph} and
10438 the \glsdisp{childentry}{child's} name is set to:
10439 \begin{codeenv*}
10440 \format{bibglsflattenedhomograph}
10441 \end{codeenv*}
10442 instead of the corresponding \csfmt{bibglsflattenedchild\ldots sort}.
10443 This defaults to just \meta{name}.
10444
10445
10446 \optsection{flatten-lonely-rule}
10447
10448 This option governs the rule used by \csopt{flatten-lonely} to
10449 determine which \glspl{sub-entry} (that have no \glspl{sibling}) to adjust and
10450 which \glsdisp{parententry}{parents} to remove. The value may be one
10451 of the following, where \meta{condition} is the condition provided
10452 by \csopt{flatten-lonely-condition}:
10453 \begin{description}
10454 \item[\optfmt{only unrecorded parents}] Only the \glspl{sub-entry}
10455 that have a \parent\ without a \igls{locationlist} (and have
10456 \meta{condition} evaluate to true) will be altered.
10457 The \gls{parententry} will be removed from the selection
10458 if the child entry is adjusted.
10459 This value is the default setting.
10460
10461 \item[\optfmt{discard unrecorded}] This setting will adjust all
10462 \glspl{sub-entry} that have no \glspl{sibling} (and have
10463 \meta{condition} evaluate to true) regardless of whether or not the
10464 \parent\ has a \igls{locationlist}.
10465 Only the \glspl{parententry} that don't have a \gls{locationlist} will be
10466 removed from the selection if the child entry is adjusted.
10467
10468 \item[\optfmt{no discard}] This setting will adjust all
10469 \glspl{sub-entry} that don't have \glspl{sibling} (and have
10470 \meta{condition} evaluate to true) regardless of whether or not the
10471 \parent\ has a \igls{locationlist}. No entries will be discarded, so
10472 \glspl{parententry} that don't have a \igls{locationlist} will still appear in the
10473 glossary.
10474 \end{description}
10475 In the above, the \igls{locationlist} includes \glspl{record} and
10476 cross-references obtained from the \field{see} or \field{seealso}
10477 fields. See \csopt{flatten-lonely} for further details.
10478
10479 \optsection{flatten-lonely-condition}
10480
10481 The value may either be empty, to indicate true (the default), or a
10482 complex condition using syntax described in
10483 \sectionref{sec:conditionals}. After taking into account
10484 \csopt{flatten-lonely} and \csopt{flatten-lonely-rule}, this option
10485 determines whether or not the child entry will be adjusted. If the
10486 condition evaluates to false, the child entry won't be adjusted.
10487
10488 For example, if both the parent entry and the child entry have long
10489 names, it may be better to keep their hierarchy. The following
10490 will only flatten lonely entries where both the child name and the
10491 parent name have less then 25 characters:
10492 \begin{codeenv*}
10493 \csopt[postsort]{flatten-lonely},
10494 \csopt[\gls{LEN}\marg{parent \idx{follow} \field{name}} \idx{ltcmp} 25 \idx{ampand} \gls{LEN}\marg{\field{name}} \idx{ltcmp} 25]{flatten-lonely-condition}
10495 \end{codeenv*}
10496 Alternatively, for a combined length of less than 50 characters:
10497 \begin{codeenv*}
10498 \csopt[postsort]{flatten-lonely},
10499 \csopt[\gls{LEN}\marg{parent \idx{follow} \field{name} \idx{concat-plus} \field{name}} \idx{ltcmp} 50]{flatten-lonely-condition}
10500 \end{codeenv*}
10501 This doesn't include the number of characters taken up by the
10502 separator but the maximum value can be adjusted to allow for that,
10503 given a constant string separator.
10504
10505 \optsection{flatten-lonely-missing-field-action}
10506
10507 This option indicates what to do if a source field identified in
10508 \csopt{flatten-lonely-condition} is missing. The value may be one of:
10509 \begin{itemize}
10510 \item \optfmt{skip}: return null;
10511 \item \optfmt{fallback}: use the fallback for the missing field
10512 (see \sectionref{sec:fallbacks}), if
10513 one is available, otherwise return null (default);
10514 \item \optfmt{empty}: treat the missing value as empty.
10515 \end{itemize}
10516 Returning null will result in the flatten lonely instruction being omitted.
10517
10518 \optsection{strip-missing-parents}
10519
10520 The \sty{glossaries} package requires that all \glspl{childentry} must be
10521 defined after the \gls{parententry}. An error occurs otherwise, so
10522 \bibgls\ will omit the \field{parent} field if it can't be found in
10523 the given \igls{resourceset}. However, when the default
10524 \csopt[false]{strip-missing-parents} is on, this omission only occurs
10525 while writing the definitions in the \ext{glstex} file (after
10526 selection and sorting).
10527
10528 Sorting is performed \hierarchically\ and the \field{group} field is
10529 set accordingly for the \glspl{top-levelentry} (but not for
10530 \glspl{childentry}), which means that an entry with a \field{parent}
10531 field will be treated by the sort method as a \gls{childentry}. This can
10532 lead to a strange result, which \bibgls\ warns about:
10533 \begin{alltt}
10534 Parent '\meta{parent id}' not found for entry \meta{child-id}
10535 \end{alltt}
10536
10537 This is the default behaviour as it may simply be a result of a
10538 typing mistake in the \field{parent} field. If you actually want
10539 missing \glsdisp{parententry}{parents} to be stripped before sorting (but after the
10540 selection process) then use \csopt[true]{strip-missing-parents}. If
10541 you want all \glsdisp{parententry}{parents} stripped then use \csopt{flatten} or
10542 \csopt[parent]{ignore-fields} instead. As from version 1.4, if you
10543 want \bibgls\ to create the missing \glsdisp{parententry}{parents}, then you can use
10544 \csopt[create]{missing-parents}.
10545
10546 \optsection{missing-parents}
10547
10548 As an alternative to \csopt{strip-missing-parents}, as from version
10549 1.4 you can now use \csopt[\meta{value}]{missing-parents} where
10550 \meta{value} may be one of:
10551 \begin{itemize}
10552 \item \optfmt{strip}: this is equivalent to
10553 \csopt[true]{strip-missing-parents};
10554
10555 \item \optfmt{warn}: this is equivalent to the default
10556 \csopt[false]{strip-missing-parents};
10557
10558 \item \optfmt{create}: this will create a new \atentry{index} entry
10559 with the missing \glsdisp{parententry}{parent's} label (after it's
10560 been processed by options such as \csopt{labelify}) with the
10561 \field{name} obtained from the \emph{original} value of the
10562 \field{parent} field (before being processed by options like
10563 \csopt{labelify}). If the \gls{childentry} has the \field{type} field
10564 set, then the new \gls{parententry} will be given the same value. The
10565 \field{category} for the new \gls{parententry} can be assigned with
10566 \csopt{missing-parent-category}.
10567 \end{itemize}
10568
10569 For example, consider the \exfile!{books.bib} file which contains
10570 entries like:
10571 \begin{codeenv}
10572 \atentry{entry}\marg{ubik,
10573 \field{name}=\marg{Ubik},
10574 \field{description}=\marg{novel by Philip K. Dick},
10575 \fieldfmt{identifier}=\marg{book},
10576 \fieldfmt{author}=\marg{\gls{sortmediacreator}\marg{Philip K.}\marg{Dick}},
10577 \fieldfmt{year}=\marg{1969}
10578 }
10579 \end{codeenv}
10580 then the field alias:
10581 \begin{codeenv}
10582 \csopt[\fieldfmt{author}=\field{parent}]{field-aliases}
10583 \end{codeenv}
10584 will treat:
10585 \begin{codeenv}
10586 \fieldfmt{author}=\marg{\gls{sortmediacreator}\marg{Philip K.}\marg{Dick}},
10587 \end{codeenv}
10588 as though it had been defined as:
10589 \begin{codeenv}
10590 \field{parent}=\marg{\gls{sortmediacreator}\marg{Philip K.}\marg{Dick}},
10591 \end{codeenv}
10592 This can be converted into a label with the options:
10593 \begin{codeenv}
10594 \csopt[parent]{labelify},
10595 \csopt[
10596 \marg{[ \cs{cs.string}\csfmt{.}]}\marg{}
10597 ]{labelify-replace}
10598 \end{codeenv}
10599 If the interpreter has been provided with the definition:
10600 \begin{codeenv}
10601 \cs{providecommand}*\marg{\gls{sortmediacreator}}[2]\marg{\idx{param}2 \idx{param}1}
10602 \end{codeenv}
10603 then the \field{parent} field for the \code{ubik} entry
10604 will become \code{DickPhilipK} but the original value is stored
10605 internally when \csopt[create]{missing-parents} is set so that it
10606 can be used as the \field{name} if the \parent\ needs to be created.
10607 Once all the entries have been processed, if \code{ubik} has been
10608 selected but no entry can be found with the label \code{DickPhilipK}
10609 then a new entry will be added as though it had been defined with:
10610 \begin{codeenv}
10611 \atentry{index}\marg{DickPhilipK,
10612 \field{name}=\marg{\gls{sortmediacreator}\marg{Philip K.}\marg{Dick}}
10613 }
10614 \end{codeenv}
10615 This is an alternative approach to the \exfile{sample-authors.tex}
10616 document from the \hyperref[sec:examples]{examples chapter}.
10617
10618 \optsection{missing-parent-category}
10619
10620 If a missing \gls{parententry} is created through the use of
10621 \csopt[create]{missing-parents} then the \field{category} field can
10622 be assigned to the new \gls{parententry} with this option. The
10623 \meta{value} may be one of:
10624 \begin{itemize}
10625 \item \code{same as child}: the \gls{parententry}['s] \field{category}
10626 field is set to the same value as the \glsdisp{childentry}{child's} (if set);
10627 \item \code{same as base}: the \gls{parententry}['s] \field{category} is
10628 set to the base name of the \ext{bib} file that provided the
10629 \gls{childentry}['s] definition;
10630 \item \code{no value} or \code{false}: don't set the \field{category} field;
10631 \item \meta{label}: the \gls{parententry}['s] \field{category} field is set to
10632 \meta{label} (which shouldn't contain any special characters).
10633 \end{itemize}
10634 The default setting is \csopt[no value]{missing-parent-category}.
10635
10636 \optsection{group-level}
10637
10638 If letter \idx{group} formation is enabled (see \csopt{group},
10639 \csopt{group-formation} and \longarg{group}) then the default
10640 behaviour is to only assign the group label for \glspl{top-levelentry}.
10641 This option allows the group label to be assigned to \glspl{sub-entry}
10642 if \idxpl{sub-group} are required.
10643 The value may be one of the following:
10644 \begin{itemize}
10645 \item \meta{n}: only assign the group for level~\meta{n} entries;
10646 \item \code{>}\meta{n}: only assign the group for entries with a
10647 level greater than \meta{n};
10648 \item \code{>=}\meta{n}: only assign the group for entries with a
10649 level greater than or equal to \meta{n};
10650 \item \code{<}\meta{n}: only assign the group for entries with a
10651 level less than \meta{n};
10652 \item \code{<=}\meta{n}: only assign the group for entries with a
10653 level less than or equal to \meta{n};
10654 \item \code{all}: equivalent to \csopt[>=0]{group-level}.
10655 \end{itemize}
10656 The default setting is \csopt[0]{group-level}.
10657 If no value is provided, \csopt[all]{group-level} is assumed. The
10658 hierarchical levels start at 0 (\gls{top-levelentry}). For any value
10659 other than \csopt[0]{group-level}, the parent entry label will be
10660 included in the group label.
10661
10662 The \idx{hiergroup} titles are formatted according to
10663 \gls{bibglshiersubgrouptitle}. If the group title would
10664 usually be set with the command \csfmt{bibglsset\ldots group}
10665 for \glspl{top-levelentry} then the \idx{hiergroup} title would
10666 be set with the analogous \csfmt{bibglsset\ldots group} command.
10667 For example, letter groups are normally set with
10668 \gls{bibglssetlettergrouptitle} but hierarchical letter groups are set
10669 with \gls{bibglssetlettergrouptitlehier}.
10670
10671 If the \longarg{no-group} setting is on then this option has no effect.
10672
10673 \begin{important}
10674 Any value other than the default \csopt[0]{group-level} requires
10675 \sty{glossaries-extra} v1.49+, which provides \cs{glssubgroupheading}.
10676 \end{important}
10677
10678 \Idxpl{sub-group} are implemented by the glossary style command:
10679 \nosecformatdef{glssubgroupheading}
10680 The \sty{glossaries-extra} package automatically implements:
10681 \begin{codeenv}
10682 \cmd{renewcommand}*\marg{\cs{glssubgroupheading}}[4]\marg{\cs{glsgroupheading}\marg{\idx{param}4}}
10683 \end{codeenv}
10684 whenever a style is set, so that if the style doesn't provide a
10685 definition for this command, it will behave like \cs{glsgroupheading}.
10686
10687 \optsection{merge-small-groups}
10688
10689 Merges consecutive \idxpl{smallgroup} that have less than \meta{n} entries. The
10690 default is \csopt[0]{merge-small-groups}, which switches off this
10691 action. If \meta{n} is omitted, \csopt[1]{merge-small-groups} is
10692 assumed.
10693
10694 This setting only has an effect if group formation is enabled.
10695 If hierarchical \idxpl{sub-group} are enabled (\csopt{group-level}) then
10696 merging is only performed on consecutive small groups within the
10697 same hierarchical level. Any \glspl{childentry} that aren't in their
10698 own \idx{sub-group} are included in the higher level group count.
10699
10700 For example, suppose you have a large number of entries in most of
10701 the letter groups:
10702 \begin{codeenv}
10703 \atentry{index}\marg{aardvark}
10704 \atentry{index}\marg{ant}
10705 \atentry{index}\marg{alligator}
10706 \atentry{index}\marg{ape}
10707 \comment{etc}
10708 \end{codeenv}
10709 but you only have one entry in each of the \qt{X}, \qt{Y} and \qt{Z}
10710 groups:
10711 \begin{codeenv}
10712 \atentry{index}\marg{xylem}
10713 \atentry{index}\marg{yak}
10714 \atentry{index}\marg{zebra}
10715 \end{codeenv}
10716 then you may prefer to merge these entries into a single group:
10717 \begin{codeenv}
10718 \gls{GlsXtrLoadResources}\oarg{merge-small-groups}
10719 \end{codeenv}
10720 The title of this merged group is obtained from
10721 \gls{bibglsmergedgrouptitle} (or \gls{bibglsmergedgrouptitle} if
10722 hierarchical groups have been enabled with \csopt{group-level}).
10723 For the above example, the merged letter group would have the title
10724 \qt{X, Y, Z}. If there are more than three groups then the middle
10725 group titles are replace with an ellipsis. For example, if there is
10726 also only one entry in the \qt{W} letter group, then the merged
10727 title would be \qt{W,\ldots, Z}.
10728
10729 The small groups must be consecutive (there is no group between
10730 them) and on the same hierarchical level in order to be merged.
10731 In the above example, if the yak entry isn't selected so that there
10732 is no \qt{Y} letter group, then the \qt{X} and \qt{Z} groups can be
10733 merged (with the merged title \qt{X, Z}). If, on the other hand,
10734 extra entries occur in the \qt{Y} letter group, so that it is larger
10735 than the value of \csopt{merge-small-groups}, then \qt{X} and
10736 \qt{Z} can no longer be merged.
10737
10738 \section{Master Documents}
10739 \label{sec:master}
10740
10741 Suppose you have two documents \filefmt{mybook.tex} and
10742 \filefmt{myarticle.tex} that share a common glossary that's shown
10743 in \filefmt{mybook.pdf} but not in \filefmt{myarticle.pdf}.
10744 Furthermore, you'd like to use \isty{hyperref} and be able to click
10745 on a term in \filefmt{myarticle.pdf} and be taken to the relevant
10746 page in \filefmt{mybook.pdf} where the term is listed in the
10747 glossary.
10748
10749 This can be achieved with the \catattr{targeturl} and
10750 \catattr{targetname} category attributes. For example, without
10751 \bibgls\ the file \filefmt{mybook.tex} might look like:
10752 \begin{codeenv}
10753 \cmd{documentclass}\marg{book}
10754 \cmd{usepackage}[colorlinks]\marg{hyperref}
10755 \cmd{usepackage}\marg{glossaries-extra}
10756 \strut
10757 \cs{cs.makeglossaries}
10758 \strut
10759 \gls{newglossaryentry}\marg{sample}\marg{\field{name}=\marg{sample},\field{description}=\marg{an example}}
10760 \strut
10761 \cmd{begin}\marg{document}
10762 \cs{chapter}\marg{Example}
10763 \cs{gls}\marg{sample}.
10764 \strut
10765 \cs{printglossaries}
10766 \cmd{end}\marg{document}
10767 \end{codeenv}
10768 The other document \filefmt{myarticle.tex} might look like:
10769 \begin{codeenv}
10770 \cmd{documentclass}\marg{article}
10771 \cmd{usepackage}[colorlinks]\marg{hyperref}
10772 \cmd{usepackage}\marg{glossaries-extra}
10773 \strut
10774 \cs{newignoredglossary*}\marg{external}
10775 \ics{glssetcategoryattribute}\marg{external}\marg{targeturl}\marg{mybook.pdf}
10776 \cs{glssetcategoryattribute}\marg{external}\marg{targetname}\marg{\cs{glolinkprefix}\cs{glslabel}}
10777 \strut
10778 \gls{newglossaryentry}\marg{sample}\marg{\field{type}=external,\field{category}=external,
10779 \field{name}=\marg{sample},\field{description}=\marg{an example}}
10780 \strut
10781 \cmd{begin}\marg{document}
10782 \cs{gls}\marg{sample}.
10783 \cmd{end}\marg{document}
10784 \end{codeenv}
10785 In this case the \mainglossary\ isn't used, but the category
10786 attributes allow a mixture of internal and external references, so
10787 the \mainglossary\ could be used for the internal
10788 references. (In which case, \csfmt{makeglossaries} and
10789 \csfmt{printglossaries} would need to be added back to
10790 \filefmt{myarticle.tex}.)
10791
10792 Note that both documents had to define the common terms. The above
10793 documents can be rewritten to work with \bibgls. First a \ext{bib}
10794 file needs to be created:
10795 \begin{codeenv}
10796 \atentry{entry}\marg{sample,
10797 \field{name}=\marg{sample},
10798 \field{description}=\marg{an example}
10799 }
10800 \end{codeenv}
10801 Assuming this file is called \filefmt{myentries.bib}, then
10802 \filefmt{mybook.tex} can be changed to:
10803 \begin{codeenv}
10804 \cmd{documentclass}\marg{book}
10805 \cmd{usepackage}[colorlinks]\marg{hyperref}
10806 \cmd{usepackage}[record]\marg{glossaries-extra}
10807 \strut
10808 \gls{GlsXtrLoadResources}\oarg{\csopt[myentries]{src}}
10809 \strut
10810 \cmd{begin}\marg{document}
10811 \cs{chapter}\marg{Example}
10812 \cs{gls}\marg{sample}.
10813 \strut
10814 \cs{printunsrtglossaries}
10815 \cmd{end}\marg{document}
10816 \end{codeenv}
10817 and \filefmt{myarticle.tex} can be changed to:
10818 \begin{codeenv}
10819 \cmd{documentclass}\marg{article}
10820 \cmd{usepackage}[colorlinks]\marg{hyperref}
10821 \cmd{usepackage}[record]\marg{glossaries-extra}
10822 \strut
10823 \cs{newignoredglossary*}\marg{external}
10824 \cs{glssetcategoryattribute}\marg{external}\marg{targeturl}\marg{mybook.pdf}
10825 \cs{glssetcategoryattribute}\marg{external}\marg{targetname}\marg{\cs{glolinkprefix}\cs{glslabel}}
10826 \strut
10827 \gls{GlsXtrLoadResources}\oarg{
10828 \csopt[myentries]{src},
10829 \csopt[none]{sort},
10830 \csopt[external]{type},
10831 \csopt[external]{category}
10832 }
10833 \strut
10834 \cmd{begin}\marg{document}
10835 \cs{gls}\marg{sample}.
10836 \cmd{end}\marg{document}
10837 \end{codeenv}
10838 Most of the options related to sorting and the glossary format are
10839 unneeded here since the glossary isn't being displayed. This may be
10840 sufficient for your needs, but it may be that the book has changed
10841 various settings that have been written to \filefmt{mybook.glstex}
10842 but aren't present in the \iext{bib} file (such as
10843 \csopt[uc]{short-case-change}). In this case, you could just remember to copy
10844 over the settings from \filefmt{mybook.tex} to
10845 \filefmt{myarticle.tex}, but
10846 another possibility is to simply make \filefmt{myarticle.tex} input
10847 \filefmt{mybook.glstex} instead of using \gls{GlsXtrLoadResources}. This
10848 can work but it's not so convenient to set the label prefix, the
10849 type and the category. The \optfmt{master} option allows this, but
10850 it has limitations (see below), so in complex cases (in particular
10851 different label prefixes combined with \hierarchical\ entries or cross-references) you'll have to use
10852 the method shown in the example code above.
10853
10854 \optsection{master}
10855
10856 This option will disable most of the options that relate to
10857 parsing and processing data contained in \iext{bib} files
10858 (since this option doesn't actually read any \ext{bib} files).
10859 It also can't be used with \csopt[copy]{action} or \csopt[define
10860 or copy]{action}. A value of \code{false} will switch off this
10861 setting (the default).
10862
10863 The use of \optfmt{master} isn't always suitable. In particular
10864 if any of the terms cross-reference each other, such as through
10865 the \field{see} or \field{seealso} field or the \field{parent} field or
10866 using commands like \ics{gls} in any of the other fields when
10867 the labels have been assigned prefixes. In this
10868 case you will need to use the method described in the example above.
10869
10870 The \meta{name} is the name of the \iext{aux} file for the
10871 \gls{masterdocument} without the extension (in this case, \filefmt{mybook}). It
10872 needs to be relative to the document referencing it or an absolute
10873 path using forward slashes as the directory divider. Remember that
10874 if it's a relative path, the PDF files (\filefmt{mybook.pdf} and
10875 \filefmt{myarticle.pdf}) will also need to be located in the same
10876 relative position.
10877
10878 When \bibgls\ detects the \csopt{master} option, it won't search for
10879 entries in any \ext{bib} files (for that particular resource set)
10880 but will create a \iext{glstex} file that inputs the
10881 \gls{masterdocument}['s] \ext{glstex} files, but it will
10882 additionally temporarily adjust the internal commands used to define
10883 entries so that the prefix given by \csopt{label-prefix}, the
10884 glossary type and the category type are all automatically inserted.
10885 If the \csopt{type} or \csopt{category} options haven't been used,
10886 the corresponding value will default to \optfmt{master}. The
10887 \catattr{targeturl} and \catattr{targetname} category attributes
10888 will automatically be set, and the glossary type will be provided
10889 using \code{\ics{provideignoredglossary*}\margm{type}} (even if
10890 \longarg{no-provide-glossaries} is set).
10891
10892 The above \filefmt{myarticle.tex} can be changed to:
10893 \begin{codeenv}
10894 \cmd{documentclass}\marg{article}
10895 \cmd{usepackage}[colorlinks]\marg{hyperref}
10896 \cmd{usepackage}[record]\marg{glossaries-extra}
10897 \strut
10898 \gls{GlsXtrLoadResources}\oarg{\csopt[book.]{label-prefix},\csopt[mybook]{master}}
10899 \strut
10900 \cmd{begin}\marg{document}
10901 \cs{gls}\marg{book.sample}.
10902 \cmd{end}\marg{document}
10903 \end{codeenv}
10904
10905 There are some settings from the \gls{masterdocument} that you
10906 still need to repeat in the other document. These include
10907 the label prefixes set when the \gls{masterdocument} loaded
10908 the resource files, and any settings in the \gls{masterdocument}
10909 that relate to the \gls{masterdocument}['s] entries.
10910
10911 For example, if the \gls{masterdocument} loaded a resource file
10912 with \csopt[term.]{label-prefix} then you also need this
10913 prefix when you reference the entries in the dependent document
10914 in addition to the \optfmt{label-prefix} for the dependent document.
10915 Suppose \filefmt{mybook.tex} loads the resources using:
10916 \begin{codeenv}
10917 \gls{GlsXtrLoadResources}\oarg{\csopt[myentries]{src},\csopt[term.]{label-prefix}}
10918 \end{codeenv}
10919 and \filefmt{myarticle.tex} loads the resources using:
10920 \begin{codeenv}
10921 \gls{GlsXtrLoadResources}\oarg{\csopt[book.]{label-prefix},\csopt[mybook]{master}}
10922 \end{codeenv}
10923 Then the entries referenced in \filefmt{myarticle.tex} need
10924 to use the prefix \optfmt{book.term.}\ as in:
10925 \begin{codeenv}
10926 This is a \cs{gls}\marg{book.term.sample} term.
10927 \end{codeenv}
10928
10929 Remember that the category labels will need adjusting to reflect the
10930 change in category label in the dependent document.
10931
10932 For example, if \filefmt{mybook.tex} included:
10933 \begin{codeenv}
10934 \cs{setabbreviationstyle}\marg{long-short-sc}
10935 \end{codeenv}
10936 then \filefmt{myarticle.tex} will need:
10937 \begin{codeenv}
10938 \cs{setabbreviationstyle}\oarg{master}\marg{long-short-sc}
10939 \end{codeenv}
10940 (change \optfmt{master} to \meta{value} if you have used
10941 \csopt[\meta{value}]{category}). You can, of course, choose
10942 a different abbreviation style for the dependent document,
10943 but the category in the optional argument needs to be correct.
10944
10945 \optsection{master-resources}
10946
10947 If the \gls{masterdocument} has multiple resource files
10948 then by default all the \gls{masterdocument}['s]
10949 \iext{glstex} files will be input. If you don't want them all
10950 you can use \optfmt{master-resources} to specify
10951 only those files that should be included. The value \meta{list} is
10952 a comma-separated list of names, where each name corresponds
10953 to the basename of the applicable \gls{resourceset}.
10954 The file \primaryresourcefmt\ is considered the primary resource
10955 file and the files \suppresourcefmt{\meta{n}} (starting with
10956 \meta{n} equal to 1) are considered the supplementary resource
10957 files.
10958
10959 For example, to just select the first and third of the
10960 supplementary resource files (omitting the primary
10961 \filefmt{mybook.glstex}):
10962 \begin{codeenv}
10963 \gls{GlsXtrLoadResources}\oarg{
10964 \csopt[mybook]{master},
10965 \csopt[mybook-1,mybook-3]{master-resources}
10966 }
10967 \end{codeenv}
10968
10969 \section{Field and Label Options}
10970 \label{sec:fieldlabelopts}
10971
10972 The options in this section may be used to set or adjust field
10973 values or labels. Some field values are expected to be labels (such
10974 as \field{group}). These labels must not contain special
10975 characters or commands, but it's possible to convert a field value
10976 into a valid label using options such as \csopt{labelify}.
10977
10978 \subsection{Entry Labels}
10979 \label{sec:labelopts}
10980
10981 \optsection[\subsubsection]{interpret-label-fields}
10982
10983 This is a boolean option that determines whether or not the fields
10984 that may only contain labels should have their values interpreted
10985 (\field{parent}, \field{category}, \field{type}, \field{group},
10986 \field{seealso} and \field{alias}). Although this option interprets
10987 commands within those fields, it doesn't strip any characters that
10988 can't be used within a label. The \field{see} field isn't included
10989 as it may optionally start with \code{\oargm{tag}} where \meta{tag}
10990 may legitimately contain \LaTeX\ code that shouldn't be interpreted.
10991
10992 The default setting is \csopt[false]{interpret-label-fields}.
10993 Note that if this setting is on, \iglspl{crossresourceref} aren't
10994 permitted. This setting has no effect if the interpreter has been
10995 disabled.
10996
10997 Related settings are \csopt{labelify} and
10998 \csopt{labelify-list} which can be used to strip content that
10999 can't be used in labels and may be used more generally for other
11000 fields. The \csopt{labelify} and \csopt{labelify-list} options
11001 are performed before \csopt{interpret-label-fields}.
11002
11003 \optsection[\subsubsection]{labelify}
11004
11005 This option should take a comma-separated list of recognised field names as the
11006 value. (If a field is present in both \csopt{labelify} and
11007 \csopt{labelify-list}, then \csopt{labelify-list} takes precedence.)
11008 Note that if this setting is on, \iglspl{crossresourceref} aren't
11009 permitted. The value is required for this key but may be empty,
11010 which indicates an empty set of fields (that is, the setting is
11011 switched off).
11012
11013 Each listed field will be converted into a string suitable
11014 for use as a label. (Not necessarily a glossary entry label, but
11015 any label that may be used in the construction of a control sequence
11016 name.)
11017
11018 The conversion is performed in the following order:
11019 \begin{enumerate}
11020 \item If the interpreter is on and the field value contains
11021 any of the characters \idx{escchar}~(backslash),
11022 \idx{bgroupchar}~(begin group), \idx{egroupchar}~(end group),
11023 \idx{nbspchar}~(non-breakable space) or \idx{mshiftchar}~(maths shift),
11024 then the value is interpreted.
11025
11026 \item Any substitutions that have been specified with
11027 \csopt{labelify-replace} are performed.
11028
11029 \item All characters that aren't alphanumeric or the space character
11030 or any of the following punctuation
11031 characters \code{.}~(full stop), \code{-}~(hyphen), \code{+}~(plus),
11032 \code{:}~(colon), \code{;}~(semi-colon), \code{\string|}~(pipe),
11033 \code{/}~(forward slash), \code{!}~(exclamation mark),
11034 \code{?}~(question mark), \code{*}~(asterisk), \code{<}~(less than),
11035 \code{>}~(greater than), \code{\textasciigrave}~(backtick),
11036 \code{'}~(apostrophe) or \code{@}~(at-sign) are stripped. If you want to
11037 retain commas, use \csopt{labelify-list} instead. If you want to
11038 strip any of the allowed punctuation, use \csopt{labelify-replace} to
11039 remove the unwanted characters. (Remember that \isty{babel} can make
11040 some of these punctuation characters active, in which case they need
11041 to be stripped.)
11042
11043 \item If \bibgls\ doesn't allow non-ASCII characters in labels, the
11044 value is then decomposed and all non-ASCII characters are removed.
11045 UTF-8 support is automatic if \bibgls\ detects \sty{fontspec} in the document's
11046 transcript file, otherwise UTF-8 in labels will only be supported if
11047 \bibgls\ detects that the versions of \sty{glossaries} and \sty{glossaries-extra}
11048 are new enough to support it.
11049 To ensure better support for UTF-8 with \pdfLaTeX, make sure you
11050 have a recent \TeX\ distribution and up-to-date versions of
11051 \sty{glossaries} and \sty{glossaries-extra}.
11052 \end{enumerate}
11053
11054 For example, suppose the \ext{bib} file contains:
11055 \begin{codeenv}
11056 \atentry{index}\marg{sample,
11057 \field{name}=\marg{\ics{AA} ngstr\ics{umlaut}om, \ics{O} stergaard, d'Arcy, and Fotheringay-Smythe}
11058 }
11059 \end{codeenv}
11060 Then:
11061 \begin{codeenv}
11062 \gls{GlsXtrLoadResources}\oarg{
11063 \csopt[entries]{src},\comment{data in entries.bib}
11064 \csopt[name]{labelify}
11065 }
11066 \end{codeenv}
11067 will convert the \field{name} field into:
11068 \begin{verbatim}
11069 Angstrom stergaard d'Arcy and Fotheringay-Smythe
11070 \end{verbatim}
11071 if \bibgls\ doesn't support non-ASCII characters in labels otherwise it will be:
11072 \begin{verbatim}
11073 Ångström Østergaard d'Arcy and Fotheringay-Smythe
11074 \end{verbatim}
11075 Note that \O\ is considered an unmodified letter and so can't
11076 be decomposed into a basic Latin letter with a combining diacritic.
11077 It's therefore removed completely from the ASCII label
11078 version. Whereas \AA\ can be decomposed into \qt{A} followed by the
11079 \qt{combining ring above} character and \"o can be decomposed into \qt{o}
11080 followed by the \qt{combining diaresis} character. You can use
11081 \csopt{labelify-replace} to replace non-ASCII characters into
11082 the closest match. Alternatively, switch to using \XeLaTeX\ or
11083 \LuaLaTeX.
11084
11085 You can use this option with \csopt{replicate-fields} if you need
11086 to retain the original:
11087 \begin{codeenv}
11088 \gls{GlsXtrLoadResources}\oarg{
11089 \csopt[entries]{src},\comment{data in entries.bib}
11090 \csopt[\field{name}=\marg{\field{user1}}]{replicate-fields},
11091 \csopt[\field{user1}]{labelify}
11092 }
11093 \end{codeenv}
11094
11095 \optsection[\subsubsection]{labelify-list}
11096
11097 This option is like \csopt{labelify} but it retains commas, as it's
11098 designed for fields that should be converted into a comma-separated
11099 list of labels. Any empty elements are removed. For example, with
11100 the \ext{bib} entry from above:
11101 \begin{codeenv}
11102 \gls{GlsXtrLoadResources}\oarg{
11103 \csopt[entries]{src},\comment{data in entries.bib}
11104 \csopt[\field{name}=\marg{\field{user1}}]{replicate-fields},
11105 \csopt[\field{user1}]{labelify-list}
11106 }
11107 \end{codeenv}
11108 will convert the \field{user1} field into:
11109 \begin{verbatim}
11110 Angstrom, stergaard, d'Arcy, and Fotheringay-Smythe
11111 \end{verbatim}
11112 or:
11113 \begin{verbatim}
11114 Ångström, Østergaard, d'Arcy, and Fotheringay-Smythe
11115 \end{verbatim}
11116 depending on whether or not UTF-8 labels are supported.
11117
11118 \optsection[\subsubsection]{labelify-replace}
11119
11120 This option takes a comma-separated list as a value with each
11121 element in the list in the form \code{\margm{regex}\margm{replacement}}
11122 where \meta{regex} is a \gls{regular-expression} (that conforms to \href{http://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html}{Java's
11123 Pattern class}~\cite{pattern}) and \meta{replacement}
11124 is the replacement text. The value is required for this key but
11125 may be empty, which indicates that the
11126 setting is switched off.
11127
11128 Remember that the argument of
11129 \gls{GlsXtrLoadResources} is expanded when written to the \ext{aux}
11130 file so take care to protect any special characters. For example, to
11131 match a literal \idx{full-stop} use \cs{cs.string}\idx{cs.period}
11132 rather than just \idx{cs.period} (backslash dot).
11133
11134 In the \meta{replacement} part, you can use
11135 \ics{glscapturedgroup}\meta{n} to reference a captured sub-sequence.
11136 For example:
11137 \begin{codeenv}
11138 \csopt[\marg{([A-Z])\ics{cs.string}\idx{cs.period}}\marg{\cs{glscapturedgroup}1}]{labelify-replace}
11139 \end{codeenv}
11140 This removes any \idx{full-stop} that follows any of the characters
11141 A,\ldots,Z. Alternatively, you can just use \verb|\string\$|
11142 instead of \cs{glscapturedgroup}. If you want a literal dollar
11143 character, you need to use \cs{glshex}\code{24} (or
11144 \verb|\string\u24|). This isn't recommended for labels (since special
11145 characters are automatically stripped), but
11146 \csopt{sort-replace} follows the same rules as
11147 \csopt{labelify-replace}, and it may be needed
11148 for that.
11149
11150 \begin{important}
11151 You can't use the \gls{MGP} quark (which expands to the \gls{MGP}
11152 identifier in a string \gls{concatenation}) to identify the captured group in this
11153 context, as the replacement text needs to use the correct
11154 \gls{regular-expression} syntax.
11155 \end{important}
11156
11157
11158 Both \csopt{labelify} and \csopt{labelify-list} use the
11159 \csopt{labelify-replace} setting to
11160 perform substitutions. For example, to replace the sub-string \qt{ and }
11161 (including spaces) with a comma:
11162 \begin{codeenv}
11163 \gls{GlsXtrLoadResources}\oarg{
11164 \csopt[entries]{src},\comment{data in entries.bib}
11165 \csopt[\field{name}=\marg{\field{user1}}]{replicate-fields},
11166 \csopt[\marg{ and }\marg{,}]{labelify-replace},
11167 \csopt[\field{user1}]{labelify-list}
11168 }
11169 \end{codeenv}
11170 The earlier example will now end up as:
11171 \begin{verbatim}
11172 Angstrom, stergaard, d'Arcy,Fotheringay-Smythe
11173 \end{verbatim}
11174 or:
11175 \begin{verbatim}
11176 Ångström, Østergaard, d'Arcy,Fotheringay-Smythe
11177 \end{verbatim}
11178 depending on whether or not UTF-8 labels are supported.
11179
11180 Note that this produces the same result regardless of whether or not
11181 the Oxford comma is present as \verb*|, and | would first be
11182 converted to \verb|,,| and then the empty element is removed
11183 resulting in a single comma.
11184
11185 You can have more than one replacement:
11186 \begin{codeenv}
11187 \gls{GlsXtrLoadResources}\oarg{
11188 \csopt[entries]{src},\comment{data in entries.bib}
11189 \csopt[\field{name}=\marg{\field{user1}}]{replicate-fields},
11190 \csopt[
11191 \marg{ and }\marg{,},\comment{first substitution}
11192 \marg{[ '\cs{cs.string}\cmd{-}]}\marg{},\comment{second substitution}
11193 \marg{\ics{glshex}00D8}\marg{O}\comment{third substitution}
11194 ]{labelify-replace},
11195 \csopt[\field{user1}]{labelify-list}
11196 }
11197 \end{codeenv}
11198 This additionally removes the space, apostrophe and hyphen
11199 characters (second substitution) and replaces \qt{\O} (\hex{00D8})
11200 with \qt{O} (third substitution) so the string now ends up as:
11201 \begin{verbatim}
11202 Angstrom,Ostergaard,dArcy,FotheringaySmythe
11203 \end{verbatim}
11204 or:
11205 \begin{verbatim}
11206 Ångström,Ostergaard,dArcy,FotheringaySmythe
11207 \end{verbatim}
11208 depending on whether or not UTF-8 labels are supported.
11209
11210 \optsection[\subsubsection]{label-prefix}
11211
11212 The \csopt{label-prefix} option prepends \meta{tag} to each entry's label. This
11213 \meta{tag} will also be inserted in front of any cross-references, unless they
11214 start with \idprefix{dual} or \idprefix{tertiary} or \idprefix{extn} (where
11215 \meta{n} is an integer). Use \csopt{dual-prefix} to change the dual label
11216 prefixes and \csopt{ext-prefixes} to change the external label prefixes.
11217
11218 If you set \csopt{label-prefix} and you define commands with
11219 \gls{glsxtrnewglslike}, then any of those commands found in entry
11220 fields won't have the \csopt{label-prefix} inserted if the prefix provided with
11221 the command starts with the prefix given in \csopt{label-prefix}.
11222 (This doesn't apply to other prefix options, such as
11223 \csopt{dual-prefix}, so take care if you have a mixture of prefix
11224 options and prefixes identified with \gls{glsxtrnewglslike}.)
11225
11226 As from version 1.8, the \primary\ label prefix is identified
11227 in the \ext{glstex} file with:
11228 \begin{codeenv}
11229 \format{bibglsprimaryprefixlabel}
11230 \end{codeenv}
11231
11232 For example, if the \ext{bib} file contains:
11233 \begin{codeenv}
11234 \atentry{entry}\marg{bird,
11235 \field{name}=\marg{bird},
11236 \field{description} = \marg{feathered animal, such as a \cs{gls}\marg{duck} or \cs{gls}\marg{goose}}
11237 }
11238 \strut
11239 \atentry{entry}\marg{waterfowl,
11240 \field{name}=\marg{waterfowl},
11241 \field{description}=\marg{Any \cs{gls}\marg{bird} that lives in or about water},
11242 \field{see}=\marg{[see also]\marg{duck,goose}}
11243 }
11244 \strut
11245 \atentry{index}\marg{duck}
11246 \strut
11247 \atentry{index}\marg{goose,\field{plural}=\qtdelim{geese}}
11248 \end{codeenv}
11249 Then if this \ext{bib} file is loaded with \csopt[gls.]{label-prefix}
11250 it's as though the entries had been defined as:
11251 \begin{codeenv}
11252 \atentry{entry}\marg{gls.bird,
11253 \field{name}=\marg{bird},
11254 \field{description} = \marg{feathered animal, such as a \cs{gls}\marg{gls.duck} or \cs{gls}\marg{gls.goose}}
11255 }
11256 \strut
11257 \atentry{entry}\marg{gls.waterfowl,
11258 \field{name}=\marg{waterfowl},
11259 \field{description}=\marg{Any \cs{gls}\marg{gls.bird} that lives in or about water},
11260 \field{see}=\marg{[see also]\marg{gls.duck,gls.goose}}
11261 }
11262 \strut
11263 \atentry{index}\marg{gls.duck,\field{name}=\marg{duck}}
11264 \strut
11265 \atentry{index}\marg{gls.goose,\field{name}=\marg{goose},\field{plural}=\qtdelim{geese}}
11266 \end{codeenv}
11267
11268 Remember to use this prefix when you reference the terms in the
11269 document with commands like \ics{gls}.
11270
11271 \optsection[\subsubsection]{duplicate-label-suffix}
11272
11273 The \sty{glossaries} package doesn't permit entries with duplicate
11274 labels (even if they're in different glossaries). If you
11275 have multiple \iglspl{resourceset} and an entry that's selected
11276 in one \igls{resourceset} is also selected in another, by
11277 default, \bibgls\ will issue a warning, but it will still write the
11278 entry definition to the \ext{glstex} file, which means you'll also
11279 get a warning from \sty{glossaries-extra} and the duplicate
11280 definition will be ignored, but associated internal fields
11281 set with commands like \cs{GlsXtrSetField} may still be set.
11282
11283 If you actually want the duplicate, you need to specify a
11284 suffix with \csopt{duplicate-label-suffix}. This suffix is only
11285 set just before writing the entry definition to the \ext{glstex}
11286 file, so it doesn't affect selection criteria nor can label
11287 substitutions be performed in any cross-references. Options such as
11288 \csopt{set-widest} that reference entry labels are incompatible
11289 as they will use the unsuffixed label.
11290
11291 The actual suffix is formed from \meta{value}\meta{n} where \meta{n}
11292 is an integer that's incremented in the event of multiple
11293 duplicates. For example, \csopt[.copy]{duplicate-label-suffix} will
11294 change the label to \meta{id}\code{.copy1} for the first duplicate
11295 of the entry whose label is \meta{id}, and \meta{id}\code{.copy2} for
11296 the second duplicate, etc.
11297
11298 \optsection[\subsubsection]{record-label-prefix}
11299
11300 If set, this option will cause \bibgls\ to pretend that each record
11301 label starts with \meta{tag}, if it doesn't already. For example, suppose
11302 the records in the \ext{aux} file are:
11303 \begin{codeenv}
11304 \gls{glsxtr@record}\marg{bird}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1}
11305 \gls{glsxtr@record}\marg{waterfowl}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1}
11306 \gls{glsxtr@record}\marg{idx.duck}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1}
11307 \gls{glsxtr@record}\marg{idx.goose}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1}
11308 \end{codeenv}
11309 The use of \csopt[idx.]{record-label-prefix} makes \bibgls\ act as
11310 though the records were given as:
11311 \begin{codeenv}
11312 \gls{glsxtr@record}\marg{idx.bird}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1}
11313 \gls{glsxtr@record}\marg{idx.waterfowl}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1}
11314 \gls{glsxtr@record}\marg{idx.duck}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1}
11315 \gls{glsxtr@record}\marg{idx.goose}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1}
11316 \end{codeenv}
11317
11318
11319 \optsection[\subsubsection]{cs-label-prefix}
11320
11321 If you have commands such as \code{\ics{gls}\margm{label}} or
11322 \code{\ics{glstext}\margm{label}} in field
11323 values (in situations where nested link text won't cause a problem)
11324 the \meta{label} will be converted as follows:
11325 \begin{itemize}
11326 \item if \meta{label} starts with \idprefix{dual} then
11327 \idprefix{dual} will be replaced by the \csopt{dual-prefix} value;
11328 \item if \meta{label} starts with \idprefix{tertiary} then
11329 \idprefix{tertiary} will be replaced by the \csopt{tertiary-prefix} value;
11330 \item if \meta{label} starts with \idprefix{extn} then
11331 \idprefix{extn} will be replaced by the corresponding
11332 \csopt{ext-prefixes} setting (if \igls{crossresourceref} mode is
11333 enabled, see \sectionref{sec:resourcesets});
11334 \item if \meta{label} doesn't start with one of the above recognised
11335 prefixes then, if \csopt{cs-label-prefix} has been used the supplied
11336 value will be inserted otherwise the \csopt{label-prefix} setting
11337 will be inserted.
11338 \end{itemize}
11339 For example, given:
11340 \begin{codeenv}
11341 \atentry{entry}\marg{bird,
11342 \field{name}=\marg{bird},
11343 \field{description} = \marg{feathered animal, such as a \cs{gls}\marg{duck} or \cs{gls}\marg{goose}}
11344 }
11345 \end{codeenv}
11346 then if \csopt[idx.]{label-prefix} is set but \csopt{cs-label-prefix}
11347 isn't included in the resource option list this will convert the
11348 \field{description} field to:
11349 \begin{codeenv}
11350 \field{description} = \marg{feathered animal, such as a \cs{gls}\marg{idx.duck} or
11351 \cs{gls}\marg{idx.goose}}
11352 \end{codeenv}
11353 However with \csopt[gls.]{cs-label-prefix} the \field{description}
11354 field will be converted to:
11355 \begin{codeenv}
11356 \field{description} = \marg{feathered animal, such as a \cs{gls}\marg{gls.duck} or
11357 \cs{gls}\marg{gls.goose}}
11358 \end{codeenv}
11359 regardless of the \csopt{label-prefix} setting. Whereas if the
11360 original entry definition is:
11361 \begin{codeenv}
11362 \atentry{entry}\marg{bird,
11363 \field{name}=\marg{bird},
11364 \field{description} = \marg{feathered animal, such as a \cs{gls}\marg{dual.duck} or
11365 \cs{gls}\marg{dual.goose}}
11366 }
11367 \end{codeenv}
11368 then \idprefix{dual} will be replaced by the value of the
11369 \csopt{dual-prefix} option regardless of the \csopt{cs-label-prefix}
11370 setting.
11371
11372 The \csopt{cs-label-prefix} setting doesn't affect labels in the
11373 fields that have an entry label or label list as the value
11374 (\field{parent}, \field{alias}, \field{see} and \field{seealso}).
11375
11376 \optsection[\subsubsection]{ext-prefixes}
11377
11378 Any cross-references in the \iext{bib} file that start with
11379 \idprefix{extn} (where \meta{n} is a positive integer) will be
11380 substituted with the \meta{n}th tag listed in the comma-separated
11381 \meta{list}. If there aren't that many items in the list, the
11382 \idprefix{extn} will simply be removed. The default setting is
11383 an empty list, which will strip all \idprefix{extn} prefixes.
11384 Remember that \igls{crossresourceref} mode needs to be enabled for
11385 this option to work (see \sectionref{sec:resourcesets}).
11386
11387 As from version 1.8, the external label prefixes are identified
11388 in the \ext{glstex} file with:
11389 \begin{codeenv}
11390 \format{bibglsexternalprefixlabel}
11391 \end{codeenv}
11392
11393 For example, suppose the file \filefmt{entries-terms.bib} contains:
11394 \begin{codeenv}
11395 \atentry{entry}\marg{set,
11396 \field{name}=\marg{set},
11397 \field{description}=\marg{collection of values, denoted \cs{gls}\marg{ext1.set}}
11398 }
11399 \end{codeenv}
11400 and the file \filefmt{entries-symbols.bib} contains:
11401 \begin{codeenv}
11402 \atentry{symbol}\marg{set,
11403 \field{name}=\marg{\cs{ensuremath}\marg{\cs{mathcal}\marg{S}}},
11404 \field{description}=\marg{a \cs{gls}\marg{ext1.set}}
11405 }
11406 \end{codeenv}
11407
11408 These files both contain an entry with the label \code{set}
11409 but the \field{description} field includes \code{\cs{gls}\marg{ext1.set}}
11410 which is referencing the entry from the other file. These
11411 two files can be loaded without conflict using:
11412 \begin{codeenv}
11413 \cmd{usepackage}[\styopt{record},\styopt{symbols}]\marg{glossaries-extra}
11414 \strut
11415 \gls{GlsXtrLoadResources}\oarg{\csopt[entries-terms]{src},
11416 \csopt[gls.]{label-prefix},
11417 \csopt[sym.]{ext-prefixes}
11418 }
11419 \strut
11420 \gls{GlsXtrLoadResources}\oarg{\csopt[entries-symbols]{src},
11421 \csopt[symbols]{type},
11422 \csopt[sym.]{label-prefix},
11423 \csopt[gls.]{ext-prefixes}
11424 }
11425 \end{codeenv}
11426
11427 Now the \code{set} entry from \filefmt{entries-terms.bib}
11428 will be defined with the label \code{gls.set} and the
11429 description will be:
11430 \begin{codeenv}
11431 collection of values, denoted \cs{gls}\marg{sym.set}
11432 \end{codeenv}
11433 The \code{set} entry
11434 from \filefmt{entries-symbols.bib} will be defined with the label
11435 \code{sym.set} and the description will be:
11436 \begin{codeenv}
11437 a \cs{gls}\marg{gls.set}
11438 \end{codeenv}
11439
11440 Note that in this case the \ext{bib} files have to be loaded
11441 as two separate resources. They can't be combined into a
11442 single \csopt{src} list as the labels aren't unique.
11443
11444 If you want to allow the flexibility to choose between
11445 loading them together or separately, you'll have to give them
11446 unique labels. For example, \filefmt{entries-terms.bib} could
11447 contain:
11448 \begin{codeenv}
11449 \atentry{entry}\marg{set,
11450 \field{name}=\marg{set},
11451 \field{description}=\marg{collection of values, denoted \cs{gls}\marg{ext1.S}}
11452 }
11453 \end{codeenv}
11454 and \filefmt{entries-symbols.bib} could contain:
11455 \begin{codeenv}
11456 \atentry{symbol}\marg{S,
11457 \field{name}=\marg{\cs{ensuremath}\marg{\cs{mathcal}\marg{S}}},
11458 \field{description}=\marg{a \cs{gls}\marg{ext1.set}}
11459 }
11460 \end{codeenv}
11461 Now they can be combined with:
11462 \begin{codeenv}
11463 \gls{GlsXtrLoadResources}\oarg{\csopt[entries-terms,entries-symbols]{src}}
11464 \end{codeenv}
11465 which will simply strip the \glsdisp{idx.idprefix.extn}{\idprefixfmt{ext1}}
11466 prefix from the cross-references. Alternatively:
11467 \begin{codeenv}
11468 \gls{GlsXtrLoadResources}\oarg{\csopt[entries-terms,entries-symbols]{src},
11469 \csopt[gls.]{label-prefix},
11470 \csopt[gls.]{ext-prefixes}
11471 }
11472 \end{codeenv}
11473 which will insert the supplied \csopt{label-prefix} at the
11474 start of the labels in the entry definitions and will replace
11475 the \idprefixfmt{ext1} prefix with \idprefixfmt{gls} in the
11476 cross-references.
11477
11478 \optsection[\subsubsection]{prefix-only-existing}
11479
11480 This is a boolean option. It's possible that a prefix can end up being
11481 inserted when there's no entry in the current \igls{resourceset} that
11482 matches the prefixed label. If this option is set then the prefix
11483 won't be added if there's no matching entry. The default setting is
11484 \csopt[false]{prefix-only-existing}.
11485
11486 \optsection[\subsubsection]{dependency-fields}
11487
11488 The \meta{list} should be a comma-separated list of fields that
11489 have values in the form \code{\oargm{tag}\meta{id-list}} where
11490 \meta{id-list} is a comma-separated list of entry labels. The value
11491 is required for this key but may be empty, which indicates an empty
11492 set of fields (that is, the setting is switched off).
11493 Note that the listed fields must be recognised as known fields, for
11494 example, custom fields defined with \cs{glsaddstoragekey}.
11495
11496 This setting makes those fields act like the \field{see} field by
11497 identifying the listed entries as dependencies, but the information
11498 isn't added to the cross-reference part of the \gls{locationlist}. This
11499 action is performed after \csopt{labelify-list}, if that's also set.
11500
11501 For example, suppose the file \filefmt{entries-en.bib} contains:
11502 \begin{codeenv}
11503 \atentry{index}\marg{cat,
11504 \fieldfmt{translations-pt}=\marg{gato,gatinho},
11505 \field{seealso}=\marg{kitten}
11506 }
11507 \strut
11508 \atentry{index}\marg{kitten,
11509 \fieldfmt{translations-pt}=\marg{gato,gatinho}
11510 }
11511 \strut
11512 \atentry{index}\marg{staple}
11513 \atentry{index}\marg{rivet}
11514 \atentry{index}\marg{mat}
11515 \atentry{index}\marg{carpet}
11516 \atentry{index}\marg{rug}
11517 \atentry{index}\marg{tapestry}
11518 \atentry{index}\marg{doormat}
11519 \atentry{index}\marg{matting}
11520 \atentry{index}\marg{coconut-matting,
11521 \field{name}=\marg{coconut matting}
11522 }
11523 \atentry{index}\marg{track}
11524 \atentry{index}\marg{furrow}
11525 \end{codeenv}
11526 and suppose the file \filefmt{entries-pt.bib} contains:
11527 \begin{codeenv}
11528 \atentry{index}\marg{gato,
11529 \field{prefix}=\marg{o},
11530 \fieldfmt{translations-en}=\marg{cat,staple,rivet},
11531 \field{seealso}=\marg{gatinho}
11532 }
11533 \strut
11534 \atentry{index}\marg{gatinho,
11535 \fieldfmt{translations-en}=\marg{kitten}
11536 }
11537 \strut
11538 \atentry{index}\marg{tapete,
11539 \fieldfmt{translations-en}=\marg{carpet,rug,mat,tapestry}
11540 }
11541 \strut
11542 \atentry{index}\marg{esteira,
11543 \field{prefix}=\marg{a},
11544 \fieldfmt{translations-en}=\marg{mat,track,matting,furrow}
11545 }
11546 \strut
11547 \atentry{index}\marg{capacho,
11548 \field{prefix}=\marg{o},
11549 \fieldfmt{translations-en}=\marg{doormat,matting,mat,coconut-matting}
11550 }
11551 \end{codeenv}
11552 The aim here is to have a document containing an
11553 English-to-Portuguese and a Portuguese-to-English dictionary. The
11554 custom \fieldfmt{translations-pt} and \fieldfmt{translations-pt}
11555 fields contain comma-separated lists of possible translations. In
11556 this case I don't want to use the \field{see} field (and, in fact,
11557 can't for the entries that have the \field{seealso} field set), but
11558 I can identify the values of those fields as dependent entries to
11559 ensure that they are selected even if they're not referenced in the
11560 document.
11561
11562 For convenience I've aliased the custom fields to \field{user1}:
11563 \begin{codeenv}
11564 \cmd{documentclass}\marg{article}
11565 \strut
11566 \cmd{usepackage}[T1]\marg{fontenc}
11567 \cmd{usepackage}[utf8]\marg{inputenc}
11568 \cmd{usepackage}[british,brazilian]\marg{babel}
11569 \cmd{usepackage}[colorlinks]\marg{hyperref}
11570 \cmd{usepackage}\oarg{\styopt{record},
11571 \styopt{nomain},
11572 \styopt{nostyles},
11573 \styopt[bookindex]{stylemods},
11574 \styopt[\glostyle{bookindex}]{style}
11575 }\marg{glossaries-extra}
11576 \cmd{usepackage}\marg{\isty{glossaries-prefix}}
11577 \strut
11578 \cs{newglossary*}\marg{en}\marg{English Terms}
11579 \cs{newglossary*}\marg{pt}\marg{Portuguese Terms}
11580 \strut
11581 \gls{GlsXtrLoadResources}\oarg{
11582 \csopt[en]{type},
11583 \csopt[entries-en]{src},
11584 \csopt[en-GB]{sort},
11585 \csopt[en]{category},
11586 \csopt[\fieldfmt{translations-pt}=\field{user1}]{field-aliases},
11587 \csopt[\field{user1}]{dependency-fields},
11588 \csopt[\field{user1}:pt-BR:\encap{glsentryname}]{sort-label-list}
11589 }
11590 \gls{GlsXtrLoadResources}\oarg{
11591 \csopt[pt]{type},
11592 \csopt[entries-pt]{src},
11593 \csopt[pt-BR]{sort},
11594 \csopt[pt]{category},
11595 \csopt[\fieldfmt{translations-en}=\field{user1}]{field-aliases},
11596 \csopt[\field{user1}]{dependency-fields},
11597 \csopt[\field{user1}:en-GB:\encap{glsentryname}]{sort-label-list}
11598 }
11599 \strut
11600 \cs{apptoglossarypreamble}\oarg{en}\marg{\cs{selectlanguage}\marg{british}}
11601 \cs{apptoglossarypreamble}\oarg{pt}\marg{\cs{selectlanguage}\marg{brazilian}}
11602 \strut
11603 \cmd{begin}\marg{document}
11604 \cs{selectlanguage}\marg{british}
11605 The \cs{gls}\marg{cat} sat on the \cs{gls}\marg{mat}.
11606 \strut
11607 \cs{selectlanguage}\marg{brazilian}
11608 O \cs{gls}\marg{gato} sentou-se no \cs{gls}\marg{tapete}.
11609 \strut
11610 \cs{renewcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\comment{}
11611 \cs{glsxtrifhasfield}\marg{\field{prefix}}\marg{\idx{param}1}\marg{\ics{xmakefirstuc}\cs{glscurrentfieldvalue}\cs{cs.space}}\marg{}\comment{}
11612 \cs{glossentryname}\marg{\idx{param}1}\comment{}
11613 \cs{glsxtrifhasfield}\marg{\field{useri}}\marg{\idx{param}1}
11614 \marg{; translations: \cs{glsxtrseelist}\cs{glscurrentfieldvalue}}\marg{}\comment{}
11615 }
11616 \cs{printunsrtglossaries}
11617 \cmd{end}\marg{document}
11618 \end{codeenv}
11619
11620 \subsection{Special Fields}
11621 \label{sec:specialfieldopts}
11622
11623 \optsection[\subsubsection]{save-original-id}
11624
11625 The \meta{value} may be the keywords \code{false} or \code{true} or
11626 the name of a field in which to store the entry's original
11627 label (as given in the \ext{bib} file). The default setting is
11628 \csopt[false]{save-original-id}. If \meta{value} is omitted or is the
11629 keyword \code{true}, then \field{originalid} is assumed.
11630
11631 If \meta{value} has an associated key in \gls!{newglossaryentry}
11632 (for example, one provided with \cs{glsaddstoragekey}) it will be
11633 set after the field aliases, otherwise (for example,
11634 \field{originalid}) it will simply be added to the \ext{glstex} file
11635 using \ics{GlsXtrSetField} after the entry definition (which means
11636 the field can't be referenced in other resource options). This
11637 setting is governed by \csopt{save-original-id-action}.
11638
11639 \optsection[\subsubsection]{save-original-id-action}
11640
11641 This option determines whether or not \csopt{save-original-id}
11642 should save the original entry label. No action is performed when
11643 \csopt[false]{save-original-id} otherwise the action is determined
11644 by \meta{value} which may be one of the following keywords:
11645 \begin{itemize}
11646 \item \code{always}: always save the original label (default);
11647 \item \code{no override}: don't override a field that's already been
11648 set;
11649 \item \code{changed override} or \code{changed} or \code{diff}:
11650 only save the original label if it's different from the final label;
11651 \item \code{changed no override}:
11652 only save the original label if it's different from the final label
11653 and the specified field hasn't been set.
11654 \end{itemize}
11655 The \qt{no override} options make no difference if the given field
11656 has no associated key in \gls!{newglossaryentry} (such as
11657 \field{originalid}). For known fields, bear in mind that the field
11658 will be set after field aliasing but before other options, such as
11659 \csopt{ignore-fields}.
11660
11661 \optsection[\subsubsection]{save-definition-index}
11662
11663 This is a boolean option. If the value is omitted \code{true} is
11664 assumed. The default setting is \csopt[false]{save-definition-index}.
11665
11666 This setting will save the \gls{definitionindex} that's used by
11667 \csopt[def]{identical-sort-action} to determine the order of
11668 definition in the special internal field \field{definitionindex}.
11669 This field is assigned when the entry is first created
11670 and can be referenced with \gls{bibglsdefinitionindex}.
11671 You can reference this field with certain resource options, such as
11672 \csopt{format-integer-fields}, but you must place the
11673 \csopt{save-definition-index} resource option first.
11674
11675 Note that (unless you need to maintain \hierarchy) if you want to
11676 order all entries by definition, it's better to use
11677 \csopt[none]{sort}, which doesn't perform any sorting, so the order
11678 will be by definition.
11679
11680 \optsection[\subsubsection]{save-use-index}
11681
11682 This is a boolean option. If the value is omitted \code{true} is
11683 assumed. The default setting is \csopt[false]{save-use-index}.
11684
11685 This setting will save the \gls{orderofuseindex} that's used by
11686 \csopt[use]{identical-sort-action} in the special internal field
11687 \field{useindex}. This field is assigned when the entry picks up
11688 its first record and can be referenced with \gls{bibglsuseindex}.
11689 You can't reference this field in resource options such as
11690 \csopt{format-integer-fields}.
11691
11692 Entries that don't have records won't have this field set. The order
11693 of use corresponds to the first time the entry is recorded in the document.
11694
11695 Note that (unless you need to maintain \hierarchy) if you want to
11696 order all entries by use, it's better to use \csopt[use]{sort},
11697 which doesn't perform any sorting.
11698
11699 \optsection[\subsubsection]{save-from-see}
11700
11701 This option allows you to save a comma-separated list of entry
11702 labels in a designated internal field of the target entry identified
11703 by their \field{see} field. If the \meta{value} is omitted,
11704 \csopt[from-see]{save-from-see} is assumed. The value may be the
11705 keyword \code{false}, which switches off this setting, otherwise the
11706 value should be the desired name of the internal field.
11707 The default setting is \csopt[false]{save-from-see}.
11708
11709 For example, if the \ext{bib} file contains:
11710 \begin{codeenv}
11711 \atentry{index}\marg{gourd}
11712 \atentry{index}\marg{cucumber,\field{see}=\marg{gourd}}
11713 \atentry{index}\marg{pumpkin,\field{see}=\marg{gourd}}
11714 \end{codeenv}
11715 then the resource option \csopt[from-see]{save-from-see} will create
11716 an internal field called \fieldfmt{from-see} for the \code{gourd} entry
11717 that contains the comma-separated list \code{cucumber,pumpkin}.
11718
11719 Note that the given internal field isn't actually assigned within \bibgls, so it
11720 can't be accessed via any resource options. Each item in this list is added using
11721 \ics{glsxtrapptocsvfield} after the source entry (that is, the entry
11722 containing the \field{see} field) is defined in the \ext{glstex}
11723 file. This means that the list will be in the same order as the
11724 entries. You can then pass the field value to \ics{glsseelist}.
11725 For example:
11726 \begin{codeenv}
11727 \cs{glsdefpostdesc}\marg{\comment{}
11728 \cs{glsxtrifhasfield}\marg{from-see}\marg{\cs{glscurrententrylabel}}
11729 \marg{, related: \cs{glsseelist}\marg{\cs{glscurrentfieldvalue}}}\marg{}\%
11730 }
11731 \end{codeenv}
11732
11733 This option has no effect with the \qt{no dependency} selection
11734 criteria (such as \csopt[recorded no deps]{selection}).
11735
11736 \optsection[\subsubsection]{save-from-seealso}
11737
11738 As \csopt{save-from-see} but for the \field{seealso} field. If the
11739 value is omitted, \csopt[from-seealso]{save-from-seealso} is assumed.
11740
11741 \optsection[\subsubsection]{save-from-alias}
11742
11743 As \csopt{save-from-see} but for the \field{alias} field. If the
11744 value is omitted, \csopt[from-alias]{save-from-alias} is assumed.
11745
11746 \optsection[\subsubsection]{save-crossref-tail}
11747
11748 If you have a cross-reference trail where one entry references
11749 another entry using \field{see}, \field{seealso} or \field{alias}
11750 and the referenced entry also references another, and so on, then
11751 you can save the tail end of the trail with this option. Note that
11752 the trail only follows single-label lists (in \field{see} or
11753 \field{seealso}). The trail is terminated if an entry doesn't have
11754 one of those three fields set or if it cross-references multiple
11755 entries or if the trail loops back on itself.
11756
11757 If you have a loop, the tail for some entries may end prematurely
11758 since the algorithm to obtain the tail saves the tail for each
11759 sub-trail to avoid recalculating it. It's best to avoid
11760 this setting if you have cross-reference loops. (Aside from two-way
11761 cross-references, it's best to avoid loops in general.)
11762
11763 The tail label is stored in the field identified by
11764 the \meta{value} of this option. If the value is omitted,
11765 \csopt[crossref-tail]{save-crossref-tail} is assumed.
11766 The field won't be set if there's no tail. The tails are calculated
11767 when writing the entry definitions to the \ext{glstex} file so the
11768 value can't be referenced or otherwise accessed by \bibgls.
11769
11770 Example:
11771 \begin{codeenv}
11772 \atentry{index}\marg{sample1,\field{see}=\marg{sample2}}
11773 \atentry{index}\marg{sample2,\field{see}=\marg{sample3}}
11774 \atentry{index}\marg{sample3,\field{see}=\marg{sample4}}
11775 \atentry{index}\marg{sample4}
11776 \end{codeenv}
11777 The tail for \code{sample1} is \code{sample4}. As a by-product of
11778 the recursion used in calculating the tail for \code{sample1}, the
11779 tail for each element in the trail (\code{sample2} and
11780 \code{sample3}) is also calculated. The tail is the same for each
11781 entry in the trail. The final entry \code{sample4} doesn't have a
11782 tail.
11783
11784 If \code{sample4} is modified to cross-reference \code{sample1}:
11785 \begin{codeenv}
11786 \atentry{index}\marg{sample4,\field{see}=\marg{sample1}}
11787 \end{codeenv}
11788 then when the tail for \code{sample4} is calculated the tail for its
11789 cross-reference (\code{sample1}) is consulted. This has already been
11790 set to \code{sample4}. An entry can't have itself as a tail so the
11791 tail for \code{sample4} is set to \code{sample3}. All the other
11792 entries still have \code{sample4} as their tail because their tail
11793 was determined while traversing the trail for \code{sample1}, which
11794 had to stop when it wrapped round to its starting point.
11795
11796 \optsection[\subsubsection]{save-original-entrytype}
11797
11798 The \meta{value} may be the keywords \code{false} or \code{true} or
11799 the name of a field in which to store the original \gls{entrytype} (as
11800 given in the \ext{bib} file but without the leading \idx{atchar} and
11801 converted to \idx!{lowercase}). The setting is
11802 \csopt[false]{save-original-entrytype}. If \meta{value} is omitted or the
11803 keyword \code{true}, then \csopt[originalentrytype]{save-original-entrytype}
11804 If \meta{value} has an associated key in \gls!{newglossaryentry}
11805 (for example, one provided with \cs{glsaddstoragekey}) it will be
11806 set after the field aliases, otherwise (for example,
11807 \field{originalentrytype}) it will simply be added to the \ext{glstex} file
11808 using \ics{GlsXtrSetField} after the entry definition (which means
11809 the field can't be referenced in other resource options). This
11810 setting is governed by \csopt{save-original-entrytype-action}.
11811
11812 \optsection[\subsubsection]{save-original-entrytype-action}
11813
11814 This option determines whether or not \csopt{save-original-entrytype}
11815 should save the original \gls{entrytype}. No action is performed when
11816 \csopt[false]{save-original-entrytype} otherwise the action is determined
11817 by \meta{value} which may be one of the following keywords:
11818 \begin{itemize}
11819 \item \code{always}: always save the original \gls{entrytype} (default);
11820 \item \code{no override}: don't override a field that's already been
11821 set;
11822 \item \code{changed override} or \code{changed} or \code{diff}:
11823 only save the original \gls{entrytype} if it's different from the final
11824 \gls{entrytype};
11825 \item \code{changed no override}:
11826 only save the original \gls{entrytype} if it's different from the final
11827 \gls{entrytype} and the specified field hasn't been set.
11828 \end{itemize}
11829 The \qt{no override} options make no difference if the given field
11830 is unknown (such as \field{originalentrytype}). For known fields, bear in
11831 mind that the field will be set after field aliasing but before
11832 other options, such as \csopt{ignore-fields}.
11833
11834 The \qt{changed} options ignore case. For example, if the \ext{bib}
11835 file defined an entry with \atentryfmt{INDEX} then both the original
11836 and final \gls{entrytype} will be \code{index}.
11837
11838 \optsection[\subsubsection]{gather-parsed-dependencies}
11839
11840 Dependencies that are found by parsing field values may be gathered into a
11841 comma-separated list saved in a field for later use.
11842 The \meta{value} is the name of the desired field. If the \meta{value} is omitted
11843 \csopt[seealso]{gather-parsed-dependencies} is assumed.
11844 If the designated field is already set, the list will be appended to the existing value.
11845
11846 Note that other dependencies, such as those obtained by examining the
11847 cross-reference fields (\field{see}, \field{seealso} or \field{alias})
11848 or ancestors or dual entries, are not automatically added.
11849 The \meta{value} may be the keyword \code{false} to switch off this option (which is the default).
11850
11851 \subsection{Assignments}
11852 \label{sec:fieldassignments}
11853
11854 \optsection[\subsubsection]{group}
11855
11856 The \csopt{group} option will set the \field{group} field to \meta{label}
11857 unless \meta{label} is \optfmt{auto}. If \csopt[auto]{group} then if
11858 the \longarg{group} switch is used the value of the \field{group}
11859 field is set automatically during the sorting (see also
11860 \csopt{group-formation}, \csopt{group-level}
11861 and \sectionref{sec:logicaldivisions}). If the \longarg{no-group}
11862 setting is on then \csopt[auto]{group} does nothing.
11863
11864 The corresponding group title can be set with
11865 \gls{glsxtrsetgrouptitle} in the document if the title is different
11866 from the label. The default behaviour is \csopt[auto]{group}.
11867
11868 For example:
11869 \begin{codeenv}
11870 \gls{GlsXtrLoadResources}\oarg{\csopt[integer]{sort},\csopt[Constants]{group},
11871 \csopt[entries-constants]{src}\comment{data in entries-constants.bib}
11872 }
11873 \gls{GlsXtrLoadResources}\oarg{\csopt[letter-case]{sort},\csopt[Variables]{group},
11874 \csopt[entries-variables]{src}\comment{data in entries-variables.bib}
11875 }
11876 \end{codeenv}
11877 In this case, if the \field{type} field hasn't been set in the \ext{bib} files,
11878 these entries will be added to the same glossary, but will
11879 be grouped according to each instance of \gls{GlsXtrLoadResources},
11880 with the provided group label.
11881
11882
11883 \optsection[\subsubsection]{category}
11884
11885 The selected entries may all have their \field{category} field
11886 changed before writing their definitions to the \ext{glstex} file.
11887 The \meta{value} may be:
11888 \begin{itemize}
11889 \item \optfmt{false}: switch off this setting (default);
11890 \item \optfmt{same as entry}: set the
11891 \field{category} to the \ext{bib} \gls{entrytype} used to define it
11892 (\idx!{lowercase} and without the initial \code{@}) after any aliasing,
11893 if applicable;
11894
11895 \item \optfmt{same as original entry}: (new to v1.4) set the \field{category}
11896 to the original \gls{entrytype} (\idx!{lowercase} and without
11897 the initial \code{@}) before it was aliased (behaves like
11898 \optfmt{same as entry} if the \gls{entrytype} wasn't aliased);
11899
11900 \item \optfmt{same as base}: (new to v1.1) set the \field{category}
11901 to the base name of the \ext{bib} file (without the extension)
11902 that provided the entry definition;
11903
11904 \item \optfmt{same as type}: set the \field{category} to the same
11905 value as the \field{type} field (if that field has been provided
11906 either in the \ext{bib} file or through the \csopt{type} option);
11907
11908 \item \meta{label}: the \field{category} is set to
11909 \meta{label} (which mustn't contain any special characters).
11910 \end{itemize}
11911 This will override any
11912 \field{category} fields supplied in the \ext{bib} file.
11913
11914 When used with \csopt{entry-type-aliases}, the option \csopt[same as
11915 entry]{category} refers to the \emph{target} \gls{entrytype} whereas
11916 \csopt[same as original entry]{category} refers to the
11917 \emph{original} \gls{entrytype} given in the \ext{bib} file. In both
11918 cases, the value is converted to \idx!{lowercase} to ensure consistency.
11919 An alternative is to use \csopt[category]{save-original-entrytype}.
11920 When combined with \csopt[changed]{save-original-entrytype-action}
11921 it's then possible to only set the \field{category} to the original
11922 \gls{entrytype} for aliased entries and leave it unmodified for unaliased
11923 entries.
11924
11925 For example, if the \ext{bib} file contains:
11926 \begin{codeenv}
11927 \atentry{entry}\marg{bird,
11928 \field{name}=\marg{bird},
11929 \field{description} = \marg{feathered animal}
11930 }
11931 \strut
11932 \atentry{index}\marg{duck}
11933 \strut
11934 \atentry{index}\marg{goose,\field{plural}=\qtdelim{geese}}
11935 \strut
11936 \atentry{dualentry}\marg{dog,
11937 \field{name}=\marg{dog},
11938 \field{description}=\marg{chien}
11939 }
11940 \end{codeenv}
11941 then if the document contains:
11942 \begin{codeenv}
11943 \gls{GlsXtrLoadResources}\oarg{\csopt[same as entry]{category},\csopt[entries]{src}}
11944 \end{codeenv}
11945 this will set the \field{category} of the \code{bird} term to \optfmt{entry}
11946 (since it was defined with \atentry{entry}), the \field{category} of the
11947 \code{duck} and \code{goose} terms to \optfmt{index} (since they were defined
11948 with \atentry{index}), and the \field{category} of the \code{dog} term to
11949 \optfmt{dualentry} (since it was defined with \atentry{dualentry}). Note that
11950 the dual entry \code{dual.dog} doesn't have the category set, since that's
11951 governed by \csopt{dual-category} instead.
11952
11953 If, instead, the document contains:
11954 \begin{codeenv}
11955 \gls{GlsXtrLoadResources}\oarg{\csopt[animals]{category},\csopt[entries]{src}}
11956 \end{codeenv}
11957 then the \field{category} of all the \primary\ selected entries will
11958 be set to \optfmt{animals}. Again the \gls{dualentry} \code{dual.dog}
11959 doesn't have the \field{category} set.
11960
11961 Note that the categories may be overridden by the commands that are used to
11962 actually define the entries (such as \gls!{bibglsnewindex}).
11963
11964 For example, if the document contains:
11965 \begin{codeenv}
11966 \cs{newcommand}\marg{\gls{bibglsnewdualentry}}[4]\marg{\comment{}
11967 \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{}
11968 }
11969 \strut
11970 \gls{GlsXtrLoadResources}\oarg{\csopt[animals]{category},\csopt[entries]{src}}
11971 \end{codeenv}
11972 then both the \code{dog} and \code{dual.dog} entries will
11973 have their \field{category} field set to \optfmt{dual} since the
11974 new definition of \gls{bibglsnewdualentry} has overridden
11975 the \csopt[animals]{category} option.
11976
11977 \optsection[\subsubsection]{type}
11978
11979 The \meta{value} may be one of:
11980 \begin{itemize}
11981 \item \optfmt{false}: switches off this setting (default);
11982
11983 \item \optfmt{same as entry}: set the \field{type} field
11984 to the \gls{entrytype} (\idx!{lowercase} and without the initial \code{@});
11985
11986 \item \optfmt{same as original entry}: set the \field{type}
11987 to the original \gls{entrytype} (\idx!{lowercase} and without
11988 the initial \code{@}) before it was aliased (behaves like
11989 \optfmt{same as entry} if the \gls{entrytype} wasn't aliased);
11990
11991 \optfmt{same as base}: set the \field{type} field
11992 to the base name of the corresponding \ext{bib} file
11993 (without the extension);
11994
11995 \item \optfmt{same as category}: set the \field{type} field
11996 to the same value as the \field{category} field
11997 (\field{type} unchanged if \field{category} not set);
11998
11999 \item \optfmt{same as parent}: sets the \field{type} to the same as
12000 the entry's \parent\ (new to v1.9). If the entry doesn't have a
12001 \parent\ or if the \parent\ doesn't have the \field{type} field set, then
12002 no change is made. Entries should always have the same type
12003 as their \parent, but it's possible for spawned entries to
12004 pick up the \field{type} field from their \igls{progenitor} entry
12005 (if it was explicitly set in the \ext{bib} file),
12006 which may be inappropriate.
12007
12008 \item\meta{label}: sets the \field{type} field to the glossary
12009 identified by \meta{label}.
12010 \end{itemize}
12011 When used with \csopt{entry-type-aliases}, the option \csopt[same as
12012 entry]{type} refers to the \emph{target} \gls{entrytype} and \csopt[same
12013 as original entry]{type} refers to the \emph{original} \gls{entrytype}
12014 given in the \ext{bib} file.
12015 An alternative is to use \csopt[type]{save-original-entrytype}.
12016 When combined with \csopt[changed]{save-original-entrytype-action}
12017 it's then possible to only set the \field{type} to the original
12018 \gls{entrytype} for aliased entries and leave it unmodified for unaliased
12019 entries.
12020
12021 \begin{important}
12022 It's not possible to have both
12023 \csopt[same as type]{category} and \csopt[same as category]{type}.
12024 \end{important}
12025
12026 Note that this setting only changes the \field{type} field for
12027 \glspl{primaryentry}. Use \csopt{dual-type} for \glspl{dualentry}.
12028
12029 For example:
12030 \begin{codeenv}
12031 \cmd{usepackage}[\styopt{record},\styopt{symbols}]\marg{glossaries-extra}
12032 \strut
12033 \gls{GlsXtrLoadResources}\oarg{\csopt[entries-symbols]{src},\csopt[symbols]{type}}
12034 \end{codeenv}
12035
12036 Make sure that the glossary type has already been defined
12037 (see \sectionref{sec:newglossary}). In the above, the
12038 \styopt{symbols} option defines the \code{symbols} glossary.
12039 If you want to use a custom glossary, you need to provide it. For
12040 example:
12041 \begin{codeenv}
12042 \cmd{usepackage}[\styopt{record},\styopt{nomain}]\marg{glossaries-extra}
12043 \strut
12044 \cs{newglossary*}\marg{dictionary}\marg{Dictionary}
12045 \strut
12046 \gls{GlsXtrLoadResources}\oarg{\csopt[entries-symbols]{src},\csopt[dictionary]{type}}
12047 \end{codeenv}
12048 (The \styopt{nomain} option was added to suppress the
12049 creation of the default \mainglossary.)
12050
12051 \optsection[\subsubsection]{ignored-type}
12052
12053 Any entry that only has \iglspl{ignoredrecord} will still be
12054 identified as having a record for selection purposes, which is
12055 necessary for the entry to be defined in the document, but it may be
12056 preferable to move such entries to a special \igls{ignoredglossary}.
12057 This can be done with \csopt[\meta{type}]{ignored-type}, where
12058 \meta{type} is the label of the \igls{ignoredglossary}.
12059
12060 The glossary will be provided with
12061 \ics{provideignoredglossary} to ensure that it's
12062 defined even if \longarg{no-provide-glossaries} is set
12063 (see \sectionref{sec:newglossary}).
12064 Note that it uses the unstarred \ics{provideignoredglossary}
12065 since it's assumed that it won't be needed in a list and
12066 therefore won't have a target. This is different to all the other
12067 settings that provide an \gls{ignoredglossary}, which use the
12068 starred version instead.
12069
12070 This option is not implemented for entries that have \emph{no} records
12071 (those entries may have been selected because they are dependent on
12072 another entry, such as a parent of a recorded child entry). The entry
12073 must have at least one \gls{ignoredrecord} and
12074 no other type of record and not be dependent on other entries or be
12075 cross-referenced by other entries.
12076
12077 Note that the \csopt{trigger-type} option, if set, overrides the
12078 \csopt{ignored-type} option for entries that have records with the
12079 special format \ics{glstriggerrecordformat} (which is also
12080 considered an \gls{ignoredrecord}). However, \csopt{ignored-type}
12081 will override the \csopt{type}, \csopt{dual-type},
12082 \csopt{tertiary-type} and the type specification in
12083 \csopt{secondary}.
12084
12085 Ignored entries may be copied to another glossary
12086 with \csopt{copy-to-glossary}. If this is undesirable, a condition
12087 may be applied to prevent it. For example, to copy all selected
12088 entries to the glossary labelled \qt{index} except for ignored
12089 entries:
12090 \begin{codeenv}
12091 \gls{GlsXtrLoadResources}\oarg{
12092 \csopt[\marg{terms,abbreviations}]{src}
12093 \csopt[ignored]{ignored-type},
12094 \csopt[\qtdelim{index} \oarg{ \field{type} \idx{notequalscmp} \qtdelim{ignored} }]{copy-to-glossary}
12095 }
12096 \end{codeenv}
12097
12098 \optsection[\subsubsection]{trigger-type}
12099
12100 The record counting commands, such as \gls{rgls}, use the special
12101 format \ics{glstriggerrecordformat}, which \bibgls\ also treats
12102 as an \igls{ignoredrecord}. This means the entry will still be
12103 identified as having a record for selection purposes, which is
12104 necessary for the entry to be defined for use in the document, but
12105 in order to prevent it from appearing in the glossary you need to
12106 transfer the entry with \csopt[\meta{type}]{trigger-type}.
12107 This will override the \csopt{type}, \csopt{dual-type},
12108 \csopt{tertiary-type} and the type specification in
12109 \csopt{secondary}.
12110
12111 The provided value \meta{type} must be a glossary label (not one of
12112 the keywords allowed by \csopt{type}) or \code{false} to switch
12113 off this setting.
12114 You can define the glossary before loading the resource, but
12115 it's not required as \bibgls\ will write
12116 \code{\ics{provideignoredglossary*}\margm{type}} to the \ext{glstex} file
12117 even if \longarg{no-provide-glossaries} is set
12118 (see \sectionref{sec:newglossary}).
12119
12120 \optsection[\subsubsection]{progenitor-type}
12121
12122 This sets the default \field{type} field for the
12123 \glsdisp{mainentry}{main term} defined by
12124 \atentry{progenitor}-like entries. The \meta{value} is as for
12125 \csopt{type}. This doesn't change the \field{type} for the spawned
12126 \gls{progeny}.
12127
12128 \optsection[\subsubsection]{progeny-type}
12129
12130 This sets the default \field{type} field for the \gls{progeny} term
12131 spawned by \atentry{progenitor}-like entries. The \meta{value} is as
12132 for \csopt{type}. This doesn't change the \field{type} for the
12133 \glsdisp{mainentry}{main} \gls{progenitor}. Remember that with the
12134 default \csopt[parent]{adopted-parent-field} setting, the given type
12135 should match the type of the \gls{parententry}.
12136
12137 \optsection[\subsubsection]{adopted-parent-field}
12138
12139 This identifies the target field to be set to the corresponding
12140 value of the \field{adoptparents} list by the \gls{progeny}
12141 entries spawned by the \atentry{progenitor} type of entry.
12142 The default is \field{parent}.
12143
12144 \optsection[\subsubsection]{ignore-fields}
12145
12146 \begin{important}
12147 Take care not to confuse \csopt{ignore-fields} with \csopt{omit-fields}.
12148 The argument of \csopt{ignore-fields} is a simple list of field names.
12149 \end{important}
12150
12151 The \csopt{ignore-fields} key indicates that you want \bibgls\ to
12152 skip the fields listed in the supplied comma-separated \meta{list} of field
12153 labels. Remember that unrecognised fields will always be skipped.
12154 However, an unrecognised field can still be referenced with some
12155 options (such as \csopt{replicate-fields}) whereas any field
12156 excluded with \csopt{ignore-fields} will be discarded and can't be
12157 referenced.
12158
12159 This setting is always implemented after \csopt{field-aliases} (see
12160 \sectionref{sec:resourcesets}). If a field has been aliased then the
12161 original field name is no longer present and so ignoring it will
12162 have no effect.
12163
12164 For example, suppose my \ext{bib} file contains:
12165 \begin{codeenv}
12166 \atentry{abbreviation}\marg{html,
12167 \field{short} =\qtdelim{html},
12168 \field{long} = \marg{hypertext markup language},
12169 \field{description}=\marg{a markup language for creating web pages},
12170 \field{seealso}=\marg{xml}
12171 }
12172 \end{codeenv}
12173 but I want to use the \abbrstyle{short-long} style and I don't want
12174 the cross-referenced term, then I can use
12175 \csopt[seealso,description]{ignore-fields}.
12176
12177 Note that \csopt[parent]{ignore-fields} removes the \field{parent}
12178 before determining the dependency lists. This means that
12179 \csopt[recorded and deps]{selection} and
12180 \csopt[recorded and ancestors]{selection} won't pick up the
12181 label in the \field{parent} field.
12182
12183 If you want to maintain the dependency and \gls{ancestor} relationship but
12184 omit the \field{parent} field when writing the entries to the
12185 \ext{glstex} file, you need to use \csopt{flatten} instead.
12186 Alternatively, you can use \csopt{omit-fields}, however the hierarchical structure
12187 will continue to be maintained.
12188
12189 The \csopt{ignore-fields} instruction removes the unwanted fields
12190 early in the Stage~3 process (see \sectionref{sec:resourcesets}).
12191 This means that those field values won't be available if they are referenced
12192 nor can they be used to establish dependencies.
12193 If fields should be omitted from the \ext{glstex} file but the field values should
12194 still be available to \bibgls, then use \csopt{omit-fields} instead.
12195
12196 \optsection[\subsubsection]{omit-fields}
12197
12198 \begin{important}
12199 Take care not to confuse \csopt{omit-fields} with \csopt{ignore-fields}.
12200 The argument of \csopt{omit-fields} is a complex list of string \glspl{concatenation}.
12201 \end{important}
12202
12203 The \csopt{omit-fields} action takes place in the final stage, at the point where
12204 each entry is written to the \ext{glstex} file. Unlike \csopt{ignore-fields},
12205 the fields aren't removed from \bibgls's own internal data structure. This means that the fields
12206 can be referenced in other options and will be parsed as usual for dependencies.
12207
12208 If set, the \meta{list} argument is a list of string \glspl{concatenation} with
12209 optional conditionals. Take care that constant strings are correctly delimited
12210 to ensure that they are not mistaken for references to field values.
12211 Note that this is different from \csopt{ignore-fields}, which simply requires
12212 a list of field names.
12213 For example, to omit the \field{description} field for all entries:
12214 \begin{codeenv}
12215 \csopt[\qtdelim{description}]{omit-fields}
12216 \end{codeenv}
12217
12218 Each identified field is simply omitted when writing the field list in the \ext{glstex} file.
12219 However, this may trigger a fallback if the field is required. This option only
12220 applies to fields that have a corresponding key that may be used in commands such
12221 as \gls{newglossaryentry}. The option does not apply to special internal fields.
12222 Any fields identified in the given list that are not recognised will be ignored.
12223
12224 When each entry definition is being written to the \ext{glstex} file, the supplied
12225 \meta{list} is evaluated for the current entry. Each non-empty non-null result
12226 will be added to a temporary set of exclusion field names. Then each \keyval\ for the current
12227 entry will be written to the \ext{glstex} for each known \meta{key} that has the
12228 corresponding field set where the \meta{key} is not included in the exclusion set.
12229
12230 Suppose the file \filefmt{abbrv.bib} contains:
12231 \begin{codeenv}
12232 \atentry{abbreviation}\marg{ssi,
12233 \field{short}=\marg{SSI},
12234 \field{long}=\marg{server-side includes},
12235 \field{description}=\marg{a simple interpreted server-side
12236 scripting language}
12237 }
12238 \atentry{abbreviation}\marg{html,
12239 \field{short}=\marg{HTML},
12240 \field{long}=\marg{hypertext markup language},
12241 \field{description}=\marg{a markup language for creating web
12242 pages}
12243 }
12244 \atentry{abbreviation}\marg{shtml,
12245 \field{short}=\marg{SHTML},
12246 \field{long}=\marg{server-side includes enabled hypertext markup language},
12247 \field{description}=\marg{a combination of \cs{gls}\marg{html} and
12248 \cs{gls}\marg{ssi}}
12249 }
12250 \end{codeenv}
12251 With \csopt[description]{ignore-fields}, the \field{description} field will
12252 be removed when the entry is first processed. This means that the
12253 dependencies in the SHTML description field won't be detected.
12254 Whereas with \csopt[\qtdelim{description}]{omit-fields}, the \field{description}
12255 field won't be removed, so it will still be parsed and the dependent entries will
12256 be detected, however the \field{description} field won't be written in the
12257 \ext{glstex} file. In this case, you may want to also use
12258 \csopt{gather-parsed-dependencies} to save a list of the dependent entries.
12259
12260 Remember that literal strings must be quoted with string \glspl{concatenation}.
12261 For example, suppose an entry has been defined as:
12262 \begin{codeenv}
12263 \atentry{index}\marg{nom-fr,
12264 \field{name}=\marg{nom},
12265 \field{description}=\marg{name}
12266 }
12267 \end{codeenv}
12268 In the case of \csopt[\qtdelim{description}]{omit-fields} then this will become:
12269 \begin{codeenv}
12270 \gls{newglossaryentry}\marg{name-fr}\marg{
12271 \field{name}=\marg{nom}
12272 }
12273 \end{codeenv}
12274 Whereas \csopt[description]{omit-fields} returns \emph{the value of} the
12275 \field{description} field. For the above example entry, the value of
12276 the \field{description} field is \qt{name}, so \field{name} is added to the exclusion set
12277 and so won't be written whilst \bibgls\ iterates over the \qt{name-fr} list of fields.
12278
12279 This means that the \field{name} field will be flagged
12280 as not written to the \ext{glstex} file. In the case of \atentry{index}, this
12281 means that the fallback for the \field{name} field will be used, which is
12282 the entry label. The result will therefore end up as:
12283 \begin{codeenv}
12284 \gls{newglossaryentry}\marg{name-fr}\marg{
12285 \field{description}=\marg{name},
12286 \field{name}=\marg{name-fr}
12287 }
12288 \end{codeenv}
12289 In this case, the \field{description} field value just happens to be the name of
12290 another recognised field. Mostly, this type of error would likely result
12291 in a string that doesn't match any known field, which will trigger a warning.
12292
12293 Conditions may also be applied. For example, to omit the \field{description}
12294 field for any entries defined with \atentry{abbreviation}:
12295 \begin{codeenv}
12296 \csopt[
12297 \qtdelim{description} \oarg{entrytype \idx{follow} actual = \qtdelim{abbreviation}}
12298 ]{omit-fields}
12299 \end{codeenv}
12300
12301 \optsection[\subsubsection]{omit-fields-missing-field-action}
12302
12303 This option indicates what to do if a source field identified in
12304 \csopt{omit-fields} is missing. The value may be one of:
12305 \begin{itemize}
12306 \item \optfmt{skip}: return null;
12307 \item \optfmt{fallback}: use the fallback for the missing field
12308 (see \sectionref{sec:fallbacks}), if
12309 one is available, otherwise return null (default);
12310 \item \optfmt{empty}: treat the missing value as empty.
12311 \end{itemize}
12312 Returning null or empty skips the string \gls{concatenation} element from the
12313 omision list.
12314
12315 \optsection[\subsubsection]{field-aliases}
12316
12317 You can instruct \bibgls\ to treat one field as though it
12318 was another using this option. The value should be a comma-separated
12319 list of \meta{field1}\dequals\meta{field2} pairs, where
12320 \meta{field1} and \meta{field2} are field names. Identical
12321 mappings and trails aren't permitted. (That is, \meta{field1}
12322 and \meta{field2} can't be the same nor can you have both
12323 \meta{field1}\dequals\meta{field2} and
12324 \meta{field2}\dequals\meta{field3}.) If you want to swap
12325 fields you need to use one of the dual \glspl{entrytype} instead.
12326 Field aliases are performed before \csopt{ignore-fields},
12327 so if \meta{field1} is listed in \csopt{ignore-fields} it won't
12328 be ignored (unless \meta{field2} is in \csopt{ignore-fields}).
12329
12330 For example, suppose \filefmt{people.bib} contains:
12331 \begin{codeenv}
12332 \atentry{entry}\marg{alexander,
12333 \field{name}=\marg{Alexander III of Macedon},
12334 \field{description}=\marg{Ancient Greek king of Macedon},
12335 \fieldfmt{born}=\marg{20 July 356 BC},
12336 \fieldfmt{died}=\marg{10 June 323 BC},
12337 \fieldfmt{othername}=\marg{Alexander the Great}
12338 }
12339 \end{codeenv}
12340 This contains three non-standard fields: \fieldfmt{born},
12341 \fieldfmt{died} and \fieldfmt{othername}. I could define
12342 these fields using \ics{glsaddkey}, but another possibility
12343 is to map these onto the user keys \field{user1}, \field{user2}
12344 and \field{user3}, which saves the overhead of providing new
12345 keys:
12346 \begin{codeenv}
12347 \gls{GlsXtrLoadResources}\oarg{
12348 \csopt[people]{src},\comment{data in people.bib}
12349 \csopt[\fieldfmt{born}=\field{user1},\fieldfmt{died}=\field{user2},\fieldfmt{othername}=\field{user3}]{field-aliases}
12350 }
12351 \end{codeenv}
12352
12353 \optsection[\subsubsection]{replicate-fields}
12354
12355 \begin{important}
12356 Note the difference in syntax between \csopt{replicate-fields} and
12357 \csopt{assign-fields}. Both have a \keyvallist\ as the option
12358 argument, but the \keyval\ syntax is different. In the case of
12359 \csopt{replicate-fields}, the left hand side (\meta{key}) is the
12360 \emph{source} field. The right hand side (\meta{value}) is a
12361 comma-separated list of \emph{destination} fields. The value of the
12362 source field will be copied into each of the destination fields.
12363 In the case of \csopt{assign-fields}, the left hand side
12364 (\meta{key}) is the \emph{destination} field and the right hand side
12365 \emph{value} is an assignment expression with an optional
12366 conditional.
12367 \end{important}
12368
12369 The value of one field can be copied to other fields using
12370 this option where each \keyval\ pair is in the form
12371 \code{\meta{field1}\dequals\marg{\meta{field2},\meta{field3},\ldots}}
12372 where all values are field names. The value is required for this key
12373 but may be empty, which indicates that the setting is switched off.
12374
12375 This option copies the contents
12376 of \meta{field1} to \meta{field2}, \meta{field3}, \ldots\
12377 (but only if the target field isn't already set with
12378 \csopt[false]{replicate-override}). This action is
12379 performed after \csopt{ignore-fields} (see
12380 \sectionref{sec:resourcesets}). If the source field is missing, the
12381 \csopt{replicate-missing-field-action} setting determines the
12382 action.
12383
12384 If the target field doesn't have an associated key recognised by
12385 \gls{newglossaryentry} then the value will be saved using
12386 \cs{GlsXtrSetField}. Special internal fields aren't permitted as
12387 either source or target fields.
12388
12389 For example, suppose \filefmt{people.bib} contains:
12390 \begin{codeenv}
12391 \atentry{entry}\marg{alexander,
12392 \field{name}=\marg{Alexander III of Macedon (Alexander the Great)},
12393 \field{text}=\marg{Alexander},
12394 \field{description}=\marg{Ancient Greek king of Macedon}
12395 }
12396 \end{codeenv}
12397 Since the \field{first} field hasn't been supplied, it
12398 will default to the value of the \field{text} field, but
12399 perhaps for one of my documents I'd like the \field{first}
12400 field to be the same as the \field{name} field. Rather than
12401 editing the \ext{bib} file, I can just do:
12402 \begin{codeenv}
12403 \gls{GlsXtrLoadResources}\oarg{
12404 \csopt[people]{src},\comment{data in people.bib}
12405 \csopt[\field{name}=\field{first}]{replicate-fields}
12406 }
12407 \end{codeenv}
12408 This copies the contents of the \field{name} field into the
12409 \field{first} field. If you have more than one field
12410 in the list take care to brace the lists to avoid confusion.
12411 For example, if for some reason I want to copy the value
12412 of the \field{name} field to both \field{first} and
12413 \field{firstplural} and copy the value of the \field{text}
12414 field to the \field{plural} field, then this requires braces
12415 for the inner list:
12416 \begin{codeenv}
12417 \gls{GlsXtrLoadResources}\oarg{
12418 \csopt[people]{src},\comment{data in people.bib}
12419 \csopt[\field{name}=\marg{\field{first},\field{firstplural}},\field{text}=\field{plural}]{replicate-fields}
12420 }
12421 \end{codeenv}
12422
12423 If my \filefmt{people.bib} file instead contained:
12424 \begin{codeenv}
12425 \atentry{entry}\marg{alexander,
12426 \field{name}=\marg{Alexander III of Macedon (Alexander the Great)},
12427 \field{first}=\marg{Alexander the Great},
12428 \field{text}=\marg{Alexander},
12429 \field{description}=\marg{Ancient Greek king of Macedon}
12430 }
12431 \end{codeenv}
12432 then:
12433 \begin{codeenv}
12434 \gls{GlsXtrLoadResources}\oarg{
12435 \csopt[people]{src},\comment{data in people.bib}
12436 \csopt[\field{name}=\field{first}]{replicate-fields}
12437 }
12438 \end{codeenv}
12439 won't alter the \field{first} field since \csopt{replicate-fields}
12440 doesn't override existing values by default. You can use
12441 \csopt{replicate-override} to change this. Alternatively, since
12442 \csopt{replicate-fields} is always performed after \csopt{ignore-fields}
12443 it's possible to ignore the \field{first} field which means that the
12444 \field{name} value can then be copied into it:
12445 \begin{codeenv}
12446 \gls{GlsXtrLoadResources}\oarg{
12447 \csopt[people]{src},\comment{data in people.bib}
12448 \csopt[\field{first}]{ignore-fields},
12449 \csopt[\field{name}=\field{first}]{replicate-fields}
12450 }
12451 \end{codeenv}
12452 Note that the ordering within the resource options doesn't
12453 make a difference. The same result occurs with:
12454 \begin{codeenv}
12455 \gls{GlsXtrLoadResources}\oarg{
12456 \csopt[people]{src},\comment{data in people.bib}
12457 \csopt[\field{name}=\field{first}]{replicate-fields},
12458 \csopt[\field{first}]{ignore-fields}
12459 }
12460 \end{codeenv}
12461
12462 \optsection[\subsubsection]{replicate-override}
12463
12464 This is a boolean option. The default setting is
12465 \csopt[false]{replicate-override}. If \optfmt{true},
12466 \csopt{replicate-fields} will override the existing value if the
12467 target field is already set.
12468
12469 \optsection[\subsubsection]{replicate-missing-field-action}
12470
12471 This option indicates what to do if a source field identified in
12472 \csopt{replicate-fields} is missing. The value may be one of:
12473 \begin{itemize}
12474 \item \optfmt{skip}: skip the replication of the missing field
12475 (default);
12476 \item \optfmt{fallback}: use the fallback for the missing field
12477 (see \sectionref{sec:fallbacks}), if
12478 one is available (otherwise skip);
12479 \item \optfmt{empty}: make the target field empty.
12480 \end{itemize}
12481
12482 \optsection[\subsubsection]{assign-fields}
12483
12484 \begin{important}
12485 Note the difference in syntax between \csopt{replicate-fields} and
12486 \csopt{assign-fields}, as highlighted in the
12487 \csopt{replicate-fields} section, above. The \csopt{assign-fields}
12488 option is implemented after the \csopt{replicate-fields} option (see
12489 \sectionref{sec:resourcesets}).
12490 \end{important}
12491
12492 The \csopt{assign-fields} option is a more complicated way of setting a
12493 field than \csopt{replicate-fields}. Each \keyval\ element of the
12494 \keyvallist\ argument has the syntax:
12495 \begin{codeenv}
12496 \meta{dest-field} \dequals\oargm{override} \meta{element-list} \oargm{condition}
12497 \end{codeenv}
12498 If the destination field (\meta{dest-field}) is already set, it will
12499 only be overwritten if \csopt[true]{assign-override} or if
12500 \oarg{override} is \qtt{o}. The \meta{dest-field} is simply the name
12501 of the field for the entry under consideration and doesn't use the
12502 more complex \meta{field-ref} syntax used in \meta{element-list},
12503 which is described in \sectionref{sec:optstringconcat}.
12504 You can, however, use the \cs{uhex} quark on either side of the
12505 \keyval\ element to indicate a Unicode character.
12506
12507 The \oargm{override} following the equal sign is optional and may be
12508 used to counteract the \csopt{assign-override} setting for the given
12509 assignment. The \meta{override} value may be either \qtt{o}
12510 (override) or \qtt{n} (no override). If not present, the
12511 \csopt{assign-override} setting will be used.
12512
12513 The \meta{element-list} is a string \gls{concatenation}, as
12514 described in \sectionref{sec:optstringconcat}. If any individual
12515 element in the list evaluates to null, the entire string is deemed
12516 to be null, in which case the assignment won't be made.
12517
12518 The \oargm{condition} part is optional. If present, the assignment
12519 is only made if the condition evaluates to true. The condition
12520 should be placed in square brackets after the \meta{element-list}
12521 part. This is a complex conditional, as described in
12522 \sectionref{sec:conditionals}.
12523
12524 Note that, unlike most \keyval\ options, the value part
12525 (\meta{element-list} \oargm{condition}) should not be grouped. The
12526 \csopt{assign-fields} option is parsed in a different way to the
12527 other \keyvallist\ options. However, it's best to group the \emph{entire}
12528 \meta{value} argument of \csopt{assign-fields}. For example:
12529 \begin{codeenv}
12530 \csopt[
12531 \field{name} \idx{equalsassign} \field{text} \idx{concat-plus} \qtdelim{, } \idx{concat-plus} \field{symbol}
12532 ]{assign-fields}
12533 \end{codeenv}
12534 Don't do \code{\field{name} \idx{equalsassign} \marg{\field{text}
12535 \idx{concat-plus} \qtdelim{, } \idx{concat-plus} \field{symbol}}}.
12536
12537 \begin{important}
12538 Remember that field values may be altered before or after
12539 \csopt{assign-fields} by other resource options (see
12540 \sectionref{sec:resourcesets}). The assignment will use the value
12541 current at the time it is referenced during the processing of
12542 \csopt{assign-fields}. If you need to reference the destination
12543 field in the assignment, make sure that the override setting is on
12544 if the field needs to be updated.
12545 \end{important}
12546
12547 For example, suppose I have defined the custom fields
12548 \fieldfmt{surname} and \fieldfmt{forename}, and I have the following
12549 in my \ext{bib} file:
12550 \begin{codeenv}
12551 \atentry{index}\marg{Smith}
12552 \atentry{index}\marg{Jane-Smith,
12553 \fieldfmt{forename}=\marg{Jane},
12554 \field{parent}=\marg{Smith}
12555 }
12556 \end{codeenv}
12557 Suppose that what I actually want is:
12558 \begin{codeenv}
12559 \atentry{index}\marg{Smith}
12560 \atentry{index}\marg{Jane-Smith,
12561 \fieldfmt{forename}=\marg{Jane},
12562 \fieldfmt{surname}=\marg{Smith},
12563 \field{parent}=\marg{Smith},
12564 \field{name}=\marg{Jane},
12565 \field{text}=\marg{Jane Smith}
12566 }
12567 \end{codeenv}
12568 This is quite repetitive to type out for every person you need to
12569 index. The \csopt{replicate-fields} option can reduce some of this.
12570 For example:
12571 \begin{codeenv}
12572 \csopt{replicate-fields}=\marg{
12573 \fieldfmt{forename}=\marg{name},
12574 \fieldfmt{surname}=\marg{parent}
12575 }
12576 \end{codeenv}
12577 This doesn't deal with the \field{text} field and also has a problem
12578 if the \field{parent} field (which should contain a label) doesn't
12579 match the surname. For example, I might also have:
12580 \begin{codeenv}
12581 \atentry{index}\marg{de-la-Fontaine,
12582 \field{name}=\marg{de la Fontaine}
12583 }
12584 \atentry{index}\marg{Margaret-de-la-Fontaine,
12585 \fieldfmt{forename}=\marg{Margaret},
12586 \field{parent}=\marg{de-la-Fontaine}
12587 }
12588 \end{codeenv}
12589 In this case the custom \fieldfmt{surname} field needs to match the
12590 parent's \field{name} field, not the parent's label.
12591
12592 The desired result can instead be obtained with:
12593 \begin{codeenv}
12594 \csopt{assign-fields}=\marg{
12595 \fieldfmt{surname} = parent \idx{follow} \field{name},
12596 \field{name} = self \idx{follow} \fieldfmt{forename},
12597 \field{text} = self \idx{follow} \fieldfmt{forename}
12598 \idx{concat-plus} \qtdelim{ } \idx{concat-plus} self \idx{follow} \fieldfmt{surname}
12599 }
12600 \end{codeenv}
12601 The \code{self \idx{follow}} part is optional so this can be written
12602 more compactly as:
12603 \begin{codeenv}
12604 \csopt{assign-fields}=\marg{
12605 \fieldfmt{surname} = parent \idx{follow} \field{name},
12606 \field{name} = \fieldfmt{forename},
12607 \field{text} = \fieldfmt{forename} \idx{concat-plus} \qtdelim{ } \idx{concat-plus} \fieldfmt{surname}
12608 }
12609 \end{codeenv}
12610 The last assignment in the above can also be written as:
12611 \begin{codeenv}
12612 \field{text} = \fieldfmt{forename} \idx{concat-plus} \marg{ } \idx{concat-plus} \fieldfmt{surname}
12613 \end{codeenv}
12614 Suppose, for some reason, I want the first use to show the surname
12615 in bold. This means I need to add
12616 \code{\cs{textbf}\idx{bgroupchar}} before the value of the
12617 surname field and the closing \idx{egroupchar} needs to go after.
12618 This can be achieved with:
12619 \begin{codeenv}
12620 \field{first} = \fieldfmt{forename} \idx{concat-plus} \qtdelim{ \cs{textbf}\idx{bgroupchar}} \idx{concat-plus} \fieldfmt{surname} \qtdelim{\idx{egroupchar}}
12621 \end{codeenv}
12622 Note that because there are unbalanced braces in the string
12623 fragments, it's necessary to use quote delimiters. Since \cs{textbf}
12624 is robust, there's no need to protect it from expansion.
12625
12626 Suppose, instead, I want the surname in \idx{uppercase} on first
12627 use. I could simply replace \cs{textbf} with \cs{MakeUppercase}, but
12628 I can get \bibgls\ to do the case-conversion instead:
12629 \begin{codeenv}
12630 \field{first} = \fieldfmt{forename} \idx{concat-plus} \qtdelim{ } \idx{concat-plus} \gls{UC}\marg{ \fieldfmt{surname} }
12631 \end{codeenv}
12632 This assumes that \ics{GlsXtrResourceInitEscSequences} has been
12633 added to the definition of \cs{glsxtrresourceinit}, as described in
12634 \sectionref{sec:quarks}. Otherwise you would need to protect \gls{UC}.
12635
12636 In the above example, the \fieldfmt{surname} field is obtained from
12637 the value of the parent's \field{name} according to the assignment:
12638 \begin{codeenv}
12639 \fieldfmt{surname} = parent \idx{follow} \field{name},
12640 \end{codeenv}
12641 In the case of the Smith entry, the \field{name} field hasn't been
12642 set.
12643
12644 If a referenced field hasn't been set then the behaviour depends on
12645 the \csopt{assign-missing-field-action} setting. The default
12646 behaviour is to use the fallback, if provided (see
12647 \sectionref{sec:fallbacks}). In the case of \atentry{index}, the
12648 fallback for the \field{name} field is the entry's label. This means
12649 that the Jane-Smith entry will have the \fieldfmt{surname} field set
12650 to \qt{Smith}.
12651
12652 If the fallback isn't set or if there is no fallback then the
12653 assignment instruction will be skipped. Similarly, if an ancestor is
12654 referenced but doesn't exist then assignment will again be skipped.
12655
12656 \begin{important}
12657 The ancestor entries must be defined first to ensure that they have
12658 been processed and have had their fields set before they can be
12659 referenced in an assignment.
12660 \end{important}
12661
12662 Since I haven't imposed any conditions on the assignments, the
12663 instructions will be attempted on all entries. This includes the
12664 parent entries.
12665
12666 The first instruction attempts to set the \fieldfmt{surname} field
12667 to the parent's \field{name}. Neither the Smith nor the
12668 de-la-Fontaine entries have a parent entry, so this instruction is
12669 skipped for both of them.
12670
12671 The second instruction attempts to set the \field{name} field to the
12672 entry's \fieldfmt{forename} field. The de-la-Fontaine entry already
12673 has the \field{name} field set so the instruction is automatically
12674 skipped (because of the default \csopt[false]{assign-override}).
12675 The Smith entry doesn't have the \field{name} field set so the
12676 assignment will be attempted but will fail because the
12677 \fieldfmt{forename} field isn't set and doesn't have a fallback.
12678
12679 The \field{text} (and \field{first}) instruction similarly
12680 references the \fieldfmt{forename} field, which isn't set, so the
12681 instruction is skipped. The instruction also contains a reference to
12682 the \fieldfmt{surname} field, but that part of the assignment isn't
12683 reached as the attempt stops at the first unset reference.
12684
12685 This means that neither the Smith not the de-la-Fontaine entries
12686 will be affected by the above \csopt{assign-fields} setting.
12687
12688 Each instruction will be attempted, in turn, unless the \csopt{assign-override}
12689 setting prevents it. This means it's possible to have multiple
12690 assignments for a particular field. The first one that succeeds will
12691 be the one that has effect (with \csopt[false]{assign-override}).
12692 For example:
12693 \begin{codeenv}
12694 \csopt{assign-fields}=\marg{
12695 \fieldfmt{surname} = parent \idx{follow} \field{name},
12696 \fieldfmt{surname} = \field{name},
12697 \field{name} = \fieldfmt{forename},
12698 \field{text} = \fieldfmt{forename} \idx{concat-plus} \qtdelim{ } \idx{concat-plus} \fieldfmt{surname}
12699 }
12700 \end{codeenv}
12701 This has two instructions for the \fieldfmt{surname}. The first one
12702 will be applied to entries that have a parent and the second one
12703 will be applied to the other entries (that don't already have the
12704 \fieldfmt{surname} set).
12705
12706 Suppose I also have some monarchs, who are more typically only
12707 referred to by their forename (with no surname), possibly prefixed by their rank and
12708 suffixed by their ordinal. Let's further suppose that in my document
12709 I have also defined the custom fields \fieldfmt{rank} and
12710 \fieldfmt{ordinal}, and in my \ext{bib} file I have:
12711 \begin{codeenv}
12712 \atentry{indexplural}\marg{king}
12713 \atentry{indexplural}\marg{queen}
12714 \atentry{indexplural}\marg{empress,\field{plural}=\marg{empresses}}
12715 \strut
12716 \atentry{index}\marg{King-Stephen,
12717 \field{parent}=\marg{king},
12718 \fieldfmt{forename}=\marg{Stephen}
12719 }
12720 \atentry{index}\marg{Empress-Matilda,
12721 \field{parent}=\marg{empress},
12722 \fieldfmt{forename}=\marg{Matilda},
12723 }
12724 \atentry{index}\marg{Elizabeth-I,
12725 \field{parent}=\marg{queen},
12726 \fieldfmt{forename}={Elizabeth},
12727 \fieldfmt{ordinal}={I}
12728 }
12729 \end{codeenv}
12730 The earlier assignment rules won't be appropriate for these cases,
12731 as they would result in the \field{text} fields: \qt{Stephen kings},
12732 \qt{Matilda empresses} and \qt{Elizabeth queens}.
12733
12734 In this case, the assignment rules need to depend on the type of
12735 entry. I could test if the parent label is \qt{king} or \qt{empress}
12736 or \qt{queen}, but a more reliable approach is to have custom entry
12737 types which can be aliased:
12738
12739 \begin{codeenv}
12740 \atentry{index}\marg{Smith}
12741 \atentryfmt{person}\marg{Jane-Smith,
12742 \fieldfmt{forename}=\marg{Jane},
12743 \field{parent}=\marg{Smith}
12744 }
12745 \atentry{index}\marg{de-la-Fontaine,
12746 \field{name}=\marg{de la Fontaine}
12747 }
12748 \atentryfmt{person}\marg{Margaret-de-la-Fontaine,
12749 \fieldfmt{forename}=\marg{Margaret},
12750 \field{parent}=\marg{de-la-Fontaine}
12751 }
12752 \strut
12753 \atentry{indexplural}\marg{king}
12754 \atentry{indexplural}\marg{queen}
12755 \atentry{indexplural}\marg{empress,\field{plural}=\marg{empresses}}
12756 \strut
12757 \atentryfmt{monarch}\marg{King-Stephen,
12758 \field{parent}=\marg{king},
12759 \fieldfmt{forename}=\marg{Stephen}
12760 }
12761 \atentryfmt{monarch}\marg{Empress-Matilda,
12762 \field{parent}=\marg{empress},
12763 \fieldfmt{forename}=\marg{Matilda},
12764 }
12765 \atentryfmt{monarch}\marg{Elizabeth-I,
12766 \field{parent}=\marg{queen},
12767 \fieldfmt{forename}={Elizabeth},
12768 \fieldfmt{ordinal}={I}
12769 }
12770 \end{codeenv}
12771 The resource options are now:
12772 \begin{codeenv}
12773 \csopt[person=index,monarch=index]{entry-type-aliases},
12774 \csopt[
12775 \field{name} = \fieldfmt{forename} \idx{concat-plus} \qt{\idx{nbspchar}} \fieldfmt{ordinal},
12776 \field{name} = \fieldfmt{forename},
12777 \fieldfmt{surname} = parent \idx{follow} \field{name}
12778 \oarg{ entrytype \idx{follow} original \idx{equalscmp} \qtdelim{person} },
12779 \field{text} = \fieldfmt{forename} \idx{concat-plus} \qtdelim{ } \idx{concat-plus} \fieldfmt{surname}
12780 \oarg{ entrytype \idx{follow} original \idx{equalscmp} \qtdelim{person} },
12781 \field{first} = \gls{FIRSTUC} \marg{ parent \idx{follow} \field{text} } \idx{concat-plus} \qtdelim{ } \idx{concat-plus} \fieldfmt{name}
12782 \oarg{ entrytype \idx{follow} original \idx{equalscmp} \qtdelim{monarch} },
12783 \field{text} = \fieldfmt{name}
12784 \oarg{ entrytype \idx{follow} original \idx{equalscmp} \qtdelim{monarch} }
12785 ]{assign-fields}
12786 \end{codeenv}
12787
12788 Additional fields can be added to accommodate nicknames or other
12789 forms of address, which will add to the complexity of the assignment
12790 specification.
12791
12792 \optsection[\subsubsection]{assign-override}
12793
12794 This is a boolean option. The default setting is
12795 \csopt[false]{assign-override}. If \optfmt{true},
12796 \csopt{assign-fields} will override the existing value if the
12797 target field is already set.
12798
12799 \optsection[\subsubsection]{assign-missing-field-action}
12800
12801 This option indicates what to do if a source field identified in
12802 \csopt{assign-fields} is missing. The value may be one of:
12803 \begin{itemize}
12804 \item \optfmt{skip}: skip the assignment;
12805 \item \optfmt{fallback}: use the fallback for the missing field
12806 (see \sectionref{sec:fallbacks}), if
12807 one is available, otherwise skip the assignment (default);
12808 \item \optfmt{empty}: treat the missing value as empty.
12809 \end{itemize}
12810 Return null will result in the assignment instruction being omitted.
12811
12812 \optsection[\subsubsection]{counter}
12813
12814 The \csopt{counter} option assigns the default counter to use
12815 for the selected entries. (This can be overridden with the
12816 \glsopt{counter} key when using commands like \cs{gls}.)
12817 The value must be the name of a counter. Since \bibgls\ doesn't know
12818 which counters are defined within the document, there's no check to
12819 determine if the value is valid (except for ensuring that
12820 \meta{value} is non-empty).
12821 A value of \code{false} will switch off this setting (the default).
12822
12823 Note that this will require an extra \LaTeX\ and \bibgls\ call since
12824 the counter can't be used for the indexing until the entry has been
12825 defined.
12826
12827 \optsection[\subsubsection]{copy-action-group-field}
12828
12829 This option may only be used when invoking \bibgls\ with the
12830 \longarg{group} (or \shortargfmt{g}) switch. If an action
12831 other than the default \csopt[define]{action} is set,
12832 this option can be used to identify a field in which to save
12833 the letter group information
12834 where \meta{value} is the name of the field. This just uses
12835 \cs{GlsXtrSetField}. You will need to redefine
12836 \ics{glsxtrgroupfield} to \meta{value} before displaying the glossary.
12837 For example, if \csopt[dupgroup]{copy-action-group-field},
12838 \csopt[copy]{action} and \csopt[copies]{type} are set in
12839 the resource options and \code{copies} identifies a custom
12840 glossary:
12841 \begin{codeenv}
12842 \ics{printunsrtglossary*}\oarg{\printglossopt[copies]{type},\printglossopt[\glostyle{indexgroup}]{style}}
12843 \marg{\cs{renewcommand}\marg{\cs{glsxtrgroupfield}}\marg{dupgroup}}
12844 \end{codeenv}
12845
12846 This option is ignored when used with \csopt[define]{action}.
12847 This option is not used by \csopt{secondary} which will
12848 always save the group information in the \field{secondarygroup}
12849 field. When used with \csopt[define or copy]{action}, entries
12850 that are defined will have both \field{group} and
12851 the field given by \csopt{copy-action-group-field} set.
12852
12853 Note that you may do \csopt[group]{copy-action-group-field} which
12854 will override the \field{group} field from the original definition.
12855 This may be useful if you don't use grouping in the
12856 \gls{primaryglossary}. That is, you use \code{nogroupskip} and a non-group
12857 style. For example:
12858 \begin{codeenv}
12859 \cs{printunsrtglossary}\oarg{\printglossopt{nogroupskip},\printglossopt[\glostyle{index}]{style}}
12860 \cs{printunsrtglossary}\oarg{\printglossopt[copies]{type},\printglossopt[indexgroup]{style}}
12861 \end{codeenv}
12862
12863 \optsection[\subsubsection]{copy-alias-to-see}
12864
12865 If set, the value of the \field{alias} field is copied to
12866 the \field{see} field. The default setting is \csopt[false]{copy-alias-to-see}.
12867
12868 \subsection{Field Adjustments}
12869 \label{sec:fieldmods}
12870
12871 \optsection[\subsubsection]{post-description-dot}
12872
12873 The \styopt{postdot} package option (or \styopt[false]{nopostdot})
12874 can be used to append a \idx{full-stop} (\idx{periodchar})\ to the
12875 end of all the descriptions. This can be awkward if some of the
12876 descriptions end with punctuation characters. This resource option
12877 can be used instead. The \meta{value} may be one of:
12878 \begin{itemize}
12879 \item\optfmt{none}: don't append a \idx{full-stop} (default);
12880 \item\optfmt{all}: append a \idx{full-stop} to all \field{description}
12881 fields in this resource set;
12882 \item\optfmt{check}: selectively append a \idx{full-stop} (see below).
12883 \end{itemize}
12884 Note that if you have dual entries and you use this option to
12885 append a \idx{full-stop}, then it will be copied over to the mapped field.
12886 This is different to the \styopt{postdot} option which doesn't
12887 add the dot to the field but incorporates it in the
12888 \idx{postdescriptionhook}. This means that a dot inserted with
12889 \csopt{post-description-dot} will come before the
12890 \idx{postdescriptionhook} whereas with \styopt{postdot} the
12891 punctuation comes after any category-specific hook.
12892
12893 The \csopt[check]{post-description-dot} setting determines whether
12894 to append the dot as follows:
12895 \begin{itemize}
12896 \item If the \csopt{post-description-dot-exclude} condition
12897 evaluates to true, then a dot isn't appended.
12898 \item If the \field{description} field ends with
12899 \ics{nopostdesc} or \ics{glsxtrnopostpunc}, then a dot isn't appended.
12900 \item If the \field{description} field doesn't end with a regular
12901 (ungrouped letter or other) character, then a dot is appended.
12902 (For example, if the description ends with a control sequence
12903 or an end group token.)
12904 \item If the \field{description} field ends with a character
12905 that belongs to the Unicode category \idx{punctuationclose}
12906 or \idx{punctuationfinalquote} then the token preceding
12907 that character is checked.
12908 \item If the \field{description} field doesn't end with
12909 a character that belongs to the Unicode category
12910 \idx{punctuationother} then the dot is added.
12911 \end{itemize}
12912 Note that the interpreter isn't used during the check.
12913 If the \field{description} ends with a command then a dot will be
12914 appended (unless it's \cs{glsxtrnopostpunc} or \cs{nopostdesc}) even if
12915 that command expands in such a way that it ends with a terminating
12916 punctuation character. This option only applies to the
12917 \field{description} field.
12918
12919 \optsection{post-description-dot-exclude}
12920
12921 The value may either be empty, to indicate false (the default), or a
12922 complex condition using syntax described in
12923 \sectionref{sec:conditionals}. This option is only applicable with
12924 \csopt[check]{post-description-dot}.
12925
12926
12927 \optsection[\subsubsection]{strip-trailing-nopost}
12928
12929 This option is always performed before \csopt{post-description-dot}.
12930 The default setting is \csopt[false]{strip-trailing-nopost}. If \optfmt{true}
12931 any trailing ungrouped \ics{nopostdesc} or \ics{glsxtrnopostpunc} found in the
12932 \field{description} field will be removed. Note that the command (possibly
12933 followed by ignored space) must be at the very end of the description for it to
12934 be removed. A description should not contain both commands. This option only
12935 applies to the \field{description} field.
12936
12937 For example, \cs{nopostdesc} will be stripped from:
12938 \begin{codeenv}
12939 \field{description}=\marg{sample\cs{nopostdesc}}
12940 \end{codeenv}
12941 since it's at the end. It will also be stripped from:
12942 \begin{codeenv}
12943 \field{description}=\marg{sample\cs{nopostdesc} }
12944 \end{codeenv}
12945 since the trailing space is ignored as it follows a control
12946 word. It won't be stripped from:
12947 \begin{codeenv}
12948 \field{description}=\marg{sample\cs{nopostdesc}\marg{} }
12949 \end{codeenv}
12950 because the final space is now significant, but even without the
12951 space it still won't be stripped as the field ends with
12952 an empty group not with \cs{nopostdesc}. Similarly it won't be
12953 stripped from:
12954 \begin{codeenv}
12955 \field{description}=\marg{sample\cs{nopostdesc}\cmd{relax}}
12956 \end{codeenv}
12957 because again it's not at the end.
12958
12959 \optsection[\subsubsection]{check-end-punctuation}
12960
12961 This options checks the end of all the fields given in \meta{list} for
12962 end of sentence punctuation. This is determined as follows, for each
12963 \meta{field} in the comma-separated \meta{list}:
12964 \begin{itemize}
12965 \item if the last character is of type \idx{punctuationclose}
12966 or \idx{punctuationfinalquote}, check the character that comes
12967 before it;
12968 \item if the character is of type \idx{punctuationother}, then check
12969 if it's listed in the entry given by \idx{sentence.terminators}
12970 in \bibgls's \langxml.
12971 \end{itemize}
12972 If a sentence terminator is found, an internal field is created
12973 called \field{fieldendpunc} that contains the punctuation
12974 character. Fields whose values must be labels (such as
12975 \field{parent}, \field{category} and \field{type}) aren't checked,
12976 even if they're included in \meta{list}.
12977
12978 The default \idx{sentence.terminators} is defined in \file{bib2gls-en.xml}
12979 as:
12980 \begin{verbatim}
12981 <entry key="sentence.terminators">.?!</entry>
12982 \end{verbatim}
12983 Any character that isn't of type \idx{punctuationother} won't
12984 match.
12985
12986 For example, the sample \exfile!{books.bib} file contains:
12987 \begin{codeenv}
12988 \atentry{entry}\marg{whydidnttheyaskevans,
12989 \field{name}=\marg{Why Didn't They Ask Evans?},
12990 \field{description}=\marg{novel by Agatha Christie},
12991 \fieldfmt{identifier}=\marg{book},
12992 \fieldfmt{author}=\marg{\gls{sortmediacreator}\marg{Agatha}\marg{Christie}},
12993 \fieldfmt{year}=\marg{1934}
12994 }
12995 \end{codeenv}
12996 With \csopt[name]{check-end-punctuation}, this entry will be
12997 assigned an internal field called
12998 \fielddisp{fieldendpunc}{nameendpunc} set to \code{?}\
12999 as that's included in \idx{sentence.terminators} and is found
13000 at the end of the \field{name} field:
13001 \begin{codeenv}
13002 \cs{GlsXtrSetField}\marg{whydidnttheyaskevans}\marg{nameendpunc}\marg{?}
13003 \end{codeenv}
13004 (Note that \csopt[first,text]{check-end-punctuation} won't match
13005 as there's no \field{first} or \field{text} field supplied.)
13006
13007 If you have a field that ends with an abbreviation followed by a
13008 \idx{full-stop}, this will be considered an end of sentence terminator, but
13009 the main purpose of this option is to provide a way to deal with
13010 cases like:
13011 \begin{codeenv}
13012 Agatha Christie wrote \cs{gls}\marg{whydidnttheyaskevans}.
13013 \end{codeenv}
13014 where the end of sentence punctuation following \cs{gls} needs to be
13015 discarded. This is needed regardless of whether or not
13016 the link text ends with an abbreviation or is a complete sentence.
13017
13018 It's then possible to hook into the \idx{postlinkhook} \qt{discard
13019 period} check. By default this just checks the category attributes
13020 that govern whether or not to discard a following period, but
13021 (with \styfmt{glossaries-extra} v1.23+) it's possible to provide
13022 an additional check by redefining:
13023 \nosecdef{glsxtrifcustomdiscardperiod}
13024 This should expand to \meta{true} if the check should be performed
13025 otherwise it should expand to \meta{false}. You can reference the
13026 label using \cs{glslabel}. For example:
13027 \begin{codeenv}
13028 \cs{renewcommand}*\marg{\gls{glsxtrifcustomdiscardperiod}}[2]\marg{\comment{}
13029 \cs{GlsXtrIfFieldUndef}\marg{nameendpunc}\marg{\cs{glslabel}}\marg{\idx{param}2}\marg{\idx{param}1}\comment{}
13030 }
13031 \end{codeenv}
13032 This uses \ics{GlsXtrIfFieldUndef} rather than
13033 \ics{glsxtrifhasfield*} since there's no need to access the field's
13034 value. (The unstarred form \ics{glsxtrifhasfield} can't be used
13035 as it introduces implicit scoping, which would interfere with the
13036 punctuation lookahead.) The other difference between
13037 \ics{GlsXtrIfFieldUndef} and the other \csfmt{\ldots hasfield} tests
13038 is the case where the field is set to an empty value. In this case
13039 the field is defined (so \ics{GlsXtrIfFieldUndef} does the
13040 \meta{false} argument) but it's considered unset (so commands like
13041 \ics{ifglshasfield} do the \meta{false} argument).
13042
13043 \optsection[\subsubsection]{sort-label-list}
13044
13045 This option takes a list as the value with each element in the list
13046 in the form:
13047 \begin{codeenv}
13048 \code{\meta{field-list}:\meta{sort}:\meta{csname}}
13049 \end{codeenv}
13050 or:
13051 \begin{codeenv}
13052 \code{\meta{field-list}:\meta{sort}}
13053 \end{codeenv}
13054 where:
13055 \begin{itemize}
13056 \item \meta{field-list} is a comma-separated list of valid fields;
13057 \item \meta{sort} is a valid sort method as per the \csopt{sort}
13058 option, but not including \optfmt{none} or \optfmt{unsrt};
13059 \item \meta{csname} is the name (without a leading backslash) of a
13060 command that takes a label as its sole mandatory argument that's
13061 recognised by \bibgls' interpreter (such as those listed in
13062 \tableref{tab:bibglsdefs}).
13063 \end{itemize}
13064 The final \code{:\meta{csname}} part may be omitted if no command
13065 need be applied. (That is, sort by label.) The \meta{list} value
13066 is required for this option but may be empty, which indicates the setting is
13067 switched off.
13068
13069 The sorting options are as those for the \gls{mainlist}. For
13070 example, for entries in the \glsdisp{mainlist}{primary list} the
13071 break point is obtained from the \csopt{break-at} setting and for
13072 entries in the \gls{duallist} the break point is obtained from
13073 \csopt{dual-break-at}. (Remember that if \csopt[combine]{dual-sort}
13074 then there is only one list that contains both the \primary\ and
13075 \dual\ entries, which is governed by the \primary\ options only.)
13076
13077 If the \meta{field-list} has more than one element
13078 take care to use braces \code{\marg{}} to avoid confusion for the
13079 list-parser. For example:
13080 \begin{codeenv}
13081 \gls{GlsXtrLoadResources}\oarg{
13082 \csopt[\marg{see,seealso}:en:glsentryname]{sort-label-list}
13083 }
13084 \end{codeenv}
13085
13086 Note that strange results may occur if this setting is used on any
13087 fields that don't simply contain a list of entry labels or if any of
13088 the referenced entries are processed in different
13089 \iglspl{resourceset} (see \sectionref{sec:resourcesets}).
13090
13091 After the main sorting of each set of selected entries is performed
13092 (as per \csopt{sort} or \csopt{dual-sort}), if this
13093 option is set, then for each
13094 \code{\margm{field-list}:\meta{sort}:\meta{csname}} the following
13095 steps are performed:
13096 \begin{enumerate}
13097 \item For each entry \meta{id}:
13098 \begin{enumerate}
13099 \item For each \meta{field} in \meta{field-list}, if the field is
13100 set for entry \meta{id} then:
13101
13102 \begin{enumerate}
13103 \item The field value must be in the form
13104 \code{\oargm{tag}\meta{label-list}} where
13105 \code{\oargm{tag}} is optional and
13106 \meta{label-list} is a comma-separated list of entry labels
13107 \meta{label$_1$}, \ldots, \meta{label$_n$};
13108 \item A new list is constructed where the $i$th element is:
13109 \code{\marg{\csfmt{}\meta{csname}\margm{label$_i$}}}
13110 unless \meta{csname} hasn't been set, in which case the
13111 $i$th element is just \margm{label$_i$} (the optional
13112 \oargm{tag} part is omitted);
13113 \item This new list is sorted according to the interpreter's
13114 definition of the command given by \meta{csname} (if provided)
13115 and the designated \meta{sort} method;
13116 \item The field value is reconstructed with the labels in the
13117 corresponding order (prefixed with \code{\oargm{tag}} if it was
13118 present in the original).
13119 \end{enumerate}
13120 \end{enumerate}
13121 \end{enumerate}
13122 Note that there is no \hierarchical\ structure in the sorting of the field list
13123 even if any of the referenced entries has a \parent.
13124
13125 For example, suppose the file \filefmt{entries.bib} contains:
13126 \begin{codeenv}
13127 \atentry{index}\marg{bird}
13128 \strut
13129 \atentry{index}\marg{waterfowl, \field{parent}=\marg{bird} }
13130 \strut
13131 \atentry{index}\marg{duck,
13132 \field{parent}=\marg{waterfowl},
13133 \field{seealso}=\marg{swan,duckling,parrot,goose}
13134 }
13135 \strut
13136 \atentry{index}\marg{swan,
13137 \field{parent}=\marg{waterfowl},
13138 \field{seealso}=\marg{goose,duck}
13139 }
13140 \strut
13141 \atentry{index}\marg{goose,
13142 \field{parent}=\marg{waterfowl},
13143 \field{seealso}=\marg{duck}
13144 }
13145 \strut
13146 \atentry{index}\marg{parrot, \field{parent}=\marg{bird} }
13147 \strut
13148 \atentry{index}\marg{duckling,
13149 \field{see}=\marg{[related terms]fluffy,velociraptor,duck,tardigrade}
13150 }
13151 \strut
13152 \atentry{index}\marg{fluffy}
13153 \strut
13154 \atentry{index}\marg{tardigrade, \field{name}=\marg{water bear} }
13155 \strut
13156 \atentry{index}\marg{velociraptor}
13157 \end{codeenv}
13158 And suppose the document contains:
13159 \begin{codeenv}
13160 \cmd{documentclass}\marg{article}
13161 \strut
13162 \cmd{usepackage}[\styopt{record},\styopt[tree]{style}]\marg{glossaries-extra}
13163 \strut
13164 \gls{GlsXtrLoadResources}\oarg{
13165 \csopt[entries]{src},
13166 \csopt[en]{sort},
13167 \csopt[\marg{seealso,see}:en:glsentryname]{sort-label-list}
13168 }
13169 \strut
13170 \cmd{begin}\marg{document}
13171 \cs{Gls}\marg{parrot}, \cs{gls}\marg{tardigrade}, \cs{gls}\marg{swan}, \cs{gls}\marg{duck},
13172 \cs{gls}\marg{goose}, \cs{gls}\marg{fluffy} \cs{gls}\marg{duckling}, \cs{gls}\marg{velociraptor}.
13173 \strut
13174 \cs{printunsrtglossaries}
13175 \cmd{end}\marg{document}
13176 \end{codeenv}
13177 Then this reorders the \field{see} and \field{seealso} fields according to
13178 the referenced entry's name (obtained with \ics{glsentryname}).
13179
13180 For example, the \field{see} field for the \code{duckling} entry was
13181 originally:
13182 \begin{codeenv}
13183 \field{see}=\marg{[related terms]fluffy,velociraptor,duck,tardigrade}
13184 \end{codeenv}
13185 but in the \ext{glstex} file it's written as:
13186 \begin{codeenv}
13187 \field{see}=\marg{[related terms]duck,fluffy,velociraptor,tardigrade}
13188 \end{codeenv}
13189 The reason for \code{tardigrade} being placed after
13190 \code{velociraptor} is because
13191 \code{\ics{glsentryname}\marg{tardigrade}} is expanded to \qt{water
13192 bear} (and \qt{W} comes after \qt{V}). If no encapsulating command
13193 was specified:
13194 \begin{codeenv}
13195 \csopt[\marg{seealso,see}:en]{sort-label-list}
13196 \end{codeenv}
13197 then the list would have been sorted according to the labels
13198 instead (and so \code{tardigrade} would come before
13199 \code{velociraptor}). Note that the optional tag is kept at the start of the
13200 list.
13201
13202 The \field{seealso} fields have also been changed. For example,
13203 the \code{duck} entry originally had:
13204 \begin{codeenv}
13205 \field{seealso}=\marg{swan,duckling,parrot,goose}
13206 \end{codeenv}
13207 but in the \ext{glstex} file it's written as:
13208 \begin{codeenv}
13209 \field{seealso}=\marg{duckling,goose,parrot,swan}
13210 \end{codeenv}
13211 Note that the \hierarchical\ structure hasn't been maintained. The glossary
13212 lists \qt{duckling} (a \gls{top-levelentry}) after \qt{swan} (a level~2 entry)
13213 but the \field{seealso} field has \code{duckling} first.
13214
13215 If you want to maintain the \hierarchy\ you can use \ics{glsxtrhiername} instead
13216 of \ics{glsentryname}:
13217 \begin{codeenv}
13218 \gls{GlsXtrLoadResources}\oarg{
13219 \csopt[entries]{src},
13220 \csopt[en]{sort},
13221 \csopt[\marg{seealso,see}:en:glsxtrhiername]{sort-label-list}
13222 }
13223 \end{codeenv}
13224 The separator between the levels is
13225 given by \ics{glsxtrhiernamesep} which is defined by
13226 \sty{glossaries-extra} to produce \qt{\glsxtrhiernamesep}.
13227 The \bibgls\ interpreter's definition of this command is different
13228 to assist sorting and simply expands to a \idx{full-stop} to prevent
13229 it from being replaced by the default word break marker.
13230
13231 In this case \code{\ics{glsxtrhiername}\marg{swan}} would be
13232 displayed as \qt{bird\glsxtrhiernamesep waterfowl\glsxtrhiernamesep
13233 swan} if used in the document, but the interpreter converts it to
13234 \qt{bird.waterfowl.swan}, so with the default \csopt{break-at}
13235 setting the actual sort value becomes \code{bird.waterfowl.swan|}
13236 (instead of \code{bird|waterfowl|swan|} which would be the result if
13237 the interpreter used the same definition as \sty{glossaries-extra}).
13238
13239 Therefore the \field{seealso} field for the \code{duck} entry ends up as:
13240 \begin{codeenv}
13241 \field{seealso}=\marg{parrot,goose,swan,duckling}
13242 \end{codeenv}
13243 Now \code{swan} comes before \code{duckling} because the actual sort
13244 value started with a \qt{B} not \qt{S}.
13245
13246 This \hierarchical\ information isn't shown in the cross-reference by
13247 default, so the \code{duck} cross-reference list appears in the
13248 document as: parrot, goose, swan \& duckling.
13249
13250 If you want the \hierarchical\ information to appear to help assist
13251 the reader, you can redefine \ics{glsseeitemformat} in the document
13252 to use \ics{glsxtrhiername}:
13253 \begin{codeenv}
13254 \cmd{renewcommand}*\marg{\cs{glsseeitemformat}}[1]\marg{\cs{glsxtrhiername}\marg{\idx{param}1}}
13255 \end{codeenv}
13256 This means that the \code{duck} cross-reference now appears in the
13257 document as: bird\glsxtrhiernamesep parrot, bird\glsxtrhiernamesep
13258 waterfowl\glsxtrhiernamesep goose, bird\glsxtrhiernamesep waterfowl
13259 \glsxtrhiernamesep swan \& duckling.
13260
13261 This next example document has two languages, English and
13262 Portuguese. The file \filefmt{entries-en.bib} contains the English
13263 terms, such as:
13264 \begin{codeenv}
13265 \atentry{index}\marg{cat, \fieldfmt{translations}=\marg{gato,gatinho} }
13266 \atentry{index}\marg{kitten, \fieldfmt{translations}=\marg{gatinho} }
13267 \atentry{index}\marg{staple, \fieldfmt{translations}=\marg{grampo}}
13268 \atentry{index}\marg{rivet, \fieldfmt{translations}=\marg{rebite}}
13269 \end{codeenv}
13270 The file \filefmt{entries-pt.bib} contains the Portuguese
13271 terms, such as:
13272 \begin{codeenv}
13273 \atentry{index}\marg{gato, \fieldfmt{translations}=\marg{cat,staple,rivet} }
13274 \atentry{index}\marg{gatinho, \fieldfmt{translations}=\marg{kitten} }
13275 \end{codeenv}
13276
13277 Both files have a custom field called \fieldfmt{translations} that
13278 will need to be either defined or aliased. This field contains a
13279 comma-separated list of labels for the corresponding entries in the
13280 other language file that provide a possible translation. Where a
13281 word has multiple possible translations, I'd like the list sorted
13282 alphabetically. (In practice, it would make more sense to sort them
13283 according to how likely the translation is, but this is for
13284 illustrative purposes.) For convenience, the
13285 custom field is simply aliased to the \field{user1} field.
13286
13287 The document has two glossaries for each set of terms. The English
13288 terms are sorted according to \csopt[en-GB]{sort} in one
13289 \igls{resourceset} and the Portuguese terms are sorted according to
13290 \csopt[pt-BR]{sort} in another \igls{resourceset}. This means that there
13291 are cross-resource references, but since there are no instances of
13292 \atentry{preamble} it should be possible to resolve the references.
13293
13294 The document code is:
13295 \begin{codeenv}
13296 \cmd{documentclass}\marg{article}
13297 \strut
13298 \cmd{usepackage}[T1]\marg{fontenc}
13299 \cmd{usepackage}[utf8]\marg{inputenc}
13300 \cmd{usepackage}[british,brazilian]\marg{babel}
13301 \cmd{usepackage}\oarg{\styopt{record},
13302 \styopt{nomain},
13303 \styopt{nostyles},
13304 \styopt[bookindex]{stylemods},
13305 \styopt[bookindex]{style}
13306 }\marg{glossaries-extra}
13307 \cmd{usepackage}\marg{glossaries-prefix}
13308 \strut
13309 \cs{newglossary*}\marg{en}\marg{English Terms}
13310 \cs{newglossary*}\marg{pt}\marg{Portuguese Terms}
13311 \strut
13312 \gls{GlsXtrLoadResources}\oarg{
13313 \csopt[all]{selection},
13314 \csopt[en]{type},
13315 \csopt[entries-en]{src},
13316 \csopt[en-GB]{sort},
13317 \csopt[\fieldfmt{translations}=\field{user1}]{field-aliases},
13318 \csopt[\field{user1}:pt-BR:\encap{glsentryname}]{sort-label-list}
13319 }
13320 \gls{GlsXtrLoadResources}\oarg{
13321 \csopt[all]{selection},
13322 \csopt[pt]{type},
13323 \csopt[entries-pt]{src},
13324 \csopt[pt-BR]{sort},
13325 \csopt[\fieldfmt{translations}=\field{user1}]{field-aliases},
13326 \csopt[\field{user1}:en-GB:\encap{glsentryname}]{sort-label-list}
13327 }
13328 \strut
13329 \cs{apptoglossarypreamble}\oarg{en}\marg{\ics{selectlanguage}\marg{british}}
13330 \cs{apptoglossarypreamble}\oarg{pt}\marg{\cs{selectlanguage}\marg{brazilian}}
13331 \strut
13332 \cmd{begin}\marg{document}
13333 \cs{renewcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\comment{}
13334 \cs{glossentryname}\marg{\idx{param}1}\comment{}
13335 \cs{glsxtrifhasfield}\marg{useri}\marg{\idx{param}1}\marg{: \ics{glsxtrseelist}\cs{glscurrentfieldvalue}}\marg{}\comment{}
13336 }
13337 \cs{printunsrtglossaries}
13338 \cmd{end}\marg{document}
13339 \end{codeenv}
13340 In verbose mode, the transcript file indicates that it's performing
13341 the label list sorting. For example, when sorting according to
13342 \csopt[user1:pt-BR:glsentryname]{sort-label-list}, the transcript
13343 file contains:
13344 \begin{verbatim}
13345 Label list sort method 'pt-BR' on field: user1
13346 \end{verbatim}
13347 The \code{cat} entry has a list of two elements in this field:
13348 \code{gato,gatinho}. This is converted into a new list where the
13349 first element is:
13350 \begin{codeenv}
13351 \marg{\cs{glsentryname}\marg{gato}}
13352 \end{codeenv}
13353 and the second element is:
13354 \begin{codeenv}
13355 \marg{\cs{glsentryname}\marg{gatinho}}
13356 \end{codeenv}
13357 Regardless of the level of verbosity, the transcript file will
13358 contain the conversions obtained by the interpreter:
13359 \begin{verbatim}
13360 texparserlib: {\glsentryname{gato}} -> gato
13361 texparserlib: {\glsentryname{gatinho}} -> gatinho
13362 \end{verbatim}
13363 The \code{kitten} entry has the same list, and the same process is
13364 repeated for that entry. The \commonlongarg{verbose} mode will provide additional
13365 information. The \commonlongarg{debug} mode will indicate whether the
13366 referenced label was found in the current \igls{resourceset} or if it had
13367 to be fetched from another \igls{resourceset}. So if the resulting
13368 order isn't what you expect, check the transcript file for messages.
13369
13370 \optsection[\subsubsection]{prune-xr}
13371
13372 If true, this is a shortcut for:
13373 \begin{codeenv}
13374 \csopt[entrytype=\marg{index(plural)?},see=\marg{},seealso=\marg{},alias=\marg{}]{prune-see-match},
13375 \csopt[entrytype=\marg{index(plural)?},see=\marg{},seealso=\marg{},alias=\marg{}]{prune-seealso-match},
13376 \end{codeenv}
13377
13378 This will remove any labels in an entry's \field{see} or
13379 \field{seealso} field where the referenced label doesn't have any
13380 records and hasn't been selected as another form of dependency and
13381 whose \gls{entrytype} is either \atentry{index} or \atentry{indexplural}
13382 and doesn't have the \field{see}, \field{seealso} or \field{alias}
13383 fields set.
13384
13385 Both \csopt{prune-see-match} and \csopt{prune-seealso-match} can be
13386 switched off at the same time with \csopt[false]{prune-xr}.
13387
13388 \optsection[\subsubsection]{prune-see-match}
13389
13390 The value has the same syntax as \csopt{match}. Omitting the value
13391 switches off the setting. This option is not cumulative.
13392
13393 If a value is supplied, this setting will attempt to prune unnecessary
13394 labels from \field{see} fields. Note that pruning may fail if there
13395 are cross-reference trails.
13396
13397 A label will be stripped from a \field{see} field if the label
13398 references an entry that has no records, isn't dependent on another
13399 entry, hasn't previously been selected, and matches the given
13400 criteria. If more that one pattern match is supplied,
13401 \csopt{prune-see-op} determines whether to apply a logical AND or a
13402 logical OR.
13403
13404 For example, suppose the file \filefmt{entries.bib} contains the
13405 following:
13406 \begin{codeenv}
13407 \atentry{index}\marg{pumpkin}
13408 \atentry{index}\marg{cucumber}
13409 \atentry{index}\marg{melon}
13410 \atentry{index}\marg{cucurbit,\field{see}=\marg{gourd}}
13411 \atentry{index}\marg{gourd,\field{see}=\marg{pumpkin,cucumber,melon}}
13412 \atentry{index}\marg{courgette}
13413 \atentry{index}\marg{marrow,\field{seealso}=\marg{courgette}}
13414 \atentry{index}\marg{broccoli}
13415 \atentry{index}\marg{cauliflower,\field{seealso}=\marg{broccoli}}
13416 \end{codeenv}
13417 Suppose the document contains:
13418 \begin{codeenv}
13419 \gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}}
13420 \cmd{begin}\marg{document}
13421 \cs{gls}\marg{cucurbit}, \cs{gls}\marg{pumpkin}, \cs{gls}\marg{melon}, \cs{gls}\marg{broccoli},
13422 \cs{gls}\marg{marrow}, \cs{gls}\marg{cauliflower}.
13423 \cs{printunsrtglossary}\oarg{title=Index}
13424 \cmd{end}\marg{document}
13425 \end{codeenv}
13426 This uses the default \csopt[recorded and deps]{selection} setting,
13427 which selects recorded entries (cucurbit, pumpkin, melon, broccoli,
13428 marrow and cauliflower) and their dependencies. In this case, the
13429 dependencies are: courgette (because it's listed in the marrow's
13430 \field{seealso} field), gourd (because it's listed in the cucurbit's
13431 \field{see} field), and cucumber (because it's listed in the
13432 gourd's \field{see} field).
13433 The resulting list is:
13434 \begin{quote}
13435 \setlength{\parindent}{0pt}%
13436 \setlength{\parskip}{0pt plus 0.3pt}%
13437 \glstreeitem broccoli 1\par
13438 \glstreeitem cauliflower 1, \emph{see also} broccoli\par
13439 \glstreeitem courgette\par
13440 \glstreeitem cucumber\par
13441 \glstreeitem cucurbit 1, \emph{see} gourd\par
13442 \glstreeitem gourd \emph{see} pumpkin, cucumber \& melon\par
13443 \glstreeitem marrow 1, \emph{see also} courgette\par
13444 \glstreeitem melon 1\par
13445 \glstreeitem pumpkin 1\par
13446 \end{quote}
13447
13448 This means that courgette and cucumber appear in the glossary
13449 without a \igls{locationlist}. If this was an actual glossary with
13450 descriptions, this may not be a problem, but it looks strange for an
13451 index since the cross-reference essentially leads the reader to a dead end.
13452
13453 Switching to \csopt[recorded no deps]{selection} will remove
13454 courgette, gourd and cucumber but the \field{see} and
13455 \field{seealso} fields will be lost. Since gourd references both
13456 pumpkin and melon (which are used in the document), it might be
13457 useful to keep the gourd entry. The aim of pruning is to remove the
13458 unwanted cucumber entry from the gourd's \field{see} list but retain
13459 pumpkin and melon.
13460
13461 An appropriate filter is needed to switch on pruning. (This is in
13462 addition to the criteria that the pruned entry has no records, isn't
13463 dependent on another entry, and hasn't previously been selected.)
13464 This type of pruning is usually only necessary for indexes so a
13465 useful filter may be simply on the \gls{entrytype} (either
13466 \atentry{index} or \atentry{indexplural}):
13467 \begin{codeenv}
13468 \gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},
13469 \csopt[entrytype=\marg{index(plural)?}]{prune-see-match}}
13470 \end{codeenv}
13471 Another possibility is to filter on an empty \field{description}:
13472 \begin{codeenv}
13473 \gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[description=\marg{}]{prune-see-match}}
13474 \end{codeenv}
13475
13476 The result is that the cauliflower and marrow entries keep their
13477 \field{seealso} lists (since this option only applies to \field{see}
13478 lists) and the courgette entry has been added (because it's
13479 in the marrow entry's \field{seealso} list). The gourd entry is
13480 removed from the cucurbit's \field{see} list (because it matches the
13481 criteria) and is not selected (because it's no longer a dependency).
13482
13483 In this case, I'd like to include the gourd entry because it has the
13484 \field{see} field set. This means adjusting the criteria so that
13485 only entries without the \field{see} field can be pruned:
13486 \begin{codeenv}
13487 \gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},
13488 \csopt[entrytype=\marg{index(plural)?},see=\marg{}]{prune-see-match}}
13489 \end{codeenv}
13490 This means that gourd is now selected (and retained in the
13491 cucurbit's \field{see} field) but cucumber is removed from the
13492 gourd's \field{see} field.
13493
13494 A similar method can be applied for the \field{seealso} fields using
13495 \csopt{prune-seealso-match}. There's no applicable setting for the
13496 \field{alias} field (since it's expected that the alias be present
13497 due to the nature of the way the \field{alias} field works).
13498
13499 For convenience, the \csopt{prune-xr} option is provided as a
13500 shortcut. If the resource command in the above example is modified
13501 to:
13502 \begin{codeenv}
13503 \gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt{prune-xr}}
13504 \end{codeenv}
13505 then the resulting list will be:
13506 \begin{quote}
13507 \setlength{\parindent}{0pt}%
13508 \setlength{\parskip}{0pt plus 0.3pt}%
13509 \glstreeitem broccoli 1\par
13510 \glstreeitem cauliflower 1, \emph{see also} broccoli\par
13511 \glstreeitem cucurbit 1, \emph{see} gourd\par
13512 \glstreeitem gourd \emph{see} pumpkin \& melon\par
13513 \glstreeitem marrow 1\par
13514 \glstreeitem melon 1\par
13515 \glstreeitem pumpkin 1\par
13516 \end{quote}
13517
13518 Note that if the pumpkin and melon references are removed from the
13519 document, then gourd will still be selected but will have no
13520 cross-reference. This is because the cucurbit entry is checked for
13521 pruning while the gourd entry still has a non-empty \field{see}
13522 field so it's not removed from the cucurbit entry.
13523
13524 There are two ways around this problem: either switch the
13525 definitions of cucurbit and gourd around in the \ext{bib} file
13526 or use \csopt{prune-iterations} to reprune (in this case,
13527 \csopt[2]{prune-iterations} is sufficient).
13528
13529 \begin{important}
13530 This setting is only compatible with the \qt{recorded and dep}
13531 selection criteria: \csopt[recorded and
13532 deps]{selection}, \csopt[recorded and deps and see]{selection}
13533 and \csopt[recorded and deps and see not also]{selection}.
13534 \end{important}
13535
13536 \optsection[\subsubsection]{prune-see-op}
13537
13538 If the value of \csopt{prune-see-match} contains more than one
13539 \meta{key}=\meta{pattern} element, the \csopt{prune-see-op}
13540 determines whether to apply a logical AND or a logical OR.
13541 The \meta{value} may be either \optfmt{and} or \optfmt{or}.
13542 The default is \csopt[and]{prune-see-op}.
13543
13544 \optsection[\subsubsection]{prune-seealso-match}
13545
13546 As \csopt{prune-see-match} but for \field{seealso} fields. If more
13547 that one pattern match is supplied, \csopt{prune-seealso-op}
13548 determines whether to apply a logical AND or a logical OR.
13549
13550 \begin{important}
13551 This setting is only compatible with the \qt{recorded and dep}
13552 selection criteria: \csopt[recorded and
13553 deps]{selection}, \csopt[recorded and deps and see]{selection}
13554 and \csopt[recorded and deps and see not also]{selection}.
13555 \end{important}
13556
13557 \optsection[\subsubsection]{prune-seealso-op}
13558
13559 If the value of \csopt{prune-seealso-match} contains more than one
13560 \meta{key}=\meta{pattern} element, the \csopt{prune-seealso-op}
13561 determines whether to apply a logical AND or a logical OR.
13562 The \meta{value} may be either \optfmt{and} or \optfmt{or}.
13563 The default is \csopt[and]{prune-seealso-op}.
13564
13565 \optsection[\subsubsection]{prune-iterations}
13566
13567 If you have cross-reference trails, you may need to reprune. The
13568 value of this options indicates the number of pruning iterations.
13569 The default is 1. The higher the number, the longer \bibgls\ will
13570 take to complete. The value can't be less that 1.
13571
13572 The maximum number of iterations is capped at 20. A cross-reference
13573 trail that long is excessive for an index.
13574
13575 \optsection[\subsubsection]{bibtex-contributor-fields}
13576
13577 This option indicates that the listed fields all use \BibTeX's name
13578 syntax (as used in \BibTeX's \code{author} and \code{editor} fields).
13579 The \meta{list} value is required for this key but
13580 may be empty, which indicates an empty set of fields (that is, the
13581 setting is switched off).
13582
13583 The values of these fields will be converted into the form:
13584 \begin{codeenv}
13585 \gls{bibglscontributorlist}\margm{contributor list}\margm{n}
13586 \end{codeenv}
13587 where \meta{n} is the number of names in the list and
13588 \meta{contributor-list} is a comma-separated list of names in the
13589 form:
13590 \begin{codeenv}
13591 \gls{bibglscontributor}\margm{forenames}\margm{von-part}\margm{surname}\margm{suffix}
13592 \end{codeenv}
13593
13594 The \gls{bibglscontributorlist} command is initially defined in
13595 \bibgls's interpreter to just do the first argument and ignore the
13596 second. This means that if you're sorting on this field, the \qt{and}
13597 part between the final names doesn't appear in the sort value.
13598 The actual definition of \gls{bibglscontributorlist} provided in the
13599 \ext{glstex} file depends on whether or not \ics{DTLformatlist} is defined.
13600 (Note that \styfmt{glossaries} automatically loads \sty{datatool-base}
13601 so this command will be defined if you have at least v2.28 of
13602 \sty{datatool-base}.)
13603
13604 For example, if the \field{name} field is specified as:
13605 \begin{codeenv}
13606 \field{name}=\marg{John Smith and Jane Doe and Dickie von Duck}
13607 \end{codeenv}
13608 then \csopt[name]{bibtex-contributor-fields} will convert the
13609 \field{name} field value to:
13610 \begin{codeenv}
13611 \gls{bibglscontributorlist}\marg{\comment{}
13612 \gls{bibglscontributor}\marg{John}\marg{}\marg{Smith}\marg{},\comment{}
13613 \gls{bibglscontributor}\marg{Jane}\marg{}\marg{Doe}\marg{},\comment{}
13614 \gls{bibglscontributor}\marg{Dickie}\marg{von}\marg{Duck}\marg{}}\marg{3}
13615 \end{codeenv}
13616 With \csopt[von]{contributor-order} the sort value obtained from
13617 this field will be:
13618 \begin{verbatim}
13619 Smith, John,Doe, Jane,von Duck, Dickie
13620 \end{verbatim}
13621 With one of the locale sort methods and with the default
13622 \csopt[word]{break-at}, this will end up as:
13623 \begin{verbatim}
13624 Smith|John|Doe|Jane|von|Duck|Dickie
13625 \end{verbatim}
13626
13627 \optsection[\subsubsection]{contributor-order}
13628
13629 The \gls{bibglscontributor} command is defined in
13630 \bibgls's interpreter and its definition is dependent on this
13631 setting. The \meta{value} may be one of (where the parts in square
13632 brackets are omitted if that argument is empty):
13633 \begin{itemize}
13634 \item \optfmt{surname}: \gls{bibglscontributor} expands to
13635 \meta{surname}\oarg{, \meta{suffix}}\oarg{, \meta{forenames}}\oarg{,
13636 \meta{von-part}};
13637 \item \optfmt{von}: \gls{bibglscontributor} expands to
13638 \oarg{\meta{von-part} }\meta{surname}\oarg{, \meta{suffix}}\oarg{, \meta{forenames}};
13639 \item \optfmt{forenames}: \gls{bibglscontributor} expands to
13640 \oarg{\meta{forenames} }\oarg{\meta{von-part} }\meta{surname}\oarg{,
13641 \meta{suffix}}.
13642 \end{itemize}
13643 The default value is \optfmt{von}. Note that if you have multiple
13644 resource sets, this option governs the way \bibgls's version of
13645 \gls{bibglscontributor} behaves. The actual definition is written to
13646 the \ext{glstex} using \cs{providecommand}, which means that \LaTeX\
13647 will only pick up the first definition.
13648
13649 For example:
13650 \begin{codeenv}
13651 \cs{newcommand}*\marg{\gls{bibglscontributor}}[4]\marg{\comment{}
13652 \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{}
13653 }
13654 \strut
13655 \gls{GlsXtrLoadResources}\oarg{
13656 \csopt[entries]{src},\comment{data in entries.bib}
13657 \csopt[name]{bibtex-contributor-fields}
13658 }
13659 \end{codeenv}
13660 This will display the names in the glossary with the forenames
13661 first, but \bibgls\ will sort according to surname.
13662
13663 An alternative approach, if you need an initial resource set
13664 such as with the \exfile{no-interpret-preamble.bib} file:
13665 \begin{codeenv}
13666 \gls{GlsXtrLoadResources}\oarg{
13667 \csopt[no-interpret-preamble]{src},
13668 \csopt[false]{interpret-preamble},
13669 \csopt[name]{bibtex-contributor-fields},
13670 \csopt[forenames]{contributor-order}
13671 }
13672 \strut
13673 \gls{GlsXtrLoadResources}\oarg{
13674 \csopt[entries]{src},\comment{data in entries.bib}
13675 \csopt[name]{bibtex-contributor-fields}
13676 }
13677 \end{codeenv}
13678 Note the need to use \csopt[name]{bibtex-contributor-fields}
13679 in the first resource set even though there are no entries in
13680 the \ext{bib} file. This is because the definition of
13681 \gls{bibglscontributor} is only written to the \ext{glstex} file if
13682 \csopt{bibtex-contributor-fields} has been set to a non-empty list.
13683 The second resource set will use the default
13684 \csopt[von]{bibtex-contributor-fields} setting when obtaining the
13685 sort value.
13686
13687 \optsection[\subsubsection]{encapsulate-fields}
13688
13689 This option should take a comma-separated list of
13690 \optfmt{\meta{field}\dequals\meta{cs-name-1arg}} values, where
13691 \meta{cs-name-1arg} is the name of a control sequence that takes
13692 one argument. The value is required for this key but
13693 may be empty, which indicates an empty set (that is, the
13694 setting is switched off).
13695
13696 During the processing stage, each field identified in
13697 the list (if defined) will have its value replaced with:
13698 \begin{codeenv}
13699 \cmd{\meta{cs-name-1arg}}\margm{value}
13700 \end{codeenv}
13701 where \meta{value} was its previous value. An
13702 empty list switches off encapsulation (the default).
13703
13704 This action overrides any previous use of \csopt{encapsulate-fields}
13705 within the same \igls{resourceset} and is always performed before
13706 \csopt{encapsulate-fields*}, regardless of the order in the
13707 \igls{resourceset}['s] list of options.
13708
13709 \optsection[\subsubsection]{encapsulate-fields*}
13710
13711 This option should take a comma-separated list of
13712 \optfmt{\meta{field}\dequals\meta{cs-name-2arg}} values, where
13713 \meta{cs-name-2arg} is the name of a control sequence that takes two
13714 arguments. The value is required for this key but
13715 may be empty, which indicates an empty set (that is, the
13716 setting is switched off).
13717
13718 During the processing stage, each field identified in the
13719 list (if defined) will have its value replaced with:
13720 \begin{codeenv}
13721 \cmd{\meta{cs-name-2arg}}\margm{value}\margm{label}
13722 \end{codeenv}
13723 where \meta{value} was its previous value and \meta{label} is the
13724 entry's label (including prefix, if appropriate). An
13725 empty list switches off encapsulation (the default).
13726
13727 This action overrides any previous use of
13728 \csopt{encapsulate-fields*} within the same \igls{resourceset}, and
13729 is always performed after \csopt{encapsulate-fields}, regardless of
13730 the order in the \igls{resourceset}['s] list of options, so if the
13731 same field is listed in both settings, its value will end up as:
13732 \begin{codeenv}
13733 \cmd{\meta{cs-name-2arg}}\marg{\cmd{\meta{cs-name-1arg}}\margm{value}}\margm{label}
13734 \end{codeenv}
13735 An alternative is to use the more complex \csopt{assign-fields} option.
13736
13737 \optsection[\subsubsection]{format-integer-fields}
13738
13739 This option should take a comma-separated list of
13740 \optfmt{\meta{field}\dequals\meta{format}} values, where
13741 \meta{format} is a
13742 \href{https://docs.oracle.com/javase/8/docs/api/java/util/Formatter.html#syntax}{string
13743 format pattern} that contains a single numeric specifier.
13744 This will convert the value stored in the identified field to the
13745 given format. If the field doesn't contain an integer value it won't
13746 be changed. If the field contains a decimal value use
13747 \csopt{format-decimal-fields} instead. This setting is performed
13748 before field encapsulation.
13749
13750 Since format patterns uses \idx{percentchar} as a placeholder, which
13751 can be problematic in the resource command, you will need to use
13752 \ics{cs.percent} instead. You may also use \ics{cs.hash},
13753 \ics{cs.dollar}, \ics{cs.amp}, \ics{cs.openbrace},
13754 \ics{cs.closebrace}, \ics{cs.underscore} and \ics{cs.backslash} to
13755 indicate the corresponding literal character. You can use \cs{u}\meta{XXXX} to
13756 indicate a character by its hexadecimal value, but remember that the
13757 resource options will be expanded when they are written to the
13758 resource file so use \cs{glshex} or \cs{cs.string}\cs{u}.
13759
13760 If you want to format the \field{definitionindex} field you must use
13761 \csopt{save-definition-index} first. For example, to save this field
13762 and then zero-pad it to four digits:
13763 \begin{codeenv}
13764 \csopt{save-definition-index},
13765 \csopt[definitionindex=\ics{cs.percent}04d]{format-integer-fields}
13766 \end{codeenv}
13767 This option can't be used for the \field{useindex} field
13768 created with \csopt{save-use-index} as that field isn't set until
13769 after the field modifications are made.
13770
13771 \optsection[\subsubsection]{format-decimal-fields}
13772
13773 As \csopt{format-integer-fields} but for decimal values. If a field
13774 contains an integer then:
13775 \begin{itemize}
13776 \item if \csopt{format-integer-fields} has also been used to set a
13777 format for the given field, the integer format will take precedence;
13778 \item otherwise the integer value will be treated as a decimal
13779 number.
13780 \end{itemize}
13781 If you get an error like:
13782 \begin{verbatim}
13783 Error: d != java.lang.Double
13784 \end{verbatim}
13785 then it means you have used an invalid specifier. (The above error
13786 results from using \verb|%d| instead of \verb|%f| or \verb|%g|.)
13787
13788 \optsection[\subsubsection]{interpret-fields}
13789
13790 This option indicates that the listed fields should be replaced by
13791 their interpreted values. The value is required for this key but
13792 may be empty, which indicates an empty set of fields (that is, the
13793 setting is switched off). Other fields not listed may still be
13794 interpreted depending on other settings. As with the \field{sort}
13795 field, any special characters are replaced with commands like
13796 \ics{glsbackslash} and \ics{bibglsdollarchar}. This option is
13797 applied after \csopt{field-case-change} (if set).
13798
13799 For example, suppose I have a file \filefmt{entries.bib} that
13800 contains definitions like:
13801 \begin{codeenv}
13802 \atentry{symbol}\marg{pi,
13803 \field{name}=\marg{\cs{ensuremath}\marg{\ics{pi}}},
13804 \field{description}=\marg{the ratio of a circle's circumference to its diameter},
13805 }
13806 \strut
13807 \atentry{symbol}\marg{sigma,
13808 \field{name} = \marg{\cs{ensuremath}\marg{\ics{sigma}}},
13809 \field{description} = \marg{standard deviation}
13810 }
13811 \end{codeenv}
13812 Instead of having a list of terms (glossary), suppose I want to have
13813 stand-alone definitions, where the term appears in a section heading.
13814 I could define a command like this:
13815 \begin{codeenv}
13816 \cs{newcommand}\marg{\cmd{definition}}[1]\marg{\comment{}
13817 \cs{ifglsentryexists}\marg{\idx{param}1}\comment{}
13818 \marg{\comment{}
13819 \cs{section}\oarg{\cs{glsentryname}\marg{\idx{param}}}\marg{\cs{glsadd}\marg{\idx{param}1}\ics{glsxtrglossentry}\marg{\idx{param}1}}\comment{}
13820 \ics{Glossentrydesc}\marg{\idx{param}1}\cs{glspostdescription}
13821 }\comment{}
13822 \marg{\cs{section}\oarg{Missing `\idx{param}1'}\marg{\cs{glsadd}\marg{\idx{param}1}}}\comment{}
13823 }
13824 \end{codeenv}
13825 which can be used in the document:
13826 \begin{codeenv}
13827 \ics{tableofcontents}
13828 \cmd{definition}\marg{pi}
13829 \cmd{definition}\marg{sigma}
13830 \end{codeenv}
13831 A problem with this definition of my custom command occurs if I add
13832 \sty{hyperref} to the document, because this tries to write \cs{pi}
13833 and \cs{sigma} to the PDF bookmarks, which doesn't work because
13834 those commands can't be automatically converted to characters
13835 permitted in a PDF string. This leads to a warning from
13836 \sty{hyperref}:
13837 \begin{alltt}
13838 Token not allowed in a PDF string (Unicode)
13839 \end{alltt}
13840 Ideally I'd like to be able to convert these symbols to Unicode so
13841 that they can appear in the bookmarks. Since \bibgls' interpreter
13842 recognises these commands, I can get it to make the conversion
13843 instead of trying to implement a method within \TeX:
13844 \begin{codeenv}
13845 \cs{glsaddstoragekey}\marg{pdfname}\marg{}\marg{\cmd{pdfname}}
13846 \gls{GlsXtrLoadResources}\oarg{
13847 \csopt[entries]{src},
13848 \csopt[\field{name}=\fieldfmt{pdfname}]{replicate-fields},
13849 \csopt[fallback]{replicate-missing-field-action},
13850 \csopt[\fieldfmt{pdfname}]{interpret-fields}
13851 }
13852 \end{codeenv}
13853 This first copies the \field{name} field to the custom
13854 \fieldfmt{pdfname} and then interprets the copy. This leaves
13855 the \field{name} field with the \LaTeX\ code to produce the symbol
13856 in the document, but the \fieldfmt{pdfname} field ends up with all markup
13857 stripped by the interpreter and the \cs{pi} and \cs{sigma} are
13858 converted to the Unicode characters \hex{1D70B} (mathematical italic
13859 small pi) and \hex{1D70E} (mathematical italic small sigma). With
13860 \XeLaTeX\ or \LuaLaTeX\ these characters can be written to the PDF
13861 bookmarks by adjusting the definition of the custom command:
13862 \begin{codeenv}
13863 \cs{newcommand}\marg{\cmd{definition}}[1]\marg{\comment{}
13864 \cs{ifglsentryexists}\marg{\idx{param}1}\comment{}
13865 \marg{\comment{}
13866 \cs{section}
13867 \oarg{\ics{texorpdfstring}\marg{\cs{glsentryname}\marg{\idx{param}1}}\marg{\cmd{pdfname}\marg{\idx{param}1}}}
13868 \marg{\cs{glsadd}\marg{\idx{param}1}\cs{glsxtrglossentry}\marg{\idx{param}1}}\comment{}
13869 \cs{Glossentrydesc}\marg{\idx{param}1}\cs{glspostdescription}
13870 }\comment{}
13871 \marg{\cs{section}\oarg{Missing `\idx{param}1'}\marg{\cs{glsadd}\marg{\idx{param}1}}}%
13872 }
13873 \end{codeenv}
13874 With \pdfLaTeX\ and \sty{fontenc}, you will need
13875 \sty{hyperref}'s \styoptfmt{unicode} option:
13876 \begin{codeenv}
13877 \cs{usepackage}\oarg{\styoptfmt{unicode}}\marg{hyperref}
13878 \end{codeenv}
13879 If you still encounter problems with the Unicode characters not
13880 appearing in the PDF bookmarks, then try the
13881 \csopt{hex-unicode-fields} option. For example:
13882 \begin{codeenv}
13883 \csopt[pdfname]{hex-unicode-fields}
13884 \end{codeenv}
13885 This still requires \sty{hyperref}'s \styoptfmt{unicode} option.
13886
13887 \optsection[\subsubsection]{interpret-fields-action}
13888
13889 This option governs the behaviour of \csopt{interpret-fields}.
13890 Available values are:
13891 \begin{itemize}
13892 \item\code{replace}: replace the field content with its interpreted
13893 value (default);
13894 \item\code{replace non empty}: only replace the field content with
13895 its interpreted value if the interpreted value isn't an empty
13896 string.
13897 \end{itemize}
13898 If a field value consists solely of commands that are unknown to the
13899 interpreter, then the resulting value will end up empty. In this
13900 case, it may be more appropriate to leave the field unchanged.
13901
13902 \optsection[\subsubsection]{hex-unicode-fields}
13903
13904 This option will convert any Unicode characters (outside of the
13905 Basic Latin set) that are found in the listed fields into
13906 \code{\gls{bibglshexunicodechar}\margm{hex-code}} where
13907 \meta{hex-code} is the hexadecimal character code.
13908
13909 The \meta{list} should be a comma-separated list of field names.
13910 This action is performed after \csopt{interpret-fields}.
13911
13912 If the field contents need to be added to the PDF bookmarks (as in
13913 the earlier example) then you need to make sure you use
13914 \sty{hyperref}'s \styoptfmt{unicode} option
13915 otherwise you'll get the warning:
13916 \begin{verbatim}
13917 Token not allowed in a PDF string (PDFDocEncoding):
13918 removing `\char'
13919 \end{verbatim}
13920 and the bookmarks will show \idx{doublequotecharhex}\meta{hex-code}
13921 instead of the Unicode character.
13922
13923 \optsection[\subsubsection]{date-time-fields}
13924
13925 This option indicates that the listed fields all contain
13926 date and time information. Primary entries will have these fields
13927 parsed according to \csopt{date-time-field-format} and
13928 \csopt{date-time-field-locale} and dual entries will have these
13929 fields parsed according to \csopt{dual-date-time-field-format} and
13930 \csopt{dual-date-time-field-locale}. If the field value is missing
13931 or doesn't match the given pattern it remains unchanged, otherwise
13932 it's converted into the form:
13933 \formatdef{bibglsdatetime}
13934 where \meta{original} is the value of the field before conversion.
13935 If the interpreter is on, the value will be interpreted before
13936 being parsed if it contains \idx{escchar}, \idx{mshiftchar},
13937 \idx{bgroupchar}, \idx{egroupchar} or \idx{nbspchar}. (Remember that
13938 \idx{nbspchar} is converted to the non-breaking space character
13939 \hex{A0} unless \longarg{break-space} is used.)
13940
13941 \optsection[\subsubsection]{date-fields}
13942
13943 As \csopt{date-time-fields} but for fields that only contain date
13944 (not time) information. If parsed correctly, the field is converted
13945 to:
13946 \formatdef{bibglsdate}
13947 The fields are parsed according to
13948 \csopt{date-field-format} and
13949 \csopt{date-field-locale} for \glspl{primaryentry} and according to
13950 \csopt{dual-date-field-format} and
13951 \csopt{dual-date-field-locale} for \glspl{dualentry}.
13952
13953 \optsection[\subsubsection]{time-fields}
13954
13955 As \csopt{date-time-fields} but for fields that only contain time
13956 (not date) information. If parsed correctly, the field is converted
13957 to:
13958 \formatdef{bibglstime}
13959 The fields are parsed according to
13960 \csopt{time-field-format} and
13961 \csopt{time-field-locale} for \glspl{primaryentry} and according to
13962 \csopt{dual-time-field-format} and
13963 \csopt{dual-time-field-locale} for \glspl{dualentry}.
13964
13965 \optsection[\subsubsection]{date-time-field-format}
13966
13967 This option also sets
13968 \csopt[\meta{value}]{dual-date-time-field-format}.
13969 The value is the format pattern used when parsing fields identified
13970 by \csopt{date-time-fields}. The \meta{value} is as for
13971 \csopt{date-sort-format}.
13972
13973 \optsection[\subsubsection]{date-field-format}
13974
13975 This option also sets
13976 \csopt[\meta{value}]{dual-date-field-format}.
13977 The value is the format pattern used when parsing fields identified
13978 by \csopt{date-fields}. The \meta{value} is as for
13979 \csopt{date-sort-format}.
13980
13981 \optsection[\subsubsection]{time-field-format}
13982
13983 This option also sets
13984 \csopt[\meta{value}]{dual-time-field-format}.
13985 The value is the format pattern used when parsing fields identified
13986 by \csopt{time-fields}. The \meta{value} is as for
13987 \csopt{date-sort-format}.
13988
13989 \optsection[\subsubsection]{date-time-field-locale}
13990
13991 This option also sets
13992 \csopt[\meta{value}]{dual-date-time-field-locale}.
13993 The value is the locale used when parsing fields identified
13994 by \csopt{date-time-fields}. The \meta{value} is as for
13995 \csopt{date-sort-locale}.
13996
13997 \optsection[\subsubsection]{date-field-locale}
13998
13999 This option also sets
14000 \csopt[\meta{value}]{dual-date-field-locale}.
14001 The value is the locale used when parsing fields identified
14002 by \csopt{date-fields}. The \meta{value} is as for
14003 \csopt{date-sort-locale}.
14004
14005 \optsection[\subsubsection]{time-field-locale}
14006
14007 This option also sets
14008 \csopt[\meta{value}]{dual-time-field-locale}.
14009 The value is the locale used when parsing fields identified
14010 by \csopt{time-fields}. The \meta{value} is as for
14011 \csopt{date-sort-locale}.
14012
14013 \subsection{Prefix Fields}
14014 \label{sec:prefixfields}
14015
14016 If you use the \isty{glossaries-prefix} package, the prefix
14017 set of fields become available (\field{prefix},
14018 \field{prefixplural}, \field{prefixfirst} and
14019 \field{prefixfirstplural}). The default behaviour of \ics{pgls} is for no
14020 separator between the prefix and the text produced with \cs{gls}.
14021 This is because there are situations where there shouldn't be a
14022 space, although a space is more commonly required.
14023
14024 This means that a space needs to be appended to the required prefix
14025 fields, but an actual space character can't be used because
14026 \sty{xkeyval} trims leading and trailing spaces. The \ics{space}
14027 command needs to be used instead, but there are also situations
14028 where an non-breakable space should be used (for example, where the
14029 prefix is a single character). It's a bit tiresome having to
14030 remember to put \ics{space} or \idx{nbspchar} at the end of the
14031 field value.
14032
14033 The \csopt{append-prefix-field} option allows the automatic insertion of a
14034 space, but it may be used without the \sty{glossaries-prefix}
14035 package. The fields that contain prefixes are identified by
14036 \csopt{prefix-fields}.
14037
14038 If you have any dual entries, then \bibgls\ will also recognise the
14039 special internal fields \field{dualprefix},
14040 \field{dualprefixplural}, \field{dualprefixfirst} and
14041 \field{dualprefixfirstplural}.
14042
14043 \optsection[\subsubsection]{prefix-fields}
14044
14045 Identifies the fields that are used to store prefixes. The default
14046 set is: \field{prefix}, \field{prefixfirst}, \field{prefixplural},
14047 \field{prefixfirstplural}, and their dual counterparts
14048 \field{dualprefix}, \field{dualprefixfirst}, \field{dualprefixplural}
14049 and \field{dualprefixfirstplural}.
14050
14051 \optsection[\subsubsection]{append-prefix-field}
14052
14053 Allowed values are:
14054 \begin{itemize}
14055 \item \optfmt{none}: don't append a space to the prefix fields (default);
14056
14057 \item \optfmt{space}: append the command identified by
14058 \csopt{append-prefix-field-cs} (\ics{space} by default) to the
14059 prefix field unless the field value ends with a character identified
14060 by \csopt{append-prefix-field-exceptions} or a command identified by
14061 \csopt{append-prefix-field-cs-exceptions}. Note that if the field
14062 value ends with anything else (such as an empty group) then these
14063 exceptions won't apply.
14064
14065 \item \optfmt{space or nbsp}: as above but uses \idx{nbspchar}
14066 instead of \ics{space} if the field value matches the pattern given
14067 by \csopt{append-prefix-field-nbsp-match}.
14068
14069 \end{itemize}
14070
14071 \optsection[\subsubsection]{append-prefix-field-cs}
14072
14073 Identifies the command \meta{cs} that should be used to append to
14074 the prefix fields. The default value is \ics{space}. Remember to use
14075 \cs{cs.string} or \cs{protect} to prevent the command from being
14076 expanded as it's written to the \ext{aux} file.
14077
14078 \optsection[\subsubsection]{append-prefix-field-exceptions}
14079
14080 This setting identifies the set of characters that, if found at the
14081 end of a prefix field, prevent \csopt{append-prefix-field} from
14082 appending a space (either \ics{space} or \idx{nbspchar}).
14083
14084 The value should be a sequence of characters. You may use
14085 \stringu\meta{hex} to identify a character by its hexadecimal code.
14086 Spaces are ignored, so \csopt[ ' - ]{append-prefix-field-exceptions}
14087 is equivalent to \csopt['-]{append-prefix-field-exceptions}.
14088
14089 The default set is the straight apostrophe character (\hex{0027}),
14090 the hyphen-minus character (\hex{002D}), the tilde character
14091 (\idx{nbspchar}), the hyphen character (\hex{2010}), the
14092 non-breaking hyphen (\hex{2011}), and the right single quotation
14093 mark (\hex{2019}).
14094
14095 \optsection[\subsubsection]{append-prefix-field-cs-exceptions}
14096
14097 This setting identifies the set of commands that, if found at the
14098 end of a prefix field, prevent \csopt{append-prefix-field} from
14099 appending a space (either \ics{space} or \idx{nbspchar}). Any spaces
14100 found in \meta{sequence} are ignored. The default setting is the
14101 set: \cs{space}, \ics{nobreakspace} and \cs{cs.space}.
14102
14103 Remember that you will need to use \cs{cs.string} or \cs{protect} to
14104 prevent the command from being expanded while the resource options
14105 are written to the \ext{aux} file.
14106
14107 \optsection[\subsubsection]{append-prefix-field-nbsp-match}
14108
14109 The value is the \gls{regular-expression} that identifies prefixes that should be
14110 followed by \idx{nbspchar} instead of \ics{space}. The default
14111 is \csopt[\idx{matchanydot}]{append-prefix-field-nbsp-match} which indicates a
14112 single character.
14113
14114 \subsection{Case-Changing}
14115 \label{sec:fieldcase}
14116
14117 The \sty{glossaries-extra} package comes with the category
14118 attributes \catattr{glossdesc} and \catattr{glossname}, which may
14119 take the values \optfmt{firstuc} or \optfmt{title}. These don't
14120 change the actual \field{name} or \field{description} fields, but
14121 instead \ics{glossentryname} and \ics{glossentrydesc} (which are
14122 used by the default glossary styles) check for the corresponding
14123 attribute and apply the appropriate \idx{case-change} to the field value.
14124
14125 So \ics{glossentryname} will use \ics{Glsentryname} if the
14126 \catattr{glossname} attribute for the given entry is set to \optfmt{firstuc}
14127 and \ics{glossentrydesc} will use \ics{Glsentrydesc} if the
14128 \catattr{glossdesc} attribute is set to \optfmt{firstuc}.
14129 The \optfmt{title} setting will instead use \ics{capitalisewords}
14130 applied to the field value.
14131
14132 The resource options described in this section provide an
14133 alternative to those attributes that actually modify the relevant
14134 field (rather than just adjusting the style code used to display it).
14135 There are two forms of modification: the field is adjusted so that
14136 the original value is encapsulated by a command or \bibgls\ will
14137 perform the actual \idx{case-change} according to its own algorithm.
14138 The results can vary according to the field content.
14139
14140 Where \bibgls\ itself performs the case change, its case-changing
14141 functions will use the \gls{resource-locale}, but whether or not
14142 \bibgls\ recognises the correct rules for the locale depends on
14143 whether or not the locale is correctly supported by the Java locale
14144 provider. The \langxml\ may provide assistance with case-conversion.
14145
14146 \begin{important}
14147 Note the difference between \ics{NoCaseChange} (which prevents case-changing
14148 for both \bibgls\ and in the \LaTeX\ document) and \ics{BibGlsNoCaseChange}
14149 (which only prevents case-changing in \bibgls). The options that defer
14150 the case-change action to \LaTeX, such as \optfmt{uc-cs}, will treat
14151 \ics{NoCaseChange} as an exclusion but not \ics{BibGlsNoCaseChange}.
14152 \end{important}
14153
14154 Each of the case-changing resource options may take one of the
14155 following values:
14156 \begin{itemize}
14157 \item \optfmt{none}: don't apply any case-changing (default);
14158
14159 \item \optfmt{lc-cs}: make \bibgls\ behave as though the field
14160 assignment:
14161 \begin{codeenv}
14162 \meta{field} = \margm{text}
14163 \end{codeenv}
14164 had actually been specified as:
14165 \begin{codeenv*}
14166 \meta{field} = \marg{\gls{bibglslowercase}\margm{text}}
14167 \end{codeenv*}
14168 which uses \TeX\ to convert the field to \idx{lowercase};
14169
14170 \item \optfmt{uc-cs}: make \bibgls\ behave as though the field
14171 assignment:
14172 \begin{codeenv}
14173 \meta{field} = \margm{text}
14174 \end{codeenv}
14175 had actually been specified as:
14176 \begin{codeenv*}
14177 \meta{field} = \marg{\gls{bibglsuppercase}\margm{text}}
14178 \end{codeenv*}
14179 which uses \TeX\ to convert the field to \idx{uppercase};
14180
14181 \item \optfmt{firstuc-cs}: make \bibgls\ behave as though the field
14182 assignment:
14183 \begin{codeenv}
14184 \meta{field} = \margm{text}
14185 \end{codeenv}
14186 had actually been specified as:
14187 \begin{codeenv*}
14188 \meta{field} = \marg{\gls{bibglsfirstuc}\margm{text}}
14189 \end{codeenv*}
14190 which uses \TeX\ to convert the field to first-letter \idx{uppercase};
14191
14192 \item \optfmt{title-cs}: make \bibgls\ behave as though the field
14193 assignment:
14194 \begin{codeenv}
14195 \meta{field} = \margm{text}
14196 \end{codeenv}
14197 had actually been specified as:
14198 \begin{codeenv*}
14199 \meta{field} = \marg{\gls{bibglstitlecase}\margm{text}}
14200 \end{codeenv*}
14201 which uses \TeX\ to convert the field to \idx{titlecase};
14202
14203 \item \optfmt{lc}: convert to \idx{lowercase} by making the
14204 appropriate modifications to tokens in the field value that have
14205 a known \idx{lowercase} alternative (see below);
14206
14207 \item \optfmt{uc}: convert to \idx{uppercase} by making the
14208 appropriate modifications to tokens in the field value that have
14209 a known \idx{uppercase} alternative (see below);
14210
14211 \item \optfmt{firstuc}: convert to first letter \idx{uppercase}
14212 by making the appropriate modification, if it has
14213 a known \idx{uppercase} alternative (see below);
14214
14215 \item \optfmt{title}: convert to \idx{titlecase} by making the
14216 appropriate modifications to the first letter of each identified
14217 word in the field value that has a known \idx{uppercase}
14218 alternative (see below).
14219
14220 A word-boundary is identified according to the
14221 \csopt{word-boundaries} setting. Words to be excluded from the
14222 case-changing (unless they occur at the start) can be identified
14223 with \ics{MFUnocap} in the \atentry{preamble} or you can use
14224 \code{\longarg{packages} mfirstuc-english} for the exclusion list
14225 provided by the \isty{mfirstuc-english} package. Alternatively, you
14226 can use \longarg{custom-packages} to load a simple package that
14227 contains the required \cs{MFUnocap} commands (in a similar style to
14228 \sty{mfirstuc-english}).
14229
14230 The \bibgls\ word-boundary implementation is slightly different with
14231 this setting than with the \cs{capitalisewords} command (implemented
14232 in \TeX\ or by the \texparserlib\ when interpreting field
14233 values). Only words in the exclusion list that start with an
14234 alphabetical character can be matched. Punctuation following a
14235 word-boundary is not considered part of the next word.
14236 If you want to identify that a particular character forms a word
14237 break, you can use \code{\ics{MFUwordbreak}\margm{char}}. For
14238 example:
14239 \begin{codeenv}
14240 \field{name}=\marg{some word\cs{MFUwordbreak}\marg{/}phrase}
14241 \end{codeenv}
14242
14243 \end{itemize}
14244
14245 If you need to selectively change the case, based on some condition
14246 (such as the \gls{entrytype}) then you can use the
14247 \csopt{assign-fields} option instead, but remember that you will
14248 need the override setting on. For example:
14249 \begin{codeenv}
14250 \csopt[
14251 \field{name} =\oarg{o} \gls{TITLE}\marg{ \field{name} }
14252 \oarg{ entrytype \idx{follow} original = \qtdelim{entry} }
14253 ]{assign-fields}
14254 \end{codeenv}
14255 This will convert the \field{name} field to \idx{titlecase} for
14256 entries that were defined in the \ext{bib} file with
14257 \atentry{entry}. Note that if you also use a case-changing option,
14258 for example, \csopt{name-case-change}, then all entries will have
14259 the change applied, according to the option's designated behaviour,
14260 regardless of whether or not the applicable field has already been
14261 altered by \csopt{assign-fields}.
14262
14263 \begin{important}
14264 Major changes have been introduced to \sty{mfirstuc} v2.08. Some of
14265 the information below refers to older versions and is not
14266 applicable with \sty{mfirstuc} v2.08+. See the \sty{mfirstuc} manual
14267 for further details.
14268 \end{important}
14269
14270 The \optfmt{firstuc-cs} and \optfmt{firstuc} options are essentially
14271 a \idx{sentencecase} change, but there's no check for
14272 sentence-breaks within the value, so even if the value contains
14273 multiple sentences, only the first is changed. If the text to be
14274 changed starts with a punctuation character it should be
14275 encapsulated with \ics{MFUskippunc} to apply the case-change to the
14276 following object. For example:
14277 \begin{codeenv}
14278 \field{name}=\marg{\cs{MFUskippunc}\marg{'}tis}
14279 \end{codeenv}
14280 If the \optfmt{firstuc} option is applied to the \field{name} field
14281 this will be converted to:
14282 \begin{codeenv}
14283 \field{name}=\marg{\cs{MFUskippunc}\marg{'}Tis}
14284 \end{codeenv}
14285 Using \ics{NoCaseChange} (provided by \sty{textcase}) instead will have the
14286 same effect, but this isn't consistent with the behaviour of
14287 \ics{makefirstuc} so it's best to use \cs{MFUskippunc} instead.
14288
14289 The \optfmt{\meta{option}-cs} settings defer the actual case-changing
14290 to \TeX, which means that the case-changing has to be applied every
14291 time the field is typeset (and it introduces non-expandable content
14292 to the field value). Be aware of the limitations of using any of the
14293 case-changing commands. See the \isty{textcase} and \isty{mfirstuc}
14294 package documentation for further details~\cite{textcase,mfirstuc}.
14295
14296 For the settings where \bibgls\ itself performs the \idx{case-change}, then
14297 \bibgls\ will iterate over each token of the field value and apply
14298 the rules listed below. Note that the case-change implemented by
14299 \bibgls\ recognises the \gls{resource-locale}, but whether or not it
14300 recognises the correct rules for the locale depends on whether or
14301 not the locale is correctly supported by the Java locale provider.
14302
14303 \begin{enumerate}
14304
14305 \item If the token is a normal Unicode alphabetic character, it will
14306 be replaced with the corresponding upper or lower case character, as
14307 appropriate. In some cases, a single character, such as \ss, is
14308 replaced by multiple characters, such as SS.
14309
14310 For \optfmt{title} and \optfmt{firstuc}, the \idx{titlecase} character is
14311 used as the replacement, for \optfmt{uc} the \idx{uppercase} character is
14312 used as the replacement, and for \optfmt{lc} the \idx{lowercase} character
14313 is used as the replacement. Many characters have the same upper and
14314 title case alternative (for example, \qt{a} will be converted to \qt{A}
14315 for the \optfmt{title}, \optfmt{firstuc} and \optfmt{uc} settings), but
14316 some characters have different title and upper versions (for example,
14317 the digraph \qt{\char"01F3} has the title version \qt{\char"01F2}
14318 and \idx{uppercase} version \qt{\char"01F1}).
14319
14320 If the option is \optfmt{firstuc} then all the remaining tokens are
14321 skipped. If the option is \optfmt{title} then the subsequent tokens
14322 are skipped until a word-boundary is found.
14323
14324 \item If the token is a normal Unicode character that isn't alphabetical,
14325 then this token will be skipped for all options.
14326
14327 \item If \code{\idx{mshiftchar}\meta{maths}\idx{mshiftchar}} is
14328 encountered, it will be skipped. If the option is \optfmt{firstuc}
14329 then all remaining tokens are skipped, so no \idx{case-change} will be
14330 performed.
14331
14332 \item\label{case-change-group} If a group \code{\margm{content}} is
14333 found, then the \idx{case-change} is applied to the entire \meta{content}
14334 (which may be empty). This corresponds to the way \ics{makefirstuc}
14335 and \ics{capitalisewords} work if a~word starts with a group. Note
14336 that with \optfmt{firstuc} and \optfmt{title} the group content will
14337 be converted according to \optfmt{uc}, so the normal \idx{uppercase}
14338 character is used rather than the title case character (if they are
14339 different).
14340
14341 If the option is \optfmt{firstuc} then all the remaining tokens are
14342 skipped. If the option is \optfmt{title} then the subsequent tokens
14343 are skipped until a word-boundary is found. A word-boundary can be
14344 marked up with \ics{MFUwordbreak}.
14345
14346 \item If a control sequence \csfmt{}\meta{csname} is found, then:
14347
14348 \begin{enumerate}
14349 \item If the control sequence is \cs{protect}, this token is skipped
14350 for all options.
14351
14352 \item With \optfmt{firstuc} and \optfmt{title}, if
14353 \code{\ics{MFUskippunc}\margm{text}} or \code{\ics{NoCaseChange}\margm{text}}
14354 occurs at the start of a word, then \bibgls\ will act as though
14355 the word hasn't started yet (so the next token will be considered
14356 for a \idx{case-change}).
14357
14358 \item If the control sequence is one of: \ics{o}, \ics{O}, \ics{l},
14359 \ics{L}, \ics{ae}, \ics{AE}, \ics{oe}, \ics{OE}, \ics{aa}, \ics{AA},
14360 \ics{ss}, \ics{SS}, \ics{ng}, \ics{NG}, \ics{th}, \ics{TH},
14361 \ics{dh}, \ics{DH}, \ics{dj} or \ics{DJ}, then
14362 it's replaced with its \idx{case-change} counterpart (if not already the
14363 correct case).
14364
14365 If the option is \optfmt{firstuc} then all the remaining tokens are
14366 skipped. If the option is \optfmt{title} then the subsequent tokens
14367 are skipped until a word-boundary is found.
14368
14369 \item If the control sequence is in the \csopt{no-case-change-cs}
14370 list or is \ics{ensuremath}, \ics{si} or if
14371 \meta{csname} ends with \qtt{ref} (for example, \ics{ref} or
14372 \ics{pageref}) then the control sequence and its argument is
14373 ignored. In the case where \meta{csname} ends with \qtt{ref}, a
14374 following star (\code{*}) or optional argument before the mandatory
14375 argument will also be skipped. This allows for some common
14376 cross-referencing commands, such as \sty{hyperref}['s]
14377 \ics{autoref}, which may have a starred form, but does not allow for
14378 more complicated commands with multiple arguments.
14379
14380 If the option is \optfmt{firstuc} then all the remaining tokens are
14381 skipped (so no \idx{case-change} will be performed). If the option is
14382 \optfmt{title} then the subsequent tokens
14383 are skipped until a word-boundary is found (so no \idx{case-change} is
14384 performed for this word).
14385
14386 \item If the control sequence is \ics{glsentrytitlecase} then:
14387 \begin{description}
14388 \item[\optfmt{lc}] the control sequence is converted to
14389 \ics{glsxtrusefield};
14390 \item[\optfmt{uc}] the control sequence is converted to
14391 \ics{GLSxtrusefield};
14392 \item[\optfmt{firstuc}] the control sequence is converted to
14393 \ics{Glsxtrusefield} and the remaining tokens are skipped;
14394 \item[\optfmt{title}] the control sequence is left unchanged
14395 and subsequent tokens are skipped until a word-boundary is found.
14396 \end{description}
14397 The field and entry label arguments are skipped.
14398
14399 \item If the control sequence is \ics{glshyperlink} then the
14400 \idx{case-change} is applied to its optional argument. (If there was no
14401 optional argument in the original field value, one will be inserted.)
14402 The label argument is skipped.
14403
14404 If the option is \optfmt{firstuc} then all the remaining tokens are
14405 skipped. If the option is \optfmt{title} then the subsequent tokens
14406 are skipped until a word-boundary is found.
14407
14408 \item If the control sequence is \ics{glsdisp}, \ics{glslink},
14409 \ics{dglsdisp} or \ics{dglslink} then the \idx{case-change} will be
14410 applied to the appropriate argument. The optional argument (if
14411 present) and the label are skipped.
14412
14413 If the option is \optfmt{firstuc} then all the remaining tokens are
14414 skipped. If the option is \optfmt{title} then the subsequent tokens
14415 are skipped until a word-boundary is found.
14416
14417 \item If the control sequence has a known case variant, it will be
14418 substituted. For example, \ics{gls} will be changed to \ics{Gls}
14419 or \ics{GLS}. In some cases there isn't an appropriate variant.
14420 For example, \ics{glsentrytext} has a first-letter upper case
14421 version \ics{Glsentrytext}, but not an all-caps version.
14422
14423 If the option is \optfmt{firstuc} then all the remaining tokens are
14424 skipped. If the option is \optfmt{title} then the subsequent tokens
14425 are skipped until a word-boundary is found.
14426
14427 \item If the control sequence is followed by a group, then the
14428 appropriate \idx{case-change} is applied to the group contents.
14429 Unlike step~\ref{case-change-group}, the \idx{case-change} isn't
14430 applied to the entire group content with \optfmt{firstuc} and
14431 \optfmt{title}. (Again, this follows the way that
14432 \ics{makefirstuc} and \ics{capitalisewords} work.)
14433
14434 If there are subsequent groups, they won't be considered arguments,
14435 but will be treated as groups, as per step~\ref{case-change-group}.
14436 (This will only affect the \optfmt{title} setting as they will be
14437 skipped by the \optfmt{firstuc} setting.) For complex cases,
14438 consider using a semantic command that hides non-textual context
14439 such as the \csfmt{strong} example described on page~\glsxtrpageref{strong}.
14440
14441 \item Otherwise the control sequence is skipped.
14442 \end{enumerate}
14443
14444 \item Anything else is skipped.
14445
14446 \end{enumerate}
14447
14448 For example, if an entry is defined as:
14449 \begin{codeenv}
14450 \atentry{abbreviation}\marg{html,
14451 \field{short} = \marg{HTML},
14452 \field{long} = \marg{hypertext markup language},
14453 \field{description}=\marg{a markup language for creating web pages}
14454 }
14455 \end{codeenv}
14456 then:
14457 \begin{codeenv}
14458 \gls{GlsXtrLoadResources}\oarg{
14459 \csopt[lc]{short-case-change},
14460 \csopt[title]{long-case-change},
14461 \csopt[firstuc]{description-case-change}
14462 }
14463 \end{codeenv}
14464 will make the entry behave as if it had been defined as:
14465 \begin{codeenv}
14466 \atentry{abbreviation}\marg{html,
14467 \field{short} = \marg{html},
14468 \field{long} = \marg{Hypertext Markup Language},
14469 \field{description}=\marg{A markup language for creating web pages}
14470 }
14471 \end{codeenv}
14472 whereas:
14473 \begin{codeenv}
14474 \gls{GlsXtrLoadResources}\oarg{
14475 \csopt[lc-cs]{short-case-change},
14476 \csopt[title-cs]{long-case-change},
14477 \csopt[firstuc-cs]{description-case-change}
14478 }
14479 \end{codeenv}
14480 will make the entry behave as if it had been defined as:
14481 \begin{codeenv}
14482 \atentry{abbreviation}\marg{html,
14483 \field{short} = \marg{\gls{bibglslowercase}\marg{HTML}},
14484 \field{long} = \marg{\gls{bibglstitlecase}\marg{hypertext markup language}},
14485 \field{description}=\marg{\gls{bibglsfirstuc}\marg{a markup language for creating web pages}}
14486 }
14487 \end{codeenv}
14488 If the given field is missing, no change is made, except under
14489 certain circumstances (see the relevant resource option for details).
14490 For example, if an abbreviation is simply defined as:
14491 \begin{codeenv}
14492 \atentry{abbreviation}\marg{html,
14493 \field{short} = \marg{html},
14494 \field{long} = \marg{hypertext markup language}
14495 }
14496 \end{codeenv}
14497 then:
14498 \begin{codeenv}
14499 \gls{GlsXtrLoadResources}\oarg{
14500 \csopt[uc]{name-case-change},
14501 \csopt[title]{description-case-change}
14502 }
14503 \end{codeenv}
14504 won't have an effect. Although the default \abbrstyle{long-short} abbreviation
14505 style sets the \field{name} and \field{description} fields, \bibgls\ doesn't
14506 have access to this information.
14507
14508 Remember that you can create missing fields by copying the value
14509 from another field. So if the resource options are changed to:
14510 \begin{codeenv}
14511 \gls{GlsXtrLoadResources}\oarg{
14512 \csopt[uc]{name-case-change},
14513 \csopt[title]{description-case-change},
14514 \csopt[\field{short}=\field{name},\field{long}=\field{description}]{replicate-fields}
14515 }
14516 \end{codeenv}
14517 then \bibgls\ will act as though the entry had been defined as:
14518 \begin{codeenv}
14519 \atentry{abbreviation}\marg{html,
14520 \field{short} = \marg{html},
14521 \field{long} = \marg{hypertext markup language},
14522 \field{name} = \marg{HTML},
14523 \field{description} = \marg{Hypertext Markup Language}
14524 }
14525 \end{codeenv}
14526 If the \abbrstyle{long-short-sc} abbreviation style is set (before
14527 \gls{GlsXtrLoadResources}) then this will override the default style
14528 for the \field{name} and \field{description}, so
14529 \code{\cs{gls}\marg{html}} will display the short form using
14530 \code{\ics{textsc}\marg{html}} but the \field{name} in the glossary
14531 will be displayed using just \code{HTML}.
14532
14533 Note that with \atentry{index} the \field{name} and \field{text}
14534 fields will automatically be created if they are missing and
14535 \csopt{name-case-change} is used. For example, if an entry is
14536 defined as:
14537 \begin{codeenv}
14538 \atentry{index}\marg{duck}
14539 \end{codeenv}
14540 then \csopt[firstuc]{name-case-change} will make this entry behave
14541 as though it was defined as:
14542 \begin{codeenv}
14543 \atentry{index}\marg{duck,
14544 \field{name} = \marg{Duck},
14545 \field{text} = \marg{duck}
14546 }
14547 \end{codeenv}
14548
14549 Suppose I have a slightly eccentric abbreviation definition:
14550 \begin{codeenv}
14551 \atentry{abbreviation}\marg{html,
14552 \field{short} = \qtdelim{ht\cs{emph}\marg{ml}},
14553 \field{long} = \qtdelim{hypertext markup language}
14554 }
14555 \end{codeenv}
14556 then \csopt[uc]{short-case-change} would convert the value of the
14557 \field{short} field into:
14558 \begin{codeenv}
14559 HT\cs{emph}{ML}
14560 \end{codeenv}
14561 Note that \csfmt{emph} isn't modified as it's recognised as a
14562 command. There's a difference between a group that follows a control
14563 sequence and one that doesn't. For example:
14564 \begin{codeenv}
14565 \atentry{abbreviation}\marg{html,
14566 \field{short} = \qtdelim{\marg{ht}ml},
14567 \field{long} = \qtdelim{hypertext markup language}
14568 }
14569 \end{codeenv}
14570 In this case \csopt[firstuc]{short-case-change} will convert the
14571 \field{short} field value to:
14572 \begin{codeenv}
14573 \marg{HT}ml
14574 \end{codeenv}
14575 (The entire contents of the group \code{\marg{ht}} has been
14576 converted.) Whereas with:
14577 \begin{codeenv}
14578 \atentry{abbreviation}\marg{html,
14579 \field{short} = \qtdelim{\cs{emph}\marg{ht}ml},
14580 \field{long} = \qtdelim{hypertext markup language}
14581 }
14582 \end{codeenv}
14583 then \csopt[firstuc]{short-case-change} will convert the
14584 \field{short} field value to:
14585 \begin{codeenv}
14586 \cs{emph}\marg{Ht}ml
14587 \end{codeenv}
14588 (Only the first letter of the argument \code{\marg{ht}} has been
14589 converted.)
14590
14591 There's no attempt at interpreting the field contents at this point (but
14592 the value may later be interpreted during sorting).
14593 For example, suppose a \field{name} field is defined using:
14594 \begin{codeenv}
14595 \field{name} = \qtdelim{z\ics{ae}\ics{oe}},
14596 \end{codeenv}
14597 then with \csopt[uc]{name-case-change}, the value would be converted to
14598 \begin{codeenv}
14599 Z\ics{AE}\ics{OE}
14600 \end{codeenv}
14601 because \cs{ae} and \cs{oe} have known \idx{uppercase} versions.
14602
14603 With \csopt[uc-cs]{name-case-change}, the \field{name}
14604 value would be converted to:
14605 \begin{codeenv}
14606 \gls{bibglsuppercase}\marg{z\cs{ae}\cs{oe}}
14607 \end{codeenv}
14608 If the interpreter is used during sorting, the sort value will be set to
14609 \code{Z\AE\OE} because the interpreter recognises all three commands.
14610
14611 You can use \code{\ics{NoCaseChange}\margm{text}} to prevent the given
14612 \meta{text} from having the case changed. For example, if the \field{short}
14613 field is defined as:
14614 \begin{codeenv}
14615 \field{short} = \marg{a\cs{NoCaseChange}\marg{bc}d}
14616 \end{codeenv}
14617 then with \csopt[uc]{short-case-change}, this would be converted to
14618 \begin{codeenv}
14619 A\cs{NoCaseChange}\marg{bc}D
14620 \end{codeenv}
14621
14622 Note that with \optfmt{firstuc} and \optfmt{title}, if
14623 \code{\ics{MFUskippunc}\margm{text}} occurs at the start of a word
14624 then it's skipped, and the case change is
14625 applied to the material following its argument. For example,
14626 suppose the \field{short} field is defined as:
14627 \begin{codeenv}
14628 \field{short}=\marg{\cs{MFUskippunc}\marg{h}tml}
14629 \end{codeenv}
14630 then the result is:
14631 \begin{codeenv}
14632 \cs{MFUskippunc}\marg{h}Tml
14633 \end{codeenv}
14634 whereas with:
14635 \begin{codeenv}
14636 \field{short}=\marg{\marg{}html}
14637 \end{codeenv}
14638 then the result is just \code{\marg{}html} (since the case change is
14639 applied to the empty group, which has no effect).
14640
14641 If you have a command that takes a label or identifier as an argument then it's
14642 best to hide the label in a custom command. For example, if the
14643 \field{short} field in the \ext{bib} definition is defined as:
14644 \begin{codeenv}
14645 \field{short} = \qtdelim{ht\ics{textcolor}\marg{red}\marg{ml}},
14646 \end{codeenv}
14647 then with \csopt[uc]{short-case-change} this would end up as:
14648 \begin{codeenv}
14649 HT\cs{textcolor}\marg{RED}\marg{ML}
14650 \end{codeenv}
14651 which is incorrect. Instead, provide a command that hides the label
14652 (such as the \csfmt{strong} example described on page~\glsxtrpageref{strong}).
14653
14654 \optsection[\subsubsection]{no-case-change-cs}
14655
14656 Instructs the non-\TeX\ case-changing options (where \bibgls, not
14657 \TeX, performs the modification) to treat the commands whose control
14658 sequence names are given in the comma-separated \meta{list} in the
14659 same way as it treats \cs{ensuremath} etc. That is, the case-change
14660 is omitted for the argument that follows any of those commands.
14661
14662 For example, this manual defines some semantic commands such as
14663 \csfmt{fieldfmt} (to format field names), \csfmt{abbrstylefmt}
14664 (to format abbreviation style names) and \csfmt{glostylefmt} (to format
14665 glossary style names). If any these occur in section
14666 and subsection headings (which are converted to \idx{titlecase})
14667 then the case-change would produce an inappropriate result.
14668 These formatting commands shouldn't have their argument changed so they
14669 are identified with:
14670 \begin{codeenv}
14671 \csopt[fieldfmt,abbrstylefmt,glostylefmt]{no-case-change-cs}
14672 \end{codeenv}
14673
14674 \optsection[\subsubsection]{word-boundaries}
14675
14676 Governs how the \optfmt{title} \idx{case-change} option
14677 determines word boundaries. The \meta{list} must contain one or
14678 more of the following keywords:
14679 \begin{description}
14680 \item[\optfmt{white space}] any white space Unicode character
14681 that is not a non-breakable space indicates a word-boundary;
14682 \item[\optfmt{cs space}] the control sequences
14683 \ics{space} or \ics{cs.space} indicate a word-boundary;
14684 \item[\optfmt{dash}] a Unicode character that belongs to the
14685 \idx{punctuationdash} block indicates a word-boundary;
14686 \item[\optfmt{nbsp}] the \idx{nbspchar} active character or the Unicode
14687 non-breakable characters \hex{00A0}, \hex{2007} and \hex{202F}
14688 indicate a word-boundary.
14689 \end{description}
14690 Any keyword that is not listed indicates that particular setting is off. This
14691 option is not cumulative. Any subsequent use of
14692 \csopt{word-boundaries} within the same set of resource options will
14693 override previous settings.
14694
14695 The default setting is \csopt[white space,cs
14696 space]{word-boundaries}, which excludes non-breakable
14697 spaces and dashes.
14698
14699 Note that you can explicitly markup word-boundary punctuation using
14700 \ics{MFUwordbreak}. For example:
14701 \begin{codeenv*}
14702 \field{name} = \marg{a book of rhyme\cs{MFUwordbreak}\marg{/}verse}
14703 \end{codeenv*}
14704
14705 \optsection[\subsubsection]{short-case-change}
14706
14707 Applies a case-change to the \field{short} field (if present).
14708 This option may take one of the values described above.
14709
14710 See \csopt{dual-short-case-change} to adjust the \field{dualshort}
14711 field.
14712
14713 \optsection[\subsubsection]{long-case-change}
14714
14715 Applies a case-change to the \field{long} field (if present).
14716 This option may take one of the values described above.
14717
14718 See \csopt{dual-long-case-change} to adjust the \field{duallong}
14719 field.
14720
14721 \optsection[\subsubsection]{name-case-change}
14722
14723 Applies a case-change to the \field{name} field.
14724 This option may take one of the values described above.
14725
14726 If the \field{text} field hasn't been set, the \field{name} value is
14727 first copied to the \field{text} field. If the \field{name} field
14728 hasn't been set (for example, with the \atentry{index}
14729 \gls{entrytype}), it's copied from the fallback value (which depends
14730 on the \gls{entrytype}, see \sectionref{sec:fallbacks}) unless the
14731 \gls{entrytype} is \atentry{abbreviation} or \atentry{acronym}, in
14732 which case if the \field{name} field is missing no action is
14733 performed.
14734
14735 \optsection[\subsubsection]{description-case-change}
14736
14737 Applies a case-change to the \field{description} field (if present).
14738 This option may take one of the values described above.
14739
14740 \optsection[\subsubsection]{field-case-change}
14741
14742 A general case-change instruction. The value should be a
14743 comma-separated list of \code{\meta{field}\dequals\meta{setting}} for each
14744 field that needs a case-change applied. The value is required for this key but
14745 may be empty, which indicates this option is switched off.
14746
14747 The \meta{setting} should be
14748 the same as the permitted values for the above options. This
14749 option is applied after all fields have been parsed but before
14750 \csopt{interpret-fields}. If the
14751 specified field is missing, the fallback for that field (if known,
14752 see \sectionref{sec:fallbacks}) is copied
14753 into the field. For example:
14754 \begin{codeenv}
14755 \csopt[\field{user1}=uc,\field{user2}={firstuc}]{field-case-change}
14756 \end{codeenv}
14757 This manual provides a custom storage key called
14758 \fieldfmt{nametitle}:
14759 \begin{codeenv}
14760 \cs{glsxtrprovidestoragekey}\marg{\fieldfmt{nametitle}}\marg{}\marg{}
14761 \end{codeenv}
14762 The resource options copy the \field{name} value to this custom
14763 field and convert \fieldfmt{nametitle} to \idx{titlecase}:
14764 \begin{codeenv}
14765 \csopt[\field{name}=\fieldfmt{nametitle}]{replicate-fields},
14766 \csopt[\fieldfmt{nametitle}=title]{field-case-change},
14767 \end{codeenv}
14768 This means that it's possible to fetch the value of
14769 \fieldfmt{nametitle} instead of \field{name}, which provides an
14770 expandable \idx{titlecase} form that's suitable for the PDF
14771 bookmarks. (Note that \LaTeX3 now provides some expandable
14772 case-changing commands.)
14773
14774 This option isn't cumulative. If used multiple times in the same
14775 \igls{resourceset}, the last instance will be the one used. If
14776 the \keyvallist\ is missing, no general case-changing is applied
14777 (the default).
14778
14779 \section{Field Fallbacks}
14780 \label{sec:fallbacks}
14781
14782 The options in this section don't modify any field values but
14783 provide instructions on what to do if \bibgls\ wants to know the
14784 value of a field where the field hasn't been explicitly set. The most common
14785 case is querying the \field{sort} field value with the default
14786 \csopt[\field{sort}]{sort-field} setting. Being able to vary the
14787 fallback used according to the \gls{entrytype} allows a more flexible
14788 approach than explicitly setting the \field{sort} field in the
14789 \ext{bib} file.
14790
14791 Note that if you specify a different field to use for the sort value
14792 with \csopt{sort-field} then the fallback for that field will be used
14793 if that field is missing. The \field{sort} fallbacks will be
14794 irrelevant if the \field{sort} field isn't being queried. If the
14795 fallback system fails to provide a value for the field identified by
14796 \csopt{sort-field} then \bibgls\ will follow the rule given by the
14797 \csopt{missing-sort-fallback} setting.
14798
14799 If you require a complex sort value that can't be implemented by the
14800 fallback system, you can use \csopt{assign-fields} to explicitly set
14801 the \field{sort} field to a string expression
14802 (\sectionref{sec:optstringconcat}). Bear in mind that if the
14803 \field{sort} field is actually set to a value, either in the
14804 \ext{bib} file or through resource options, then \emph{the
14805 \field{sort} fallback won't be used} and the sort fallback options
14806 describe in this section won't have any effect.
14807
14808 There are other fields that \bibgls\ may want to query that won't
14809 necessarily be set in the \ext{bib} file but may be inferred from
14810 another field. For example, if the \field{sort} field fallback
14811 references the \field{name} field then the \field{name} field will
14812 also need a fallback if it hasn't been set.
14813
14814 Another possibility is that the interpreter encounters content that
14815 includes commands such as \ics{gls}. Since the interpreter can't
14816 tell at what point in the document the first use flag is changed,
14817 \ics{gls} is treated as \ics{glstext} (and similarly \ics{glspl} is
14818 treated as \ics{glsplural}) so the \field{text} (or \field{plural})
14819 field will be queried by the interpreter.
14820
14821 The commands \ics{newglossaryentry} and \ics{longnewglossaryentry}
14822 are the foundation for all commands that define glossary entries.
14823 These commands both require that either the \field{name} or the
14824 \field{parent} field are set. If the \field{name} is omitted, then
14825 its value is obtained from the \gls{parententry}['s] name. The
14826 \field{description} must also be provided but may be set to empty.
14827 (Some entry types, such as \atentry{index}, will set
14828 \field{description} to empty if that field is missing, but for other
14829 entry types, such as \atentry{entry}, the \field{description} is
14830 required and will trigger a warning if omitted.)
14831
14832 All other entry definition commands, such as \ics{newabbreviation} and
14833 \ics{glsxtrnewsymbol}, internally use one of those foundation
14834 commands.\footnote{Or the internal command that both
14835 \cs{newglossaryentry} and \cs{longnewglossaryentry} use.} In the
14836 case of \ics{newabbreviation} (and \ics{newacronym}), the
14837 \field{name} field is set by the style using values obtained from
14838 the \field{short} and\slash or \field{long} fields. This is
14839 information that \bibgls\ is unaware of and may guess incorrectly
14840 when trying to determine an appropriate value for the \field{name}
14841 field if it is omitted (which is typically the case) from
14842 abbreviation entry types, such as \atentry{abbreviation} or
14843 \atentry{acronym}.
14844
14845 The general \atentry{entry} entry type, uses the same rules as
14846 \ics{newglossaryentry}:
14847 \begin{description}
14848 \item[\field{name}] If the \field{parent} field has been set, then
14849 the parent's \field{name} field is used. If the parent's
14850 \field{name} field isn't set, then the fallback for the parent's
14851 \field{name} field is used (which will depend on the parent's
14852 \gls{entrytype}). If neither the \field{name} nor the \field{parent}
14853 field is set, then a warning is issued since at least one of those
14854 fields must be set for \atentry{entry}.
14855
14856 \item[\field{text}] If the \field{text} field is missing, it's
14857 obtained from the \field{name} field or the fallback for the
14858 \field{name} field, if that hasn't been set.
14859
14860 \item[\field{plural}] If the \field{name} field has been set then
14861 the \field{plural} value is obtained by appending \ics{glspluralsuffix}
14862 to the value of the \field{text} field (or the fallback for the
14863 \field{text} field, if that hasn't been set).
14864
14865 If the \field{name} field hasn't been set but the \field{parent}
14866 field has been set, then the \field{plural} is obtained from the
14867 parent's \field{plural} field. If the parent's \field{plural} field
14868 hasn't been set then the fallback for that value will be used,
14869 according to the parent's \gls{entrytype}.
14870
14871 \item[\field{first}] The fallback for the \field{first} field is
14872 obtained from the \field{text} field (or the fallback for the
14873 \field{text} field, if that hasn't been set).
14874
14875 \item[\field{firstplural}] The fallback for the \field{firstplural}
14876 field is obtained by appending \ics{glspluralsuffix} to the value of
14877 the \field{first} field, if that field has been set, otherwise it's
14878 obtained from the \field{plural} field (or the fallback for the
14879 \field{plural} field if that isn't set).
14880
14881 \end{description}
14882
14883 Note that although \bibgls\ follows the \ics{newglossaryentry} rules
14884 in order to obtain the fallback, it doesn't explicitly set those
14885 fields in the \ext{glstex} file if they weren't provided in the
14886 \ext{bib} file or set using options such as \csopt{replicate-fields}
14887 or \csopt{assign-fields}.
14888
14889 The exception to this is the \field{sort} field, which will be
14890 obtained from the \field{name} field for most \glspl{entrytype} unless
14891 overridden by one of the applicable sort fallback options, such as
14892 \csopt{entry-sort-fallback}. If the designated fallback (such as
14893 \field{name}) is missing, then the fallback value for that field
14894 will be used.
14895
14896 The \atentry{index} and \atentry{indexplural} entry types are
14897 slightly different. They have their own rules for obtaining the
14898 value of the \field{name} field, and will explicitly set it in the
14899 \ext{glstex} file via the helper commands \gls{bibglsnewindex}
14900 and \gls{bibglsnewindexplural}.
14901
14902 In the case of \atentry{index}, if the \field{name} field is
14903 missing, its value will be obtained from the entry's original label.
14904 If the \field{sort} field is missing, its value is obtained from the
14905 \field{name} field unless a different fallback is specified with
14906 \csopt{custom-sort-fallbacks}. The remaining fallbacks are as for
14907 \atentry{entry}.
14908
14909 It's more complicated for \atentry{indexplural}, which has the following
14910 fallback rules:
14911 \begin{description}
14912 \item[\field{name}] If the \field{name} field is missing, its value
14913 is obtained from the entry's \field{plural} field (or the fallback
14914 for the \field{plural} field, if that field is missing).
14915
14916 \item[\field{plural}] If the \field{plural} field is missing, its
14917 value is obtained by appending \ics{glspluralsuffix} to the value
14918 of the \field{text} field (or the fallback for the \field{text}
14919 field, if that field is missing).
14920
14921 \item[\field{text}] If the \field{text} field is missing, its value
14922 is obtained from the entry's original label.
14923
14924 \item[\field{sort}] If the \field{sort} field is missing, its value
14925 is obtained from the \field{name} field unless a different fallback
14926 is specified with \csopt{custom-sort-fallbacks}.
14927 \end{description}
14928 The remaining fallbacks are as for \atentry{entry}.
14929
14930 The most awkward of all the \glspl{entrytype} are, as indicated earlier,
14931 the abbreviations where the field values such as \field{name} and
14932 \field{text} are set by the abbreviation style. Therefore, there are resource
14933 options specifically to identify the most appropriate fallback
14934 values for abbreviations. The default is to use the value of the
14935 \field{short} field as the fallback for the \field{name},
14936 \field{sort} and \field{text} fields. If this is inappropriate for
14937 your abbreviation style then you will need to use the options listed below to
14938 provide more appropriate fallbacks. These options don't actually set
14939 the \field{name} and \field{text} fields in the \ext{glstex} file
14940 and don't include any style formatting (such as font changing
14941 commands), which are irrelevant to \bibgls.\footnote{The \field{sort} field
14942 will be set in the \ext{glstex} file as it's useful for debugging,
14943 but it's typically irrelevant.}
14944
14945 For other entry types, see their description in \sectionref{sec:bib}.
14946
14947 \optsection{abbreviation-name-fallback}
14948
14949 The \glspl{entrytype} that define abbreviations (such as
14950 \atentry{abbreviation} and \atentry{acronym}) will, by default,
14951 fallback on the \field{short} field if the \field{name} field is
14952 missing and it's required for some reason (for example, with
14953 \csopt[name]{sort-field}). If you prefer to
14954 fallback on a different field, then you can use this option to
14955 specify the field. For example,
14956 \csopt[long]{abbreviation-name-fallback}.
14957 The \meta{field} value must be a known field (not an internal field)
14958 but can't be the \field{sort} field.
14959
14960 Note that the default fallback for the \field{sort} field for
14961 abbreviations is given by \csopt{abbreviation-sort-fallback} which
14962 is set to \field{short} not \field{name} by default. So changing the
14963 fallback for the \field{name} field won't have an effect unless the
14964 \field{sort} fallback is changed to \field{name} or
14965 \csopt[\field{name}]{sort-field} is used or the \field{name} field
14966 is referenced in an option such as \csopt{assign-fields}.
14967
14968 Field concatenation isn't available for this option.
14969
14970 \optsection{abbreviation-text-fallback}
14971
14972 Similar to \csopt{abbreviation-name-fallback} but for the
14973 \field{text} field. The default fallback is the \field{short} field.
14974 Field concatenation isn't available for this option.
14975
14976 Note that you can't have both
14977 \csopt[\field{text}]{abbreviation-name-fallback} and
14978 \csopt[\field{name}]{abbreviation-text-fallback} as it would cause
14979 an infinite loop.
14980
14981 \optsection{abbreviation-sort-fallback}
14982
14983 The \glspl{entrytype} that define abbreviations (such as
14984 \atentry{abbreviation} and \atentry{acronym}) will, by default,
14985 fallback on the \field{short} field if the \field{sort} field is
14986 missing (assuming \csopt[sort]{sort-field}). If you prefer to
14987 fallback on a different field, then you can use this option to
14988 specify the field. For example,
14989 \csopt[long]{abbreviation-sort-fallback}. Note that if you use
14990 \csopt[name]{sort-field}, then the fallback field will be given by
14991 \csopt{abbreviation-name-fallback} if the \field{name} field is
14992 omitted.
14993
14994 The \meta{field} may be a known field but not an internal
14995 field. It can't be the \field{sort} field. It may also be
14996 one of the keywords: \optfmt{id} (for the entry's label) or
14997 \optfmt{original id} (for the entry's original label). The
14998 \meta{field} may also be a composite in the form
14999 \optfmt{\meta{field1}+\meta{field2}+\ldots} which indicates that the
15000 sort value should be obtained by concatenating the values of given fields,
15001 where the separator is given by \csopt{field-concat-sep}.
15002
15003 Note that \csopt{missing-sort-fallback} and
15004 \csopt{custom-sort-fallbacks} override this setting.
15005
15006 \begin{important}
15007 The \csopt{abbreviation-sort-fallback} setting is only used when \bibgls\
15008 tries to access the \field{sort} field for an abbreviation and finds
15009 that the field hasn't been set. This means that this setting has no effect
15010 if you explicitly set the \field{sort} field or if you change the field used
15011 for sorting (\csopt{sort-field}).
15012 \end{important}
15013
15014 \optsection{entry-sort-fallback}
15015
15016 The regular \glspl{entrytype} (such as \atentry{entry} and
15017 \atentry{dualentry}) will, by default, fallback on the \field{name}
15018 field if the \field{sort} field is missing (assuming
15019 \csopt[sort]{sort-field}). If you prefer to
15020 fallback on a different field, then you can use this option to
15021 specify the field.
15022 Note that \csopt{missing-sort-fallback} and
15023 \csopt{custom-sort-fallbacks} override this setting.
15024
15025 The \meta{field} may be a known field but not an internal
15026 field. It can't be the \field{sort} field. It may also be
15027 one of the keywords: \optfmt{id} (for the entry's label) or
15028 \optfmt{original id} (for the entry's original label). The
15029 \meta{field} may also be a composite in the form
15030 \optfmt{\meta{field1}+\meta{field2}+\ldots} which indicates that the
15031 sort value should be obtained by concatenating the values of given fields,
15032 where the separator is given by \csopt{field-concat-sep}.
15033
15034 This setting doesn't affect the index type of entries, such as
15035 \atentry{index} or \atentry{indexplural}. This is useful if your
15036 glossary contains \iglspl{homograph} (terms with the same spelling) which
15037 can't be distinguished by the sort comparators. For example, suppose
15038 my file \filefmt{entries.bib} contains:
15039 \begin{codeenv}
15040 \atentry{index}\marg{pagelist,
15041 \field{name}=\marg{page list},
15042 \field{description}=\marg{a list of individual pages or page ranges}
15043 }
15044 \strut
15045 \atentry{index}\marg{glossary}
15046 \strut
15047 \atentry{entry}\marg{glossarylist,
15048 \field{parent}=\marg{glossary},
15049 \field{description}=\marg{list of technical words}
15050 }
15051 \strut
15052 \atentry{entry}\marg{glosscol,
15053 \field{parent}=\marg{glossary},
15054 \field{description}=\marg{collection of glosses}
15055 }
15056 \end{codeenv}
15057 Now first consider a document that uses the default settings:
15058 \begin{codeenv}
15059 \cmd{documentclass}\marg{article}
15060 \strut
15061 \cmd{usepackage}\oarg{\styopt{record},\styopt{subentrycounter},\styopt[\glostyle{treenoname}]{style}}\marg{glossaries-extra}
15062 \strut
15063 \gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}}
15064 \strut
15065 \cmd{begin}\marg{document}
15066 A test document describing \cs{glspl}\marg{pagelist} and
15067 \cs{gls}\marg{glosscol} (collection) vs \cs{gls}\marg{glossarylist} (list).
15068 \strut
15069 \cs{printunsrtglossary}
15070 \cmd{end}\marg{document}
15071 \end{codeenv}
15072 The default behaviour for \atentry{entry} if the \field{sort} field
15073 is missing is to fallback on the \field{name} field. If the
15074 \field{name} field is missing (as with \code{glossarylist} and
15075 \code{glosscol}), then the value is obtained from the
15076 \field{name} field from the \gls{parententry}. The \gls{parententry} for these
15077 \glspl{homograph} is the \code{glossary} entry, which was defined with
15078 \atentry{index} and doesn't have the \field{name} field. For the
15079 \atentry{index} entries, if \field{name} is missing the value is
15080 obtained from the label.
15081
15082 Therefore both \code{glossarylist} and \code{glosscol} end
15083 up with the same sort value: \code{glossary}. This triggers a
15084 message in verbose mode (\commonlongarg{verbose}) which can be found
15085 in the transcript file:
15086 \begin{verbatim}
15087 Identical sort values for 'glossarylist' and 'glosscol'
15088 Falling back on ID
15089 \end{verbatim}
15090 So the actual sort values used are \qt{glossarylist} and
15091 \qt{glosscol}. This puts the \code{glossarylist} entry
15092 before the \code{glosscol} entry.
15093
15094 Now suppose a minor modification is made to the document:
15095 \begin{codeenv}
15096 \gls{GlsXtrLoadResources}
15097 \oarg{
15098 \csopt[entries]{src},
15099 \csopt[description]{entry-sort-fallback}
15100 }
15101 \end{codeenv}
15102 This means that when the sort function fails to find the
15103 \field{sort} field for the terms defined with \atentry{entry}, it
15104 will fallback on the \field{description} field. This doesn't affect
15105 the terms defined with \atentry{index}, which still fallback on the
15106 \field{name} field. This time there's no message in the transcript
15107 file and the \code{glosscol} entry now comes before the
15108 \code{glossarylist} entry.
15109
15110 \begin{important}
15111 The \csopt{entry-sort-fallback} setting is only used when \bibgls\
15112 tries to access the \field{sort} field for a term defined with
15113 \atentry{entry} and finds that the field hasn't been set. This means
15114 that this setting has no effect if you explicitly set the \field{sort}
15115 field or if you change the field used for sorting
15116 (\csopt{sort-field}).
15117 \end{important}
15118
15119 \optsection{symbol-sort-fallback}
15120
15121 The \glspl{entrytype} that define symbols (such as \atentry{symbol} and
15122 \atentry{number}) will, by default, fallback on the entry's original label if the
15123 \field{sort} field is missing (assuming the default
15124 \csopt[sort]{sort-field}). If you prefer to fallback on a different
15125 field, then you can use this option to specify the field. For
15126 example, \csopt[name]{symbol-sort-fallback}.
15127
15128 The \meta{field} may be a known field but not an internal
15129 field. It can't be the \field{sort} field. It may also be
15130 one of the keywords: \optfmt{id} (for the entry's label) or
15131 \optfmt{original id} (for the entry's original label). The
15132 \meta{field} may also be a composite in the form
15133 \optfmt{\meta{field1}+\meta{field2}+\ldots} which indicates that the
15134 sort value should be obtained by concatenating the values of given fields,
15135 where the separator is given by \csopt{field-concat-sep}.
15136
15137 Note that \csopt{missing-sort-fallback} and
15138 \csopt{custom-sort-fallbacks} override this setting.
15139
15140 \begin{important}
15141 The \csopt{symbol-sort-fallback} setting is only used when \bibgls\
15142 tries to access the \field{sort} field for a symbol and finds
15143 that the field hasn't been set. This means that this setting has no effect
15144 if you explicitly set the \field{sort} field or if you change the field used
15145 for sorting (\csopt{sort-field}).
15146 \end{important}
15147
15148 \optsection{bibtexentry-sort-fallback}
15149
15150 The \glsdisp{mainentry}{main} \atentry{bibtexentry}
15151 \glspl{entrytype} will, by default,
15152 fallback on the \field{name} if the
15153 \field{sort} field is missing (assuming the default
15154 \csopt[sort]{sort-field}). If you prefer to fallback on a different
15155 field, then you can use this option to specify the field.
15156
15157 The \meta{field} may be a known field but not an internal
15158 field. It can't be the \field{sort} field. It may also be
15159 one of the keywords: \optfmt{id} (for the entry's label) or
15160 \optfmt{original id} (for the entry's original label). The
15161 \meta{field} may also be a composite in the form
15162 \optfmt{\meta{field1}+\meta{field2}+\ldots} which indicates that the
15163 sort value should be obtained by concatenating the values of given fields,
15164 where the separator is given by \csopt{field-concat-sep}.
15165
15166 Note that \csopt{missing-sort-fallback} and
15167 \csopt{custom-sort-fallbacks} override this setting.
15168
15169 \begin{important}
15170 The \csopt{bibtexentry-sort-fallback} setting is only used when
15171 \bibgls\ tries to access the \field{sort} field for a \gls{mainentry}
15172 defined with \atentry{bibtexentry} and finds that the field hasn't
15173 been set. This means that this setting has no effect if you
15174 explicitly set the \field{sort} field or if you change the field used for
15175 sorting (\csopt{sort-field}).
15176 \end{important}
15177
15178 \optsection{custom-sort-fallbacks}
15179
15180 The value should be a \keyvallist\ in the form
15181 \meta{entrytype}\dequals\meta{field} where \meta{entrytype} is the
15182 \emph{original} \gls{entrytype} (before being aliased with
15183 \csopt{entry-type-aliases}). This will override any of the sort fallback
15184 options listed below for entries whose original \gls{entrytype} matches
15185 \meta{entrytype}.
15186
15187 The \meta{field} may be a known field but not an internal field. For
15188 obvious reasons, it can't be the \field{sort} field (since
15189 \meta{field} is the fallback a missing \field{sort} field). It may also be one of the
15190 keywords: \optfmt{id} (for the entry's label) or \optfmt{original id}
15191 (for the entry's original label). The \meta{field} may also be a
15192 composite in the form \optfmt{\meta{field1}+\meta{field2}+\ldots}
15193 which indicates that the sort value should be obtained by
15194 concatenating the values of the given fields, where the separator is
15195 given by \csopt{field-concat-sep}.
15196
15197 For example, if the \ext{bib} file contains:
15198 \begin{codeenv}
15199 \atentryfmt{unit}\marg{ohm,
15200 \field{name}=\marg{\cs{si}\marg{\csfmt{ohm}}},
15201 \field{description}=\marg{electrical resistance}
15202 }
15203 \strut
15204 \atentryfmt{constant}\marg{pi,
15205 \field{name}=\marg{\cs{ensuremath}\marg{\cs{pi}}},
15206 \field{description}=\marg{the ratio of the length of the circumference
15207 of a circle to its diameter},
15208 \field{user1}=\marg{3.14159}
15209 }
15210 \strut
15211 \atentry{symbol}\marg{fx,
15212 \field{name}=\marg{\cs{ensuremath}\marg{f(x)}},
15213 \field{description}=\marg{a function of \idx{mshiftchar}x\idx{mshiftchar}}
15214 }
15215 \strut
15216 \atentry{number}\marg{zero,
15217 \field{name}=\marg{0},
15218 \field{description}=\marg{nothing or no quantity}
15219 }
15220 \end{codeenv}
15221 Then the resource options:
15222 \begin{codeenv}
15223 \csopt[\entryfmt{unit}=\entryref{symbol},\entryfmt{constant}=\entryref{number}]{entry-type-aliases},
15224 \csopt[\entryfmt{unit}=\field{name},\entryfmt{constant}=\field{user1}]{custom-sort-fallbacks}
15225 \end{codeenv}
15226 will treat the custom \atentryfmt{unit} and \atentryfmt{constant}
15227 entries as though they had been defined with \atentry{symbol}
15228 and \atentry{number}, respectively, but the fallback for the
15229 \field{sort} field is different: the \code{ohm} entry will use the
15230 \field{name} field for the sort fallback (because its original
15231 \gls{entrytype} was \entryfmt{unit}), the \code{pi} entry will use the
15232 \field{user1} field for the sort fallback (because its original
15233 \gls{entrytype} was \entryfmt{constant}) and the \code{fx} and
15234 \code{zero} entries will use the label for the sort fallback (since
15235 neither \entryfmt{symbol} nor \entryfmt{number} were identified in
15236 \csopt{custom-sort-fallbacks} so the \csopt{symbol-sort-fallback} is
15237 used).
15238
15239 If an entry hasn't had its \gls{entrytype} aliased then \meta{entrytype}
15240 is its actual \gls{entrytype}. For example, consider the following
15241 definitions:
15242 \begin{codeenv}
15243 \atentry{abbreviation}\marg{svm,
15244 \field{short}=\marg{SVM},
15245 \field{long}=\marg{support vector machine}
15246 }
15247 \atentry{acronym}\marg{laser,
15248 \field{short}=\marg{laser},
15249 \field{long}=\marg{light amplification by stimulated emission of radiation}
15250 }
15251 \end{codeenv}
15252 Then \csopt[short]{abbreviation-sort-fallback} will make both
15253 entries fallback on the \field{short} field (since
15254 \csopt{abbreviation-sort-fallback} applies to both \atentry{acronym}
15255 and \atentry{abbreviation}), but the option:
15256 \begin{codeenv}
15257 \csopt[\entryref{abbreviation}=\field{long},\entryref{acronym}=\field{short}]{custom-sort-fallbacks}
15258 \end{codeenv}
15259 will make the entry defined with \atentry{abbreviation} fallback on
15260 the \field{long} field and the entry defined with \atentry{acronym}
15261 will fallback on the \field{short} field.
15262
15263 Since the default setting is \csopt[short]{abbreviation-sort-fallback}
15264 this only needs to be:
15265 \begin{codeenv}
15266 \csopt[\entryref{abbreviation}=\field{long}]{custom-sort-fallbacks}
15267 \end{codeenv}
15268 In this case, the entry defined with \atentry{abbreviation} (\qt{SVM}) will use
15269 the setting given in \csopt{custom-sort-fallbacks}, but the entry
15270 defined with \atentry{acronym} (\qt{laser}) will use the setting given by
15271 \csopt{abbreviation-sort-fallback} since \atentry{acronym} hasn't
15272 been identified in \csopt{custom-sort-fallbacks}.
15273
15274 This option also covers \glspl{dualentry}. For example:
15275 \begin{codeenv}
15276 \csopt[
15277 \entryref{dualindexnumber}=\field{description},
15278 \entryfmt{dualindexnumbersecondary}=\field{user1}
15279 ]{custom-sort-fallbacks}
15280 \end{codeenv}
15281 Note that the \gls{entrytype} for the \dual\ is in the form
15282 \code{\meta{primary entry type}secondary}.
15283
15284 \begin{important}
15285 The \csopt{custom-sort-fallbacks} setting is only used when \bibgls\
15286 tries to access the \field{sort} field for an entry (whose original
15287 \gls{entrytype} has been identified in this setting) and finds that the field
15288 hasn't been set. This means that this setting has no effect if you
15289 explicitly set the \field{sort} field or if you change the field
15290 used for sorting (\csopt{sort-field}).
15291 \end{important}
15292
15293 \optsection{field-concat-sep}
15294
15295 This option sets the field concatenation separator to \meta{value}
15296 used by the \field{sort} fallback options. The default is a space.
15297 An empty value indicates no separator. You may use
15298 \gls{uhex}\meta{hex} to indicate a character by its hexadecimal code
15299 (see \sectionref{sec:quarks}). Note that the more complex field
15300 concatenation specification described in
15301 \sectionref{sec:optstringconcat} isn't available for this option.
15302
15303 For example, suppose the \ext{bib} file contains:
15304 \begin{codeenv}
15305 \atentry{abbreviation}\marg{ac,
15306 \field{short}=\marg{AC},
15307 \field{long}=\marg{alternating current}
15308 }
15309 \atentry{index}\marg{acacia}
15310 \end{codeenv}
15311 Then the resource option:
15312 \begin{codeenv}
15313 \gls{GlsXtrLoadResources}\oarg{
15314 \csopt[letter-nocase]{sort},
15315 \csopt[\field{short}+\field{long}]{abbreviation-sort-fallback}
15316 }
15317 \end{codeenv}
15318 will set the \code{ac} sort value to \qt{AC alternating current}.
15319 That is, the \field{short} value concatenated with the \field{long}
15320 value using the default space separator. With the
15321 \optfmt{letter-nocase} sort method, this will put the \code{ac}
15322 entry before the \code{acacia} entry (because the space character
15323 comes before \qt{a}).
15324
15325 If the resource options are changed to:
15326 \begin{codeenv}
15327 \gls{GlsXtrLoadResources}\oarg{
15328 \csopt[letter-nocase]{sort},
15329 \csopt[\empty]{field-concat-sep},
15330 \csopt[\field{short}+\field{long}]{abbreviation-sort-fallback}
15331 }
15332 \end{codeenv}
15333 This will obtain the sort value for abbreviations from a
15334 concatenation of the \meta{short} and \meta{long} values without a
15335 separator. This means that the \code{ac} sort value will be
15336 \qt{ACalternating current} and so the \code{ac} entry will
15337 come after the \code{acacia} entry (since \qt{l} comes after \qt{c}).
15338
15339 This setting is only used for the sort fallback options that allow
15340 field concatenation (such as \csopt{entry-sort-fallback} but not
15341 \csopt{missing-sort-fallback}).
15342
15343 Note that due to the way that the \keyvallist\ parser trims leading and
15344 trailing spaces, you can't simply do \csopt[~]{field-concat-sep}
15345 to indicate a space character as the value will end up as an empty
15346 string. You can instead do \csopt[\stringu20]{field-concat-sep} but
15347 since this is the default value there shouldn't be much need for it.
15348
15349 Remember that the separator may be replaced with a break point
15350 marker depending on the sort method and \csopt{break-at} setting.
15351
15352 \section{Plurals}
15353 \label{sec:plurals}
15354
15355 Some languages, such as English, have a general rule that plurals
15356 are formed from the singular with a suffix appended. This isn't
15357 an absolute rule. There are plenty of exceptions (for example,
15358 geese, children, churches, elves, fairies, sheep, mice), so a
15359 simplistic approach of just doing \code{\ics{gls}\margm{label}[s]}
15360 will sometimes produce inappropriate results, so the \styfmt{glossaries}
15361 package provides a \field{plural} key with the corresponding command
15362 \ics{glspl}.
15363
15364 In some cases a plural may not make any sense (for example, if the
15365 term is a verb or symbol), so the \field{plural} key is optional, but to
15366 make life easier for languages where the majority of plurals can
15367 simply be formed by appending a suffix to the singular, the
15368 \styfmt{glossaries} package lets the \field{plural} field default
15369 to the value of the \field{text} field with \ics{glspluralsuffix}
15370 appended. This command is defined to be just the letter \qt{s}.
15371 This means that the majority of terms in such languages don't need to have the
15372 \field{plural} supplied as well, and you only need to use it for the
15373 exceptions.
15374
15375 For languages that don't have this general rule, the \field{plural}
15376 field will always need to be supplied for nouns.
15377
15378 There are other plural fields, such as \field{firstplural},
15379 \field{longplural} and \field{shortplural}. Again, if you are using
15380 a language that doesn't have a simple suffix rule, you'll have to
15381 supply the plural forms if you need them (and if a plural makes
15382 sense in the context).
15383
15384 If these fields are omitted, the \styfmt{glossaries} package follows
15385 these rules:
15386 \begin{itemize}
15387 \item If \field{firstplural} is missing, then \ics{glspluralsuffix}
15388 is appended to the \field{first} field, if that field has been
15389 supplied. If the \field{first} field hasn't been supplied but the
15390 \field{plural} field has been supplied, then the \field{firstplural}
15391 field defaults to the \field{plural} field. If the \field{plural}
15392 field hasn't been supplied, then both the \field{plural} and
15393 \field{firstplural} fields default to the \field{text} field (or
15394 \field{name}, if no \field{text} field) with \ics{glspluralsuffix}
15395 appended.
15396
15397 \item If the \field{longplural} field is missing, then
15398 \ics{glspluralsuffix} is appended to the \field{long} field, if the
15399 \field{long} field has been supplied.
15400
15401 \item If the \field{shortplural} field is missing then, \emph{with
15402 the base \styfmt{glossaries} acronym mechanism}, \ics{acrpluralsuffix}
15403 is appended to the \field{short} field.
15404
15405 \end{itemize}
15406
15407 The last case is different with the \isty{glossaries-extra} extension
15408 package. The \field{shortplural} field defaults to the \field{short}
15409 field with \ics{abbrvpluralsuffix} appended \emph{unless overridden
15410 by category attributes}. This suffix command is set by the
15411 abbreviation styles. This means that every time an abbreviation
15412 style is implemented, \ics{abbrvpluralsuffix} is redefined. Most
15413 styles simply define this command as:
15414 \begin{codeenv}
15415 \cs{renewcommand}*\marg{\cs{abbrvpluralsuffix}}\marg{\cs{glsxtrabbrvpluralsuffix}}
15416 \end{codeenv}
15417 where \ics{glsxtrabbrvpluralsuffix} expands to \ics{glspluralsuffix}.
15418 The \qt{sc} styles (such as \abbrstyle{long-short-sc}) use a different
15419 definition:
15420 \begin{codeenv}
15421 \cs{renewcommand}*\marg{\cs{abbrvpluralsuffix}}\marg{\cs{protect}\ics{glsxtrscsuffix}}
15422 \end{codeenv}
15423 This allows the suffix to be reverted back to the upright font,
15424 counteracting the affect of the small-caps font.
15425
15426 This means that if you want to change or strip the suffix used for
15427 the plural short form, it's usually not sufficient to redefine
15428 \ics{abbrvpluralsuffix}, as the change will be undone the next time
15429 the style is applied. Instead, for a document-wide solution, you
15430 need to redefine \ics{glsxtrabbrvpluralsuffix}. Alternatively you can
15431 use the category attributes.
15432
15433 There are two attributes that affect the short plural suffix
15434 formation. The first is \catattr{aposplural} which uses the suffix
15435 \begin{codeenv*}
15436 \idx{aposchar}\cs{abbrvpluralsuffix}
15437 \end{codeenv*}
15438 That is, an \idx{apostrophe} followed by \ics{abbrvpluralsuffix} is
15439 appended. The second attribute is \catattr{noshortplural} which
15440 suppresses the suffix and simply sets \field{shortplural} to the
15441 same as \field{short}.
15442
15443 With \bibgls, if you have some abbreviations where the plural should
15444 have a suffix and some where the plural shouldn't have a suffix
15445 (for example, the document has both English and French abbreviations)
15446 then there are two approaches.
15447
15448 The first approach is to use the category attributes. For example:
15449 \begin{codeenv}
15450 \cs{glssetcategoryattribute}\marg{french}\marg{\catattr{noshortplural}}
15451 \end{codeenv}
15452 Now just make sure all the French abbreviations are have their
15453 \field{category} field set to \optfmt{french}:
15454 \begin{codeenv}
15455 \gls{GlsXtrLoadResources}\oarg{\csopt[fr-abbrvs]{src},\csopt[french]{category}}
15456 \end{codeenv}
15457
15458 The other approach is to use the options listed below for the given
15459 \igls{resourceset}. For example:
15460 \begin{codeenv}
15461 \gls{GlsXtrLoadResources}\oarg{\csopt[fr-abbrvs]{src},\csopt[\empty]{short-plural-suffix}}
15462 \end{codeenv}
15463
15464 \optsection{short-plural-suffix}
15465
15466 Sets the plural suffix for the default \field{shortplural} to
15467 \meta{value}. The \meta{value} may be one of:
15468 \begin{itemize}
15469 \item \meta{suffix}: add the
15470 \field{shortplural} field, if missing, with the given \meta{suffix}.
15471 \item \meta{empty}: add the
15472 \field{shortplural} field, if missing, with no suffix.
15473 \item \optfmt{use-default}: leave
15474 it to \styfmt{glossaries-extra} to determine the appropriate default.
15475 \end{itemize}
15476 The default setting is \csopt[use-default]{short-plural-suffix}.
15477 If the \code{=\meta{value}} part is omitted, then
15478 \csopt[\empty]{short-plural-suffix} is assumed.
15479
15480 \optsection{dual-short-plural-suffix}
15481
15482 Sets the plural suffix for the default \field{dualshortplural} field to
15483 \meta{value}. As with \csopt{short-plural-suffix}, the default
15484 setting is \csopt[use-default]{dual-short-plural-suffix}. If the
15485 \meta{value} is omitted or empty, the suffix is set to empty.
15486
15487 \section{Location List Options}
15488 \label{sec:locationopts}
15489
15490 The \styopt{record} package option automatically adds two new keys:
15491 \field{loclist} and \field{location}. These two fields are set by
15492 \bibgls\ from the information supplied in the \iext{aux} file (unless
15493 the option \csopt[false]{save-locations} is used). The
15494 \field{location} field contains the code to typeset the formatted
15495 \igls{locationlist}.
15496
15497 Note that the cross-referencing information provided with the
15498 \field{see}, \field{seealso} and \field{alias} fields is put in the
15499 location list. If you only want the cross-reference and not any of
15500 the locations, use \csopt[see]{save-locations} (or similar).
15501
15502 The \field{loclist} field has the syntax of an \isty{etoolbox}
15503 internal list and includes every \gls{location} (except for the
15504 \glsdisp{discardedrecord}{discarded duplicates} and
15505 \iglspl{ignoredrecord}) with no \idx{range} formations. Any \idx{explicit-range}
15506 markup is stripped from the \glsopt{format} information to leave
15507 just the \idx{encap} name, so you just get the start and end
15508 \glspl{location} added as individual elements but they are still
15509 encapsulated with the associated formatting command. Each item in
15510 the list is provided in one of the following forms:
15511 \begin{codeenv}
15512 \ics{glsseeformat}\oargm{tag}\margm{label list}\marg{}
15513 \end{codeenv}
15514 for the cross-reference supplied by the \field{see} field,
15515 \begin{codeenv}
15516 \ics{glsxtruseseealsoformat}\margm{xr list}
15517 \end{codeenv}
15518 for the cross-reference supplied by the \field{seealso} field,
15519 \nosecdef{glsnoidxdisplayloc}
15520 for standard the internal \glspl{location},
15521 \begin{codeenv}
15522 \format{glsxtrdisplaysupploc}
15523 \end{codeenv}
15524 for \glsdisp{supplementalrecord}{supplemental (external) locations} and
15525 \begin{codeenv}
15526 \format{glsxtrdisplaylocnameref}
15527 \end{codeenv}
15528 for \code{nameref} \glspl{record}. (See \sectionref{sec:supplementalopts}
15529 for more information about \glsdisp{supplementalrecord}{supplemental locations} and
15530 \longarg{merge-nameref-on} for more information about \code{nameref}
15531 records.)
15532
15533 You can iterate through the \field{loclist} value
15534 using one of \sty{etoolbox}'s internal list \idxpl{loop} (either
15535 by first fetching the list using \ics{glsfieldfetch}
15536 or through \styfmt{glossaries-extra}'s \ics{glsxtrfielddolistloop}
15537 or \ics{glsxtrfieldforlistloop} shortcuts).
15538
15539 The \meta{format} is that supplied by the \glsopt{format} key
15540 when using commands like \ics{gls} or \ics{glsadd} (the encapsulator or
15541 \idx{encap} in \idx!{makeindex} parlance). If omitted, the default
15542 \glsopt[glsnumberformat]{format} is assumed (unless this
15543 default value is changed with \ics{GlsXtrSetDefaultNumberFormat}.
15544 The value of the \glsopt{format} key must be the name of
15545 a text-block command without the leading backslash that takes
15546 a single argument (the \gls{location}). The \gls{location}
15547 is encapsulated by that command. For example,
15548 \begin{codeenv}
15549 \cs{gls}\oarg{\glsopt[\encap{textbf}]{format}}\marg{sample}
15550 \end{codeenv}
15551 will display the corresponding \gls{location} in bold, but note that this
15552 will no longer have a hyperlink if you've used \sty{hyperref}.
15553 If you want to retain the hyperlink you need the \gls{location}
15554 encapsulated with \cs{hyperbf} instead of \cs{textbf}:
15555 \begin{codeenv}
15556 \cs{gls}\oarg{\glsopt[\encap{hyperbf}]{format}}\marg{sample}
15557 \end{codeenv}
15558 The \csfmt{hyper}\meta{xx} set of commands all internally use
15559 \cs{glshypernumber} which adds the appropriate hyperlink to the
15560 \gls{location}. See Table~6.1 in the \styfmt{glossaries}~\cite{glossaries}
15561 user manual for a list of all the \csfmt{hyper}\meta{xx} commands.
15562
15563 \Idxpl{range} can be explicitly formed using the parenthetical
15564 syntax \glsopt[\idx{openrange}]{format} and
15565 \glsopt[\idx{openrange}]{format} or \glsopt[\idx{openrange}\meta{csname}]{format} and
15566 \glsopt[\idx{closerange}\meta{csname}]{format} (where \meta{csname} is again the name of
15567 a text-block command without the initial backslash) in the optional
15568 argument of commands like \ics{gls} or \ics{glsadd}. With
15569 \sty{glossaries-extra} v1.50+, you can also use \ics{glsstartrange}
15570 and \ics{glsendrange} (which is useful if the unbalanced parentheses
15571 upset syntax highlighting).
15572
15573 These \idxpl{explicit-range} will always form a \idx{range},
15574 regardless of \csopt{min-loc-range}, unless the start and end
15575 coincide and \longarg{collapse-same-location-range} is in effect.
15576 The \idx{explicit-range} will be encapsulated with \gls!{bibglsrange}
15577 (unless \csopt[true]{merge-ranges}). (This command is not used with
15578 \idxpl{implicit-range} that are formed by collating consecutive \glspl{location}.)
15579 The initial marker is stripped from the \meta{format} argument of
15580 the \gls{location} formatting commands, such as
15581 \gls{glsnoidxdisplayloc}, to allow for easy conversion to the
15582 corresponding text-block command.
15583
15584 \Idxpl{explicit-range} don't merge with neighbouring
15585 \glspl{location} (unless \csopt[true]{merge-ranges}), but will
15586 absorb any individual \glspl{location} within the \idx{range} that doesn't
15587 conflict. (Conflicts, denoted \idxpl{interloper}, will be moved to the start of the
15588 \idx{explicit-range}, regardless of \csopt{merge-ranges}.)
15589 For example, if \code{\cs{gls}\marg{sample}} is used on page~1,
15590 \code{\cs{gls}\oarg{\glsopt[\idx{openrange}]{format}}\marg{sample}}
15591 is used on page~2, \code{\cs{gls}\marg{sample}} is used on page~3, and
15592 \code{\cs{gls}\oarg{\glsopt[\idx{closerange}]{format}}\marg{sample}}
15593 is used on page~4, then the \gls{locationlist} will be 1, 2--4. The
15594 entry on page~3 is absorbed into the \idx{explicit-range}, but, with
15595 the default \csopt[false]{merge-ranges}, the
15596 \idx{range} can't be expanded to include page~1. If the entry on page~3 had a
15597 different format to the \idx{explicit-range}, for example
15598 \code{\cs{gls}\oarg{\glsopt[\encap{textbf}]{format}}\marg{sample}}
15599 then this will cause a warning and the \idx{interloper} will be
15600 moved before the start of the \idx{range} so that the
15601 \gls{locationlist} would then be 1, \textbf{3}, 2--4.
15602
15603 The \csopt[true]{merge-ranges} option will make \idxpl{explicit-range}
15604 behave like \idxpl{implicit-range}, which allows them to merge with
15605 neighbouring \idxpl{range}. The \gls{bibglsrange} command won't be used in
15606 this case (regardless of whether or not the \idx{range} was merged with
15607 neighbouring \glspl{location}). Options such as
15608 \csopt{min-loc-range} won't have an effect on the merged \idx{range}, but
15609 will still effect \idxpl{implicit-range} that haven't been merged with an
15610 \idx{explicit-range}.
15611
15612 An \igls{ignoredrecord} identifies a term that needs to be treated as
15613 though it has a \gls{record} for selection purposes, but the
15614 \gls{record} should not be included in the \gls{locationlist}.
15615 The special format \glsaddopt[\encap{glsignore}]{format} is provided
15616 by the \styfmt{glossaries} package for cases where the \gls{location}
15617 should be ignored. (The command \ics{glsignore} simply ignores its
15618 argument.) This works reasonably well if an entry only has the one
15619 \gls{location}, but if the entry happens to be indexed again, it can lead
15620 to an odd empty gap in the \gls{locationlist} with a spurious comma. If
15621 \bibgls\ encounters a \gls{record} with this special format, the entry
15622 will be selected but the \gls{record} will be discarded.
15623
15624 This means that the \gls{locationlist} will be empty if the entry was
15625 only indexed with the special ignored format, but if the entry was also
15626 indexed with another format then the \gls{locationlist} won't include the
15627 \iglspl{ignoredrecord}. (This format is used by \ics{glsaddallunused} but
15628 remember that iterative commands like this don't work with \bibgls.
15629 Instead, just use \csopt[all]{selection} to select all entries.
15630 Those that don't have \glspl{record} won't have a \gls{locationlist}.)
15631
15632 For example, suppose you only want main matter \glspl{location} in the
15633 number list, but you want entries that only appear in the back matter
15634 to still appear in the glossary (without a \gls{locationlist}), then you could do:
15635 \begin{codeenv}
15636 \ics{backmatter}
15637 \ics{GlsXtrSetDefaultNumberFormat}\marg{\encap{glsignore}}
15638 \end{codeenv}
15639 If you also want to drop front matter \glspl{location} as well:
15640 \begin{codeenv}
15641 \ics{frontmatter}
15642 \cs{GlsXtrSetDefaultNumberFormat}\marg{\encap{glsignore}}
15643 \ldots
15644 \ics{mainmatter}
15645 \cs{GlsXtrSetDefaultNumberFormat}\marg{\encap{glsnumberformat}}
15646 \ldots
15647 \cs{backmatter}
15648 \cs{GlsXtrSetDefaultNumberFormat}\marg{\encap{glsignore}}
15649 \end{codeenv}
15650
15651 Note that \idx{explicit-range} formations aren't discarded, so if
15652 \encap{glsignore} is used in a \idx{range}, such as:
15653 \begin{codeenv}
15654 \ics{glsadd}\oarg{\glsopt[\idx{openrange}\encap{glsignore}]{format}}\marg{sample}
15655 \ldots
15656 \cs{glsadd}\oarg{\glsopt[\idx{closerange}\encap{glsignore}]{format}}\marg{sample}
15657 \end{codeenv}
15658 then the \idx{range} will be included in the \gls{locationlist} (encapsulated
15659 with \ics{glsignore}), but this case would be a rather odd use of
15660 this special format and is not recommended.
15661
15662 The \gls{record} counting commands, such as \gls{rgls}, use the special
15663 format \encap{glstriggerrecordformat}, which \bibgls\ also treats
15664 as an \igls{ignoredrecord} and the same rules as for \encap{glsignore} apply.
15665
15666 The \glspl{location} are always listed in the order in which they were indexed,
15667 (except for the cross-reference which may be placed at the start or
15668 end of the list or omitted).
15669 This is different to \idx!{xindy} and \idx!{makeindex} where you can
15670 specify the ordering (such as \idx!{lowercase} Roman first, then digits,
15671 etc), but unlike those applications, \bibgls\ allows any \gls{location},
15672 although it may not be able to work out an integer representation.
15673 (With \idx!{xindy}, you can define new \gls{location} formats, but you need
15674 to remember to add the appropriate code to the custom module.)
15675
15676 It's possible to define a custom glossary style where
15677 \ics{glossentry} (and the \child\ form \ics{subglossentry}) ignore the
15678 final argument (which will be the \field{location} field)
15679 and instead parse the \field{loclist} field and re-order the
15680 \glspl{location} or process them in some other way. Remember that you can
15681 also use \ics{glsnoidxloclist}
15682 provided by \styfmt{glossaries}. For example:
15683 \begin{codeenv}
15684 \cs{glsfieldfetch}\marg{gls.sample}\marg{loclist}\marg{\cmd{loclist}}\comment{fetch location list}
15685 \cs{glsnoidxloclist}\marg{\cmd{loclist}}\comment{iterate over locations}
15686 \end{codeenv}
15687 This uses \ics{glsnoidxloclisthandler} as the list's \idx{handler}
15688 macro, which simply displays each \gls{location} separated by \ics{delimN}.
15689 (See also
15690 \href{http://www.dickimaw-books.com/latex/admin/html/foreachtips.shtml}{Iteration
15691 Tips and Tricks}~\cite{iterationtips}.)
15692
15693 Each regular \gls{location} is listed in the \iext{aux} file in the form:
15694 \nosecdef{glsxtr@record}
15695 (See \longarg{merge-nameref-on} for \code{nameref} records.)
15696 Exact duplicates are discarded. For example, if \code{cat}
15697 is indexed twice on page 1:
15698 \begin{codeenv}
15699 \gls{glsxtr@record}\marg{cat}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1}
15700 \gls{glsxtr@record}\marg{cat}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1}
15701 \end{codeenv}
15702 then the second \gls{record} is discarded. Only the first
15703 \gls{record} is added to the \gls{locationlist}.
15704
15705 Partial duplicates, where all arguments match except for
15706 \meta{format}, may be discarded depending on the value
15707 of \meta{format}. For example, if page~1 of the document
15708 uses \code{\cs{gls}\marg{cat}} and
15709 \code{\cs{gls}\oarg{\glsopt[\encap{hyperbf}]{format}}\marg{cat}}
15710 then the \ext{aux} file will contain:
15711 \begin{codeenv}
15712 \gls{glsxtr@record}\marg{cat}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1}
15713 \gls{glsxtr@record}\marg{cat}\marg{}\marg{\counter{page}}\marg{\encap{hyperbf}}\marg{1}
15714 \end{codeenv}
15715 This is a partial \gls{record} match. In this case, \bibgls\
15716 makes the following tests:
15717 \begin{itemize}
15718 \item If one of the formats includes an \idx{explicit-range} formation marker, the
15719 \idx{range} takes precedence.
15720
15721 \item If one of the formats is \encap{glsnumberformat} (as in the
15722 above example) or an \igls{ignoredrecord} format such as
15723 \encap{glsignore}, that format will be skipped. So in the above
15724 example, the second \gls{record} will be added to the \gls{locationlist}, but
15725 not the first. (A message will only be written to the transcript if
15726 the \commonlongarg{debug} switch is used.) The default
15727 \encap{glsnumberformat} will take precedence over the
15728 \igls{ignoredrecord} formats (\encap{glsignore} and
15729 \encap{glstriggerrecordformat}).
15730
15731 \item If a mapping has been set with the \longarg{map-format}
15732 switch that mapping will be checked.
15733 \item Otherwise the duplicate \gls{record} will be discarded with a
15734 warning.
15735 \end{itemize}
15736
15737 The \field{location} field is used to store the formatted
15738 \gls{locationlist}. The code for this list is generated by \bibgls\ based on the
15739 information provided in the \iext{aux} file, the presence of the
15740 \field{see} or \field{seealso} field and the various settings described in this
15741 chapter. When you display the glossary using \ics{printunsrtglossary},
15742 if the \field{location} field is present it will be displayed
15743 according to the glossary style (and other factors, such as whether the
15744 \styopt{nonumberlist} option has been used, either as a package
15745 option or supplied in the optional argument of \ics{printunsrtglossary}).
15746 For more information on adjusting the formatting see the
15747 \styfmt{glossaries}~\cite{glossaries} and
15748 \styfmt{glossaries-extra}~\cite{glossaries-extra} user manuals.
15749
15750 \optsection{save-locations}
15751
15752 This was originally a boolean setting, but as from v3.0 there are
15753 additional values.
15754 \begin{itemize}
15755 \item \optfmt{false}: don't save anything in the \field{location}
15756 field;
15757
15758 \item \optfmt{true}: save cross-references and all non-ignored
15759 locations in the \field{location} field;
15760
15761 \item \optfmt{see}: only save cross-references (\field{see},
15762 \field{seealso} and \field{alias}) in the \field{location} field;
15763
15764 \item \optfmt{see not also}: only save the \field{see} and
15765 \field{alias} cross-references (not \field{seealso}) in the
15766 \field{location} field;
15767
15768 \item \optfmt{alias only}: only save the \field{alias}
15769 cross-references (not \field{see} or \field{seealso}) in the
15770 \field{location} field.
15771
15772 \end{itemize}
15773
15774 By default, the \glspl{location} will be processed and stored in the
15775 \field{location} and \field{loclist} fields. However, if you don't
15776 want the \glspl{locationlist} (for example, you are using the
15777 \styopt{nonumberlist} option or you are using \idx!{xindy} with a
15778 custom \gls{location} rule), then there's no need for \bibgls\ to process
15779 the \glspl{location}. To switch this function off, just use
15780 \csopt[false]{save-locations}. Note that with this setting, if
15781 you're not additionally using \idx!{makeindex} or \idx!{xindy}, then
15782 the \glspl{location} won't be available even if you don't have the
15783 \styopt{nonumberlist} option set.
15784
15785 The boolean \field{nonumberlist} key that may be used in
15786 \gls{newglossaryentry} can also be used in a \ext{bib} file, but in
15787 this case it can't have an empty value. The value must be either
15788 \code{true} or \code{false}. If \code{true} then \bibgls\ won't
15789 save the \field{location} or \field{loclist} fields, regardless of
15790 the \csopt{save-locations} resource option.
15791
15792 The \field{nonumberlist} key provided by the base \sty{glossaries}
15793 package doesn't represent a real field. The value isn't saved but,
15794 if used, it will alter the indexing information that's written to
15795 the \idx!{makeindex} or \idx!{xindy} file. It's a little hack to
15796 ensure that the \gls{location} is hidden for a specific entry when used
15797 with \idx!{makeindex} and \idx!{xindy}.
15798
15799 \bibgls\ will look for this key to determine if the \gls{location} should
15800 be omitted for the given entry, but it won't write the key to the
15801 \ext{glstex} file.
15802
15803 \optsection{save-loclist}
15804
15805 If you want the \field{location} field but don't need
15806 \field{loclist}, you can use \csopt[false]{save-loclist}.
15807 This can help to save resources and build time.
15808
15809 \optsection{save-primary-locations}
15810
15811 A synonym for \csopt{save-principal-locations}.
15812
15813 \optsection{save-principal-locations}
15814
15815 It's sometimes useful to identify a \igls{principallocation} with a different
15816 format, such as bold or italic. This helps the reader select which
15817 \gls{location} to try first in the event of a long \gls{locationlist}. However,
15818 you may prefer to store the \glspl{principallocation} in a different field to
15819 give it a more prominent position. In order to do this you
15820 need to specify the format (or formats) used to identify
15821 \glspl{principallocation} with \csopt{principal-location-formats} and
15822 use \csopt{save-principal-locations} to determine how to deal with
15823 these \glspl{location}.
15824
15825 This option may take one of the following values:
15826 \begin{itemize}
15827 \item \optfmt{false}: don't save \glspl{principallocation} (default);
15828
15829 \item \optfmt{retain}: save \glspl{principallocation} in the
15830 \field{primarylocations} field but don't remove from the usual
15831 \igls{locationlist};
15832
15833 \item \optfmt{default format}: similar to \optfmt{retain} but the
15834 format for the \glsdisp{principallocation}{principal records} in the
15835 \field{location} field is converted to the default
15836 \encap{glsnumberformat} \idx{encap} (the \glspl{record} in the
15837 \field{primarylocations} field retain their given format);
15838
15839 \item \optfmt{start}: save \glspl{principallocation} in the
15840 \field{primarylocations} field and also move to the start of the
15841 usual \igls{locationlist};
15842
15843 \item \optfmt{remove}: save \glspl{principallocation} in the
15844 \field{primarylocations} field and remove from the usual
15845 \igls{locationlist}. You may want to consider using the
15846 \longarg{retain-formats} switch with this setting if you don't
15847 want to lose a partial \gls{location} match (for example, if the
15848 \gls{principallocation} coincides with the start of an
15849 \idx{explicit-range}).
15850
15851 \end{itemize}
15852
15853 The \glspl{principallocation} are copied to the \field{primarylocations}
15854 field and are either encapsulated with \gls!{bibglsprimary} or can
15855 be split into groups, according to \csopt{principal-loc-counters}.
15856
15857 If you use \csopt[remove]{save-principal-locations}, the
15858 \field{location} field will end up empty if the \glspl{location} for the
15859 associated entry were all identified as principal. If you use
15860 \csopt[start]{save-principal-locations}, all
15861 \glspl{principallocation} will be
15862 moved to the start of the \igls{locationlist} stored in the
15863 \field{location} field, but there will be no additional markup
15864 (other than the given format) to identify them. If you need
15865 additional markup, then use \csopt[remove]{save-principal-locations}
15866 and adjust the \igls{locationlist} format to insert the
15867 \glspl{principallocation} at the start. This can be done by modifying the glossary
15868 style.
15869
15870 For example, the \glostyle{bookindex} style inserts
15871 \ics{glsxtrbookindexprelocation} before the \gls{location}, so you could
15872 redefine this:
15873 \begin{codeenv}
15874 \cs{renewcommand}*\marg{\cs{glsxtrbookindexprelocation}}[1]\marg{\comment{}
15875 \cs{glsxtrifhasfield}\marg{primarylocations}\marg{\idx{param}1}\comment{}
15876 \marg{\comment{}
15877 \ics{glsxtrprelocation}
15878 \cs{glscurrentfieldvalue}
15879 \cs{glsxtrifhasfield}\marg{location}\marg{\idx{param}1}\marg{;}\marg{}\comment{}
15880 }\comment{}
15881 \marg{}\comment{}
15882 \cs{glsxtrprelocation}
15883 }
15884 \end{codeenv}
15885 (Note that if \csopt{loc-prefix} is used, the prefix will be
15886 in the \field{location} field and so will come after the
15887 \glspl{principallocation} in the above example. Similarly for cross-references
15888 unless they've been omitted.)
15889
15890 You can switch from using the \field{location} field to the
15891 \field{primarylocations} field by locally changing
15892 \ics{GlsXtrLocationField}:
15893 \begin{codeenv}
15894 \cs{printunsrtglossary*}\marg{\comment{}
15895 \cs{renewcommand}\marg{\cs{GlsXtrLocationField}}\marg{primarylocations}\comment{}
15896 }
15897 \end{codeenv}
15898 Remember that the \idx{handler} used by \cs{printunsrtglossary} will
15899 fallback on the \field{loclist} field if the field identified
15900 by \cs{GlsXtrLocationField} is missing or empty. You may want to
15901 consider using \csopt[false]{save-loclist} to prevent this.
15902
15903 \optsection{primary-location-formats}
15904
15905 A synonym for \csopt{principal-location-formats}.
15906
15907 \optsection{principal-location-formats}
15908
15909 This option will automatically set
15910 \csopt[retain]{save-principal-locations} unless it has already been
15911 changed from the default \csopt[false]{save-principal-locations}
15912 setting. The argument should be a comma-separated list of
15913 formats. If a record's format is contained in this list then it will
15914 be considered a \igls{principallocation} and it will be included in the
15915 associated entry's \field{primarylocations} field.
15916
15917 For example, suppose the file \filefmt{entries.bib} contains:
15918 \begin{codeenv}
15919 \atentry{entry}\marg{bird,
15920 \field{name}=\marg{bird},
15921 \field{description}=\marg{feathered animal}
15922 }
15923 \atentry{entry}\marg{waterfowl,
15924 \field{name}=\marg{waterfowl},
15925 \field{description}=\marg{any bird that lives in or about water}
15926 }
15927 \atentry{entry}\marg{zebra,
15928 \field{name}=\marg{zebra},
15929 \field{description}=\marg{striped African horse}
15930 }
15931 \atentry{entry}\marg{parrot,
15932 \field{name}=\marg{parrot},
15933 \field{description}=\marg{mainly tropical bird with bright plumage}
15934 }
15935 \end{codeenv}
15936 and the document \filefmt{test.tex} contains:
15937 \begin{codeenv}
15938 \cmd{documentclass}\marg{report}
15939 \strut
15940 \cmd{usepackage}\oarg{colorlinks}\marg{hyperref}
15941 \cmd{usepackage}\oarg{\styopt{record},
15942 \styopt[dot]{postpunc},
15943 \styopt{nostyles},
15944 \styopt[tree,bookindex]{stylemods},
15945 \styopt[bookindex]{style}}\marg{glossaries-extra}
15946 \strut
15947 \gls{GlsXtrLoadResources}\oarg{
15948 \csopt[entries]{src},
15949 \csopt[hyperbf,hyperemph]{principal-location-formats},
15950 \csopt[remove]{save-principal-locations}
15951 }
15952 \strut
15953 \cmd{renewcommand}*\marg{\cs{glsxtrbookindexprelocation}}[1]\marg{\comment{}
15954 \cs{glsxtrifhasfield}\marg{\field{primarylocations}}\marg{\idx{param}1}\comment{}
15955 \marg{\comment{}
15956 \ics{glsxtrprelocation}
15957 \cs{glscurrentfieldvalue}
15958 \cs{glsxtrifhasfield}\marg{\field{location}}\marg{\idx{param}1}\marg{;}\marg{}\comment{}
15959 }\comment{}
15960 \marg{}\comment{}
15961 \cs{glsxtrprelocation}
15962 }
15963 \strut
15964 \gls{glsxtrnewglslike}\oarg{\glsopt[\encap{hyperbf}]{format}}\marg{}\marg{\cmd{primary}}\marg{\cmd{primarypl}}\marg{\cmd{Primary}}\marg{\cmd{Primarypl}}
15965 \strut
15966 \cmd{begin}\marg{document}
15967 \cmd{chapter}\marg{Sample}
15968 \cmd{Primary}\marg{waterfowl}, \cs{gls}\marg{bird} and \cs{gls}\marg{zebra}.
15969 \strut
15970 \cmd{chapter}\marg{Another Sample}
15971 \cs{Gls}\marg{waterfowl}, \cmd{primary}\marg{bird} and \cs{gls}\marg{zebra}.
15972 \strut
15973 \cmd{chapter}\marg{Yet Another Sample}
15974 \cs{Gls}\marg{waterfowl}, \cs{gls}\marg{bird} and \cmd{primary}\marg{zebra}.
15975 \strut
15976 \cmd{chapter}\marg{Yet Another Sample Again}
15977 \cs{Gls}\marg{waterfowl}, \cs{gls}\marg{bird}, \cmd{primarypl}\marg{parrot} and \cs{gls}\marg{zebra}.
15978 \strut
15979 \ics{printunsrtglossary*}\oarg{\printglossopt[\iglostyle{tree}]{style},\printglossopt{nonumberlist}}\marg{\comment{}
15980 \cmd{renewcommand}*\marg{\ics{glsextrapostnamehook}}[1]\marg{\ics{glsadd}\oarg{\glsopt[\encap{hyperemph}]{format}}\marg{\idx{param}1}}\comment{}
15981 }
15982 \strut
15983 \cs{printunsrtglossary}\oarg{\printglossopt[Index]{title},\printglossopt[false]{target}}
15984 \cmd{end}\marg{document}
15985 \end{codeenv}
15986
15987 The \csopt[\encap{hyperbf},\encap{hyperemph}]{principal-location-formats}
15988 setting in the above indicates that \glspl{location} encapsulated with
15989 \ics{hyperbf} and \ics{hyperemph} are
15990 \glsdisp{principallocation}{principal records}. In this case, the
15991 bold format is used to indicate the \gls{principallocation} in the
15992 main document text and the emphasized format is used to indicate the
15993 \gls{location} in the \gls{mainglossary}.
15994
15995 The \glsdisp{principallocation}{principal records} are removed from
15996 the \field{location} field due to the
15997 \csopt[remove]{save-principal-locations} setting. This can lead to a
15998 ragged \gls{locationlist}. The option \csopt[default
15999 format]{save-principal-locations} can allow the
16000 \gls{principallocation} to be absorbed into a \idx{range}.
16001
16002 The \gls{mainglossary} records are added through the category-independent post-name
16003 hook with \cs{glsadd}. This won't be implemented until the entries are actually
16004 defined as the page number can't be determined until the glossary can be
16005 displayed. This means that the document build requires an extra \bibgls\ and
16006 \LaTeX\ run:
16007 \begin{verbatim}
16008 pdflatex test
16009 bib2gls --group test
16010 pdflatex test
16011 bib2gls --group test
16012 pdflatex test
16013 \end{verbatim}
16014
16015 For consistency, I've used \gls{glsxtrnewglslike} to provide commands
16016 used to indicate a principal reference in the text. This means that if
16017 I decide to change the optional arguments used for principal
16018 references I only need to edit one line. For example, I might want to
16019 change the default counter:
16020 \begin{codeenv}
16021 \gls{glsxtrnewglslike}\oarg{\glsopt[\encap{hyperbf}]{format},\glsopt[\counter{chapter}]{counter}}\marg{}\marg{\cmd{primary}}\marg{\cmd{primarypl}}\marg{\cmd{Primary}}\marg{\cmd{Primarypl}}
16022 \end{codeenv}
16023
16024 Here's another example that only has one principal format (\encap{hyperrm})
16025 that's indexed through the use of \ics{GlsXtrAutoAddOnFormat}, which sets
16026 up a hook that automatically inserts:
16027 \begin{codeenv*}
16028 \ics{glsadd}\oarg{\glsaddopt[\counter{chapter}]{counter},\glsaddopt[\encap{hyperrm}]{format}}\margm{label}
16029 \end{codeenv*}
16030 on each instance of \code{\cs{gls}\oarg{\glsopt[primaryfmt]{format}}\margm{label}} (or
16031 similar). This means that the entry is indexed twice when this particular
16032 format is used: first with the \encap{hyperrm} format and \counter{chapter}
16033 counter (from the \cs{glsadd} command in the hook), and then with the
16034 \code{primaryfmt} format and the default counter (as per normal behaviour):
16035 \begin{codeenv}
16036 \cmd{documentclass}\marg{report}
16037 \strut
16038 \cmd{usepackage}\oarg{colorlinks}\marg{hyperref}
16039 \cmd{usepackage}\oarg{
16040 \styopt[nameref]{record},
16041 \styopt[dot]{postpunc},
16042 \styopt{nostyles},
16043 \styopt[tree,bookindex]{stylemods},
16044 \styopt[bookindex]{style}}\marg{glossaries-extra}
16045 \strut
16046 \gls{GlsXtrLoadResources}\oarg{
16047 \csopt[topics]{src},
16048 \csopt[hyperrm]{principal-location-formats},
16049 \csopt[remove]{save-principal-locations},
16050 \csopt[false]{save-loclist}
16051 }
16052 \strut
16053 \cmd{newcommand}\marg{\cmd{primaryfmt}}\oarg{1}\marg{\cs{hyperbf}\marg{\idx{param}1}}
16054 \strut
16055 \ics{GlsXtrAutoAddOnFormat}\marg{primaryfmt}\marg{\glsaddopt[\counter{chapter}]{counter},\glsaddopt[\encap{hyperrm}]{format}}
16056 \strut
16057 \gls{glsxtrnewglslike}\oarg{\glsaddopt[primaryfmt]{format}}\marg{}\marg{\cmd{primary}}\marg{\cmd{primarypl}}\marg{\cmd{Primary}}\marg{\cmd{Primarypl}}
16058 \strut
16059 \cmd{begin}\marg{document}
16060 \cmd{chapter}\marg{Sample}
16061 \cmd{Primary}\marg{waterfowl}, \cs{gls}\marg{bird} and \cs{gls}\marg{zebra}.
16062 \strut
16063 \cmd{chapter}\marg{Another Sample}
16064 \cs{Gls}\marg{waterfowl}, \cmd{primary}\marg{bird} and \cs{gls}\marg{zebra}.
16065 \strut
16066 \cmd{chapter}\marg{Yet Another Sample}
16067 \cs{Gls}\marg{waterfowl}, \cs{gls}\marg{bird} and \cmd{primary}\marg{zebra}.
16068 \strut
16069 \cmd{chapter}\marg{Yet Another Sample Again}
16070 \cs{Gls}\marg{waterfowl}, \cs{gls}\marg{bird}, \cmd{primarypl}\marg{parrot} and \cs{gls}\marg{zebra}.
16071 \strut
16072 \ics{printunsrtglossary*}\oarg{\printglossopt[\glostyle{tree}]{style},\printglossopt[Summary]{title}}\marg{\comment{}
16073 \cmd{renewcommand}*\marg{\ics{glsextrapostnamehook}}[1]\marg{\ics{glsadd}\oarg{\glsaddopt[\encap{hyperemph}]{format}}\marg{\idx{param}1}}\comment{}
16074 \cmd{renewcommand}\marg{\ics{GlsXtrLocationField}}\marg{\field{primarylocations}}\comment{}
16075 }
16076 \strut
16077 \cs{printunsrtglossary}\oarg{\printglossopt[Index]{title},\printglossopt[false]{target}}
16078 \cmd{end}\marg{document}
16079 \end{codeenv}
16080
16081 Note that in this case, from \bibgls' point of view, the principal
16082 format is \encap{hyperrm} not \code{primaryfmt}. This picks out the
16083 records created with the automated \ics{glsadd}, which have the
16084 counter set to \counter{chapter}. The first glossary (with the
16085 title \qt{Summary}) switches the location field to
16086 \field{primarylocations} so that only the
16087 \glsdisp{principallocation}{principal records} are listed. Since
16088 \styopt[nameref]{record} has been used this means that the chapter
16089 title is shown rather than the chapter number.
16090
16091 The second glossary (\qt{Index}) shows the \glspl{locationlist} that
16092 only have the \counter{page} counter (because the automated
16093 \cs{glsadd} records with the \counter{chapter} counter have been
16094 removed because they were identified as
16095 \glsdisp{principallocation}{principal records}). These just show the
16096 page number as that's the default display with
16097 \styopt[nameref]{record} for records with the \counter{page}
16098 counter.
16099
16100 An alternative to \ics{GlsXtrAutoAddOnFormat} would be to simply
16101 define the custom commands as follows:
16102 \begin{codeenv}
16103 \cmd{newcommand}\marg{\cmd{primary}}[2][]\marg{\comment{}
16104 \cs{glsadd}\oarg{\glsaddopt[\counter{chapter}]{counter},\glsaddopt[\encap{hyperrm}]{format}}\marg{\idx{param}2}\comment{}
16105 \cs{gls}\oarg{\glsopt[primaryfmt]{format},\idx{param}1}\marg{\idx{param}2}\comment{}
16106 }
16107 \cmd{newcommand}\marg{\cmd{primarypl}}[2][]\marg{\comment{}
16108 \cs{glsadd}\oarg{\glsaddopt[\counter{chapter}]{counter},\glsaddopt[\encap{hyperrm}]{format}}\marg{\idx{param}2}\comment{}
16109 \cs{glspl}\oarg{\glsopt[primaryfmt]{format},\idx{param}1}\marg{\idx{param}2}\comment{}
16110 }
16111 \cmd{newcommand}\marg{\cmd{Primary}}[2][]\marg{\comment{}
16112 \cs{glsadd}\oarg{\glsaddopt[\counter{chapter}]{counter},\glsaddopt[\encap{hyperrm}]{format}}\marg{\idx{param}2}\comment{}
16113 \cs{Gls}\oarg{\glsopt[primaryfmt]{format},\idx{param}1}\marg{\idx{param}2}\comment{}
16114 }
16115 \cmd{newcommand}\marg{\cmd{Primarypl}}[2][]\marg{\comment{}
16116 \cs{glsadd}\oarg{\glsaddopt[\counter{chapter}]{counter},\glsaddopt[\encap{hyperrm}]{format}}\marg{\idx{param}2}\comment{}
16117 \cs{Glspl}\oarg{\glsopt[primaryfmt]{format},\idx{param}1}\marg{\idx{param}2}\comment{}
16118 }
16119 \end{codeenv}
16120 This is more useful if you want to simply omit the
16121 \code{\glsopt[primaryfmt]{format}} option (just remove it from the above four
16122 definitions), which makes it easier to merge the \glspl{location} into
16123 \idxpl{range} in the index.
16124
16125 \optsection{primary-loc-counters}
16126
16127 A synonym for \csopt{principal-loc-counters}.
16128
16129 \optsection{principal-loc-counters}
16130
16131 This option determines whether the \glspl{principallocation} should
16132 be split into groups according to the location counter. The value
16133 may be one or:
16134 \begin{itemize}
16135 \item \optfmt{combine}: don't split into groups (default);
16136 \item \optfmt{match}: match the \csopt{loc-counters} setting;
16137 \item \optfmt{split}: split into groups regardless of the
16138 \csopt{loc-counters} setting.
16139 \end{itemize}
16140
16141 With \csopt[combine]{principal-loc-counters} or with
16142 \csopt[match]{principal-loc-counters} and the default \csopt[as
16143 use]{loc-counters} settings, no groups will be formed and the
16144 \glspl{principallocation} will be encapsulated with
16145 \gls{bibglsprimary}. Otherwise, the locations will be split into
16146 groups according to the counter and each group will be encapsulated
16147 with \gls{bibglsprimarylocationgroup} and separated with
16148 \gls{bibglsprimarylocationgroupsep}.
16149
16150 For example, suppose the file \filefmt{topics.bib} contains the
16151 following entry:
16152 \begin{codeenv}
16153 \atentry{entry}\marg{zebra,
16154 \field{name}=\marg{zebra},
16155 \field{description}=\marg{striped African horse}
16156 }
16157 \end{codeenv}
16158 The document sets up a \gls{principallocation} format identified by
16159 the custom command \csfmt{primaryfmt}:
16160 \begin{codeenv}
16161 \cs{newcommand}\marg{\cmd{primaryfmt}}[1]\marg{\cs{hyperbf}\marg{\idx{param}1}}
16162 \end{codeenv}
16163 The \ics{GlsXtrAutoAddOnFormat} command is used to automatically
16164 record an entry with the \counter{chapter} counter (using
16165 \ics{glsadd}) every time the entry is
16166 recorded with the \gls{principallocation} format:
16167 \begin{codeenv}
16168 \cs{GlsXtrAutoAddOnFormat}\marg{primaryfmt}\marg{\glsopt{counter}=\counter{chapter},\glsopt{format}=primaryfmt}
16169 \end{codeenv}
16170 This means that, for example,
16171 \begin{codeenv}
16172 \cs{gls}\oarg{\glsopt{format}=primaryfmt}\margm{zebra}
16173 \end{codeenv}
16174 will also first do:
16175 \begin{codeenv}
16176 \cs{glsadd}\oarg{\glsopt{counter}=\counter{chapter},\glsopt{format}=primaryfmt}\margm{zebra}
16177 \end{codeenv}
16178
16179 If \idx{resourceset} is loaded with:
16180 \begin{codeenv}
16181 \gls{GlsXtrLoadResources}\oarg{\csopt[topics]{src},
16182 \csopt[primaryfmt]{primary-location-formats},
16183 \csopt[retain]{save-primary-locations}
16184 }
16185 \end{codeenv}
16186 then both the \field{location} field and the
16187 \field{primarylocations} field will include both the \counter{page}
16188 and \counter{chapter} records mixed together. The
16189 \field{primarylocations} field will have the locations encapsulated
16190 with \gls{bibglsprimary}.
16191
16192 With
16193 \begin{codeenv}
16194 \gls{GlsXtrLoadResources}\oarg{\csopt[topics]{src},
16195 \csopt[primaryfmt]{primary-location-formats},
16196 \csopt[retain]{save-primary-locations},
16197 \csopt[split]{primary-loc-counters}
16198 }
16199 \end{codeenv}
16200 the \field{primarylocations} field will have the locations split into
16201 two groups, each encapsulated with \gls{bibglsprimarylocationgroup}.
16202 The \field{location} field will have the \counter{chapter} and
16203 \counter{page} locations intermingled.
16204
16205 With
16206 \begin{codeenv}
16207 \gls{GlsXtrLoadResources}\oarg{\csopt[topics]{src},
16208 \csopt[primaryfmt]{primary-location-formats},
16209 \csopt[retain]{save-primary-locations},
16210 \csopt[split]{primary-loc-counters},
16211 \csopt[page]{loc-counters}
16212 }
16213 \end{codeenv}
16214 The \field{primarylocations} field will be the same as before, but
16215 the \field{location} field will only have the \counter{page}
16216 locations.
16217
16218 Whereas with
16219 \begin{codeenv}
16220 \gls{GlsXtrLoadResources}\oarg{\csopt[topics]{src},
16221 \csopt[primaryfmt]{primary-location-formats},
16222 \csopt[retain]{save-primary-locations},
16223 \csopt[match]{primary-loc-counters},
16224 \csopt[page]{loc-counters}
16225 }
16226 \end{codeenv}
16227 Both the \field{primarylocations} field and the \field{location}
16228 field will only have the \counter{page} locations.
16229
16230 The order of the groups depends on whether \optfmt{split} or
16231 \optfmt{match} is used. With \csopt[match]{primary-loc-counters} the
16232 counter group order will match \csopt{loc-counters}. Whereas with
16233 \csopt[split]{primary-loc-counters} the counter group order will be determined by
16234 the order of records.
16235
16236 So in the case of the above document where the \counter{chapter}
16237 record is automatically added before the \counter{page} record
16238 (where the \glsopt{format} is \code{primaryfmt}) then with:
16239 \begin{codeenv}
16240 \gls{GlsXtrLoadResources}\oarg{\csopt[topics]{src},
16241 \csopt[primaryfmt]{primary-location-formats},
16242 \csopt[retain]{save-primary-locations},
16243 \csopt[match]{primary-loc-counters},
16244 \csopt[page,chapter]{loc-counters}
16245 }
16246 \end{codeenv}
16247 then both the \field{location} field and the
16248 \field{primarylocations} field will have the \counter{page} group
16249 first, followed by the \counter{chapter} group. Whereas with:
16250 \begin{codeenv}
16251 \gls{GlsXtrLoadResources}\oarg{\csopt[topics]{src},
16252 \csopt[primaryfmt]{primary-location-formats},
16253 \csopt[retain]{save-primary-locations},
16254 \csopt[skip]{primary-loc-counters},
16255 \csopt[page,chapter]{loc-counters}
16256 }
16257 \end{codeenv}
16258 then the \field{primarylocations} field will have the
16259 \counter{chapter} group first, followed by the \counter{page} group.
16260
16261 \optsection{merge-ranges}
16262
16263 This boolean option determines whether or not \idxpl{explicit-range} should
16264 merge with neighbouring \glspl{location} on either side of the
16265 \idx{range}. The default setting is \csopt[false]{merge-ranges}.
16266
16267 Note that \gls{bibglsrange} won't be used with
16268 \csopt[true]{merge-ranges}, regardless of whether or not the \idx{range}
16269 was merged with neighbouring \glspl{location}. Options such as
16270 \csopt{min-loc-range}, \csopt{suffixF} and \csopt{suffixFF}
16271 won't have an effect on the merged range, but
16272 will still effect \idxpl{implicit-range} that haven't been merged with an
16273 \idx{explicit-range}.
16274
16275 Regardless of the value of this option, \idxpl{interloper} will still be
16276 moved to the start of the \idx{range} and encapsulated with
16277 \gls{bibglsinterloper}.
16278
16279 \optsection{min-loc-range}
16280
16281 By default, three or more consecutive \glspl{location} \meta{loc-1},
16282 \meta{loc-2}, \ldots, \meta{loc-n} are compressed into
16283 the \idx{range} \code{\meta{loc-1}\ics{delimR} \meta{loc-n}}
16284 (an \idx{implicit-range}). Otherwise
16285 the \glspl{location} are separated by \gls!{bibglsdelimN} or \gls!{bibglslastDelimN}.
16286 As mentioned above, these aren't merged with \idx{explicit-range}
16287 formations unless \csopt[true]{merge-ranges}.
16288
16289 You can change how many consecutive \glspl{location} are need to
16290 form an \idx{implicit-range} with the \csopt{min-loc-range} setting where
16291 \meta{value} is either \optfmt{none} (don't form ranges) or an
16292 integer greater than one indicating how many consecutive
16293 \glspl{location} should be converted into a \idx{range}.
16294
16295 \bibgls\ determines if one \gls{location}
16296 \code{\margm{prefix-2}\margm{counter-2}\margm{format-2}\margm{location-2}}
16297 is one unit more than another \gls{location}
16298 \code{\margm{prefix-1}\margm{counter-1}\margm{format-1}\margm{location-1} }
16299 according to the following:
16300 \begin{enumerate}
16301 \item\label{itm:pre} If \meta{prefix-1} is not equal to \meta{prefix-2} or
16302 \meta{counter-1} is not equal to \meta{counter-2} or \meta{format-1}
16303 is not equal to \meta{format-2}, then the \glspl{location} aren't
16304 considered consecutive.
16305 \item\label{itm:emptyloc} If either \meta{location-1} or \meta{location-2} are empty,
16306 then the \glspl{location} aren't considered consecutive.
16307 \item\label{itm.csmatch} If both \meta{location-1} and \meta{location-2} match the
16308 pattern (line break for clarity only)\footnote{The Java class \code{\csfmt{p}\marg{javaDigit}}
16309 used in the \gls{regular-expression} will match any digits in the
16310 Unicode \idx{numberdecimaldigit} category not just the digits in the Basic Latin set. Similarly \code{\csfmt{p}\marg{javaAlphabetic}} will also match alphabetic
16311 characters outside the Basic Latin set.}
16312 \begin{verbatim}
16313 (.*?)(?:\\protect\s*)?(\\[\p{javaAlphabetic}@]+)\s*\{([\p{javaDigit}
16314 \p{javaAlphabetic}]+)\}
16315 \end{verbatim}
16316 then:
16317 \begin{itemize}
16318 \item if the control sequence matched by group 2 isn't the same for
16319 both \glspl{location}, the \glspl{location} aren't considered consecutive;
16320 \item if the argument of the control sequence (group 3) is the same for
16321 both \glspl{location}, then the test is retried with \meta{location-1}
16322 set to group 1 of the first pattern match and \meta{location-2}
16323 set to group 1 of the second pattern match;
16324 \item otherwise the test is retried with \meta{location-1} set to
16325 group 3 of the first pattern match and \meta{location-2} set to
16326 group 3 of the second pattern match.
16327 \end{itemize}
16328 \item\label{itm:decmatch} If both \meta{location-1} and \meta{location-2} match the
16329 pattern
16330 \begin{verbatim}
16331 (.*?)([^\p{javaDigit}]?)(\p{javaDigit}+)
16332 \end{verbatim}
16333 then:
16334 \begin{enumerate}
16335 \item\label{itm:decgrp3eq} if group 3 of both pattern matches are
16336 equal then:
16337 \begin{enumerate}
16338 \item\label{itm:decgrp3nz} if group 3 isn't zero, the \glspl{location}
16339 aren't considered consecutive;
16340 \item if the separators (group 2) are different the test is
16341 retried with \meta{location-1} set to the concatenation of the first
16342 two groups \meta{group-1}\meta{group-2} of the first pattern match
16343 and \meta{location-2} set to the concatenation of the first two groups
16344 \meta{group-1}\meta{group-2} of the second pattern
16345 match;
16346 \item\label{itm:decgrp3eqsepeq} if the separators (group 2) are the same the test is
16347 retried with \meta{location-1} set to the first
16348 group \meta{group-1} of the first pattern match
16349 and \meta{location-2} set to the first group
16350 \meta{group-1} of the second pattern match.
16351 \end{enumerate}
16352 \item If \meta{group-1} of the first pattern match (of
16353 \meta{location-1}) doesn't equal
16354 \meta{group-1} of the second pattern match (of \meta{location-2})
16355 or \meta{group-2} of the first pattern match (of
16356 \meta{location-1}) doesn't equal
16357 \meta{group-2} of the second pattern match (of \meta{location-2})
16358 then the \glspl{location} aren't considered consecutive;
16359 \item\label{itm:decgrp3} If $0 < l_2 - l_1 \leq d $
16360 where $l_2$ is \meta{group 3} of the second pattern match,
16361 $l_1$ is \meta{group 3} of the first pattern match and
16362 $d$ is the value of \optfmt{max-loc-diff} then the \glspl{location}
16363 are consecutive otherwise they're not consecutive.
16364 \end{enumerate}
16365 \item\label{itm:rommatch} The next pattern matches for \meta{prefix}\meta{sep}\meta{n}
16366 where \meta{n} is a \idx!{lowercase} Roman numeral, which is converted to
16367 a decimal value and the test is performed in the same way as the
16368 above \hyperref[itm:decmatch]{decimal test}.
16369 \item\label{itm:Rommatch} The next pattern matches for \meta{prefix}\meta{sep}\meta{n}
16370 where \meta{n} is an \idx!{uppercase} Roman numeral, which is converted to
16371 a decimal value and the test is performed
16372 in the same way as the above \hyperref[itm:decmatch]{decimal test}.
16373 \item\label{itm:alphmatch} The next pattern matches for \meta{prefix}\meta{sep}\meta{c}
16374 where \meta{c} is either a \idx!{lowercase} letter from \code{a} to
16375 \code{z} or an \idx!{uppercase} letter from \code{A} to \code{Z}.
16376 The character is converted to its code point and the test is
16377 performed in the same way as the \hyperref[itm:decmatch]{decimal pattern} above.
16378 \item\label{itm:nomatch} If none of the above, the \gls{location} aren't considered
16379 consecutive.
16380 \end{enumerate}
16381
16382 Examples:
16383 \begin{enumerate}
16384 \item
16385 \begin{codeenv}
16386 \gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1}
16387 \gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{2}
16388 \end{codeenv}
16389 These records are consecutive. The prefix, counter and format are
16390 identical (so the test passes step~\ref{itm:pre}), the \glspl{location} match
16391 the \hyperref[itm:decmatch]{decimal pattern} and the test in
16392 step~\ref{itm:decgrp3} passes.
16393
16394 \item
16395 \begin{codeenv}
16396 \gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1}
16397 \gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{textbf}}\marg{2}
16398 \end{codeenv}
16399 These records aren't consecutive since the formats are different.
16400
16401 \item
16402 \begin{codeenv}
16403 \gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{A.i}
16404 \gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{A.ii}
16405 \end{codeenv}
16406 These records are consecutive. The prefix, counter and format are
16407 identical (so it passes step~\ref{itm:pre}). The \glspl{location} match
16408 the \hyperref[itm:rommatch]{lower case Roman numeral pattern}, where
16409 \code{A} is considered a prefix and the dot is consider a
16410 separator. The Roman numerals i and ii are converted to decimal and
16411 the test is retried with the \glspl{location} set to 1 and 2, respectively.
16412 This now passes the decimal pattern test (step~\ref{itm:decgrp3}).
16413
16414 \item
16415 \begin{codeenv}
16416 \gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{i.A}
16417 \gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{ii.A}
16418 \end{codeenv}
16419 These records aren't consecutive. They match the
16420 \hyperref[itm:alphmatch]{alpha pattern}. The first \gls{location} is
16421 considered to consist of the prefix \code{i}, the separator
16422 \code{.}\ (dot) and the number given by the character code of A.
16423 The second \gls{location} is considered to consist of the prefix
16424 \code{ii}, the separator \code{.}\ (dot) and the number
16425 given by the character code of A.
16426
16427 The test fails because the numbers are equal and the prefixes are
16428 different.
16429
16430 \item
16431 \begin{codeenv}
16432 \gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1.0}
16433 \gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{2.0}
16434 \end{codeenv}
16435 These records are consecutive. They match the \hyperref[itm:decmatch]{decimal
16436 pattern}, and then step~\ref{itm:decgrp3eq} followed by
16437 step~\ref{itm:decgrp3eqsepeq}. The \code{.0} part is discarded and
16438 the test is retried with the first \gls{location} set to 1 and the second
16439 \gls{location} set to 2.
16440
16441 \item
16442 \begin{codeenv}
16443 \gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1.1}
16444 \gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{2.1}
16445 \end{codeenv}
16446 These records aren't consecutive as the test branches off into
16447 step~\ref{itm:decgrp3nz}.
16448
16449 \item
16450 \begin{codeenv}
16451 \gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{\cmd{@alph}\marg{1}}
16452 \gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{\cmd{@alph}\marg{2}}
16453 \end{codeenv}
16454 These records are consecutive. The \glspl{location} match the
16455 \hyperref[itm.csmatch]{control sequence pattern}. The control
16456 sequences are the same, so the test is retried with the first
16457 \gls{location} set to 1 and the second \gls{location} set to 2.
16458
16459 In this example, the \gls{location} has been written to the file as
16460 \code{\csfmt{@alph}\margm{number}} instead of fully expanding according to the
16461 normal behaviour of \code{\ics{alph}\margm{counter}}. (Note that
16462 \gls!{GlsXtrLoadResources} changes the category code of \code{@} to allow for
16463 internal commands in \glspl{location}.) This unusual case is for illustrative purposes.
16464 \end{enumerate}
16465
16466 \optsection{max-loc-diff}
16467
16468 This setting is used to determine whether two \glspl{location} are
16469 considered consecutive.
16470 The value must be an integer greater than or equal to 1.
16471 (The default is \optfmt{1}.)
16472
16473 For two \glspl{location}, \meta{location-1} and \meta{location-2},
16474 that have numeric values $n_1$ and $n_2$ (and identical prefix,
16475 counter and format), then the sequence \meta{location-1},
16476 \meta{location-2} is considered consecutive if
16477 \[
16478 0 < n_2 - n_1 \leq \text{\meta{max-loc-diff}}
16479 \]
16480 The default value of 1 means that \meta{location-2} immediately
16481 follows \meta{location-1} if $n_2 = n_1+1$.
16482
16483 For example, if \meta{location-1} is \qt{B} and \meta{location-2}
16484 is \qt{C}, then $n_1 = 66$ and $n_2 = 67$. Since $n_2 = 67 = 66+1=
16485 n_1+1$ then \meta{location-2} immediately follows \meta{location-1}.
16486
16487 This is used in the \idx{implicit-range} formations within
16488 the \glspl{locationlist} (as described
16489 in the above section).
16490 So, for example, the list \qt{1, 2, 3, 5, 7, 8, 10, 11, 12, 58, 59,
16491 61} becomes
16492 \qt{1--3, 5, 7, 8, 10--12, 58, 59, 61}.
16493
16494 The automatically indexing of commands like \ics{gls} means that
16495 the \glspl{locationlist} can become long and ragged. You could
16496 deal with this by switching off the automatic indexing and
16497 only explicitly index pertinent use or you can adjust
16498 the value of \optfmt{max-loc-diff} so that a \idx{range} can be formed even
16499 if there are one or two gaps in it.
16500 By default, any \idxpl{range} that have skipped gaps in this
16501 manner will be followed by \gls!{bibglspassim}. The default
16502 definition of this command is obtained from the resource file.
16503 For English, this is \verb*| passim| (space followed by \qt{passim}).
16504
16505 So with the above set of \glspl{location}, if \csopt[2]{max-loc-diff} then
16506 the list becomes \qt{1--12 passim, 58--61 passim} which now highlights that
16507 there are two blocks within the document related to that
16508 term.
16509
16510 \optsection{suffixF}
16511
16512 If set, an \idx{implicit-range} consisting of two consecutive
16513 \glspl{location} \meta{loc-1} and \meta{loc-2} will be displayed in
16514 the \gls{locationlist} as \meta{loc-1}\meta{value}. This option
16515 doesn't affect \idxpl{explicit-range}, even with
16516 \csopt[true]{merge-ranges}.
16517
16518 Note that \csopt[\empty]{suffixF} sets the suffix to the
16519 empty string. To remove the suffix formation use
16520 \csopt[none]{suffixF}.
16521
16522 The default is \csopt[none]{suffixF}.
16523
16524 \optsection{suffixFF}
16525
16526 If set, an \idx{implicit-range} consisting of three or more
16527 consecutive \glspl{location} \meta{loc-1} and \meta{loc-2} will be
16528 displayed in the \gls{locationlist} as \meta{loc-1}\meta{value}.
16529 This option doesn't affect \idxpl{explicit-range}, even with
16530 \csopt[true]{merge-ranges}.
16531
16532 Note that \csopt[\empty]{suffixFF} sets the suffix to the
16533 empty string. To remove the suffix formation use
16534 \csopt[none]{suffixFF}.
16535
16536 The default is \csopt[none]{suffixFF}.
16537
16538 \optsection{compact-ranges}
16539
16540 The \meta{value} may be an integer \meta{n} or \optfmt{false} (equivalent to
16541 \csopt[0]{compact-ranges}) or \optfmt{true} (equivalent to
16542 \csopt[3]{compact-ranges}). If no \meta{value} is specified,
16543 \optfmt{true} is assumed.
16544
16545 This setting allows location \idxpl{range} such as 184--189 to appear
16546 more compactly as 184--9. The end \gls{location} is encapsulated
16547 in the command \gls{bibglscompact}, so the \idx{range} would actually
16548 become:
16549 \begin{codeenv}
16550 184\ics{delimR}\gls{bibglscompact}\marg{digit}\marg{18}\marg{9}
16551 \end{codeenv}
16552 If the \gls{location} is in the form \code{\meta{cs}\margm{loc}}
16553 (where \meta{cs} is a command)
16554 then \gls{bibglscompact} will be inside the argument.
16555 For example, if the \idx{range} would normally be:
16556 \begin{codeenv}
16557 \cmd{custom}\marg{184}\ics{delimR}\cmd{custom}\marg{189}
16558 \end{codeenv}
16559 then it would become:
16560 \begin{codeenv}
16561 \cmd{custom}\marg{184}\ics{delimR}\cmd{custom}\marg{\gls{bibglscompact}\marg{digit}\marg{18}\marg{9}}
16562 \end{codeenv}
16563 The numerical value given in \csopt[\meta{n}]{compact-ranges}
16564 indicates that compaction should only occur if the actual \gls{location}
16565 consists of at least \meta{n} characters, for $\meta{n} \geq 2$.
16566 Any value of \meta{n} less than 2 will switch off compaction.
16567
16568 For example, \code{189} consists of 3 characters, so it will be
16569 compacted with \csopt[3]{compact-ranges} but not with
16570 \csopt[4]{compact-ranges}. Whereas \code{\csfmt{custom}\marg{89}}
16571 would only be compacted with \csopt[2]{compact-ranges}
16572 because \code{89} only consists of 2 characters.
16573
16574 The compaction isn't limited to decimal digits but it will only
16575 occur if both the start and end \gls{location} have the same number of
16576 characters. For example, xvi--xviii can't be compacted because
16577 the start consists of three characters and the end consists
16578 of five characters, whereas xxv--xxx can be compacted to xxv--x,
16579 which may look a little strange. In this case, you may want to
16580 consider changing the definition of \cs{bibglscompact} so that
16581 it only performs the compaction for digits.
16582
16583 \optsection{see}
16584
16585 If an entry has a \field{see} field, this can be placed before or
16586 after the \gls{locationlist}, or completely omitted (but the value will
16587 still be available in the \field{see} field for use with
16588 \ics{glsxtrusesee}). The required \meta{value} must be one of:
16589 \begin{itemize}
16590 \item \optfmt{omit}: omit the see reference from the
16591 \gls{locationlist}.
16592
16593 \item \optfmt{before}: place the see reference before the
16594 \gls{locationlist}.
16595
16596 \item \optfmt{after}: place the see reference after the
16597 \gls{locationlist} (default).
16598 \end{itemize}
16599
16600 The separator between the \gls{locationlist} and the cross-reference is
16601 provided by \gls!{bibglsseesep}. This separator is omitted if the
16602 \gls{locationlist} is empty. The cross-reference is written to the
16603 \field{location} field using \code{\gls{bibglsusesee}\margm{label}}.
16604
16605 \optsection{seealso}
16606
16607 This is like \csopt{see} but governs the location of the cross-references
16608 provided by the \field{seealso} field. You need at least v1.16
16609 of \sty{glossaries-extra} for this option. The values are the
16610 same as for \csopt{see} but the separator is given by
16611 \gls!{bibglsseealsosep}. The cross-reference is written to the
16612 \field{location} field using \code{\gls{bibglsuseseealso}\margm{label}}.
16613
16614 \optsection{alias}
16615
16616 This is like \csopt{see} but governs the location of the cross-references
16617 provided by the \field{alias} field. The separator is given by
16618 \gls!{bibglsaliassep}. The cross-reference is written to the
16619 \field{location} field using \code{\gls{bibglsusealias}\margm{label}}.
16620
16621 \optsection{alias-loc}
16622
16623 If an entry has an \field{alias} field, the \gls{locationlist}
16624 may be retained or omitted or transferred to the target entry.
16625 The required \meta{value} must be one of:
16626 \begin{itemize}
16627 \item\optfmt{keep}: keep the \gls{locationlist};
16628 \item\optfmt{transfer}: transfer the \gls{locationlist};
16629 \item\optfmt{omit}: omit the \gls{locationlist}.
16630 \end{itemize}
16631 The default setting is \csopt[transfer]{alias-loc}.
16632 In all cases, the target entry will be added to the \field{see}
16633 field of the entry with the \field{alias} field, unless it
16634 already has a \field{see} field (in which case the \field{see} value
16635 is left unchanged).
16636
16637 Note that with \csopt[transfer]{alias-loc}, both the aliased
16638 entry and the target entry must be in the same resource set.
16639 (That is, both entries have been selected by the same instance of
16640 \gls!{GlsXtrLoadResources}.) If you have \sty{glossaries-extra} version~1.12,
16641 you may need to redefine \ics{glsxtrsetaliasnoindex} to do
16642 nothing if the \glspl{locationlist} aren't showing correctly
16643 with aliased entries. (This was corrected in version~1.13.)
16644
16645 \optsection{loc-prefix}
16646
16647 The \csopt{loc-prefix} setting indicates that the \glspl{locationlist}
16648 should begin with \code{\gls!{bibglslocprefix}\margm{n}}. The \meta{value} may
16649 be one of the following:
16650 \begin{itemize}
16651 \item \optfmt{false}: don't insert \code{\gls{bibglslocprefix}\margm{n}} at the
16652 start of the \glspl{locationlist} (default).
16653
16654 \item \optfmt{\margm{prefix-1},\margm{prefix-2},\ldots,\margm{prefix-n}}:
16655 insert \code{\gls{bibglslocprefix}\margm{n}} (where \meta{n} is the number of
16656 \glspl{location} in the list) at the start of each \gls{locationlist} and the
16657 definition of \gls{bibglslocprefix} will have an \ics{ifcase} condition:
16658 \begin{codeenv}
16659 \cmd{providecommand}\marg{\gls{bibglslocprefix}}[1]\marg{\comment{}
16660 \ics{ifcase}\idx{param}1
16661 \cmd{or} \meta{prefix-1}\gls{bibglspostlocprefix}
16662 \cmd{or} \meta{prefix-2}\gls{bibglspostlocprefix}
16663 \ldots
16664 \cmd{else} \meta{prefix-n}\gls{bibglspostlocprefix}
16665 \cmd{fi}
16666 }
16667 \end{codeenv}
16668
16669 \item \optfmt{comma}: equivalent to \csopt[\marg{,~}]{loc-prefix}
16670 but avoids confusion with the list syntax. That is, the prefix is a comma
16671 followed by a space for non-empty \glspl{locationlist}.
16672
16673 \item \optfmt{list}: equivalent to \csopt[\ics{pagelistname} ]{loc-prefix}.
16674
16675 \item \optfmt{true}: equivalent to
16676 \csopt[\gls{bibglspagename},\gls{bibglspagesname}]{loc-prefix},
16677 where the definitions of \gls{bibglspagename} and
16678 \gls{bibglspagesname} are obtained from the \idx{tag.page} and
16679 \idx{tag.pages} entries in \bibgls's \langxml.
16680 This setting works best if the document's language matches the
16681 language file. However, you can redefine these commands within
16682 the document's language hooks or in the glossary preamble.
16683
16684 \end{itemize}
16685
16686 If \meta{value} is omitted, \optfmt{true} is assumed. The definition
16687 will be placed in the \ext{glstex} file according to
16688 \csopt{loc-prefix-def}.
16689
16690 For example:
16691 \begin{codeenv}
16692 \gls{GlsXtrLoadResources}\oarg{\csopt[main]{type},\csopt[individual]{loc-prefix-def},\csopt[entries1]{src},\csopt[false]{loc-prefix}}
16693 \gls{GlsXtrLoadResources}\oarg{\csopt[main]{type},\csopt[individual]{loc-prefix-def},\csopt[entries2]{src},\csopt{loc-prefix}}
16694 \gls{GlsXtrLoadResources}\oarg{\csopt[symbols]{type},\csopt[entries3]{src},\csopt[p.,pp.]{loc-prefix}}
16695 \end{codeenv}
16696 This works since the conflicting \csopt[p.,pp.]{loc-prefix} and
16697 \csopt[true]{loc-prefix} are in different glossaries (assigned through the
16698 \csopt{type} key). The entries fetched from \filefmt{entries1.bib}
16699 won't have a location prefix. The entries fetched from
16700 \filefmt{entries2.bib} will have the location prefix obtained from
16701 the language resource file. The entries fetched from
16702 \filefmt{entries3.bib} will have the location prefix \qt{p.}\ or
16703 \qt{pp.} (Note that using the \csopt{type} option isn't the same as
16704 setting the \field{type} field for each entry in the \ext{bib}
16705 file.)
16706
16707 If the \csopt{type} option isn't used:
16708 \begin{codeenv}
16709 \gls{GlsXtrLoadResources}\oarg{\csopt[entries1]{src},\csopt[false]{loc-prefix}}
16710 \gls{GlsXtrLoadResources}\oarg{\csopt[entries2]{src},\csopt{loc-prefix}}
16711 \gls{GlsXtrLoadResources}\oarg{\csopt[entries3]{src},\csopt[p.,pp.]{loc-prefix}}
16712 \end{codeenv}
16713 then \csopt[true]{loc-prefix} takes precedence over
16714 \csopt[p.,pp.]{loc-prefix} (since it was used first). The entries fetched from
16715 \filefmt{entries1.bib} still won't have a location prefix, but the entries
16716 fetched from both \filefmt{entries2.bib} and \filefmt{entries3.bib}
16717 have the location prefixes obtained from the language resource file.
16718
16719 Note that if you identify some glossaries but not others (for
16720 example, you have dual entries in separate glossaries but only
16721 use \csopt{type} and not \csopt{dual-type}), then you will need to
16722 use \csopt[global]{loc-prefix-def} or \csopt[local]{loc-prefix-def}.
16723
16724 \optsection{loc-prefix-def}
16725
16726 This determines how the location prefix identified by
16727 \csopt{loc-prefix} is written to the \ext{glstex} file. The value
16728 may be one of:
16729 \begin{itemize}
16730 \item\optfmt{global} the definition is globally defined using
16731 \cs{providecommand};
16732 \item\optfmt{local} the definition is locally defined using
16733 \cs{providecommand} in the general glossary preamble
16734 (\cs{glossarypreamble});
16735 \item\optfmt{individual} the definition is locally defined using
16736 \cs{providecommand} in the glossary preamble of each type that has
16737 been identified in the current \gls{resourceset}, using options like
16738 \csopt{type} and \csopt{dual-type}
16739 (\ics{apptoglossarypreamble}).
16740 \end{itemize}
16741 The default is \csopt[individual]{loc-prefix-def}. Note that this
16742 can lead to an undefined control sequence error if locations appear
16743 in a glossary that hasn't been detected by the \gls{resourceset}.
16744
16745 \optsection{loc-suffix}
16746
16747 This is similar to \csopt{loc-prefix} but there are some subtle
16748 differences. In this case \meta{value} may either be the keyword
16749 \optfmt{false} (in which case the location suffix is omitted) or a
16750 comma-separated list
16751 \optfmt{\meta{suffix-0}\dcomma\meta{suffix-1}\dcomma\ldots\dcomma\meta{suffix-n}}
16752 where \meta{suffix-0} is the suffix to use when the
16753 \gls{locationlist} only has a cross-reference with no
16754 \glspl{location}, \meta{suffix-1} is the suffix to use when the
16755 \gls{locationlist} has one \gls{location} (optionally with a
16756 cross-reference), and so on. The final \meta{suffix-n} in the list
16757 is the suffix when the \gls{locationlist} has \meta{n} or more
16758 \glspl{location} (optionally with a cross-reference).
16759
16760 This option will append \code{\gls!{bibglslocsuffix}\margm{n}} to
16761 \glspl{locationlist} that either have a cross-reference or have at
16762 least one \gls{location}. Unlike \gls{bibglslocprefix}, this
16763 command isn't used when the \gls{locationlist} is completely empty.
16764 Also, unlike \gls{bibglslocprefix}, this suffix command doesn't have
16765 an equivalent to \gls{bibglspostlocprefix}.
16766
16767 If \meta{value} omitted, \csopt[\ics{at}\idx{periodchar}]{loc-suffix}
16768 is assumed. The default is \csopt[false]{loc-suffix}.
16769
16770 The way the definition is written to the \ext{glstex} file is determined
16771 by \csopt{loc-suffix-def}.
16772 Note that if you identify some glossaries but not others (for
16773 example, you have dual entries in separate glossaries but only
16774 use \csopt{type} and not \csopt{dual-type}), then you will need to
16775 use \csopt[global]{loc-suffix-def} or \csopt[local]{loc-suffix-def}.
16776
16777 \optsection{loc-suffix-def}
16778
16779 This determines how the location suffix identified by
16780 \csopt{loc-suffix} is written to the \ext{glstex} file. The value
16781 may be one of:
16782 \begin{itemize}
16783 \item\optfmt{global} the definition is globally defined using
16784 \cs{providecommand};
16785 \item\optfmt{local} the definition is locally defined using
16786 \cs{providecommand} in the general glossary preamble
16787 (\cs{glossarypreamble});
16788 \item\optfmt{individual} the definition is locally defined using
16789 \cs{providecommand} in the glossary preamble of each type that has
16790 been identified in the current \gls{resourceset}, using options like
16791 \csopt{type} and \csopt{dual-type}
16792 (\ics{apptoglossarypreamble}).
16793 \end{itemize}
16794 The default is \csopt[individual]{loc-suffix-def}. Note that this
16795 can lead to an undefined control sequence error if locations appear
16796 in a glossary that hasn't been detected by the \gls{resourceset}.
16797
16798 \optsection{loc-counters}
16799
16800 Commands like \ics{gls} allow you to select a different
16801 counter to use for the \gls{location} for that specific instance
16802 (overriding the default counter for the entry's glossary type).
16803 This is done with the \glsopt{counter} option. For example,
16804 consider the following document:
16805 \begin{codeenv}
16806 \cmd{documentclass}\marg{article}
16807 \strut
16808 \cmd{usepackage}\oarg{colorlinks}\marg{hyperref}
16809 \cmd{usepackage}\oarg{\styopt{record},\styopt[tree]{style}}\marg{glossaries-extra}
16810 \strut
16811 \gls{GlsXtrLoadResources}\oarg{
16812 \csopt[entries]{src}\comment{data in entries.bib}
16813 }
16814 \strut
16815 \cmd{begin}\marg{document}
16816 \strut
16817 \cs{gls}\marg{pi}.
16818 \cmd{begin}\marg{equation}
16819 \cs{gls}\oarg{\glsopt[\counter{equation}]{counter}}\marg{pi}
16820 \cmd{end}\marg{equation}
16821 \cmd{begin}\marg{equation}
16822 \cs{gls}\oarg{\glsopt[\counter{equation}]{counter}}\marg{pi}
16823 \cmd{end}\marg{equation}
16824 \strut
16825 \cmd{newpage}
16826 \cmd{begin}\marg{equation}
16827 \cs{gls}\oarg{\glsopt[\counter{equation}]{counter}}\marg{pi}
16828 \cmd{end}\marg{equation}
16829 \strut
16830 \cmd{newpage}
16831 \cs{gls}\marg{pi}.
16832 \strut
16833 \cmd{newpage}
16834 \cs{gls}\marg{pi}.
16835 \strut
16836 \cmd{newpage}
16837 \cs{gls}\marg{pi}.
16838 \strut
16839 \cmd{newpage}
16840 \cs{printunsrtglossaries}
16841 \cmd{end}\marg{document}
16842 \end{codeenv}
16843 This results in the \gls{locationlist} \qt{1, 1--3, 3--5}. This
16844 looks a little odd and it may seem as though the \idx{implicit-range} formation
16845 hasn't worked, but the \glspl{location} are actually: page~1, equation~1,
16846 equation~2, equation~3, page~3, page~4 and page~5. \Idxpl{range} can't
16847 be formed across different counters.
16848
16849 The \csopt[\meta{list}]{loc-counters} option instructs \bibgls\
16850 to group the \glspl{location} according to the counters given in
16851 the comma-separated \meta{list}. If a \gls{location} has a counter
16852 that's not listed in \meta{list}, then the \gls{location} is discarded.
16853
16854 For example:
16855 \begin{codeenv}
16856 \gls{GlsXtrLoadResources}\oarg{
16857 \csopt[\counter{equation},\counter{page}]{loc-counters},\comment{group locations by counter}
16858 \csopt[entries]{src}\comment{data in entries.bib}
16859 }
16860 \end{codeenv}
16861 This will first list the \glspl{location} for the \counter{equation}
16862 counter and then the \glspl{location} for the \counter{page} counter.
16863 Each group of \glspl{location} is encapsulated within the command
16864 \gls!{bibglslocationgroup}\margm{n}\margm{counter}\margm{locations}.
16865 The groups are separated by \gls!{bibglslocationgroupsep}.
16866
16867 The \meta{list} value must be non-empty. Use
16868 \csopt[as-use]{loc-counters} to restore the default behaviour, where
16869 the \glspl{location} are listed in the document order of use, or
16870 \csopt[false]{save-locations} to omit the \glspl{locationlist}. Note that
16871 you can't form counter groups from
16872 \hyperref[sec:supplementalopts]{supplemental location lists}.
16873
16874 \optsection{save-index-counter}
16875
16876 \emph{This option requires at least version 1.29 of
16877 \isty{glossaries-extra}.} The \meta{value} may be one of:
16878 \begin{itemize}
16879 \item \optfmt{false}: don't create the \field{indexcounter} field
16880 (default);
16881 \item \optfmt{true}: create the \field{indexcounter} field with the
16882 value set to the first \counter{wrglossary} \gls{location};
16883 \item \meta{encap}: create the \field{indexcounter} field with the
16884 value set to the first \counter{wrglossary} \gls{location}
16885 where the \glsopt{format} is \meta{encap}.
16886 \end{itemize}
16887 This setting will have no effect if the \styopt{indexcounter}
16888 package option hasn't been used. In the case where the \meta{value}
16889 is \meta{encap}, make sure that this format takes priority in the
16890 \gls{location} precedence rules (\longarg{map-format}). If the
16891 \gls{location} with that \meta{encap} format value is discarded then
16892 it can't be saved.
16893
16894 The \styopt{indexcounter} package option
16895 (\sty{glossaries-extra} v1.29+) creates a new counter called
16896 \counter{wrglossary} that's incremented every time a term is
16897 indexed (recorded), except for cross-references such as \cs{glssee}.
16898 The increment is performed using \ics{refstepcounter} and is
16899 followed by \code{\ics{label}\marg{wrglossary.\meta{n}}} where
16900 \meta{n} is the value of the \counter{wrglossary} counter.
16901 This option is intended for use with the \sty{hyperref} package to
16902 allow \glspl{location} to link back to the particular part of the page where
16903 the term was referenced rather than to the top of the page.
16904
16905 \begin{important}
16906 Take care not to confuse this with the \field{indexed} special internal field
16907 introduced in \sty{glossaries-extra} v1.49+. This is incremented on a per-entry basis
16908 and does not have an associated counter.
16909 \end{important}
16910
16911 The \styopt{indexcounter} package option also automatically
16912 implements the option \styopt[wrglossary]{counter}, which means that
16913 each instance of \code{\ics{gls}\margm{id}} writes the label
16914 information to the \iext{aux} file:
16915 \begin{codeenv}
16916 \cmd{newlabel}\marg{wrglossary.\meta{n}}\marg{\margm{n}\margm{page}\marg{}\marg{wrglossary.\meta{n}}\marg{}}
16917 \end{codeenv}
16918 (where \meta{page} is the page number) followed by the record:
16919 \begin{codeenv}
16920 \gls{glsxtr@record}\margm{id}\marg{}\marg{wrglossary}\marg{\encap{glsnumberformat}}\margm{n}
16921 \end{codeenv}
16922 The \gls{location} here is actually the value of the \counter{wrglossary}
16923 counter not the page number, but \bibgls\ can pick up the
16924 corresponding \meta{page} from the \csfmt{newlabel} command. It then
16925 replaces the \gls{record}['s] location \meta{n} with:
16926 \nosecdef{glsxtr@wrglossarylocation}
16927 (but it only does this for \glspl{record} that have the \counter{wrglossary}
16928 counter).
16929
16930 The \sty{glossaries-extra} package (v1.29+) adjusts the definition
16931 of \ics{glshypernumber} (which is internally used by
16932 \cs{glsnumberformat}, \cs{hyperbf} etc when \sty{hyperref} has been
16933 loaded) so that if the counter is \counter{wrglossary} then
16934 \ics{pageref} is used instead of \ics{hyperlink}. This means that the
16935 page number is displayed in the \gls{locationlist} but it links back to
16936 the place where the corresponding \cs{label} occurred.
16937
16938 This method works partially with \idx!{makeindex} and \idx!{xindy}
16939 but from their point of view the \gls{location} is the value of the
16940 \counter{wrglossary} counter, which interferes with their ability to
16941 merge duplicate page numbers and form \idxpl{range}. Since \bibgls\ is
16942 designed specifically to work with \sty{glossaries-extra}, it's
16943 aware of this special counter and will merge and collate the
16944 \glspl{location} according to the corresponding page number instead.
16945
16946 With the default \longarg{merge-wrglossary-records} switch, if a
16947 term has multiple \counter{wrglossary} records for a given page they
16948 will be merged. The reference link will be the dominant record for
16949 that page.
16950
16951 The \csopt{save-index-counter} option allows you to save the first
16952 of the \counter{wrglossary} \glspl{location} for a given entry or the first
16953 instance of a specific format of the \counter{wrglossary} \glspl{location}
16954 for a given entry. This \gls{location} is stored in the
16955 \field{indexcounter} internal field using:
16956 \begin{codeenv}
16957 \ics{GlsXtrSetField}\margm{id}\marg{\field{indexcounter}}\marg{\gls{glsxtr@wrglossarylocation}\margm{n}\margm{page}}
16958 \end{codeenv}
16959 Since \gls{glsxtr@wrglossarylocation} simply expands to its first
16960 argument, the corresponding label can be obtained with:
16961 \begin{codeenv}
16962 wrglossary.\gls{glsxtr@wrglossarylocation}\margm{n}\margm{page}
16963 \end{codeenv}
16964 For convenience, \sty{glossaries-extra-bib2gls} provides:
16965 \nosecdef{GlsXtrIndexCounterLink}
16966 which will do:
16967 \begin{codeenv*}
16968 \ics{cs.hyperref.int}\oarg{wrglossary.\meta{value}}\margm{text}
16969 \end{codeenv*}
16970 where \meta{value} is the value of the \field{indexcounter} field if
16971 it has been set. If the \field{indexcounter} field hasn't been set
16972 (or if \sty{hyperref} hasn't been loaded) then just \meta{text} is
16973 done.
16974
16975 This provides a convenient way of encapsulating the \field{name} in
16976 the glossary so that it links back to the first \counter{wrglossary}
16977 entry or the first \glsopt[\meta{encap}]{format} \counter{wrglossary}
16978 entry. This encapsulation can be done by providing a new glossary
16979 style or more simply by redefining \ics{glsnamefont}:
16980 \begin{codeenv}
16981 \cmd{renewcommand}\marg{\cs{glsnamefont}}[1]\marg{\comment{}
16982 \gls{GlsXtrIndexCounterLink}\marg{\idx{param}1}\marg{\cs{glscurrententrylabel}}}
16983 \end{codeenv}
16984 Here's a complete example:
16985 \begin{codeenv}
16986 \cmd{documentclass}\marg{article}
16987 \strut
16988 \cmd{usepackage}\marg{lipsum}\comment{dummy filler text}
16989 \cmd{usepackage}\oarg{colorlinks}\marg{hyperref}
16990 \cmd{usepackage}\oarg{\styopt{record},\styopt{indexcounter}}\marg{glossaries-extra}
16991 \strut
16992 \cmd{newcommand}\marg{\cmd{primary}}[1]\marg{\cs{hyperbf}\marg{\idx{param}1}}
16993 \strut
16994 \gls{GlsXtrLoadResources}\oarg{
16995 \csopt[entries]{src},\comment{terms defined in entries.bib}
16996 \csopt[primary]{save-index-counter}
16997 }
16998 \strut
16999 \cmd{renewcommand}\marg{\cs{glsnamefont}}[1]\marg{\comment{}
17000 \gls{GlsXtrIndexCounterLink}\marg{\idx{param}1}\marg{\cs{glscurrententrylabel}}}
17001 \strut
17002 \cmd{begin}\marg{document}
17003 \strut
17004 A \cs{gls}\marg{sample}. \cmd{lipsum}*[1] A \cs{gls}\marg{duck}.
17005 \strut
17006 An equation:
17007 \cmd{begin}\marg{equation}
17008 \cs{gls}\oarg{\glsopt[\counter{equation}]{counter}}\marg{pi}
17009 \cmd{end}\marg{equation}
17010 \strut
17011 \cmd{lipsum}[2]
17012 \strut
17013 Another \cs{gls}\oarg{\glsopt[primary]{format}}\marg{sample}. \cmd{lipsum}*[3] Another
17014 \cs{gls}\marg{duck}.
17015 \strut
17016 \cs{gls}\marg{pi}. \cmd{lipsum}[4]
17017 \strut
17018 A \cs{gls}\marg{sample}. \cmd{lipsum}*[5] A \cs{gls}\marg{duck} and
17019 \cs{gls}\oarg{\glsopt[primary]{format}}\marg{pi}.
17020 \strut
17021 \cmd{lipsum}*[6] A \cs{gls}\oarg{\glsopt[primary]{format}}\marg{duck}.
17022 \strut
17023 \cs{printunsrtglossaries}
17024 \cmd{end}\marg{document}
17025 \end{codeenv}
17026 Note that the \glsopt[\counter{equation}]{counter} entry will have its own
17027 independent \gls{location}. In this example, it's difficult to tell the
17028 difference between 1 (the equation reference) and 1 (the page
17029 reference) in the \gls{locationlist} for the \code{pi} entry.
17030
17031 The \glsopt[primary]{format} instances indicate
17032 \glsdisp{principallocation}{principal} references.
17033 They're displayed in bold (since \csfmt{primary} is defined to use
17034 \csfmt{hyperbf}) and these are the \glspl{location} saved in the
17035 \field{indexcounter} field because that's the \meta{encap}
17036 identified by the \csopt[primary]{save-index-counter} setting.
17037
17038 \section{Supplemental Locations}
17039 \label{sec:supplementalopts}
17040
17041 \emph{These options require at least version 1.14 of
17042 \isty{glossaries-extra}.} If you require \glspl{location} from multiple
17043 external sources, then you need at least version 1.36 of
17044 \isty{glossaries-extra} (or, more specifically,
17045 \isty{glossaries-extra-bib2gls}, which is automatically loaded
17046 by the \styopt[only]{record} package option).
17047
17048 The \sty{glossaries-extra} package (from v1.14) provides a way of
17049 manually adding \glspl{location} in \glspl{supplementaldocument} through the use
17050 of the \glsaddopt{thevalue} option in the optional argument of
17051 \ics{glsadd}. Setting values manually is inconvenient and can result
17052 in errors, so \bibgls\ provides a way of doing this automatically.
17053 Both the \gls{maindocument} and the \supplementarydocument\ need to use
17054 the \styopt{record} option. The entries provided in the \csopt{src}
17055 set must have the same labels as those used in the
17056 \supplementarydocument. (The simplest way to achieve this is to ensure that both
17057 documents use the same \ext{bib} files and the same prefixes.)
17058
17059 For example, suppose the file \filefmt{entries.bib} contains:
17060 \begin{codeenv}
17061 \atentry{entry}\marg{sample,
17062 \field{name}=\marg{sample},
17063 \field{description}=\qtdelim{an example entry}
17064 }
17065 \strut
17066 \atentry{abbreviation}\marg{html,
17067 \field{short}=\qtdelim{html},
17068 \field{long}=\marg{hypertext markup language}
17069 }
17070 \strut
17071 \atentry{abbreviation}\marg{ssi,
17072 \field{short}=\qtdelim{ssi},
17073 \field{long}=\qtdelim{server-side includes}
17074 }
17075 \strut
17076 \atentry{index}\marg{goose,\field{plural}=\qtdelim{geese}}
17077 \end{codeenv}
17078 Now suppose the supplementary document is contained in the file
17079 \filefmt{suppl.tex}:
17080 \begin{codeenv}
17081 \cmd{documentclass}\marg{article}
17082 \strut
17083 \cmd{usepackage}\oarg{colorlinks}\marg{hyperref}
17084 \cmd{usepackage}\oarg{\styopt{record},\styopt[section]{counter}}\marg{glossaries-extra}
17085 \strut
17086 \gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}}
17087 \strut
17088 \cmd{renewcommand}\marg{\cmd{thesection}}\marg{S\cmd{arabic}\marg{section}}
17089 \cmd{renewcommand}\marg{\cmd{theHsection}}\marg{\cmd{thepart}.\cmd{thesection}}
17090 \strut
17091 \cmd{begin}\marg{document}
17092 \cmd{part}\marg{Sample Part}
17093 \cmd{section}\marg{Sample Section}
17094 \cs{gls}\marg{goose}. \cs{gls}\marg{sample}.
17095 \strut
17096 \cmd{part}\marg{Another Part}
17097 \cmd{section}\marg{Another Section}
17098 \cs{gls}\marg{html}.
17099 \cs{gls}\marg{ssi}.
17100 \strut
17101 \cs{printunsrtglossaries}
17102 \cmd{end}\marg{document}
17103 \end{codeenv}
17104 This uses the \counter{section} counter for the \glspl{location} and has a
17105 prefix (\code{\csfmt{thepart}.})\ for the section hyperlinks.
17106
17107 Now let's suppose I have another document called \filefmt{main.tex}
17108 that uses the \code{sample} entry, but also needs to include the
17109 \gls{location} (S1) from the \supplementarydocument. The manual approached
17110 offered by \styfmt{glossaries-extra} is quite cumbersome and requires
17111 setting the \catattr{externallocation} attribute and using
17112 \ics{glsadd} with \glsaddopt[S1]{thevalue}, \glsaddopt[I.S1]{theHvalue}
17113 and \glsaddopt[\encap{glsxtrsupphypernumber}]{format}.
17114
17115 This can be simplified with \bibgls\ by using the
17116 \optfmt{supplemental-locations} option, described below.
17117
17118 Version 1.36 of \isty{glossaries-extra-bib2gls} introduces some
17119 special \gls{location} formatting commands that don't use the
17120 \catattr{externallocation} attribute, but instead have an extra
17121 argument that indicates the external reference. The additional
17122 argument means that it can't be used by the \glsaddopt{format}
17123 key, but with \bibgls\ you don't use \cs{glsadd} to record
17124 the external \glspl{location}. Instead it obtains the \glspl{record} from
17125 the corresponding \supplementary\ \ext{aux} file, and adjusts the
17126 \gls{location} encapsulator as appropriate.
17127
17128 If \bibgls\ detects an older version of \sty{glossaries-extra},
17129 it will only allow one external \supplemental\ source, and
17130 will set the \catattr{externallocation} attribute and use
17131 the \encap{glsxtrsupphypernumber} format. Otherwise \bibgls\
17132 will allow multiple sources and use the newer method.
17133
17134 \optsection{supplemental-locations}
17135
17136 The value should be the base name (without the extension) of the
17137 \supplementarydocument\ (\optfmt{suppl} in the above example).
17138 If you have at least version 1.36 of \sty{glossaries-extra},
17139 the value may be a comma-separated list of base names (without the
17140 extensions) of the \supplementarydocuments. If an older version is
17141 detected, \bibgls\ will issue a warning and only accept the first
17142 element of the list.
17143
17144 For example:
17145 \begin{codeenv}
17146 \cmd{documentclass}\marg{article}
17147 \strut
17148 \cmd{usepackage}\oarg{colorlinks}\marg{hyperref}
17149 \cmd{usepackage}\oarg{\styopt{record}}\marg{glossaries-extra}
17150 \strut
17151 \gls{GlsXtrLoadResources}\oarg{
17152 \csopt[suppl]{supplemental-locations},\comment{fetch records from suppl.aux}
17153 \csopt[entries]{src}}
17154 \strut
17155 \cmd{begin}\marg{document}
17156 \cs{Gls}\marg{sample} document.
17157 \strut
17158 \cs{printunsrtglossaries}
17159 \cmd{end}\marg{document}
17160 \end{codeenv}
17161 The \gls{locationlist} for \code{sample} will now be \qt{1, S1} (page~1
17162 from the \gls{maindocument} and S1 from the \supplementarydocument).
17163
17164 With \sty{glossaries-extra} v1.36+, a regular \gls{location} from the
17165 \supplementarydocument\ will be encapsulated with:
17166 \nosecdef{glsxtrdisplaysupploc}
17167 By default, this simply creates an external hyperlink to the
17168 \supplementarydocument\ with the \gls{location} as the hyperlink text.
17169 The hyperlink is created using \meta{src} as the target path
17170 with the fragment part (anchor) formed from the prefix and
17171 \gls{location}. The \catattr{externallocation} attribute is not set in
17172 this case. The actual formatting is done via:
17173 \nosecdef{glsxtrmultisupplocation}
17174 which ignores the \meta{format} argument by default. Its
17175 definition is simply:
17176 \begin{codeenv}
17177 \cmd{newcommand}*\marg{\gls{glsxtrmultisupplocation}}[3]\marg{\comment{}
17178 \marg{\comment{scope required to localise changes}
17179 \cmd{def}\cs{glsxtrsupplocationurl}\marg{\idx{param}2}\comment{}
17180 \cs{glshypernumber}\marg{\idx{param}1}\comment{}
17181 }\comment{}
17182 }
17183 \end{codeenv}
17184 This locally sets the command \ics{glsxtrsupplocationurl}, which is checked
17185 by \ics{glshypernumber} to establish an external rather than internal link.
17186 You can redefine the \supplementallocation\ command to retain the original
17187 \idx{encap} used in the target document:
17188 \begin{codeenv}
17189 \cmd{renewcommand}*\marg{\gls{glsxtrmultisupplocation}}[3]\marg{\comment{}
17190 \marg{\comment{scope required to localise changes}
17191 \cmd{def}\cs{glsxtrsupplocationurl}\marg{\idx{param}2}\comment{}
17192 \ics{csuse}\marg{\idx{param}3}\marg{\idx{param}1}\comment{}
17193 }\comment{}
17194 }
17195 \end{codeenv}
17196 but remember that if a hyperlink is required, the identified
17197 control sequence name must correspond to a command that
17198 uses \cs{glshyperlink} (such as \cs{hyperbf}), otherwise you
17199 will lose the hyperlink.
17200
17201 With older versions of \sty{glossaries-extra},
17202 the original \gls{location} format from the \supplementarydocument\
17203 will be replaced by \encap{glsxtrsupphypernumber}, which
17204 again produces an external hyperlink. The \catattr{externallocation}
17205 attribute also needs to be set (this can be done automatically with
17206 \csopt{supplemental-category}) to identify the external document.
17207 The original format can't be accessed.
17208
17209 In both cases, if the document hasn't loaded the \isty{hyperref} package, the
17210 \gls{location} will simply be displayed without a hyperlink. Even if both the main
17211 and the \supplementarydocuments\ have loaded \sty{hyperref}, note that not all
17212 PDF viewers can handle external hyperlinks, and some that can open the external
17213 PDF file may not recognise the destination within that file.
17214
17215 The special \code{nameref} \glspl{location} (see
17216 \longarg{merge-nameref-on}) are still identified with
17217 \gls!{glsxtrdisplaylocnameref} but the \meta{file} argument will now
17218 be set.
17219
17220 As from \bibgls\ v1.7, any awkward characters in the file path are
17221 replaced with \gls{bibglshrefchar} or (for \idx{non-ASCII}
17222 characters, when supported) \gls{bibglshrefunicode}. Both commands
17223 take two arguments: the hexadecimal character code and the actual
17224 character. In the case of \gls{bibglshrefchar}, the second
17225 argument is ignored, and the first is preceded by a literal percent
17226 character, so \filefmt{file name.pdf} will be converted to:
17227 \begin{codeenv}
17228 file\gls{bibglshrefchar}\marg{20}\marg{ }name.pdf
17229 \end{codeenv}
17230 which will expand to \verb|file%20name.pdf|.
17231 In the case of \gls{bibglshrefunicode}, the first argument is
17232 ignored, so \filefmt{skr\'aarnafn.pdf} will be converted to:
17233 \begin{codeenv}
17234 skr\gls{bibglshrefunicode}\marg{E1}\marg{\'a}arnafn.pdf
17235 \end{codeenv}
17236 which will expand to \code{skr\'aarnafn.pdf}.
17237
17238
17239 The \supplementarylocation\ lists are encapsulated within
17240 \gls{bibglssupplemental}. With \sty{glossaries-extra} v1.36+,
17241 this command will encapsulate the sub-lists with
17242 \gls{bibglssupplementalsublist}.
17243
17244 So the above example with an old version of \sty{glossaries-extra}
17245 (pre 1.36) will set the \supplementallocation\ list (which only consists
17246 of one \gls{location}) to:
17247 \begin{codeenv}
17248 \gls{bibglssupplemental}
17249 \marg{1}\marg{\ics{setentrycounter}\oarg{I}\marg{\counter{section}}\cs{glsxtrsupphypernumber}\marg{S1}}
17250 \end{codeenv}
17251 and the external target must be supplied through the
17252 \catattr{externallocation} attribute, which can be set
17253 with the \csopt{supplemental-category} option.
17254
17255 Whereas with at least version 1.36, the list will be:
17256 \begin{codeenv}
17257 \gls{bibglssupplemental}\marg{1}\marg{\gls{bibglssupplementalsublist}\marg{1}\marg{suppl.pdf}
17258 \marg{\gls{glsxtrdisplaysupploc}\marg{I}\marg{\counter{section}}\marg{\encap{glsnumberformat}}\marg{suppl.pdf}\marg{S1}}}
17259 \end{codeenv}
17260
17261 If an entry has both a main \gls{locationlist} and a
17262 \supplementarylocation\ list (such as the \code{sample} entry above), the lists
17263 will be separated by \gls!{bibglssupplementalsep}. The sub-lists
17264 (when supported) are separated by \gls{bibglssupplementalsubsep}.
17265
17266 \optsection{supplemental-selection}
17267
17268 In the above example, only the \code{sample} entry is listed in the
17269 \gls{maindocument}, even though the \supplementarydocument\ also
17270 references the \code{goose}, \code{html} and \code{ssi} entries. By
17271 default, only those entries that are referenced in the \gls{maindocument}
17272 will have \supplementarylocations\ added (if found in the
17273 \glsdisp{supplementaldocument}{supplementary document's} \iext{aux}
17274 file). You can additionally include other entries that are
17275 referenced in the \supplementarydocument\ but not in the main
17276 document using \optfmt{supplemental-selection}. The \meta{value} may
17277 be one of the following:
17278 \begin{itemize}
17279 \item \optfmt{all}: add all the entries in the
17280 \supplementarydocument\ that have been defined in the \ext{bib} files listed in
17281 \csopt{src} for this resource set in the \gls{maindocument}.
17282 \item \optfmt{selected}: only add \supplementallocations\ for entries
17283 that have already been selected by this \gls{resourceset}.
17284 \item \meta{label-1},\ldots,\meta{label-2}: in addition to all those
17285 entries that have already been selected by this resource set, also
17286 add the entries identified in the comma-separated list. If a label
17287 in this list doesn't have a record in the
17288 \glsdisp{supplementaldocument}{supplementary document's}
17289 \ext{aux} file, it will be ignored.
17290 \end{itemize}
17291 Any records in the \supplementary\ \ext{aux} file that aren't defined
17292 by the current resource set (through the \ext{bib} files listed in
17293 \csopt{src}) will be ignored. Entry aliases aren't taken into
17294 account when including \supplementarylocations.
17295
17296 For example:
17297 \begin{codeenv}
17298 \cmd{documentclass}\marg{article}
17299 \strut
17300 \cmd{usepackage}\oarg{colorlinks}\marg{hyperref}
17301 \cmd{usepackage}\oarg{\styopt{record}}\marg{glossaries-extra}
17302 \strut
17303 \gls{GlsXtrLoadResources}\oarg{
17304 \csopt[suppl]{supplemental-locations},
17305 \csopt[html,ssi]{supplemental-selection},
17306 \csopt[entries]{src}}
17307 \strut
17308 \cmd{begin}\marg{document}
17309 \cs{Gls}\marg{sample} document.
17310 \strut
17311 \cs{printunsrtglossaries}
17312 \cmd{end}\marg{document}
17313 \end{codeenv}
17314 This will additionally add the \code{html} and \code{ssi} entries
17315 even though they haven't been used in this document. The
17316 \code{goose} entry used in the \supplementarydocument\ won't be
17317 included.
17318
17319 \optsection{supplemental-category}
17320
17321 The \field{category} field for entries containing \supplementallocation\
17322 lists may be set using this option. If unset,
17323 \meta{value} defaults to the same as that given by the
17324 \csopt{category} option. The \meta{value} may either be a known
17325 identifier (as per \csopt{category}) or the category label. For example:
17326 \begin{codeenv}
17327 \cmd{documentclass}\marg{article}
17328 \strut
17329 \cmd{usepackage}\oarg{colorlinks}\marg{hyperref}
17330 \cmd{usepackage}\oarg{\styopt{record}}\marg{glossaries-extra}
17331 \strut
17332 \gls{GlsXtrLoadResources}\oarg{
17333 \csopt[suppl]{supplemental-locations},
17334 \csopt[html,ssi]{supplemental-selection},
17335 \csopt[supplemental]{supplemental-category},
17336 \csopt[entries]{src}}
17337 \strut
17338 \cmd{begin}\marg{document}
17339 \cs{Gls}\marg{sample} document.
17340 \strut
17341 \cs{printunsrtglossaries}
17342 \cmd{end}\marg{document}
17343 \end{codeenv}
17344
17345 A value of \code{false} will switch off this setting (the default).
17346
17347 \section{Sorting}
17348 \label{sec:sortingopts}
17349
17350 Entries are typically displayed in an ordered list, but the
17351 \styfmt{glossaries-extra} package is versatile enough to be used in
17352 wider contexts than simple terms, symbols or abbreviations. For
17353 example, entries could contain theorems or problems where the
17354 \field{name} supplies the title and the \field{description} provides
17355 a description of the theorem or problem. Another field might then
17356 contain the proof or solution. Therefore, somewhat unusually for an
17357 indexing application, \bibgls\ also provides the option to shuffle
17358 the entries instead of sorting them.
17359
17360 This section covers the resource options for sorting
17361 \glspl{primaryentry}. See \sectionref{sec:dualoptssort} for sorting
17362 \glspl{dualentry} and also \csopt{sort-label-list} for sorting field
17363 values that contain a comma-separated list of entry labels (such as
17364 the \field{see} or \field{seealso} fields).
17365
17366 The sort methods that use a comparison function (that is, all the
17367 sort methods except those listed in \tableref{tab:sortoptionsnosort})
17368 require a sort value for each entry. The function compares these
17369 values to determine the order. By default, this sort value is
17370 obtained from the \field{sort} field but for greater flexibility
17371 it's best to not actually set this field. \bibgls\ has a set of fallbacks
17372 that it uses if a field it needs to access is missing. These
17373 fallbacks depend on the \gls{entrytype} and resource settings (see
17374 \sectionref{sec:fallbacks}).
17375
17376 For example, if a term defined with \atentry{index} doesn't have the
17377 \field{sort} field set then \bibgls\ will use the value given by the
17378 \field{name} field because \field{name} is the fallback field for
17379 \field{sort} for \atentry{index} entries. If the \field{name} field
17380 isn't set either then \bibgls\ will use the fallback for that field.
17381 In the case of \atentry{index} that's the entry's label. If the
17382 \field{sort} field is explicitly set then there's no need to use the
17383 fallback.
17384
17385 If, on the other hand, a term defined with \atentry{symbol} doesn't
17386 have the \field{sort} field set then \bibgls\ will use the value
17387 from the field identified by \csopt{symbol-sort-fallback}, which is
17388 the entry's label by default (not the \field{name} field).
17389
17390 This means that if I don't explicitly set the \field{sort} field for
17391 any entries then I can, for example, sort terms defined with
17392 \atentry{index} by \field{name} and those defined with
17393 \atentry{symbol} by \field{description} with the setting:
17394 \begin{codeenv}
17395 \csopt[description]{symbol-sort-fallback}
17396 \end{codeenv}
17397
17398 If the field used to obtain the sort value is changed
17399 (with \csopt{sort-field}) then the \field{sort} field won't be
17400 queried. This reduces the flexibility of selecting the most
17401 appropriate field for given \glspl{entrytype}. For example,
17402 \csopt[name]{sort-field} will force all entries to be sorted by the
17403 \field{name} field, which may not be appropriate for symbols.
17404
17405 \begin{important}
17406 If you choose a field whose value must be a label (such as
17407 \field{parent} or \field{group}) then the sort value will be that label.
17408 \end{important}
17409
17410 You can have \atentry{preamble} definitions that
17411 can be hidden from \bibgls's interpreter. For example,
17412 \exfile{no-interpret-preamble.bib} might contain:
17413 \begin{codeenv}
17414 \atentry{preamble}\marg{\qtdelim{\cmd{providecommand}\marg{\gls{sortop}}[2]\marg{\idx{param}1 \idx{param}2}}}
17415 \end{codeenv}
17416 which is loaded using:
17417 \begin{codeenv}
17418 \gls{GlsXtrLoadResources}\oarg{\csopt[no-interpret-preamble]{src},
17419 \csopt[false]{interpret-preamble}}
17420 \end{codeenv}
17421 This provides a custom command:
17422 \nosecdef{sortop}
17423 for internal use in the document. (Remember it won't be defined on
17424 the first \LaTeX\ run before the \iext{glstex} file has been
17425 created and so is only used within entry fields.)
17426
17427 Another file, say, \filefmt{interpret-preamble.bib} may provide
17428 a definition for \bibgls:
17429 \begin{codeenv}
17430 \atentry{preamble}\marg{\qtdelim{\cmd{providecommand}\marg{\gls{sortop}}[2]\marg{\idx{param}2, \idx{param}1}}}
17431 \end{codeenv}
17432 which can be processed with:
17433 \begin{codeenv}
17434 \gls{GlsXtrLoadResources}\oarg{\csopt[interpret-preamble]{src}}
17435 \end{codeenv}
17436 to provide \bibgls\ with this definition.
17437 The \filefmt{entries.bib} file could contain:
17438 \begin{codeenv}
17439 \atentry{entry}\marg{caesar,
17440 \field{name}=\marg{\gls{sortop}\marg{Gaius Julius}\marg{Caesar}},
17441 \field{first}=\marg{Julius Caesar},
17442 \field{text}=\marg{Caesar},
17443 \field{description}=\marg{Roman politician and general}
17444 }
17445 \end{codeenv}
17446 and then be processed with:
17447 \begin{codeenv}
17448 \gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}}
17449 \end{codeenv}
17450
17451 The definition provided in \filefmt{interpret-preamble.bib}, which
17452 swaps the two arguments around, is now picked up by \bibgls, so the
17453 sort value becomes \code{Caesar, Gaius Julius}, but this new
17454 definition doesn't affect the document since \LaTeX\ has already
17455 defined \gls{sortop} from the first resource set, so the name will
17456 appear as \qt{Gaius Julius Caesar} in the glossary. (If you have
17457 \cs{renewcommand} rather than \cs{providecommand}, you can prevent
17458 the redefinition occurring in the document with
17459 \csopt[false]{write-preamble}.)
17460
17461 Alternatively both of these \ext{bib} files can be loaded in one
17462 \igls{resourceset}:
17463 \begin{codeenv}
17464 \gls{GlsXtrLoadResources}\oarg{\csopt[interpret-preamble,entries]{src}}
17465 \end{codeenv}
17466 Another possibility is to provide a custom package that contains the
17467 command definitions for the \bibgls\ interpreter and load it with
17468 \longarg{custom-packages} instead of having the
17469 \filefmt{interpret-preamble.bib} file.
17470
17471 \optsection{sort}
17472
17473 The \csopt{sort} key indicates how \glspl{primaryentry} should be sorted.
17474 If the \meta{value} is omitted, \csopt[resource]{sort} is assumed.
17475 Note the differences between the keywords \optfmt{resource},
17476 \optfmt{doc} and \optfmt{locale}:
17477 \begin{description}
17478 \item[\optfmt{resource}] The default \gls{resource-locale}, which
17479 can be specified with the \csopt{locale} option. If that option
17480 hasn't been set, then \optfmt{resource} will be equivalent to
17481 \optfmt{doc}. This option is new to \bibgls\ v3.3. Previous versions
17482 had \csopt[doc]{sort} as the default.
17483
17484 \item[\optfmt{doc}] The \gls{document-locale} if it has been detected by
17485 \sty{tracklang}. If no document language has been detected (or
17486 identified with \commonlongarg{locale}), then
17487 \optfmt{doc} will be equivalent to \optfmt{locale}.
17488
17489 \item[\optfmt{locale}] The default \gls{Java-locale}.
17490
17491 \end{description}
17492
17493 The \optfmt{\meta{method}\dhyphen reverse} options reverse the
17494 result returned by the corresponding \meta{method} comparator.
17495 However \optfmt{\meta{method}\dhyphen reverse} may not produce a
17496 list that's the exact reverse of the underlying non-reversed
17497 \meta{method} as the \hierarchical\ structure or associated settings
17498 can affect the order.
17499
17500 \begin{table}[p]
17501 \caption{Summary of Available Sort Options: No Sort Field}
17502 \label{tab:sortoptionsnosort}
17503 \centering
17504 \begin{tabular}{ll}
17505 \optfmt{none} or \optfmt{unsrt} & don't sort\tabularnewline
17506 \optfmt{random} & shuffle entries\tabularnewline
17507 \optfmt{use} & order of use\tabularnewline
17508 \optfmt{use-reverse} & reverse order of use\tabularnewline
17509 \optfmt{recordcount}\textsuperscript\textdagger & order of record count\tabularnewline
17510 \optfmt{recordcount-reverse}\textsuperscript\textdagger & reverse order of record count
17511 \end{tabular}
17512 \par
17513 \medskip
17514 \textsuperscript\textdagger Requires \longarg{record-count} switch.
17515 \end{table}
17516
17517 \begin{table}[p]
17518 \caption{Summary of Available Sort Options: Alphabet}
17519 \label{tab:sortoptionsrule}
17520 \centering
17521 \begin{tabular}{ll}
17522 \meta{lang tag} & sort according to this language tag\tabularnewline
17523 \meta{lang tag}\optfmt{-reverse} & reverse sort according to this language tag\tabularnewline
17524 \optfmt{resource} & sort according to the default
17525 \gls{resource-locale}\tabularnewline
17526 \optfmt{resource-reverse} & reverse sort according to the default
17527 \gls{resource-locale}\tabularnewline
17528 \optfmt{doc} & sort according to the \gls{document-locale}\tabularnewline
17529 \optfmt{doc-reverse} & reverse sort according to the
17530 \gls{document-locale}\tabularnewline
17531 \optfmt{locale} & sort according to the default
17532 \gls{Java-locale}\tabularnewline
17533 \optfmt{locale-reverse} & reverse sort according to the default
17534 \gls{Java-locale}\tabularnewline
17535 \optfmt{custom} & sort according to \csopt[\meta{custom
17536 rule}]{sort-rule}\tabularnewline
17537 \optfmt{custom-reverse} & reverse sort according to \csopt[\meta{custom rule}]{sort-rule}
17538 \end{tabular}
17539 \end{table}
17540
17541 \begin{table}[p]
17542 \caption{Summary of Available Sort Options: Letter (Non-Locale)}
17543 \label{tab:sortoptionsletter}
17544 \centering
17545 \begin{tabular}{ll}
17546 \optfmt{letter-case} & case-sensitive letter sort\tabularnewline
17547 \optfmt{letter-case-reverse} & reverse case-sensitive letter
17548 sort\tabularnewline
17549 \optfmt{letter-nocase} & case-insensitive letter sort\tabularnewline
17550 \optfmt{letter-nocase-reverse} & reverse case-insensitive letter
17551 sort\tabularnewline
17552 \optfmt{letter-upperlower} & upper-lower letter sort\tabularnewline
17553 \optfmt{letter-upperlower-reverse} & reverse upper-lower letter
17554 sort\tabularnewline
17555 \optfmt{letter-lowerupper} & lower-upper letter sort\tabularnewline
17556 \optfmt{letter-lowerupper-reverse} & reverse lower-upper letter sort
17557 \end{tabular}
17558 \end{table}
17559
17560 \begin{table}[p]
17561 \caption{Summary of Available Sort Options: Letter-Number}
17562 \label{tab:sortoptionsletternumber}
17563 \centering
17564 \begin{tabular}{ll}
17565 \optfmt{letternumber-case} & case-sensitive letter-number
17566 sort\tabularnewline
17567 \optfmt{letternumber-case-reverse} & reverse case-sensitive
17568 letter-number sort\tabularnewline
17569 \optfmt{letternumber-nocase} & case-insensitive letter-number
17570 sort\tabularnewline
17571 \optfmt{letternumber-nocase-reverse} & reverse case-insensitive
17572 letter-number sort\tabularnewline
17573 \optfmt{letternumber-upperlower} & upper-lower letter-number
17574 sort\tabularnewline
17575 \optfmt{letternumber-upperlower-reverse} & reverse upper-lower
17576 letter-number sort\tabularnewline
17577 \optfmt{letternumber-lowerupper} & lower-upper letter-number
17578 sort\tabularnewline
17579 \optfmt{letternumber-lowerupper-reverse} & reverse lower-upper letter-number sort
17580 \end{tabular}
17581 \end{table}
17582
17583 \begin{table}[p]
17584 \caption{Summary of Available Sort Options: Numerical}
17585 \label{tab:sortoptionsnumerical}
17586 \centering
17587 \begin{tabular}{ll}
17588 \optfmt{integer} & integer sort\tabularnewline
17589 \optfmt{integer-reverse} & reverse integer sort\tabularnewline
17590 \optfmt{hex} & hexadecimal sort\tabularnewline
17591 \optfmt{hex-reverse} & reverse hexadecimal sort\tabularnewline
17592 \optfmt{octal} & octal sort\tabularnewline
17593 \optfmt{octal-reverse} & reverse octal sort\tabularnewline
17594 \optfmt{binary} & binary sort\tabularnewline
17595 \optfmt{binary-reverse} & reverse binary sort\tabularnewline
17596 \optfmt{float} & float sort\tabularnewline
17597 \optfmt{float-reverse} & reverse float sort\tabularnewline
17598 \optfmt{double} & double sort\tabularnewline
17599 \optfmt{double-reverse} & reverse double sort\tabularnewline
17600 \optfmt{numeric} & locale-sensitive numeric sort\tabularnewline
17601 \optfmt{numeric-reverse} & reverse locale-sensitive numeric
17602 sort\tabularnewline
17603 \optfmt{currency} & locale-sensitive currency sort\tabularnewline
17604 \optfmt{currency-reverse} & reverse locale-sensitive currency
17605 sort\tabularnewline
17606 \optfmt{percent} & locale-sensitive percent sort\tabularnewline
17607 \optfmt{percent-reverse} & reverse locale-sensitive percent
17608 sort\tabularnewline
17609 \optfmt{numberformat} & locale-sensitive custom numeric
17610 sort\tabularnewline
17611 \optfmt{numberformat-reverse} & reverse locale-sensitive custom numeric sort
17612 \end{tabular}
17613 \end{table}
17614
17615 \begin{table}[p]
17616 \caption{Summary of Available Sort Options: Date-Time}
17617 \label{tab:sortoptionsdatetime}
17618 \centering
17619 \begin{tabular}{ll}
17620 \optfmt{date} & locale-sensitive date sort\tabularnewline
17621 \optfmt{date-reverse} & reverse locale-sensitive date
17622 sort\tabularnewline
17623 \optfmt{datetime} & locale-sensitive date-time sort\tabularnewline
17624 \optfmt{datetime-reverse} & reverse locale-sensitive date-time
17625 sort\tabularnewline
17626 \optfmt{time} & locale-sensitive time sort\tabularnewline
17627 \optfmt{time-reverse} & reverse locale-sensitive time sort
17628 \end{tabular}
17629 \end{table}
17630
17631 \subsubsection{No Sort Field}
17632
17633 Most of the sort methods listed in \tableref{tab:sortoptionsnosort}
17634 don't actually perform any sorting. This may cause a problem for
17635 \hierarchical\ entries. In some cases this can lead to detached
17636 \glspl{childentry} or an attempt to define a \gls{childentry} before its \parent.
17637 The methods listed in this section all ignore the \csopt{sort-field}
17638 setting and all the various sort fallback settings, except where
17639 noted below.
17640 \begin{itemize}
17641
17642 \item \optfmt{none} (or \optfmt{unsrt}): don't sort the entries.
17643 (The entries will be in the order they were processed when parsing
17644 the data.)
17645
17646 If you need to order by definition but also maintain \hierarchy\ then use:
17647 \begin{codeenv}
17648 \csopt{save-definition-index},
17649 \csopt[\field{definitionindex}]{sort-field},
17650 \csopt[integer]{sort}
17651 \end{codeenv}
17652
17653 \item \optfmt{random}: shuffles rather than sorts the entries.
17654 This won't work if there are \hierarchical\ entries, so it's best
17655 to use this option with \csopt{flatten}. The seed for the
17656 random generator can be set using \csopt{shuffle} (which
17657 also automatically sets \csopt[random]{sort} and \csopt{flatten}).
17658
17659 \item \optfmt{use}: order of use. This order is determined
17660 by the \glspl{record} written to the \iext{aux} file by the \styopt{record}
17661 package option. Dependencies and cross-references (including those
17662 identified with \ics{glssee}) come after entries with \glspl{record}.
17663
17664 Note that this is different from using the analogous option with
17665 \idx{makeindex} or \idx{xindy}, which does actually sort
17666 numerically, where each entry has an associated number set on the
17667 first use of that term that's used as the sort value.
17668
17669 If you need to order by use but also maintain \hierarchy\ then use:
17670 \begin{codeenv}
17671 \csopt{save-use-index},
17672 \csopt[\field{useindex}]{sort-field},
17673 \csopt[integer]{sort}
17674 \end{codeenv}
17675
17676 \item \optfmt{use-reverse}: reverses the order that would be
17677 obtained with \csopt[use]{sort} without reference to \hierarchy.
17678
17679 \item \optfmt{recordcount}: order of \gls{recordcount} (starting from 0). This order is
17680 determined by the total number of records written to the \iext{aux}
17681 file for each entry. Unlike the above methods, this performs a \hierarchical\ sort.
17682 If letter groups are enabled with \longarg{group}, this method will assign the entries to
17683 the \idx{numbergroup}.
17684
17685 This option requires the \longarg{record-count} switch. Although
17686 that switch makes \bibgls\ write the total \gls{recordcount} to the
17687 \ext{glstex} file in the \field{recordcount} internal field (so that it
17688 can be accessed in the document), \bibgls\ doesn't actually have a
17689 field itself that contains the information. So although this option
17690 behaves much like \csopt[integer]{sort} it's not possible to select
17691 a field containing the required value. In the event of two or more
17692 entries having the same \gls{recordcount}, the
17693 \csopt{identical-sort-action} option is used to determine the
17694 relative ordering between them.
17695
17696 \item \optfmt{recordcount-reverse}: reverse order of \gls{recordcount}
17697 (ending with 0). All the above notes applying to
17698 \optfmt{recordcount} also apply here.
17699
17700 \end{itemize}
17701
17702 Suppose the file \filefmt{entries.bib} contains
17703 definitions of a set of symbols that don't have any intuitive
17704 ordering (for example, they are all pictographs) then there may be
17705 no point in trying to order them, in which case you can do:
17706 \begin{codeenv}
17707 \gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[none]{sort}}
17708 \end{codeenv}
17709 Alternatively, you could list them in order of use:
17710 \begin{codeenv}
17711 \gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[use]{sort}}
17712 \end{codeenv}
17713 or by frequency of use. For example, starting with entries that
17714 don't have any records followed by the least used entries (a rarely-used symbol
17715 may be harder to remember and most likely to be looked up in the glossary):
17716 \begin{codeenv}
17717 \gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[recordcount]{sort}}
17718 \end{codeenv}
17719 Or starting with the most used entries:
17720 \begin{codeenv}
17721 \gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[recordcount-reverse]{sort}}
17722 \end{codeenv}
17723 It all depends on what's likely to be most useful to the reader.
17724
17725 Consider the following:
17726 \begin{codeenv}
17727 \ics{newglossary*}\marg{frequent}\marg{Most Frequently Used Terms}
17728 \gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[use]{sort},
17729 \csopt[recordcount-reverse:frequent]{secondary}
17730 }
17731 \cs{newcommand}\marg{\csfmt{filterhook}}[1]\marg{\comment{}
17732 \ics{GlsXtrIfFieldCmpNum}*\marg{\field{recordcount}}\marg{\idx{hashchar}1}\marg{>}\marg{10}\comment{}
17733 \marg{}\comment{}
17734 \marg{\ics{printunsrtglossaryskipentry}}\comment{}
17735 }
17736 \csfmt{begin}\marg{document}
17737 \cs{printunsrtglossary*}\oarg{\printglossopt[false]{target},\printglossopt[frequent]{type}}\marg{\comment{}
17738 \cs{let}\ics{printunsrtglossaryentryprocesshook}\csfmt{filterhook}
17739 }
17740 \comment{Main body of the document \ldots}
17741 \cs{printunsrtglossary}
17742 \csfmt{end}\marg{document}
17743 \end{codeenv}
17744 This has a summary at the start of the document that only contains
17745 entries that have at least 10 records and is ordered according to
17746 the total number of records (starting with the most frequently used
17747 entry). The \gls{mainglossary} at the end of the document is ordered
17748 according to use and contains all selected entries.
17749
17750 Compare this with the following:
17751 \begin{codeenv}
17752 \gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[use]{sort}}
17753 \cs{newcommand}\marg{\csfmt{filterhook}}[1]\marg{\comment{}
17754 \ics{GlsXtrIfFieldCmpNum}*\marg{\field{recordcount}}\marg{\idx{hashchar}1}\marg{>}\marg{10}\comment{}
17755 \marg{}\comment{}
17756 \marg{\ics{printunsrtglossaryskipentry}}\comment{}
17757 }
17758 \csfmt{begin}\marg{document}
17759 \cs{printunsrtglossary*}\oarg{\printglossopt[false]{target},
17760 \printglossopt[Most Frequently Used Terms]{title}}\marg{\comment{}
17761 \cs{let}\ics{printunsrtglossaryentryprocesshook}\csfmt{filterhook}
17762 }
17763 \comment{Main body of the document \ldots}
17764 \cs{printunsrtglossary}
17765 \csfmt{end}\marg{document}
17766 \end{codeenv}
17767 This again has a summary at the start of the document that only
17768 contains entries that have at least 10 records but is now ordered
17769 according to use.
17770
17771 Both examples assume there are no \glspl{childentry} as the filtering can
17772 cause \glspl{parententry} to be omitted. Both examples require
17773 \longarg{record-count} but only the first example sorts according to
17774 the \gls{recordcount}.
17775
17776 \subsubsection{Alphabet}
17777
17778 The sort methods listed in \tableref{tab:sortoptionsrule} are for
17779 alphabets that are defined by a rule. These usually ignore most
17780 punctuation and may ignore modifiers (such as accents). Use with
17781 \csopt{break-at} to determine whether or not to split at word
17782 boundaries. The collation rules (except for the custom options) are obtained
17783 from the \idx{localeprovider} (see page~\pageref{locale.provider}).
17784
17785 \begin{itemize}
17786 \item \meta{lang tag}: sort according to the rules of the locale
17787 given by the \idx{IETF} language tag \meta{lang tag}.
17788
17789 \item \meta{lang tag}\optfmt{-reverse}: reverse sort according to the rules of the locale
17790 given by the \idx{IETF} language tag \meta{lang tag}.
17791
17792 \item \optfmt{resource}: equivalent to
17793 \csopt[\meta{lang tag}]{sort} where \meta{lang tag} is obtained
17794 from the default \gls{resource-locale}.
17795
17796 \item \optfmt{resource-reverse}: equivalent to
17797 \csopt[\meta{lang tag}-reverse]{sort} where \meta{lang tag} is obtained
17798 from the default \gls{resource-locale}.
17799
17800 \item \optfmt{locale}: equivalent to
17801 \csopt[\meta{lang tag}]{sort} where \meta{lang tag} is obtained
17802 from the \gls{Java-locale} (which usually matches the
17803 operating system's locale).
17804
17805 \item \optfmt{locale-reverse}: equivalent to
17806 \csopt[\meta{lang tag}-reverse]{sort} where \meta{lang tag} is obtained
17807 from the \gls{Java-locale}.
17808
17809 \item \optfmt{doc}: sort the entries according to the
17810 \gls{document-locale}. This is equivalent to \csopt[\meta{lang tag}]{sort}
17811 where \meta{lang tag} is the locale associated with the document
17812 language. In the case of a multi-lingual document, \meta{lang tag}
17813 is the locale of the last language resource file to be loaded through
17814 \isty{tracklang}'s interface. It's best to explicitly set the locale
17815 for multi-lingual documents to avoid confusion. If no document
17816 language has been set, this option is equivalent to \csopt[locale]{sort}.
17817
17818 \item \optfmt{doc-reverse}: as \optfmt{doc} but in reverse order.
17819
17820 \item \optfmt{custom}: sort the entries according to the
17821 rule provided by \csopt{sort-rule}.
17822
17823 \item \optfmt{custom-reverse}: reverse sort the entries according to the
17824 rule provided by \csopt{sort-rule}.
17825 \end{itemize}
17826
17827 Note that \csopt[\meta{lang tag}]{sort} can provide more detail about the
17828 given locale than \csopt[doc]{sort}, depending on how the document
17829 language has been specified. For example, with:
17830 \begin{codeenv}
17831 \cmd{documentclass}\marg{article}
17832 \cmd{usepackage}\oarg{ngerman}\marg{babel}
17833 \cmd{usepackage}\oarg{\styopt{record}}\marg{glossaries}
17834 \gls{GlsXtrLoadResources}\oarg{\csopt[german-terms]{src}}
17835 \end{codeenv}
17836 the language tag will be \code{de-1996}, which doesn't have an
17837 associated region, so this is equivalent to using \csopt[de-1996]{sort}.
17838 Whereas with:
17839 \begin{codeenv}
17840 \cmd{documentclass}\oarg{de-DE-1996}\marg{article}
17841 \cmd{usepackage}\oarg{ngerman}\marg{babel}
17842 \cmd{usepackage}\oarg{\styopt{record}}\marg{glossaries}
17843 \gls{GlsXtrLoadResources}\oarg{\csopt[german-terms]{src}}
17844 \end{codeenv}
17845 the language tag will be \code{de-DE-1996} because \isty{tracklang}
17846 has picked up the locale from the document class options, so this is
17847 equivalent to using \csopt[de-DE-1996]{sort}. This is
17848 only likely to cause a difference if a language has different
17849 sorting rules according to the region or if the language may be
17850 written in multiple scripts.
17851
17852 If no \gls{document-locale} has been set and the
17853 \csopt{locale} resource option hasn't been used
17854 then the \csopt[resource]{sort} and \csopt[doc]{sort}
17855 will be equivalent to \csopt[locale]{sort}.
17856 For example, with:
17857 \begin{codeenv}
17858 \cmd{documentclass}\marg{article}
17859 \cmd{usepackage}\oarg{\styopt{record}}\marg{glossaries}
17860 \gls{GlsXtrLoadResources}\oarg{\csopt[german-terms]{src}}
17861 \end{codeenv}
17862 the language tag will be whatever is the default locale for the \idx{JVM}.
17863 For a user in Germany, this could be \code{de-DE-1996} and for a user
17864 in Austria this could be \code{de-AT-1996}.
17865
17866 A multilingual document will need to have the \csopt{sort} specified
17867 when loading the \idx{resourceset} to ensure the correct language is chosen.
17868 For example:
17869 \begin{codeenv}
17870 \gls{GlsXtrLoadResources}\oarg{\csopt[english-terms]{src},\csopt[en-GB]{sort}}
17871 \gls{GlsXtrLoadResources}\oarg{\csopt[german-terms]{src},\csopt[de-DE-1996]{sort}}
17872 \end{codeenv}
17873
17874 Alternatively (as from \bibgls\ v3.3), use \csopt{locale}:
17875 \begin{codeenv}
17876 \gls{GlsXtrLoadResources}\oarg{\csopt[en-GB]{locale},\csopt[english-terms]{src}}
17877 \gls{GlsXtrLoadResources}\oarg{\csopt[de-DE-1996]{locale},\csopt[german-terms]{src}}
17878 \end{codeenv}
17879
17880 \subsubsection{Letter (Non Locale)}
17881
17882 The sort methods listed in \tableref{tab:sortoptionsletter}
17883 use letter comparators. These simply compare the
17884 character codes. The \optfmt{-nocase} options first convert the
17885 \field{sort} field to \idx{lowercase} before performing the sort to
17886 provide a case-insensitive comparison.
17887
17888 Punctuation isn't ignored.
17889 Use \csopt[\meta{lang tag}]{sort} with \csopt[none]{break-at} to
17890 emulate \idx!{xindy}['s] locale letter ordering. The examples below
17891 show the ordering of the list \code{antelope}, \code{bee}, \code{Africa},
17892 \code{aardvark} and \code{Brazil}.
17893 \begin{itemize}
17894 \item \optfmt{letter-case}: case-sensitive letter sort.
17895 \Idx{uppercase} and \idx{lowercase} are in separate letter groups.
17896 Example:
17897
17898 \code{Africa} (letter group \idx{uppercase} \qt{A}), \code{Brazil}
17899 (letter group \idx{uppercase} \qt{B}), \code{aardvark} (letter group
17900 \idx{lowercase} \qt{a}), \code{antelope} (letter group
17901 \idx{lowercase} \qt{a}), \code{bee} (letter group \idx{lowercase} \qt{b}).
17902
17903 \item \optfmt{letter-case-reverse}: reverse case-sensitive letter sort.
17904 Example:
17905
17906 \code{bee} (letter group \idx{lowercase} \qt{b}), \code{antelope}
17907 (letter group \idx{lowercase} \qt{a}), \code{aardvark} (letter group
17908 \idx{lowercase} \qt{a}) \code{Brazil} (letter group \idx{uppercase}
17909 \qt{B}), \code{Africa} (letter group \idx{uppercase} \qt{A}).
17910
17911 \item \optfmt{letter-nocase}: case-insensitive letter sort. (All
17912 \idx{uppercase} characters will have first been converted to
17913 \idx{lowercase} in the sort value.)
17914 Example:
17915
17916 \code{aardvark} (letter group \qt{A}), \code{Africa}
17917 (letter group \qt{A}), \code{antelope} (letter group \qt{A}),
17918 \code{bee} (letter group \qt{B}),
17919 \code{Brazil} (letter group \qt{B}).
17920
17921 \item \optfmt{letter-nocase-reverse}: reverse case-insensitive letter sort.
17922 Example:
17923
17924 \code{Brazil} (letter group \qt{B}), \code{bee} (letter group
17925 \qt{B}), \code{antelope} (letter group \qt{A}), \code{Africa}
17926 (letter group \qt{A}), \code{aardvark} (letter group \qt{A}).
17927
17928 \item \optfmt{letter-upperlower}: each character pair is first
17929 compared according to their \idx{lowercase} values. If these are equal,
17930 then they are compared according to case. This puts upper and lower
17931 case in the same letter group but the \idx{uppercase} comes first.
17932 Example:
17933
17934 \code{Africa} (letter group \qt{A}), \code{aardvark} (letter group
17935 \qt{A}), \code{antelope} (letter group \qt{A}), \code{Brazil}
17936 (letter group \qt{B}), \code{bee} (letter group \qt{B}).
17937
17938 \item \optfmt{letter-upperlower-reverse}: reverse upper-lower letter sort.
17939 This now puts the \idx{lowercase} letters first within the letter group.
17940 Example:
17941
17942 \code{bee} (letter group \qt{B}), \code{Brazil} (letter group
17943 \qt{B}), \code{antelope} (letter group \qt{A}), \code{aardvark}
17944 (letter group \qt{A}), \code{Africa} (letter group \qt{A}).
17945
17946 \item \optfmt{letter-lowerupper}: each character pair is first
17947 compared according to their \idx{lowercase} values. If these are equal,
17948 then they are compared according to case. This puts
17949 \idxlink{uppercase}{upper} and \idx{lowercase} in the same letter group but the \idx{lowercase} comes first.
17950 Example:
17951
17952 \code{aardvark} (letter group \qt{A}), \code{antelope} (letter group \qt{A}),
17953 \code{Africa} (letter group \qt{A}), \code{bee} (letter group
17954 \qt{B}), \code{Brazil} (letter group \qt{B}).
17955
17956 \item \optfmt{letter-lowerupper-reverse}: reverse lower-upper letter sort.
17957 This now puts the \idx{uppercase} letters first within the letter group.
17958 Example:
17959
17960 \code{Brazil} (letter group \qt{B}), \code{bee} (letter group
17961 \qt{B}), \code{Africa} (letter group \qt{A}), \code{antelope}
17962 (letter group \qt{A}), \code{aardvark} (letter group \qt{A}).
17963
17964 \end{itemize}
17965
17966 \subsubsection{Letter-Number}
17967 \label{sec:letternumber}
17968
17969 The sort methods listed in \tableref{tab:sortoptionsletternumber}
17970 use a letter-integer hybrid. They behave in a similar way to the
17971 above letter sort methods, but if an integer number pattern is detected in
17972 the string then the sub-string containing the number will be compared.
17973 This only detects base 10 integers (unlike the numeric methods
17974 such as \csopt[hexadecimal]{sort} or \csopt[float]{sort}) but in
17975 addition to recognising all the digits in the Unicode \idx{numberdecimaldigit}
17976 category it also recognises the subscript and
17977 superscript digits, such as \textsuperscript{1} (\hex{00B9})
17978 and \textsuperscript{2} (\hex{00B2}).
17979
17980 As with the letter sort methods, letters are compared using a
17981 character code comparison not by a locale alphabet. The closest
17982 locale-sensitive equivalent is to use \csopt{sort-number-pad} with a
17983 locale sort method. Alternatively, use \ics{IfTeXParserLib} or
17984 \ics{IfNotBibGls} and
17985 \ics{bibglspaddigits} to pad the number for the interpreter but
17986 not in the \TeX\ document.
17987
17988 \begin{figure}
17989 \figcontents
17990 {%
17991 \begin{tikzpicture}[every node/.style={minimum size=9mm},
17992 ampersand replacement=\&]
17993 \matrix[font={\Large\ttfamily}]
17994 {
17995 \node[draw]{a\hexsb{61}}; \& \node{$=$}; \& \node[draw]{a\hexsb{61}}; \&[20mm]
17996 \node[draw]{a\hexsb{61}}; \& \node{$=$}; \& \node[draw]{a\hexsb{61}};
17997 \\
17998 \node[draw]{b\hexsb{62}}; \& \node{$=$}; \& \node[draw]{b\hexsb{62}}; \&
17999 \node[draw]{b\hexsb{62}}; \& \node{$=$}; \& \node[draw]{b\hexsb{62}};
18000 \\
18001 \node[draw]{c\hexsb{63}}; \& \node{$=$}; \& \node[draw]{c\hexsb{63}}; \&
18002 \node[draw]{c\hexsb{63}}; \& \node{$=$}; \& \node[draw]{c\hexsb{63}};
18003 \\
18004 \node[draw,ultra thick]{1\hexsb{31}}; \& \node{$<$}; \&
18005 \node[draw,ultra thick]{6\hexsb{36}}; \&
18006 \node (n1) {1}; \& \node{$>$}; \& \node[draw,ultra thick]{6};
18007 \\
18008 \node[draw]{2\hexsb{32}}; \& \& \node[draw]{b\hexsb{62}}; \&
18009 \node (n2) {2}; \& \& \node[draw]{b\hexsb{62}};
18010 \\
18011 \node[draw]{f\hexsb{66}}; \& \& \node[draw]{a\hexsb{61}}; \&
18012 \node[draw]{f\hexsb{66}}; \& \& \node[draw]{a\hexsb{61}};
18013 \\
18014 \node[draw]{o\hexsb{6f}}; \& \& \node[draw]{r\hexsb{72}}; \&
18015 \node[draw]{o\hexsb{6f}}; \& \& \node[draw]{r\hexsb{72}};
18016 \\
18017 \node[draw]{o\hexsb{6f}}; \& \& \&
18018 \node[draw]{o\hexsb{6f}}; \& \&
18019 \\[10pt]
18020 \& \node[font=\rmfamily]{\subfigfmt{a}}; \& \&
18021 \& \node[font=\rmfamily]{\subfigfmt{b}}; \&
18022 \\
18023 };
18024 \draw[ultra thick] (n1.north east) rectangle (n2.south west);
18025 \end{tikzpicture}%
18026 }
18027 {%
18028 \caption[Regular letter comparison vs letter-number
18029 comparison]{Regular letter comparison vs letter-number comparison.
18030 Comparing the strings \code{abc12foo} and \code{abc6bar}:
18031 \subfigfmt{a} \optfmt{letter-case}; \subfigfmt{b}
18032 \optfmt{letternumber-case}.}%
18033 }
18034 {fig:letternumber}
18035 \end{figure}
18036
18037 For example, suppose the first string is \code{abc12foo}
18038 and the second string is \code{abc6bar}.
18039 \Figureref{fig:letternumber}\subfigfmt{a} shows the regular letter
18040 comparison using \csopt[letter-case]{sort}, where the subscript
18041 indicates the hexadecimal character code. The first three characters
18042 from each string are identical (\code{abc}). At this point there's
18043 no difference detected, so the comparator moves on to the next
18044 character, \code{1\hexsb{31}} for the first string and
18045 \code{6\hexsb{36}} for the second string. Since \hex{31} is less than
18046 \hex{36}, the first string (\code{abc12foo}) is considered less than the second
18047 (\code{abc6bar}).
18048
18049 With the letter-number comparison using
18050 \csopt[letternumber-case]{sort}, the comparator starts in much the
18051 same way. The first three characters from each string are still
18052 identical, so the comparator moves on to the next character,
18053 \code{1} for the first string and \code{6} for the second.
18054 These are now both recognised as digits, so the comparator
18055 looks ahead and reads in any following digits (if present). For the
18056 first case, this is the sub-string \code{12} and, for the second
18057 case, \code{6} (\figureref{fig:letternumber}\subfigfmt{b}). These
18058 are both compared according to their integer representation $12 >
18059 6$, so \code{abc12bar} is considered greater than \code{abc6foo}
18060 (that is, \code{abc12bar} comes after \code{abc6foo}).
18061
18062 The same result occurs for other numbering systems, for example if
18063 the Basic Latin digits 1, 2 and 6 are replaced with the
18064 corresponding Devanagari digits \devone, \devtwo\ and
18065 \devsix. (But note that the letter comparisons will still be
18066 based on their Unicode values not according to a particular locale.
18067 This type of sort method is intended primarily for symbolic values,
18068 such as chemical formulae, rather than for words or phrases.)
18069
18070 Signed integers are also recognised, so \code{abc-12foo} is less
18071 than \code{abc+6bar}, which is again different from the result
18072 obtained with a straight letter comparator where the
18073 character~\code{+} (\hex{2B})
18074 comes before the character~\code{-} (\hex{2D}). The sign must be followed by at
18075 least one digit for it to be recognised as a number otherwise it's
18076 treated as a punctuation character.
18077
18078 If only one sub-string is numeric
18079 then the \csopt{letter-number-rule} is used to determine the
18080 result. Where both sub-strings are non-numeric, then the
18081 \csopt{letter-number-punc-rule} setting is used to determine the result
18082 according to the category of the characters, which may be one of the
18083 following:
18084 \begin{itemize}
18085 \item white space: belongs to the Unicode \idx{separatorspace}
18086 category. If both characters are white space, then they are compared
18087 according to their Unicode values otherwise they are ordered according to
18088 the \csopt{letter-number-punc-rule} setting.
18089
18090 \item letter: belongs to one of the Unicode categories \idx{letteruppercase},
18091 \idx{letterlowercase}, \idx{lettertitlecase},
18092 \idx{lettermodifier} or \idx{letterother}. If both characters
18093 are letters then, for sort method \optfmt{letternumber-\meta{modifier}},
18094 the characters are compared in the same way as the
18095 corresponding \optfmt{letter-\meta{modifier}} sort method otherwise
18096 they are ordered according to the
18097 \csopt{letter-number-punc-rule} setting.
18098
18099 \item punctuation: everything else. If both characters are
18100 punctuation, then they are compared according to their Unicode value
18101 otherwise they are ordered according to
18102 the \csopt{letter-number-punc-rule} setting.
18103 \end{itemize}
18104 For simplicity, the actual sort value used during sorting isn't a
18105 simple string but is converted into a list of objects that represent
18106 one of: letter, integer, space or other (punctuation). This reduces
18107 the amount of parsing of substrings that needs to be performed.
18108
18109 The examples below show the ordering of the list:
18110 \code{CH\textsubscript{2}O},
18111 \code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}},
18112 \code{C\textsubscript{5}H\textsubscript{4}NCOOH},
18113 \code{CO}, \code{Cl},
18114 \code{Co}, \code{Co\textsubscript{2}O\textsubscript{3}},
18115 \code{Co\textsubscript{2}}, \code{CO\textsubscript{2}},
18116 \code{CoMoO\textsubscript{4}} and \code{CoCl\textsubscript{2}},
18117 for the setting
18118 \csopt[between]{letter-number-rule}, where the subscripts are
18119 the Unicode subscript characters.
18120
18121 \begin{itemize}
18122 \item \optfmt{letternumber-case}: case-sensitive
18123 letter-number sort. Example:
18124
18125 \code{CH\textsubscript{2}O},
18126 \code{CO},
18127 \code{CO\textsubscript{2}},
18128 \code{C\textsubscript{5}H\textsubscript{4}NCOOH},
18129 \code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}},
18130 \code{Cl},
18131 \code{Co},
18132 \code{CoCl\textsubscript{2}},
18133 \code{CoMoO\textsubscript{4}},
18134 \code{Co\textsubscript{2}},
18135 \code{Co\textsubscript{2}O\textsubscript{3}}.
18136
18137 (Order determined by: $\mathtt{H} < \mathtt{O} < 5 < 10 < \mathtt{l} < \mathtt{o}$.)
18138
18139 \item \optfmt{letternumber-case-reverse}: reverse case-sensitive
18140 letter-number sort. Example:
18141
18142 \code{Co\textsubscript{2}O\textsubscript{3}},
18143 \code{Co\textsubscript{2}},
18144 \code{CoMoO\textsubscript{4}},
18145 \code{CoCl\textsubscript{2}},
18146 \code{Co},
18147 \code{Cl},
18148 \code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}},
18149 \code{C\textsubscript{5}H\textsubscript{4}NCOOH},
18150 \code{CO\textsubscript{2}},
18151 \code{CO},
18152 \code{CH\textsubscript{2}O}.
18153
18154 \item \optfmt{letternumber-nocase}: case-insensitive
18155 letter-number sort. The sort value is first converted to lower
18156 case. Note that \csopt[between]{letter-number-rule} doesn't make
18157 sense in this context as there won't be any \idx!{uppercase} characters in
18158 the sort value, so numbers will always come before letters. Example:
18159
18160 \code{C\textsubscript{5}H\textsubscript{4}NCOOH},
18161 \code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}},
18162 \code{CH\textsubscript{2}O},
18163 \code{Cl},
18164 \code{CO},
18165 \code{Co},
18166 \code{CO\textsubscript{2}},
18167 \code{Co\textsubscript{2}},
18168 \code{Co\textsubscript{2}O\textsubscript{3}},
18169 \code{CoCl\textsubscript{2}},
18170 \code{CoMoO\textsubscript{4}}.
18171
18172 (Order determined by: $5 < 10 < \mathtt{h} < \mathtt{l} < \mathtt{o}$.)
18173
18174 \item \optfmt{letternumber-nocase-reverse}: reverse case-insensitive
18175 letter-number sort, so numbers will now always come after letters. Example:
18176
18177 \code{CoMoO\textsubscript{4}},
18178 \code{CoCl\textsubscript{2}},
18179 \code{Co\textsubscript{2}O\textsubscript{3}},
18180 \code{Co\textsubscript{2}},
18181 \code{CO\textsubscript{2}},
18182 \code{Co},
18183 \code{CO},
18184 \code{Cl},
18185 \code{CH\textsubscript{2}O},
18186 \code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}},
18187 \code{C\textsubscript{5}H\textsubscript{4}NCOOH}.
18188
18189 \item \optfmt{letternumber-upperlower}: upper-lower
18190 letter-number sort. This behaves slightly differently to
18191 \optfmt{letter-upperlower} when used with \csopt[between]{letter-number-rule}
18192 and has a more complicated rule that's determined by the character
18193 following the number and implied numbers inserted between letters.
18194 (There was a bug in earlier versions that has been corrected in v1.8
18195 so you may find a slightly different ordering when upgrading.)
18196 Example:
18197
18198 \code{CH\textsubscript{2}O},
18199 \code{C\textsubscript{5}H\textsubscript{4}NCOOH},
18200 \code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}},
18201 \code{Cl},
18202 \code{CO},
18203 \code{CO\textsubscript{2}},
18204 \code{Co},
18205 \code{Co\textsubscript{2}},
18206 \code{CoCl\textsubscript{2}},
18207 \code{CoMoO\textsubscript{4}},
18208 \code{Co\textsubscript{2}O\textsubscript{3}}.
18209
18210 (Order determined by: $\mathtt{H} < 5\mathtt{H} < 10\mathtt{H} <
18211 \mathtt{l} < \mathtt{O} < \mathtt{o}$, and for the terms starting
18212 with \code{CO} or \code{Co}: 2 comes after null and $\mathtt{C} <
18213 \mathtt{M} < 2\mathtt{O}$.)
18214
18215 Compare this with \csopt[before letter]{letter-number-rule} which
18216 results in the order:
18217
18218 \code{C\textsubscript{5}H\textsubscript{4}NCOOH},
18219 \code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}},
18220 \code{CH\textsubscript{2}O},
18221 \code{Cl},
18222 \code{CO},
18223 \code{CO\textsubscript{2}},
18224 \code{Co},
18225 \code{Co\textsubscript{2}},
18226 \code{Co\textsubscript{2}O\textsubscript{3}},
18227 \code{CoCl\textsubscript{2}},
18228 \code{CoMoO\textsubscript{4}}.
18229
18230 \item \optfmt{letternumber-upperlower-reverse}: reverse upper-lower
18231 letter-number sort. Example (with \csopt[between]{letter-number-rule}):
18232
18233 \code{Co\textsubscript{2}O\textsubscript{3}},
18234 \code{CoMoO\textsubscript{4}},
18235 \code{CoCl\textsubscript{2}},
18236 \code{Co\textsubscript{2}},
18237 \code{Co},
18238 \code{CO\textsubscript{2}},
18239 \code{CO},
18240 \code{Cl},
18241 \code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}},
18242 \code{C\textsubscript{5}H\textsubscript{4}NCOOH},
18243 \code{CH\textsubscript{2}O}.
18244
18245 Compare this with \csopt[before letter]{letter-number-rule} which
18246 results in the order:
18247
18248 \code{CoMoO\textsubscript{4}},
18249 \code{CoCl\textsubscript{2}},
18250 \code{Co\textsubscript{2}O\textsubscript{3}},
18251 \code{Co\textsubscript{2}},
18252 \code{Co},
18253 \code{CO\textsubscript{2}},
18254 \code{CO},
18255 \code{Cl},
18256 \code{CH\textsubscript{2}O},
18257 \code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}},
18258 \code{C\textsubscript{5}H\textsubscript{4}NCOOH}.
18259
18260 Remember that the associated settings are reversed as
18261 well. So \csopt[before letter]{letter-number-rule}
18262 results in numbers \emph{after} letters.
18263
18264 \item \optfmt{letternumber-lowerupper}: lower-upper letter-number
18265 sort. As with the upper-lower option, this behaves slightly differently to
18266 \optfmt{letter-lowerupper} when used with \csopt[between]{letter-number-rule}
18267 and has a more complicated rule.
18268 Example:
18269
18270 \code{CH\textsubscript{2}O},
18271 \code{C\textsubscript{5}H\textsubscript{4}NCOOH},
18272 \code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}},
18273 \code{Cl},
18274 \code{Co},
18275 \code{Co\textsubscript{2}},
18276 \code{CoCl\textsubscript{2}},
18277 \code{CoMoO\textsubscript{4}},
18278 \code{Co\textsubscript{2}O\textsubscript{3}},
18279 \code{CO},
18280 \code{CO\textsubscript{2}}.
18281
18282 Compare this with \csopt[before letter]{letter-number-rule} which
18283 results in the order:
18284
18285 \code{C\textsubscript{5}H\textsubscript{4}NCOOH},
18286 \code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}},
18287 \code{CH\textsubscript{2}O},
18288 \code{Cl},
18289 \code{Co},
18290 \code{Co\textsubscript{2}},
18291 \code{Co\textsubscript{2}O\textsubscript{3}},
18292 \code{CoCl\textsubscript{2}},
18293 \code{CoMoO\textsubscript{4}},
18294 \code{CO},
18295 \code{CO\textsubscript{2}}.
18296
18297 \item \optfmt{letternumber-lowerupper-reverse}: reverse lower-upper
18298 letter-number sort. Example (with \csopt[between]{letter-number-rule}):
18299
18300 \code{CO\textsubscript{2}},
18301 \code{CO},
18302 \code{Co\textsubscript{2}O\textsubscript{3}},
18303 \code{CoMoO\textsubscript{4}},
18304 \code{CoCl\textsubscript{2}},
18305 \code{Co\textsubscript{2}},
18306 \code{Co},
18307 \code{Cl},
18308 \code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}},
18309 \code{C\textsubscript{5}H\textsubscript{4}NCOOH},
18310 \code{CH\textsubscript{2}O}.
18311
18312 \end{itemize}
18313
18314 \subsubsection{Numerical}
18315 \label{sec:numerical}
18316
18317 The sort methods listed in \tableref{tab:sortoptionsnumerical}
18318 use numeric comparisons. The sort value is expected to
18319 be a numeric value. If it can't be parsed then it's treated as 0
18320 (and a warning will be written to the transcript).
18321 These all recognise the digits in the Unicode \qt{Number,
18322 Decimal Digit} category but, unlike the hybrid letter-number
18323 comparators above, they don't recognise the superscript or subscript
18324 digits. The \qt{non-locale} in some of the descriptions below
18325 indicates that the method doesn't recognise locale-sensitive
18326 formatting, such as group separators.
18327 \begin{itemize}
18328 \item \optfmt{integer}: integer sort. This is for non-locale integer sort
18329 values.
18330
18331 \item \optfmt{integer-reverse}: as above but reverses the order.
18332
18333 \item \optfmt{hex}: hexadecimal integer sort. This is for non-locale
18334 hexadecimal sort values.
18335
18336 \item \optfmt{hex-reverse}: as above but reverses the order.
18337
18338 \item \optfmt{octal}: octal integer sort. This is for non-locale
18339 octal sort values.
18340
18341 \item \optfmt{octal-reverse}: as above but reverses the order.
18342
18343 \item \optfmt{binary}: binary integer sort. This is for non-locale binary sort
18344 values.
18345
18346 \item \optfmt{binary-reverse}: as above but reverses the order.
18347
18348 \item \optfmt{float}: single-precision sort. This is for non-locale
18349 decimal sort values.
18350
18351 \item \optfmt{float-reverse}: as above but reverses the order.
18352
18353 \item \optfmt{double}: double-precision sort. This is for non-locale
18354 decimal sort values.
18355
18356 \item \optfmt{double-reverse}: as above but reverses the order.
18357
18358 \item \optfmt{numeric}: locale-sensitive numeric sort. Use
18359 \csopt{numeric-locale} to set the locale.
18360
18361 \item \optfmt{numeric-reverse}: as above but reverses the order.
18362
18363 \item \optfmt{currency}: locale-sensitive currency sort. Use
18364 \csopt{numeric-locale} to set the locale.
18365
18366 \item \optfmt{currency-reverse}: as above but reverses the order.
18367
18368 \item \optfmt{percent}: locale-sensitive percent sort. Use
18369 \csopt{numeric-locale} to set the locale.
18370
18371 \item \optfmt{percent-reverse}: as above but reverses the order.
18372
18373 \item \optfmt{numberformat}: locale-sensitive custom numeric sort. Use
18374 \csopt{numeric-locale} to set the locale and
18375 \csopt{numeric-sort-pattern} to set the number pattern.
18376
18377 \item \optfmt{numberformat-reverse}: as above but reverses the order.
18378
18379 \end{itemize}
18380
18381 In general, it doesn't make much sense to have \hierarchical\ entries
18382 that need to be sorted by a number, but it is possible as long as each
18383 level uses the same type of numbering.
18384
18385 \subsubsection{Date-Time}
18386
18387 The sort methods listed in \tableref{tab:sortoptionsdatetime}
18388 are for dates and times. Use \csopt{date-sort-format}
18389 and \csopt{date-sort-locale} to specify the date format and locale.
18390 \begin{itemize}
18391 \item \optfmt{date}: sort dates.
18392
18393 \item \optfmt{date-reverse}: as above but reverses the order.
18394
18395 \item \optfmt{datetime}: sort date and time information.
18396
18397 \item \optfmt{datetime-reverse}: as above but reverses the order.
18398
18399 \item \optfmt{time}: sort times.
18400
18401 \item \optfmt{time-reverse}: as above but reverses the order.
18402
18403 \end{itemize}
18404
18405 If the field you want to sort by contains a date then the
18406 simplest way to sort is to ensure the date is in ISO format
18407 and then just use a letter sort. However it may be that
18408 the date is in the format particular to your locale or you have a
18409 mix of \era{AD} and \era{BC}. In which
18410 case you can use one of the date/time sort options (such as
18411 \csopt[date]{sort} or \csopt[date-reverse]{sort}). The locale
18412 is assumed to be your default locale (as given by the \idx{JVM})
18413 but if you are using a different locale this can
18414 be set with \csopt{date-sort-locale}. The pattern is assumed
18415 to be the default for that locale but you can change this with
18416 \csopt{date-sort-format}. If you provide your
18417 own custom pattern you must make sure that it matches the selected
18418 \optfmt{sort} option.
18419
18420 Take care if you switch from using the \idx{JRE} to the \idx{CLDR}
18421 \idx{localeprovider} as you may find the default pattern changes.
18422
18423 The locale and pattern information is used by \bibgls\ to parse the
18424 field. If the field value can't be parsed then \bibgls\ will issue
18425 a warning and assume the current date (or time).
18426
18427 The actual sort value that's used by the comparator is numeric. In
18428 the case of the time-based \csopt[datetime]{sort} and
18429 \csopt[time]{sort} (or their \optfmt{-reverse} versions), this value
18430 is the number of milliseconds since 1st~January, 1970. In the case
18431 of \csopt[date]{sort} (or \csopt[date-reverse]{sort}), this value is
18432 obtained from $a(y\times10000 + m\times100 + d)$ where $y$ is the
18433 year, $m$ is the month number, $d$ is the day of month number, and
18434 $a$ is an integer representation of the era ($-1$ for \era{BC} and
18435 $+1$ for \era{AD}).
18436
18437 Unlike the numeric sort methods (such as \csopt[integer]{sort})
18438 the date-time sort methods set the \field{sort} field to a value
18439 that can be more easily parsed within the document and that should
18440 mostly achieve the same ordering if a letter comparator were to be used
18441 with it (except for \era{BC} dates, where the order needs to be
18442 reversed). This has the by-product of providing a field that
18443 you can access within the document that can be more easily parsed by
18444 \LaTeX.
18445
18446 In general, it doesn't make much sense to have \hierarchical\ entries
18447 that need to be sorted by date, but it is possible as long as each
18448 level uses the same date format.
18449
18450 For example, suppose my \ext{bib} file contains:
18451 \begin{codeenv}
18452 \atentry{entry}\marg{journalentry,
18453 \field{name}=\marg{10 Jan 2017},
18454 \field{description}=\marg{an interesting journal entry}
18455 }
18456 \end{codeenv}
18457 The \field{name} field uses an abbreviated UK date format.
18458 If all my other entries also use this format in the \field{name}
18459 then I can sort them chronologically:
18460 \begin{codeenv}
18461 \gls{GlsXtrLoadResources}\oarg{
18462 \csopt[entries]{src},\comment{data in entries.bib}
18463 \csopt[date]{sort},
18464 \csopt[en-GB]{date-sort-locale},
18465 \csopt[medium]{date-sort-format}
18466 }
18467 \end{codeenv}
18468 (The medium format is actually the default for this locale,
18469 and the locale matches my system locale, so I could omit
18470 both \csopt{date-sort-locale} and \csopt{date-sort-format}.)
18471
18472 If \commonlongarg{verbose} mode is on, the transcript will show
18473 the label, sort value and numeric value for each entry.
18474 In this case, the information is:
18475 \begin{verbatim}
18476 journalentry -> '+1 2017-01-10' [20170110]
18477 \end{verbatim}
18478 The first value is the label (\code{journalentry}), the second
18479 value is assigned to the \field{sort} field
18480 (\code{+1 2017-01-10}) and the number in square brackets
18481 is the actual numeric value used by the comparator. The signed
18482 number at the start of the sort field \code{+1} is the numeric
18483 representation of the era as used for the $a$ variable in the
18484 computation of the numeric value (as described earlier).
18485
18486 If I change the format to \csopt[short]{date-sort-format},
18487 then the date can't be parsed correctly and \bibgls\ will
18488 issue the following warning:
18489 \begin{verbatim}
18490 Warning: Can't parse sort value '10 Jan 2017' for 'journalentry'
18491 (pattern: 'dd/MM/yyyy')
18492 \end{verbatim}
18493 This shows the value that \bibgls\ is trying to
18494 parse (\code{10 Jan 2017}) for the entry identified by
18495 the given label (\code{journalentry}). The pattern \bibgls\
18496 expects is also given (\code{dd/MM/yyyy}).
18497
18498 \optsection{shuffle}
18499
18500 Automatically sets \csopt[random]{sort} and \csopt{flatten}.
18501 The value \meta{seed} may be omitted. If present, it should
18502 be an integer used as a seed for the random number generator.
18503
18504 \optsection{sort-field}
18505
18506 The \csopt{sort-field} key indicates which field provides the sort
18507 value. The \meta{field} must be a recognised field name or you
18508 may use \csopt[id]{sort-field} to sort according to the label.
18509 The default value is the \field{sort} field (which is typically
18510 inferred rather than explicitly set).
18511
18512 Example:
18513 \begin{codeenv}
18514 \gls{GlsXtrLoadResources}\oarg{
18515 \csopt[entries-terms]{src},\comment{data in entries-terms.bib}
18516 \csopt[symbol]{sort-field},\comment{sort by 'symbol' field}
18517 \csopt[letter-case]{sort}\comment{case-sensitive letter sort}
18518 }
18519 \end{codeenv}
18520 This sorts the entries according to the \field{symbol} field using
18521 a case-sensitive letter comparison.
18522
18523 \begin{important}
18524 In general it's better to use the default \csopt[sort]{sort-field}
18525 and adjust the fallbacks instead (see
18526 \sectionref{sec:fallbacks}). The \csopt{sort-field} option is
18527 provided if you want to use a specific field regardless of the
18528 \gls{entrytype}.
18529 \end{important}
18530
18531 If an entry is missing a value for \meta{field}, then the value of
18532 the fallback field will be used instead. If \csopt{missing-sort-fallback} is
18533 set, then that's used as the fallback, otherwise it depends on the
18534 \gls{entrytype}.
18535 If no fallback field can be found, the entry's label will be used.
18536
18537 For the specific case with the default \csopt[sort]{sort-field}
18538 setting, the fallback for the \field{sort} field is governed not
18539 only by the \gls{entrytype} but also by some associated settings:
18540
18541 \begin{itemize}
18542 \item If the entry's original type (before being aliased with
18543 \csopt{entry-type-aliases}) is identified in
18544 \csopt{custom-sort-fallbacks}, then if the \field{sort} field is missing
18545 the value is obtained from the supplied custom mapping.
18546
18547 \item If the entry is defined using \atentry{entry} (or a dual form
18548 that acts like \atentry{entry}), then if the \field{sort} field is
18549 missing the value is obtained from the field identified by
18550 \csopt{entry-sort-fallback}. If that field is also missing then
18551 that field's fallback is used.
18552
18553 \item For the index \glspl{entrytype} like \atentry{index} or
18554 \atentry{indexplural}, then if the \field{sort} field is missing the
18555 value is obtained from the \field{name} field. If that field is also
18556 missing, then the value is obtained from the particular \gls{entrytype}['s]
18557 fallback for the \field{name} field. (For example, the entry's label
18558 for \atentry{index} or the \field{plural} field for
18559 \atentry{indexplural}.)
18560
18561 \item If the entry is defined with an abbreviation type (for
18562 example, \atentry{abbreviation} or \atentry{acronym}) then if the
18563 \field{sort} field is missing, \bibgls\ will fallback on the field
18564 given by \csopt{abbreviation-sort-fallback}.
18565
18566 \item The symbol-like \glspl{entrytype} fallback on the field given by
18567 \csopt{symbol-sort-fallback} if the \field{sort} field is missing.
18568
18569 \item Entries defined using \atentry{bibtexentry} fallback on the field
18570 given by \csopt{bibtexentry-sort-fallback}, which defaults to the
18571 \field{name} field. Note that this only applies to the \gls{mainentry}.
18572 The \glsdisp{spawnedentry}{spawned} \atentry{contributor} entries behave like
18573 \atentry{index}.
18574
18575 \end{itemize}
18576 Use \csopt{dual-sort-field} when sorting dual entries.
18577
18578 \optsection{missing-sort-fallback}
18579
18580 With \csopt[\meta{sort-field}]{sort-field}, if the value of the field
18581 identified by \meta{sort-field} is missing, then \bibgls\ behaves as
18582 follows:
18583 \begin{enumerate}
18584 \item If \csopt[\meta{fallback-field}]{missing-sort-fallback} is set, then
18585 \bibgls\ will fallback on the value provided by the field
18586 \meta{fallback-field}. If \meta{fallback-field} is
18587 missing, then \bibgls\ will query the \gls{entrytype}['s] fallback for
18588 \meta{fallback-field} (not for \meta{sort-field}).
18589
18590 The \meta{fallback-field} must be a known field but not an internal
18591 field. It can't be the \field{sort} field. (Take care not to cause
18592 an infinite loop if \csopt{sort-field} has been changed.) Unlike the
18593 other sort fallback options, such as \csopt{entry-sort-fallback},
18594 the \meta{fallback-field} can't be a keyword (to identify the label)
18595 and can't be a composite.
18596
18597 \item If the \gls{entrytype} has a fallback rule for
18598 \meta{sort-field}, then that rule is used (see
18599 \sectionref{sec:fallbacks}). When \csopt[sort]{sort-field} this
18600 means:
18601 \begin{itemize}
18602 \item If the entry's original \gls{entrytype} has been identified in
18603 \csopt{custom-sort-fallbacks}, then \bibgls\ will fallback on the
18604 designated custom setting.
18605
18606 \item If the entry was defined using one of the index types (such as
18607 \atentry{index}), then \bibgls\ will fallback on the \field{name}
18608 field.
18609
18610 \item If the entry was defined using the \atentry{entry} type (or a
18611 dual form that acts like \atentry{entry}), then \bibgls\ will
18612 fallback on the field given by \csopt{entry-sort-fallback}.
18613
18614 \item If the entry was defined using
18615 one of the symbol types (such as \atentry{symbol}), then \bibgls\
18616 will fallback on the field given by \csopt{symbol-sort-fallback}.
18617
18618 \item If the entry was defined using
18619 one of the abbreviation types (such as \atentry{abbreviation}), then \bibgls\
18620 will fallback on the field given by
18621 \csopt{abbreviation-sort-fallback}.
18622
18623 \item If the entry was defined using \atentry{bibtexentry} (but not
18624 the spawned \atentry{contributor} entries), then \bibgls\ will
18625 fallback on the field given by
18626 \csopt{bibtexentry-sort-fallback}.
18627 \end{itemize}
18628 If \meta{sort-field} is not \field{sort}, then there may not be a
18629 fallback, in which case the next condition applies:
18630 \item Otherwise the sort value will be set to the entry label and \bibgls\
18631 will issue a warning.
18632 \end{enumerate}
18633 The default setting is \csopt[\empty]{missing-sort-fallback}, which
18634 means that step~1 above is omitted.
18635
18636 Use \csopt{dual-missing-sort-fallback} when sorting dual entries
18637 separately from primaries, and use
18638 \csopt{secondary-missing-sort-fallback} for \csopt{secondary}
18639 sorting.
18640
18641 \optsection{trim-sort}
18642
18643 If the interpreter is used to determine the sort value, this setting
18644 governs whether or not the interpreter should trim leading and
18645 trailing spaces. The default setting is \csopt[true]{trim-sort}.
18646
18647 This option automatically sets \csopt[\meta{boolean}]{dual-trim-sort}
18648 and \csopt[\meta{boolean}]{secondary-trim-sort}.
18649
18650 \optsection{sort-replace}
18651
18652 This option may be used to perform \gls{regular-expression} substitutions
18653 on the sort value and has the same syntax as \csopt{labelify-replace}.
18654 The value is required for this key but may be empty, which indicates
18655 that the setting is switched off.
18656
18657 This action is done after the interpreter parses the
18658 sort value (if applicable) and before \csopt{sort-number-pad} (if
18659 applicable). For example, suppose the sort value is:
18660 \begin{codeenv}
18661 \cs{ensuremath}\marg{\ics{approx} 3.14}
18662 \end{codeenv}
18663 then the interpreter will convert this to $\mathtt{\approx}$\texttt{3.14} but:
18664 \begin{codeenv}
18665 \csopt[\marg{\cs{glshex}2248}\marg{}]{sort-replace}
18666 \end{codeenv}
18667 can be used to strip the $\approx$ symbol (\hex{2248}) so that the value can
18668 now be parsed as a number if \csopt[double]{sort} has been used.
18669
18670 Use \csopt{dual-sort-replace} for dual
18671 and \csopt{secondary-sort-replace} for secondary sort methods.
18672
18673 \optsection{sort-rule}
18674
18675 If the \csopt[custom]{sort} option is used, the sort rule must be
18676 provided with \optfmt{sort-rule}. If \csopt{sort} is not set to
18677 \optfmt{custom}, the \optfmt{sort-rule} setting will be ignored.
18678 This setting uses Java's
18679 \href{http://docs.oracle.com/javase/8/docs/api/java/text/RuleBasedCollator.html}{RuleBasedCollator}
18680 class~\cite{rulebasedcollator}, and the rule syntax needs to conform
18681 to that format.
18682
18683 Remember that the options will be expanded as they are written to
18684 the \iext{aux} file, so be careful of any special characters that
18685 occur in the rule. For the special characters \idx{param}
18686 \idx{commentchar} \idx{sbchar} \idx{colsep} \idx{bgroupchar} and
18687 \idx{egroupchar} you can use \ics{cs.hash}, \ics{cs.percent},
18688 \ics{cs.underscore}, \ics{cs.amp}, \ics{cs.openbrace} and
18689 \ics{cs.closebrace}. These will be written to the \ext{aux} file
18690 with the leading backslash, but \bibgls\ will remove it for this
18691 resource option. Remember that the \styfmt{glossaries} package
18692 provides \ics{glsbackslash} and \ics{glstildechar} which can be used
18693 to produce a literal backslash (\idx{backslashchar}) and tilde
18694 (\idx{tildechar}).
18695
18696 You can also
18697 use \stringu\meta{hex} (where \meta{hex} is a hexadecimal
18698 code) to represent a Unicode character. For example:
18699 \begin{codeenv}
18700 \gls{GlsXtrLoadResources}\oarg{
18701 \csopt[custom]{sort},
18702 \csopt[< a,A < b,B < c,C < ch,Ch,CH < d,D
18703 < dd,Dd,DD < e,E < f,F < ff,Ff,FF
18704 < g,G < ng,Ng,NG < h,H < ij,Ij,IJ
18705 < i,I < j,J < k,K < l,L < ll,Ll,LL < m,M
18706 < n,N < o,O < p,P < ph,Ph,PH < q,Q < r,R < rh,Rh,RH
18707 < s,S < t,T < th,Th,TH < u,U < v,V < w,W < x,X < y,Y < z,Z
18708 < \stringu00E6,\stringu00C6]{sort-rule}
18709 }
18710 \end{codeenv}
18711 It's best to use \ics{cs.string} rather than \ics{protect} to avoid
18712 unwanted spaces interfering with \meta{hex}. Note that
18713 \sty{glossaries-extra} v1.21+ provides\footnote{The command
18714 definition was moved to \isty{glossaries-extra-bib2gls} from version
18715 1.27 since it's only needed with \bibgls.}\ \ics{glshex}
18716 which just does \stringu\ so you can do
18717 \code{\ics{glshex} 00E6} instead of \code{\stringu00E6}.
18718 This is only one character different, but you can redefine
18719 \ics{glsxtrresourceinit} to locally set \ics{u} to \ics{glshex} while
18720 the protected write is performed. For example:
18721 \begin{codeenv}
18722 \cs{renewcommand}*\marg{\cs{glsxtrresourceinit}}\marg{\cmd{let}\cmd{u}\cs{glshex}}
18723 \end{codeenv}
18724 Then you can just do \code{\csfmt{u}00E6} instead of \code{\stringu00E6}.
18725 Note that \ics{GlsXtrResourceInitEscSequences} performs a similar
18726 assignment, so you can instead do:
18727 \begin{codeenv}
18728 \cs{renewcommand}*\marg{\cs{glsxtrresourceinit}}\marg{\comment{}
18729 \ics{GlsXtrResourceInitEscSequences}
18730 }
18731 \end{codeenv}
18732
18733 The \isty{glossaries-extra-bib2gls} package (which is automatically loaded by
18734 the \styopt{record} option) provides some commands for common rule blocks
18735 that may be used in the construction of custom rules. For example:
18736 \begin{codeenv}
18737 \csopt[\ics{glsxtrcontrolrules}
18738 ;\ics{glsxtrspacerules}
18739 ;\ics{glsxtrnonprintablerules}
18740 ;\ics{glsxtrcombiningdiacriticrules}
18741 ,\ics{glsxtrhyphenrules}
18742 <\ics{glsxtrgeneralpuncrules}
18743 <\ics{glsxtrdigitrules}
18744 <\ics{glsxtrfractionrules}
18745 <\ics{glsxtrMathItalicGreekIrules}
18746 <\ics{glsxtrGeneralLatinIVrules}
18747 <\ics{glsxtrLatinAA}
18748 <\ics{glsxtrLatinOslash}
18749 ]{sort-rule}
18750 \end{codeenv}
18751 This places the Greek maths symbols (such as \ics{alpha}) before the
18752 Latin block. See the \sty{glossaries-extra} documentation for
18753 further details of these commands.
18754
18755 You might find it convenient to provide similar commands in a
18756 package for rules you may often need. For example, suppose I have a
18757 package called, say, \styfmt{mapsymbols} for providing map symbols:
18758 \begin{codeenv}
18759 \cmd{NeedsTeXFormat}\marg{LaTeX2e}
18760 \cmd{ProvidesPackage}\marg{mapsymbols}
18761 \comment{some package or font loading stuff here to provide}
18762 \comment{the appropriate symbols}
18763 \cmd{newcommand}\marg{\cmd{Stadium}}\marg{\ldots}
18764 \cmd{newcommand}\marg{\cmd{Battlefield}}\marg{\ldots}
18765 \cmd{newcommand}\marg{\cmd{Harbour}}\marg{\ldots}
18766 \comment{etc}
18767 \strut
18768 \comment{Provide a rule block:}
18769 \cmd{newcommand}\marg{\cmd{MapSymbolOrder}}\marg{\comment{}
18770 \cs{glshex} 2694 \comment{crossed-swords 0x2694}
18771 < \cs{glshex} 2693 \comment{anchor 0x2693}
18772 < \cs{glshex} 26BD \comment{football 0x26BD}
18773 }
18774 \end{codeenv}
18775 In addition to \filefmt{mapsymbols.sty}, I also need to create
18776 \filefmt{mapsymbols.bib} to provide the appropriate definitions for
18777 \bibgls:
18778 \begin{codeenv}
18779 \atentry{preamble}\marg{\qtdelim{\cs{glsxtrprovidecommand}\marg{\cmd{Harbour}}\marg{\icharhex{2693}}
18780 \cs{glsxtrprovidecommand}\marg{\cmd{Battlefield}}\marg{\charhex{2694}}
18781 \cs{glsxtrprovidecommand}\marg{\cmd{Stadium}}\marg{\charhex{26BD}}}}
18782 \end{codeenv}
18783 The use of \ics{glsxtrprovidecommand} will override any previous
18784 definitions of these commands in \bibgls's interpreter but will act
18785 like \ics{providecommand} within the document, and so won't
18786 interfere with the commands defined in \filefmt{mapsymbols.sty}.
18787 Now I can just do:
18788 \begin{codeenv}
18789 \cmd{usepackage}\marg{mapsymbols}\comment{my custom package}
18790 \cmd{usepackage}[\styopt{record}]\marg{glossaries-extra}
18791 \strut
18792 \gls{GlsXtrLoadResources}\oarg{
18793 \csopt[mapsymbols,\comment{<--- my custom mapsymbols.bib}
18794 entries\comment{data in entries.bib}
18795 ]{src},
18796 \csopt[custom]{sort},
18797 \csopt[\cs{glsxtrcontrolrules}
18798 ;\cs{glsxtrspacerules}
18799 ;\cs{glsxtrnonprintablerules}
18800 ;\cs{glsxtrcombiningdiacriticrules}
18801 ,\cs{glsxtrhyphenrules}
18802 <\cs{glsxtrgeneralpuncrules}
18803 <\cs{glsxtrdigitrules}
18804 <\cs{glsxtrfractionrules}
18805 <\cmd{MapSymbolOrder} \comment{<--- custom map symbols}
18806 <\cs{glsxtrMathItalicGreekIrules}
18807 <\ics{glsxtrGeneralLatinIrules}
18808 ]{sort-rule}
18809 }
18810 \end{codeenv}
18811
18812 An alternative to providing \filefmt{mapsymbols.bib} is to provide a
18813 custom package just for \bibgls' use. For example,
18814 \filefmt{mapsymbols-bib2gls.sty}:
18815 \begin{codeenv}
18816 \comment{Provided for \bibgls\ only.}
18817 \comment{Use \cmd{usepackage}\marg{mapsymbols} in the document.}
18818 \cmd{NeedsTeXFormat}\marg{LaTeX2e}
18819 \cmd{ProvidesPackage}\marg{mapsymbols-bib2gls}
18820 \cs{glsxtrprovidecommand}\marg{\cmd{Harbour}}\marg{\charhex{2693}}
18821 \cs{glsxtrprovidecommand}\marg{\cmd{Battlefield}}\marg{\charhex{2694}}
18822 \cs{glsxtrprovidecommand}\marg{\cmd{Stadium}}\marg{\charhex{26BD}}
18823 \cmd{endinput}
18824 \end{codeenv}
18825 and instruct \bibgls\ to parse it with
18826 \code{\longarg{custom-packages} mapsymbols-bib2gls} (and use
18827 \filefmt{mapsymbols.sty} in the document). Remember that \bibgls\
18828 isn't a \TeX\ engine so make sure to only use simple commands in
18829 this file.
18830
18831 \optsection{break-at}
18832
18833 This option automatically implements
18834 \csopt[\meta{option}]{dual-break-at} and
18835 \csopt[\meta{option}]{secondary-break-at}.
18836
18837 The alphabet sort options (\tableref{tab:sortoptionsrule}) typically
18838 list non-letter characters before alphabetical characters and spaces
18839 are quite often in the ignored set. This means that the alphabet
18840 sort options are naturally in a letter order, similar to
18841 \idx!{xindy}['s] \code{ord/letorder} module. (This isn't the same as
18842 \csopt[letter-nocase]{sort}, which just sorts according to the
18843 Unicode value not according to a particular alphabet.)
18844
18845 In order to replicate \idx!{makeindex} and \idx!{xindy}['s] default word
18846 order, \bibgls\ splits up the sort value at word boundaries and
18847 inserts a marker (identified by \csopt{break-marker}).
18848 For example, if the sort value is \qt{sea lion} then it's actually
18849 converted to \verb"sea|lion|" whereas \qt{sea} becomes \verb"sea|"
18850 and \qt{seal} becomes \verb"seal|". The default marker is \verb"|"
18851 which is commonly placed in collation rules before digits but
18852 after the ignored characters, such as spaces and hyphens.
18853
18854 Note that this action removes non-letters, so for example,
18855 if the sort value is \verb"# (parameter)" then it will be converted
18856 to \verb"parameter|" (hash, space and parentheses removed).
18857 If you only want to break at spaces (optionally following a comma)
18858 use the following instead:
18859 \begin{codeenv}
18860 \csopt[none]{break-at},
18861 \csopt[\marg{,? +}\marg{|}]{sort-replace}
18862 \end{codeenv}
18863
18864 You can change the construction of the break points with
18865 \csopt[\meta{option}]{break-at} where \meta{option} may be one of:
18866 \begin{itemize}
18867 \item \optfmt{word}: break at word boundaries (default).
18868 Note that what constitutes a word varies
18869 according to the locale but usually anything that's not alphanumeric
18870 will designate a word-boundary. The characters between words are
18871 discarded.
18872 For example, the sort value \qt{Tom, Dick, and Harry} becomes
18873 \verb"Tom|Dick|and|Harry", which has discarded the comma and space
18874 characters.
18875 \item \optfmt{character}: break after each character.
18876 \item \optfmt{sentence}: break after each sentence.
18877 \item \optfmt{upper-notlower}: break after any \idx{uppercase} character
18878 that's not followed by a \idx{lowercase} character. For example,
18879 \qt{MathML} becomes \verb"MathM|L|" and \qt{W3C} becomes
18880 \verb"W|3C|".
18881 \item \optfmt{upper-upper}: break after any \idx{uppercase} character
18882 that's followed by an \idx{uppercase} character.
18883 \item \optfmt{upper-notlower-word}: first applies break-points
18884 according to \optfmt{upper-notlower} and then according to
18885 \optfmt{word}.
18886 \item \optfmt{upper-upper-word}: first applies break-points
18887 according to \optfmt{upper-upper} and then according to
18888 \optfmt{word}.
18889 \item \optfmt{none}: don't create break points. Use this option to
18890 emulate \idx!{makeindex} or \idx!{xindy}'s letter ordering, or combine
18891 with \csopt{sort-replace} to insert custom break points.
18892 \end{itemize}
18893
18894 This option is ignored when used with the non-alphabetic
18895 \csopt{sort} options. You can find the break points in the
18896 \field{sort} field for the entry's definition in the \ext{glstex}
18897 file (which is provided for information rather than for use in the
18898 document). Alternatively, use the \commonlongarg{debug} switch to show
18899 the break points in the transcript. (This will also show the
18900 collation rule.)
18901
18902 If you want to selectively apply break points only to certain
18903 entries, use \csopt{break-at-match} or \csopt{break-at-not-match}.
18904
18905 \optsection{break-marker}
18906
18907 This option automatically implements the dual and secondary settings
18908 \csopt[\meta{marker}]{dual-break-marker} and
18909 \csopt[\meta{marker}]{secondary-break-marker}.
18910
18911 The break marker can be changed using
18912 \csopt[\meta{marker}]{break-marker}, where \meta{marker} is
18913 the character to use. For example, \csopt[-]{break-marker} will use a
18914 hyphen. The marker may be empty, which effectively strips the
18915 inter-word punctuation. For example, with
18916 \csopt[\empty]{break-marker}, \qt{Tom, Dick, and Harry} becomes
18917 \code{TomDickandHarry} and \qt{sea lion} simply becomes
18918 \code{sealion}. If \meta{marker} is omitted,
18919 \csopt[\empty]{break-marker} is assumed.
18920
18921 \optsection{break-at-match}
18922
18923 This option automatically implements
18924 \csopt[\meta{option}]{dual-break-at-match} and
18925 \csopt[\meta{option}]{secondary-break-at-match}.
18926
18927 If you have \csopt{break-at} set to create break points (for
18928 example, with \csopt[word]{break-at}) then you can specify which
18929 entries should have break points with this option. The value has the same
18930 syntax as \csopt{match}. If an entry matches the criteria, then
18931 break points are added, otherwise no break points are added.
18932 For example, to only have break points for entries defined with \atentry{index}
18933 or \atentry{indexplural}:
18934 \begin{codeenv}
18935 \csopt[entrytype=index(plural)?]{break-at-match}
18936 \end{codeenv}
18937 This option has no effect with \csopt[none]{break-at}.
18938
18939 \optsection{break-at-match-op}
18940 This option automatically implements
18941 \csopt[\meta{option}]{dual-break-at-match-op} and
18942 \csopt[\meta{option}]{secondary-break-at-match-op}.
18943
18944 If the value of \csopt{break-at-match} contains more than one
18945 \meta{key}=\meta{pattern} element, the \csopt{break-at-match-op}
18946 determines whether to apply a logical AND or a logical OR.
18947 The \meta{value} may be either \optfmt{and} or \optfmt{or}.
18948 The default is \csopt[and]{break-at-match-op}.
18949
18950 \optsection{break-at-not-match}
18951
18952 This option automatically implements
18953 \csopt[\meta{option}]{dual-break-at-not-match} and
18954 \csopt[\meta{option}]{secondary-break-at-not-match}.
18955
18956 For example, to prevent entries defined with
18957 \atentry{symbol} from having break points:
18958 \begin{codeenv}
18959 \csopt[entrytype=symbol]{break-at-not-match}
18960 \end{codeenv}
18961 Like \csopt{break-at-match} but negates the match.
18962 This option has no effect with \csopt[none]{break-at}.
18963
18964 \optsection{sort-number-pad}
18965
18966 This option automatically implements the dual and secondary settings
18967 \csopt[\meta{number}]{dual-sort-number-pad},
18968 \csopt[\meta{number}]{secondary-sort-number-pad}.
18969
18970 If \meta{number} is greater than 1, any integer sub-strings found
18971 in the sort value will be zero-padded up to this value. Since the
18972 \code{-} character is often ignored by rule-based sort methods,
18973 any signs found will be replaced with the markers given by
18974 \csopt{sort-pad-plus} and \csopt{sort-pad-minus}, which should be
18975 chosen to ensure that negative numbers are ordered before positive
18976 numbers (if this is desired). An unsigned number will have the
18977 \csopt{sort-pad-plus} marker inserted before it. The default value
18978 is \csopt[0]{sort-number-pad}, which doesn't implement any padding.
18979
18980 If you use this with a locale sort method, it's best to also set
18981 \csopt[none]{break-at}, as the default word boundary break points
18982 will likely be confused by a mix of alphanumerics.
18983
18984 \optsection{sort-pad-plus}
18985
18986 This option automatically implements the dual and secondary settings
18987 \csopt[\meta{marker}]{dual-sort-pad-plus},
18988 \csopt[\meta{marker}]{secondary-sort-pad-plus}.
18989
18990 This option only has an effect when used with
18991 \csopt[\meta{number}]{sort-number-pad} where \meta{number} is
18992 greater than 1. Positive numbers will have their sign replaced with
18993 \meta{marker}. The default setting is \csopt[>]{sort-pad-plus}.
18994
18995 \optsection{sort-pad-minus}
18996
18997 This option automatically implements the dual and secondary settings
18998 \csopt[\meta{marker}]{dual-sort-pad-minus},
18999 \csopt[\meta{marker}]{secondary-sort-pad-minus}.
19000
19001 This option only has an effect when used with
19002 \csopt[\meta{number}]{sort-number-pad} where \meta{number} is
19003 greater than 1. Negative numbers will have their sign replaced with
19004 \meta{marker}. The default setting is \csopt[<]{sort-pad-plus}.
19005
19006 \optsection{identical-sort-action}
19007
19008 This option automatically implements the dual and secondary settings
19009 \csopt[\meta{value}]{dual-identical-sort-action} and
19010 \csopt[\meta{value}]{secondary-identical-sort-action}.
19011
19012 This option determines what the comparator should do if
19013 two entries at the same \hierarchicallevel\ are considered
19014 equal. The \meta{value} may be one of:
19015 \begin{itemize}
19016 \item\optfmt{none}: don't take any further action if sort values are
19017 identical;
19018 \item\optfmt{def} if sort values are identical, order them according to definition;
19019 \item\optfmt{use}: if sort values are identical, order them
19020 according to use in the document (order determine by a normal record);
19021 \item\optfmt{id}: if sort values are identical, compare
19022 the entry labels;
19023 \item\optfmt{original id}: if sort values are identical, compare the
19024 original unprefixed entry labels (as given in the \ext{bib} file);
19025 \item\meta{field}: if sort values are identical, compare
19026 the values from the given \meta{field}.
19027 \end{itemize}
19028 For the last three cases, a simple case-sensitive string comparison is used.
19029 If \meta{value} isn't a recognised keyword or valid field an error will occur. The
19030 default setting is \csopt[id]{identical-sort-action}. If you're
19031 using one of the sort rules listed in \tableref{tab:sortoptionsrule}
19032 and you also want a locale-sensitive sort used on the fallback, then
19033 you need to use \csopt{sort-suffix} instead.
19034
19035 \bibgls\ allows duplicate sort values, but this can cause a problem
19036 for \hierarchical\ entries where \glspl{parententry} with duplicate sort
19037 fields are clumped together and their \children\ follow. To prevent
19038 this from happening, the \csopt[id]{identical-sort-action}
19039 setting will fallback on comparing the labels. Since all labels
19040 must be unique, this means comparisons between two different entries
19041 are all either strictly higher or strictly lower.
19042
19043 This action occurs after any suffixes have been appended through
19044 \csopt{sort-suffix}.
19045
19046 \optsection{sort-suffix}
19047
19048 This option automatically implements the dual and secondary settings
19049 \csopt[\meta{value}]{dual-sort-suffix} and
19050 \csopt[\meta{value}]{secondary-sort-suffix}.
19051 The value may be one of:
19052 \begin{itemize}
19053 \item\optfmt{none}: don't append a suffix to any \field{sort} value;
19054 \item\optfmt{non-unique}: append a numeric suffix to non-unique
19055 \field{sort} values;
19056 \item\meta{field}: append the value of the given field (if set) to
19057 the \field{sort} field. The given field must be defined (has an
19058 associated key for use in \gls{newglossaryentry}) but may be unset.
19059 If the interpreter is on, the field contents will be interpreted.
19060 If the field is just a label (such as the \field{category} field)
19061 you may find it simpler to use
19062 \csopt[\meta{field}]{identical-sort-action} instead.
19063 \end{itemize}
19064 The default setting is \csopt[none]{sort-suffix}.
19065
19066 This option only affects the alphabetic
19067 (\tableref{tab:sortoptionsrule}), letter
19068 (\tableref{tab:sortoptionsletter}) and letter-number
19069 (\tableref{tab:sortoptionsletternumber}) sort rules. For the other
19070 types of sort methods (not including the no-sort options listed in
19071 \tableref{tab:sortoptionsnosort}) you'll need to use
19072 \csopt{identical-sort-action} to prevent problems occurring with
19073 duplicate sort values.
19074
19075 In the case of \csopt[non-unique]{sort-suffix}, this will only
19076 append a suffix to the duplicate sort values (within the same
19077 \hierarchicallevel). The first sort value to be encountered isn't
19078 given a suffix.
19079
19080 The \csopt[\meta{field}]{sort-suffix} setting will only append a suffix
19081 if that field is set, but (if set) it will apply the suffix to all
19082 \field{sort} values, even those that are unique.
19083
19084 If you use \commonlongarg{verbose}, then \bibgls\ will write information
19085 in the transcript when it appends a suffix to the sort value. The
19086 message:
19087 \begin{alltt}
19088 Sort value '\meta{sort}' (entry '\meta{id}') not unique for the entry's
19089 \hierarchicallevel.
19090 \end{alltt}
19091 indicates that an entry with the given \meta{sort} value has already
19092 been found within the same \hierarchicallevel\ as the currently
19093 processed entry (whose label is given by \meta{id}). The same
19094 \hierarchicallevel\ in this context means that either both entries
19095 don't have a \parent\ or both entries have the same \parent. (That is,
19096 the entries are considered \glspl{sibling}.)
19097
19098 This message will then be followed by:
19099 \begin{alltt}
19100 Appending suffix '\meta{suffix}' to the sort value '\meta{sort}'
19101 for entry '\meta{id}'.
19102 \end{alltt}
19103 which indicates that the entry (identified by the label \meta{id})
19104 has been assigned the sort value given by \meta{sort}\meta{suffix}.
19105 If any break markers are applied, this is done after the suffix has
19106 been appended.
19107
19108 For example, suppose in my document I want to write about \appfmt{makeglossaries}
19109 (the application) and \csfmt{makeglossaries} (the command). I might
19110 decide to define semantic commands:
19111 \begin{codeenv}
19112 \cs{newcommand}*\marg{\cmd{application}}[1]\marg{\ics{texttt}\marg{\idx{param}1}}
19113 \cs{newcommand}*\marg{\cmd{command}}[1]\marg{\cs{texttt}\marg{\cs{glsbackslash} \idx{param}1}}
19114 \end{codeenv}
19115 In my \ext{bib} file I might have:
19116 \begin{codeenv}
19117 \atentry{entry}\marg{cs.makeglossaries,
19118 \field{name}=\marg{\cmd{command}\marg{makeglossaries}},
19119 \field{category}=\marg{command},
19120 \field{description}=\marg{opens glossary files}
19121 }
19122 \strut
19123 \atentry{entry}\marg{ap.makeglossaries,
19124 \field{name}=\marg{\cmd{application}\marg{makeglossaries}},
19125 \field{category}=\marg{application},
19126 \field{description}=\marg{Perl script}
19127 }
19128 \end{codeenv}
19129 If \bibgls\ is provided with the definitions of \csfmt{application}
19130 and \csfmt{command} (by interpreting the \atentry{preamble} or a
19131 package provided with \longarg{custom-packages}) then it will
19132 determine that the sort value for \code{cs.makeglossaries} is
19133 \csfmt{makeglossaries} and the sort value for
19134 \code{ap.makeglossaries} is just \code{makeglossaries}. These are
19135 two distinct sort values from \bibgls's point of view although the
19136 sort rule may consider them identical if the rule ignores the
19137 \idx{escchar} character (such as the locale sort methods), in which case,
19138 \bibgls\ will then act according to \csopt{identical-sort-action}.
19139
19140 If \bibgls\ isn't provided with these custom definitions, then it
19141 will ignore those semantic commands and both entries will end up with
19142 the sort value \code{makeglossaries}. The second instance will be
19143 recognised as a duplicate and the sort value will be converted to
19144 \code{makeglossaries1} (where the automated suffix is \code{1} and
19145 the suffix marker, see below, is the empty string). Whereas with,
19146 say, \csopt[.]{sort-suffix-marker}\ then the sort value would become
19147 \code{makeglossaries.1}.
19148
19149 For comparison, consider the following document:
19150 \begin{codeenv}
19151 \cmd{documentclass}\marg{article}
19152 \strut
19153 \cmd{usepackage}[\styopt[indexgroup]{style}]\marg{glossaries}
19154 \strut
19155 \ics{cs.makeglossaries}
19156 \strut
19157 \cs{newcommand}*\marg{\cmd{application}}[1]\marg{\cs{texttt}\marg{\idx{param}1}}
19158 \cs{newcommand}*\marg{\cmd{command}}[1]\marg{\cs{texttt}\marg{\cs{glsbackslash} \idx{param}1}}
19159 \strut
19160 \gls{newglossaryentry}\marg{cs.makeglossaries}\marg{\comment{}
19161 \field{name}=\marg{\cmd{command}\marg{makeglossaries}},
19162 \field{description}=\marg{opens glossary files}}
19163 \strut
19164 \gls{newglossaryentry}\marg{ap.makeglossaries}\marg{\comment{}
19165 \field{name}=\marg{\cmd{application}\marg{makeglossaries}},
19166 \field{description}=\marg{Perl script}}
19167 \strut
19168 \cmd{begin}\marg{document}
19169 \cs{gls}\marg{cs.makeglossaries} and \cs{gls}\marg{ap.makeglossaries}.
19170 \ics{printglossaries}
19171 \cmd{end}\marg{document}
19172 \end{codeenv}
19173
19174 This uses \idx{makeindex}, which puts both entries in the
19175 \qt{Symbols} group (since they both start with \idx{escchar} from the
19176 start of \csfmt{command} and \csfmt{application}, respectively).
19177 The ordering is \appfmt{makeglossaries}, \csfmt{makeglossaries}
19178 because \qt{a} (second character of \csfmt{application}) comes
19179 before \qt{c} (second character of \csfmt{command}).
19180
19181 The switch to \idx{xindy} just involves adding the \styopt{xindy}
19182 package option:
19183 \begin{codeenv}
19184 \cs{usepackage}[\styopt{xindy},\styopt[indexgroup]{style}]\marg{glossaries}
19185 \end{codeenv}
19186 This results in a glossary that only contains one entry,
19187 \csfmt{makeglossaries}, because \idx{xindy} merges entries with
19188 duplicate sort values and the sort values end up as duplicates
19189 because \idx{xindy} discards the \csfmt{application} and
19190 \csfmt{command} control sequences. Although \bibgls\ also ignores
19191 unknown control sequences, it doesn't perform this merger.
19192
19193 If I add:
19194 \begin{codeenv}
19195 \atentry{preamble}\marg{\qtdelim{\cs{providecommand}*\marg{\cmd{application}}[1]\marg{\cs{texttt}\marg{\idx{param}1}}
19196 \cs{providecommand}\marg{\cmd{command}}[1]\marg{\cs{texttt}\marg{\cs{glsbackslash} \idx{param}1}}}}
19197 \end{codeenv}
19198 to the earlier \ext{bib} file (called, say, \filefmt{entries.bib})
19199 then the document can be altered to use \bibgls:
19200 \begin{codeenv}
19201 \cmd{documentclass}\marg{article}
19202 \strut
19203 \cmd{usepackage}[\styopt{record},\styopt[indexgroup]{style}]\marg{glossaries-extra}
19204 \strut
19205 \gls{GlsXtrLoadResources}\oarg{\csopt[entries.bib]{src},
19206 \csopt[non-unique]{sort-suffix},
19207 \csopt[none]{identical-sort-action}
19208 }
19209 \strut
19210 \cmd{begin}\marg{document}
19211 \cs{gls}\marg{cs.makeglossaries} and \cs{gls}\marg{ap.makeglossaries}.
19212 \cs{printunsrtglossaries}
19213 \cmd{end}\marg{document}
19214 \end{codeenv}
19215 This uses the default \csopt[locale]{sort} which considers \idx{escchar}
19216 an ignored (punctuation) character, so both \csfmt{makeglossaries} and
19217 \appfmt{makeglossaries} are listed in the \qt{M} letter group, even
19218 though the interpreter has determined that the sort value for
19219 \code{cs.makeglossaries} is the literal string \csfmt{makeglossaries}.
19220 Note that in this case \bibgls\ doesn't detect duplicate sort values
19221 since it only uses a simple string comparison to detect duplicates
19222 rather than using the collator.
19223
19224 If I switch to using a letter-based sort rule instead, for example
19225 \csopt[letter-nocase]{sort}, then \csfmt{makeglossaries} will be
19226 listed in the \qt{Symbols} letter group since the leading \idx{escchar}
19227 from the sort value \csfmt{makeglossaries} isn't ignored with this
19228 rule.
19229
19230 Now let's suppose I use \csopt[false]{interpret-preamble} to prevent
19231 \bibgls\ from interpreting the preamble:
19232 \begin{codeenv}
19233 \gls{GlsXtrLoadResources}\oarg{\csopt[entries.bib]{src},\csopt[false]{interpret-preamble}}
19234 \end{codeenv}
19235 This means that the custom commands won't be recognised and will
19236 therefore be ignored, so both entries will have their sort values reduced to
19237 \code{makeglosssaries}.
19238
19239 The first entry to be processed is \code{cs.makeglossaries} because
19240 it's the first to be selected. This is assigned the sort value
19241 \code{makeglossaries}. (Note that, unless you use
19242 \csopt[unsrt]{sort}, the initial selection order is based on the record
19243 order. In this example, \code{cs.makeglossaries} has the first
19244 record in the \ext{aux} file.)
19245
19246 The next entry to be processed is \code{ap.makeglossaries}. This
19247 also ends up with the sort value \code{makeglossaries} so \bibgls\
19248 converts this to \code{makeglossaries1} and (with verbose mode on)
19249 the following messages are written to the transcript:
19250 \begin{verbatim}
19251 Sort value 'makeglossaries' (entry 'ap.makeglossaries') not unique
19252 for the entry's hierarchical level.
19253 Appending suffix '1' to the sort value 'makeglossaries' for entry
19254 'ap.makeglossaries'.
19255 \end{verbatim}
19256 Both entries are listed in the \qt{M} letter group in the order
19257 \csfmt{makeglossaries}, \appfmt{makeglossaries}.
19258
19259 If the records are reversed:
19260 \begin{codeenv}
19261 \cs{gls}\marg{ap.makeglossaries} and \cs{gls}\marg{cs.makeglossaries}.
19262 \end{codeenv}
19263 then the sort value for \code{cs.makeglossaries} is now considered
19264 the duplicate and the order is reversed: \appfmt{makeglossaries},
19265 \csfmt{makeglossaries}.
19266
19267 Suppose now I modify the \ext{bib} file so that
19268 \code{ap.makeglossaries} is defined as:
19269 \begin{codeenv}
19270 \atentry{entry}\marg{ap.makeglossaries,
19271 \field{name}=\marg{\cmd{application}\marg{makeglossaries}},
19272 \field{category}=\marg{application},
19273 \field{description}=\marg{Perl script (must be used with \cs{gls}\marg{cs.makeglossaries})}
19274 }
19275 \end{codeenv}
19276 and suppose the document only contains an explicit reference to
19277 \code{ap.makeglossaries}:
19278 \begin{codeenv}
19279 \cmd{begin}\marg{document}
19280 \cs{gls}\marg{ap.makeglossaries}
19281 \cs{printunsrtglossaries}
19282 \cmd{end}\marg{document}
19283 \end{codeenv}
19284 Now \code{ap.makeglossaries} is the first entry to be selected
19285 because entries with records are always selected before any
19286 (unrecorded) dependencies. In this case \code{cs.makeglossaries} is
19287 only selected because it's required by \code{ap.makeglossaries}. Now
19288 \code{ap.makeglossaries} is the first to have its sort value
19289 assigned, and it's \code{cs.makeglossaries} that has the duplicate.
19290 This means that the ordering in the glossary is now:
19291 \appfmt{makeglossaries}, \csfmt{makeglossaries}.
19292
19293 An oddity occurs if the glossary is moved to the start of the
19294 document:
19295 \begin{codeenv}
19296 \cmd{begin}\marg{document}
19297 \cs{printunsrtglossaries}
19298 \cs{gls}\marg{ap.makeglossaries}
19299 \cmd{end}\marg{document}
19300 \end{codeenv}
19301 In this case, the first document build:
19302 \begin{verbatim}
19303 pdflatex myDoc
19304 bibgls --group --verbose myDoc
19305 pdflatex myDoc
19306 \end{verbatim}
19307 leads to the ordering described above:
19308 \appfmt{makeglossaries}, \csfmt{makeglossaries}.
19309 However, the next document build has a new record for
19310 \code{cs.makeglossaries} occurring in the glossary (within the
19311 description of \code{ap.makeglossaries}) which means it's now the
19312 first entry to be selected so the ordering switches to:
19313 \csfmt{makeglossaries}, \appfmt{makeglossaries}.
19314 In this type of situation you might be better off with the
19315 \csopt[id]{identical-sort-action} option instead.
19316
19317 Remember that you can temporarily switch off the indexing by locally
19318 setting:
19319 \begin{codeenv*}
19320 \ics{GlsXtrSetDefaultGlsOpts}\marg{\glsopt{noindex}}
19321 \end{codeenv*}
19322 Since the glossary preamble is scoped, you can simply do
19323 \begin{codeenv}
19324 \ics{appto}\ics{glossarypreamble}\marg{\cs{GlsXtrSetDefaultGlsOpts}\marg{\glsopt{noindex}}}
19325 \end{codeenv}
19326 to switch off the indexing within the glossary (or use
19327 \ics{apptoglossarypreamble}). Note that this is
19328 different to using:
19329 \begin{codeenv}
19330 \ics{GlsXtrSetDefaultNumberFormat}\marg{\encap{glsignore}}
19331 \end{codeenv}
19332 which creates an \igls{ignoredrecord}. Even though the record is ignored
19333 (and so won't show in the \gls{locationlist}) the record still influences
19334 the selection order and the record count.
19335
19336 \optsection{sort-suffix-marker}
19337
19338 This automatically implements the dual and secondary settings
19339 \csopt[\meta{value}]{dual-sort-suffix-marker} and
19340 \csopt[\meta{value}]{secondary-sort-suffix-marker}.
19341
19342 If a suffix is appended to the sort value (see above) then it will
19343 be separated by the suffix marker, which can be set with
19344 \csopt[\meta{value}]{sort-suffix-marker} where \meta{value} is the
19345 marker. By default the marker is empty. You can use \stringu\meta{hex}
19346 or \cs{glshex}\meta{hex} to indicate Unicode characters outside the
19347 \idx{ASCII} range. If, for some reason, you want to use a special
19348 character, such as \idx{param}, you will need to precede it with
19349 \ics{cs.string} (for example \code{\cs{cs.string}\idx{param}}) or
19350 use the above hexadecimal markup. If you use \ics{cs.hash} it will
19351 be treated as a literal string containing a backslash followed by a
19352 hash character.
19353
19354 \optsection{encapsulate-sort}
19355
19356 This option will encapsulate the sort value (after modifications such
19357 as \csopt{sort-suffix} and \csopt{sort-number-pad}) with
19358 \csfmt{\meta{csname}}\marg{value}\marg{entry-id} where \meta{value}
19359 is the sort value that would otherwise have been used and
19360 \meta{entry-id} is the entry's label. It will then be interpreted
19361 (if enabled). Note that \meta{value} may already have been
19362 interpreted in a previous step.
19363
19364 \optsection{strength}
19365
19366 This option automatically implements
19367 \csopt[\meta{value}]{dual-strength} and
19368 \csopt[\meta{value}]{secondary-strength}.
19369
19370 The collation strength used by the alphabet sort methods
19371 (\tableref{tab:sortoptionsrule}) can be set to the following values:
19372 \glsdisp{primarycollatorstrength}{\optfmt{primary}} (default),
19373 \glsdisp{secondarycollatorstrength}{\optfmt{secondary}},
19374 \glsdisp{tertiarycollatorstrength}{\optfmt{tertiary}} or
19375 \glsdisp{identicalcollatorstrength}{\optfmt{identical}}. These
19376 indicate the difference between two characters, but the exact
19377 assignment is locale dependent. See the documentation for Java's
19378 \href{http://docs.oracle.com/javase/8/docs/api/java/text/Collator.html}{\code{Collator}
19379 class}~\cite{collator} for further details.
19380
19381 For example, suppose the file \filefmt{entries.bib} contains:
19382 \begin{codeenv}
19383 \atentry{index}\marg{resume}
19384 \atentry{index}\marg{RESUME}
19385 \atentry{index}\marg{resumee, \field{name}=\marg{r\ics{acute}esum\cs{acute}e}}
19386 \atentry{index}\marg{rat}
19387 \atentry{index}\marg{rot}
19388 \atentry{index}\marg{aardvark}
19389 \atentry{index}\marg{zoo}
19390 \end{codeenv}
19391 and the document contains:
19392 \begin{codeenv}
19393 \cmd{documentclass}\marg{article}
19394 \strut
19395 \cmd{usepackage}[\styopt{record}]\marg{glossaries-extra}
19396 \strut
19397 \gls{GlsXtrLoadResources}\oarg{\csopt[en]{sort},\csopt[entries]{src}}
19398 \strut
19399 \cmd{begin}\marg{document}
19400 \cs{gls}\marg{resumee}, \cs{gls}\marg{resume}, \cs{gls}\marg{RESUME},
19401 \cs{gls}\marg{aardvark}, \cs{gls}\marg{rat}, \cs{gls}\marg{rot}, \cs{gls}\marg{zoo}.
19402 \strut
19403 \cs{printunsrtglossaries}
19404 \cmd{end}\marg{document}
19405 \end{codeenv}
19406 then this uses the default \csopt[primary]{strength}, so the entries
19407 are listed as aardvark, rat, r\'esum\'e, resume, RESUME, rot, zoo.
19408
19409 If the strength is changed to \optfmt{secondary}:
19410 \begin{codeenv}
19411 \gls{GlsXtrLoadResources}\oarg{\csopt[en]{sort},\csopt[entries]{src},\csopt[secondary]{strength}}
19412 \end{codeenv}
19413 then the entries are listed as aardvark, rat, resume, RESUME,
19414 r\'esum\'e, rot, zoo.
19415
19416 If the strength is changed to \optfmt{tertiary} or
19417 \optfmt{identical}, there's no difference from
19418 \csopt[secondary]{strength} for this particular example.
19419
19420 This option is ignored by non-alphabet sorts (such as letter or numeric).
19421
19422 \optsection{decomposition}
19423
19424 This option automatically implements the dual and secondary settings
19425 \csopt[\meta{value}]{dual-decomposition} and
19426 \csopt[\meta{value}]{secondary-decomposition}.
19427
19428 The collation decomposition used by alphabet sort methods
19429 (\tableref{tab:sortoptionsrule}) can be set
19430 to the following values: \optfmt{canonical} (default),
19431 \optfmt{full} or \optfmt{none}. This determines how Unicode composed
19432 characters are handled. The fastest mode is \optfmt{none} but is
19433 only appropriate for languages without accents. The slowest mode is
19434 \optfmt{full} but is the most complete for languages with \idx{non-ASCII}
19435 characters. See the documentation for Java's
19436 \href{http://docs.oracle.com/javase/8/docs/api/java/text/Collator.html}{\code{Collator}
19437 class}~\cite{collator} for further details.
19438 This option is ignored by non-alphabet sorts (such as letter or numeric).
19439
19440 \optsection{letter-number-rule}
19441
19442 This automatically implements the dual and secondary settings
19443 \csopt[\meta{value}]{dual-letter-number-rule}
19444 and
19445 \csopt[\meta{value}]{secondary-letter-number-rule}.
19446
19447 If you use one of the letter-number sort methods
19448 (\tableref{tab:sortoptionsletternumber}), then you can determine the
19449 comparison between a number and letter. The \meta{value} may be
19450 one of:
19451 \begin{itemize}
19452 \item\optfmt{before letter}: numbers are considered less than any
19453 letter.
19454
19455 \item\optfmt{after letter}: numbers are considered greater than any
19456 letter.
19457
19458 \item\optfmt{between}: (default) numbers come between letter cases.
19459 With the \optfmt{letternumber\dhyphen case} sort option, this will put
19460 numbers after \idx{uppercase} and before \idx{lowercase}. This
19461 setting doesn't make much sense with the
19462 \optfmt{letternumber\dhyphen nocase} option but, if used, this will put
19463 numbers before letters. The \optfmt{letternumber\dhyphen upperlower} and
19464 \optfmt{letternumber\dhyphen lowerupper} options are more complicated. See
19465 \sectionref{sec:letternumber} for more detail.
19466
19467 \item\optfmt{first}: numbers are considered less than all
19468 characters (including punctuation and spaces).
19469
19470 \item\optfmt{last}: numbers are considered greater than all
19471 characters (including punctuation and spaces).
19472 \end{itemize}
19473 Note that the reverse sort methods will invert this setting.
19474 Remember also that the case-insensitive letter-number sort methods always
19475 first convert the \field{sort} field to \idx{lowercase}, which means that
19476 if you use one of them then there won't be any \idx{uppercase}
19477 characters.
19478
19479 Use \csopt{letter-number-punc-rule} to determine the relative
19480 position of white space and punctuation.
19481
19482 \optsection{letter-number-punc-rule}
19483
19484 This automatically implements the dual and secondary
19485 \csopt[\meta{value}]{dual-letter-number-punc-rule}
19486 and
19487 \csopt[\meta{value}]{secondary-letter-number-punc-rule}.
19488
19489 If you use one of the letter-number sort methods
19490 (\tableref{tab:sortoptionsletternumber}), then you can determine the
19491 order of white space and punctuation. In this context, punctuation
19492 means any character that's not considered a letter, a number
19493 or white space. This means that characters such as combining marks
19494 are considered punctuation.
19495
19496 The \meta{value} may be one of the following:
19497 \begin{itemize}
19498 \item\optfmt{punc-space-first}: punctuation comes first, followed by
19499 white space (then letters and optionally numbers according to the letter-number
19500 rule);
19501 \item\optfmt{punc-space-last}: punctuation followed by white space
19502 come last (after letters and optionally numbers according to the letter-number
19503 rule);
19504 \item\optfmt{space-punc-first}: white space comes first, followed by
19505 punctuation (then letters and optionally numbers according to the letter-number
19506 rule);
19507 \item\optfmt{space-punc-last}: white space followed by punctuation
19508 come last (after letters and optionally numbers according to the letter-number
19509 rule);
19510 \item\optfmt{space-first-punc-last}: white space comes first
19511 (followed by letters and optionally numbers according to the letter-number
19512 rule) and punctuation comes last;
19513 \item\optfmt{punc-first-space-last}: punctuation comes first
19514 (followed by letters and optionally numbers according to the letter-number
19515 rule) and white space comes last;
19516 \item\optfmt{punc-first-space-zero}: punctuation comes first
19517 (although numbers may come before)
19518 and white space is replaced by the digit~\code{0} (\hex{30});
19519 \item\optfmt{punc-last-space-zero}: punctuation comes last
19520 (although numbers may come after)
19521 and white space is replaced by the digit~\code{0} (\hex{30}).
19522 \item\optfmt{punc-first-space-zero-match-next}: punctuation comes first
19523 (although numbers may come before)
19524 and white space is replaced by the appropriate zero character (see below);
19525 \item\optfmt{punc-last-space-zero-match-next}: punctuation comes last
19526 (although numbers may come after)
19527 and white space is replaced by the appropriate zero character (see below).
19528 \end{itemize}
19529 Remember that the reverse sort methods will invert order governed by this setting.
19530
19531 For the \optfmt{space-zero-match-next} settings, the sort value will
19532 have all spaces replaced with a digit that represents zero. If the
19533 space isn't followed by a digit, the basic Latin \code{0} (\hex{30})
19534 will be used, otherwise \bibgls\ will try to match the zero with the
19535 following digit group. For example, if the space is followed by
19536 \textsuperscript{1} (\hex{B9}) the space will be replaced by
19537 \textsuperscript{0} (\hex{2070}), resulting in the sub-string
19538 \code{\textsuperscript{01}} (\hex{B9} \hex{2070}).
19539
19540 If just the \optfmt{space-zero}
19541 (without the \optfmt{-match-next}) is used then the space will just
19542 be replaced with \code{0} resulting in the sub-string
19543 \code{0\textsuperscript{1}} (\hex{30} \hex{2070}). In this case, the
19544 \code{0} will be distinct from \textsuperscript{1} (rather than
19545 being considered a leading zero). However, for
19546 other numbering systems the \code{0} will be treated as a leading
19547 zero. For example, if the space is followed by the Devanagari digit
19548 one (\hex{0967}) then the sub-string will be \hex{30} \hex{0967} but here the
19549 mixture is allowed to form a number (with a leading zero) as both
19550 characters belong to the Unicode category \idx{numberdecimaldigit}.
19551
19552 This means that the \optfmt{-match-next} settings are only really
19553 needed if the sort string contains the superscript or subscript
19554 digits that don't belong to the \qt{Number, Decimal Digit} category.
19555 The plain \optfmt{space-zero} alternatives are more efficient as
19556 they just perform a simple substitution.
19557
19558 The \texparserlib\ used by \bibgls\ recognises the standard
19559 \LaTeX\ text-mode commands \ics{textsuperscript}\margm{text} and
19560 \ics{textsubscript}\margm{text}
19561 and will use the Unicode superscript or subscript characters if they cover every
19562 character in \meta{text}, otherwise HTML markup is used, but that's
19563 then stripped by \bibgls. This means that:
19564 \begin{codeenv}
19565 C\cs{textsubscript}\marg{10}H\cs{textsubscript}\marg{10}O\cs{textsubscript}\marg{4}
19566 \end{codeenv}
19567 will be converted to:
19568 \code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}} but:
19569 \begin{codeenv}
19570 X\cs{textsubscript}\marg{1, 2}
19571 \end{codeenv}
19572 will be converted to:
19573 \begin{verbatim}
19574 X<sub>1, 2</sub>
19575 \end{verbatim}
19576 which ends up as \code{X1, 2}.
19577
19578
19579 Note that \csopt[first]{letter-number-rule} and
19580 \csopt[last]{letter-number-rule} overrides this option when
19581 comparing a number with white space or punctuation.
19582
19583 \optsection{numeric-sort-pattern}
19584
19585 If you use the custom \csopt[numberformat]{sort} or
19586 \csopt[numberformat-reverse]{sort}, you need to
19587 specify the format pattern with this option where
19588 \meta{value} is a pattern recognised by Java's
19589 \href{http://docs.oracle.com/javase/8/docs/api/java/text/DecimalFormat.html}{\code{java.text.DecimalFormat}}
19590 class~\cite{decimalformat}. You can use \stringu\meta{hex} or
19591 \cs{glshex}\meta{hex} to indicate Unicode characters by their
19592 hexadecimal code. You can also use \ics{cs.hash}, \ics{cs.percent},
19593 \ics{cs.underscore}, \ics{cs.amp}, \ics{cs.openbrace} and
19594 \ics{cs.closebrace} to indicate \idx{hashchar}, \idx{percentchar},
19595 \idx{underscorechar}, \idx{ampchar}, \idx{openbracechar} and
19596 \idx{closebracechar}.
19597
19598 Where the dual or secondary sort uses \optfmt{numberformat}
19599 or \optfmt{numberformat-reverse}, use \csopt{dual-numeric-sort-pattern} for
19600 \csopt{dual-sort} and \csopt{secondary-numeric-sort-pattern}
19601 for \csopt{secondary}.
19602
19603 \optsection{numeric-locale}
19604
19605 If you use any of the locale-sensitive numeric sort methods
19606 described in \sectionref{sec:numerical},
19607 such as \csopt[numeric]{sort}, use this option to set
19608 the locale if the default \gls{resource-locale} isn't appropriate. The value may be:
19609 \begin{itemize}
19610 \item\optfmt{resource}: use the default \gls{resource-locale}, if
19611 set, otherwise assume \optfmt{doc};
19612 \item\optfmt{doc}: use the \gls{document-locale} or, if not set, assume
19613 \csopt[locale]{numeric-locale};
19614 \item\optfmt{locale}: use the \gls{Java-locale} (which is usually
19615 the operating system's locale);
19616 \item\meta{lang-tag}: set to the locale identified by the given
19617 a valid language tag \meta{lang-tag}.
19618 \end{itemize}
19619 Use \csopt{dual-numeric-locale} for
19620 \csopt{dual-sort} and \csopt{secondary-numeric-locale}
19621 for \csopt{secondary}.
19622
19623 \begin{important}
19624 If you use the \csopt{locale} resource option with \csopt[resource]{numeric-locale},
19625 then the \csopt{locale} option must be come before
19626 \csopt{numeric-locale}.
19627 \end{important}
19628
19629 \optsection{date-sort-locale}
19630
19631 If you use a date/time sort method (\tableref{tab:sortoptionsdatetime}),
19632 then you can set the locale used by Java's date-time parser.
19633 The default setting is \csopt[resource]{date-sort-locale}.
19634
19635 The value may be \optfmt{resource} (use the \gls{resource-locale}),
19636 \optfmt{doc} (use the \gls{document-locale}),
19637 \optfmt{locale} (use the \gls{Java-locale}),
19638 or a valid language tag \meta{lang-tag} identifying the locale.
19639
19640 Use \csopt{dual-date-sort-locale} and \csopt{secondary-date-sort-locale}
19641 for the dual and secondary.
19642
19643 \begin{important}
19644 If you use the \csopt{locale} resource option with \csopt[resource]{date-sort-locale},
19645 then the \csopt{locale} option must be come before
19646 \csopt{date-sort-locale}.
19647 \end{important}
19648
19649 \optsection{date-sort-format}
19650
19651 If you use a date/time sort method (\tableref{tab:sortoptionsdatetime}),
19652 then you can set the format used by Java's date-time parser.
19653 If omitted, \csopt[default]{date-sort-format} is assumed.
19654 The \meta{value} may be one of:
19655 \begin{itemize}
19656 \item\optfmt{default}: use the locale's default format.
19657 \item\optfmt{short}: use the locale's short format.
19658 \item\optfmt{medium}: use the locale's medium format.
19659 \item\optfmt{long}: use the locale's long format.
19660 \item\optfmt{full}: use the locale's full format.
19661 \item\meta{pattern}: provide a custom pattern.
19662 This should match the specifications for Java's
19663 \href{http://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html}{\code{SimpleDateFormat}}
19664 class~\cite{simpledateformat}. You may use \stringu\meta{hex} or
19665 \code{\cs{glshex} \meta{hex}} to indicate Unicode characters
19666 or \ics{cs.hash}, \ics{cs.percent}, \ics{cs.underscore}, \ics{cs.amp},
19667 \ics{cs.openbrace} and \ics{cs.closebrace} to indicate
19668 \idx{hashchar}, \idx{percentchar}, \idx{underscorechar},
19669 \idx{ampchar}, \idx{openbracechar} and~\idx{closebracechar}.
19670 \end{itemize}
19671
19672 With the custom setting, if the pattern only contains date (but not
19673 time) information, then it must be used with \csopt[date]{sort}
19674 or \csopt[date-reverse]{sort}. If the pattern only contains time
19675 (but not date) information, then it must be used with
19676 \csopt[time]{sort} or \csopt[time\dhyphen reverse]{sort}. If the pattern
19677 contains date and time information, then it must be used with
19678 \csopt[datetime]{sort} or \csopt[datetime-reverse]{sort}.
19679
19680 For example, suppose each entry provides information about a person
19681 and the \field{user1} field is used to store their date of birth:
19682 \begin{codeenv}
19683 \atentry{entry}\marg{caesar,
19684 \field{name}=\marg{Gaius Julius Caesar},
19685 \field{first}=\marg{Julius Caesar},
19686 \field{text}=\marg{Caesar},
19687 \field{description}=\marg{Roman politician and general},
19688 \field{user1}=\marg{13 July 100 BC}
19689 }
19690 \strut
19691 \atentry{entry}\marg{wellington,
19692 \field{name}=\marg{Arthur Wellesley, 1st Duke of Wellington},
19693 \field{first}=\marg{Arthur Wellesley (Duke of Wellington)},
19694 \field{text}=\marg{Wellington},
19695 \field{description}=\marg{Anglo-Irish soldier and statesman},
19696 \field{user1}=\marg{1 May 1769 AD}
19697 }
19698 \end{codeenv}
19699 Then the entries can be sorted by date of birth using:
19700 \begin{codeenv}
19701 \gls{GlsXtrLoadResources}\oarg{
19702 \csopt[entries]{src},\comment{data in entries.bib}
19703 \csopt[user1]{sort-field},
19704 \csopt[date]{sort},
19705 \csopt[d MMM y G]{date-sort-format}
19706 }
19707 \end{codeenv}
19708
19709 The \code{G} (era) date pattern specifier expects a string, such as
19710 \qt{AD}. It will match \idx{lowercase} forms, such as \qt{ad}, so if you
19711 have \code{\cs{textsc}\marg{ad}} the interpreter will convert this to
19712 \code{ad} (stripping the text-block command). However, in general
19713 it's best to supply a semantic command that ensures that the
19714 interpreted result matches the required format.
19715
19716 For example, if \csfmt{era} is provided with:
19717 \begin{codeenv}
19718 \atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{era}}[1]\marg{\cs{textsc}\marg{\cs{MakeLowercase}\marg{\idx{param}1}}}}}
19719 \end{codeenv}
19720 If the definition is hidden from the interpreter
19721 (\csopt[false]{interpret-preamble}) and the field
19722 value contains \verb|\era{AD}| then the custom command will simply be stripped
19723 leaving \code{AD} which can be matched by \code{G}.
19724
19725 If the definition is picked up by the interpreter then the field
19726 value will contain \code{ad} (from \ics{MakeLowercase}) but this can
19727 be matched by \code{G}, so it isn't a problem.
19728 However, if the definition of \csfmt{era} is changed so that the era label
19729 supplied in the argument is converted to something that doesn't
19730 match \code{G} then the definition should be hidden from the
19731 interpreter.
19732
19733 Here's a complete document that changes the \field{group} fields to use
19734 the year and era:
19735 \begin{codeenv}
19736 \cmd{documentclass}\marg{article}
19737 \strut
19738 \cmd{usepackage}[\styopt{record},\styopt[indexgroup]{style}]\marg{glossaries-extra}
19739 \strut
19740 \cs{newcommand}\marg{\gls{bibglsdategroup}}[7]\marg{\idx{param}1\idx{param}4\idx{param}7}
19741 \cs{newcommand}\marg{\gls{bibglsdategrouptitle}}[7]\marg{\ics{number}\idx{param}1\cs{cs.space}\idx{param}4}
19742 \strut
19743 \gls{GlsXtrLoadResources}\oarg{
19744 \csopt[entries]{src},
19745 \csopt[user1]{sort-field},
19746 \csopt[date]{sort},
19747 \csopt[d MMM y G]{date-sort-format},
19748 \csopt[all]{selection}
19749 }
19750 \strut
19751 \cmd{begin}\marg{document}
19752 \cs{printunsrtglossaries}
19753 \cmd{end}\marg{document}
19754 \end{codeenv}
19755 (The use of \ics{number} strips the leading zero from the year.)
19756
19757 \optsection{group-formation}
19758
19759 If the \field{group} field hasn't been set in
19760 the \ext{bib} file or through options like \csopt{group}, then it is
19761 assigned according to this option's setting during sorting if
19762 \longarg{group} has been used. Permitted values:
19763 \begin{itemize}
19764 \item\optfmt{default}: the group is assigned according to
19765 the sort method's default group formation. This is the default
19766 setting.
19767
19768 \item\optfmt{codepoint}: the group is set to
19769 \format{bibglsunicodegroup}, where the first argument is the first
19770 significant character (converted to \idx{lowercase} and decomposed,
19771 if applicable) of the sort value.
19772
19773 \item\optfmt{unicode category}: the group is set to
19774 \format{bibglsunicodegroup}, where the first argument is the label
19775 identifying the Unicode category of the first significant character
19776 of the sort value. For example, the label \code{Ll} signifies a
19777 \idx!{lowercase} letter and \code{Lu} signifies an \idx!{uppercase}
19778 letter.
19779
19780 \item\optfmt{unicode script}: the group is set to
19781 \format{bibglsunicodegroup}, where the first argument is the
19782 label identifying the Unicode script of the first significant
19783 character of the sort value. For example, the label \code{LATIN}
19784 indicates Latin, \code{GREEK} indicates Greek and \code{COMMON}
19785 indicates common characters (such as mathematical Greek characters
19786 that are often used with non-Greek scripts).
19787
19788 \item\optfmt{unicode category and script}: the group is set to
19789 \format{bibglsunicodegroup}, where the first argument is the
19790 label corresponding to the Unicode category and script of the first
19791 significant character of the sort value. For example, the label
19792 \code{Ll.LATIN} indicates a \idx!{lowercase} Latin letter.
19793 \end{itemize}
19794 This option has no effect with \longarg{no-group} or if no sorting
19795 is applied. Use \csopt{secondary-group-formation} for secondary
19796 sorting and \csopt{dual-group-formation} for dual entries.
19797
19798 \begin{important}
19799 Settings other than the default can cause the groups to become
19800 fragmented, so care is needed if you use this option.
19801 See also \sectionref{sec:logicaldivisions}.
19802 \end{important}
19803
19804
19805 \section{Secondary Glossary}
19806 \label{sec:secondaryopts}
19807
19808 The \gls{secondaryglossary} may only be used with \csopt[define]{action}
19809 (within the same resource set) since it's incompatible with the copy actions.
19810 You may use \csopt{secondary} in the first resource set and a copy
19811 action in a subsequent resource set.
19812
19813 \optsection{secondary}
19814
19815 It may be that you want to display a glossary twice but with a
19816 different order. For example, the first time alphabetically and the
19817 second time by category. One way to do this is to have two
19818 \gls{GlsXtrLoadResources} that both load the same \ext{bib} file with
19819 different \csopt{label-prefix} and \csopt{sort} settings, but this
19820 is only possible with \csopt[all]{selection} or by ensuring you
19821 reference each entry with both label prefixes. Another method is
19822 to use \csopt[copy]{action} but this requires a second resource
19823 command with the same selection criteria.
19824
19825 A simpler method is to use a single \gls{GlsXtrLoadResources}
19826 with the \csopt{secondary} option. The value
19827 (which must be supplied) should be in the format:
19828 \begin{definition}
19829 \meta{sort}:\meta{field}:\meta{type}
19830 \end{definition}
19831 or
19832 \begin{definition}
19833 \meta{sort}:\meta{type}
19834 \end{definition}
19835 If the \meta{field} is omitted, the value of \csopt{sort-field} is
19836 used. Remember that when the \glspl{primaryentry} are sorted, the
19837 \field{sort} field will be set, which means that the \field{sort} fallback field
19838 (see \sectionref{sec:fallbacks}) won't be used in the
19839 \glsdisp{secondaryglossary}{secondary} sort. In
19840 general it's best to supply the field unless one type is sorted and the
19841 other isn't. (The actual sort value obtained by the
19842 \glsdisp{secondaryglossary}{secondary} sort
19843 will be saved in the \field{secondarysort} field in case you require it.)
19844
19845 The value of \meta{sort} is as for \csopt{sort}, but note
19846 that in this case the sort value \optfmt{unsrt} or \optfmt{none}
19847 means to use the same ordering as the \glspl{primaryentry}. For
19848 example, with \csopt[de-CH-1996]{sort},
19849 \csopt[none:copies]{secondary} the \code{copies} list will be
19850 ordered according to \code{de-CH-1996} and not according to the
19851 order in which they were read when the \ext{bib} file or files were
19852 parsed. If \meta{sort} is \optfmt{custom}, then the rule should be
19853 provided with \csopt{secondary-sort-rule}.
19854
19855 This option will copy all the selected entries into the glossary labelled
19856 \meta{type} sorted according to \meta{sort} (using \meta{field} as
19857 the sort value). Note that this \emph{just copies the entry's label}
19858 to the \gls{secondaryglossary} list rather than creating a duplicate entry,
19859 which saves resources but it means that all the fields will be
19860 identical. If you want groups in your glossary, the group
19861 information for the \glspl{secondaryglossary} will be stored in the
19862 internal \field{secondarygroup} field. The \field{group} field will
19863 contain the group for the \gls{primaryglossary}.
19864
19865 In order to switch fields in \ics{printunsrtglossary}, you need at
19866 least v1.21 of \sty{glossaries-extra} which provides
19867 \ics{glsxtrgroupfield} to keep track of the appropriate field label.
19868 If this command is defined, the preamble for the \gls{secondaryglossary}
19869 will be adjusted to locally change the field to
19870 \field{secondarygroup}. With older versions, the group information
19871 in the \gls{secondaryglossary} will be the same as for the
19872 \gls{primaryglossary}.
19873
19874 If the glossary \meta{type} doesn't exist, it will be
19875 defined with \ics{provideignoredglossary*}\margm{type}
19876 even if \longarg{no-provide-glossaries} is set.
19877 Note that if the glossary already exists and contains entries,
19878 the existing entries aren't re-ordered. The new entries are
19879 simply appended to the list.
19880
19881 For example, suppose the \ext{bib} file contains entries like:
19882 \begin{codeenv}
19883 \atentry{entry}\marg{quartz,
19884 \field{name}=\marg{quartz},
19885 \field{description}=\marg{hard mineral consisting of silica},
19886 \field{category}=\marg{mineral}
19887 }
19888 \strut
19889 \atentry{entry}\marg{cabbage,
19890 \field{name}=\marg{cabbage},
19891 \field{description}=\marg{vegetable with thick green or purple leaves},
19892 \field{category}=\marg{vegetable}
19893 }
19894 \strut
19895 \atentry{entry}\marg{waterfowl,
19896 \field{name}=\marg{waterfowl},
19897 \field{description}=\marg{any bird that lives in or about water},
19898 \field{category}=\marg{animal}
19899 }
19900 \end{codeenv}
19901 and the document preamble contains:
19902 \begin{codeenv}
19903 \gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[en-GB]{sort},
19904 \csopt[en-GB:category:topic]{secondary}
19905 }
19906 \end{codeenv}
19907 This sorts the \glspl{primaryentry} according to the default
19908 \csopt{sort-field} and then sorts the entries according
19909 to the \field{category} field and copies this list to
19910 the \code{topic} glossary (which will be provided if not defined.)
19911
19912 The \glsdisp{secondaryglossary}{secondary list} can be displayed
19913 with the hypertargets switched off to prevent duplicates. The
19914 cross-references will link to the \glsdisp{primaryglossary}{original glossary}.
19915
19916 For example:
19917 \begin{codeenv*}
19918 \ics{printunsrtglossary}\oarg{\printglossopt[Summary (alphabetical)]{title}}
19919 \ics{printunsrtglossary}\oarg{\printglossopt[Summary (by topic)]{title},\printglossopt[false]{target}}
19920 \end{codeenv*}
19921
19922 The alternative (or if more than two lists are required) is to
19923 reload the same \ext{bib} file with different label prefixes.
19924 For example, if the entries are stored in \filefmt{entries.bib}:
19925 \begin{codeenv}
19926 \cs{newglossary*}\marg{nosort}\marg{Symbols (Unsorted)}
19927 \cs{newglossary*}\marg{byname}\marg{Symbols (Letter Order)}
19928 \cs{newglossary*}\marg{bydesc}\marg{Symbols (Ordered by Description)}
19929 \cs{newglossary*}\marg{byid}\marg{Symbols (Ordered by Label)}
19930 \strut
19931 \gls{GlsXtrLoadResources}\oarg{
19932 \csopt[entries]{src},\comment{entries.bib}
19933 \csopt[unsrt]{sort},
19934 \csopt[nosort]{type}
19935 }
19936 \strut
19937 \gls{GlsXtrLoadResources}\oarg{
19938 \csopt[entries]{src},\comment{entries.bib}
19939 \csopt[letter-case]{sort},
19940 \csopt[byname]{type},
19941 \csopt[byname.]{label-prefix}
19942 }
19943 \strut
19944 \gls{GlsXtrLoadResources}\oarg{
19945 \csopt[entries]{src},\comment{entries.bib}
19946 \csopt[locale]{sort},
19947 \csopt[description]{sort-field},
19948 \csopt[bydesc]{type},
19949 \csopt[bydesc.]{label-prefix}
19950 }
19951 \strut
19952 \gls{GlsXtrLoadResources}\oarg{
19953 \csopt[entries]{src},\comment{entries.bib}
19954 \csopt[letter]{sort},
19955 \csopt[id]{sort-field},
19956 \csopt[byid]{type},
19957 \csopt[byid.]{label-prefix}
19958 }
19959 \end{codeenv}
19960
19961 \optsection{secondary-match}
19962
19963 Similar to \csopt{match} but determines whether or not to include a
19964 \gls{primaryentry} in the \glsdisp{secondaryglossary}{secondary
19965 list}. The syntax is the same but this option is governed by
19966 \csopt{secondary-match-op} and \csopt{secondary-match-action}. Note
19967 that if an entry hasn't been selected for the
19968 \glsdisp{primaryglossary}{primary list} then it won't be added to
19969 the \glsdisp{secondaryglossary}{secondary list}, regardless of this
19970 setting.
19971
19972 \optsection{secondary-not-match}
19973
19974 Similar to \csopt{not-match} but determines whether or not to
19975 include a \gls{primaryentry} in the
19976 \glsdisp{secondaryglossary}{secondary list}. The syntax is the same
19977 but this option is governed by \csopt{secondary-match-op} and
19978 \csopt{secondary-match-action}. Note that if an entry hasn't been
19979 selected for the \glsdisp{primaryglossary}{primary list} then it
19980 won't be added to the \glsdisp{secondaryglossary}{secondary list},
19981 regardless of this setting.
19982
19983 \optsection{secondary-match-op}
19984
19985 As \csopt{match-op} but for the \glsdisp{secondaryglossary}{secondary list} selection.
19986
19987 \optsection{secondary-match-action}
19988
19989 As \csopt{match-action} but for the \glsdisp{secondaryglossary}{secondary list} selection.
19990
19991 \optsection{secondary-missing-sort-fallback}
19992
19993 As \csopt{missing-sort-fallback} but for
19994 \glsdisp{secondaryglossary}{secondary} sorting.
19995
19996 \optsection{secondary-trim-sort}
19997
19998 As \csopt{trim-sort} but for \glsdisp{secondaryglossary}{secondary} sorting.
19999
20000 \optsection{secondary-sort-replace}
20001
20002 As \csopt{sort-replace} but for \glsdisp{secondaryglossary}{secondary} sorting.
20003
20004 \optsection{secondary-sort-rule}
20005
20006 As \csopt{sort-rule} but for \glsdisp{secondaryglossary}{secondary} custom sorting.
20007
20008 \optsection{secondary-break-at}
20009
20010 As \csopt{break-at} but for \glsdisp{secondaryglossary}{secondary} entries.
20011
20012 \optsection{secondary-break-marker}
20013
20014 As \csopt{break-marker} but for \glsdisp{secondaryglossary}{secondary} entries.
20015
20016 \optsection{secondary-break-at-match}
20017
20018 As \csopt{break-at-match} but for \glsdisp{secondaryglossary}{secondary} entries.
20019
20020 \optsection{secondary-break-at-match-op}
20021
20022 As \csopt{break-at-match-op} but for \glsdisp{secondaryglossary}{secondary} entries.
20023
20024 \optsection{secondary-break-at-not-match}
20025
20026 As \csopt{break-at-not-match} but for \glsdisp{secondaryglossary}{secondary} entries.
20027
20028 \optsection{secondary-sort-number-pad}
20029
20030 As \csopt{sort-number-pad} but for \glsdisp{secondaryglossary}{secondary} entries.
20031
20032 \optsection{secondary-sort-pad-plus}
20033
20034 As \csopt{sort-pad-plus} but for \glsdisp{secondaryglossary}{secondary} entries.
20035
20036 \optsection{secondary-sort-pad-minus}
20037
20038 As \csopt{sort-pad-minus} but for \glsdisp{secondaryglossary}{secondary} entries.
20039
20040 \optsection{secondary-identical-sort-action}
20041
20042 As \csopt{identical-sort-action} but for \glsdisp{secondaryglossary}{secondary} entries.
20043
20044 \optsection{secondary-sort-suffix}
20045
20046 As \csopt{sort-suffix} but for \glsdisp{secondaryglossary}{secondary} entries.
20047
20048 \optsection{secondary-sort-suffix-marker}
20049
20050 As \csopt{sort-suffix-marker} but for \glsdisp{secondaryglossary}{secondary} entries.
20051
20052 \optsection{secondary-strength}
20053
20054 As \csopt{strength} but for \glsdisp{secondaryglossary}{secondary} entries.
20055
20056 \optsection{secondary-decomposition}
20057
20058 As \csopt{decomposition} but for \glsdisp{secondaryglossary}{secondary} entries.
20059
20060 \optsection{secondary-letter-number-rule}
20061
20062 As \csopt{letter-number-rule} but for \glsdisp{secondaryglossary}{secondary} letter-number sorting.
20063
20064 \optsection{secondary-letter-number-punc-rule}
20065
20066 As \csopt{letter-number-punc-rule} but for \glsdisp{secondaryglossary}{secondary} letter-number sorting.
20067
20068 \optsection{secondary-numeric-sort-pattern}
20069
20070 As \csopt{numeric-sort-pattern} but for \glsdisp{secondaryglossary}{secondary}
20071 locale-sensitive numeric sorting.
20072
20073 \optsection{secondary-numeric-locale}
20074
20075 As \csopt{numeric-locale} but for \glsdisp{secondaryglossary}{secondary}
20076 locale-sensitive numeric sorting.
20077
20078 \optsection{secondary-date-sort-locale}
20079
20080 As \csopt{date-sort-locale} but for \glsdisp{secondaryglossary}{secondary} date-time sorting.
20081
20082 \optsection{secondary-date-sort-format}
20083
20084 As \csopt{date-sort-format} but for \glsdisp{secondaryglossary}{secondary} date-time sorting.
20085
20086 \optsection{secondary-group-formation}
20087
20088 As \csopt{group-formation} but for \glsdisp{secondaryglossary}{secondary} sorting.
20089
20090 \section{Dual Entries}
20091 \label{sec:dualopts}
20092
20093 \subsection{General Dual Settings}
20094 \label{sec:dualoptsgeneral}
20095
20096 \optsection[\subsubsection]{dual-prefix}
20097
20098 This option indicates the prefix to use for the \glspl{dualentry}. The
20099 default value is \idprefix{dual} (including the terminating period).
20100 Any references to dual entries within the \ext{bib} file should use
20101 the prefix \idprefix{dual} which will be replaced by \meta{value}
20102 when the \ext{bib} file is parsed.
20103
20104 As from version 1.8, the dual label prefix is identified
20105 in the \ext{glstex} file with:
20106 \begin{codeenv}
20107 \format{bibglsdualprefixlabel}
20108 \end{codeenv}
20109
20110 \optsection[\subsubsection]{primary-dual-dependency}
20111
20112 This is a boolean setting that determines whether or not \primary\ and
20113 \dual\ entries should be considered mutual dependencies. The default value is
20114 \csopt[true]{primary-dual-dependency}, which means that if a
20115 \primary\ has records then the \dual\ is added as a dependency and vice versa.
20116 The setting \csopt[false]{primary-dual-dependency} can't be used
20117 with \csopt[none]{dual-sort} or \csopt[use]{dual-sort} (but may be
20118 used with \csopt[combine]{dual-sort} and \csopt[none]{sort} or
20119 \csopt[use]{sort}).
20120
20121 \optsection[\subsubsection]{combine-dual-locations}
20122
20123 This setting allows the \glspl{locationlist} for each \gls{primaryentry}
20124 to be merged with that of the corresponding \gls{dualentry}.
20125 The \meta{value} may be one of:
20126 \begin{itemize}
20127 \item\optfmt{false} This is the default setting. The
20128 \glspl{locationlist} aren't combined.
20129
20130 \item\optfmt{both} Both the \primary\ and \dual\ are given the combined
20131 \gls{locationlist}.
20132
20133 \item\optfmt{dual} Only the \dual\ is given the combined
20134 \gls{locationlist}. The \glsdisp{primaryentry}{primary's} location list is emptied.
20135
20136 \item\optfmt{primary} Only the \primary\ is given the combined
20137 \gls{locationlist}. The \glsdisp{dualentry}{dual's}
20138 \gls{locationlist} is emptied.
20139
20140 \item\optfmt{dual retain principal} Like \optfmt{dual} but any
20141 \glspl{principallocation} for \glspl{primaryentry} will have a copy left in the
20142 \gls{primaryentry}['s] \igls{locationlist}.
20143 \item\optfmt{primary retain principal} Like \optfmt{primary} but any
20144 \glspl{principallocation} for \glspl{dualentry} will have a copy left in the
20145 \gls{dualentry}['s] \igls{locationlist}.
20146 \end{itemize}
20147
20148 For example, suppose the file \filefmt{entries.bib} contains:
20149 \begin{codeenv}
20150 \atentry{dualindexentry}\marg{array,
20151 \field{description}=\marg{ordered list of values}
20152 }
20153 \strut
20154 \atentry{dualindexentry}\marg{vector,
20155 \field{name}=\marg{vector},
20156 \field{description}=\marg{column or row of values}
20157 }
20158 \strut
20159 \atentry{dualindexentry}\marg{set,
20160 \field{description}=\marg{collection of values}
20161 }
20162 \strut
20163 \atentry{dualindexentry}\marg{matrix,
20164 \field{plural}=\marg{matrices},
20165 \field{description}=\marg{rectangular array of values}
20166 }
20167 \end{codeenv}
20168 and the document contains:
20169 \begin{codeenv}
20170 \cmd{documentclass}\marg{article}
20171 \strut
20172 \cmd{usepackage}[colorlinks]\marg{hyperref}
20173 \cmd{usepackage}[\styopt{record},\styopt{index},\styopt[indexgroup]{style}]\marg{glossaries-extra}
20174 \strut
20175 \gls{GlsXtrLoadResources}\oarg{
20176 \csopt[entries]{src},
20177 \csopt[index]{type},
20178 \csopt[idx.]{label-prefix},
20179 \csopt[gls.]{dual-prefix},
20180 \csopt[main]{dual-type}
20181 }
20182 \strut
20183 \cmd{begin}\marg{document}
20184 \cs{gls}\marg{gls.array}, \cs{gls}\marg{gls.vector}, \cs{gls}\marg{gls.set}, \cs{gls}\marg{gls.matrix}.
20185 \strut
20186 \cmd{newpage}
20187 \cs{gls}\marg{gls.array}, \cs{gls}\marg{idx.vector}, \cs{gls}\marg{idx.set}, \cs{gls}\marg{gls.matrix}.
20188 \strut
20189 \cmd{newpage}
20190 \cs{gls}\marg{gls.array}, \cs{gls}\marg{gls.vector}, \cs{gls}\marg{gls.set}, \cs{gls}\marg{gls.matrix}.
20191 \strut
20192 \cs{printunsrtglossaries}
20193 \cmd{end}\marg{document}
20194 \end{codeenv}
20195 In this case, the \glspl{primaryentry} are placed in the \code{index}
20196 glossary type and are assigned the prefix \idprefixfmt{idx} but only
20197 two of the \glspl{primaryentry} have been used in the document (both on
20198 page~2).
20199
20200 The \glspl{dualentry} are assigned the prefix \idprefixfmt{gls} and are
20201 placed in the \mainglossary. The \code{gls.array}
20202 and \code{gls.matrix} entries have been indexed on pages~1, 2 and~3.
20203 The \code{gls.vector} and \code{gls.set} entries have been indexed
20204 on pages~1 and~3.
20205
20206 With the default setting, some of the \glspl{location} are in the
20207 \mainglossary\ (corresponding to \code{\cs{gls}\marg{gls.array}},
20208 \code{\cs{gls}\marg{gls.vector}}, \code{\cs{gls}\marg{gls.set}} and
20209 \code{\cs{gls}\marg{gls.matrix}}) and some of the \glspl{location} are in the
20210 \code{index} glossary (corresponding to \code{\cs{gls}\marg{idx.vector}}
20211 and \code{\cs{gls}\marg{idx.set}}).
20212
20213 If the option \csopt[primary]{combine-dual-locations} is added to
20214 the resource set, then all the \glspl{location} are moved to the
20215 \code{index} glossary. The entries in the \mainglossary\ no longer
20216 have \glspl{location}. This is actually preferable for this type of
20217 document and it's best not to reference the \primary\ (index)
20218 entries as the hyperlink created by \ics{gls} will point to the
20219 index, but these entries don't have descriptions, so it's less
20220 useful than referencing the \dual\ (\code{main}) entries as then the
20221 hyperlink can point to the definition in the \mainglossary.
20222
20223
20224 \subsection{Dual Fields}
20225 \label{sec:dualoptsfields}
20226
20227 \optsection[\subsubsection]{dual-type}
20228
20229 This option sets the \field{type} field for all \glspl{dualentry}.
20230 (The \glspl{primaryentry} obey the \csopt{type} option.) This
20231 will override any value of \field{type} provided in the \ext{bib}
20232 file (or created through a mapping). The \meta{value} is required and
20233 should be one of:
20234 \begin{itemize}
20235 \item \optfmt{false}: switches off this setting (default);
20236
20237 \item \optfmt{same as entry}: sets the \field{type} to the
20238 \gls{entrytype} (\idx!{lowercase} and without
20239 the initial \code{@}). For example, if the entry was defined with
20240 \atentry{dualentry}, the \field{type} will be set to
20241 \optfmt{dualentry}.
20242 If you've used \csopt{entry-type-aliases}, this refers to the target
20243 \gls{entrytype} not the original \gls{entrytype} provided in the \ext{bib}
20244 file.
20245
20246 \item \optfmt{same as original entry}: set the \field{type} field
20247 to the original \gls{entrytype} (\idx!{lowercase} and without
20248 the initial \code{@}) before it was aliased (behaves like
20249 \optfmt{same as entry} if the \gls{entrytype} wasn't aliased).
20250
20251 \item \optfmt{same as base}: sets the \field{type} to the base name
20252 of the \ext{bib} file (without the extension) that provided the
20253 entry definition (new to v1.1);
20254
20255 \item \optfmt{same as primary}: sets the \field{type} to the same as
20256 the corresponding \gls{primaryentry}['s] \field{type} (which may have been
20257 set with \csopt{type}). If the \gls{primaryentry} doesn't have the
20258 \field{type} field set, the \glsdisp{dualentry}{dual's} \field{type} will remain
20259 unchanged.
20260
20261 \item \optfmt{same as parent}: sets the \field{type} to the same as
20262 the entry's \parent\ (new to v1.9). If the entry doesn't have a
20263 \parent\ or if the \parent\ doesn't have the \field{type} field set,
20264 then no change is made.
20265
20266 \item \optfmt{same as category} set the \field{type} field
20267 to the same value as the \field{category} field
20268 (\field{type} unchanged if \field{category} not set);
20269
20270 \item \meta{label}: sets the \field{type} field to \meta{label}.
20271 \end{itemize}
20272
20273 Remember that the glossary with that label must have already
20274 been defined (see \sectionref{sec:newglossary}).
20275 For example:
20276 \begin{codeenv}
20277 \cs{newglossary*}\marg{english}\marg{English}
20278 \cs{newglossary*}\marg{french}\marg{French}
20279 \strut
20280 \gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[en]{sort},\csopt[fr]{dual-sort},
20281 \csopt[english]{type},
20282 \csopt[french]{dual-type}}
20283 \end{codeenv}
20284 Alternatively:
20285 \begin{codeenv}
20286 \cs{newglossary*}\marg{dictionary}\marg{Dictionary}
20287 \strut
20288 \gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[en]{sort},\csopt[fr]{dual-sort},
20289 \csopt[dictionary]{type},
20290 \csopt[same as primary]{dual-type}}
20291 \end{codeenv}
20292
20293 \optsection[\subsubsection]{dual-category}
20294
20295 This option sets the \field{category} field for all
20296 \glspl{dualentry}. (The \glspl{primaryentry} obey the \csopt{category} option.) This
20297 will override any value of \field{category} provided in the \ext{bib}
20298 file (or created through a mapping). The \meta{value} may be empty or
20299 one of:
20300 \begin{itemize}
20301 \item \optfmt{false}: switch off this setting (default);
20302 \item \optfmt{same as entry}: sets the \field{category} to the
20303 \gls{entrytype} (\idx{lowercase} and without
20304 the initial \code{@}). For example, if the entry was defined with
20305 \atentry{dualentry}, the \field{category} will be set to
20306 \optfmt{dualentry}.
20307 If you've used \csopt{entry-type-aliases}, this refers to the target
20308 \gls{entrytype} not the original \gls{entrytype} provided in the \ext{bib}
20309 file.
20310
20311 \item \optfmt{same as original entry}: set the \field{category} field
20312 to the original \gls{entrytype} (\idx{lowercase} and without
20313 the initial \code{@}) before it was aliased (behaves like
20314 \optfmt{same as entry} if the \gls{entrytype} wasn't aliased).
20315
20316 \item \optfmt{same as base}: sets the \field{category} to the base
20317 name of the \ext{bib} file (without the extension) that provided the
20318 entry definition (new to v1.1);
20319
20320 \item \optfmt{same as primary}: sets the \field{category} to the
20321 same as the corresponding \gls{primaryentry}['s] \field{category} (which
20322 may have been set with \csopt{category}). If the \gls{primaryentry}
20323 doesn't have the \field{category} field set, the \glsdisp{dualentry}{dual's}
20324 \field{category} will remain unchanged.
20325
20326 \item \optfmt{same as type}: sets the \field{category} to the same
20327 as the value of the entry's \field{type} field (which may have been
20328 set with \csopt{dual-type}). If the entry doesn't have the
20329 \field{type} field set, the \field{category} will remain unchanged.
20330
20331 \item \meta{label}: sets the \field{category} field to \meta{label}.
20332 \end{itemize}
20333
20334 \optsection[\subsubsection]{dual-counter}
20335
20336 As \csopt{counter} but for the \glspl{dualentry}. In this case
20337 \meta{value} may be the name of the counter or
20338 \optfmt{same as primary} which uses the counter for the
20339 \gls{primaryentry} or \optfmt{false} to switch off this setting.
20340
20341 \optsection[\subsubsection]{dual-short-case-change}
20342
20343 As \csopt{short-case-change} but applies to the \field{dualshort}
20344 field instead.
20345
20346 \optsection[\subsubsection]{dual-long-case-change}
20347
20348 As \csopt{long-case-change} but applies to the \field{duallong}
20349 field instead.
20350
20351 \optsection[\subsubsection]{dual-field}
20352
20353 If this option is used, this will add \ics{glsxtrprovidestoragekey}
20354 to the start of the \iext{glstex} file providing the key given by
20355 \meta{value}. Any entries defined using a dual \gls{entrytype}, such as
20356 \atentry{dualentry}, will be written to the \ext{glstex} file with
20357 an extra field called \meta{value} that is set to the mirror entry.
20358 If \meta{value} is omitted \csopt[dual]{dual-field} is assumed. If
20359 you use a different value, you will need to redefine
20360 \gls{GlsXtrDualField} (either locally or globally).
20361 A value of \code{false} will switch off this setting (the default).
20362
20363 For example, if the \ext{bib} file contains:
20364 \begin{codeenv}
20365 \atentry{dualentry}\marg{child,
20366 \field{name}=\marg{child},
20367 \field{plural}=\marg{children},
20368 \field{description}=\marg{enfant}
20369 }
20370 \end{codeenv}
20371 Then with \csopt[dual]{dual-field} (or simply \csopt{dual-field}
20372 without a value) this will first add the line:
20373 \begin{codeenv}
20374 \cs{glsxtrprovidestoragekey}\marg{\field{dual}}\marg{}\marg{}
20375 \end{codeenv}
20376 at the start of the file and will include the line:
20377 \begin{codeenv*}
20378 \field{dual}=\marg{dual.child},
20379 \end{codeenv*}
20380 for the \gls{primaryentry} (\code{child}) and the line:
20381 \begin{codeenv}
20382 \field{dual}=\marg{child},
20383 \end{codeenv}
20384 for the \gls{dualentry} (\code{dual.child}). It's then possible to
20385 reference one entry from the other. For example, the post-description
20386 hook could contain:
20387 \begin{codeenv}
20388 \cs{ifglshasfield}\marg{\field{dual}}\marg{\cs{glscurrententrylabel}}
20389 \marg{\comment{}
20390 \cs{space}
20391 (\cs{glshyperlink}\marg{\cs{glscurrentfieldvalue}})\comment{}
20392 }\comment{}
20393 \marg{}\comment{}
20394 \end{codeenv}
20395 Note that this new field won't be available for use within the
20396 \iext{bib} file (unless it was previously defined in the document
20397 before \gls!{GlsXtrLoadResources}).
20398
20399 \optsection[\subsubsection]{dual-date-time-field-format}
20400
20401 As \csopt{date-time-field-format} but is used for \glspl{dualentry}.
20402
20403 \optsection[\subsubsection]{dual-date-field-format}
20404
20405 As \csopt{date-field-format} but is used for \glspl{dualentry}.
20406
20407 \optsection[\subsubsection]{dual-time-field-format}
20408
20409 As \csopt{time-field-format} but is used for \glspl{dualentry}.
20410
20411 \optsection[\subsubsection]{dual-date-time-field-locale}
20412
20413 As \csopt{date-time-field-locale} but is used for \glspl{dualentry}.
20414
20415 \optsection[\subsubsection]{dual-date-field-locale}
20416
20417 As \csopt{date-field-locale} but is used for \glspl{dualentry}.
20418
20419 \optsection[\subsubsection]{dual-time-field-locale}
20420
20421 As \csopt{time-field-locale} but is used for \glspl{dualentry}.
20422
20423 \subsection{Dual Sorting}
20424 \label{sec:dualoptssort}
20425
20426 \optsection[\subsubsection]{dual-sort}
20427
20428 This option indicates how to sort the \glspl{dualentry}.
20429 The \glspl{primaryentry} are sorted with the normal entries according to
20430 \csopt{sort}, and the \glspl{dualentry} are sorted according to
20431 \csopt{dual-sort} unless \csopt[combine]{dual-sort} in which case the
20432 \glspl{dualentry} will be combined with the \glspl{primaryentry} and all the
20433 entries will be sorted together according to the \csopt{sort} option.
20434
20435 If \meta{value} isn't set to \optfmt{combine} then the
20436 \glspl{dualentry} are sorted separately according to \meta{value} (as per
20437 \csopt{sort}) and the \glspl{dualentry} will be appended at the end of
20438 the \iext{glstex} file. The field used by the comparator is given by
20439 \csopt{dual-sort-field}.
20440 If \csopt[custom]{dual-sort}, then the \glspl{dualentry} are sorted according to the
20441 rule provided by \csopt{dual-sort-rule}.
20442
20443 For example:
20444 \begin{codeenv}
20445 \gls{GlsXtrLoadResources}\oarg{
20446 \csopt[entries-dual]{src},
20447 \csopt[en]{sort},
20448 \csopt[de-CH-1996]{dual-sort}
20449 }
20450 \end{codeenv}
20451 This will sort the \glspl{primaryentry} according to \optfmt{en}
20452 (English) and the \glspl{secondaryentry} according to \optfmt{de-CH-1996}
20453 (Swiss German new orthography) whereas:
20454 \begin{codeenv}
20455 \gls{GlsXtrLoadResources}\oarg{
20456 \csopt[entries-dual]{src},
20457 \csopt[en-GB]{sort},
20458 \csopt[combine]{dual-sort}
20459 }
20460 \end{codeenv}
20461 will combine the dual entries with the \glspl{primaryentry} and sort them
20462 all according to the \optfmt{en-GB} locale (British English).
20463
20464 If not set, \csopt{dual-sort} defaults to \optfmt{combine}. If
20465 \meta{value} is omitted, \optfmt{resource} is assumed.
20466
20467 \optsection[\subsubsection]{dual-sort-field}
20468
20469 This option indicates the field to use when sorting dual entries
20470 (when they haven't been combined with the \glspl{primaryentry}). The
20471 default value is the same as the \csopt{sort-field} value.
20472
20473 \optsection[\subsubsection]{dual-missing-sort-fallback}
20474
20475 As \csopt{missing-sort-fallback} but for \dual\ sorting.
20476
20477 \optsection[\subsubsection]{dual-trim-sort}
20478
20479 As \csopt{trim-sort} but for \dual\ sorting.
20480
20481 \optsection[\subsubsection]{dual-sort-replace}
20482
20483 As \csopt{sort-replace} but for \dual\ sorting.
20484
20485 \optsection[\subsubsection]{dual-sort-rule}
20486
20487 As \csopt{sort-rule} but for \csopt[custom]{dual-sort}.
20488
20489 \optsection[\subsubsection]{dual-break-at}
20490
20491 As \csopt{break-at} but for \glspl{dualentry}.
20492
20493 \optsection[\subsubsection]{dual-break-marker}
20494
20495 As \csopt{break-marker} but for \glspl{dualentry}.
20496
20497 \optsection[\subsubsection]{dual-break-at-match}
20498
20499 As \csopt{break-at-match} but for \glspl{dualentry}.
20500
20501 \optsection[\subsubsection]{dual-break-at-match-op}
20502
20503 As \csopt{break-at-match-op} but for \glspl{dualentry}.
20504
20505 \optsection[\subsubsection]{dual-break-at-not-match}
20506
20507 As \csopt{break-at-not-match} but for \glspl{dualentry}.
20508
20509 \optsection[\subsubsection]{dual-sort-number-pad}
20510
20511 As \csopt{sort-number-pad} but for \glspl{dualentry}.
20512
20513 \optsection[\subsubsection]{dual-sort-pad-plus}
20514
20515 As \csopt{sort-pad-plus} but for \glspl{dualentry}.
20516
20517 \optsection[\subsubsection]{dual-sort-pad-minus}
20518
20519 As \csopt{sort-pad-minus} but for \glspl{dualentry}.
20520
20521 \optsection[\subsubsection]{dual-identical-sort-action}
20522
20523 As \csopt{identical-sort-action} but for \glspl{dualentry}.
20524
20525 \optsection[\subsubsection]{dual-sort-suffix}
20526
20527 As \csopt{sort-suffix} but for \glspl{dualentry}.
20528
20529 \optsection[\subsubsection]{dual-sort-suffix-marker}
20530
20531 As \csopt{sort-suffix-marker} but for \glspl{dualentry}.
20532
20533 \optsection[\subsubsection]{dual-strength}
20534
20535 As \csopt{strength} but for \glspl{dualentry}.
20536
20537 \optsection[\subsubsection]{dual-decomposition}
20538
20539 As \csopt{decomposition} but for \glspl{dualentry}.
20540
20541 \optsection[\subsubsection]{dual-letter-number-rule}
20542
20543 As \csopt{letter-number-rule} but for \glspl{dualentry} that use a
20544 letter-number sort.
20545
20546 \optsection[\subsubsection]{dual-letter-number-punc-rule}
20547
20548 As \csopt{letter-number-punc-rule} but for \glspl{dualentry} that use a
20549 letter-number sort.
20550
20551 \optsection[\subsubsection]{dual-numeric-sort-pattern}
20552
20553 As \csopt{numeric-sort-pattern} but for \glspl{dualentry} that use a
20554 locale-sensitive numeric sort.
20555
20556 \optsection[\subsubsection]{dual-numeric-locale}
20557
20558 As \csopt{numeric-locale} but for \glspl{dualentry} that use a
20559 locale-sensitive numeric sort.
20560
20561 \optsection[\subsubsection]{dual-date-sort-locale}
20562
20563 As \csopt{date-sort-locale} but for \glspl{dualentry} that
20564 use a date/time sort.
20565
20566 \optsection[\subsubsection]{dual-date-sort-format}
20567
20568 As \csopt{date-sort-format} but for \glspl{dualentry} that
20569 use a date/time sort.
20570
20571 \optsection[\subsubsection]{dual-group-formation}
20572
20573 As \csopt{group-formation} but for \dual\ sorting.
20574
20575
20576 \subsection{Dual Mappings}
20577 \label{sec:dualoptsmap}
20578
20579 \optsection[\subsubsection]{dual-entry-map}
20580
20581 This setting governs the behaviour of \atentry{dualentry}
20582 definitions. The value consists of two comma-separated lists of
20583 equal length identifying the field mapping used to create the
20584 \gls{dualentry} from the \primary\ one. Note that the \field{alias} field
20585 can't be mapped.
20586
20587 The default setting is:
20588 \begin{codeenv}
20589 \csopt[
20590 \marg{\field{name},\field{plural},\field{description},\field{descriptionplural}},
20591 \marg{\field{description},\field{descriptionplural},\field{name},\field{plural}}
20592 ]{dual-entry-map}
20593 \end{codeenv}
20594 The \gls{dualentry} is created by copying the value of the field in the
20595 first list \meta{list1} to the field in the corresponding place in the second
20596 list \meta{list2}. Any additional fields are copied over to the same
20597 field.
20598 For example:
20599 \begin{codeenv}
20600 \atentry{dualentry}\marg{cat,
20601 \field{name}=\marg{cat},
20602 \field{description}=\marg{chat},
20603 \field{see}=\marg{dog}
20604 }
20605 \end{codeenv}
20606 defines two entries. The \gls{primaryentry} is essentially like:
20607 \begin{codeenv}
20608 \atentry{entry}\marg{cat,
20609 \field{name}=\marg{cat},
20610 \field{plural}=\marg{cat\cs{glspluralsuffix} },
20611 \field{description}=\marg{chat},
20612 \field{descriptionplural}=\marg{chat\cs{glspluralsuffix} },
20613 \field{see}=\marg{dog}
20614 }
20615 \end{codeenv}
20616 and the \gls{dualentry} is essentially like:
20617 \begin{codeenv}
20618 \atentry{entry}\marg{dual.cat,
20619 \field{description}=\marg{cat},
20620 \field{descriptionplural}=\marg{cat\cs{glspluralsuffix} },
20621 \field{name}=\marg{chat},
20622 \field{plural}=\marg{chat\cs{glspluralsuffix} },
20623 \field{see}=\marg{dog}
20624 }
20625 \end{codeenv}
20626 (except they're defined using \gls{bibglsnewdualentry} instead of
20627 \gls{bibglsnewentry}, and each is considered dependent on the other.)
20628
20629 The \field{see} field isn't listed in \csopt{dual-entry-map} so its
20630 value is simply copied directly over to the \field{see} field in the
20631 dual entry. Note that the missing \field{plural} and
20632 \field{descriptionplural} fields have been filled in using their
20633 fallback values (see \sectionref{sec:fallbacks}).
20634
20635 In general \bibgls\ doesn't try to supply missing fields, but in the
20636 dual entry cases it needs to do this for the mapped fields. This is
20637 because the shuffled fields might have different default values from
20638 the \styfmt{glossaries-extra} package's point of view. For example,
20639 \gls{longnewglossaryentry} doesn't provide a default for
20640 \field{descriptionplural} if it hasn't been set.
20641
20642 \optsection[\subsubsection]{dual-abbrv-map}
20643
20644 This is like \csopt{dual-entry-map} but applies to
20645 \atentry{dualabbreviation} rather than \atentry{dualentry}.
20646 Note that the \field{alias} field can't be mapped. The
20647 default setting is:
20648 \begin{codeenv}
20649 \csopt[
20650 \marg{\field{short},\field{shortplural},\field{long},\field{longplural},\field{dualshort},\field{dualshortplural},
20651 \field{duallong},\field{duallongplural}},
20652 \marg{\field{dualshort},\field{dualshortplural},\field{duallong},\field{duallongplural},\field{short},\field{shortplural},
20653 \field{long},\field{longplural}}
20654 ]{dual-abbrv-map}
20655 \end{codeenv}
20656
20657 This essentially flips the \field{short} field with the
20658 \field{dualshort} field and the \field{long} field with the
20659 \field{duallong} field. See \atentry{dualabbreviation}
20660 for further details.
20661
20662 \optsection[\subsubsection]{dual-abbrventry-map}
20663
20664 This is like \csopt{dual-entry-map} but applies to
20665 \atentry{dualabbreviationentry} rather than \atentry{dualentry}.
20666 Note that the \field{alias} field can't be mapped. The
20667 default setting is:
20668 \begin{codeenv}
20669 \csopt[
20670 \marg{\field{long},\field{short},\field{shortplural}},
20671 \marg{\field{name},\field{text},\field{plural}}
20672 ]{dual-abbrventry-map}
20673 \end{codeenv}
20674 See \atentry{dualabbreviationentry} for further details.
20675
20676
20677 \optsection[\subsubsection]{dual-symbol-map}
20678
20679 This is like \csopt{dual-entry-map} but applies to
20680 \atentry{dualsymbol} rather than \atentry{dualentry}.
20681 Note that the \field{alias} field can't be mapped. The
20682 default setting is:
20683 \begin{codeenv}
20684 \csopt[
20685 \marg{\field{name},\field{plural},\field{symbol},\field{symbolplural}},
20686 \marg{\field{symbol},\field{symbolplural},\field{name},\field{plural}}
20687 ]{dual-symbol-map}
20688 \end{codeenv}
20689 This essentially flips the \field{name} field with the
20690 \field{symbol} field.
20691
20692 \optsection[\subsubsection]{dual-indexentry-map}
20693
20694 This is like \csopt{dual-entry-map} but applies to
20695 \atentry{dualindexentry} rather than \atentry{dualentry}.
20696 The default setting is:
20697 \begin{codeenv}
20698 \csopt[
20699 \marg{\field{name}},
20700 \marg{\field{name}}
20701 ]{dual-indexentry-map}
20702 \end{codeenv}
20703 Note that there must always be at least one pair, even if it's the
20704 same field, since this identifies the field to use for the backlink,
20705 if set.
20706
20707 \optsection[\subsubsection]{dual-indexsymbol-map}
20708
20709 This is like \csopt{dual-entry-map} but applies to both
20710 \atentry{dualindexsymbol} and \atentry{dualindexnumber}.
20711 The default setting is:
20712 \begin{codeenv}
20713 \csopt[
20714 \marg{\field{symbol},\field{name},\field{symbolplural},\field{plural}},
20715 \marg{\field{name},\field{symbol},\field{plural},\field{symbolplural}}
20716 ]{dual-indexsymbol-map}
20717 \end{codeenv}
20718
20719 \optsection[\subsubsection]{dual-indexabbrv-map}
20720
20721 This is like \csopt{dual-entry-map} but applies to both the dual
20722 \atentry{dualindexabbreviation} and tertiary
20723 \atentry{tertiaryindexabbreviationentry} \glspl{entrytype}.
20724 The default setting is:
20725 \begin{codeenv}
20726 \csopt[
20727 \marg{\field{name}},
20728 \marg{\field{name}}
20729 ]{dual-indexabbrv-map}
20730 \end{codeenv}
20731
20732 \subsection{Dual Back-Links}
20733 \label{sec:dualoptsbacklinks}
20734
20735 \optsection[\subsubsection]{dual-entry-backlink}
20736
20737 This is a boolean setting. If \meta{boolean} is missing \optfmt{true}
20738 is assumed.
20739
20740 When used with \atentry{dualentry}, if \meta{boolean} is
20741 \optfmt{true}, this will wrap the contents of the first mapped field
20742 with \gls{bibglshyperlink}. The field is obtained from the first
20743 mapping listed in \csopt{dual-entry-map}.
20744
20745 For example, if the document contains:
20746 \begin{codeenv}
20747 \gls{GlsXtrLoadResources}\oarg{\csopt{dual-entry-backlink},
20748 \csopt[
20749 \marg{\field{name},\field{plural},\field{description},\field{descriptionplural}},
20750 \marg{\field{description},\field{descriptionplural},\field{name},\field{plural}}
20751 ]{dual-entry-map},
20752 \csopt[entries-dual]{src}}
20753 \end{codeenv}
20754 and if the \ext{bib} file contains:
20755 \begin{codeenv}
20756 \atentry{dualentry}\marg{child,
20757 \field{name}=\marg{child},
20758 \field{plural}=\marg{children},
20759 \field{description}=\marg{enfant}
20760 }
20761 \end{codeenv}
20762 Then the definition of the \gls{primaryentry} (\code{child}) in the
20763 \ext{glstex} file will set the \field{description} field to:
20764 \begin{codeenv}
20765 \gls{bibglshyperlink}\marg{enfant}\marg{dual.child}
20766 \end{codeenv}
20767 and the \gls{dualentry} (\code{dual.child}) will have the
20768 \field{description} field set to:
20769 \begin{codeenv}
20770 \gls{bibglshyperlink}\marg{child}\marg{child}
20771 \end{codeenv}
20772 This use of the wrapper \gls{bibglshyperlink} (rather than explicitly
20773 using \ics{glshyperlink}) and inserting the actual field value
20774 (rather than using commands like \ics{glsentryname}) allows it
20775 to work with \ics{makefirstuc} if the field requires a case-change.
20776
20777 The reason the \field{description} field is chosen for the modification is
20778 because the first field listed in \meta{list1} of \csopt{dual-entry-map}
20779 is the \field{name} field which maps to \field{description} (the
20780 first field in the second list \meta{list2}). This means that the hyperlink for
20781 the \gls{dualentry} should be put in the \field{description} field.
20782
20783 For the \gls{primaryentry}, the \field{name} field is looked up in the
20784 second list from the \csopt{dual-entry-map} setting. This is the
20785 third item in this second list, so the third item in the first list
20786 is selected, which also happens to be the \field{description} field,
20787 so the hyperlink for the \gls{primaryentry} is put in the
20788 \field{description} field.
20789
20790 \optsection[\subsubsection]{dual-abbrv-backlink}
20791
20792 This is analogous to \csopt{dual-entry-backlink} but for entries
20793 defined with \atentry{dualabbreviation} instead of
20794 \atentry{dualentry}.
20795
20796 \optsection[\subsubsection]{dual-symbol-backlink}
20797
20798 This is analogous to \csopt{dual-entry-backlink} but for entries
20799 defined with \atentry{dualsymbol} instead of \atentry{dualentry}.
20800
20801 \optsection[\subsubsection]{dual-abbrventry-backlink}
20802
20803 Analogous to \csopt{dual-entry-backlink} but for entries
20804 defined with \atentry{dualabbreviationentry} instead of
20805 \atentry{dualentry}. This setting can be problematic as the
20806 backlinks rely on the relevant field being known to \bibgls.
20807 Since the abbreviation style typically sets the \field{name}
20808 field (and sometimes the \field{description} field as well), you may
20809 find that no backlink appears. A simple workaround is to
20810 use \csopt{dual-field} (or \csopt[dual]{dual-field})
20811 to store the dual label in the \field{dual} field, and then
20812 use a style that checks for this field and adds the backlink.
20813
20814 With \sty{glossaries-extra} v1.30+ you can use:
20815 \nosecdef{GlsXtrDualBackLink}
20816 which encapsulates \meta{text} with a hyperlink to the \dual.
20817 The \meta{label} identifies the entry that requires a backlink.
20818 The \glsdisp{dualentry}{dual's} label is obtained from the field given by:
20819 \nosecdef{GlsXtrDualField}
20820 which defaults to \field{dual}. Note that if you assign a
20821 different field label with \csopt{dual-field}, then you will
20822 need to redefine \gls{GlsXtrDualField} as appropriate.
20823
20824 For example:
20825 \begin{codeenv}
20826 \cs{renewcommand}*\marg{\ics{glsuserdescription}}[2]\marg{\comment{}
20827 \gls{GlsXtrDualBackLink}\marg{\ics{glslonguserfont}\marg{\idx{param}1}}\marg{\idx{param}2}\comment{}
20828 }
20829 \cs{setabbreviationstyle}\marg{\abbrstyle{long-short-user}}
20830 \gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt{dual-field}}
20831 \end{codeenv}
20832
20833 \optsection[\subsubsection]{dual-entryabbrv-backlink}
20834
20835 As \csopt{dual-abbrventry-backlink} but for entries
20836 defined with \atentry{dualentryabbreviation} instead of
20837 \atentry{dualabbreviationentry}.
20838
20839 \optsection[\subsubsection]{dual-indexentry-backlink}
20840
20841 This is analogous to \csopt{dual-entry-backlink} but for entries
20842 defined with \atentry{dualindexentry} instead of
20843 \atentry{dualentry}.
20844
20845 \optsection[\subsubsection]{dual-indexsymbol-backlink}
20846
20847 This is analogous to \csopt{dual-entry-backlink} but for entries
20848 defined with \atentry{dualindexsymbol} and
20849 \atentry{dualindexnumber}.
20850
20851 \optsection[\subsubsection]{dual-indexabbrv-backlink}
20852
20853 This is analogous to \csopt{dual-entry-backlink} but for entries
20854 defined with \atentry{dualindexabbreviation} and
20855 \atentry{tertiaryindexabbreviationentry}.
20856
20857 \optsection[\subsubsection]{dual-backlink}
20858
20859 Shortcut for:
20860 \begin{flushleft}\obeylines
20861 \csopt[\meta{boolean}]{dual-entry-backlink},
20862 \csopt[\meta{boolean}]{dual-abbrventry-backlink},
20863 \csopt[\meta{boolean}]{dual-abbrv-backlink},
20864 \csopt[\meta{boolean}]{dual-symbol-backlink},
20865 \csopt[\meta{boolean}]{dual-indexentry-backlink},
20866 \csopt[\meta{boolean}]{dual-indexsymbol-backlink},
20867 \csopt[\meta{boolean}]{dual-indexabbrv-backlink}
20868 \end{flushleft}
20869
20870 \section{Tertiary Entries}
20871
20872 \optsection{tertiary-prefix}
20873
20874 This option indicates the prefix to use for the \glspl{tertiaryentry}. The
20875 default value is \idprefix{tertiary} (including the terminating period).
20876
20877 As from version 1.8, the \glsdisp{tertiaryentry}{tertiary} label prefix is identified
20878 in the \ext{glstex} file with:
20879 \begin{codeenv}
20880 \format{bibglstertiaryprefixlabel}
20881 \end{codeenv}
20882
20883 \optsection{tertiary-type}
20884
20885 This option indicates that the \glspl{tertiaryentry} should have
20886 their \field{type} field set to \meta{value}. If \meta{value} is
20887 empty the \field{type} is left unchanged. Unlike
20888 the \csopt{type} and \csopt{dual-type} options, there are no
20889 recognised keywords.
20890
20891 \optsection{tertiary-category}
20892
20893 This option indicates that the \glspl{tertiaryentry} should have
20894 their \field{category} field set to \meta{value}. If \meta{value} is
20895 empty the \field{category} is left unchanged. Unlike
20896 the \csopt{category} and \csopt{dual-category} options, there are no
20897 recognised keywords.
20898
20899 \section{Compound (Combined or Multi) Entries}
20900 \label{sec:compoundentries}
20901
20902 These options refer to \glspl{compoundentry} which are either
20903 defined in a \ext{bib} file with \atentry{compoundset} or are
20904 defined in the document using \cs{multiglossaryentry} (or
20905 \cs{provideglossaryentry}). See \sectionref{sec:compoundsetentry}
20906 for further details.
20907
20908 \optsection{compound-options-global}
20909
20910 This is a boolean option. The default is
20911 \csopt[true]{compound-options-global}.
20912
20913 If \optfmt{true}, the \gls{compoundentry} options described in this
20914 section, except for \csopt{compound-write-def}, pick up all
20915 \glspl{compoundentry} provided in the document (defined either with
20916 \atentry{compoundset} or in the document with
20917 \ics{multiglossaryentry}).
20918
20919 If \optfmt{false}, options only apply to \glspl{compoundentry} defined
20920 with \atentry{compoundset} in the current \gls{resourceset}.
20921
20922 If \igls{crossresourceref} are disabled then any instances of
20923 \atentry{compoundset} in subsequent \glspl{resourceset} can only be
20924 picked up from the \ext{aux} file on the next build.
20925
20926 \optsection{compound-dependent}
20927
20928 This is a boolean option. The default is
20929 \csopt[false]{compound-dependent}.
20930
20931 If you have chosen to switch off indexing for the \glspl{compotherlabel}
20932 then they may not be selected (unless they have been indexed via
20933 another method, such as explicitly using \cs{gls}). You can use this
20934 option to make the \glspl{compotherlabel} dependencies of the
20935 \gls{compmainlabel} (if the entry given by \gls{compmainlabel} is
20936 present in the current \gls{resourceset}).
20937
20938 This means that if the \gls{compmainlabel} is selected then the
20939 \glspl{compotherlabel} should also be selected (if dependencies are
20940 part of the selection criteria).
20941
20942 \optsection{compound-add-hierarchy}
20943
20944 This is a boolean option. The default is
20945 \csopt[false]{compound-add-hierarchy}.
20946 If true, this will set the \field{parent} field for each element
20947 $e_i$ to the previous element $e_{i-1}$ in the list, provided that:
20948 \begin{itemize}
20949 \item the element $e_i$ isn't the first element in the list;
20950 \item the element $e_i$ and the previous element $e_{i-1}$ are
20951 present in the current \gls{resourceset};
20952 \item the element $e_i$ doesn't already have the \field{parent} field set;
20953 \item the element $e_i$ isn't an \gls{ancestor} of the previous element $e_{i-1}$.
20954 \item the previous element $e_{i-1}$ isn't an \gls{ancestor} of the
20955 element $e_i$.
20956 \end{itemize}
20957 For example, if the \ext{bib} file contains:
20958 \begin{codeenv}
20959 \atentry{abbreviation}\marg{clostridium,
20960 \field{short}=\marg{C.},
20961 \field{long}=\marg{Clostridium}
20962 }
20963 \atentry{index}\marg{botulinum}
20964 \atentry{compoundset}\marg{cbot,
20965 \field{elements}=\marg{clostridium,botulinum}}
20966 \end{codeenv}
20967 Then the \code{botulinum} entry will have its \field{parent} field
20968 set to \code{clostridium}. The \code{clostridium} entry won't be
20969 adjusted (since it's the first element in the list).
20970
20971 \optsection{compound-has-records}
20972
20973 This option may take one of the following values:
20974 \begin{description}
20975 \item[\optfmt{true}]
20976 Any \gls{compoundentry} referenced with commands like
20977 \ics{mgls} is considered to have \glspl{record} for each element for
20978 selection purposes, even if there are no \glspl{record} in the \ext{aux}
20979 file. (This is useful on the first \LaTeX\ run where the
20980 \glspl{compoundentry} are defined with \atentry{compoundset}.)
20981
20982 \item[\optfmt{false}]
20983 The element \glspl{record} are created as they normally are with
20984 commands like \cs{gls} that are internally used by \cs{mgls}.
20985
20986 \item[\optfmt{default}]
20987 Behaves like \csopt[true]{compound-has-records} if the current
20988 \gls{resourceset} has any \ext{bib} files containing one or more
20989 \atentry{compoundset} \glspl{entrytype}. Otherwise behaves like
20990 \csopt[false]{compound-has-records}.
20991 \end{description}
20992
20993 The default is \csopt[default]{compound-has-records}.
20994 If the value is omitted, \optfmt{true} is assumed.
20995
20996 \optsection{compound-adjust-name}
20997
20998 If an entry has been identified as the \gls{compmainlabel} in any
20999 \glspl{compoundentry} then the \field{name} field can be adjusted
21000 with this option. Allowed values:
21001 \begin{itemize}
21002 \item \optfmt{false} don't adjust the \field{name} field (default);
21003 \item \optfmt{unique} only adjust the \field{name} field if
21004 the entry is the \gls{compmainlabel} of exactly one set;
21005 \item \optfmt{once} adjust the \field{name} field if
21006 the entry is the \gls{compmainlabel} of any set. Only one adjustment
21007 is made. If the entry is the \gls{compmainlabel} of multiple
21008 \glspl{compoundentry} there's no guarantee which set will be chosen
21009 for the adjustment.
21010 \end{itemize}
21011
21012 If the value isn't supplied, \optfmt{once} is assumed. As with
21013 \csopt{name-case-change}, the pre-adjusted \field{name} value will
21014 be copied to the \field{text} field provided the \field{text} field
21015 hasn't already been set and provided that the entry isn't an
21016 abbreviation.
21017
21018 The adjusted value will be in the form:
21019 \begin{codeenv*}
21020 \ics{glsxtrmultientryadjustedname}\margm{sublist1}\margm{name}\margm{sublist2}\marg{mlabel}
21021 \end{codeenv*}
21022 where \meta{label} is the \gls{compoundentry} label, \meta{name} was
21023 the value of the \field{name} field before the adjustment,
21024 \meta{sublist1} is the list of \glspl{compotherlabel} before the
21025 \gls{compmainlabel} (which will be empty if the \gls{compmainlabel}
21026 is the first element in the set) and
21027 \meta{sublist2} is the list of \glspl{compotherlabel} after the
21028 \gls{compmainlabel} (which will be empty if the \gls{compmainlabel}
21029 is the last element in the set).
21030
21031 The adjustment is made before \csopt{name-case-change} (if set).
21032 The control sequence case changes (such as
21033 \csopt[firstuc-cs]{name-case-change}) will replace \cs{glsxtrmultientryadjustedname}
21034 with the relevant command (\ics{Glsxtrmultientryadjustedname} for
21035 \optfmt{firstuc-cs}, \ics{GlsXtrmultientryadjustedname} for
21036 \optfmt{title-cs} and \cs{GLSxtrmultientryadjustedname} for
21037 \optfmt{uc-cs}).
21038
21039 \optsection{compound-main-type}
21040
21041 Set the \field{type} field of the \glslink{compmainlabel}{main
21042 entries}. The \meta{value} is required and should be one of:
21043 \begin{itemize}
21044 \item \optfmt{same as entry}: sets the \field{type} to the
21045 \gls{entrytype} (\idx!{lowercase} and without
21046 the initial \code{@}). For example, if the entry was defined with
21047 \atentry{index}, the \field{type} will be set to \optfmt{index}.
21048 If you've used \csopt{entry-type-aliases}, this refers to the target
21049 \gls{entrytype} not the original \gls{entrytype} provided in the \ext{bib}
21050 file.
21051
21052 \item \optfmt{same as original entry}: set the \field{type} field
21053 to the original \gls{entrytype} (\idx!{lowercase} and without
21054 the initial \code{@}) before it was aliased (behaves like
21055 \optfmt{same as entry} if the \gls{entrytype} wasn't aliased).
21056
21057 \item \optfmt{same as base}: sets the \field{type} to the base name
21058 of the \ext{bib} file (without the extension) that provided the
21059 entry definition;
21060
21061 \item \optfmt{same as category}: sets the \field{type} to the same
21062 as the \field{category} field;
21063
21064 \item \optfmt{same as parent}: sets the \field{type} to the same as
21065 the entry's \parent. If the entry doesn't have a
21066 \parent\ or if the \parent\ doesn't have the \field{type} field set,
21067 then no change is made.
21068
21069 \item \meta{label}: sets the \field{type} field to \meta{label}.
21070 \end{itemize}
21071
21072 This setting is governed by \csopt{compound-type-override}.
21073
21074 \optsection{compound-other-type}
21075
21076 Set the \field{type} field of the \glslink{compotherlabel}{other
21077 entries}. The \meta{value} is required and should be one of:
21078 \begin{itemize}
21079 \item \optfmt{same as main}: sets the \field{type} to the same as
21080 the \glslink{compmainlabel}{main entry}.
21081
21082 \item \optfmt{same as entry}: sets the \field{type} to the
21083 \gls{entrytype} (\idx!{lowercase} and without
21084 the initial \code{@}). For example, if the entry was defined with
21085 \atentry{index}, the \field{type} will be set to \optfmt{index}.
21086 If you've used \csopt{entry-type-aliases}, this refers to the target
21087 \gls{entrytype} not the original \gls{entrytype} provided in the \ext{bib}
21088 file.
21089
21090 \item \optfmt{same as original entry}: set the \field{type} field
21091 to the original \gls{entrytype} (\idx!{lowercase} and without
21092 the initial \code{@}) before it was aliased (behaves like
21093 \optfmt{same as entry} if the \gls{entrytype} wasn't aliased).
21094
21095 \item \optfmt{same as base}: sets the \field{type} to the base name
21096 of the \ext{bib} file (without the extension) that provided the
21097 entry definition;
21098
21099 \item \optfmt{same as category}: sets the \field{type} to the same
21100 as the \field{category} field;
21101
21102 \item \optfmt{same as parent}: sets the \field{type} to the same as
21103 the entry's \parent. If the entry doesn't have a
21104 \parent\ or if the \parent\ doesn't have the \field{type} field set,
21105 then no change is made.
21106
21107 \item \meta{label}: sets the \field{type} field to \meta{label}.
21108 \end{itemize}
21109
21110 This setting is governed by \csopt{compound-type-override}.
21111
21112 \optsection{compound-type-override}
21113
21114 This is a boolean option. The default is
21115 \csopt[false]{compound-type-override}.
21116
21117 If \optfmt{true}, then the options \csopt{compound-main-type}
21118 and \csopt{compound-other-type} will overwrite the \field{type}
21119 field otherwise those options will only set the \field{type} field
21120 if it hasn't already been set.
21121
21122 \optsection{compound-write-def}
21123
21124 If \glspl{compoundentry} are defined in the \ext{bib} files using
21125 \atentry{compoundset}, this option governs whether or not to write
21126 their definition to the \ext{glstex} file. The value may be one of:
21127 \begin{definition}
21128 \item[\optfmt{none}] Don't write the definitions to the \ext{glstex}
21129 file. For example, if you are reloading a \ext{bib} file from
21130 another \gls{resourceset}, you will need this option to prevent
21131 duplicate definitions. (The alternative is to define
21132 \gls{bibglsdefcompoundset} to use \ics{providemultiglossaryentry}
21133 instead of \ics{multiglossaryentry}.)
21134
21135 \item[\optfmt{all}] Write all definitions to the \ext{glstex} file,
21136 regardless of whether or not they have been referenced using
21137 commands like \cs{mgls}.
21138
21139 \item[\optfmt{ref}] Only write the definitions for
21140 \glspl{compoundentry} that have been referenced using commands like
21141 \cs{mgls}. (Default.)
21142 \end{definition}
21143
21144 The \glspl{compoundentry} are defined in the \ext{glstex} file with
21145 \gls{bibglsdefcompoundset}.
21146
21147 \chapter{Provided Commands}
21148 \label{sec:bibglscs}
21149
21150 When \bibgls\ creates the \iext{glstex} file, it writes some
21151 definitions for custom commands in the form \csfmt{bibgls\ldots} which
21152 may be changed as required. The command definitions all use
21153 \ics{providecommand} which means that you can define the command with
21154 \ics{newcommand} before the resource file is loaded.
21155
21156 Note that if you try to redefine any of these commands after the
21157 resource file has been loaded with \ics{renewcommand}, you will get
21158 an error on the first \LaTeX\ run when the \ext{glstex} file doesn't
21159 exist. You may prefer to use \ics{glsrenewcommand} instead, which
21160 will generate a warning instead of an error.
21161
21162 Since many of the commands are actually used within the \ext{glstex}
21163 file, it's best to use \cs{newcommand} before the first
21164 \igls{resourceset} and \cs{renewcommand} between \iglspl{resourceset}
21165 if adjustments are necessary.
21166
21167
21168 \section{Entry Definitions}
21169 \label{sec:newentrydefs}
21170
21171 This section lists the commands (\csfmt{bibglsnew\ldots}) used to
21172 define entries. Note that the entry definition commands are
21173 actually used when \TeX\ inputs the resource file, so redefining
21174 them after the resource file is loaded won't have an effect on the
21175 entries defined in that resource file (but will affect entries defined
21176 in subsequent resource files). Each provided command is defined in
21177 the \ext{glstex} file immediately before the first entry that
21178 requires it, so only the commands that are actually needed are
21179 provided.
21180
21181 The \field{sort} key may be set within the \ext{glstex} entry
21182 definition, but its value is usually not required in the document
21183 unless you are using a hybrid method with \styopt[hybrid]{record}
21184 (in which case, it's redundant to get \bibgls\ to sort).
21185
21186 After each entry is defined, if it has any associated \glspl{location} and
21187 the default \csopt[true]{save-loclist} is set, then the
21188 \glspl{location} are added using:
21189 \nosecformatdef{glsxtrfieldlistadd}
21190 Any additional fields that don't have associated keys are then set (if
21191 required) with \ics{GlsXtrSetField}.
21192
21193 \cssection{bibglsnewentry}
21194
21195 \formatdef{bibglsnewentry}
21196 This command is used to define terms identified with the
21197 \atentry{entry} type. The definition provided in the \ext{glstex}
21198 file is:
21199 \begin{codeenv}
21200 \cs{providecommand}\marg{\gls{bibglsnewentry}}[4]\marg{\comment{}
21201 \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{}
21202 }
21203 \end{codeenv}
21204 This uses the starred form \ics{longnewglossaryentry*} that
21205 doesn't automatically append \ics{nopostdesc} (which interferes with
21206 the post-description hooks provided by category attributes).
21207
21208 \cssection{bibglsnewsymbol}
21209
21210 \formatdef{bibglsnewsymbol}
21211 This command is used to define terms identified with the
21212 \atentry{symbol} type. The definition provided in the \ext{glstex}
21213 file is:
21214 \begin{codeenv}
21215 \cs{providecommand}\marg{\gls{bibglsnewsymbol}}[4]\marg{\comment{}
21216 \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{}
21217 }
21218 \end{codeenv}
21219 Note that this sets the \field{sort} field to the label, but this
21220 may be overridden by the \meta{options} if the \field{sort} field
21221 was supplied or if \bibgls\ has determined the value whilst sorting
21222 the entries.
21223
21224 This also sets the \field{category} to \optfmt{symbol}, but again this may
21225 be overridden by \meta{options} if the entry had the \field{category}
21226 field set in the \ext{bib} file or if the \field{category} was
21227 overridden with \csopt[\meta{value}]{category}.
21228
21229 \cssection{bibglsnewnumber}
21230
21231 \formatdef{bibglsnewnumber}
21232 This command is used to define terms identified with the
21233 \atentry{number} type. The definition provided in the \ext{glstex}
21234 file is:
21235 \begin{codeenv}
21236 \cs{providecommand}\marg{\gls{bibglsnewnumber}}[4]\marg{\comment{}
21237 \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{}
21238 }
21239 \end{codeenv}
21240 This is much the same as \gls{bibglsnewsymbol} above but sets the
21241 \field{category} to \optfmt{number}. Again the \field{sort} and
21242 \field{category} keys may be overridden by \meta{options}.
21243
21244 \cssection{bibglsnewindex}
21245
21246 \formatdef{bibglsnewindex}
21247 This command is used to define terms identified with the
21248 \atentry{index} type. The definition provided in the \ext{glstex}
21249 file is:
21250 \begin{codeenv}
21251 \cs{providecommand}*\marg{\gls{bibglsnewindex}}[2]\marg{\comment{}
21252 \gls{newglossaryentry}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}1},\field{category}=\marg{index},\field{description}=\marg{},\idx{param}2}\comment{}
21253 }
21254 \end{codeenv}
21255 This makes the \field{name} default to the \meta{label}, assigns
21256 the \field{category} to \code{index} and sets an empty
21257 \field{description}. These settings may be overridden by
21258 \meta{options}.
21259
21260 Note that the \field{description} doesn't include
21261 \ics{nopostdesc} to allow for the \idx{postdescriptionhook} used by
21262 category attributes.
21263
21264 \cssection{bibglsnewindexplural}
21265
21266 \formatdef{bibglsnewindexplural}
21267 This command is used to define terms identified with the
21268 \atentry{indexplural} type. The definition provided in the \ext{glstex}
21269 file is:
21270 \begin{codeenv}
21271 \cs{providecommand}\marg{\gls{bibglsnewindexplural}}[3]\marg{\comment{}
21272 \gls{newglossaryentry}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{category}=\marg{indexplural},\field{description}=\marg{},\idx{param}2}\comment{}
21273 }
21274 \end{codeenv}
21275 This assigns the \field{category} to \code{indexplural} and sets an empty
21276 \field{description}. These settings may be overridden by \meta{options}.
21277
21278 \cssection{bibglsnewabbreviation}
21279
21280 \formatdef{bibglsnewabbreviation}
21281 This command is used to define terms identified with the
21282 \atentry{abbreviation} type. The definition provided in the \ext{glstex}
21283 file is:
21284 \begin{codeenv}
21285 \cs{providecommand}\marg{\gls{bibglsnewabbreviation}}[4]\marg{\comment{}
21286 \gls{newabbreviation}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{}
21287 }
21288 \end{codeenv}
21289 Since this uses \gls{newabbreviation}, it obeys the
21290 abbreviation style for its given \field{category} (which may have
21291 been set in \meta{options}, either from the \field{category} field
21292 in the \ext{bib} file or through the \csopt{category} option).
21293 Similarly the \field{type} will obey \ics{glsxtrabbrvtype} unless
21294 the value is supplied in the \ext{bib} file or through the
21295 \csopt{type} option.
21296
21297 \cssection{bibglsnewacronym}
21298
21299 \formatdef{bibglsnewacronym}
21300 This command is used to define terms identified with the
21301 \atentry{acronym} type. The definition provided in the \ext{glstex}
21302 file is:
21303 \begin{codeenv}
21304 \cs{providecommand}\marg{\gls{bibglsnewacronym}}[4]\marg{\comment{}
21305 \gls{newacronym}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{}
21306 }
21307 \end{codeenv}
21308 This works in much the same way as \gls{bibglsnewabbreviation}.
21309 Remember that with the \styfmt{glossaries-extra} package \gls{newacronym}
21310 is redefined to just use \gls{newabbreviation} with the default \field{type}
21311 set to \ics{acronymtype} and the default \field{category} set to
21312 \code{acronym}.
21313
21314 \cssection{bibglsnewdualentry}
21315
21316 \formatdef{bibglsnewdualentry}
21317 This command is used to define terms identified with the
21318 \atentry{dualentry} type. The definition provided in the \ext{glstex}
21319 file is:
21320 \begin{codeenv}
21321 \cs{providecommand}\marg{\gls{bibglsnewdualentry}}[4]\marg{\comment{}
21322 \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{}
21323 }
21324 \end{codeenv}
21325
21326 \cssection{bibglsnewdualindexentry}
21327
21328 \formatdef{bibglsnewdualindexentry}
21329 This command is used to define \primary\ terms identified with the
21330 \atentry{dualindexentry} type. The definition provided in the \ext{glstex}
21331 file is:
21332 \begin{codeenv}
21333 \cs{providecommand}\marg{\gls{bibglsnewdualindexentry}}[4]\marg{\comment{}
21334 \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{category}=\marg{index},\idx{param}2}\marg{}\comment{}
21335 }
21336 \end{codeenv}
21337 Note that this definition ignores the \meta{description} argument.
21338
21339 \cssection{bibglsnewdualindexentrysecondary}
21340
21341 \formatdef{bibglsnewdualindexentrysecondary}
21342 This command is used to define \glsdisp{dualentry}{secondary} terms identified with the
21343 \atentry{dualindexentry} type. The definition provided in the \ext{glstex}
21344 file is:
21345 \begin{codeenv}
21346 \cs{providecommand}\marg{\gls{bibglsnewdualindexentrysecondary}}[4]\marg{\comment{}
21347 \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{}
21348 }
21349 \end{codeenv}
21350
21351 \cssection{bibglsnewdualindexsymbol}
21352
21353 \formatdef{bibglsnewdualindexsymbol}
21354 This command is used to define \primary\ terms identified with the
21355 \atentry{dualindexsymbol} type. The definition provided in the \ext{glstex}
21356 file is:
21357 \begin{codeenv}
21358 \cs{providecommand}\marg{\gls{bibglsnewdualindexsymbol}}[5]\marg{\comment{}
21359 \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{}
21360 }
21361 \end{codeenv}
21362 Note that this definition ignores the \meta{description} argument.
21363
21364 \cssection{bibglsnewdualindexsymbolsecondary}
21365
21366 \formatdef{bibglsnewdualindexsymbolsecondary}
21367 This command is used to define \glsdisp{dualentry}{secondary} terms identified with the
21368 \atentry{dualindexsymbol} type. The definition provided in the \ext{glstex}
21369 file is:
21370 \begin{codeenv}
21371 \cs{providecommand}\marg{\gls{bibglsnewdualindexsymbolsecondary}}[5]\marg{\comment{}
21372 \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{}
21373 }
21374 \end{codeenv}
21375
21376 \cssection{bibglsnewdualindexnumber}
21377
21378 \formatdef{bibglsnewdualindexnumber}
21379 This command is used to define \primary\ terms identified with the
21380 \atentry{dualindexnumber} type. The definition provided in the \ext{glstex}
21381 file is:
21382 \begin{codeenv}
21383 \cs{providecommand}\marg{\gls{bibglsnewdualindexnumber}}[5]\marg{\comment{}
21384 \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{}
21385 }
21386 \end{codeenv}
21387 Note that this definition ignores the \meta{description} argument.
21388
21389 \cssection{bibglsnewdualindexnumbersecondary}
21390
21391 \formatdef{bibglsnewdualindexnumbersecondary}
21392 This command is used to define \glsdisp{dualentry}{secondary} terms identified with the
21393 \atentry{dualindexnumber} type. The definition provided in the \ext{glstex}
21394 file is:
21395 \begin{codeenv}
21396 \cs{providecommand}\marg{\cs{bibglsnewdualindexnumbersecondary}}[5]\marg{\comment{}
21397 \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{}
21398 }
21399 \end{codeenv}
21400
21401 \cssection{bibglsnewdualindexabbreviation}
21402
21403 \formatdef{bibglsnewdualindexabbreviation}
21404 This command is used to define \primary\ terms identified with the
21405 \atentry{dualindexabbreviation} type. The default definition provided in
21406 the \ext{glstex} file is:
21407 \begin{codeenv}
21408 \cs{providecommand}\marg{\gls{bibglsnewdualindexabbreviation}}[7]\marg{\comment{}
21409 \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\comment{}
21410 \field{name}=\marg{\cs{protect}\gls{bibglsuseabbrvfont}\marg{\idx{param}4}\marg{\cs{glscategory}\marg{\idx{param}2}}},\comment{}
21411 \field{category}=\marg{index},\idx{param}3}\marg{}\comment{}
21412 }
21413 \end{codeenv}
21414 In this case \meta{dual-label} is the \gls{dualentry}['s] label, which is used
21415 to fetch the category label in \gls{bibglsuseabbrvfont}. (The
21416 \field{category} field for the dual isn't used since a custom
21417 definition of
21418 \gls!{bibglsnewdualindexabbreviationsecondary} may override the
21419 value known to \bibgls.)
21420
21421 Note that (as shown above) with the default
21422 \csopt[short]{abbreviation-name-fallback} the \field{name} uses:
21423 \nosecformatdef{bibglsuseabbrvfont}
21424 to format the name, which ensures that it uses the same font as the
21425 short form for the \dual\ abbreviation. This will use
21426 \ics{glsuseabbrvfont} if it's defined otherwise it will be defined
21427 to replicate that command. If \csopt{abbreviation-name-fallback} is
21428 set to some other field then the \field{name} uses:
21429 \nosecformatdef{bibglsuselongfont}
21430 instead, which ensures that it uses the same font as the
21431 long form for the \dual\ abbreviation.
21432
21433 \cssection{bibglsnewdualindexabbreviationsecondary}
21434
21435 \formatdef{bibglsnewdualindexabbreviationsecondary}
21436 This command is used to define \glsdisp{dualentry}{secondary} terms identified with the
21437 \atentry{dualindexabbreviation} \gls{entrytype}.
21438 The definition provided in the \ext{glstex} file is:
21439 \begin{codeenv}
21440 \cs{providecommand}\marg{\gls{bibglsnewdualindexabbreviationsecondary}}[6]\marg{\comment{}
21441 \cs{ifstrempty}\marg{\idx{param}6}\comment{}
21442 \marg{\gls{newabbreviation}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}4}\marg{\idx{param}5}}\comment{}
21443 \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{}
21444 }
21445 \end{codeenv}
21446 This ensures that a missing or empty \field{description} doesn't
21447 interfere with the abbreviation style.
21448
21449 \cssection{bibglsnewdualabbreviationentry}
21450
21451 \formatdef{bibglsnewdualabbreviationentry}
21452 This command is used to define \primary\ terms identified with the
21453 \atentry{dualabbreviationentry} type. The definition provided in the \ext{glstex}
21454 file is:
21455 \begin{codeenv}
21456 \cs{providecommand}\marg{\gls{bibglsnewdualabbreviationentry}}[5]\marg{\comment{}
21457 \gls{newabbreviation}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{}
21458 }
21459 \end{codeenv}
21460 Note that this definition ignores the \meta{description} argument.
21461
21462 \cssection{bibglsnewdualabbreviationentrysecondary}
21463
21464 \formatdef{bibglsnewdualabbreviationentrysecondary}
21465 This command is used to define \glsdisp{dualentry}{secondary} terms identified with the
21466 \atentry{dualabbreviationentry} type. The definition provided in the \ext{glstex}
21467 file is:
21468 \begin{codeenv}
21469 \cs{providecommand}\marg{\gls{bibglsnewdualabbreviationentrysecondary}}[5]\marg{\comment{}
21470 \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\idx{param}2}\marg{\idx{param}5}\comment{}
21471 }
21472 \end{codeenv}
21473 Note that this definition ignores the \meta{short} and \meta{long}
21474 arguments (which will typically be empty unless the default mappings
21475 are changed).
21476
21477 \cssection{bibglsnewdualentryabbreviation}
21478
21479 \formatdef{bibglsnewdualentryabbreviation}
21480 This command is used to define \primary\ terms identified with the
21481 (now deprecated) \gls{entrytype}
21482 \atentry{dualentryabbreviation}. The definition provided in the \ext{glstex}
21483 file is:
21484 \begin{codeenv}
21485 \cs{providecommand}\marg{\gls{bibglsnewdualentryabbreviation}}[5]\marg{\comment{}
21486 \gls{newabbreviation}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{}
21487 }
21488 \end{codeenv}
21489 Note that this definition ignores the \meta{description} argument.
21490
21491 \cssection{bibglsnewdualentryabbreviationsecondary}
21492
21493 \formatdef{bibglsnewdualentryabbreviationsecondary}
21494 This command is used to define \glsdisp{dualentry}{secondary} terms identified with the
21495 (now deprecated) \gls{entrytype}
21496 \atentry{dualentryabbreviation}. The definition provided in the \ext{glstex}
21497 file is:
21498 \begin{codeenv}
21499 \cs{providecommand}\marg{\gls{bibglsnewdualentryabbreviationsecondary}}[5]\marg{\comment{}
21500 \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\idx{param}2}\marg{\idx{param}5}\comment{}
21501 }
21502 \end{codeenv}
21503 Note that this definition ignores the \meta{short} and \meta{long}
21504 arguments (which will typically be empty unless the default mappings
21505 are changed).
21506
21507 \cssection{bibglsnewdualsymbol}
21508
21509 \formatdef{bibglsnewdualsymbol}
21510 This command is used to define terms identified with the
21511 \atentry{dualsymbol} type. The definition provided in the \ext{glstex}
21512 file is:
21513 \begin{codeenv}
21514 \cs{providecommand}\marg{\gls{bibglsnewdualsymbol}}[4]\marg{\comment{}
21515 \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}}
21516 \end{codeenv}
21517
21518 \cssection{bibglsnewdualnumber}
21519
21520 \formatdef{bibglsnewdualnumber}
21521 This command is used to define terms identified with the
21522 \atentry{dualnumber} type. The definition provided in the \ext{glstex}
21523 file is:
21524 \begin{codeenv}
21525 \cs{providecommand}\marg{\gls{bibglsnewdualnumber}}[4]\marg{\comment{}
21526 \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}}
21527 \end{codeenv}
21528
21529 \cssection{bibglsnewdualabbreviation}
21530
21531 \formatdef{bibglsnewdualabbreviation}
21532 This command is used to define terms identified with the
21533 \atentry{dualabbreviation} type where the \field{duallong} field
21534 is swapped with the \field{long} field and the \field{dualshort}
21535 field is swapped with the \field{short} field. The definition provided in the
21536 \ext{glstex} file is:
21537 \begin{codeenv}
21538 \cs{providecommand}\marg{\gls{bibglsnewdualabbreviation}}[4]\marg{\comment{}
21539 \gls{newabbreviation}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{}
21540 }
21541 \end{codeenv}
21542
21543 \cssection{bibglsnewdualacronym}
21544
21545 \formatdef{bibglsnewdualacronym}
21546 This command is used to define terms identified with the
21547 \atentry{dualacronym} type. The definition provided in the \ext{glstex}
21548 file is:
21549 \begin{codeenv}
21550 \cs{providecommand}\marg{\gls{bibglsnewdualacronym}}[4]\marg{\comment{}
21551 \gls{newacronym}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{}
21552 }
21553 \end{codeenv}
21554 This works in much the same way as \gls{bibglsnewdualabbreviation}.
21555 Remember that with the \styfmt{glossaries-extra} package \gls{newacronym}
21556 is redefined to just use \gls{newabbreviation} with the default \field{type}
21557 set to \ics{acronymtype} and the default \field{category} set to
21558 \code{acronym}.
21559
21560 \cssection{bibglsnewtertiaryindexabbreviationentry}
21561
21562 \formatdef{bibglsnewtertiaryindexabbreviationentry}
21563 This is used to define \primary\ terms identified with the
21564 \atentry{tertiaryindexabbreviationentry} type. It's essentially
21565 the same as \gls!{bibglsnewdualindexabbreviation}.
21566 The definition provided in the \ext{glstex} file is:
21567 \begin{codeenv}
21568 \cs{providecommand}\marg{\gls{bibglsnewtertiaryindexabbreviationentry}}[7]\marg{\comment{}
21569 \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\comment{}
21570 \field{name}=\marg{\cs{protect}\gls{bibglsuseabbrvfont}\marg{\idx{param}4}\marg{\cs{glscategory}\marg{\idx{param}2}}},\comment{}
21571 \field{category}=\marg{index},\idx{param}3}{}\comment{}
21572 }
21573 \end{codeenv}
21574
21575 \cssection{bibglsnewtertiaryindexabbreviationentrysecondary}
21576
21577 \formatdef{bibglsnewtertiaryindexabbreviationentrysecondary}
21578 This command is used to define both the
21579 \glsdisp{secondaryentry}{secondary} and
21580 \glsdisp{tertiaryentry}{tertiary} terms identified with the
21581 \atentry{tertiaryindexabbreviationentry} type. The
21582 \glsdisp{secondaryentry}{secondary} term is
21583 an abbreviation and the \glsdisp{tertiaryentry}{tertiary} term is a regular entry. The
21584 definition written to the \ext{glstex} file is:
21585 \begin{codeenv}
21586 \cs{providecommand}\marg{\gls{bibglsnewtertiaryindexabbreviationentrysecondary}}[8]\marg{\comment{}
21587 \gls{newabbreviation}\oarg{\idx{param}3}\marg{\idx{param}1}\marg{\idx{param}6}\marg{\idx{param}7}\comment{}
21588 \cs{longnewglossaryentry*}\marg{\idx{param}2}\comment{}
21589 \marg{\field{name}=\marg{\cs{protect}\gls{bibglsuselongfont}\marg{\idx{param}7}\marg{\cs{glscategory}\marg{\idx{param}1}}},\idx{param}4}\comment{}
21590 \marg{\idx{param}8}\comment{}
21591 }
21592 \end{codeenv}
21593 The \meta{label} is the label for the
21594 \glsdisp{secondaryentry}{secondary} (abbreviation) entry and
21595 \meta{tertiary-label} is the label for the
21596 \glsdisp{tertiaryentry}{tertiary} (regular) entry. The fifth
21597 argument (\meta{primary name}) isn't used but is provided if
21598 required for a custom redefinition. The \field{name} field for the
21599 \glsdisp{tertiaryentry}{tertiary} is obtained from the \meta{long}
21600 argument encapsulated by \gls{bibglsuselongfont} to format the name,
21601 which ensures that it uses the same font as the long form for the
21602 dual abbreviation. This will use \ics{glsuselongfont} if it's
21603 defined otherwise it will be defined to replicate that command.
21604
21605 \cssection{bibglsnewbibtexentry}
21606
21607 \formatdef{bibglsnewbibtexentry}
21608 This command is used to define the \glsdisp{mainentry}{main term} identified with
21609 \atentry{bibtexentry}.
21610 The definition written to the \ext{glstex} file is:
21611 \begin{codeenv}
21612 \cs{providecommand}\marg{\gls{bibglsnewbibtexentry}}[4]\marg{\comment{}
21613 \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{}
21614 }
21615 \end{codeenv}
21616
21617 \cssection{bibglsnewcontributor}
21618
21619 \formatdef{bibglsnewcontributor}
21620 This command is used to define terms identified with
21621 \atentry{contributor} (typically implicitly created through
21622 \atentry{bibtexentry}).
21623 The definition written to the \ext{glstex} file is:
21624 \begin{codeenv}
21625 \cs{providecommand}\marg{\gls{bibglsnewcontributor}}[4]\marg{\comment{}
21626 \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{}
21627 }
21628 \end{codeenv}
21629
21630 \cssection{bibglsnewprogenitor}
21631
21632 \formatdef{bibglsnewprogenitor}
21633 This command is used to define the \glsdisp{mainentry}{main terms} created by
21634 \atentry{progenitor}. The definition is written to the \ext{glstex}
21635 file as:
21636 \begin{codeenv}
21637 \cs{providecommand}\marg{\gls{bibglsnewprogenitor}}[4]\marg{\comment{}
21638 \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{}
21639 }
21640 \end{codeenv}
21641
21642 \cssection{bibglsnewspawnindex}
21643
21644 \formatdef{bibglsnewspawnindex}
21645 This command is used to define the \glsdisp{mainentry}{main terms} created by
21646 \atentry{spawnindex}. The definition is written to the \ext{glstex}
21647 file as:
21648 \begin{codeenv}
21649 \cs{providecommand}\marg{\gls{bibglsnewspawnindex}}[4]\marg{\comment{}
21650 \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{}
21651 }
21652 \end{codeenv}
21653
21654 \cssection{bibglsnewspawnedindex}
21655
21656 \formatdef{bibglsnewspawnedindex}
21657 This command is used to define the \glsdisp{spawnedentry}{terms spawned} by
21658 \atentry{progenitor} or \atentry{spawnindex}. The definition is written
21659 to the \ext{glstex} file as:
21660 \begin{codeenv}
21661 \cs{providecommand}\marg{\gls{bibglsnewspawnedindex}}[2]\marg{\comment{}
21662 \gls{newglossaryentry}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}1},\field{category}={index},\field{description}=\marg{},\idx{param}2}\comment{}
21663 }
21664 \end{codeenv}
21665
21666 \cssection{bibglsnewspawnindexplural}
21667
21668 \formatdef{bibglsnewspawnindexplural}
21669 This command is used to define the \glsdisp{mainentry}{main terms} created by
21670 \atentry{spawnindexplural}. The definition is written to the \ext{glstex}
21671 file as:
21672 \begin{codeenv}
21673 \cs{providecommand}\marg{\gls{bibglsnewspawnindexplural}}[4]\marg{\comment{}
21674 \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{}
21675 }
21676 \end{codeenv}
21677
21678 \cssection{bibglsnewspawnedindexplural}
21679
21680 \formatdef{bibglsnewspawnedindexplural}
21681 This command is used to define the \glsdisp{spawnedentry}{terms spawned} by
21682 \atentry{spawnindexplural}.
21683 The definition is written to the \ext{glstex} file as:
21684 \begin{codeenv}
21685 \cs{providecommand}\marg{\gls{bibglsnewspawnedindexplural}}[3]\marg{\comment{}
21686 \gls{newglossaryentry}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{category}=\marg{indexplural},\field{description}=\marg{},\idx{param}2}\comment{}
21687 }
21688 \end{codeenv}
21689
21690 \cssection{bibglsnewspawnentry}
21691
21692 \formatdef{bibglsnewspawnentry}
21693 This command is used to define the \glsdisp{mainentry}{main terms} created by
21694 \atentry{spawnentry}. The definition is written to the \ext{glstex}
21695 file as:
21696 \begin{codeenv}
21697 \cs{providecommand}\marg{\gls{bibglsnewspawnentry}}[4]\marg{\comment{}
21698 \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{}
21699 }
21700 \end{codeenv}
21701
21702 \cssection{bibglsnewspawnedentry}
21703
21704 \formatdef{bibglsnewspawnedentry}
21705 This command is used to define the \glsdisp{spawnedentry}{terms spawned} by \atentry{spawnentry}.
21706 The definition is written to the \ext{glstex} file as:
21707 \begin{codeenv}
21708 \cs{providecommand}\marg{\gls{bibglsnewspawnedentry}}[4]\marg{\comment{}
21709 \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{}
21710 }
21711 \end{codeenv}
21712
21713 \cssection{bibglsnewspawnabbreviation}
21714
21715 \formatdef{bibglsnewspawnabbreviation}
21716 This command is used to define the \glsdisp{mainentry}{main terms} created by
21717 \atentry{spawnabbreviation}. The definition is written to the \ext{glstex}
21718 file as:
21719 \begin{codeenv}
21720 \cs{providecommand}\marg{\gls{bibglsnewspawnabbreviation}}[4]\marg{\comment{}
21721 \gls{newabbreviation}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{}
21722 }
21723 \end{codeenv}
21724
21725 \cssection{bibglsnewspawnedabbreviation}
21726
21727 \formatdef{bibglsnewspawnedabbreviation}
21728 This command is used to define the \glsdisp{spawnedentry}{terms spawned} by \atentry{spawnabbreviation}.
21729 The definition is written to the \ext{glstex} file as:
21730 \begin{codeenv}
21731 \cs{providecommand}\marg{\gls{bibglsnewspawnedabbreviation}}[4]\marg{\comment{}
21732 \gls{newabbreviation}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{}
21733 }
21734 \end{codeenv}
21735
21736 \cssection{bibglsnewspawnacronym}
21737
21738 \formatdef{bibglsnewspawnacronym}
21739 This command is used to define the \glsdisp{mainentry}{main terms} created by
21740 \atentry{spawnacronym}. The definition is written to the \ext{glstex}
21741 file as:
21742 \begin{codeenv}
21743 \cs{providecommand}\marg{\gls{bibglsnewspawnacronym}}[4]\marg{\comment{}
21744 \gls{newacronym}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{}
21745 }
21746 \end{codeenv}
21747
21748 \cssection{bibglsnewspawnedacronym}
21749
21750 \formatdef{bibglsnewspawnedacronym}
21751 This command is used to define the \glsdisp{spawnedentry}{terms spawned} by \atentry{spawnacronym}.
21752 The definition is written to the \ext{glstex} file as:
21753 \begin{codeenv}
21754 \cs{providecommand}\marg{\gls{bibglsnewspawnedacronym}}[4]\marg{\comment{}
21755 \gls{newacronym}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{}
21756 }
21757 \end{codeenv}
21758
21759 \cssection{bibglsnewspawnsymbol}
21760
21761 \formatdef{bibglsnewspawnsymbol}
21762 This command is used to define the \glsdisp{mainentry}{main terms} created by
21763 \atentry{spawnsymbol}. The definition is written to the \ext{glstex}
21764 file as:
21765 \begin{codeenv}
21766 \cs{providecommand}\marg{\gls{bibglsnewspawnsymbol}}[4]\marg{\comment{}
21767 \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{}
21768 }
21769 \end{codeenv}
21770
21771 \cssection{bibglsnewspawnedsymbol}
21772
21773 \formatdef{bibglsnewspawnedsymbol}
21774 This command is used to define the \glsdisp{spawnedentry}{terms spawned} by \atentry{spawnsymbol}.
21775 The definition is written to the \ext{glstex} file as:
21776 \begin{codeenv}
21777 \cs{providecommand}\marg{\gls{bibglsnewspawnedsymbol}}[4]\marg{\comment{}
21778 \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}}
21779 \end{codeenv}
21780
21781 \cssection{bibglsnewspawnnumber}
21782
21783 \formatdef{bibglsnewspawnnumber}
21784 This command is used to define the \glsdisp{mainentry}{main terms} created by
21785 \atentry{spawnnumber}. The definition is written to the \ext{glstex}
21786 file as:
21787 \begin{codeenv}
21788 \cs{providecommand}\marg{\gls{bibglsnewspawnnumber}}[4]\marg{\comment{}
21789 \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{}
21790 }
21791 \end{codeenv}
21792
21793 \cssection{bibglsnewspawnednumber}
21794
21795 \formatdef{bibglsnewspawnednumber}
21796 This command is used to define the \glsdisp{spawnedentry}{terms spawned} by \atentry{spawnnumber}.
21797 The definition is written to the \ext{glstex} file as:
21798 \begin{codeenv}
21799 \cs{providecommand}\marg{\gls{bibglsnewspawnednumber}}[4]\marg{\comment{}
21800 \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}}
21801 \end{codeenv}
21802
21803 \cssection{bibglsnewspawndualindexentry}
21804
21805 \formatdef{bibglsnewspawndualindexentry}
21806 This command is used to define the \gls{progenitor}['s] \primary\ term created by
21807 \atentry{spawndualindexentry}.
21808 The definition is written to the \ext{glstex} file as:
21809 \begin{codeenv}
21810 \cs{providecommand}\marg{\gls{bibglsnewspawndualindexentry}}[4]\marg{\comment{}
21811 \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{category}=\marg{index},\idx{param}2}{}\comment{}
21812 }
21813 \end{codeenv}
21814 The \meta{description} argument is ignored.
21815
21816 \cssection{bibglsnewspawndualindexentrysecondary}
21817
21818 \formatdef{bibglsnewspawndualindexentrysecondary}
21819 This command is used to define the \gls{progenitor}['s]
21820 \glsdisp{dualentry}{secondary} (dual) term created by
21821 \atentry{spawndualindexentry}.
21822 The definition is written to the \ext{glstex} file as:
21823 \begin{codeenv}
21824 \cs{providecommand}\marg{\gls{bibglsnewspawndualindexentrysecondary}}[4]\marg{\comment{}
21825 \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{}
21826 }
21827 \end{codeenv}
21828
21829 \section{Compound Entry Sets}
21830 \label{sec:compounddefs}
21831
21832 \cssection{bibglsdefcompoundset}
21833
21834 \formatdef{bibglsdefcompoundset}
21835
21836 The default definition uses \ics{multiglossaryentry}.
21837
21838 \section{Location Lists and Cross-References}
21839 \label{sec:loclistdefs}
21840
21841 These commands deal with the way the \iglspl{locationlist} and
21842 cross references are formatted. The commands typically aren't used until
21843 the entry information is displayed in the glossary, so you may
21844 redefine these commands after the resource file has been loaded.
21845
21846 \cssection{bibglsseesep}
21847
21848 \formatdef{bibglsseesep}
21849 Any entries that provide a \field{see} field (and that field hasn't
21850 be omitted from the \gls{locationlist} with \csopt[omit]{see}) will
21851 have \gls{bibglsseesep} inserted between the \field{see} part and the
21852 \gls{locationlist} (unless there are no \glspl{location}, in which case just
21853 the \field{see} part is displayed without \gls{bibglsseesep}).
21854
21855 This command is provided with:
21856 \begin{codeenv}
21857 \cs{providecommand}\marg{\gls{bibglsseesep}}\marg{, }
21858 \end{codeenv}
21859 You can define this before you load the \ext{bib} file:
21860 \begin{codeenv}
21861 \cs{newcommand}\marg{\gls{bibglsseesep}}\marg{; }
21862 \gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}}
21863 \end{codeenv}
21864 Or you can redefine it afterwards:
21865 \begin{codeenv}
21866 \gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}}
21867 \cs{glsrenewcommand}\marg{\gls{bibglsseesep}}\marg{; }
21868 \end{codeenv}
21869
21870 \cssection{bibglsseealsosep}
21871
21872 \formatdef{bibglsseealsosep}
21873 This is like \gls{bibglsseesep} but is used with cross-reference
21874 lists provided with the \field{seealso} field, if supported.
21875
21876 \cssection{bibglsaliassep}
21877
21878 \formatdef{bibglsaliassep}
21879 This is like \gls{bibglsseesep} but is used with cross-reference
21880 lists provided with the \field{alias} field.
21881
21882 \cssection{bibglsusesee}
21883
21884 \formatdef{bibglsusesee}
21885 Displays the formatted cross-reference list stored in the
21886 \field{see} field for the given entry. This just defaults to
21887 \ics{glsxtrusesee}\margm{label}.
21888
21889 \cssection{bibglsuseseealso}
21890
21891 \formatdef{bibglsuseseealso}
21892 Displays the formatted cross-reference list stored in the
21893 \field{seealso} field for the given entry. This just defaults to
21894 \ics{glsxtruseseealso}\margm{label}.
21895
21896 \cssection{bibglsusealias}
21897
21898 \formatdef{bibglsusealias}
21899 Displays the formatted cross-reference stored in the
21900 \field{alias} field for the given entry. This is defined to use
21901 \ics{glsseeformat}.
21902
21903 \cssection{bibglsdelimN}
21904
21905 \formatdef{bibglsdelimN}
21906 Separator between individual \glspl{location}, except for the last.
21907 This defaults to \ics{delimN}.
21908
21909 \cssection{bibglslastDelimN}
21910
21911 \formatdef{bibglslastDelimN}
21912 Separator between penultimate and final individual \glspl{location}.
21913 This defaults to \code{,\idx{nbspchar}} to discourage lonely \glspl{location}.
21914
21915 \cssection{bibglscompact}
21916
21917 \formatdef{bibglscompact}
21918 This command is used with \csopt{compact-ranges} when the end
21919 \gls{location} in a \idx{range} is compacted.
21920 The first argument \meta{pattern} indicates the \gls{location} pattern:
21921 \code{digit} for digits, \code{roman} for \idx!{lowercase}
21922 Roman numerals, \code{ROMAN} for \idx!{uppercase} Roman
21923 numerals and \code{alpha} for alphabetical \glspl{location}. The actual
21924 \gls{location} is split into two parts, \meta{part1} and \meta{part2}.
21925 The string concatenation \meta{part1}\meta{part2} forms the
21926 actual \gls{location}.
21927
21928 This just does \meta{part2} by default.
21929
21930 \cssection{bibglspassim}
21931
21932 \formatdef{bibglspassim}
21933 If \csopt{max-loc-diff} is greater than~1, then any
21934 \idxpl{implicit-range} that have skipped over gaps will be followed
21935 by \gls{bibglspassim}, which is defined as:
21936 \begin{codeenv}
21937 \cs{providecommand}\marg{\gls{bibglspassim}}\marg{ \gls{bibglspassimname}}
21938 \end{codeenv}
21939 You can define this before you load the \ext{bib} file:
21940 \begin{codeenv}
21941 \cs{newcommand}\marg{\gls{bibglspassim}}\marg{}
21942 \gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}}
21943 \end{codeenv}
21944 Or you can redefine it afterwards:
21945 \begin{codeenv}
21946 \gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}}
21947 \cs{glsrenewcommand}\marg{\gls{bibglspassim}}\marg{}
21948 \end{codeenv}
21949
21950 \cssection{bibglspassimname}
21951
21952 \formatdef{bibglspassimname}
21953 The default definition is obtained from the \langxml. For example, with
21954 \file{bib2gls-en.xml} the provided definition is:
21955 \begin{codeenv}
21956 \cs{providecommand}\marg{\gls{bibglspassimname}}\marg{passim}
21957 \end{codeenv}
21958
21959 \cssection{bibglsrange}
21960
21961 \formatdef{bibglsrange}
21962 \Idxpl{explicit-range} formed using \glsopt[\idx{openrange}]{format} and
21963 \glsopt[\idx{closerange}]{format} or \glsopt[\idx{openrange}\meta{csname}]{format} and
21964 \glsopt[\idx{closerange}\meta{csname}]{format} (where \meta{csname} matches and is a
21965 text-block command without the initial backslash) in the optional
21966 argument of commands like \ics{gls} or \ics{glsadd} are encapsulated within
21967 the argument of \gls{bibglsrange}. By default, this simply does its
21968 argument. This command is not used with \idxpl{implicit-range} that
21969 are formed by collating consecutive \glspl{location} or when
21970 \csopt[true]{merge-ranges} is used.
21971
21972 \cssection{bibglsinterloper}
21973
21974 \formatdef{bibglsinterloper}
21975 If an \idxpl{explicit-range} conflicts with a record, a warning will be
21976 issued and the conflicting record (the \idx{interloper}) will be shifted to the front
21977 of the \idx{range} inside the argument of \gls{bibglsinterloper}.
21978 The default definition just does \meta{location}\gls!{bibglsdelimN}
21979 so that it fits neatly into the list.
21980
21981 For example, suppose on page~4 of my document I start a \idx{range} with:
21982 \begin{codeenv*}
21983 \cs{glsadd}\oarg{\glsaddopt[\idx{openrange}]{format}}\marg{sample}
21984 \end{codeenv*}
21985 and end it on page~9 with:
21986 \begin{codeenv*}
21987 \cs{glsadd}\oarg{\glsaddopt[\idx{closerange}]{format}}\marg{sample}
21988 \end{codeenv*}
21989 This forms an \idx{explicit-range}, but let's suppose on page~6 I
21990 have:
21991 \begin{codeenv}
21992 \cs{gls}\oarg{\glsopt[\encap{hyperbf}]{format}}\marg{sample}
21993 \end{codeenv}
21994 This record conflicts with the \idx{explicit-range} (which doesn't include
21995 \encap{hyperbf} in the format). This causes a warning and
21996 the conflicting entry will be moved before the start of the
21997 \idx{explicit-range} resulting in \textbf{6}, 4--9.
21998
21999 Note that \idxpl{implicit-range} can't be formed from \idxpl{interloper} (nor can
22000 \idxpl{implicit-range} be merged with explicit ones with the default
22001 \csopt[false]{merge-ranges}),
22002 so if \code{\cs{gls}\oarg{\glsopt[\encap{hyperbf}]{format}}\marg{sample}}
22003 also occurs on pages~7 and~8 then the result will be \textbf{6}, \textbf{7},
22004 \textbf{8}, 4--9. Either remove the \idx{explicit-range} or
22005 remove the conflicting entries. (Alternatively, redefine
22006 \gls{bibglsinterloper} to ignore its argument, which will
22007 discard the conflicting entries.)
22008
22009 \cssection{bibglspostlocprefix}
22010
22011 \formatdef{bibglspostlocprefix}
22012 If the \csopt{loc-prefix} option is on, \gls!{bibglslocprefix} will
22013 be inserted at the start of \glspl{locationlist}, and its default
22014 definition includes \gls{bibglspostlocprefix}
22015 placed after the prefix text. This command is provided with:
22016 \begin{codeenv}
22017 \cs{providecommand}\marg{\gls{bibglspostlocprefix}}\marg{\cs{cs.space}}
22018 \end{codeenv}
22019 which puts a space between the prefix text and the \gls{locationlist}.
22020 You can define this before you load the \ext{bib} file:
22021 \begin{codeenv}
22022 \cs{newcommand}\marg{\gls{bibglspostlocprefix}}\marg{: }
22023 \gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt{loc-prefix}}
22024 \end{codeenv}
22025 Or you can redefine it afterwards:
22026 \begin{codeenv}
22027 \gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt{loc-prefix}}
22028 \cs{glsrenewcommand}\marg{\gls{bibglspostlocprefix}}\marg{: }
22029 \end{codeenv}
22030
22031 \cssection{bibglslocprefix}
22032
22033 \formatdef{bibglslocprefix}
22034 If the \csopt{loc-prefix} option is on, this command will be
22035 provided. The location of the definition is determined by the
22036 \csopt{loc-prefix-def} option. For example, if the document has:
22037 \begin{codeenv}
22038 \gls{GlsXtrLoadResources}\oarg{\csopt[main]{type},\csopt[individual]{loc-prefix-def},\csopt[p.,pp.]{loc-prefix},\csopt[entries]{src}}
22039 \end{codeenv}
22040 then the following will be added to the \ext{glstex} file:
22041 \begin{codeenv}
22042 \cs{apptoglossarypreamble}\oarg{main}\marg{\comment{}
22043 \cs{providecommand}\marg{\gls{bibglslocprefix}}[1]\marg{\comment{}
22044 \cs{ifcase}\idx{param}\idx{param}1
22045 \cmd{or} p.\gls{bibglspostlocprefix}
22046 \cmd{else} pp.\gls{bibglspostlocprefix}
22047 \cmd{fi}
22048 }\comment{}
22049 }
22050 \end{codeenv}
22051 However, if the \csopt{type} key is missing or if the option
22052 \csopt[local]{loc-prefix-def} is used, then the following will
22053 be added instead:
22054 \begin{codeenv}
22055 \cs{appto}\cs{glossarypreamble}\marg{\comment{}
22056 \cs{providecommand}\marg{\gls{bibglslocprefix}}[1]\marg{\comment{}
22057 \cs{ifcase}\idx{param}1
22058 \cmd{or} p.\gls{bibglspostlocprefix}
22059 \cmd{else} pp.\gls{bibglspostlocprefix}
22060 \cmd{fi}
22061 }\comment{}
22062 }
22063 \end{codeenv}
22064 If \csopt[global]{loc-prefix-def} is used then the definition is
22065 global (outside of the glossary preamble).
22066
22067 \cssection{bibglspagename}
22068
22069 \formatdef{bibglspagename}
22070 If \csopt[true]{loc-prefix} is used, then this command is provided
22071 using the value of \idx{tag.page} from the \langxml. For example with \file{bib2gls-en.xml} the definition is:
22072 \begin{codeenv}
22073 \cs{providecommand}\marg{\gls{bibglspagename}}\marg{Page}
22074 \end{codeenv}
22075
22076 \cssection{bibglspagesname}
22077
22078 \formatdef{bibglspagesname}
22079 If \csopt[true]{loc-prefix} is used, then this command is provided
22080 using the value of \idx{tag.pages} from the \langxml. For example with \file{bib2gls-en.xml} the definition is:
22081 \begin{codeenv}
22082 \cs{providecommand}\marg{\gls{bibglspagesname}}\marg{Pages}
22083 \end{codeenv}
22084
22085 \cssection{bibglslocsuffix}
22086
22087 \formatdef{bibglslocsuffix}
22088 If the \csopt{loc-suffix} option is on, this command will be
22089 provided. The location of the definition depends on the
22090 \csopt{loc-suffix-def} option.
22091
22092 This command's definition depends on the value provided by
22093 \csopt{loc-suffix}. For example, with
22094 \csopt[\ics{at}{\idx{periodchar}}]{loc-suffix}
22095 the command is defined as:
22096 \begin{codeenv}
22097 \cs{providecommand}\marg{\gls{bibglslocsuffix}}[1]\marg{\ics{at}.}
22098 \end{codeenv}
22099 (which ignores the argument).
22100
22101 Whereas with \csopt[\meta{A}\dcomma\meta{B}\dcomma\meta{C}]{loc-suffix}
22102 the command is defined as:
22103 \begin{codeenv}
22104 \cs{providecommand}\marg{\gls{bibglslocsuffix}}[1]\marg{\cs{ifcase}\idx{param}1 \meta{A}\cmd{or} \meta{B}\cmd{else} \meta{C}\cmd{fi}}
22105 \end{codeenv}
22106
22107 Note that this is slightly different from \gls{bibglslocprefix} as
22108 it includes the 0 case, which in this instance means that there were
22109 no \glspl{location} but there was a cross-reference. This command isn't
22110 added when the \gls{locationlist} is empty.
22111
22112 \cssection{bibglslocationgroup}
22113
22114 \formatdef{bibglslocationgroup}
22115 When the \csopt{loc-counters} option is used, the \glspl{location}
22116 for each entry are grouped together according to the counter
22117 (in the order specified in the value of \csopt{loc-counters}).
22118 Each group of \glspl{location} is encapsulated within
22119 \gls{bibglslocationgroup}, where \meta{n} is the number
22120 of \glspl{location} within the group, \meta{counter} is the
22121 counter name and \meta{list} is the formatted \gls{location} sub-list.
22122 By default, this simply does \meta{list}, but may be
22123 defined (before the resources are loaded) or redefined
22124 (after the resources are loaded) as required.
22125
22126 For example:
22127 \begin{codeenv}
22128 \cs{newcommand}*\marg{\gls{bibglslocationgroup}}[3]\marg{\comment{}
22129 \cs{ifnum}\idx{param}1=1
22130 \idx{param}2:
22131 \cmd{else}
22132 \idx{param}2s:
22133 \cmd{fi}
22134 \idx{param}3\comment{}
22135 }
22136 \strut
22137 \gls{GlsXtrLoadResources}\oarg{
22138 \csopt[equation,page]{loc-counters},\comment{group locations by counter}
22139 \csopt[entries]{src}\comment{data in entries.bib}
22140 }
22141 \end{codeenv}
22142 This will prefix each group with the counter name, if there's
22143 only one \gls{location}, or the counter name followed by \qt{s},
22144 if there are multiple \glspl{location} within the group.
22145
22146 There are various ways to adapt this to translate the counter
22147 name to a different textual label, such as:
22148 \begin{codeenv}
22149 \cs{providecommand}\marg{\cmd{pagename}}\marg{Page}
22150 \cs{providecommand}\marg{\cmd{pagesname}}\marg{Pages}
22151 \cs{providecommand}\marg{\cmd{equationname}}\marg{Equation}
22152 \cs{providecommand}\marg{\cmd{equationsname}}\marg{Equations}
22153 \strut
22154 \cs{newcommand}*\marg{\gls{bibglslocationgroup}}[3]\marg{\comment{}
22155 \ics{ifnum}\idx{param}1=1
22156 \ics{ifcsdef}\marg{\idx{param}2name}\marg{\cs{csuse}\marg{\idx{param}2name}}\marg{\idx{param}2}:
22157 \cmd{else}
22158 \cs{ifcsdef}\marg{\idx{param}2sname}\marg{\cs{csuse}\marg{\idx{param}2sname}}\marg{\idx{param}2s}:
22159 \cmd{fi}
22160 \idx{param}3\comment{}
22161 }
22162 \end{codeenv}
22163
22164 \cssection{bibglslocationgroupsep}
22165
22166 \formatdef{bibglslocationgroupsep}
22167 When the \csopt{loc-counters} option is set, this command
22168 is used to separate each \gls{location} sub-group. It may be defined
22169 before the resources are loaded:
22170 \begin{codeenv}
22171 \cs{newcommand}*\marg{\gls{bibglslocationgroupsep}}\marg{; }
22172 \strut
22173 \gls{GlsXtrLoadResources}\oarg{
22174 \csopt[equation,page]{loc-counters},\comment{group locations by counter}
22175 \csopt[entries]{src}\comment{data in entries.bib}
22176 }
22177 \end{codeenv}
22178 or redefined after the resources are loaded:
22179 \begin{codeenv}
22180 \gls{GlsXtrLoadResources}\oarg{
22181 \csopt[equation,page]{loc-counters},\comment{group locations by counter}
22182 \csopt[entries]{src}\comment{data in entries.bib}
22183 }
22184 \strut
22185 \cs{glsrenewcommand}*\marg{\gls{bibglslocationgroupsep}}\marg{; }
22186 \end{codeenv}
22187
22188 \cssection{bibglsprimary}
22189
22190 \formatdef{bibglsprimary}
22191 When the \csopt{save-principal-locations} option is used, the
22192 \glspl{principallocation} are stored in the \field{primarylocations} field
22193 encapsulated with this command, unless the locations are split into
22194 groups according to the location counter.
22195
22196 The first argument is the number of \glspl{location} in the list.
22197 The second argument is the list of \glspl{location} formatted in the
22198 usual way. The default definition is to ignore the first argument
22199 and simply do the second.
22200
22201 If the locations are split into groups, then \gls{bibglsprimarylocationgroup}
22202 is used for each group instead (separated with
22203 \gls{bibglsprimarylocationgroupsep}).
22204
22205 \cssection{bibglsprimarylocationgroup}
22206
22207 \formatdef{bibglsprimarylocationgroup}
22208 As \gls{bibglslocationgroup} but for primary group
22209 locations.
22210
22211 \cssection{bibglsprimarylocationgroupsep}
22212
22213 \formatdef{bibglsprimarylocationgroupsep}
22214 As \gls{bibglslocationgroupsep} but for primary group locations.
22215
22216 \cssection{bibglssupplemental}
22217
22218 \formatdef{bibglssupplemental}
22219 When the \csopt{supplemental-locations} option is used, the
22220 \glspl{location} from a \supplementarydocument\ are encapsulated
22221 within the \meta{list} part of \gls{bibglssupplemental}. The first
22222 argument \meta{n} (ignored by default) is the number of
22223 \supplementarylocations.
22224
22225 If multiple \supplemental\ sources are permitted (that is,
22226 \bibgls\ has detected that the document is using at least
22227 version 1.36 of \sty{glossaries-extra}), then the \meta{list}
22228 part will consist of sub-lists for each external source. In this
22229 case, \meta{n} will be the total number of elements across
22230 all the sub-lists.
22231
22232 \cssection{bibglssupplementalsublist}
22233
22234 \formatdef{bibglssupplementalsublist}
22235 If multiple \supplemental\ sources are permitted, this will be used
22236 to format each sub-list, where \meta{n} (ignored by default)
22237 is the number of elements in the sub-list, \meta{external document}
22238 (ignored by default) is the external source and \meta{list}
22239 is the list of \supplementarylocations\ in \meta{external document}.
22240
22241 \cssection{bibglssupplementalsep}
22242
22243 \formatdef{bibglssupplementalsep}
22244 The separator between the main \gls{locationlist} and the supplementary
22245 \gls{locationlist}. By default this is just \gls!{bibglsdelimN}. This may be
22246 defined before the resources are loaded:
22247 \begin{codeenv}
22248 \cs{newcommand}\marg{\gls{bibglssupplementalsep}}\marg{; }
22249 \strut
22250 \gls{GlsXtrLoadResources}\oarg{
22251 \csopt[supplDoc]{supplemental-locations},
22252 \csopt[entries]{src}}
22253 \end{codeenv}
22254 or redefined after the resources are loaded:
22255 \begin{codeenv}
22256 \gls{GlsXtrLoadResources}\oarg{
22257 \csopt[supplDoc]{supplemental-locations},
22258 \csopt[entries]{src}}
22259 \strut
22260 \cs{glsrenewcommand}\marg{\gls{bibglssupplementalsep}}\marg{; }
22261 \end{codeenv}
22262
22263 \cssection{bibglssupplementalsubsep}
22264
22265 \formatdef{bibglssupplementalsubsep}
22266 The separator between the supplementary
22267 \gls{location} sub-lists. By default this is just \gls!{bibglsdelimN}.
22268
22269 \cssection{bibglshrefchar}
22270
22271 \formatdef{bibglshrefchar}
22272 Expands to a literal percent character followed by \meta{hex}. The
22273 second argument is ignored.
22274
22275 \cssection{bibglshrefunicode}
22276
22277 \formatdef{bibglshrefunicode}
22278 Expands to the second argument. The first argument is ignored.
22279
22280 \cssection{bibglshexunicodechar}
22281
22282 \formatdef{bibglshexunicodechar}
22283 This command is used by the \csopt{hex-unicode-fields} option when
22284 replacing any Unicode characters. The argument \meta{hex} is the hexadecimal
22285 character code. Note that the argument isn't preceded by the double-quote
22286 character~\idx{doublequotecharhex} (which is normally used to
22287 identify hexadecimal numbers in \LaTeX). Instead, the definition
22288 needs to insert this character, if appropriate.
22289
22290 If \bibgls\ has detected that the \sty{hyperref} package has been
22291 loaded, it will provide a definition that may be used in PDF
22292 bookmarks provided that \sty{hyperref}'s \styoptfmt{unicode} option is
22293 set. Otherwise the command will simply do
22294 \code{\ics{cs.symbol}\marg{\idx{doublequotecharhex}\meta{hex}}}
22295 (which will require an appropriate font in order to render the
22296 symbol correctly).
22297
22298 \section{Letter Groups}
22299 \label{sec:lettergroupdefs}
22300
22301 The commands listed in this section are provided for use with the
22302 \longarg{group} switch and glossary styles that display the letter
22303 group title. If these need their definitions altered, they should
22304 be defined before the resource file is loaded if field expansion
22305 is on (\longarg{expand-fields}) otherwise they may be redefined
22306 afterwards.
22307
22308 The base \isty{glossaries} package determines group titles through a fairly
22309 simplistic rule. Both \idx!{makeindex} and \idx!{xindy} write the
22310 line:
22311 \nosecformatdef{glsgroupheading}
22312 to the associated glossary file at the start of each new letter group.
22313 For example, the \qt{A} letter group will be written as:
22314 \begin{codeenv}
22315 \gls{glsgroupheading}\marg{A}
22316 \end{codeenv}
22317 This is quite straightforward and the heading title can just be
22318 \qt{A}. The \qt{Symbols} group is written as:
22319 \begin{codeenv}
22320 \gls{glsgroupheading}\marg{glssymbols}
22321 \end{codeenv}
22322 To allow for easy translation, the base \sty{glossaries} package has
22323 the simple rule:
22324 \begin{itemize}
22325 \item if \csfmt{\meta{heading}groupname} exists use that;
22326 \item otherwise just use \meta{heading}.
22327 \end{itemize}
22328 There's no \csfmt{Agroupname} provided, but \ics{glssymbolsgroupname}
22329 is provided and is supported by the associated language modules,
22330 such as \styfmt{glossaries-french}. (Similarly for the \qt{Numbers}
22331 group.)
22332
22333 The glossary styles that provide hyperlinks to the groups (such as
22334 \glostyle{indexhypergroup}) use \meta{heading} to form the target
22335 name. A problem arises when active characters occur in
22336 \meta{heading}, which happens with extended characters and
22337 \isty{inputenc}.
22338
22339 The \sty{glossaries-extra} package (as from version 1.14) provides:
22340 \nosecformatdef{glsxtrsetgrouptitle}
22341 to set the title for a group with the given label. The internal
22342 workings of \gls{glsgroupheading} are modified to use a slightly
22343 altered rule:
22344 \begin{itemize}
22345 \item if a title has been set using
22346 \gls{glsxtrsetgrouptitle}\margm{heading}\margm{title} for the given
22347 \meta{heading}, use that;
22348 \item if \csfmt{\meta{heading}groupname} exists, use that;
22349 \item just use \meta{heading} for the title.
22350 \end{itemize}
22351 So if \gls{glsxtrsetgrouptitle} hasn't been used, it falls back on
22352 the original rule.
22353
22354 The problem is now how to make the indexing application use the
22355 desired label in the argument of \gls{glsgroupheading} instead of selecting
22356 the heading based on the first character of each sort value for each
22357 \gls{top-levelentry} in that group. This can't be done with
22358 \idx!{makeindex}, and with \idx!{xindy} it requires a custom language
22359 module, which isn't a trivial task.
22360
22361 With \bibgls, a different approach is used. The \iext{glstex} file
22362 created isn't comparable to the \iext{gls} file created by
22363 \idx!{makeindex} or \idx!{xindy}. There's nowhere for \bibgls\ to
22364 write the \gls{glsgroupheading} line as it isn't creating the code
22365 that typesets the glossary list. Instead it's creating the code that
22366 defines the entries. The actual group heading is inserted by
22367 \ics{printunsrtglossary} and it's only able to do this by checking if
22368 the entry has a \field{group} field and comparing it to the previous
22369 entry's \field{group} field.
22370
22371 The behaviour of the group formation implemented by the sort
22372 methods may be changed with \csopt{group-formation}. With any
22373 setting other than \csopt[default]{group-formation}, the group label
22374 is set to \format{bibglsunicodegroup} and the title is set to
22375 \format{bibglsunicodegrouptitle} (see below) otherwise the label and
22376 title are determined by the sort method.
22377
22378 The collators used by the locale and letter-based rules save the
22379 following information for each entry based on the first significant letter of
22380 the \field{sort} field (if the letter is recognised as alphabetical,
22381 according to the rule):
22382 \begin{itemize}
22383 \item \meta{title} The group's title. This is typically title-cased.
22384 For example, if the rule recognises the digraph \qt{dz}, then the
22385 title is \qt{Dz}. Exceptions to this are included in the \langxml.
22386 If the key \idx{grouptitle.case.lc} exists, where
22387 \meta{lc} is the \idx!{lowercase} version of \meta{title}, then the value
22388 of that key is used instead. For example, the Dutch digraph \qt{ij}
22389 should be converted to \qt{IJ}, so \file{bib2gls-en.xml} includes:
22390 \begin{verbatim}
22391 <entry key="grouptitle.case.ij">IJ</entry>
22392 \end{verbatim}
22393 (See the \longarg{group} switch for more details.)
22394 \item \meta{letter} This is the actual letter at the start of the
22395 given entry's \field{sort} field, which may be \idx!{lowercase} or may
22396 contain diacritics that don't appear in \meta{title}.
22397 \item \meta{id} A numeric identifier. This may be the collation key
22398 or the code point for the given letter, depending on the sort
22399 method.
22400 \item \meta{type} The entry's glossary type. If not known, this will
22401 be empty. (\bibgls\ won't know if you've modified the associated
22402 \csfmt{bibglsnew\ldots} command to set the \field{type}. It can only
22403 know the type if it's in the original \ext{bib} definition or is set
22404 using resource options such as \csopt{type}.)
22405 \end{itemize}
22406
22407 The \field{group} field is then set using:
22408 \begin{codeenv}
22409 \field{group}=\marg{\gls{bibglslettergroup}\margm{title}\margm{letter}\margm{id}\margm{type}}
22410 \end{codeenv}
22411 This field needs to expand to a simple label, which \gls!{bibglslettergroup}
22412 is designed to do. Note that non-letter groups are dealt with
22413 separately (see below).
22414
22415 \cssection{bibglssetlastgrouptitle}
22416
22417 In the last resource (\ext{glstex}) file, after all the relevant
22418 group titles have been set with the commands listed below, there's a
22419 final title setting:
22420 \formatdef{bibglssetlastgrouptitle}
22421 This does nothing by default, but the arguments are set to
22422 correspond to the group with the maximum id for that resource file.
22423 It's provided as a convenient way of overriding the final group
22424 title without the inconvenience of looking up the group label in the
22425 \ext{glstex} file. If you have multiple glossaries or if you want to
22426 override a different group, then you need to inspect the
22427 \ext{glstex} file to work out the corresponding label (by finding
22428 the \field{group} assignment for one of the entries in that group).
22429
22430 The \meta{cs} argument is the control sequence used in the
22431 \field{group} field to obtain the label from \meta{specs}. For
22432 example, if the highest \meta{id} is 2147418112 from:
22433 \begin{codeenv}
22434 \field{group}=\marg{\gls{bibglslettergroup}\marg{Ø}\marg{Ø}\marg{2147418112}\marg{}}
22435 \end{codeenv}
22436 then the last group is identified with:
22437 \begin{codeenv}
22438 \gls{bibglssetlastgrouptitle}\marg{\gls{bibglslettergroup}}\marg{\marg{Ø}\marg{Ø}\marg{2147418112}\marg{}}
22439 \end{codeenv}
22440 In this case \meta{cs} is \gls{bibglslettergroup} and \meta{specs}
22441 are the arguments for that command. If you want \gls{bibglssetlastgrouptitle}
22442 to change the group title then you need to define it before the
22443 \igls{resourceset}. For example:
22444 \begin{codeenv}
22445 \cs{newcommand}*\marg{\gls{bibglssetlastgrouptitle}}[2]\marg{\comment{}
22446 \cs{glsxtrsetgrouptitle}\marg{\idx{param}1\idx{param}2}\marg{Foreign Words}}
22447 \gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}}
22448 \end{codeenv}
22449 If you need to change a particular group title, then it has to be
22450 done after the \idx{resourceset}:
22451 \begin{codeenv}
22452 \gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}}
22453 \cs{glsxtrsetgrouptitle}
22454 \marg{\gls{bibglslettergroup}\marg{\marg{Ø}\marg{Ø}\marg{2147418112}\marg{}}}\comment{label}
22455 \marg{Foreign Words}\comment{title}
22456 \end{codeenv}
22457
22458 \cssection{bibglshypergroup}
22459
22460 \formatdef{bibglshypergroup}
22461
22462 If the \iext{log} file indicates that \isty{hyperref} has been loaded
22463 and the \longarg{group} switch is used, then this command will be
22464 used to create the navigation information for glossary styles such
22465 as \glostyle{indexhypergroup}. Note that this requires at least
22466 \isty{glossaries} v4.53 and \isty{glossaries-extra} v1.53. If older
22467 versions are detected, this command will simply ignore its
22468 arguments.
22469
22470 \subsection{Top-Level Groups Only}
22471 \label{sec:toplevelgroups}
22472 \renewcommand{\cssectioncmd}{\subsubsection}
22473
22474 The default \csopt{group-level} setting will only create groups for
22475 the \glspl{top-levelentry}. Any \glspl{sub-entry} are considered to
22476 be part of the \gls{top-levelentry}['s] group. If hierarchical
22477 groups are enabled, the commands defined in \sectionref{sec:hiergroups}
22478 are provided.
22479
22480 \cssection{bibglssetlettergrouptitle}
22481
22482 For each \idx{lettergroup} that's detected, \bibgls\ will write the line:
22483 \formatdef{bibglssetlettergrouptitle}
22484 in the \ext{glstex} file, which sets the group's title using:
22485 \begin{codeenv}
22486 \format{glsxtrsetgrouptitle}
22487 \end{codeenv}
22488 where the \meta{group label} part matches the corresponding \field{group}
22489 value.
22490
22491 Note that \gls{bibglssetlettergrouptitle} only has a single
22492 argument, but that argument contains the four arguments needed by
22493 \gls!{bibglslettergroup} and \gls!{bibglslettergrouptitle}.
22494 These arguments are as described above.
22495
22496 If \gls{glsxtrsetgrouptitle} has been defined (\sty{glossaries-extra}
22497 version 1.14 onwards), then \gls{bibglssetlettergrouptitle} will be
22498 defined as:
22499 \begin{codeenv}
22500 \cs{providecommand}\marg{\gls{bibglssetlettergrouptitle}}[1]\marg{\comment{}
22501 \cs{glsxtrsetgrouptitle}\marg{\gls{bibglslettergroup}\idx{param}1}\marg{\gls{bibglslettergrouptitle}\idx{param}1}}
22502 \end{codeenv}
22503 If an earlier version of \sty{glossaries-extra} is used, then this
22504 function can't be supported and the command will be defined to
22505 simply ignore its argument. This will fall back on the original
22506 method of just using \meta{title} as the label.
22507
22508 Since \gls{bibglssetlettergrouptitle} is used in the \ext{glstex} file to
22509 set the group titles, the associated commands need to be defined
22510 before the resource file is loaded if their definitions require
22511 modification. After the resource file has been loaded, you can
22512 adjust the title of a specific group, but you'll need to check the
22513 \ext{glstex} file for the appropriate arguments. For example, if the
22514 \ext{glstex} file contains:
22515 \begin{codeenv}
22516 \gls{bibglssetlettergrouptitle}\marg{\marg{\AE}\marg{\ae}\marg{7274496}\marg{}}
22517 \end{codeenv}
22518 but you actually want the group title to appear as \qt{\AE\ (AE)}
22519 instead of just \qt{\AE}, then after the resource file has been
22520 loaded you can do:
22521 \begin{codeenv}
22522 \gls{glsxtrsetgrouptitle}
22523 \marg{\gls{bibglslettergroup}\marg{\AE}\marg{\ae}\marg{7274496}\marg{}}\comment{label}
22524 \marg{\AE\ (AE)}\comment{title}
22525 \end{codeenv}
22526
22527 \cssection{bibglslettergroup}
22528
22529 \formatdef{bibglslettergroup}
22530 This command is used to determine the \idx{lettergroup} label. The
22531 default definition is \meta{type}\meta{id}, which ensures that no
22532 problematic characters occur in the label since \meta{type} can't
22533 contains special characters and \meta{id} is numeric. The
22534 \meta{type} is included in case there are multiple glossaries, since
22535 the hyperlink name must be unique.
22536
22537 \cssection{bibglslettergrouptitle}
22538
22539 \formatdef{bibglslettergrouptitle}
22540 This command is used to determine the \idx{lettergroup} title.
22541 The default definition is \ics{unexpanded}\margm{title}, which guards
22542 against any expansion issues that may arise with characters outside
22543 the basic Latin set.
22544
22545 For example:
22546 \begin{codeenv}
22547 \atentry{entry}\marg{angstrom,
22548 \field{name}=\marg{\cs{AA} ngstr\cs{umlaut}om}
22549 \field{description}=\marg{a unit of length equal to one hundred-millionth
22550 of a centimetre}
22551 }
22552 \end{codeenv}
22553 The \field{sort} value is \qtt{\AA ngstr\"om}. With \csopt[en]{sort}
22554 the \meta{title} part will be \code{A} but with \csopt[sv]{sort}
22555 the \meta{title} part will be \code{\AA}. In both cases the
22556 \meta{letter} argument will be \code{\AA}.
22557
22558 Take care if you are using a script that needs encapsulating. For
22559 example, with the \isty{CJKutf8} package the \idx{CJK} characters need to
22560 be placed within the \env{CJK} environment, so any letter group
22561 titles that contain \idx{CJK} characters will need special attention.
22562
22563 For example, suppose the \ext{bib} file contains entries in the
22564 form:
22565 \begin{codeenv}
22566 \atentry{dualentry}\marg{\meta{label},
22567 \field{name} = \marg{\gls{cjkname}\margm{\idx{CJK} characters}},
22568 \field{description} = \margm{English translation}
22569 }
22570 \end{codeenv}
22571 and the document contains:
22572 \begin{codeenv}
22573 \cmd{usepackage}\marg{CJKutf8}
22574 \cmd{usepackage}[\styopt{record},\styopt[indexgroup]{style},\styopt{nomain}]\marg{glossaries-extra}
22575 \strut
22576 \cs{newglossary*}\marg{japanese}\marg{Japanese to English}
22577 \cs{newglossary*}\marg{english}\marg{English to Japanese}
22578 \strut
22579 \ics{newrobustcmd}\marg{\gls{cjkname}}[1]\marg{\cmd{begin}\marg{CJK}\marg{UTF8}\marg{min}\idx{param}1\cmd{end}\marg{CJK}}
22580 \strut
22581 \gls{GlsXtrLoadResources}\oarg{
22582 \csopt[testcjk]{src},\comment{bib file}
22583 \csopt[ja-JP]{sort},\comment{locale used to sort \glspl{primaryentry}}
22584 \csopt[en-GB]{dual-sort},\comment{locale used to sort \glspl{dualentry}}
22585 \csopt[japanese]{type},\comment{put the \gls{primaryentry} in the 'japanese' glossary}
22586 \csopt[english]{dual-type},\comment{put the \gls{dualentry} in the 'english' glossary}
22587 \csopt[en.]{dual-prefix}
22588 }
22589 \end{codeenv}
22590 then \idx{CJK} characters will appear in the \meta{title} argument of
22591 \gls{bibglslettergrouptitle} which causes a problem because they need
22592 to be encapsulated within the \env{CJK} environment. This can be more
22593 conveniently done with the user supplied \inlinedef{cjkname}, but the \idx{CJK}
22594 characters need to be protected from expansion so \ics{unexpanded} is
22595 also needed. The new definition of \gls{bibglslettergrouptitle} needs
22596 to be defined before \gls{GlsXtrLoadResources}. For example:
22597 \begin{codeenv}
22598 \cs{newcommand}\marg{\gls{bibglslettergrouptitle}}[4]\marg{\cs{unexpanded}\marg{\gls{cjkname}\marg{\idx{param}1}}}
22599 \end{codeenv}
22600 There's a slight problem here in that the English letter group titles
22601 also end up encapsulated. An alternative approach is to use the
22602 \meta{type} part to provide different forms. For example:
22603 \begin{codeenv}
22604 \cs{newcommand}*\marg{\cmd{englishlettergroup}}[1]\marg{\idx{param}1}
22605 \cs{newcommand}*\marg{\cmd{japaneselettergroup}}[1]\marg{\gls{cjkname}\marg{\idx{param}1}}
22606 \cs{newcommand}\marg{\gls{bibglslettergrouptitle}}[4]\marg{\comment{}
22607 \cs{unexpanded}\marg{\cs{csuse}\marg{\idx{param}4lettergroup}\marg{\idx{param}1}}}
22608 \end{codeenv}
22609
22610 \cssection{bibglssetothergrouptitle}
22611
22612 The label and title for \idxpl{symbolgroup}
22613 are dealt with in a similar way to the \idxpl!{lettergroup}, but in this
22614 case the title is set using:
22615 \formatdef{bibglssetothergrouptitle}
22616 This is defined in an analogous manner:
22617 \begin{codeenv}
22618 \cs{providecommand}\marg{\gls{bibglssetothergrouptitle}}[1]\marg{\comment{}
22619 \cs{glsxtrsetgrouptitle}\marg{\gls{bibglsothergroup}\idx{param}1}\marg{\gls{bibglsothergrouptitle}\idx{param}1}}
22620 \end{codeenv}
22621 where the group label is obtained using \gls!{bibglsothergroup} and
22622 the group title is obtained from \gls!{bibglsothergrouptitle}.
22623 Note that since non-alphabetic characters don't have upper or lower
22624 case versions, there are only three arguments. The other difference
22625 between this and the letter group version is that the \meta{id} is
22626 given in hexadecimal format (corresponding to the character code).
22627
22628 For example, suppose my \ext{bib} file contains:
22629 \begin{codeenv}
22630 \atentry{entry}\marg{sauthor,
22631 \field{name}=\marg{/Author},
22632 \field{description} = \marg{author string}
22633 }
22634 \end{codeenv}
22635 If a locale sort is used, the leading slash \code{/} will be
22636 ignored and this entry will belong to the \qt{A} letter group using
22637 the letter commands described above. If, instead, one of the
22638 character code sort methods are used, such as
22639 \csopt[letter-case]{sort}, then this entry will be identified as
22640 belonging to a symbol (or \qt{other}) group and the title will be
22641 set using:
22642 \begin{codeenv}
22643 \gls{bibglssetothergrouptitle}\marg{\marg{/}\marg{2F}\marg{}}
22644 \end{codeenv}
22645
22646 \cssection{bibglsothergroup}
22647
22648 \formatdef{bibglsothergroup}
22649 This expands to the label for \idxpl{symbolgroup}. This just
22650 defaults to \code{glssymbols} (ignoring all arguments), which
22651 replicates the label used when \idx!{makeindex} or \idx!{xindy}
22652 generate the glossary files.
22653
22654 \cssection{bibglsothergrouptitle}
22655
22656 \formatdef{bibglsothergrouptitle}
22657 This expands to the title for \idxpl{symbolgroup}. This just
22658 expands to \ics{glssymbolsgroupname} by default.
22659
22660 \cssection{bibglssetemptygrouptitle}
22661
22662 Used when the sort value degenerates to an empty string. This command
22663 sets the label and title.
22664 \formatdef{bibglssetemptygrouptitle}
22665 (Note the inner group, as with the other similar
22666 \csfmt{bibglsset\ldots grouptitle} commands.)
22667
22668 \cssection{bibglsemptygroup}
22669
22670 \formatdef{bibglsemptygroup}
22671 This expands to the label for \idxpl{emptygroup}. This
22672 defaults to \code{glssymbols} to make it consistent with
22673 \idxpl{nonlettergroup} (since the sort value likely contained
22674 unknown symbol commands).
22675
22676 \cssection{bibglsemptygrouptitle}
22677
22678 \formatdef{bibglsemptygrouptitle}
22679 This expands to the group title for \idx{emptygroup}. This just
22680 expands to \ics{glssymbolsgroupname} by default.
22681
22682 \cssection{bibglssetnumbergrouptitle}
22683
22684 The numeric sort methods (\tableref{tab:sortoptionsnumerical})
22685 all create \idxpl{numbergroup} instead of letter
22686 or symbol groups. These behave in an analogous way to the above.
22687 \formatdef{bibglssetnumbergrouptitle}
22688 In this case \meta{value} is the actual numeric sort value, and
22689 \meta{id} is a decimal number obtained from converting \meta{value}
22690 to an integer. This command is defined as:
22691 \begin{codeenv}
22692 \cs{providecommand}\marg{\gls{bibglssetnumbergrouptitle}}[1]\marg{\comment{}
22693 \cs{glsxtrsetgrouptitle}\marg{\gls{bibglsnumbergroup}\idx{param}1}\marg{\gls{bibglsnumbergrouptitle}\idx{param}1}}
22694 \end{codeenv}
22695
22696 \cssection{bibglsnumbergroup}
22697
22698 The \idx{numbergroup} label is obtained from:
22699 \formatdef{bibglsnumbergroup}
22700 This just defaults to \code{glsnumbers}.
22701
22702 \cssection{bibglsnumbergrouptitle}
22703
22704 The \idx{numbergroup} title is obtained from:
22705 \formatdef{bibglsnumbergrouptitle}
22706 This just defaults to \ics{glsnumbersgroupname}.
22707
22708 \cssection{bibglssetdatetimegrouptitle}
22709
22710 The date-time sort methods (\tableref{tab:sortoptionsdatetime})
22711 create \idxpl{datetimegroup}. These behave in an analogous way to the above.
22712 \formatdef{bibglssetdatetimegrouptitle}
22713 This command is defined as:
22714 \begin{codeenv}
22715 \cs{providecommand}\marg{\gls{bibglssetdatetimegrouptitle}}[1]\marg{\comment{}
22716 \cs{glsxtrsetgrouptitle}
22717 \marg{\gls{bibglsdatetimegroup}\idx{param}1}\comment{}
22718 \marg{\gls{bibglsdatetimegrouptitle}\idx{param}1}\comment{}
22719 }
22720 \end{codeenv}
22721
22722 \cssection{bibglsdatetimegroup}
22723
22724 \formatdef{bibglsdatetimegroup}
22725
22726 This command is used for \idx{datetimegroup} labels with \optfmt{datetime} sorting
22727 (\tableref{tab:sortoptionsdatetime}). This has ten arguments, which means a
22728 little trickery is needed to deal with the tenth argument.
22729 The default definition is:
22730 \begin{codeenv}
22731 \cs{providecommand}\marg{\gls{bibglsdatetimegroup}}[9]\marg{\idx{param}1\idx{param}2\idx{param}3\ics{@firstofone}}
22732 \end{codeenv}
22733 This forms the group label from the year \meta{YYYY}, month \meta{MM},
22734 day \meta{DD} and \meta{type}.
22735
22736 \cssection{bibglsdatetimegrouptitle}
22737
22738 \formatdef{bibglsdatetimegrouptitle}
22739
22740 This command is used for \idx{datetimegroup} titles with \optfmt{datetime} sorting
22741 (\tableref{tab:sortoptionsdatetime}).
22742 The default definition is:
22743 \begin{codeenv}
22744 \cs{providecommand}\marg{\gls{bibglsdatetimegrouptitle}}[9]\marg{\idx{param}1-\idx{param}2-\idx{param}3\ics{@gobble}}
22745 \end{codeenv}
22746 This sets the title to the numeric
22747 \code{\meta{YYYY}-\meta{MM}-\meta{DD}}
22748 but may be redefined as appropriate.
22749
22750 \cssection{bibglssetdategrouptitle}
22751
22752 The date sort methods (\tableref{tab:sortoptionsdatetime})
22753 create \idxpl{dategroup} (the time isn't included). These behave in an
22754 analogous way to the above.
22755 \formatdef{bibglssetdategrouptitle}
22756 This command is defined as:
22757 \begin{codeenv}
22758 \cs{providecommand}\marg{\gls{bibglssetdategrouptitle}}[1]\marg{\comment{}
22759 \cs{glsxtrsetgrouptitle}\marg{\gls{bibglsdategroup}\idx{param}1}\marg{\gls{bibglsdategrouptitle}\idx{param}1}}
22760 \end{codeenv}
22761
22762 \cssection{bibglsdategroup}
22763
22764 \formatdef{bibglsdategroup}
22765
22766 This command is used for \idx{dategroup} labels with \optfmt{date} (no time) sorting
22767 (\tableref{tab:sortoptionsdatetime}). The default definition is:
22768 \begin{codeenv}
22769 \cs{providecommand}\marg{\gls{bibglsdategroup}}[7]\marg{\idx{param}1\idx{param}2\idx{param}4\idx{param}7}
22770 \end{codeenv}
22771 This forms the group label from the year, month, era and type.
22772 In this case, the era is a textual representation not the numeric
22773 value used in calculating the sort value.
22774
22775 \cssection{bibglsdategrouptitle}
22776
22777 \formatdef{bibglsdategrouptitle}
22778 This command is used for \idx{dategroup} titles with \optfmt{date} (no time) sorting
22779 (\tableref{tab:sortoptionsdatetime}). The default definition is:
22780 \begin{codeenv}
22781 \cs{providecommand}\marg{\gls{bibglsdategrouptitle}}[7]\marg{\idx{param}1-\idx{param}2}
22782 \end{codeenv}
22783 This just sets the title to the numeric year-month form
22784 \code{\meta{YYYY}-\meta{MM}}.
22785
22786 \cssection{bibglssettimegrouptitle}
22787
22788 The time sort methods (\tableref{tab:sortoptionsdatetime})
22789 create \idxpl{timegroup} (the date isn't included). These behave in an
22790 analogous way to the above.
22791 \formatdef{bibglssettimegrouptitle}
22792 This command is defined as:
22793 \begin{codeenv}
22794 \cs{providecommand}\marg{\gls{bibglssettimegrouptitle}}[1]\marg{\comment{}
22795 \cs{glsxtrsetgrouptitle}\marg{\gls{bibglstimegroup}\idx{param}1}\marg{\gls{bibglstimegrouptitle}\idx{param}1}}
22796 \end{codeenv}
22797
22798 \cssection{bibglstimegroup}
22799
22800 \formatdef{bibglstimegroup}
22801 This command is used for \idx{timegroup} labels with \optfmt{time} (no date) sorting
22802 (\tableref{tab:sortoptionsdatetime}).
22803 This command is defined as:
22804 \begin{codeenv}
22805 \cs{providecommand}\marg{\gls{bibglstimegroup}}[7]\marg{\idx{param}1\idx{param}2\idx{param}7}
22806 \end{codeenv}
22807
22808 \cssection{bibglstimegrouptitle}
22809
22810 \formatdef{bibglstimegrouptitle}
22811
22812 This command is used for \idx{timegroup} titles with \optfmt{time} (no date) sorting
22813 (\tableref{tab:sortoptionsdatetime}).
22814 This command is defined as:
22815 \begin{codeenv}
22816 \cs{providecommand}\marg{\gls{bibglstimegrouptitle}}[7]\marg{\idx{param}1}
22817 \end{codeenv}
22818
22819 \cssection{bibglssetunicodegrouptitle}
22820
22821 \formatdef{bibglssetunicodegrouptitle}
22822 This command is used to assign the group titles when the group
22823 formation is set to any value other than the default. For example,
22824 this command will be used with \csopt[codepoint]{group-formation}.
22825 The label is obtained from \gls{bibglsunicodegroup} and the title is
22826 obtained from \gls{bibglsunicodegrouptitle}.
22827
22828 \cssection{bibglsunicodegroup}
22829
22830 \formatdef{bibglsunicodegroup}
22831 The \meta{label} depends on the \csopt{group-formation} setting:
22832 \begin{itemize}
22833 \item\csopt[codepoint]{group-formation}: the \meta{label} is the
22834 Unicode value of \meta{character} (converted to \idx!{lowercase} and
22835 decomposed, if applicable);
22836 \item\csopt[unicode category]{group-formation}: the \meta{label} is the
22837 Unicode category of \meta{character} (for example, \code{Lu} means
22838 an \idx!{uppercase} letter);
22839 \item\csopt[unicode script]{group-formation}: the \meta{label} is the
22840 Unicode script associated with \meta{character} (for example,
22841 \code{LATIN});
22842 \item\csopt[unicode category and script]{group-formation}: the \meta{label}
22843 identifies both the Unicode category and script associated with
22844 \meta{character} (for example, \code{Lu.LATIN}).
22845 \end{itemize}
22846 (Similarly for \csopt{secondary-group-formation} and
22847 \csopt{dual-group-formation}.) By default this command expands to
22848 \meta{type}\meta{label}.
22849
22850 The \meta{character} is the first significant character of the sort
22851 value. The \meta{id} is the hexadecimal code of (possibly decomposed)
22852 \meta{character}. The case of codepoint \meta{id} may or may not correspond
22853 to the case of \meta{character}.
22854
22855 For example, with \csopt[codepoint]{group-formation}, an unset
22856 \field{type} and a sort value of \qt{\AA ngstr\"om} with \qt{\AA} as a
22857 significant character distinct from \qt{A} then the \field{group}
22858 field will be assigned using:
22859 \begin{codeenv}
22860 \field{group}=\marg{\gls{bibglsunicodegroup}\marg{å}\marg{Å}\marg{C5}\marg{}}
22861 \end{codeenv}
22862 whereas with \csopt[unicode category and script]{group-formation} it will be:
22863 \begin{codeenv}
22864 \field{group}=\marg{\gls{bibglsunicodegroup}\marg{Lu.LATIN}\marg{Å}\marg{C5}\marg{}}
22865 \end{codeenv}
22866 (\idx!{uppercase} Latin letter).
22867
22868 If instead \qt{\AA} is considered equivalent to \qt{A} according to the
22869 collator, then with \csopt[codepoint]{group-formation}, the value will be:
22870 \begin{codeenv}
22871 \field{group}=\marg{\gls{bibglsunicodegroup}\marg{a}\marg{Å}\marg{61}\marg{}}
22872 \end{codeenv}
22873 Note that the \meta{id} is now \hex{61} (the decomposed \qt{A}
22874 converted to \idx{lowercase}) not \hex{C5}.
22875
22876 \cssection{bibglsunicodegrouptitle}
22877
22878 \formatdef{bibglsunicodegrouptitle}
22879 The title for Unicode group formations is simply defined as
22880 \code{\cs{unexpanded}\margm{label}} so you will need to change it to
22881 something more appropriate. For example (before the \igls{resourceset}):
22882 \begin{codeenv}
22883 \cs{newcommand}\marg{\gls{bibglsunicodegrouptitle}}[4]\marg{\comment{}
22884 \ifnumhex{\idx{param}3}>64
22885 \ifnumhex{\idx{param}3} < 91
22886 A-{}-Z\comment{}
22887 \cmd{else}
22888 \ifnumhex{\idx{param}3} > 96
22889 \ifnumhex{\idx{param}3} < 123
22890 A-{}-Z\comment{}
22891 \cmd{fi}
22892 \cmd{fi}
22893 \cmd{fi}
22894 \cmd{fi}
22895 }
22896 \end{codeenv}
22897 This will make the title \qt{A--Z} if \meta{id} is greater
22898 than 64 and less than 91 or greater than 96 and less than 123
22899 (and will be empty otherwise).
22900
22901 Note that this setting can create an odd effect if the sorting
22902 causes the groups to be split up. For example, if some of the sort values
22903 start with extended or non-Latin characters this can break up the
22904 groups. First check how the group labels are assigned using:
22905 \begin{codeenv}
22906 \cs{newcommand}\marg{\gls{bibglsunicodegrouptitle}}\marg{\gls{bibglsunicodegroup}}
22907 \end{codeenv}
22908 then adjust the definition of \gls{bibglsunicodegroup} until the
22909 grouping is correct, and then change the definition of
22910 \gls{bibglsunicodegrouptitle} so that the title is correct.
22911
22912 \cssection{bibglssetmergedgrouptitle}
22913
22914 Used when groups are merged by \csopt{merge-small-groups}. This command
22915 sets the label and title.
22916 \formatdef{bibglssetmergedgrouptitle}
22917 (Note the inner group, as with the other similar
22918 \csfmt{bibglsset\ldots grouptitle} commands.)
22919
22920 \cssection{bibglsmergedgroup}
22921
22922 \formatdef{bibglsmergedgroup}
22923 This expands to the label for merged groups.
22924
22925 \cssection{bibglsmergedgrouptitle}
22926
22927 \formatdef{bibglsmergedgrouptitle}
22928 This expands to the group title for merged groups.
22929
22930 \cssection{bibglsmergedgroupfmt}
22931
22932 \formatdef{bibglsmergedgroupfmt}
22933 Used by \gls{bibglsmergedgrouptitle} and
22934 \gls{bibglsmergedgrouphierfmt} to format merged group titles. The
22935 first argument \meta{n} is the total number of groups that have been
22936 merged, the second argument, \meta{g$_1$} is the first group title,
22937 \marg{\meta{g$_2$}\ldots\meta{g$_n$}} are the middle group titles
22938 (empty if $\meta{n}=2$), and \meta{g$_n$} is the last group title.
22939
22940 The default definition is:
22941 \begin{codeenv}
22942 \cs{providecommand}\marg{\gls{bibglsmergedgroupfmt}}[4]\marg{\idx{param}2,
22943 \cs{ifcase}\idx{param}1\cmd{or}\cmd{or}\cmd{or} \idx{param}3,
22944 \cmd{else}\ldots, \cmd{fi} \idx{param}4}
22945 \end{codeenv}
22946
22947
22948 \subsection{Hierarchical Groups}
22949 \label{sec:hiergroups}
22950
22951 Hierarchical letter groups are set with analogous commands that have
22952 \code{hier} appended to the command name. There are also two extra
22953 arguments, \meta{parent} (the \gls{parententry}['s] label) and
22954 \meta{level} (the hierarchical level).
22955
22956 \cssection{bibglsgrouplevel}
22957
22958 \formatdef{bibglsgrouplevel}
22959 This command is used when \csopt{group-level} is used to apply group
22960 formations for different hierarchical levels. The \meta{label}
22961 argument is the label that would normally be applied to level~0.
22962 The \meta{n} argument is the hierarchical level (0 for
22963 \glspl{top-levelentry}). By default, this command simply expands to
22964 \meta{label}.
22965
22966 \cssection{bibglshiersubgrouptitle}
22967
22968 Hierarchical group titles are formatted using:
22969 \formatdef{bibglshiersubgrouptitle}
22970 This is defined as:
22971 \begin{codeenv}
22972 \cs{providecommand}\marg{\gls{bibglshiersubgrouptitle}}[3]\marg{\cs{ifnum}\idx{param}1>0 \cs{Glsxtrhiername}\marg{\idx{param}2} / \cmd{fi} \idx{param}3}
22973 \end{codeenv}
22974 The first argument \meta{level} is the hierarchical level, the
22975 second argument is the \gls{parententry} label (empty for
22976 $\meta{level}=0$), and the third argument \meta{title} is the
22977 normal title that would apply to the group with the default
22978 \csopt[0]{group-level} setting. Note that this uses
22979 \cs{Glsxtrhiername}\margm{parent} if $\meta{level}>0$.
22980 If this isn't required then redefine \gls{bibglshiersubgrouptitle}
22981 to simply expand to \meta{title} (\code{\idx{param}3}).
22982
22983 \cssection{bibglssetlettergrouptitlehier}
22984 \formatdef{bibglssetlettergrouptitlehier}
22985 As \gls{bibglssetlettergrouptitle} but used for hierarchical groups.
22986
22987 \cssection{bibglslettergrouphier}
22988 \formatdef{bibglslettergrouphier}
22989 As \gls{bibglslettergroup} but used for hierarchical groups. It
22990 expands to the hierarchical letter group label.
22991 This is defined as:
22992 \begin{codeenv}
22993 \cs{providecommand}\marg{\gls{bibglslettergrouphier}}[6]\marg{\idx{param}4\idx{param}5\idx{param}3}
22994 \end{codeenv}
22995
22996 \cssection{bibglslettergrouptitlehier}
22997 \formatdef{bibglslettergrouptitlehier}
22998 As \gls{bibglslettergrouptitle} but used for hierarchical groups. It
22999 expands to the hierarchical letter group title. This is defined as:
23000 \begin{codeenv}
23001 \cs{providecommand}\marg{\gls{bibglslettergrouptitlehier}}[6]\marg{\cs{protect}\gls{bibglshiersubgrouptitle}\marg{\idx{param}6}\marg{\idx{param}5}\marg{\cs{unexpanded}\marg{\idx{param}1}}}
23002 \end{codeenv}
23003
23004 \cssection{bibglssetothergrouptitlehier}
23005 \formatdef{bibglssetothergrouptitlehier}
23006 As \gls{bibglssetothergrouptitle} but used for hierarchical groups.
23007
23008 \cssection{bibglsothergrouphier}
23009 \formatdef{bibglsothergrouphier}
23010 As \gls{bibglsothergroup} but used for hierarchical groups. It
23011 expands to the hierarchical other group label.
23012 This is defined as:
23013 \begin{codeenv}
23014 \cs{providecommand}\marg{\gls{bibglsothergrouphier}}[5]\marg{\idx{param}3\idx{param}4glssymbols}
23015 \end{codeenv}
23016
23017 \cssection{bibglsothergrouptitlehier}
23018 \formatdef{bibglsothergrouptitlehier}
23019 As \gls{bibglsothergrouptitle} but used for hierarchical groups. It
23020 expands to the hierarchical other group title. This is defined as:
23021 \begin{codeenv}
23022 \cs{providecommand}\marg{\gls{bibglsothergrouptitlehier}}[5]\marg{\cs{protect}\gls{bibglshiersubgrouptitle}\marg{\idx{param}5}\marg{\idx{param}4}\marg{\cs{protect}\cs{glssymbolsgroupname}}}
23023 \end{codeenv}
23024
23025 \cssection{bibglssetemptygrouptitlehier}
23026 \formatdef{bibglssetemptygrouptitlehier}
23027 As \gls{bibglssetemptygrouptitle} but used for hierarchical groups.
23028
23029 \cssection{bibglsemptygrouphier}
23030 \formatdef{bibglsemptygrouphier}
23031 As \gls{bibglsemptygroup} but used for hierarchical groups. It
23032 expands to the hierarchical empty group label.
23033 This is defined as:
23034 \begin{codeenv}
23035 \cs{providecommand}\marg{\gls{bibglsemptygrouphier}}[3]\marg{\idx{param}1\idx{param}2glssymbols}
23036 \end{codeenv}
23037
23038 \cssection{bibglsemptygrouptitlehier}
23039 \formatdef{bibglsemptygrouptitlehier}
23040 As \gls{bibglsemptygrouptitle} but used for hierarchical groups. It
23041 expands to the hierarchical empty group title. This is defined as:
23042 \begin{codeenv}
23043 \cs{providecommand}\marg{\gls{bibglsemptygrouptitlehier}}[3]\marg{\cs{protect}\gls{bibglshiersubgrouptitle}\marg{\idx{param}3}\marg{\idx{param}2}\marg{\cs{protect}\cs{glssymbolsgroupname}}}
23044 \end{codeenv}
23045
23046 \cssection{bibglssetnumbergrouptitlehier}
23047 \formatdef{bibglssetnumbergrouptitlehier}
23048 As \gls{bibglssetnumbergrouptitle} but used for hierarchical groups.
23049
23050 \cssection{bibglsnumbergrouphier}
23051 \formatdef{bibglsnumbergrouphier}
23052 As \gls{bibglsnumbergroup} but used for hierarchical groups. It
23053 expands to the hierarchical number group label.
23054 This is defined as:
23055 \begin{codeenv}
23056 \cs{providecommand}\marg{\gls{bibglsnumbergrouphier}}[5]\marg{\idx{param}3\idx{param}4glsnumbers}
23057 \end{codeenv}
23058
23059 \cssection{bibglsnumbergrouptitlehier}
23060 \formatdef{bibglsnumbergrouptitlehier}
23061 As \gls{bibglsnumbergrouptitle} but used for hierarchical groups. It
23062 expands to the hierarchical number group title. This is defined as:
23063 \begin{codeenv}
23064 \cs{providecommand}\marg{\gls{bibglsnumbergrouptitlehier}}[5]\marg{\cs{protect}\gls{bibglshiersubgrouptitle}\marg{\idx{param}5}\marg{\idx{param}4}\marg{\cs{protect}\cs{glsnumbersgroupname}}}
23065 \end{codeenv}
23066
23067 \cssection{bibglssetdatetimegrouptitlehier}
23068 \formatdef{bibglssetdatetimegrouptitlehier}
23069 As \gls{bibglssetdatetimegrouptitle} but used for hierarchical groups.
23070
23071 \cssection{bibglsdatetimegrouphier}
23072 \formatdef{bibglsdatetimegrouphier}
23073 As \gls{bibglsdatetimegroup} but used for hierarchical groups. It
23074 expands to the hierarchical \idx{datetimegroup} label.
23075 Since this has more than 9 arguments, it is defined in two parts:
23076 \begin{codeenv}
23077 \cs{providecommand}\marg{\gls{bibglsdatetimegrouphier}}[9]\marg{\idx{param}1\idx{param}2\idx{param}3\gls{bibglsdatetimegrouphierfinalargs}}
23078 \end{codeenv}
23079 The final arguments are obtained with \gls{bibglsdatetimegrouphierfinalargs}.
23080
23081 \cssection{bibglsdatetimegrouphierfinalargs}
23082 \formatdef{bibglsdatetimegrouphierfinalargs}
23083 This picks up the final three arguments for \gls{bibglsdatetimegrouphier}:
23084 \begin{codeenv}
23085 \cs{providecommand}*\marg{\gls{bibglsdatetimegrouphierfinalargs}}[3]\marg{\idx{param}1\idx{param}2}
23086 \end{codeenv}
23087
23088 \cssection{bibglsdatetimegrouptitlehier}
23089 \formatdef{bibglsdatetimegrouptitlehier}
23090 As \gls{bibglsdatetimegrouptitle} but used for hierarchical groups. It
23091 expands to the hierarchical \idx{datetimegroup} title.
23092 Since this has more than 9 arguments, it is defined in two parts:
23093 \begin{codeenv}
23094 \cs{providecommand}\marg{\gls{bibglsdatetimegrouptitlehier}}[9]\marg{\gls{bibglsdatetimegrouptitlehierfinalargs}\marg{\idx{param}1-\idx{param}2-\idx{param}3}}
23095 \end{codeenv}
23096 The final arguments are obtained with \gls{bibglsdatetimegrouptitlehierfinalargs}.
23097
23098 \cssection{bibglsdatetimegrouptitlehierfinalargs}
23099 \formatdef{bibglsdatetimegrouptitlehierfinalargs}
23100 This picks up the final three arguments for \gls{bibglsdatetimegrouptitlehier}:
23101 \begin{codeenv}
23102 \cs{providecommand}*\marg{\gls{bibglsdatetimegrouptitlehierfinalargs}}[4]\marg{\cs{protect}\gls{bibglshiersubgrouptitle}\marg{\idx{param}4}\marg{\idx{param}3}\marg{\idx{param}1}}
23103 \end{codeenv}
23104 In this case, the first argument is set by
23105 \gls{bibglsdatetimegrouptitlehier} to the date
23106 (\code{\meta{YYYY}-\meta{MM}-\meta{DD}}). The remaining arguments
23107 are the \meta{type}, \meta{parent} and \meta{level} information.
23108
23109 \cssection{bibglssetdategrouptitlehier}
23110 \formatdef{bibglssetdategrouptitlehier}
23111 As \gls{bibglssetdategrouptitle} but used for hierarchical groups.
23112
23113 \cssection{bibglsdategrouphier}
23114 \formatdef{bibglsdategrouphier}
23115 As \gls{bibglsdategroup} but used for hierarchical groups. It
23116 expands to the hierarchical date group label.
23117 This is defined as:
23118 \begin{codeenv}
23119 \cs{providecommand}\marg{\gls{bibglsdategrouphier}}[9]\marg{\idx{param}1\idx{param}2\idx{param}4\idx{param}7\idx{param}8}
23120 \end{codeenv}
23121
23122 \cssection{bibglsdategrouptitlehier}
23123 \formatdef{bibglsdategrouptitlehier}
23124 As \gls{bibglsdategrouptitle} but used for hierarchical groups. It
23125 expands to the hierarchical date group title. This is defined as:
23126 \begin{codeenv}
23127 \cs{providecommand}\marg{\gls{bibglsdategrouptitlehier}}[9]\marg{\cs{protect}\gls{bibglshiersubgrouptitle}\marg{\idx{param}9}\marg{\idx{param}8}\marg{\idx{param}1-\idx{param}2}}
23128 \end{codeenv}
23129
23130 \cssection{bibglssettimegrouptitlehier}
23131 \formatdef{bibglssettimegrouptitlehier}
23132 As \gls{bibglssettimegrouptitle} but used for hierarchical groups.
23133
23134 \cssection{bibglstimegrouphier}
23135 \formatdef{bibglstimegrouphier}
23136 As \gls{bibglstimegroup} but used for hierarchical groups. It
23137 expands to the hierarchical time group label. This is defined as:
23138 \begin{codeenv}
23139 \cs{providecommand}\marg{\gls{bibglstimegrouphier}}[9]\marg{\idx{param}1\idx{param}2\idx{param}7\idx{param}8}
23140 \end{codeenv}
23141
23142 \cssection{bibglstimegrouptitlehier}
23143 \formatdef{bibglstimegrouptitlehier}
23144 As \gls{bibglstimegrouptitle} but used for hierarchical groups. It
23145 expands to the hierarchical time group title. This is defined as:
23146 \begin{codeenv}
23147 \cs{providecommand}\marg{\gls{bibglstimegrouptitlehier}}[9]\marg{\cs{protect}\gls{bibglshiersubgrouptitle}\marg{\idx{param}9}\marg{\idx{param}8}{\idx{param}1}}
23148 \end{codeenv}
23149
23150 \cssection{bibglssetunicodegrouptitlehier}
23151 \formatdef{bibglssetunicodegrouptitlehier}
23152 As \gls{bibglssetunicodegrouptitle} but used for hierarchical groups.
23153
23154 \cssection{bibglsunicodegrouphier}
23155 \formatdef{bibglsunicodegrouphier}
23156 As \gls{bibglsunicodegroup} but used for hierarchical groups. This
23157 expands to the hierarchical group label:
23158 \begin{codeenv}
23159 \cs{providecommand}\marg{\gls{bibglsunicodegrouphier}}[6]\marg{\idx{param}4\idx{param}5\idx{param}3}
23160 \end{codeenv}
23161
23162 \cssection{bibglsunicodegrouptitlehier}
23163 \formatdef{bibglsunicodegrouptitlehier}
23164 As \gls{bibglsunicodegrouptitle} but used for hierarchical groups. This
23165 expands to the hierarchical group title:
23166 \begin{codeenv}
23167 \cs{providecommand}\marg{\gls{bibglsunicodegrouptitlehier}}[6]\marg{\cs{protect}\gls{bibglshiersubgrouptitle}\marg{\idx{param}6}\marg{\idx{param}5}\marg{\cs{unexpanded}\marg{\idx{param}1}}}
23168 \end{codeenv}
23169
23170 \cssection{bibglssetmergedgrouptitlehier}
23171 \formatdef{bibglssetmergedgrouptitlehier}
23172 As \gls{bibglssetmergedgrouptitle} but used for hierarchical groups.
23173
23174 \cssection{bibglsmergedgrouphier}
23175 \formatdef{bibglsmergedgrouphier}
23176 As \gls{bibglsmergedgroup} but used for hierarchical groups. This
23177 expands to the hierarchical group label:
23178 \begin{codeenv}
23179 \cs{providecommand}\marg{\gls{bibglsmergedgrouphier}}[8]\marg{merged.\idx{param}1}
23180 \end{codeenv}
23181
23182 \cssection{bibglsmergedgrouptitlehier}
23183 \formatdef{bibglsmergedgrouptitlehier}
23184 As \gls{bibglsmergedgrouptitle} but used for hierarchical groups. This
23185 expands to the hierarchical group title:
23186 \begin{codeenv}
23187 \cs{providecommand}\marg{\gls{bibglsmergedgrouptitlehier}}[8]\marg{\comment{}
23188 \cs{unexpanded}\marg{\cs{ifnum}\idx{param}8=0\gls{bibglsmergedgroupfmt}\marg{\idx{param}3}\marg{\idx{param}4}\marg{\idx{param}5}\marg{\idx{param}6}\cmd{else}\gls{bibglsmergedgrouphierfmt}\marg{\idx{param}3}\marg{\idx{param}4}\marg{\idx{param}5}\marg{\idx{param}6}\cmd{fi}}\comment{}
23189 }
23190 \end{codeenv}
23191 This uses \gls{bibglsmergedgroupfmt} ($\meta{level}=0$) or
23192 \gls{bibglsmergedgrouphierfmt} ($\meta{level}>0$) to format the title.
23193
23194 \cssection{bibglsmergedgrouphierfmt}
23195
23196 \formatdef{bibglsmergedgrouphierfmt}
23197 Used by \gls{bibglsmergedgrouphierfmt} to format merged hierarchical group titles.
23198 The first argument \meta{n} is the total number of groups that have been
23199 merged, the second argument, \meta{g$_1$} is the first group title,
23200 \marg{\meta{g$_2$}\ldots\meta{g$_n$}} are the middle group titles
23201 (empty if $\meta{n}=2$), and \meta{g$_n$} is the last group title.
23202
23203 The default definition depends on whether or not \bibgls\ has
23204 detected \sty{hyperref} in the document's \ext{log} file. If it has,
23205 then the definition is:
23206 \begin{codeenv}
23207 \cs{providecommand}\marg{\gls{bibglsmergedgrouphierfmt}}[4]\marg{\idx{param}2,
23208 \ics{texorpdfstring}\marg{\marg{\cs{def}\gls{bibglshiersubgrouptitle}\idx{param}\idx{param}1\idx{param}\idx{param}2\idx{param}\idx{param}3{\idx{param}\idx{param}3}\cs{ifcase}\idx{param}1\cmd{or}\cmd{or}\cmd{or}
23209 \idx{param}3, \cmd{else}\cmd{ldots}, \cmd{fi}
23210 \idx{param}4}}\marg{\cs{ifcase}\idx{param}1\cmd{or}\cmd{or}\cmd{or}
23211 \idx{param}3, \cmd{else}\cmd{ldots}, \cmd{fi} \idx{param}4}}
23212 \end{codeenv}
23213 Otherwise the definition is:
23214 \begin{codeenv}
23215 \cs{providecommand}\marg{\gls{bibglsmergedgrouphierfmt}}[4]\marg{\idx{param}2,
23216 \marg{\cs{def}\gls{bibglshiersubgrouptitle}\idx{param}\idx{param}1\idx{param}\idx{param}2\idx{param}\idx{param}3{\idx{param}\idx{param}3}\cs{ifcase}\idx{param}1\cmd{or}\cmd{or}\cmd{or}
23217 \idx{param}3, \cmd{else}\cmd{ldots}, \cmd{fi}
23218 \idx{param}4}}
23219 \end{codeenv}
23220 This locally redefines \gls{bibglshiersubgrouptitle} to just do its
23221 final argument to allow for a more compact title.
23222
23223 \renewcommand{\cssectioncmd}{\subsection}
23224 \section{Flattened Entries}
23225 \label{sec:flattendefs}
23226
23227 These commands relate to the way the \field{name} field is altered
23228 when flattening \glspl{lonelychildentry} with the \csopt{flatten-lonely}
23229 option.
23230
23231 \cssection{bibglsflattenedhomograph}
23232
23233 \formatdef{bibglsflattenedhomograph}
23234 The default definition simply does \meta{name}.
23235
23236 This command is used if the \child\ and \parent\ names are identical.
23237 For example, suppose the \ext{bib} file contains:
23238 \begin{codeenv}
23239 \atentry{index}\marg{super.glossary, \field{name}=\marg{glossary}}
23240 \strut
23241 \atentry{entry}\marg{glossarycol,
23242 \field{parent}=\marg{super.glossary},
23243 \field{description}=\marg{collection of glosses}
23244 }
23245 \strut
23246 \atentry{entry}\marg{glossarylist,
23247 \field{parent}=\marg{super.glossary},
23248 \field{description}=\marg{list of technical words}
23249 }
23250 \end{codeenv}
23251 The \glspl{childentry} don't have a \field{name} field, so the value is assumed
23252 to be the same as the \glsdisp{parententry}{parent's} \field{name} field.
23253 Here's an example document where both \glspl{childentry} are used:
23254 \begin{codeenv}
23255 \cmd{documentclass}\marg{article}
23256 \strut
23257 \cmd{usepackage}[\styopt{record},\istyopt{subentrycounter},\styopt[treenoname]{style}]\marg{glossaries-extra}
23258 \strut
23259 \gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}}
23260 \strut
23261 \cmd{begin}\marg{document}
23262 \cs{gls}\marg{glossarycol} (collection) vs \cs{gls}\marg{glossarylist} (list).
23263 \strut
23264 \cs{printunsrtglossary}
23265 \cmd{end}\marg{document}
23266 \end{codeenv}
23267 This uses one of the glossary styles designed for \iglspl{homograph} and the
23268 glossary has the structure:
23269 \begin{flushleft}
23270 \textbf{glossary}\par
23271 \quad 1) collection of glosses 1\par
23272 \quad 2) list of technical words 1
23273 \end{flushleft}
23274 If \glsdisp{lonelychildentry}{only one child entry} is selected, then the result looks a little
23275 odd. For example:
23276 \begin{flushleft}
23277 \textbf{glossary}\par
23278 \quad 1) collection of glosses 1
23279 \end{flushleft}
23280 With the \csopt{flatten-lonely} option, the \parent\ is removed and
23281 the \child\ is moved up a \hierarchicallevel. With
23282 \csopt[postsort]{flatten-lonely} this would normally adjust the
23283 name so that it appears as \meta{parent name}, \meta{child name}
23284 but in this case it would look a little odd for the name to
23285 appear as \qt{glossary, glossary} so instead the name is
23286 set to:
23287 \begin{codeenv}
23288 \gls{bibglsflattenedhomograph}\marg{glossary}\marg{super.glossary}
23289 \end{codeenv}
23290 (where the first argument is the original name and the second argument is the
23291 label of the \gls{parententry}).
23292
23293 This means that the name simply appears as \qt{glossary}, even if
23294 the \csopt[postsort]{flatten-lonely} option is used. Note that if
23295 the \gls{parententry} is removed, the \parent\ label won't be of
23296 much use. You can test for existence using \ics{ifglsentryexists}
23297 in case you want to vary the way the name is displayed according to
23298 whether or not the \parent\ is still present.
23299
23300 \cssection{bibglsflattenedchildpresort}
23301
23302 \formatdef{bibglsflattenedchildpresort}
23303
23304 Used by the \csopt[presort]{flatten-lonely} option. This defaults
23305 to just \meta{child name}. If you want to change this, remember that
23306 you can let the interpreter know by adding the definition to
23307 \atentry{preamble}. For example:
23308 \begin{codeenv}
23309 \atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\gls{bibglsflattenedchildpresort}}[2]\marg{\idx{param}1 (\idx{param}2)}}}
23310 \end{codeenv}
23311
23312 \cssection{bibglsflattenedchildpostsort}
23313
23314 \formatdef{bibglsflattenedchildpostsort}
23315
23316 Used by the \csopt[postsort]{flatten-lonely} option. This defaults
23317 to \code{\meta{parent name}, \meta{child name}}.
23318
23319 Note that the arguments are in the reverse order to those of the
23320 previous command. This is done to assist the automated first letter
23321 upper-casing. If either command is redefined to alter the ordering,
23322 then this can confuse the case-changing mechanism, in which case you
23323 may want to consider switching on the expansion of the \field{name}
23324 field using:
23325 \begin{codeenv}
23326 \gls{glssetexpandfield}\marg{name}
23327 \end{codeenv}
23328 (before \gls{GlsXtrLoadResources}).
23329
23330 \section{Other}
23331
23332 \cssection{bibglscopytoglossary}
23333
23334 \formatdef{bibglscopytoglossary}
23335 This command is provided if the \csopt{copy-to-glossary} option is
23336 set and is used to copy an entry to another glossary. The definition
23337 is:
23338 \begin{codeenv}
23339 \cmd{providecommand}\marg{\gls{bibglscopytoglossary}}[2]{\comment{}
23340 \ics{ifglossaryexists*}\marg{}\comment{}
23341 \marg{\ics{GlsXtrIfInGlossary}\marg{\idx{param}1}\marg{\idx{param}2}\marg{}\marg{\ics{glsxtrcopytoglossary}\marg{\idx{param}1}\marg{\idx{param}2}}}\comment{}
23342 \marg{}\comment{}
23343 }
23344 \end{codeenv}
23345 This ensures that the entry is only copied if the glossary exists
23346 and if the entry hasn't already been copied to it.
23347
23348 This command isn't used by the \csopt[copy]{action} or
23349 \csopt[copy or define]{action} settings, which use \ics{glsxtrcopytoglossary}
23350 directly.
23351
23352 \cssection{bibglssettotalrecordcount}
23353
23354 \formatdef{bibglssettotalrecordcount}
23355 This command is provided if \longarg{record-count} is used. It's
23356 used to set the \field{recordcount} field to the total number of
23357 records for the given entry. This is defined as:
23358 \begin{codeenv}
23359 \cmd{providecommand}*\marg{\gls{bibglssettotalrecordcount}}[2]\marg{\comment{}
23360 \cs{GlsXtrSetField}\marg{\idx{param}1}\marg{\field{recordcount}}\marg{\idx{param}2}\comment{}
23361 }
23362 \end{codeenv}
23363
23364 \cssection{bibglssetrecordcount}
23365
23366 \formatdef{bibglssetrecordcount}
23367 This command is provided if \longarg{record-count} is used. It's
23368 used to set the \field{recordcount.counter} field to the total number of
23369 records associated with the given counter for the given entry. This
23370 is defined as:
23371 \begin{codeenv}
23372 \cmd{providecommand}*\marg{\gls{bibglssetrecordcount}}[3]\marg{\comment{}
23373 \cs{GlsXtrSetField}\marg{\idx{param}1}\marg{recordcount.\idx{param}2}\marg{\idx{param}3}\comment{}
23374 }
23375 \end{codeenv}
23376
23377 \cssection{bibglssetlocationrecordcount}
23378
23379 \formatdef{bibglssetlocationrecordcount}
23380 This command is provided if \longarg{record-count-unit} is used.
23381 It's used to set the \field{recordcount.counter.location} field to
23382 the total number of records associated with the given location for
23383 the given entry. This is defined as:
23384 \begin{codeenv}
23385 \cmd{providecommand}*\marg{\gls{bibglssetlocationrecordcount}}[4]\marg{\comment{}
23386 \cs{GlsXtrSetField}\marg{\idx{param}1}\marg{recordcount.\idx{param}2.\ics{glsxtrdetoklocation}\idx{param}3}\marg{\idx{param}4}\comment{}
23387 }
23388 \end{codeenv}
23389
23390 \cssection{bibglshyperlink}
23391
23392 \formatdef{bibglshyperlink}
23393 Used by the \hyperref[sec:dualoptsbacklinks]{back link options},
23394 this just defaults to:
23395 \begin{codeenv}
23396 \ics{glshyperlink}\oargm{text}\margm{label}
23397 \end{codeenv}
23398
23399 \cssection{bibglssetwidest}
23400
23401 \formatdef{bibglssetwidest}
23402 This is used by \csopt{set-widest} to set the widest name for the
23403 given \hierarchicallevel\ where the glossary type can't be determined.
23404 This is defined as:
23405 \begin{codeenv}
23406 \cs{providecommand}*\marg{\gls{bibglssetwidest}}[2]\marg{\cs{glsxtrSetWidest}\marg{}\marg{\idx{param}1}\marg{\idx{param}2}}
23407 \end{codeenv}
23408 if \ics{glsxtrSetWidest} has been defined, or:
23409 \begin{codeenv}
23410 \cs{providecommand}*\marg{\gls{bibglssetwidest}}[2]\marg{\cs{glsupdatewidest}\oarg{\idx{param}1}\marg{\idx{param}2}}
23411 \end{codeenv}
23412 if \ics{glsupdatewidest} is defined, otherwise it will be
23413 defined to use \ics{glssetwidest}:
23414 \begin{codeenv}
23415 \cs{providecommand}*\marg{\gls{bibglssetwidest}}[2]\marg{\cs{glssetwidest}\oarg{\idx{param}1}\marg{\idx{param}2}}
23416 \end{codeenv}
23417 Since this isn't scoped, this will affect other glossaries.
23418 In general, if you have more than one glossary it's best to
23419 set the \field{type} using options like \csopt{type}.
23420
23421 \cssection{bibglssetwidestfortype}
23422
23423 \formatdef{bibglssetwidestfortype}
23424 This is used by \csopt{set-widest} to set the widest name for the
23425 given \hierarchicallevel\ where the glossary type is known. This
23426 is defined as:
23427 \begin{codeenv}
23428 \cs{providecommand}*\marg{\gls{bibglssetwidestfortype}}[3]\marg{\comment{}
23429 \cs{glsxtrSetWidest}\marg{\idx{param}1}\marg{\idx{param}2}\marg{\idx{param}3}\comment{}
23430 }
23431 \end{codeenv}
23432 if \ics{glsxtrSetWidest} has been defined, or:
23433 \begin{codeenv}
23434 \cs{providecommand}*\marg{\gls{bibglssetwidestfortype}}[3]\marg{\comment{}
23435 \cs{apptoglossarypreamble}\oarg{\idx{param}1}\marg{\cs{glsupdatewidest}\oarg{\idx{param}2}\marg{\idx{param}3}}\comment{}
23436 }
23437 \end{codeenv}
23438 if \ics{glsupdatewidest} is defined, otherwise it will be
23439 defined to use \ics{glssetwidest}:
23440 \begin{codeenv}
23441 \cs{providecommand}*\marg{\gls{bibglssetwidestfortype}}[3]\marg{\comment{}
23442 \cs{apptoglossarypreamble}\oarg{\idx{param}1}\marg{\cs{glssetwidest}\oarg{\idx{param}2}\marg{\idx{param}3}}\comment{}
23443 }
23444 \end{codeenv}
23445 Since the glossary preamble is scoped, this won't affect other
23446 glossaries.
23447
23448 \cssection{bibglssetwidestfallback}
23449
23450 \formatdef{bibglssetwidestfallback}
23451 This is used by \csopt{set-widest} instead of \gls{bibglssetwidest}
23452 when all \field{name} fields end up as an empty string when
23453 interpreted by \bibgls. This typically means that all the
23454 \field{name} fields contain unknown commands. This fallback command
23455 will use:
23456 \begin{codeenv}
23457 \ics{glsxtrSetWidestFallback}\marg{2}\margm{glossary list}
23458 \end{codeenv}
23459 if defined otherwise it will use \ics{glsFindWidestLevelTwo}, which
23460 sets the widest name for the \glsdisp{top-levelentry}{top-level} and
23461 first two sub-levels across all the listed glossaries.
23462
23463 \cssection{bibglssetwidestfortypefallback}
23464
23465 \formatdef{bibglssetwidestfortypefallback}
23466 This is used by \csopt{set-widest} instead of
23467 \gls{bibglssetwidestfortype}
23468 when all \field{name} fields end up as an empty string when
23469 interpreted by \bibgls. This typically means that all the
23470 \field{name} fields contain unknown commands. This fallback command
23471 will append \gls{bibglssetwidestfallback} to the glossary preamble
23472 for the given type.
23473
23474 \cssection{bibglssetwidesttoplevelfallback}
23475
23476 \formatdef{bibglssetwidesttoplevelfallback}
23477 This is used by \csopt{set-widest} instead of \gls{bibglssetwidest}
23478 when all \field{name} fields end up as an empty string when
23479 interpreted by \bibgls. This typically means that all the
23480 \field{name} fields contain unknown commands. This fallback command
23481 will use:
23482 \begin{codeenv}
23483 \ics{glsxtrSetWidestFallback}\marg{0}\margm{glossary list}
23484 \end{codeenv}
23485 if defined otherwise it will use \ics{glsFindWidestTopLevelName},
23486 which sets the widest name for the \glsdisp{top-levelentry}{top-level}.
23487
23488 \cssection{bibglssetwidesttoplevelfortypefallback}
23489
23490 \formatdef{bibglssetwidesttoplevelfortypefallback}
23491 This is used by \csopt{set-widest} instead of
23492 \gls{bibglssetwidestfortype}
23493 when all \field{name} fields end up as an empty string when
23494 interpreted by \bibgls. This typically means that all the
23495 \field{name} fields contain unknown commands. This fallback command
23496 will append \gls{bibglssetwidesttoplevelfallback} to the glossary
23497 preamble of the given type.
23498
23499 \cssection{bibglscontributorlist}
23500
23501 \formatdef{bibglscontributorlist}
23502 This is used when \csopt{bibtex-contributor-fields} is set. The
23503 definition depends on whether or not \ics{DTLformatlist} has been
23504 defined:
23505 \begin{codeenv}
23506 \ics{ifdef}\cs{DTLformatlist}
23507 \marg{\comment{datatool v2.28+}
23508 \cs{providecommand}*\marg{\gls{bibglscontributorlist}}[2]\marg{\cs{DTLformatlist}\marg{\idx{param}1}}
23509 }
23510 \marg{\comment{datatool v2.27 or earlier}
23511 \cs{providecommand}*\marg{\gls{bibglscontributorlist}}[2]\marg{\comment{}
23512 \ics{def}\cmd{bibgls@sep}\marg{}\comment{}
23513 \ics{@for}\cmd{bibgls@item}:=\idx{param}1\cmd{do}\marg{\cmd{bibgls@sep}\cmd{bibgls@item}\cs{def}\cmd{bibgls@sep}\marg{, }}\comment{}
23514 }
23515 }
23516 \end{codeenv}
23517 The second argument allows you to provide definitions like:
23518 \begin{codeenv}
23519 \cs{newcommand}*\marg{\gls{bibglscontributorlist}}[2]\marg{\comment{}
23520 \cs{ifcase}\idx{param}2
23521 \cmd{or}
23522 name:
23523 \cmd{else}
23524 names:
23525 \cmd{fi}
23526 \cs{DTLformatlist}\marg{\idx{param}1}\comment{}
23527 }
23528 \end{codeenv}
23529
23530 \cssection{bibglscontributor}
23531
23532 \formatdef{bibglscontributor}
23533 This is used when \csopt{bibtex-contributor-fields} is set. The
23534 definition depends on the value of \csopt{contributor-order}. Note that if you
23535 have multiple resource sets, that option governs the way \bibgls's version of
23536 \gls{bibglscontributor} behaves. The definition is written to the \ext{glstex}
23537 using \cs{providecommand}, so \LaTeX\ will only pick up the first definition.
23538
23539 \cssection{bibglsdatetime}
23540
23541 \formatdef{bibglsdatetime}
23542 Used to encapsulate date-time fields identified with
23543 \csopt{date-time-fields}.
23544 Since \gls{bibglsdatetime} requires more than nine arguments, the
23545 remaining four arguments are picked up with:
23546 \nosecdef{bibglsdatetimeremainder}
23547 The default definitions are:
23548 \begin{codeenv}
23549 \cs{providecommand}\marg{\gls{bibglsdatetime}}[9]\marg{\gls{bibglsdatetimeremainder}}
23550 \cs{providecommand}\marg{\gls{bibglsdatetimeremainder}}[4]\marg{\idx{param}4}
23551 \end{codeenv}
23552
23553 \cssection{bibglsdate}
23554
23555 \formatdef{bibglsdate}
23556 Used to encapsulate date fields identified with
23557 \csopt{date-fields}.
23558 The default definition is:
23559 \begin{codeenv}
23560 \cs{providecommand}\marg{\gls{bibglsdate}}[7]\marg{\idx{param}7}
23561 \end{codeenv}
23562
23563 \cssection{bibglstime}
23564
23565 \formatdef{bibglstime}
23566 Used to encapsulate date fields identified with
23567 \csopt{time-fields}.
23568 The default definition is:
23569 \begin{codeenv}
23570 \cs{providecommand}\marg{\gls{bibglstime}}[7]\marg{\idx{param}7}
23571 \end{codeenv}
23572
23573 \cssection{bibglsprimaryprefixlabel}
23574
23575 \formatdef{bibglsprimaryprefixlabel}
23576 A hook to pick up the \primary\ prefix label (identified with
23577 \csopt{label-prefix}) if required. This does nothing by default. If
23578 required, this command should be defined before the
23579 \igls{resourceset} is loaded.
23580
23581 \cssection{bibglsdualprefixlabel}
23582
23583 \formatdef{bibglsdualprefixlabel}
23584 A hook to pick up the \dual\ prefix label (identified with
23585 \csopt{dual-prefix}) if required. This does nothing by default. If
23586 required, this command should be defined before the
23587 \igls{resourceset} is loaded.
23588
23589 \cssection{bibglstertiaryprefixlabel}
23590
23591 \formatdef{bibglstertiaryprefixlabel}
23592 A hook to pick up the \glsdisp{tertiaryentry}{tertiary} prefix label (identified with
23593 \csopt{tertiary-prefix}) if required. This does nothing by default. If
23594 required, this command should be defined before the
23595 \igls{resourceset} is loaded.
23596
23597 \cssection{bibglsexternalprefixlabel}
23598
23599 \formatdef{bibglsexternalprefixlabel}
23600 A hook to pick up the \meta{n}th external prefix label (identified with
23601 \csopt{ext-prefixes}) if required. This does nothing by default and
23602 won't be used if the list of external prefixes is empty. If required,
23603 this command should be defined before the \igls{resourceset} is
23604 loaded.
23605
23606 \cssection{bibglshashchar}
23607
23608 \formatdef{bibglshashchar}
23609 Expands to a literal hash character (\,\idx{hashchar}\,).
23610
23611 \cssection{bibglsunderscorechar}
23612
23613 \formatdef{bibglsunderscorechar}
23614 Expands to a literal underscore character (\,\idx{underscorechar}\,).
23615
23616 \cssection{bibglsdollarchar}
23617
23618 \formatdef{bibglsdollarchar}
23619 Expands to a literal dollar character (\,\idx{dollarchar}\,).
23620
23621 \cssection{bibglsampersandchar}
23622
23623 \formatdef{bibglsampersandchar}
23624 Expands to a literal ampersand character (\,\idx{ampchar}\,).
23625
23626 \cssection{bibglscircumchar}
23627
23628 \formatdef{bibglscircumchar}
23629 Expands to a literal circumflex character (\,\idx{circumchar}\,).
23630
23631 \cssection{bibglsaposchar}
23632
23633 \formatdef{bibglsaposchar}
23634 Expands to a literal apostrophe character (\,\idx{aposchar}\,).
23635 This command is only provided if \longarg{replace-quotes} is used.
23636
23637 \cssection{bibglsdoublequotechar}
23638
23639 \formatdef{bibglsdoublequotechar}
23640 Expands to a literal double-quote character (\,\idx{doublequotechar}\,).
23641 This command is only provided if \longarg{replace-quotes} is used.
23642
23643 \cssection{bibglsuppercase}
23644
23645 \formatdef{bibglsuppercase}
23646 Converts \meta{text} to \idx{uppercase}. This just uses
23647 \ics{glsuppercase} (if \sty{glossaries} v4.50+,
23648 \sty{glossaries-extra} v1.49+ and \sty{mfirstuc} v2.08+)
23649 or \ics{MakeTextUppercase} by default.
23650
23651 \cssection{bibglslowercase}
23652
23653 \formatdef{bibglslowercase}
23654 Converts \meta{text} to \idx{lowercase}. This just uses
23655 \ics{glslowercase} (if \sty{glossaries} v4.50+,
23656 \sty{glossaries-extra} v1.49+ and \sty{mfirstuc} v2.08+)
23657 \ics{MakeTextLowercase} by default.
23658
23659 \cssection{bibglstitlecase}
23660
23661 \formatdef{bibglstitlecase}
23662 Converts \meta{text} to \idx{titlecase}. This just uses
23663 \ics{capitalisewords} by default.
23664
23665 \cssection{bibglsfirstuc}
23666
23667 \formatdef{bibglsfirstuc}
23668 Converts the first letter of \meta{text} to \idx{uppercase}. This just uses
23669 \ics{makefirstuc} by default.
23670
23671 \cssection{BibGlsNoCaseChange}
23672
23673 Behaves as \cs{NoCaseChange} within \bibgls, so it will prevent its argument
23674 from being altered by options such as \csopt{short-case-change} or if the
23675 interpreter encounters this command within a case-changing command such as
23676 \cs{glsuppercase}. However, the definition provided in the \ext{glstex} file
23677 simply expands to \meta{text} in the document without adding the command to the
23678 case-changing exclusion list so it won't prevent any case-change within
23679 the \LaTeX\ document.
23680
23681 \cssection{bibglsdefinitionindex}
23682
23683 \formatdef{bibglsdefinitionindex}
23684 If \csopt{save-definition-index} has been set this command expands to the
23685 \gls{definitionindex} of the entry identified by \meta{label}. This
23686 command will only be provided in the \ext{glstex} file if
23687 \csopt{save-definition-index} has been set. However, the command is
23688 always defined by the \texparserlib\
23689 but will expand to empty if the associated resource option hasn't
23690 been set.
23691
23692 \cssection{bibglsuseindex}
23693
23694 \formatdef{bibglsuseindex}
23695 If \csopt{save-use-index} has been set this command expands to the
23696 \gls{orderofuseindex} of the entry identified by \meta{label}. This
23697 command will only be provided in the \ext{glstex} file if
23698 \csopt{save-use-index} has been set. However, the command is
23699 always defined by the \texparserlib\
23700 but will expand to empty if the associated resource option hasn't
23701 been set.
23702
23703 \chapter{Converting Existing \iext{tex} to \iext{bib}}
23704 \label{sec:tex2bib}
23705 \setsecdepth{1}
23706 \renewcommand{\cssectioncmd}{\subsubsection}
23707
23708 There are some supplementary command line tools provided with
23709 \bibgls\ that can convert certain types of data from existing
23710 documents to \iext{bib} files:
23711 \begin{itemize}
23712 \item \idx{convertgls2bib} converts
23713 data from commands like \gls{newglossaryentry} to \ext{bib} entry
23714 data (see \sectionref{sec:gls2bib}).
23715
23716 \item \idx{datatool2bib} converts \sty{datatool} databases to
23717 \ext{bib} entry data (see \sectionref{sec:gls2bib}).
23718 \end{itemize}
23719
23720 These command line tools share the same common switches listed in
23721 \sectionref{sec:commonswitches}. Additionally, they share the switches
23722 listed in \sectionref{sec:shared2bibswitches}, but they may also
23723 have their specific switches, which are described in the relevant
23724 section.
23725
23726 \begin{important}
23727 It's likely that you will need to post-process the \ext{bib} files
23728 or at least double-check that the conversion has been performed
23729 adequately.
23730 \end{important}
23731
23732 The \ext{bib} format has case-insensitive field names. However, the
23733 source files input by the converter tool typically have
23734 case-sensitive labels that correspond to the destination \ext{bib}
23735 field. The converter tools will convert the fields to
23736 \idx{lowercase} after any mappings have been applied.
23737 Use \converterlongarg{field-case} to change this.
23738 Additionally, the \ext{bib} format prohibits certain characters in
23739 field names and entry labels (such as spaces), so these will be
23740 stripped. The resulting field names must be non-empty.
23741
23742 The \texparserlib\ is used to parse the input files. The conversion
23743 tool may automatically implement the relevant packages (such as
23744 \sty{datatool} and \sty{datagidx} for \idx{datatool2bib}).
23745 However, the behaviour of some commands may be
23746 modified to better suit the conversion process.
23747
23748 Note that \ics{IfTeXParserLib} will expand to its first argument,
23749 but \ics{IfNotBibGls} will also expand to its first argument, since
23750 it's only defined to expand to its second argument by the \bibgls\
23751 interpreter not by the \texparserlib\ core code.
23752
23753 Avoid any overly complicated code within the \ext{tex} file. The
23754 \texparserlib\ isn't a \TeX\ engine! The input \ext{tex} file
23755 doesn't need to be a complete document, but if you want certain
23756 commands recognised from packages that the \texparserlib\ supports,
23757 you'll need to include \ics{usepackage} in the \ext{tex} file. If
23758 you want to quit parsing the \ext{tex} file at the start of the
23759 document, use the \converterlongarg{preamble-only} switch.
23760
23761 \begin{important}
23762 The \texparserlib\ recognises
23763 \ics{input} and \ics{include} and so will also parse the referenced
23764 file if either command is encountered.
23765 If you have multiple files, it's better to pass just the relevant
23766 file to the conversion tool rather than the main document file.
23767 \end{important}
23768
23769 \section{Shared Conversion Tool Switches}
23770 \label{sec:shared2bibswitches}
23771
23772 \converterarg{texenc}
23773
23774 The character \igls{encoding} of the source \ext{tex} file. If omitted, the
23775 \idx{JVM}['s] default \gls{encoding} is assumed (which may or
23776 may not be the same as the operating system's default).
23777
23778 \converterarg{bibenc}
23779
23780 The character \igls{encoding} of the \ext{bib} file. If omitted, the same
23781 \gls{encoding} as the \ext{tex} file is assumed.
23782
23783 \converterarg{space-sub}
23784
23785 The \ext{bib} format doesn't allow spaces in labels. If your original
23786 definitions in your \ext{tex} file have spaces, use this option to
23787 replace spaces in labels. Each space will be substituted with
23788 \meta{replacement}. Where applicable, the cross-referencing fields, \field{see},
23789 \field{seealso} and \field{alias}, will also be adjusted, but any
23790 references using \ics{gls} etc will have to be substituted manually
23791 (or use a global search and replace action in your text editor).
23792 If you want to strip the spaces, use an empty string for
23793 \meta{replacement}. You'll need to delimit this according to your
23794 operating system. For example:
23795 \begin{verbatim}
23796 convertgls2bib --space-sub '' entries.tex entries.bib
23797 \end{verbatim}
23798 Alternatively, use \converterlongarg{field-map} to supply an
23799 alternative field name.
23800
23801 \begin{important}
23802 Note that all forbidden punctuation characters
23803 (such as commas, equal signs and braces) will be automatically stripped.
23804 \end{important}
23805
23806 \converterarg{preamble-only}
23807
23808 Stop parsing if the start of the \env{document} environment is found.
23809
23810 \converterarg{no-preamble-only}
23811
23812 Parse the entire file (default). Be prepared for a lot of
23813 \qt{unknown command} warnings if you make the conversion tool parse an
23814 entire document.
23815
23816 \converterarg{overwrite}
23817
23818 Allow existing \ext{bib} files to be overwritten. (Default unless
23819 otherwise specified.)
23820
23821 \converterarg{no-overwrite}
23822
23823 Don't allow existing \ext{bib} files to be overwritten.
23824
23825 \converterarg{ignore-fields}
23826
23827 Omit all the fields listed in \meta{list} from the \ext{bib} file.
23828 This option is cumulative.
23829 Note that in earlier versions of \idx{convertgls2bib} an empty list
23830 cancelled the list of ignored fields. As from version 4.0, you will
23831 need to use \converterlongarg{no-ignore-fields} to clear the list.
23832
23833 Each item in the list should identify
23834 the field by its original case-sensitive key.
23835
23836 \converterarg{no-ignore-fields}
23837
23838 Cancels the effect of \converterlongarg{ignore-fields}.
23839
23840 \converterarg{field-map}
23841
23842 Provides a mapping from source labels to the field names used in
23843 the destination \ext{bib} file. The argument should be a
23844 comma-separated list of \code{\meta{src-label}=\meta{dest-field}}
23845 pairs.
23846 This option is cumulative.
23847
23848 For \idx{convertgls2bib}, the source labels are the keys used in
23849 commands such as \gls{newglossaryentry}. These should ordinarily not
23850 need any mappings. However, you may, for example, want to convert
23851 the user keys to something more appropriate.
23852 For \idx{datatool2bib}, the source labels are the column keys.
23853
23854 \converterarg{no-field-map}
23855
23856 Cancels all field mappings.
23857
23858 \converterarg{field-case}
23859
23860 Specifies whether or not to change the case of the field name when
23861 writing to the \ext{bib} file. Valid \meta{setting}:
23862 \optfmt{none} (no case-change), \optfmt{lc} (to \idx{lowercase}, default),
23863 \optfmt{uc} (to \idx{uppercase}), \optfmt{title} (to \idx{titlecase}),
23864 or \optfmt{sentence} (to \idx{sentencecase}). Note that since spaces
23865 aren't permitted in field names, the last two are equivalent.
23866 The case-change is applied after mapping.
23867
23868 \converterarg{index-conversion}
23869
23870 Use \atentry{index} instead of \atentry{entry} if the
23871 \field{description} is empty or, for \idx{convertgls2bib}, if the
23872 \field{description} is simply \ics{nopostdesc} or
23873 \ics{glsxtrnopostpunc}. (Only applies to terms that would otherwise
23874 be converted to \atentry{entry}, such as those defined with
23875 \gls{newglossaryentry} in the case of \idx{convertgls2bib}.)
23876
23877 \converterarg{no-index-conversion}
23878
23879 Don't convert \atentry{entry} to \atentry{index} (default).
23880
23881 \converterarg{log-file}
23882
23883 The log file is optional for the converter applications. It's
23884 provided for use with the \texparserlib\ debugging modes
23885 (\commonlongarg{debug-mode}) which writes
23886 logging information to this file (which can be sizeable).
23887 A log file will automatically be created if debugging is enabled,
23888 otherwise it will need to be explicitly created with
23889 \converterlongarg{log-file} if required. The default name, if
23890 automatically created, is the name of the converter application with
23891 the \ext{log} file extension.
23892
23893 \begin{important}
23894 Unlike \bibgls's \longarg{log-file} switch, the conversion
23895 tools don't have a corresponding short switch.
23896 \end{important}
23897
23898 \section{\glsfmttext{idx.convertgls2bib}: Conversion from \styfmt{glossaries} or
23899 \styfmt{glossaries-extra}}
23900 \label{sec:gls2bib}
23901 \setsecdepth{2}
23902
23903 If you have already been using the \styfmt{glossaries} or
23904 \styfmt{glossaries-extra} package with a large file containing all your
23905 definitions using commands like \gls{newglossaryentry}, then you can
23906 use the supplementary tool \idx{convertgls2bib} to convert the definitions
23907 to the \ext{bib} format required by \bibgls. The syntax is:
23908 \begin{alltt}
23909 convertgls2bib \oargm{options} \meta{tex file} \meta{bib file}
23910 \end{alltt}
23911 where \meta{tex file} is the \ext{tex} file and \meta{bib file} is
23912 the \ext{bib} file. This application is less secure than \bibgls\ as
23913 it doesn't use \idx{kpsewhich} to check \texmfcnf{openinany} and
23914 \texmfcnf{openoutany}. Take care not to accidentally overwrite
23915 existing \ext{bib} files as there's no check to determine if
23916 \meta{bib file} already exists with the default \converterlongarg{overwrite}.
23917
23918 If the \ext{bib} extension is missing from \meta{bib file}, it will
23919 be added. The extension is required for \meta{tex file}.
23920
23921 \subsection{Command Line Arguments}
23922
23923 The \meta{options} specific to \idx{convertgls2bib} are described below.
23924 This is in addition to those described in \sectionref{sec:commonswitches}
23925 and \sectionref{sec:shared2bibswitches}. Note that
23926 \convertglsbiblongarg{split-on-type} overrides the default
23927 \converterlongarg{overwrite} setting.
23928
23929 \convertglsbibarg{ignore-sort}
23930
23931 Omit the \field{sort} field. This is the default since \bibgls\ can
23932 work out a more intuitive sort value than either \idx!{makeindex} or
23933 \idx!{xindy}.
23934 This option is automatically set if the \field{sort} field is
23935 included in \converterlongarg{ignore-fields}.
23936
23937 \convertglsbibarg{no-ignore-sort}
23938
23939 Don't ignore the \field{sort} field.
23940
23941 \convertglsbibarg{ignore-type}
23942
23943 Omit the \field{type} field in the \ext{bib} file. You may find it
23944 more flexible not to be locked into a specific glossary type if you
23945 have a large database of entries.
23946 This option is automatically set if the \field{type} field is
23947 included in \converterlongarg{ignore-fields}.
23948
23949 \convertglsbibarg{no-ignore-type}
23950
23951 Don't omit the \field{type} field (default unless
23952 \convertglsbiblongarg{split-on-type}).
23953
23954 \convertglsbibarg{ignore-category}
23955
23956 Omit the \field{category} field in the \ext{bib} file.
23957 This option is automatically set if the \field{category} field is
23958 included in \converterlongarg{ignore-fields}.
23959
23960 \convertglsbibarg{no-ignore-category}
23961
23962 Don't omit the \field{category} field (default unless
23963 \convertglsbiblongarg{split-on-category}).
23964
23965 \convertglsbibarg{split-on-type}
23966
23967 Split the entries into separate files according to the \field{type}
23968 field. Any entries that have the \field{type} field set to \ics{glsdefaulttype}
23969 or that don't have the \field{type} field set and there's no default provided
23970 by the command used to define the entry (see below) then the
23971 \atentryfmt{\meta{entry}} data will be written to the main \meta{bib
23972 file}. Otherwise entries will be written to the split file
23973 (in the same directory as \meta{bib file}).
23974
23975 The split file name depends on whether or not the
23976 \convertglsbiblongarg{split-on-category} switch has also been used. With both
23977 and if the category and field values are different then
23978 the file name is \metametafilefmt{}{type}{-}{category}{.bib} otherwise
23979 it's \metafilefmt{}{type}{.bib}.
23980
23981 Commands that have a default type are as follows:
23982 \begin{itemize}
23983 \item \gls{newabbreviation}, \gls{newacronym}, \ics{oldacronym},
23984 \gls{newdualentry}:
23985 the default type is assumed to be \code{abbreviations} (regardless
23986 of the definition of \ics{acronymtype} or \ics{glsxtrabbrvtype});
23987 \item \gls{glsxtrnewsymbol}: the default type is assumed to be \code{symbols};
23988 \item \gls{glsxtrnewnumber}: the default type is assumed to be \code{numbers};
23989 \item \gls{newterm}: the default type is assumed to be \code{index}.
23990 \end{itemize}
23991
23992 This option automatically implements \convertglsbiblongarg{ignore-type} and
23993 \converterlongarg{no-overwrite}.
23994
23995 \convertglsbibarg{no-split-on-type}
23996
23997 Don't split the entries into separate files according to their type
23998 (default).
23999
24000 \convertglsbibarg{split-on-category}
24001
24002 Split the entries into separate files according to the \field{category}.
24003 If the \field{category} field isn't present and there's no default provided
24004 by the command used to define the entry (see below) then the
24005 \atentryfmt{\meta{entry}} data will be written to the main \meta{bib
24006 file}. Otherwise entries will be written to the split file
24007 (in the same directory as \meta{bib file}).
24008
24009 The split file name depends on whether or not the
24010 \convertglsbiblongarg{split-on-type} switch has also been used. With both and
24011 if the category and field values are different then
24012 the file name is \metametafilefmt{}{type}{}{category}{.bib} otherwise
24013 it's \metafilefmt{}{category}{.bib}.
24014
24015 Commands that have a default category are as follows:
24016 \begin{itemize}
24017 \item \gls{newabbreviation}, \gls{newacronym}, \ics{oldacronym},
24018 \gls{newdualentry}:
24019 the default category is assumed to be \code{abbreviation};
24020 \item \gls{glsxtrnewsymbol}: the default category is assumed to be \code{symbol};
24021 \item \gls{glsxtrnewnumber}: the default category is assumed to be \code{number};
24022 \item \gls{newterm}: the default category is assumed to be \code{index}.
24023 \end{itemize}
24024
24025 For example, if you have both \convertglsbiblongarg{split-on-type} and
24026 \convertglsbiblongarg{split-on-category}, then the default file name for
24027 \gls{newabbreviation} will be
24028 \filefmt{abbreviations-abbreviation.bib} but the default file name
24029 for \gls{newterm} will be \filefmt{index.bib}. Whereas if you only
24030 have \convertglsbiblongarg{split-on-category} and not
24031 \convertglsbiblongarg{split-on-type}, then then default file name for
24032 \gls{newabbreviation} will be \filefmt{abbreviation.bib}.
24033
24034 This option automatically implements \convertglsbiblongarg{ignore-category} and
24035 \converterlongarg{no-overwrite}.
24036
24037 \convertglsbibarg{no-split-on-category}
24038
24039 Don't split the entries into separate files according to their
24040 category (default).
24041
24042
24043 \convertglsbibarg{absorb-see}
24044
24045 Absorb any cross-referencing information identified with
24046 \ics{glssee} or \ics{glsxtrindexseealso} commands into
24047 the corresponding entry (default).
24048
24049 \convertglsbibarg{no-absorb-see}
24050
24051 Don't absorb any cross-referencing information identified with \ics{glssee}
24052 or \ics{glsxtrindexseealso} commands.
24053
24054 \convertglsbibarg{internal-field-map}
24055
24056 Appends the given internal field to key mappings to the predefined
24057 list. This action is cumulative. The mappings are needed for
24058 \gls{glssetexpandfield} and \gls{glssetnoexpandfield}, which use
24059 \idx{internalfields} for their arguments.
24060 Note that this is different from \converterlongarg{field-map} which
24061 maps the key used in commands like \gls{newglossaryentry} to
24062 the corresponding field label written the \ext{bib} file.
24063
24064 \subsection{Recognised Commands}
24065
24066 The \idx{convertgls2bib} application recognises the commands listed below as well as
24067 some standard commands such as \ics{newcommand}. The \texparserlib\
24068 is instructed to skip its usual implementation of the
24069 \sty{glossaries} and \sty{glossaries-extra} packages as only a
24070 limited set of commands need to be defined.
24071
24072 In all cases below, if \meta{\keyvallist} contains:
24073 \begin{codeenv*}
24074 \field{see}=\marg{[\ics{seealsoname}]\meta{label(s)}}
24075 \end{codeenv*}
24076 or
24077 \begin{codeenv*}
24078 \field{see}=\marg{[\ics{alsoname}]\meta{label(s)}}
24079 \end{codeenv*}
24080 this will be substituted with:
24081 \begin{codeenv*}
24082 \field{seealso}=\margm{label(s)}
24083 \end{codeenv*}
24084 For example:
24085 \begin{codeenv}
24086 \gls{newterm}\oarg{\field{see}=\marg{[\cs{seealsoname}]goose}}\marg{duck}
24087 \end{codeenv}
24088 will be written as:
24089 \begin{codeenv}
24090 \atentry{index}\marg{duck,
24091 \field{seealso} = \marg{goose}
24092 }
24093 \end{codeenv}
24094 Note that it won't convert \code{\field{see}=\marg{[see also]\meta{labels}}}.
24095 If you have used explicit text instead of \ics{seealsoname} or
24096 \ics{alsoname} then consider performing a global search and replace
24097 on your file using your text editor.
24098
24099 Additionally, if \meta{\keyvallist} contains:
24100 \begin{codeenv}
24101 \field{type}=\marg{\ics{glsdefaulttype}}
24102 \end{codeenv}
24103 then this field will be ignored. (This \field{type} value is
24104 recommended in \meta{\keyvallist} when loading files with
24105 \gls{loadglsentries}\oargm{type}\margm{file} to allow the optional
24106 argument to set the \field{type}. With \bibgls\ you can use the
24107 \csopt{type} option instead.)
24108
24109 \cssection{glsexpandfields}
24110 The base \styfmt{glossaries} package provides:
24111 \formatdef{glsexpandfields}
24112 If present, this instructs \idx{convertgls2bib} to expand all fields
24113 except for those explicitly identified by \gls{glssetnoexpandfield}.
24114 Remember that there are many commands that aren't recognised by
24115 \idx{convertgls2bib} so it may not be possible to correctly expand
24116 field values. Conversely, there are some commands that will be
24117 expanded by \idx{convertgls2bib} that aren't expandable in \TeX\
24118 (such as \ics{MakeUppercase} and \ics{char}).
24119
24120 \cssection{glsnoexpandfields}
24121 The base \styfmt{glossaries} package provides:
24122 \formatdef{glsnoexpandfields}
24123 If present, this instructs \idx{convertgls2bib} to not expand fields
24124 unless explicitly identified by \gls{glssetexpandfield}.
24125
24126 \cssection{glssetexpandfield}
24127 The base \styfmt{glossaries} package provides:
24128 \formatdef{glssetexpandfield}
24129 If present, this instructs \idx{convertgls2bib} to expand the
24130 given field, even if \gls{glsnoexpandfields} has been used.
24131 Note that the argument should be the internal field label.
24132 The default set of mappings are recognised. Any additional mappings
24133 will need to be added with
24134 \convertglsbiblongarg{internal-field-map}.
24135
24136 \cssection{glssetnoexpandfield}
24137 The base \styfmt{glossaries} package provides:
24138 \formatdef{glssetnoexpandfield}
24139 If present, this instructs \idx{convertgls2bib} to not expand the
24140 given field, even if \gls{glsexpandfields} has been used.
24141 Unlike the default behaviour with the \sty{glossaries} package, there are no
24142 fields explicitly switched off by default with \idx{convertgls2bib}.
24143
24144 \cssection{loadglsentries}
24145 The base \styfmt{glossaries} package provides:
24146 \formatdef{loadglsentries}
24147 This locally redefines \ics{glsdefaulttype} to \meta{type} (if the optional argument is supplied)
24148 and inputs \meta{file}. If the \meta{file} doesn't have an extension, \ext{tex} is assumed.
24149 (The \texparserlib\ also recognises \ics{input}.)
24150
24151 In general, it's better to simply use \meta{file} as the source file
24152 when running \idx{convertgls2bib} instead of using the main document
24153 file as the source.
24154
24155 \cssection{newglossaryentry}
24156 The base \styfmt{glossaries} package provides:
24157 \formatdef{newglossaryentry}
24158 This is converted to:
24159 \begin{codeenv}
24160 \atentry{entry}\marg{\meta{label},
24161 \meta{\keyvallist}
24162 }
24163 \end{codeenv}
24164 \ics{newentry} is recognised as a synonym of \gls{newglossaryentry}.
24165
24166 \cssection{provideglossaryentry}
24167 The base \styfmt{glossaries} package provides:
24168 \formatdef{provideglossaryentry}
24169 This is converted to:
24170 \begin{codeenv}
24171 \atentry{entry}\marg{\meta{label},
24172 \meta{\keyvallist}
24173 }
24174 \end{codeenv}
24175 but only if \meta{label} hasn't already been defined.
24176
24177 \cssection{longnewglossaryentry}
24178 The base \styfmt{glossaries} package provides:
24179 \formatdef{longnewglossaryentry}
24180 This is converted to:
24181 \begin{codeenv}
24182 \atentry{entry}\marg{\meta{label},
24183 \meta{\keyvallist},
24184 \field{description} = \margm{description}
24185 }
24186 \end{codeenv}
24187 The starred version provided by the \styfmt{glossaries-extra} package
24188 is also recognised. The unstarred version strips trailing spaces
24189 from \meta{description}. (This doesn't add \ics{nopostdesc}, but
24190 \styfmt{glossaries-extra} defaults to \styopt{nopostdot}.)
24191
24192 \cssection{longprovideglossaryentry}
24193
24194 The base \styfmt{glossaries} package provides:
24195 \formatdef{longprovideglossaryentry}
24196 As above, but only if \meta{label} hasn't already been defined.
24197
24198 \cssection{newterm}
24199
24200 The base \styfmt{glossaries} package provides:
24201 \formatdef{newterm}
24202 (when the \styopt{index} option is used).
24203 This is converted to:
24204 \begin{codeenv}
24205 \atentry{index}\marg{\meta{label},
24206 \meta{\keyvallist}
24207 }
24208 \end{codeenv}
24209 if the optional argument is present, otherwise it's just converted
24210 to:
24211 \begin{codeenv}
24212 \atentry{index}\marg{\meta{label}}
24213 \end{codeenv}
24214
24215 If \converterlongarg{space-sub} is used and \meta{label} contains one or
24216 more spaces, then \field{name} will be set if not included in
24217 \meta{\keyvallist}. For example, if \filefmt{entries.bib}
24218 contains:
24219 \begin{codeenv}
24220 \gls{newterm}\marg{sea lion}
24221 \gls{newterm}\oarg{\field{seealso}=\marg{sea lion}}\marg{seal}
24222 \end{codeenv}
24223 then:
24224 \begin{verbatim}
24225 convertgls2bib --space-sub '-' entries.bib entries.tex
24226 \end{verbatim}
24227 will write the terms to \filefmt{entries.tex} as:
24228 \begin{codeenv}
24229 \atentry{index}\marg{sea-lion,
24230 \field{name} = \marg{sea lion}
24231 }
24232 \strut
24233 \atentry{index}\marg{seal,
24234 \field{seealso} = \marg{sea-lion}
24235 }
24236 \end{codeenv}
24237 whereas just:
24238 \begin{verbatim}
24239 convertgls2bib entries.bib entries.tex
24240 \end{verbatim}
24241 will write the terms to \filefmt{entries.tex} as:
24242 \begin{codeenv}
24243 \atentry{index}\marg{sea lion}
24244 \strut
24245 \atentry{index}\marg{seal,
24246 \field{seealso} = \marg{sea lion}
24247 }
24248 \end{codeenv}
24249 which will cause a problem when the \ext{bib} file is parsed
24250 by \bibgls\ (and will probably also cause a problem for
24251 bibliographic management systems).
24252
24253 \cssection{newabbreviation}
24254 The \styfmt{glossaries-extra} package provides:
24255 \formatdef{newabbreviation}
24256 This is converted to:
24257 \begin{codeenv}
24258 \atentry{abbreviation}\marg{\meta{label},
24259 \field{short} = \margm{short},
24260 \field{long} = \margm{long},
24261 \meta{\keyvallist}
24262 }
24263 \end{codeenv}
24264 if the optional argument is present, otherwise it's converted to:
24265 \begin{codeenv}
24266 \atentry{abbreviation}\marg{\meta{label},
24267 \field{short} = \margm{short},
24268 \field{long} = \margm{long}
24269 }
24270 \end{codeenv}
24271
24272 \cssection{newacronym}
24273 The base \styfmt{glossaries} package provides:
24274 \formatdef{newacronym}
24275 (which is redefined by \styfmt{glossaries-extra} to use
24276 \gls{newabbreviation}).
24277
24278 As above but uses \atentry{acronym} instead. The base package also
24279 provides \ics{oldacronym}, which emulates the way abbreviations were
24280 defined with the precursor \styfmt{glossary} package. This has
24281 different syntax to \gls{newacronym} but is also recognised by \idx{convertgls2bib}
24282 and is converted to \atentry{acronym}.
24283
24284 \cssection{glsxtrnewsymbol}
24285 The \styfmt{glossaries-extra} package provides:
24286 \formatdef{glsxtrnewsymbol}
24287 (when the \styopt{symbols} option is used).
24288 This is converted to:
24289 \begin{codeenv}
24290 \atentry{symbol}\marg{\meta{label},
24291 \field{name} = \margm{symbol}
24292 }
24293 \end{codeenv}
24294 if the optional argument is missing, otherwise it's converted to:
24295 \begin{codeenv}
24296 \atentry{symbol}\marg{\meta{label},
24297 \field{name} = \margm{symbol},
24298 \meta{\keyvallist}
24299 }
24300 \end{codeenv}
24301 unless \meta{\keyvallist} contains the \field{name} field,
24302 in which case it's converted to:
24303 \begin{codeenv}
24304 \atentry{symbol}\marg{\meta{label},
24305 \meta{\keyvallist}
24306 }
24307 \end{codeenv}
24308 \ics{newsym} is recognised as a synonym for \gls{glsxtrnewsymbol}.
24309
24310 \cssection{glsxtrnewnumber}
24311
24312 The \styfmt{glossaries-extra} package provides:
24313 \formatdef{glsxtrnewnumber}
24314 (when the \styopt{numbers} option is used).
24315 This is converted to:
24316 \begin{codeenv}
24317 \atentry{number}\marg{\meta{label},
24318 \field{name} = \margm{label}
24319 }
24320 \end{codeenv}
24321 if the optional argument is missing, otherwise it's converted to:
24322 \begin{codeenv}
24323 \atentry{number}\marg{\meta{label},
24324 \field{name} = \margm{label},
24325 \meta{\keyvallist}
24326 }
24327 \end{codeenv}
24328 if \field{name} isn't listed in \meta{\keyvallist},
24329 otherwise it's converted to:
24330 \begin{codeenv}
24331 \atentry{number}\marg{\meta{label},
24332 \meta{\keyvallist}
24333 }
24334 \end{codeenv}
24335 \ics{newnum} is recognised as a synonym for \gls{glsxtrnewnumber}.
24336
24337 \cssection{newdualentry}
24338
24339 \formatdef{newdualentry}
24340 This command isn't provided by either \styfmt{glossaries} or
24341 \styfmt{glossaries-extra} but is used as an example in the
24342 \sty{glossaries} user manual~\cite{glossaries} and in the sample file
24343 \file{sample-dual.tex} that accompanies the \sty{glossaries}
24344 package. Since this command seems to be used quite a bit (given the
24345 number of times it crops up on sites like
24346 \href{https://tex.stackexchange.com/}{\TeX\ on StackExchange}),
24347 \idx{convertgls2bib} also supports it unless this command is
24348 defined using \ics{newcommand} or \ics{renewcommand} in the
24349 input file. In which case the default definition will be overridden.
24350
24351 If the command definition isn't overridden, then it's converted to:
24352 \begin{codeenv}
24353 \atentry{dualabbreviationentry}\marg{\meta{label},
24354 \field{short} = \margm{short},
24355 \field{long} = \margm{long},
24356 \field{description} = \margm{description},
24357 \meta{\keyvallist}
24358 }
24359 \end{codeenv}
24360 if \meta{\keyvallist} is supplied, otherwise it's converted to:
24361 \begin{codeenv}
24362 \atentry{dualabbreviationentry}\marg{\meta{label},
24363 \field{short} = \margm{short},
24364 \field{long} = \margm{long},
24365 \field{description} = \margm{description}
24366 }
24367 \end{codeenv}
24368
24369 For example, if the original \ext{tex} file contains:
24370 \begin{codeenv}
24371 \cs{newcommand}*\marg{\gls{newdualentry}}[5][]\marg{\comment{}
24372 \gls{newglossaryentry}\marg{main-\idx{param}2}\marg{\field{name}=\marg{\idx{param}4},\comment{}
24373 \field{text}=\marg{\idx{param}3\cs{glsadd}\marg{\idx{param}2}},\comment{}
24374 \field{description}=\marg{\idx{param}5},\comment{}
24375 \idx{param}1
24376 }\comment{}
24377 \gls{newacronym}\marg{\idx{param}2}\marg{\idx{param}3\cs{glsadd}\marg{main-\idx{param}2}}\marg{\idx{param}4}\comment{}
24378 }
24379 \strut
24380 \gls{newdualentry}\marg{svm}\comment{label}
24381 \marg{SVM}\comment{abbreviation}
24382 \marg{support vector machine}\comment{long form}
24383 \marg{Statistical pattern recognition technique}\comment{description}
24384 \end{codeenv}
24385 then the \ext{bib} file will contain:
24386 \begin{codeenv}
24387 \atentry{entry}\marg{main-svm,
24388 \field{name} = \marg{support vector machine},
24389 \field{description} = \marg{Statistical pattern recognition technique},
24390 \field{text} = \marg{SVM\cs{glsadd}\marg{svm}}
24391 }
24392 \strut
24393 \atentry{acronym}\marg{svm,
24394 \field{short} = \marg{SVM\cs{glsadd}\marg{main-svm}},
24395 \field{long} = \marg{support vector machine}
24396 }
24397 \end{codeenv}
24398 since \gls{newdualentry} was defined with \ics{newcommand}. However,
24399 if the original file uses \ics{providecommand} or omits the
24400 definition of \gls{newdualentry}, then the \ext{bib} file will
24401 contain:
24402 \begin{codeenv}
24403 \atentry{dualabbreviationentry}\marg{svm,
24404 \field{short} = \marg{SVM},
24405 \field{description} = \marg{Statistical pattern recognition technique},
24406 \field{long} = \marg{support vector machine}
24407 }
24408 \end{codeenv}
24409
24410 \section{\glsfmttext{idx.datatool2bib}: Conversion from
24411 \styfmt{datatool}}
24412 \label{sec:datatool2bib}
24413
24414 A \isty{datatool} database can be converted to a \ext{bib} file
24415 with the supplementary tool \idx{datatool2bib}. The syntax is:
24416 \begin{alltt}
24417 datatool2bib \oargm{options} \meta{tex file} \meta{bib file}
24418 \end{alltt}
24419 where \meta{tex file} is the \ext{tex} file and \meta{bib file} is
24420 the \ext{bib} file. This application is less secure than \bibgls\ as
24421 it doesn't use \idx{kpsewhich} to check \texmfcnf{openinany} and
24422 \texmfcnf{openoutany}. Take care not to accidentally overwrite
24423 existing \ext{bib} files as there's no check to determine if
24424 \meta{bib file} already exists with the default \converterlongarg{overwrite}.
24425
24426 This tool is primarily intended to convert \sty{datagidx} databases,
24427 so it will automatically assume that \sty{datagidx} is loaded.
24428 It can, however, be used for general databases, but you will need to
24429 choose an appropriate column with unique values for the entry label (with
24430 \datatoolbiblongarg{label} or use \datatoolbiblongarg{auto-label}).
24431
24432 The \meta{tex file} may be a complete document (in which case, you
24433 may want to use \converterlongarg{preamble-only} if the database
24434 commands are all in the preamble) or may be a file that just
24435 contains the database construction commands. The conversion tool
24436 uses the \texparserlib\ which has some limited support for
24437 \sty{datatool}, including database construction commands and file
24438 input commands \ics{DTLloaddb}, \ics{DTLloaddbtex} and the newer
24439 \gls{DTLread}.
24440
24441 For example, suppose I have a document file called
24442 \filefmt{myDoc.tex} that contains:
24443 \begin{codeenv}
24444 \csfmt{documentclass}\marg{article}
24445 \csfmt{usepackage}\marg{datatool}
24446 \gls{DTLnewdb}\marg{mydata}
24447 \gls{DTLnewrow}\marg{mydata}
24448 \gls{DTLnewdbentry}\marg{mydata}\marg{Forename}\marg{John}
24449 \gls{DTLnewdbentry}\marg{mydata}\marg{Surname}\marg{Smith}
24450 \comment{...}
24451 \cmd{begin}\marg{document}
24452 \comment{...}
24453 \cmd{end}\marg{document}
24454 \end{codeenv}
24455 Then I can extract this data with:
24456 \begin{codeenv}
24457 datatool2bib \converterlongarg{preamble-only} myDoc.tex mydata.bib
24458 \end{codeenv}
24459 If the database commands are instead in a separate file called, say,
24460 \filefmt{mydata.tex} which is simply input in \filefmt{myDoc.tex}
24461 then \filefmt{mydata.tex} can then be used for the \meta{tex file}
24462 input file:
24463 \begin{verbatim}
24464 datatool2bib mydata.tex mydata.bib
24465 \end{verbatim}
24466 Note that the \texparserlib\ also recognises commands such as
24467 \gls{dtlexpandnewvalue}. If this is in \filefmt{myDoc.tex} rather
24468 than in \filefmt{mydata.tex} and only \filefmt{mydata.tex} is parsed
24469 then the \texparserlib\ won't encounter \gls{dtlexpandnewvalue} and
24470 so won't enable new value expansion. You can, however, use
24471 \code{\datatoolbiblongarg{setup} expand-new-value} to switch on new
24472 value expansion.
24473
24474 If the data source is in a CSV file, then the \texparserlib\ can
24475 parse it but only if the file is referenced in \ics{DTLloaddb} (pre
24476 \sty{datatool} v3.0) or \gls{DTLread} (\sty{datatool} v3.0+).
24477 For the newer \gls{DTLread} command, the \code{format=\iext{csv}} setting is
24478 required to parse CSV files or \code{format=\iext{tsv}} for TSV files.
24479 If the file contains \LaTeX\ commands, \code{content=tex} is
24480 required otherwise \code{content=literal} is required.
24481
24482 So in order to convert a CSV file called \filefmt{mydata.csv} to
24483 a \ext{bib} file, the \texparserlib\ needs to parse:
24484 \begin{codeenv}
24485 \gls{DTLread}\oarg{format=csv,content=literal}\marg{mydata.csv}
24486 \end{codeenv}
24487 Rather than having to parse the entire document source file or
24488 create a stub file that simply contains this command, you can use
24489 the \datatoolbiblongarg{read} switch instead:
24490 \begin{codeenv}
24491 datatool2bib \datatoolbiblongarg{read} format=csv,content=literal mydata.csv mydata.bib
24492 \end{codeenv}
24493 This is equivalent to creating a stub file with just the
24494 \gls{DTLread} line.
24495
24496 In general, better results are obtained if \idx{datatool2bib} parses
24497 \gls{datagidx.newterm} and \gls{datagidx.newacro} instead of the
24498 actual \sty{datagidx} databases. The custom \sty{datagidx} databases
24499 have a number of columns for internal use that are not applicable to
24500 \bibgls.
24501
24502 When you run \idx{datatool2bib} from the command line, there will be
24503 two lines reporting the number of databases found by parsing the
24504 input. For example:
24505 \begin{verbatim}
24506 1 database (datatool) found
24507 0 databases (datagidx) found
24508 \end{verbatim}
24509 The first line indicates the number of regular \sty{datatool}
24510 databases that were found by the \texparserlib. The second line
24511 indicates the number of \sty{datagidx} databases that were detected
24512 by scanning for \gls{datagidx.newterm} and \gls{datagidx.newacro}.
24513
24514 In the first case, the source field labels will correspond to the
24515 column keys (such as \optfmt{Label}, \optfmt{Name},
24516 \optfmt{Description} and \optfmt{Symbol}), whereas in the second
24517 case the source field labels will correspond to the option keys for
24518 \gls{datagidx.newterm} and \gls{datagidx.newacro} (such as \optfmt{description} and
24519 \optfmt{symbol}, but not the \optfmt{label} key, which will be
24520 dropped from the list after its value is saved elsewhere).
24521
24522 \subsection{Command Line Arguments}
24523
24524 The \meta{options} specific to \idx{datatool2bib} are described below.
24525 This is in addition to those described in \sectionref{sec:commonswitches}
24526 and \sectionref{sec:shared2bibswitches}.
24527
24528 \datatoolbibarg{label}
24529
24530 Obtain the \ext{bib} entry label from the column identified by the
24531 \meta{column-key}. Note that the column key is the original
24532 case-sensitive column label not the mapped field.
24533 The label will be obtained by copying the value from the given
24534 column and processing according to \converterlongarg{space-sub}
24535 (and stripping forbidden characters). This option is not applicable
24536 to \gls{datagidx.newterm} and \gls{datagidx.newacro}.
24537
24538 \begin{important}
24539 The chosen column should have unique values (and should still be
24540 unique after processing).
24541 \end{important}
24542
24543 The default setting is \code{\datatoolbiblongarg{label} Label}
24544 since this is the column used for labels with \styfmt{datagidx} (but
24545 is only applicable if you save the database with \cs{DTLwrite}
24546 rather than having \idx{datatool2bib} parse \gls{datagidx.newterm}
24547 and \gls{datagidx.newacro}).
24548
24549 If you are converting a general \sty{datatool} database, either
24550 choose a different column or switch on the auto label.
24551
24552 \datatoolbibarg{auto-label}
24553
24554 If there is no appropriate column for a label, this option may be
24555 used to automatically generate the label in the form
24556 \meta{prefix}\meta{n}. If
24557 \datatoolbiblongarg{auto-label-prefix} is set, that will provide the
24558 \meta{prefix}, otherwise the prefix will match the database label.
24559
24560 \datatoolbibarg{no-auto-label}
24561
24562 Switches off automatic labelling. The labels will be created from
24563 the column identified by \datatoolbiblongarg{label}.
24564
24565 \datatoolbibarg{auto-label-prefix}
24566
24567 Sets the prefix for use with \datatoolbiblongarg{auto-label}.
24568 This option automatically implements
24569 \datatoolbiblongarg{auto-label}.
24570
24571 \datatoolbibarg{read}
24572
24573 Instead of parsing the provided \ext{tex} file in the usual manner,
24574 the \datatoolbiblongarg{read} option will act as though the input
24575 is:
24576 \begin{codeenv}
24577 \gls+{DTLread}\oargm{options}\marg{filename}
24578 \end{codeenv}
24579 where \meta{filename} is the input filename supplied to
24580 \idx{datatool2bib}. This can be use where the source file is a
24581 CSV file rather than a \LaTeX\ file.
24582
24583 \datatoolbibarg{setup}
24584 Implements \code{\gls{DTLsetup}\margm{options}} before parsing.
24585 Note that this can be counteracted by any changes to the settings
24586 within the file being parsed.
24587
24588 \datatoolbibarg{save-datum}
24589 Equivalent to:
24590 \begin{codeenv}
24591 \datatoolbiblongarg{save-value} "-value" \datatoolbiblongarg{save-currency} "-currency"
24592 \end{codeenv}
24593 For example, if the CSV file
24594 \filefmt{products.csv} contains:
24595 \begin{alltt}
24596 ID,Product,Quantity,Price
24597 1,Sample,3,"\$1,234.50"
24598 \end{alltt}
24599 then with:
24600 \begin{codeenv}
24601 datatool2bib \datatoolbiblongarg{label} Product \datatoolbiblongarg{read} "format=csv,content=literal" products.csv products.bib
24602 \end{codeenv}
24603 The \filefmt{products.bib} file will contain:
24604 \begin{codeenv}
24605 \atentry{entry}\marg{Sample,
24606 \fieldfmt{id} = \marg{1},
24607 \fieldfmt{product} = \marg{Sample},
24608 \fieldfmt{quantity} = \marg{3},
24609 \fieldfmt{price} = \marg{\cs{cs.dollar}1,234.5}
24610 }
24611 \end{codeenv}
24612 Whereas with:
24613 \begin{codeenv}
24614 datatool2bib \datatoolbiblongarg{save-datum} \datatoolbiblongarg{label} Product \datatoolbiblongarg{read} "format=csv,content=literal" products.csv products.bib
24615 \end{codeenv}
24616 \begin{codeenv}
24617 \atentry{entry}\marg{Sample,
24618 \fieldfmt{id} = \marg{1},
24619 \fieldfmt{product} = \marg{Sample},
24620 \fieldfmt{quantity} = \marg{3},
24621 \fieldfmt{price} = \marg{\cs{cs.dollar}1,234.5},
24622 \fieldfmt{price-value} = \marg{1234.5},
24623 \fieldfmt{price-currency} = \marg{\cs{cs.dollar}}
24624 }
24625 \end{codeenv}
24626 Note that the original number formatting is retained in the
24627 \fieldfmt{price} field but the plain numeric value is saved in the
24628 \fieldfmt{price-value} field and the currency symbol is saved in the
24629 \fieldfmt{price-currency} field. These custom fields will all need
24630 to be defined or aliased when the \ext{bib} file is read by \bibgls.
24631
24632 For further information on the \sty{datatool} datum format see the
24633 \sty{datatool} v3.0+ user manual. You need to set the
24634 decimal and number group characters with \ics{DTLsetnumberchars} and
24635 the currency symbol with \ics{DTLnewcurrencysymbol} for the values
24636 to be parsed correctly.
24637
24638 \datatoolbibarg{no-save-datum}
24639 Equivalent to:
24640 \begin{codeenv}
24641 \datatoolbiblongarg{no-save-value} \datatoolbiblongarg{no-save-currency}
24642 \end{codeenv}
24643
24644 \datatoolbibarg{save-value}
24645
24646 If a field contains a formatted numeric value or currency (according
24647 to the current \sty{datatool} settings), the numeric value will be
24648 saved in the field \meta{field}\meta{prefix} if it's different from
24649 the value in \meta{field}.
24650
24651 \datatoolbibarg{no-save-value}
24652
24653 Don't save numeric values in a separate field (default).
24654
24655 \datatoolbibarg{save-currency}
24656
24657 If a field contains a formatted currency (according
24658 to the current \sty{datatool} settings), the currency symbol will be
24659 saved in the field \meta{field}\meta{prefix}.
24660
24661 \datatoolbibarg{no-save-currency}
24662
24663 Don't save the currency symbol in a separate field (default).
24664
24665 \datatoolbibarg{split}
24666
24667 If multiple databases are found in the input file, create a separate
24668 output file for each database. If the output \meta{bib file} provided to
24669 \idx{datatool2bib} is given as \filefmt{\meta{base}.bib} then each
24670 database \meta{dbname} will be saved in the file
24671 \filefmt{\meta{base}-\meta{dbname}.bib}.
24672
24673 \datatoolbibarg{no-split}
24674
24675 All data found from parsing the input file will be saved in the
24676 single output \meta{bib file} (default).
24677
24678 \datatoolbibarg{detect-symbols}
24679
24680 Attempt to detect entries that should be \atentry{symbol} or
24681 \atentry{number} based on the value of the \field{name} field.
24682 This tries to expand the value of the name field with
24683 \ics{DTLgidxParen} and \ics{DTLgidxIgnore} locally defined to
24684 discard their argument. If the result is empty or if the first
24685 character of the result is not alphabetic then,
24686 if the result parses as an integer, \atentry{number}
24687 will be chosen otherwise \atentry{symbol} will be chosen.
24688 (An empty result can occur if the \field{name} field solely consists
24689 of commands that are unknown to the \texparserlib, which suggests
24690 symbols rather than words.)
24691
24692 This setting is only applicable for entries defined with
24693 \sty{datagidx}['s] \cs{newterm} command, not with general
24694 \sty{datatool} databases. Note that if this
24695 results in a change to the entry type from its default
24696 \atentry{entry} then \converterlongarg{index-conversion} won't
24697 convert the type to \atentry{index}, regardless of whether or
24698 not the \field{description} field is set.
24699
24700 \datatoolbibarg{no-detect-symbols}
24701
24702 Don't attempt to detect symbols (default).
24703
24704 \datatoolbibarg{numeric-locale}
24705
24706 For use with \datatoolbiblongarg{detect-symbols}, this switch
24707 identifies the locale used for numeric parsing to determine whether
24708 or not the \atentry{number} entry type should be used.
24709 If omitted, the \idx{JVM}['s] default locale is assumed.
24710
24711 \datatoolbibarg{adjust-gls}
24712
24713 This setting is the default.
24714 Any instance of commands like \ics{datagidx.gls} found in field
24715 values will have their labels adjusted, if they have been modified
24716 due to stripping spaces etc. Also, the syntax of \sty{datagidx}['s]
24717 \ics{datagidx.gls} is slightly different from \sty{glossaries}['s]
24718 \ics{gls} as the format is incorporated at the start of the label.
24719 If this is detected, the format will be added as an optional
24720 argument, matching the \sty{glossaries} syntax.
24721
24722 Additionally, commands that have different names from those provided
24723 by \sty{glossaries} will be replaced with the closest match. For
24724 example, \ics{datagidx.glsnl} will be replaced with \code{\ics{gls}*}
24725 (no hyperlink).
24726
24727 \datatoolbibarg{no-adjust-gls}
24728
24729 Don't adjust commands like \ics{datagidx.gls} in field values.
24730
24731 \datatoolbibarg{dependency-field}
24732
24733 Sets the name of the dependency field. Has no effect with
24734 \datatoolbiblongarg{no-strip-glsadd}. With
24735 \datatoolbiblongarg{strip-glsadd}, the label from the
24736 stripped \ics{datagidx.glsadd} argument will be added to the field identified
24737 by \meta{field}. The default is \fieldfmt{dependency} which will be ignored
24738 by \bibgls\ unless instructed otherwise (via resource options such
24739 as \csopt{field-aliases} or by defining the field with commands such
24740 as \cs{glsaddstoragekey}).
24741
24742 For example, \meta{field} could be set to \field{see} (but be aware
24743 that this won't be merged with any existing \field{see} value for
24744 the same entry) or the new document to use the created \ext{bib}
24745 file could define \meta{field} and reference it in
24746 \csopt{dependency-fields}.
24747
24748 The \meta{field} will have any invalid content stripped and will be
24749 adjusted to match the \converterlongarg{field-case} setting.
24750 If the \meta{field} ends up as an empty string, it will behave as
24751 \datatoolbiblongarg{no-dependency-field}.
24752
24753 \datatoolbibarg{no-dependency-field}
24754
24755 Don't save any labels stripped with
24756 \datatoolbiblongarg{strip-glsadd}.
24757
24758 \datatoolbibarg{strip}
24759
24760 Switch on all strip options.
24761
24762 \datatoolbibarg{no-strip}
24763
24764 Switch off all strip options.
24765
24766 \datatoolbibarg{strip-glsadd}
24767
24768 Any instance of \ics{datagidx.glsadd} found in field values will be
24769 stripped, along with the argument. Note that this command is
24770 provided by \sty{datagidx} and, unlike the analogous
24771 \sty{glossaries} command, it doesn't have an optional argument but
24772 instead allows the format option to be included in the mandatory
24773 argument.
24774
24775 This setting is the default as \cs{glsadd} is rarely needed in field
24776 values with \bibgls, as dependencies and the \csopt{selection}
24777 criteria are usually sufficient.
24778
24779 \datatoolbibarg{no-strip-glsadd}
24780
24781 No search is made for \ics{datagidx.glsadd} in field values. Note
24782 that this means that no adjustments for the different syntax will be
24783 made.
24784
24785 \datatoolbibarg{strip-acronym-font}
24786
24787 Any instance of \ics{acronymfont} found in field values will be
24788 strip and the braces around the argument will be removed.
24789
24790 This setting is the default since \cs{acronymfont} should not be
24791 used with \sty{glossaries-extra}.
24792
24793 \datatoolbibarg{no-strip-acronym-font}
24794
24795 No search is made for \cs{acronymfont} in the field values. Note
24796 that the use of \cs{acronymfont} is deprecated with
24797 \sty{glossaries-extra} as it has a different abbreviation mechanism
24798 to the base \sty{glossaries} package.
24799
24800 \datatoolbibarg{strip-case-change}
24801
24802 The following \idxpl{casecommands} will be stripped from field
24803 values and the braces around the argument will be removed:
24804 \csfmt{uppercase}, \csfmt{lowercase},
24805 \ics{MakeTextUppercase}, \ics{MakeTextLowercase},
24806 \ics{MakeUppercase}, \ics{MakeLowercase}, and the \sty{mfirstuc}
24807 commands.
24808
24809 \datatoolbibarg{no-strip-case-change}
24810
24811 Don't strip the \idxpl{casecommands} from field values (default).
24812
24813 \subsection{Recognised Commands}
24814
24815 This section lists \isty{datatool} and \isty{datagidx} commands that
24816 are recognised by \idx{datatool2bib}. (There may be other commands
24817 that are also recognised but aren't relevant to the conversion
24818 process.) See the \sty{datatool} user manual for further
24819 information.
24820
24821 \cssection{DTLsetup}
24822 Some but not all \sty{datatool} settings are
24823 recognised by the \texparserlib. Of those that are recognised, the
24824 settings pertinent to \idx{datatool2bib} are: \optfmt{default-name},
24825 \optfmt{store-datum}, \optfmt{new-value-trim},
24826 \optfmt{new-value-expand}, and \optfmt{io}.
24827
24828 The \optfmt{io} setting
24829 takes a comma-separated list of default I/O options applicable to
24830 \gls{DTLread} (and \cs{DTLwrite}). Recognised I/O options:
24831 \optfmt{name}, \optfmt{keys}, \optfmt{headers}, \optfmt{expand},
24832 \optfmt{format}, \optfmt{add-delimiter}, \optfmt{csv-escape-chars},
24833 \optfmt{csv-content}, \optfmt{csv-blank}, \optfmt{csv-skip-lines}
24834 (and synonym \optfmt{omitlines}), \optfmt{no-header} (and synonym
24835 \optfmt{noheader}), \optfmt{auto-keys} (and synonym
24836 \optfmt{autokeys}), \optfmt{overwrite}, \optfmt{load-action},
24837 \optfmt{delimiter}, and \optfmt{separator}.
24838
24839 \cssection{DTLread}
24840 Loads a database from the given file, where the format should be
24841 identified in \meta{options} with the \optfmt{format} key. The
24842 default is \code{format=csv}, which indicates that the file is a CSV
24843 file. For tab-separated files, use \code{format=tsv}. If the CSV/TSV
24844 file contains \TeX\ markup within the cells, use
24845 \code{csv-content=tex} otherwise use \code{csv-content=literal}.
24846
24847 Note that:
24848 \begin{codeenv}
24849 datatool2bib \datatoolbiblongarg{read} \meta{io-options} \meta{filename} \meta{bib file}
24850 \end{codeenv}
24851 is equivalent to creating a file \filefmt{otherfile.tex} with a single line:
24852 \begin{codeenv}
24853 \gls{DTLread}\oargm{io-options}\margm{filename}
24854 \end{codeenv}
24855 and then running:
24856 \begin{alltt}
24857 datatool2bib otherfile.tex \meta{bib file}
24858 \end{alltt}
24859
24860 \begin{important}
24861 The \texparserlib\ also recognises \ics{DTLwrite} but
24862 \idx{datatool2bib} redefines the command to do nothing.
24863 \end{important}
24864
24865 \cssection{dtlexpandnewvalue}
24866 New values will be expanded before being added to the database.
24867 Note that the \texparserlib\ may not expand commands in the same way
24868 as \TeX, and it won't be able to expand unknown commands.
24869
24870 \cssection{dtlnoexpandnewvalue}
24871 New values will not be expanded before being added to the database
24872 (default).
24873
24874 \cssection{DTLnewdb}
24875 Defines a new database with the given label.
24876
24877 \cssection{DTLnewrow}
24878 Creates a new row in the database identified the given label.
24879
24880 \cssection{DTLnewdbentry}
24881 Adds a new entry to the final row of the given database.
24882
24883 For example:
24884 \begin{codeenv}
24885 \gls+{DTLnewdb}\marg{mydata}
24886 \gls+{DTLnewrow}\marg{mydata}
24887 \gls+{DTLnewdbentry}\marg{mydata}\marg{Forename}\marg{John}
24888 \gls{DTLnewdbentry}\marg{mydata}\marg{Surname}\marg{Smith}
24889 \gls{DTLnewdbentry}\marg{mydata}\marg{Email}\marg{[email protected]}
24890 \gls{DTLnewrow}\marg{mydata}
24891 \gls{DTLnewdbentry}\marg{mydata}\marg{Forename}\marg{Jane}
24892 \gls{DTLnewdbentry}\marg{mydata}\marg{Surname}\marg{Doe}
24893 \gls{DTLnewdbentry}\marg{mydata}\marg{Email}\marg{[email protected]}
24894 \end{codeenv}
24895 This can be converted using, for example (assuming the above is in
24896 the file \filefmt{mydata.tex}):
24897 \begin{codeenv}
24898 datatool2bib \datatoolbiblongarg{auto-label} mydata.tex mydata.bib
24899 \end{codeenv}
24900 This will create the file \filefmt{mydata.bib}, which will contain:
24901 \begin{codeenv}
24902 \atentry{entry}\marg{mydata1,
24903 \fieldfmt{forename} = \marg{John},
24904 \fieldfmt{surname} = \marg{Smith},
24905 \fieldfmt{email} = \marg{[email protected]}
24906 }
24907 \strut
24908 \atentry{entry}\marg{mydata2,
24909 \fieldfmt{forename} = \marg{Jane},
24910 \fieldfmt{surname} = \marg{Doe},
24911 \fieldfmt{email} = \marg{[email protected]}
24912 }
24913 \end{codeenv}
24914 (Use \converterlongarg{index-conversion} to use \atentry{index} instead
24915 of \atentry{entry} where there's no \field{description}.)
24916 The \csopt{assign-fields} resource option can be used to set
24917 the \field{name} field to a concatenation of the forename and
24918 surname fields (which would need to be aliased or defined if
24919 required).
24920
24921 \cssection{DTLaction}
24922 This general purpose action command can be used to create and append
24923 to databases. The applicable actions that are recognised by the
24924 \texparserlib\ (and therefore by \idx{datatool2bib}) are:
24925 \optfmt{new}, \optfmt{new row}, \optfmt{new entry}, and
24926 \optfmt{add column}.
24927
24928 For example:
24929 \begin{codeenv}
24930 \gls+{DTLsetup}\marg{default-name=mydata}
24931 \gls+{DTLaction}\marg{new}
24932 \gls{DTLaction}\oarg{
24933 assign =
24934 \marg{
24935 Name = \marg{José Arara},
24936 Score = 68,
24937 Award = \marg{\cs{cs.dollar}2,453.99}
24938 }
24939 }\marg{new row}
24940 \gls{DTLaction}\oarg{
24941 assign =
24942 \marg{
24943 Name = \marg{Zoë Zebra},
24944 Score = 73,
24945 Award = \marg{\cs{cs.dollar}2,542}
24946 }
24947 }\marg{new row}
24948 \end{codeenv}
24949 This can be converted using, for example (assuming the above is in
24950 the file \filefmt{mydata.tex}):
24951 \begin{codeenv}
24952 datatool2bib \datatoolbiblongarg{label} Name mydata.tex mydata.bib
24953 \end{codeenv}
24954 This will create the file \filefmt{mydata.bib}, which will contain:
24955 \begin{codeenv}
24956 \atentry{entry}\marg{JoséArara,
24957 \field{name} = \marg{José Arara},
24958 \fieldfmt{score} = \marg{68},
24959 \fieldfmt{award} = \marg{\cs{cs.dollar}2,453.99}
24960 }
24961 \strut
24962 \atentry{entry}{ZoëZebra,
24963 \field{name} = \marg{Zoë Zebra},
24964 \fieldfmt{score} = \marg{73},
24965 \fieldfmt{award} = \marg{\cs{cs.dollar}2,542}
24966 }
24967 \end{codeenv}
24968 Again, use \converterlongarg{index-conversion} to use
24969 \atentry{index} instead of \atentry{entry} if the
24970 \field{description} field is missing.
24971
24972 The \iext{dtltex} and \ext{dbtex} file formats are also recognised
24973 by the \texparserlib. The commands used in those files are not
24974 intended for document use, but the files may be passed to
24975 \idx{datatool2bib} as the input file. See the \sty{datatool} v3.0+
24976 user manual for further details of those formats.
24977
24978 \prefixedcssection{datagidx}{newgidx}
24979 Defines a new \sty{datagidx} database, which may be referenced in
24980 \gls{datagidx.newterm} and \gls{datagidx.newacro} by the
24981 \optfmt{database} key in their optional argument (which be parsed
24982 and then dropped from the field list).
24983
24984 \prefixedcssection{datagidx}{newterm}
24985 This is similar to the \gls{newterm} command provided by
24986 \sty{glossaries} (via the \styopt{index} package option), but has
24987 slightly different behaviour. With \sty{datagidx}, the mandatory
24988 argument is the name. The label may be supplied in the optional
24989 argument. If omitted, the label is obtained from the name. The
24990 \idx{datatool2bib} application will try to mimic the process used by
24991 \sty{datagidx} to create the label from the name, but may not
24992 produce an exact match. It's therefore important to double-check the
24993 resulting \ext{bib} file afterwards.
24994
24995 Each \gls{datagidx.newterm} will be converted to \atentry{entry}
24996 unless it has both the \field{long} and \field{short} fields set, in
24997 which case it will be converted to \atentry{abbreviation}. If there
24998 is no \field{description} and \converterlongarg{index-conversion} is
24999 used, then \atentry{index} will be used instead of \atentry{entry}
25000 (but not if the term has been identified as an abbreviation).
25001
25002 \prefixedcssection{datagidx}{newacro}
25003 This is simply a wrapper command that internally uses
25004 \gls{datagidx.newterm}. However, \idx{datatool2bib} has a slightly
25005 different behaviour that doesn't add the formatting or case-changing
25006 commands (since these can be dealt with by the abbreviation style or
25007 \bibgls\ resource options).
25008
25009 \chapter{Examples}
25010 \label{sec:examples}
25011 \setsecdepth*{0}
25012 \renewcommand{\cssectioncmd}{\subsection}
25013
25014 The example files described here can be found in the
25015 \filefmt{examples} sub-directory. The \ext{bib} files are listed
25016 first and then sample files that use the \ext{bib} data.
25017 Make sure you have the latest versions of \styfmt{glossaries},
25018 \styfmt{mfirstuc}, \styfmt{glossaries-extra} and \bibgls\ if you
25019 want to try these out. (The \exfile{sample-media.tex} file requires
25020 at least \styfmt{datatool} v2.28.) If you get any undefined control
25021 sequence or undefined style errors then you need to update your
25022 \TeX\ distribution. Use the \longarg{group} switch when invoking
25023 \bibgls\ for all these examples if you want the glossaries divided
25024 into groups. The set of system calls for the document build in the
25025 examples below may require an extra \LaTeX\ run to ensure the PDF
25026 bookmarks are up-to-date when \sty{hyperref} is used.
25027
25028 These files are just examples of how to use \bibgls. There are other
25029 ways of defining similar entries and sometimes alternatives are
25030 suggested. Use the code here as a starting point if you need data
25031 like this and adapt it to a format appropriate for your
25032 requirements. There are also some example documents in the
25033 \href{https://www.dickimaw-books.com/gallery}{Dickimaw Books gallery}.
25034
25035 \filesection{no-interpret-preamble.bib}
25036
25037 The \exfile{no-interpret-preamble.bib} file contains command
25038 definitions used in some of the \field{name} fields. Although these
25039 commands aren't used explicitly in the document, they need to be
25040 defined when the names are displayed in the document (typically in
25041 the glossary). These commands are much like the \gls{sortop} command
25042 described on \glsxtrpageref{sortop} and need to be hidden
25043 from \bibgls's interpreter. This file doesn't contain any entry
25044 definitions and must be loaded first with
25045 \csopt[false]{interpret-preamble}. The
25046 \exfile{interpret-preamble.bib} or \exfile{interpret-preamble2.bib}
25047 file can then be loaded to provide alternative definitions for
25048 \bibgls's interpreter.
25049
25050 The first command is:
25051 \nosecdef{sortname}
25052 This is used in the \field{name} fields for entries containing
25053 information about a person. The aim here is for \bibgls\ to sort
25054 according to \meta{surname}, \meta{first name(s)} but for the
25055 glossary to display \meta{first name(s)} \meta{surname}. For names
25056 with a \qt{von} part, there's another command:
25057 \nosecdef{sortvonname}
25058 which has a similar purpose.
25059 The third command is:
25060 \nosecdef{sortart}
25061 This is the same as \gls{sortname} but is designed for titles,
25062 phrases or sentences that start with an article (such as \qt{a} or
25063 \qt{the}). Although it has the same definition as \gls{sortname}
25064 in this file, in the interpreted files the article part is omitted
25065 to completely ignore them in the sorting.
25066 The fourth command is:
25067 \nosecdef{sortmediacreator}
25068 which again is functionally the same as \gls{sortname}.
25069
25070 The names could be specified using \BibTeX's
25071 syntax instead with \csopt{bibtex-contributor-fields} to convert it,
25072 but the aim here is to show a variety of ways to use \bibgls. For an
25073 example of \csopt{bibtex-contributor-fields}, see the way the
25074 \fieldfmt{cast} field in \exfile{films.bib} is dealt with.
25075
25076 Although the file only contains ASCII characters, it starts with
25077 an \gls{encoding} line to prevent \bibgls\ from searching the entire file
25078 for it. (That's not so much of an issue with a short file, but may
25079 cause an unnecessary delay for much longer files.)
25080
25081 The contents of \filefmt{no-interpret-preamble.bib} are as follows:
25082 \lstinputlisting[firstline=5]{../examples/no-interpret-preamble.bib}
25083
25084 \filesection{interpret-preamble.bib}
25085
25086 This provides definitions of \gls{sortname}, \gls{sortvonname},
25087 \gls{sortart} and \gls{sortmediacreator} in \atentry{preamble}
25088 that can be picked up by the interpreter and used during sorting.
25089 Note that in this case \gls{sortart} is defined to ignore the
25090 article to completely ignore it from sorting. If you happen to have
25091 \qt{a \meta{something}} and \qt{the \meta{something}} where the
25092 \meta{something}s are identical, you may want to append the article
25093 to disambiguate them.
25094
25095 The contents of \filefmt{interpret-preamble.bib} are as follows:
25096 \lstinputlisting[firstline=5]{../examples/interpret-preamble.bib}
25097
25098 \filesection{interpret-preamble2.bib}
25099
25100 An alternative to \exfile{interpret-preamble.bib} with a different
25101 definition of \gls{sortmediacreator}. This uses \cs{renewcommand}
25102 instead of \cs{providecommand} so \csopt[false]{write-preamble}
25103 is required to prevent \LaTeX\ from picking up the definitions.
25104
25105 The contents of \filefmt{interpret-preamble2.bib} are as follows:
25106 \lstinputlisting[firstline=5]{../examples/interpret-preamble2.bib}
25107
25108 \filesection{constants.bib}
25109
25110 The \exfile{constants.bib} file contains mathematical constants.
25111 These all use a custom \gls{entrytype} \atentryfmt{constant}, which must
25112 be aliased otherwise the entries will all be ignored. The entries
25113 all have custom fields, which also need to be aliased.
25114 For example:
25115 \begin{codeenv}
25116 \csopt[constant=entry]{entry-type-aliases},
25117 \csopt[
25118 \fieldfmt{constantname}=\field{name},
25119 \fieldfmt{constantsymbol}=\field{symbol},
25120 \fieldfmt{definition}=\field{description},
25121 \fieldfmt{identifier}=\field{category},
25122 \fieldfmt{value}=\field{user1}
25123 ]{field-aliases}
25124 \end{codeenv}
25125 This setting means that, for example,
25126 \begin{codeenv}
25127 \atentryfmt{constant}\marg{root2,
25128 \fieldfmt{constantname}=\marg{Pythagoras' constant},
25129 \fieldfmt{constantsymbol}=\marg{\cs{ensuremath}\marg{\ics{surd}2}},
25130 \fieldfmt{definition}=\marg{the square root of 2},
25131 \fieldfmt{value}=\marg{1.41421},
25132 \fieldfmt{identifier}=\marg{constant}
25133 }
25134 \end{codeenv}
25135 is treated as though it was defined as:
25136 \begin{codeenv}
25137 \atentry{entry}\marg{root2,
25138 \field{name}=\marg{Pythagoras' constant},
25139 \field{symbol}=\marg{\cs{ensuremath}\marg{\cs{surd}2}},
25140 \field{description}=\marg{the square root of 2},
25141 \field{user1}=\marg{1.41421},
25142 \field{category}=\marg{constant}
25143 }
25144 \end{codeenv}
25145 This use of custom fields and \glspl{entrytype} allows more flexibility.
25146 For example, I may have another document that uses the same
25147 \ext{bib} file but requires a different definition:
25148 \begin{codeenv}
25149 \atentry{number}\marg{root2,
25150 \field{description}=\marg{Pythagoras' constant},
25151 \field{name}=\marg{\cs{ensuremath}\marg{\cs{surd}2}}
25152 }
25153 \end{codeenv}
25154 which can be obtained with:
25155 \begin{codeenv}
25156 \csopt[constant=number]{entry-type-aliases},
25157 \csopt[
25158 \fieldfmt{constantname}=\field{description},
25159 \fieldfmt{constantsymbol}=\field{name}
25160 ]{field-aliases}
25161 \end{codeenv}
25162 Since the other custom fields haven't be aliased, they're ignored.
25163
25164 The custom fields are: \fieldfmt{identifier} (set to \code{constant}
25165 for all the entries), \fieldfmt{constantname} (the constant's name),
25166 \fieldfmt{definition} (a definition of the constant),
25167 \fieldfmt{value} (the approximate numeric value of the constant),
25168 \fieldfmt{constantsymbol} (the symbolic representation of the
25169 constant) and \fieldfmt{alternative} (alternative symbol).
25170 There are three entries that don't have the custom
25171 \fieldfmt{value} field: \code{zero} and \code{one} (the exact value
25172 is in the \fieldfmt{constantsymbol} field in both cases) and \code{imaginary}
25173 (where there's no real number value).
25174
25175 I've provided some commands in the \atentry{preamble} for
25176 constants that are represented by Latin and Greek letters.
25177 These can be defined in the document before the \igls{resourceset}
25178 if different notation is required. The upright Greek commands require
25179 the \isty{upgreek} package.
25180
25181 If it's likely that there may be a need to sort according to
25182 \fieldfmt{definition}, then it would be better to use \gls!{sortart}
25183 describe above:
25184 \begin{codeenv}
25185 \atentryfmt{constant}\marg{root2,
25186 \fieldfmt{constantname}=\marg{Pythagoras' constant},
25187 \fieldfmt{constantsymbol}=\marg{\cs{ensuremath}\marg{\cs{surd}2}},
25188 \fieldfmt{definition}=\marg{\gls{sortart}\marg{the}\marg{square root of 2}},
25189 \fieldfmt{value}=\marg{1.41421},
25190 \fieldfmt{identifier}=\marg{constant}
25191 }
25192 \end{codeenv}
25193 Remember that this would need \exfile{no-interpret-preamble.bib} to
25194 ensure the command is recognised in the document.
25195
25196 The contents of \filefmt{constants.bib} are as follows:
25197 \lstinputlisting[firstline=5]{../examples/constants.bib}
25198
25199 \filesection{chemicalformula.bib}
25200
25201 The \exfile{chemicalformula.bib} file contains chemical formulae.
25202 Each entry has a field that uses \ics{ce} provided by \sty{mhchem}
25203 so the document will need to load that package. Since all resource
25204 files must be loaded in the preamble, it's possible to ensure that
25205 the package is loaded using:
25206 \begin{codeenv}
25207 \atentry{preamble}\marg{\qtdelim{\cs{usepackage}\marg{mhchem}}}
25208 \end{codeenv}
25209 However, it's best just to load it in the document otherwise it
25210 won't be available before the \ext{glstex} file has been loaded.
25211 Also, \sty{glossaries} (and therefore \sty{glossaries-extra}) must be
25212 loaded after \sty{hyperref}, which usually needs to be loaded last
25213 so most packages should be loaded before \sty{glossaries-extra}.
25214 Instead, I've just put a comment in the \ext{bib} file as a
25215 reminder.
25216
25217 All entries are defined using a custom \gls{entrytype}
25218 \atentryfmt{chemical}. This must be aliased using
25219 \csopt{entry-type-aliases} or the entries will be ignored. For
25220 example, to make \atentryfmt{chemical} behave like \atentry{symbol}:
25221 \begin{codeenv}
25222 \csopt[\fieldfmt{chemical}=\field{symbol}]{entry-type-aliases}
25223 \end{codeenv}
25224 Remember that with the \atentry{symbol} type, if the \field{sort}
25225 field is omitted \bibgls\ will fallback on the label by default. It
25226 can be changed to fallback on the \field{name} field instead using
25227 \csopt[name]{symbol-sort-fallback}. This will require the use of
25228 the interpreter if the name contains a command but \bibgls\
25229 recognises the \sty{mhchem} package and has a limited ability to
25230 interpret \cs{ce}. If \atentryfmt{chemical} is changed to
25231 \atentry{entry} instead then the fallback for the \field{sort} will be the
25232 entry's \field{name}.
25233
25234 All entries only contain custom fields, which will all be ignored by
25235 \bibgls\ unless defined or aliased: \fieldfmt{identifier}, which is set to
25236 \code{chemical} for all entries, \fieldfmt{formula}, which is set to the
25237 chemical formula, and \fieldfmt{chemicalname}, which is set to the chemical
25238 name. This allows the flexibility of determining whether the
25239 \field{name} or \field{symbol} field should contain the chemical
25240 formula on a per-resource basis. For example:
25241 \begin{codeenv}
25242 \csopt[\fieldfmt{formula}=\field{name},\fieldfmt{chemicalname}=\field{description}]{field-aliases}
25243 \end{codeenv}
25244 or
25245 \begin{codeenv}
25246 \csopt[\fieldfmt{chemicalname}=\field{name},\fieldfmt{formula}=\field{symbol}]{field-aliases}
25247 \end{codeenv}
25248
25249 The contents of \filefmt{chemicalformula.bib} are as follows:
25250 \lstinputlisting[firstline=5]{../examples/chemicalformula.bib}
25251
25252 \filesection{bacteria.bib}
25253
25254 The \exfile{bacteria.bib} file contains bacteria abbreviations.
25255 These all use the \atentry{abbreviation} \gls{entrytype} with a
25256 \field{short} and \field{long} field.
25257
25258 The entries all have a custom field \fieldfmt{identifier} set to
25259 \code{bacteria}. This will be ignored by \bibgls\ unless it's
25260 defined using \cs{glsaddkey} or \cs{glsaddstoragekey} or if it's
25261 aliased with \csopt{field-aliases}.
25262
25263 The contents of \filefmt{bacteria.bib} are as follows:
25264 \lstinputlisting[firstline=5]{../examples/bacteria.bib}
25265
25266 \filesection{baseunits.bib}
25267
25268 The \exfile{baseunits.bib} file contains base \idxpl{SIunit}. The entries
25269 are all defined using the custom \atentryfmt{unit}
25270 \gls{entrytype}. This must be aliased with \csopt{entry-type-aliases} otherwise
25271 \bibgls\ will ignore all the entries. For example:
25272 \begin{codeenv}
25273 \csopt[\fieldfmt{unit}=\field{symbol}]{entry-type-aliases}
25274 \end{codeenv}
25275 will make \bibgls\ treat the entries as though they were defined
25276 using \atentry{symbol}. (Remember that \atentry{symbol} \glspl{entrytype}
25277 use the label as the fallback field for \field{sort}.)
25278
25279 The entries all have custom fields \fieldfmt{unitname},
25280 \fieldfmt{unitsymbol} and \fieldfmt{measurement}, one of which must
25281 be aliased or copied to \field{name} if \atentryfmt{unit} is aliased
25282 to an \gls{entrytype} that requires it. The other custom fields may be aliased or
25283 copied to \field{symbol} and \field{description} as required. The
25284 \fieldfmt{unitsymbol} fields all use \ics{si} provided by the
25285 \isty{siunitx} package, so that package must be loaded in the
25286 document. This is one of the small number of packages recognised by
25287 \bibgls, so it's possible to sort according to the symbol if
25288 required.
25289
25290 The entries also all have a custom field \fieldfmt{identifier} set to
25291 \code{baseunit}. This will be ignored by \bibgls\ unless it's
25292 defined using \cs{glsaddkey} or \cs{glsaddstoragekey} or if it's
25293 aliased with \csopt{field-aliases}.
25294
25295 The contents of \filefmt{baseunits.bib} are as follows:
25296 \lstinputlisting[firstline=5]{../examples/baseunits.bib}
25297
25298 \filesection{derivedunits.bib}
25299
25300 The \exfile{derivedunits.bib} file is much like \exfile{baseunits.bib}
25301 but contains derived units and in this case the custom \gls{entrytype}
25302 is \atentryfmt{measurement}, which must be aliased
25303 otherwise the entries will all be ignored.
25304 The entries all have a custom field \fieldfmt{identifier} set to
25305 \code{derivedunit}. This will be ignored by \bibgls\ unless it's
25306 defined using \cs{glsaddkey} or \cs{glsaddstoragekey} or if it's
25307 aliased with \csopt{field-aliases}.
25308
25309 The contents of \filefmt{derivedunits.bib} are as follows:
25310 \lstinputlisting[firstline=5]{../examples/derivedunits.bib}
25311
25312 \filesection{people.bib}
25313
25314 The \exfile{people.bib} file contains details about people.
25315 The \field{name} fields contain custom commands provided in
25316 \exfile{no-interpret-preamble.bib} and
25317 \exfile{interpret-preamble.bib}.
25318 Remember that if \exfile{no-interpret-preamble.bib} is
25319 loaded first, the definitions provided in that file will be the one
25320 in use in the document. The \exfile{interpret-preamble.bib} file
25321 then needs to be loaded to provide the definitions for \bibgls's
25322 interpreter.
25323
25324 The information for each person is supplied in an \atentry{entry}
25325 type. There are some non-standard fields: \fieldfmt{born},
25326 \fieldfmt{died} and \fieldfmt{othername}. These fields will be ignored
25327 unless keys are provided (using \cs{glsaddkey} or
25328 \cs{glsaddstoragekey}) or the fields are aliased (using
25329 \csopt{field-aliases}). The \fieldfmt{born} and \fieldfmt{died}
25330 fields have dates that are \emph{almost} in the default \code{en-GB}
25331 locale format with the \idx{JRE} \idx{localeprovider}, but they include a
25332 tilde \idx{nbspchar} to prevent awkward line breaks. By default \bibgls's
25333 interpreter converts \idx{nbspchar} to the non-breaking space character
25334 \hex{A0} which isn't recognised by the date format. This can easily
25335 be fixed with the \longarg{break-space} switch which will interpret
25336 \idx{nbspchar} as a normal breakable space (\hex{20}), so with that switch
25337 \csopt[date]{sort} or \csopt[date-reverse]{sort} can be used on
25338 either of those fields. However, the \idx{CLDR} has a slightly
25339 different default format than the \idx{JRE} for dates with
25340 \code{en-GB}, so it's probably simplest to actually specify the
25341 required format.
25342
25343 An alternative approach would be to provide a command that can be
25344 modified in the document to adjust the date style. For example, the
25345 \fieldfmt{born} field could be specified as:
25346 \begin{codeenv}
25347 \fieldfmt{born}=\marg{\cmd{formatdate}\marg{13}\marg{7}\marg{100}\marg{BC}}
25348 \end{codeenv}
25349 The definition provided for the document could then be, for example:
25350 \begin{codeenv}
25351 \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}
25352 \end{codeenv}
25353 (where \ics{DTMdisplaydate} is provided by the \isty{datetime2}
25354 package) and a definition could be provided for \bibgls's
25355 interpreter, for example:
25356 \begin{codeenv}
25357 \cs{providecommand}\marg{\cmd{formatdate}}[4]\marg{\idx{param}1/\idx{param}2/\idx{param}3 \idx{param}4}
25358 \end{codeenv}
25359 This would need the date format set. For example,
25360 \csopt[d/M/y G]{date-sort-format}.
25361
25362 Some of the entries, such as \code{caesar}, have a \field{first}
25363 field. In those cases the \field{first} field is slightly different
25364 from the \field{name} field (for example, \qt{Gaius} is omitted in
25365 \code{caesar}'s \field{first} field). The other entries don't have a
25366 \field{first} field. They can simply have the \field{name} copied to
25367 \field{first} with the \csopt{replicate-fields} option (so that the
25368 full name is shown on first use) or the \field{first} field can be
25369 ignored with \csopt{ignore-fields} (so all entries will use the
25370 \field{text} field on first use). The \csopt{replicate-override}
25371 option can be used to force the \field{name} field to be copied to
25372 the \field{first} field, even if the \field{first} field is already
25373 set. Alternatively, with \csopt[true]{replicate-override} and
25374 \csopt[\field{first}=\field{name}]{replicate-fields}, the \field{first} field be
25375 copied to the \field{name} field. For consistency, the \field{first}
25376 fields use the same custom commands as used in the \field{name}
25377 field.
25378
25379 There's one name with a \qt{von} part. In this case the \field{name}
25380 field is set to:
25381 \begin{codeenv}
25382 \gls{sortvonname}\marg{Manfred}\marg{von}\marg{Richthofen}
25383 \end{codeenv}
25384 which will come under the \qt{V} letter group since \gls{sortvonname}
25385 is defined as \meta{von} \meta{surname}, \meta{first name(s)}
25386
25387 If you prefer that this name should come under \qt{R} instead, then
25388 you need to adjust the definition of \gls{sortvonname}:
25389 \begin{codeenv}
25390 \atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{sortname}}[2]\marg{\idx{param}2, \idx{param}1}
25391 \cs{providecommand}\marg{\cmd{sortvonname}}[3]\marg{\idx{param}3, \idx{param}1 \idx{param}2}}}
25392 \end{codeenv}
25393 An alternative approach would be to format the names using
25394 \BibTeX's contributor syntax and use
25395 \csopt[name]{bibtex-contributor-fields} to convert them.
25396
25397 There are also some synonyms provided with \atentry{index}
25398 \glspl{entrytype} that have the \field{alias} field to redirect to the
25399 \gls{mainentry}. These don't include a \field{description} or any of the other
25400 fields as that would be redundant. All the information can be found
25401 in the \gls{mainentry}.
25402
25403 Except for the aliases, the entries have a custom field
25404 \fieldfmt{identifier} set to \code{person}. This will be ignored by
25405 \bibgls\ unless it's defined using \cs{glsaddkey} or
25406 \cs{glsaddstoragekey} or if it's aliased with \csopt{field-aliases}.
25407
25408 The contents of \filefmt{people.bib} are as follows:
25409 \lstinputlisting[firstline=5]{../examples/people.bib}
25410
25411 \filesection{books.bib}
25412
25413 The \exfile{books.bib} file contains details about books.
25414 As above, the entries use custom commands provided in
25415 \exfile{no-interpret-preamble.bib} and
25416 \exfile{interpret-preamble.bib} or
25417 \exfile{interpret-preamble2.bib}.
25418 The entries all have a custom field \fieldfmt{identifier} set to
25419 \code{book} and other custom fields \fieldfmt{author} and
25420 \fieldfmt{year}.
25421 These will be ignored by \bibgls\ unless they're
25422 defined using \cs{glsaddkey} or \cs{glsaddstoragekey} or if they're
25423 aliased with \csopt{field-aliases}.
25424
25425 There are other ways in which this data could be specified. For
25426 example, the \field{description} field could contain a brief summary
25427 (or \qt{log line}). The \fieldfmt{author} field could use \BibTeX's
25428 syntax instead with \csopt{bibtex-contributor-fields} to convert it.
25429 Alternatively, the entries could be defined using standard \BibTeX\
25430 \glspl{entrytype} that are all aliased to \atentry{bibtexentry}.
25431
25432 The contents of \filefmt{books.bib} are as follows:
25433 \lstinputlisting[firstline=5]{../examples/books.bib}
25434
25435 \filesection{films.bib}
25436
25437 The \exfile{films.bib} file contains details about films.
25438 As above, the entries use custom commands provided in
25439 \exfile{no-interpret-preamble.bib} and
25440 \exfile{interpret-preamble.bib}.
25441 The entries all have a custom field \fieldfmt{identifier} set to
25442 \code{film} and other custom fields \fieldfmt{cast}, \fieldfmt{director} and
25443 \fieldfmt{year}. These will be ignored by \bibgls\ unless they're
25444 defined using \cs{glsaddkey} or \cs{glsaddstoragekey} or if they're
25445 aliased with \csopt{field-aliases}.
25446
25447 This example file references entries defined in \exfile{books.bib}
25448 through the use of the special
25449 \glsdisp{idx.idprefix.extn}{\idprefixfmt{ext1}} prefix.
25450 To avoid a label conflict \exfile{films.bib} prefixes all labels
25451 with \idprefixfmt{film} rather than relying on \csopt{label-prefix}.
25452 This ensures that both \exfile{books.bib} and \exfile{films.bib}
25453 can be loaded in the same resource set (otherwise they'd have to be
25454 loaded in separate resource sets with different prefixes). Remember
25455 that you can use \gls{glsxtrnewgls}. For example:
25456 \begin{codeenv}
25457 \gls{glsxtrnewgls}\marg{film.}\marg{\cmd{film}}
25458 \end{codeenv}
25459 This means you can do, for example, just \verb|\film{bladerunner}|
25460 if you want to reference a film without worrying about the prefix.
25461
25462 As with all the example files, there are other ways in which
25463 to specify the data, depending on your requirements. For example,
25464 the \fieldfmt{director} field could use \BibTeX's contributor syntax
25465 (as the \fieldfmt{cast} field does). Some of
25466 the films actually had more than one director but only one is listed
25467 per film in this sample file for simplicity. Similarly, the
25468 \fieldfmt{cast} field only contains the principal actors rather than the
25469 complete list. The book on which the film is based
25470 could be contained in a cross-reference field or a custom
25471 \fieldfmt{basedon} field.
25472
25473 The book \qt{Do Androids Dream of Electric Sheep?}\ referenced at the end
25474 of the \qt{Blade Runner} film's \field{description} ends with
25475 a question mark. (Similarly for \qt{Why Didn't They Ask Evans?})
25476 If the \field{description} field is simply set as:
25477 \begin{codeenv}
25478 \field{description}=\marg{a film starring Harrison Ford, Rutger Hauer
25479 and Sean Young loosely based on the novel
25480 \cs{gls}\marg{ext1.doandroidsdreamofelectricsheep}},
25481 \end{codeenv}
25482 then the \styopt{postdot} package option will produce an odd
25483 result as the inserted \idx{full-stop} immediately follows the question
25484 mark. This is an awkward situation. One possibility is to explicitly
25485 put the \idx{full-stop} at the end of the \field{description} field for all the
25486 other entries and omit it for the problematic entries, but this
25487 interferes with the possibility of a category-dependent
25488 \idx{postdescriptionhook}.
25489
25490 Another option is to put \ics{nopostdesc} in the
25491 problematic entries. For example:
25492 \begin{codeenv}
25493 \field{description}=\marg{a film starring Harrison Ford, Rutger Hauer
25494 and Sean Young loosely based on the novel
25495 \cs{gls}\marg{ext1.doandroidsdreamofelectricsheep}\cs{nopostdesc}},
25496 \end{codeenv}
25497 Be careful with this as it will completely suppress the
25498 \idx{postdescriptionhook}.
25499 A third possibility is to use \ics{glsxtrnopostpunc} instead:
25500 \begin{codeenv}
25501 \field{description}=\marg{a film starring Harrison Ford, Rutger Hauer
25502 and Sean Young loosely based on the novel
25503 \cs{gls}\marg{ext1.doandroidsdreamofelectricsheep}\cs{glsxtrnopostpunc}},
25504 \end{codeenv}
25505 This doesn't interfere with the \idx{postdescriptionhook} but if a hook
25506 is provided the post-punctuation may then be required. In both of
25507 the above two cases, \csopt{strip-trailing-nopost} could be used
25508 to remove the suppression commands from the \field{description}
25509 fields if a hook is defined. However this doesn't deal with hooks
25510 that only conditionally append text.
25511
25512 The best solution is with \styfmt{glossaries-extra} v1.23+ which
25513 provides \ics{glsxtrrestorepostpunc} for use in the category
25514 \idxpl{postdescriptionhook} that counteracts \cs{glsxtrnopostpunc}.
25515 This can be placed inside a \idx{conditional}, as used in
25516 \exfile{sample-media.tex}, and does nothing if \cs{glsxtrnopostpunc}
25517 doesn't occur in the \field{description} field. (Note that
25518 \cs{glsxtrrestorepostpunc} can't be used to counteract
25519 \cs{nopostdesc}, since that completely suppresses the hook.)
25520
25521 The contents of \filefmt{films.bib} are as follows:
25522 \lstinputlisting[firstline=5]{../examples/films.bib}
25523
25524 \filesection{citations.bib}
25525
25526 The \exfile{citations.bib} file is actually a \BibTeX\ file, but it
25527 can be parsed by \bibgls\ if the \BibTeX\ \glspl{entrytype} are converted
25528 to \atentry{bibtexentry}, which can easily be done with:
25529 \begin{codeenv}
25530 \csopt[\ics{GlsXtrBibTeXEntryAliases}]{entry-type-aliases}
25531 \end{codeenv}
25532 The field names will also need to be defined or aliased. For
25533 example:
25534 \begin{codeenv}
25535 \csopt[\fieldfmt{title}=\field{name}]{field-aliases}
25536 \end{codeenv}
25537 If \bibgls\ is then run with \longarg{cite-as-record} any
25538 \ics{citation} commands found in the \ext{aux} file will be treated
25539 as ignored records. The \atentry{preamble} provides a formatting
25540 command that's used by both \BibTeX\ and \bibgls, so \cs{providecommand}
25541 is required rather than \cs{newcommand} as it will appear in both
25542 the \iext{bbl} and the \iext{glstex} files. (In general it's best to
25543 use \cs{providecommand} rather than \cs{newcommand} in the
25544 \atentry{preamble} but in this case it's essential.)
25545 The contents of \filefmt{citations.bib} are as follows:
25546 \lstinputlisting[firstline=5]{../examples/citations.bib}
25547
25548 \filesection{mathgreek.bib}
25549
25550 The \exfile{mathgreek.bib} file contains Greek letters for use in
25551 maths mode. These are all defined with \atentry{symbol}, which means
25552 that by default the \field{sort} field will be obtained from the
25553 label not from the \field{name} field. However, if you want to sort
25554 by the \field{name} field (for example, with \csopt[name]{sort-field})
25555 the \texparserlib\ recognises all the mathematical Greek letter commands
25556 provided in the \LaTeX\ kernel. Additionally it recognises
25557 \ics{omicron} which isn't provided by \LaTeX\ (the symbol can be
25558 reproduced with a \idx!{lowercase} Latin \qt{o}). Note that
25559 \isty{glossaries-extra-bib2gls} (\sty{glossaries-extra} v1.27+)
25560 provides all the missing Greek letters (such as \cs{omicron}).
25561
25562 The \ext{bib} file could just use \code{o}:
25563 \begin{codeenv}
25564 \atentry{symbol}\marg{omicron,
25565 \field{name}=\marg{\cs{ensuremath}\marg{o}},
25566 \field{description}=\marg{omicron},
25567 \fieldfmt{identifier}=\marg{mathgreek}
25568 }
25569 \end{codeenv}
25570 but this means that if \bibgls\ sorts according to the \field{name}
25571 field using a letter sort, this entry will come before all the other
25572 Greek letters since the character \qt{o} has Unicode value \hex{6F}
25573 whereas, for example, mathematical italic small alpha ($\alpha$)
25574 has Unicode value \hex{1D6FC}. This means that for sorting purposes
25575 it's better to use \ics{omicron}:
25576 \begin{codeenv}
25577 \atentry{symbol}\marg{omicron,
25578 \field{name}=\marg{\cs{ensuremath}\marg{\cs{omicron}}},
25579 \field{description}=\marg{omicron},
25580 \fieldfmt{identifier}=\marg{mathgreek}
25581 }
25582 \end{codeenv}
25583 but \LaTeX\ needs a definition for this, so it's provided in the
25584 \atentry{preamble}:
25585 \begin{codeenv}
25586 \atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cs{omicron}}\marg{o}}}
25587 \end{codeenv}
25588 (With \sty{glossaries-extra} v1.27+, this is no longer needed.)
25589 The \texparserlib\ and \sty{glossaries-extra-bib2gls}
25590 similarly provide the missing \idx!{uppercase}
25591 Greek letters, and these can be dealt with in the same way.
25592
25593 The contents of \filefmt{mathgreek.bib} are as follows:
25594 \lstinputlisting[firstline=5]{../examples/mathgreek.bib}
25595
25596 \filesection{bigmathsymbols.bib}
25597
25598 The \exfile{bigmathsymbols.bib} file contains mathematical symbols
25599 that have a large version in display mode. As with
25600 \exfile{mathgreek.bib} the entries are defined using
25601 \atentry{symbol}. This example file requires the \isty{stix} package
25602 as not all of the commands are provided by the \LaTeX\ kernel.
25603 This file also has a preamble:
25604 \begin{codeenv}
25605 \atentry{preamble}\marg{\qtdelim{\cmd{providecommand}\marg{\cmd{bigoperatornamefmt}}[1]\marg{\comment{}
25606 \idx{mshiftchar}\ics{displaystyle}\idx{param}1\ics{textstyle}\idx{param}1\idx{mshiftchar}}
25607 \cmd{providecommand}\marg{\cmd{nary}}[1]\marg{\idx{mshiftchar}\idx{param}1\idx{mshiftchar}-ary}}}
25608 \end{codeenv}
25609 The first command \inlinedef{bigoperatornamefmt}
25610 is used in the \field{name} field to display both the in-line and display
25611 versions of the symbol. The \texparserlib\ only has a limited ability to
25612 interpret this as not all the symbols have Unicode in-line and large versions.
25613 In some cases, such as the integral symbol $\int$, there is only a small
25614 version. (A large version would require construction from \hex{2320},
25615 \hex{23AE} and \hex{2321}, which is too complicated in this context.)
25616 However, the interpreter works well enough to guess at the widest
25617 name if \csopt{set-widest} is used. There's no advantage in sorting
25618 according to the \field{name} field here, unless a custom rule is
25619 provided, as the Unicode symbols are scattered about different
25620 blocks. Better approaches are to sort according to document use
25621 (\csopt[use]{sort}) or to sort according to the \field{description}
25622 field.
25623
25624 The other custom command is \inlinedef{nary} to provide semantic markup for
25625 \qt{$n$-ary}. This could be defined without an argument:
25626 \begin{codeenv}
25627 \cmd{providecommand}\marg{\cmd{nary}}\marg{\idx{mshiftchar}n\idx{mshiftchar}-ary}
25628 \end{codeenv}
25629 but providing an argument will allow \code{\csfmt{nary}\marg{n}} to work
25630 with first letter upper-casing in the event that the
25631 \field{description} field has a case-change applied (otherwise
25632 it would end up as \qt{$N$-ARY}). Of course, it may be that no case-change
25633 should be applied, but this example is just for illustrative purposes.
25634
25635 As with the other sample \ext{bib} files, each entry is given a
25636 custom \fieldfmt{identifier} field, which by default will be
25637 ignored. In this case, \fieldfmt{identifier} is either set to
25638 \code{naryoperator} (for $n$-ary operators) or \code{integral}
25639 for integrals.
25640
25641 The contents of \filefmt{bigmathsymbols.bib} are as follows:
25642 \lstinputlisting[firstline=5]{../examples/bigmathsymbols.bib}
25643
25644 \filesection{mathsrelations.bib}
25645
25646 The \exfile{mathsrelations.bib} file contains mathematical
25647 relational symbols. These use the maths shift character
25648 \idx{mshiftchar} in the \field{name} field and just the symbol in
25649 the \field{text} field. This just illustrates an alternative way of
25650 defining symbols. Since \ics{ensuremath} isn't used, commands like
25651 \cs{gls} must be explicitly placed in maths mode. For example,
25652 \code{\idx{mshiftchar}\cs{gls}\marg{leq}\idx{mshiftchar}} rather than simply
25653 \code{\cs{gls}\marg{leq}}. The custom \fieldfmt{identifier} field is
25654 set to \code{relation}.
25655
25656 The contents of \filefmt{mathsrelations.bib} are as follows:
25657 \lstinputlisting[firstline=5]{../examples/mathsrelations.bib}
25658
25659 \filesection{binaryoperators.bib}
25660
25661 The \exfile{binaryoperators.bib} file contains mathematical binary
25662 operators. The format is much like the above
25663 \exfile{mathsrelations.bib} file. The custom \fieldfmt{identifier}
25664 field is set to \code{binaryoperator}.
25665
25666 The contents of \filefmt{binaryoperators.bib} are as follows:
25667 \lstinputlisting[firstline=5]{../examples/binaryoperators.bib}
25668
25669 \filesection{unaryoperators.bib}
25670
25671 The \exfile{unaryoperators.bib} file contains mathematical unary
25672 operators. As above, this again uses \atentry{symbol} to define the symbols,
25673 but in this case \ics{ensuremath} is used in the \field{name}
25674 field and there's no \field{text} field. I've also used \ics{mathord}
25675 to ensure the symbol is treated as a unary (rather than binary)
25676 operator, except for the \ics{forall} entry which is already defined as an
25677 ordinary maths symbol.
25678
25679 The contents of \filefmt{unaryoperators.bib} are as follows:
25680 \lstinputlisting[firstline=5]{../examples/unaryoperators.bib}
25681
25682 \filesection{mathsobjects.bib}
25683
25684 The \exfile{mathsobjects.bib} file contains entries related to
25685 mathematical objects (sets, spaces, vectors and matrices). This
25686 provides some custom formatting commands in the preamble:
25687 \nosecdef{setfmt}
25688 which is used to format \meta{symbol} as a set,
25689 \nosecdef{setcontentsfmt}
25690 which is used to format the set contents,
25691 \nosecdef{setmembershipfmt}
25692 which is used to format the set membership criteria,
25693 \nosecdef{setcardfmt}
25694 which is used to format the cardinality of a set,
25695 (Note this uses \ics{vert} not \textbar\ as in some of the earlier
25696 examples.)
25697 \nosecdef{numspacefmt}
25698 which is used to format \meta{symbol} as a number space,
25699 \nosecdef{transposefmt}
25700 which is used to format matrix and vector transposes,
25701 \nosecdef{invfmt}
25702 which is used to format inverses,
25703 \nosecdef{vecfmt}
25704 which is used to format \meta{symbol} as a vector, and
25705 \nosecdef{mtxfmt}
25706 which is used to format \meta{symbol} as a matrix.
25707 These commands are intended for use with \gls{glsxtrfmt},
25708 but \gls!{setmembershipfmt} causes a problem as it has two
25709 arguments and \gls{glsxtrfmt} requires the control sequence to
25710 have exactly one argument. This means employing a little trick.
25711 A command with just one argument is provided:
25712 \nosecdef{setmembershiponeargfmt}
25713 that requires the actual two arguments to be supplied inside
25714 \code{\idx!{param}1}. The outer grouping is removed and the two-argument
25715 \gls!{setmembershipfmt} command is applied:
25716 \begin{codeenv}
25717 \cs{providecommand}\marg{\gls{setmembershiponeargfmt}}[1]\marg{\gls{setmembershipfmt}\idx{param}1}
25718 \end{codeenv}
25719 This means that the entry needs to be referenced in the document
25720 using:
25721 \begin{codeenv}
25722 \gls{glsxtrfmt}\marg{setmembership}\marg{\margm{variable(s)}\margm{condition}}
25723 \end{codeenv}
25724 The simplest thing to do here is to provide a wrapper command in the
25725 document, for example:
25726 \begin{codeenv}
25727 \cs{newcommand}*\marg{\cmd{setmembership}}[2]\marg{\gls{glsxtrfmt}\marg{setmembership}\marg{\marg{\idx{param}1}\marg{\idx{param}2}}}
25728 \end{codeenv}
25729 Now this can be used as:
25730 \begin{codeenv}
25731 \cmd{setmembership}\margm{variable(s)}\margm{condition}
25732 \end{codeenv}
25733
25734 There are essentially two types of entry defined in this file:
25735 entries that demonstrate the formatting for the objects
25736 and entries that represent specific objects. In the first case
25737 there's a custom \fieldfmt{format} field
25738 that's set to the control sequence name of the relevant semantic
25739 command. If this field is defined or aliased then it can be used
25740 with \gls!{glsxtrfmt} (as in the example above).
25741
25742 In both cases there's a custom \fieldfmt{identifier} field that
25743 reflects the type of object: \code{set} for sets,
25744 \code{numberspace} for number spaces,
25745 \code{matrix} for matrices or vectors.
25746
25747 Be careful with the set cardinality example. Remember that nested
25748 links cause problems and the \sty{glossaries-extra} manual advises
25749 against using commands like \cs{gls} or \gls!{glsxtrfmt} within
25750 link text and that includes within the \meta{text} argument of
25751 \gls!{glsxtrfmt}. See \exfile{sample-maths.tex} for suggested
25752 usage.
25753
25754 Some of the \field{description} fields use \gls!{sortart}, so
25755 \exfile{no-interpret-preamble.bib} and
25756 \exfile{interpret-preamble.bib} are also needed.
25757
25758 The contents of \filefmt{mathsobjects.bib} are as follows:
25759 \lstinputlisting[firstline=5]{../examples/mathsobjects.bib}
25760
25761 \filesection{miscsymbols.bib}
25762
25763 The \exfile{miscsymbols.bib} file contains text symbols provided
25764 by the \isty{marvosym} and \isty{ifsym} packages. The \sty{ifsym}
25765 package needs to be loaded with the \styoptfmt{weather} option
25766 to provide the weather commands. Unfortunately both packages define
25767 \csfmt{Sun} and \csfmt{Lightning}, which causes a conflict. See
25768 \exfile{sample-textsymbols.tex} for a workaround. Alternatively,
25769 you can load \sty{ifsym} without the \styoptfmt{weather} option
25770 and use the internal definition of \sty{ifsym}'s \csfmt{Sun}
25771 and \csfmt{Lightning} commands:
25772 \begin{codeenv}
25773 \atentryfmt{icon}\marg{sun,
25774 \fieldfmt{icon}=\marg{\ics{textweathersymbol}\marg{16}},
25775 \fieldfmt{description}=\marg{sunny},
25776 \fieldfmt{identifier}=\marg{weather}
25777 }
25778 \strut
25779 \atentryfmt{icon}\marg{lightning,
25780 \fieldfmt{icon}=\marg{\cs{textweathersymbol}\marg{26}},
25781 \field{description}=\marg{thunderstorm},
25782 \fieldfmt{identifier}=\marg{weather}
25783 }
25784 \end{codeenv}
25785 This removes the conflict, and \csfmt{Sun} and \csfmt{Lightning}
25786 are as defined by \sty{marvosym}.
25787
25788 This file uses a custom \gls{entrytype} \atentryfmt{icon}, which must be
25789 aliased to a recognised entry identifier otherwise the entries will
25790 all be ignored. For example:
25791 \begin{codeenv}
25792 \csopt[\fieldfmt{icon}=\field{symbol}]{entry-type-aliases}
25793 \end{codeenv}
25794
25795 There are three types of symbols defined: media controls, information
25796 and weather. They have the custom \fieldfmt{identifier}
25797 field set to \code{mediacontrol}, \code{information} and
25798 \code{weather}, respectively. There are two other custom fields:
25799 \fieldfmt{icon} and \fieldfmt{icondescription}. These will need to
25800 be aliased to \field{name} and \field{description}.
25801
25802 Neither of these packages are recognised by \bibgls, which means
25803 that \csopt{set-widest} won't be able to determine the widest name
25804 nor is this data suitable for sorting according to the
25805 \fieldfmt{icon} field (or its alias). Instead, either sort by label
25806 (which is the default for \atentry{symbol}) or by the
25807 \field{description}. If you want to use one of the
25808 \glostyle{alttree} styles you can still use \csopt{set-widest}, but
25809 it will have to use the fallback command. Alternatively, you can
25810 omit \csopt{set-widest} and explicitly use
25811 \cs{glsFindWidestTopLevelName}.
25812
25813 The contents of \filefmt{miscsymbols.bib} are as follows:
25814 \lstinputlisting[firstline=5]{../examples/miscsymbols.bib}
25815
25816 \filesection{markuplanguages.bib}
25817
25818 The \exfile{markuplanguages.bib} file includes a mixture of
25819 \atentry{entry} and \atentry{abbreviation} definitions. A~custom
25820 command is provided in \atentry{preamble} to tag the letters
25821 in the \field{long} field that are used to form the abbreviation.
25822 This simply does its argument and is provided in case it's not set
25823 up in the document. If you do want to enable tagging using
25824 \ics{GlsXtrEnableInitialTagging}, remember that this command must be
25825 used before the abbreviations are defined, which means before
25826 the resource file is input with \gls{GlsXtrLoadResources}.
25827 Similarly, the abbreviation style must be set before the
25828 abbreviations are defined.
25829
25830 For convenience \atentry{string} is also used to define a \ext{bib}
25831 variable, which may be appended to fields using the \ext{bib}
25832 concatenation character \idx{stringconcat}. As with the other sample
25833 \ext{bib} files, there's a custom field \fieldfmt{identifier}
25834 which will be ignored unless defined or aliased.
25835
25836 The empty braces at the start some of the fields are there to
25837 protect against first letter uppercasing within \TeX, where it might cause a
25838 problem. (For example, with the \catattr{glossname} attribute.)
25839
25840 The contents of \filefmt{markuplanguages.bib} are as follows:
25841 \lstinputlisting[firstline=5]{../examples/markuplanguages.bib}
25842
25843 \filesection{usergroups.bib}
25844
25845 The \exfile{usergroups.bib} file requires either \XeLaTeX\ or
25846 \LuaLaTeX\ as some of the entry labels use \idx{non-ASCII} characters.
25847 This file has a mixture of \atentry{abbreviation} and
25848 \atentry{index} entries. It also uses \atentry{string} for
25849 convenience and provides a custom command \csfmt{dash} in
25850 \atentry{preamble}. Each entry is the name of a \TeX\ user group:
25851 the international \idx{TUG} and all the local groups.
25852 Most of them have an abbreviated name, so they're defined with
25853 \atentry{abbreviation}. There are a few without an abbreviation, so
25854 they're defined with \atentry{index} instead. There's one alias.
25855 (The information was obtained from \idx{TUG}['s]
25856 \href{http://tug.org/usergroups.html}{user groups
25857 page}~\cite{tugusergroups}.)
25858
25859 As with the other examples, there are some custom fields which will
25860 be ignored if they aren't defined or aliased: \fieldfmt{identifier}
25861 (set to \code{texusergroup}), \fieldfmt{language} (a comma-separated
25862 list of language tags) and \fieldfmt{translation} (provides a
25863 translation if the user group name isn't in English).
25864
25865 Not all entries have a \fieldfmt{translation} field. It it's
25866 omitted, then the user group name is in English, otherwise it's
25867 in the first language listed in the \fieldfmt{language} field.
25868 Most of the language tags are just the ISO 639-1 language code, but
25869 a few of them include the ISO 3166-1 region code as well.
25870
25871 The contents of \filefmt{usergroups.bib} are as follows:
25872 \begin{lstlisting}[escapechar=|]
25873 % Encoding: UTF-8
25874
25875 % Requires XeLaTeX/LuaLaTeX for non-ASCII labels
25876
25877 @string{tug={\TeX\ Users Group}}
25878
25879 @preamble{"\providecommand{\dash}{\,---\,}"}
25880
25881 @abbreviation{TUG,
25882 short={TUG},
25883 long=tug,
25884 language={en},
25885 identifier={texusergroup}
25886 }
25887
25888 @abbreviation{bgTeX,
25889 short={bgTeX},
25890 long={Bulgarian \LaTeX\ Users Group},
25891 language={bg},
25892 identifier={texusergroup}
25893 }
25894
25895 @abbreviation{latex-br,
25896 short={latex-br},
25897 long={Grupo de Usuários},
25898 language={pt-BR},
25899 identifier={texusergroup},
25900 translation={Brazilian }#tug
25901 }
25902
25903 @abbreviation{CTeX,
25904 short={CTeX},
25905 long={Chinese \TeX\ Society},
25906 identifier={texusergroup},
25907 language={zh}
25908 }
25909
25910 @abbreviation{CSTUG,
25911 short={CSTUG},
25912 long={|Československé sdružení uživatelů TeXu|, z.~s.},
25913 language={cs},
25914 identifier={texusergroup},
25915 translation={Czech Republic }#tug
25916 }
25917
25918 @abbreviation{DANTE,
25919 short={DANTE e.V.},
25920 long={Deutschsprachige Anwendervereinigung \TeX\ e.V.},
25921 language={de},
25922 identifier={texusergroup},
25923 translation={German Speaking }#tug
25924 }
25925
25926 @abbreviation{DKTUG,
25927 short={DK-TUG},
25928 long={Danish }#tug,
25929 language={da},
25930 identifier={texusergroup}
25931 }
25932
25933 @index{EUG,
25934 name={Estonian User Group},
25935 language={et},
25936 identifier={texusergroup}
25937 }
25938
25939 @abbreviation{CervanTeX,
25940 short={CervanTeX},
25941 long={Grupo de Usuarios de \TeX\ Hispanohablantes},
25942 language={es},
25943 identifier={texusergroup},
25944 translation={Spanish Speaking }#tug
25945 }
25946
25947 @abbreviation{TirantloTeX,
25948 short={Tirant lo \TeX},
25949 long={Catalan }#tug,
25950 language={ca},
25951 identifier={texusergroup}
25952 }
25953
25954 @abbreviation{GUTenberg,
25955 short={GUTenberg},
25956 long={Groupe francophone des utilisateurs de \TeX},
25957 language={fr},
25958 identifier={texusergroup},
25959 translation={French Speaking }#tug
25960 }
25961
25962 @abbreviation{UKTUG,
25963 short={UK-TUG},
25964 long={UK }#tug,
25965 language={en-GB},
25966 identifier={texusergroup}
25967 }
25968
25969 @abbreviation{|\greekmono ɛϕτ|,
25970 short={|\greekmono ɛϕτ|},
25971 long={|\greekmono Σύλλογος Ελλήνων Φίλων του| \TeX},
25972 language={el},
25973 identifier={texusergroup},
25974 translation={Greek \TeX\ Friends}
25975 }
25976
25977 @abbreviation{MaTeX,
25978 short={MaTeX},
25979 long={Magyar \TeX\ Egyesület},
25980 language={hu},
25981 identifier={texusergroup},
25982 translation={Hungarian }#tug
25983 }
25984
25985 @abbreviation{ITALIC,
25986 short={ITALIC},
25987 long={Irish \TeX\ and \LaTeX\ In-print Community},
25988 language={en-IE,en-GB},
25989 identifier={texusergroup}
25990 }
25991
25992 @abbreviation{ÍsTeX,
25993 short={ÍsTeX},
25994 long={Vefur íslenskra \TeX\ notenda},
25995 language={is},
25996 identifier={texusergroup},
25997 translation={Icelandic }#tug
25998 }
25999
26000 @abbreviation{GuIT,
26001 short={GuIT},
26002 long={Gruppo Utilizzatori Italiani di \TeX},
26003 language={it},
26004 identifier={texusergroup},
26005 translation={Italian }#tug
26006 }
26007
26008 @abbreviation{KTS,
26009 short={KTS},
26010 identifier={texusergroup},
26011 long={Korean \TeX\ Society},
26012 language={ko}
26013 }
26014
26015 @index{KTUG,
26016 alias={KTS},
26017 identifier={texusergroup}
26018 }
26019
26020 @index{LTVG,
26021 name={Lietuvos \TeX'o |Vartotojų Grupė|},
26022 language={lt},
26023 identifier={texusergroup},
26024 translation={Lithuanian }#tug
26025 }
26026
26027 @index{mxTeX,
26028 name={\TeX\ México},
26029 language={es-MX},
26030 identifier={texusergroup},
26031 translation={Mexican }#tug
26032 }
26033
26034 @abbreviation{NTG,
26035 short={NTG},
26036 long={Nederlandstalige \TeX\ Gebruikersgroep},
26037 language={nl},
26038 identifier={texusergroup},
26039 translation={Netherlands }#tug
26040 }
26041
26042 @index{NTUG,
26043 name={Nordic \TeX\ Users Group},
26044 language={da,et,fi,fo,is,nb,nn,sv},
26045 identifier={texusergroup}
26046 }
26047
26048 @abbreviation{GUST,
26049 short={GUST},
26050 long={Polska Grupa |Użytkowników| Systemu \TeX},
26051 language={pl},
26052 identifier={texusergroup},
26053 translation={Polish }#tug
26054 }
26055
26056 @abbreviation{GUTpt,
26057 short={GUTpt},
26058 long={Grupo de Utilizadores de \TeX},
26059 language={pt},
26060 identifier={texusergroup},
26061 translation={Portuguese }#tug
26062 }
26063
26064 @abbreviation{VietTUG,
26065 short={VietTUG},
26066 long={Vietnamese }#tug,
26067 language={vi},
26068 identifier={texusergroup}
26069 }
26070
26071 @abbreviation{LUGSA,
26072 short={LUGSA},
26073 long={\LaTeX\ User Group\dash South Africa},
26074 language={en-ZA},
26075 identifier={texusergroup}
26076 }
26077
26078
26079 \end{lstlisting}
26080
26081 \filesection{animals.bib}
26082
26083 The \exfile{animals.bib} file contains entries defined using
26084 \atentry{entry}. As with the above example \ext{bib} files, there's
26085 a custom \fieldfmt{identifier} field that will be ignored unless
26086 defined or aliased.
26087
26088 The contents of \filefmt{animals.bib} are as follows:
26089 \lstinputlisting[firstline=5]{../examples/animals.bib}
26090
26091 \filesection{minerals.bib}
26092
26093 The \exfile{minerals.bib} file contains entries defined using
26094 \atentry{entry}. As with the above example \ext{bib} files, there's
26095 a custom \fieldfmt{identifier} field that will be ignored unless
26096 defined or aliased.
26097
26098 The contents of \filefmt{minerals.bib} are as follows:
26099 \lstinputlisting[firstline=5]{../examples/minerals.bib}
26100
26101 \filesection{vegetables.bib}
26102
26103 The \exfile{vegetables.bib} file contains entries defined using
26104 \atentry{entry} and an entry defined with \atentry{index} with just
26105 the \field{alias} field. As with the above example \ext{bib} files, there's
26106 a custom \fieldfmt{identifier} field that will be ignored unless
26107 defined or aliased.
26108
26109 The contents of \filefmt{vegetables.bib} are as follows:
26110 \lstinputlisting[firstline=5]{../examples/vegetables.bib}
26111
26112 \filesection{terms.bib}
26113
26114 The \exfile{terms.bib} file contains entries defined using
26115 \atentry{index}. Unlike the above sample \ext{bib} files, there
26116 are no custom fields here.
26117
26118 The contents of \filefmt{terms.bib} are as follows:
26119 \lstinputlisting[firstline=5]{../examples/terms.bib}
26120
26121 \filesection{topics.bib}
26122
26123 The \exfile{topics.bib} file contains entries defined using
26124 \atentry{index}. Again there are no custom fields here.
26125
26126 The contents of \filefmt{topics.bib} are as follows:
26127 \lstinputlisting[firstline=5]{../examples/topics.bib}
26128
26129 \filesection{sample-hierarchical.tex}
26130
26131 This example uses the \exfile{terms.bib}, \exfile{animals.bib},
26132 \exfile{minerals.bib} and \exfile{vegetables.bib} files to create a
26133 \gls{hierarchicalglossary}. These are specified with the resource option:
26134 \begin{codeenv}
26135 \csopt[{terms,animals,minerals,vegetables}]{src}
26136 \end{codeenv}
26137 The custom \fieldfmt{identifier} field is
26138 aliased to the \field{parent} field since it conveniently matches
26139 the labels of the animal, mineral and vegetable entries in the
26140 \exfile{terms.bib} file:
26141 \begin{codeenv}
26142 \csopt[{identifier=parent}]{field-aliases}
26143 \end{codeenv}
26144 The default \csopt{selection} setting means that only those terms
26145 referenced in the document and their dependencies are selected. The
26146 referenced entries simply have \qt{1} in the \igls{locationlist} as
26147 it's only a trivial single-paged example.
26148
26149 The dependencies that haven't actually been referenced in the
26150 document don't have a \igls{locationlist}. (The \qt{seal} entry is a
26151 dependency, but it's also been referenced in the document, so it has a
26152 \igls{locationlist}.) The \qt{quartz}, \qt{beryl} and \qt{marrow}
26153 entries are dependencies because they occur in the description of
26154 some of the referenced entries. Normally this would mean that they
26155 have no \igls{locationlist} after the first \LaTeX+\bibgls+\LaTeX\
26156 build but once the glossary has been created the references to those
26157 dependent entries in the descriptions will create records and so on
26158 the next \bibgls+\LaTeX\ they will also have \iglspl{locationlist}.
26159 This would make the complete document build:
26160 \begin{verbatim}
26161 pdflatex sample-hierarchical
26162 bib2gls --group sample-hierarchical
26163 pdflatex sample-hierarchical
26164 bib2gls --group sample-hierarchical
26165 pdflatex sample-hierarchical
26166 \end{verbatim}
26167 However, in this example I've decided to \glsdisp{ignoredrecord}{ignore} any records
26168 created in the glossary:
26169 \begin{codeenv}
26170 \ics{GlsXtrSetDefaultNumberFormat}\marg{\encap{glsignore}}
26171 \end{codeenv}
26172 This means that the document build is the usual \LaTeX+\bibgls+\LaTeX.
26173
26174 I've used the \glostyle{treegroup} style so I need to invoke
26175 \bibgls\ with the \longarg{group} switch. This creates letter groups
26176 for the \glspl{top-levelentry}. Note that \glspl{sub-entry} never have letter groups.
26177
26178 The complete code is listed below. The document build is:
26179 \begin{verbatim}
26180 pdflatex sample-hierarchical
26181 bib2gls --group sample-hierarchical
26182 pdflatex sample-hierarchical
26183 \end{verbatim}
26184 The complete document is shown in \figureref{fig:sample-hierarchical.pdf}.
26185
26186 \lstinputlisting[firstline=5]{../examples/sample-hierarchical.tex}
26187
26188 \begin{figure}
26189 \figcontents
26190 {%
26191 \frame{\includegraphics[height=.9\textheight]{../examples/sample-hierarchical.pdf}}%
26192 }
26193 {\caption{\filefmt{sample-hierarchical.pdf}}}
26194 {fig:sample-hierarchical.pdf}
26195 \end{figure}
26196
26197 \filesection{sample-nested.tex}
26198
26199 As discussed in \sectionref{sec:logicaldivisions} there are three
26200 ways of creating logical divisions when displaying the entries
26201 through the use of the \field{type}, \field{group} and \field{parent} fields.
26202 In general, \glspl{hierarchicalglossary} are created with
26203 the \field{parent} field and an appropriate glossary style (as in
26204 the previous \exfile{sample-hierarchical.tex} example).
26205
26206 This example creates a \hierarchical\ effect but the entries don't
26207 actually have a \hierarchical\ structure as none of them have the
26208 \field{parent} field set. Instead, what were the \glspl{childentry} in
26209 \exfile{sample-hierarchical.tex} now have the \field{type} field
26210 set. The \hierarchical\ effect is achieved with
26211 \ics{printunsrtinnerglossary} (which requires at least
26212 \sty{glossaries-extra} v1.44).
26213
26214 \begin{important}
26215 The \ics{printunsrtinnerglossary} command is unsuitable for use
26216 with tabular-like styles, such as \glostyle{long}, and can be
26217 problematic with \glostyle{list} styles. However, those styles
26218 aren't suitable for \glspl{hierarchicalglossary} anyway.
26219 \end{important}
26220
26221 Normally, \hierarchy\ is achieve through definitions like:
26222 \begin{codeenv}
26223 \atentry{index}\marg{animal}
26224 \atentry{entry}\marg{duck,\field{name}=\marg{duck},
26225 \field{description}=\marg{a waterbird with webbed feet},
26226 \field{parent}=\marg{animal}
26227 }
26228 \end{codeenv}
26229 The previous example did this by loading both the \exfile{terms.bib}
26230 and \exfile{animals.bib} files and aliasing the custom
26231 \fieldfmt{identifier} field to \field{parent}. In this example, the
26232 custom field is aliased to \field{type}, which effectively makes the
26233 definitions behave like:
26234 \begin{codeenv}
26235 \atentry{index}\marg{animal}
26236 \atentry{entry}\marg{duck,\field{name}=\marg{duck},
26237 \field{description}=\marg{a waterbird with webbed feet},
26238 \field{type}=\marg{animal}
26239 }
26240 \end{codeenv}
26241 The aim here is for the \code{animal} entry to be placed in the
26242 \gls{mainglossary} so that it's listed with \cs{printunsrtglossary}. The
26243 \code{duck} entry is placed in a glossary that has a label
26244 (\code{animal}) that matches the label of the \qt{parent} entry
26245 (even though it's technically not a \parent). This new glossary
26246 (\code{animal}) can be automatically defined by invoking \bibgls\
26247 with the \longarg{provide-glossaries} switch.
26248
26249 This example document defines a custom handler function that
26250 will do the current entry as normal (with \cs{glsxtrunsrtdo}) but
26251 will then check for the existence of a glossary that has the same
26252 label as the current entry. This requires the starred version of
26253 \ics{ifglossaryexists} to included ignored glossaries in the
26254 existence check. If the glossary exists, it's then displayed using
26255 \ics{printunsrtinnerglossary}:
26256 \begin{codeenv}
26257 \cs{newcommand}\marg{\csfmt{nestedhandler}}[1]\marg{\comment{}
26258 \cs{glsxtrunsrtdo}\marg{\idx{hashchar}1}\comment{}
26259 \ics{ifglossaryexists*}\marg{\idx{hashchar}1}\comment{}
26260 \marg{\comment{}
26261 \cs{printunsrtinnerglossary}\oarg{\printglossopt[\idx{hashchar}1]{type},\printglossopt[++1]{leveloffset},\printglossopt[false]{groups}}
26262 \marg{}\marg{}\comment{}
26263 }\comment{}
26264 \marg{}\comment{}
26265 }
26266 \end{codeenv}
26267 The \printglossopt{leveloffset} option is required to achieve a
26268 \hierarchical\ effect (provided the glossary style supports it) and
26269 the \printglossopt[false]{groups} option is needed to prevent letter
26270 groups showing for the nested glossary, which would otherwise create
26271 a strange effect. (This example uses the \glostyle{treegroup} style,
26272 which provides a \gls{hierarchicalglossary} with letter groups.)
26273
26274 The \cs{printunsrtglossary} handler macro then needs to be set to
26275 this custom macro when the \gls{mainglossary} is displayed:
26276 \begin{codeenv}
26277 \cs{printunsrtglossary*}\marg{\cs{let}\cs{printunsrtglossaryhandler}\csfmt{nestedhandler}}
26278 \end{codeenv}
26279 The main difficulty comes with ensuring that all the necessary
26280 entries are selected. Now that the custom \fieldfmt{identifier}
26281 field has been aliased to \field{type} rather than \field{parent},
26282 the \code{animal} entry is no longer considered a dependent. The
26283 \code{duck} entry has been referenced in the document with \cs{gls}
26284 but the \code{animal} entry hasn't. The previous example ensured
26285 that the \code{animal} entry was selected because it was a \parent\ of
26286 a selected entry. If the same resource options are used in this
26287 example, the \gls{mainglossary} will be empty, which means that the
26288 nested glossaries won't be displayed either.
26289
26290 One way to ensure that the \code{animal}, \code{mineral} and
26291 \code{vegetable} entries are selected is to identify the \field{type}
26292 field as a dependency field:
26293 \begin{codeenv}
26294 \gls{GlsXtrLoadResources}\oarg{\csopt[{terms,animals,minerals,vegetables}]{src},
26295 \csopt[{identifier=type}]{field-aliases},
26296 \csopt[{type}]{dependency-fields}
26297 }
26298 \end{codeenv}
26299 This will achieve the same effect as the
26300 \exfile{sample-hierarchical.tex} document, but it's a far more
26301 convoluted method. The reason this example document is listed here
26302 is to demonstrate a sightly modified \hierarchical\ effect that can't
26303 be achieved through the normal method.
26304
26305 Suppose that, for some strange reason, I want the \qt{animal},
26306 \qt{mineral} and \qt{vegetable} entries to be listed in a different
26307 order (say, reverse alphabetical). The other entries (\qt{duck} etc)
26308 need to be sorted in normal alphabetical order.
26309
26310 The \csopt{sort} option applies the same sort method to all
26311 \hierarchical\ levels. The sort \emph{value} chosen for particular entries
26312 can be altered through the use of fallbacks (such as the
26313 \csopt{entry-sort-fallback} or \csopt{symbol-sort-fallback} options)
26314 and a letter comparator may be used to resolve identical sort
26315 values (\csopt{identical-sort-action}), but the same sort algorithm
26316 is applied to all entries in the same set (primary, secondary or dual
26317 within the same resource set). The only way to apply different sort
26318 methods is to separate the entries into different resource sets (or
26319 use dual or secondary sorting).
26320
26321 This can be achieved by having one resource set for the \glspl{mainentry}
26322 with one sort method and another resource set for all the other
26323 entries with a different sort method:
26324 \begin{codeenv}
26325 \gls{GlsXtrLoadResources}\oarg{\csopt[terms]{src},\csopt[en-reverse]{sort}}
26326
26327 \gls{GlsXtrLoadResources}\oarg{\csopt[animals,minerals,vegetables]{src},\csopt[en]{sort},
26328 \csopt[{identifier=type}]{field-aliases},\csopt[{type}]{dependency-fields}
26329 }
26330 \end{codeenv}
26331 This works when cross-resource dependencies are permitted (see
26332 \sectionref{sec:resourcesets}). In the event that cross-resource
26333 dependencies aren't permitted, the selection criteria is more
26334 complicated:
26335 \begin{codeenv}
26336 \gls{GlsXtrLoadResources}\oarg{\csopt[terms,animals,minerals,vegetables]{src},
26337 \csopt[en-reverse]{sort},
26338 \csopt[{identifier=parent}]{field-aliases},
26339 \csopt[ancestors but not recorded]{selection}
26340 }
26341
26342 \gls{GlsXtrLoadResources}\oarg{
26343 \csopt[animals,minerals,vegetables]{src},
26344 \csopt[{identifier=type}]{field-aliases},
26345 \csopt[{type}]{dependency-fields}
26346 \csopt[en]{sort}
26347 }
26348 \end{codeenv}
26349 Fortunately in this example, cross-resource dependencies are
26350 permitted so the simpler alternative works. (If they're not
26351 permitted, the \bibgls\ transcript file will contain
26352 \qt{Cross-resource references can't be supported for resource set
26353 \meta{filename}}.)
26354
26355 The complete code is listed below. The document build is:
26356 \begin{verbatim}
26357 pdflatex sample-nested
26358 bib2gls --group --provide-glossaries sample-nested
26359 pdflatex sample-nested
26360 \end{verbatim}
26361 The complete document is shown in \figureref{fig:sample-nested.pdf}.
26362
26363 \lstinputlisting[firstline=5]{../examples/sample-nested.tex}
26364
26365 \begin{figure}
26366 \figcontents
26367 {%
26368 \frame{\includegraphics[height=.9\textheight]{../examples/sample-nested.pdf}}%
26369 }
26370 {\caption{\filefmt{sample-nested.pdf}}}
26371 {fig:sample-nested.pdf}
26372 \end{figure}
26373
26374 \filesection{sample-constants.tex}
26375
26376 This example uses the \exfile{constants.bib} file. The aim here
26377 is to just have a list of all the constants defined in the \ext{bib}
26378 file. (There are no references in the document.) This means I need
26379 to use:
26380 \begin{codeenv}
26381 \csopt[all]{selection}
26382 \end{codeenv}
26383 in order to select all entries. I also need to alias the custom
26384 \atentryfmt{constant} \gls{entrytype} otherwise all the entries will be
26385 ignored. I decided to make \atentryfmt{constant} behave like
26386 \atentry{number} for semantic reasons:
26387 \begin{codeenv}
26388 \csopt[constant=number]{entry-type-aliases}
26389 \end{codeenv}
26390 The custom fields also need aliasing:
26391 \begin{codeenv}
26392 \csopt[
26393 \fieldfmt{identifier}=\field{category},
26394 \fieldfmt{constantsymbol}=\field{name},
26395 \fieldfmt{constantname}=\field{description},
26396 \fieldfmt{value}=\field{user1},
26397 \fieldfmt{definition}=\field{user2},
26398 \fieldfmt{alternative}=\field{user3},
26399 ]{field-aliases}
26400 \end{codeenv}
26401 I decided to use the \glostyle{altlist} style, so I've instructed
26402 \bibgls\ to determine the widest name:
26403 \begin{codeenv}
26404 \csopt{set-widest}
26405 \end{codeenv}
26406 It's always a good idea to specify the glossary type when using
26407 \csopt{set-widest}, although in this example there's only one
26408 glossary so it doesn't make much difference.
26409 \begin{codeenv}
26410 \csopt[main]{type}
26411 \end{codeenv}
26412 I decided to order the constants according to their (approximate)
26413 numerical value. I've aliased the custom \fieldfmt{value} field to
26414 \field{user1}, so I can sort by that field using a numerical
26415 comparison:
26416 \begin{codeenv}
26417 \csopt[\field{user1}]{sort-field},
26418 \csopt[double]{sort}
26419 \end{codeenv}
26420 There are three entries without the \fieldfmt{user1} field (as the
26421 custom \fieldfmt{value} field is missing in the \ext{bib} file):
26422 \code{zero}, \code{one} and \code{imaginary}. In the case of
26423 \code{zero} and \code{one} the exact value can be obtained from the
26424 \field{name} field. Since I've change the default \csopt{sort-field}, I
26425 can't use \csopt{symbol-sort-fallback}. Instead I need to use:
26426 \begin{codeenv}
26427 \csopt[\field{name}]{missing-sort-fallback}
26428 \end{codeenv}
26429
26430 What happens with the \code{imaginary} entry? It has no real
26431 representation. The transcript (\ext{glg}) file shows the message:
26432 \begin{verbatim}
26433 Warning: Can't parse sort value 'i' for: imaginary
26434 \end{verbatim}
26435 With the numerical sort methods, if the field can't be parsed the
26436 value defaults to 0. This means that both \code{zero} and
26437 \code{imaginary} have 0 as the sort value, so the
26438 \csopt{identical-sort-action} is implemented. The default setting
26439 means that \bibgls\ will fallback on comparing the entry labels, so
26440 \code{imaginary} comes before \code{zero}.
26441
26442 Since I'm just using the \glostyle{alttree} style, I only need
26443 \sty{glossary-tree}. I can improve efficiency in the document build
26444 by preventing the other glossary style packages from being loaded
26445 using the \styopt{nostyles} package option. This also prevents
26446 \sty{glossary-tree} from being loaded, but I can both load it and
26447 patch the styles with \sty{glossaries-extra-stylemods} through the
26448 option \styopt[tree]{stylemods}. Since the default \glostyle{list}
26449 style is no longer available, I need to set a new default with
26450 \styopt[alttree]{style}. I also want to automatically insert a
26451 \idx{full-stop} after the description, which can be done with
26452 \styopt{postdot}. Don't forget that the \styopt{record} option is
26453 always needed when using \bibgls. This means that the
26454 \sty{glossaries-extra} package needs to be loaded as follows:
26455 \begin{codeenv}
26456 \cs{usepackage}\oarg{\styopt{record},\styopt{nostyles},\styopt{postdot},\styopt[tree]{stylemods},\styopt[alttree]{style}}
26457 \marg{glossaries-extra}
26458 \end{codeenv}
26459 I've assigned the custom \fieldfmt{constantname} field to the
26460 \field{description} field and the custom \fieldfmt{constantsymbol} field to the
26461 \field{name} field. This means that by default the glossary list
26462 will just show the symbolic representation and the constant's name.
26463 I'd like to append the value and definition after the description.
26464 With the base \sty{glossaries} package this would require defining a
26465 new glossary style but with \sty{glossaries-extra} it can easily be
26466 achieved through the \idx{postdescriptionhook}.
26467
26468 I've aliased the custom \fieldfmt{identifier} field to
26469 \field{category}, which means that all the entries will have the
26470 \field{category} set to \code{constant}. The
26471 \idx{postdescriptionhook} is obtained from
26472 \idx{glsxtrpostdesccategory}, so I need to define
26473 the command \csfmt{glsxtrpostdescconstant}. A simple definition is:
26474 \begin{codeenv}
26475 \cs{newcommand}\marg{\cmd{glsxtrpostdescconstant}}\marg{\comment{}
26476 \cs{space} (approximately \cs{glsentryuseri}\marg{\cs{glscurrententrylabel}})\comment{}
26477 : \cs{glsentryuserii}\marg{\cs{glscurrententrylabel}}\comment{}
26478 }
26479 \end{codeenv}
26480 This is fine if all entries have the \field{user1} and \field{user2}
26481 fields set. A more generic approach tests for the existence of these
26482 fields. This can either be done with \ics{ifglshasfield}:
26483 \begin{codeenv}
26484 \cs{newcommand}\marg{\cmd{glsxtrpostdescconstant}}\marg{\comment{}
26485 \cs{ifglshasfield}\marg{\field{user1}}\marg{\cs{glscurrententrylabel}}\comment{}
26486 \marg{ (approximately \cs{glscurrentfieldvalue})}\comment{}
26487 \marg{}\comment{}
26488 \cs{ifglshasfield}\marg{\field{user2}}\marg{\cs{glscurrententrylabel}}\comment{}
26489 \marg{: \cs{glscurrentfieldvalue}}\comment{}
26490 \marg{}\comment{}
26491 }
26492 \end{codeenv}
26493 or with \ics{glsxtrifhasfield}:
26494 \begin{codeenv}
26495 \cs{newcommand}\marg{\cmd{glsxtrpostdescconstant}}{\comment{}
26496 \cs{glsxtrifhasfield}\marg{\field{useri}}\marg{\cs{glscurrententrylabel}}\comment{}
26497 \marg{ (approximately \cs{glscurrentfieldvalue})}\comment{}
26498 \marg{}\comment{}
26499 \cs{glsxtrifhasfield}\marg{\field{userii}}\marg{\cs{glscurrententrylabel}}\comment{}
26500 \marg{: \cs{glscurrentfieldvalue}}\comment{}
26501 \marg{}\comment{}
26502 }
26503 \end{codeenv}
26504 (Note the need to use the internal field label \field{useri} and
26505 \field{userii} with \ics{glsxtrifhasfield}.)
26506
26507 A modification can be made to also show the alternative
26508 representation (obtained from the custom \fieldfmt{alternative}
26509 field which has been aliased to \field{user3}):
26510 \begin{codeenv}
26511 \cs{newcommand}\marg{\cmd{glsxtrpostdescconstant}}{\comment{}
26512 \cs{glsxtrifhasfield}\marg{\field{useriii}}\marg{\cs{glscurrententrylabel}}\comment{}
26513 \marg{ (also denoted \cs{glscurrentfieldvalue}
26514 \cs{glsxtrifhasfield}\marg{\field{useri}}\marg{\cs{glscurrententrylabel}}\comment{}
26515 \marg{, approximately \cs{glscurrentfieldvalue}}\comment{}
26516 \marg{}\comment{}
26517 )\comment{}
26518 }\comment{}
26519 \marg{\comment{}
26520 \cs{glsxtrifhasfield}\marg{\field{useri}}\marg{\cs{glscurrententrylabel}}\comment{}
26521 \marg{ (approximately \cs{glscurrentfieldvalue})}\comment{}
26522 \marg{}\comment{}
26523 }\comment{}
26524 \cs{glsxtrifhasfield}\marg{\field{userii}}\marg{\cs{glscurrententrylabel}}\comment{}
26525 \marg{: \cs{glscurrentfieldvalue}}\comment{}
26526 \marg{}\comment{}
26527 }
26528 \end{codeenv}
26529 If you have at least \styfmt{glossaries-extra} v1.31, it's better to use:
26530 \begin{codeenv}
26531 \ics{glsdefpostdesc}\marg{constant}
26532 \end{codeenv}
26533 instead of:
26534 \begin{codeenv}
26535 \cs{newcommand}\marg{\cmd{glsxtrpostdescconstant}}
26536 \end{codeenv}
26537 as it can guard against accidental misspelling of the \code{glsxtrpostdesc}
26538 part of the command name.
26539
26540 The complete code is listed below. The document build is:
26541 \begin{verbatim}
26542 pdflatex sample-constants
26543 bib2gls sample-constants
26544 pdflatex sample-constants
26545 \end{verbatim}
26546 The complete document is shown in \figureref{fig:sample-constants.pdf}.
26547
26548 \lstinputlisting[firstline=5]{../examples/sample-constants.tex}
26549
26550 \begin{figure}
26551 \figcontents
26552 {%
26553 \frame{\includegraphics[height=.9\textheight]{../examples/sample-constants.pdf}}%
26554 }
26555 {\caption{\filefmt{sample-constants.pdf}}}
26556 {fig:sample-constants.pdf}
26557 \end{figure}
26558
26559 \filesection{sample-chemical.tex}
26560
26561 This example just uses the \exfile{chemicalformula.bib} file. The aim here
26562 is to have a list of chemical formulae referenced in the document
26563 but not have a number list. I could use the \styopt{nonumberlist}
26564 package option to suppress the number list display, but it's more
26565 efficient to instruct \bibgls\ to not save the number list with:
26566 \begin{codeenv}
26567 \csopt[false]{save-locations}
26568 \end{codeenv}
26569 All entries are defined in \exfile{chemicalformula.bib} using
26570 a custom \gls{entrytype} \atentryfmt{chemical} which needs to be aliased
26571 in order for the entries to be recognised:
26572 \begin{codeenv}
26573 \csopt[chemical=symbol]{entry-type-aliases}
26574 \end{codeenv}
26575 Additionally, the entries only have custom fields, so these also
26576 need to be aliased. In this case I want the formula in the \field{name} field
26577 and the chemical name in the \field{description} field:
26578 \begin{codeenv}
26579 \csopt[\fieldfmt{formula}=\field{name},\fieldfmt{chemicalname}=\field{description}]{field-aliases}
26580 \end{codeenv}
26581 The \atentry{symbol} \gls{entrytype} falls back on the label for the
26582 \field{sort} value by default, but I've decided
26583 to fallback on the \field{name} field for sorting:
26584 \begin{codeenv}
26585 \csopt[\field{name}]{symbol-sort-fallback}
26586 \end{codeenv}
26587 An alternative approach would simply be to alias
26588 \atentryfmt{chemical} to \atentry{entry} instead.
26589
26590 Since the \field{name} field contains chemical formulae rather than
26591 words, it makes more sense to use one of the letter sort methods
26592 rather than a locale collator. In this case the names contain
26593 mixtures of letters and numbers, so one of the letter-number sort
26594 methods (listed in \tableref{tab:sortoptionsletternumber}) would be
26595 appropriate.
26596
26597 I want to use the \glostyle{alttreegroup} style (provided by
26598 \sty{glossary-tree}). Since I don't require the other style
26599 packages, I've used \styopt{nostyles} to suppress the automatic
26600 loading and \styopt[tree]{stylemods} to both load
26601 \sty{glossary-tree} and patch it. The \glostyle{alttreegroup} style
26602 needs to know the widest name, so I've use \csopt{set-widest} for
26603 convenience. The default behaviour of the tree styles is to
26604 format the name in bold. This is done through the command
26605 \ics{glstreenamefmt} which is defined as:
26606 \begin{codeenv}
26607 \cs{newcommand}*\marg{\cs{glstreenamefmt}}[1]\marg{\cs{textbf}\marg{\idx{param}1}}
26608 \end{codeenv}
26609 The group headings use \ics{glstreegroupheaderfmt} which defaults to
26610 \cs{glstreenamefmt}. Since I want to keep bold headings, I need to
26611 redefine this as well:
26612 \begin{codeenv}
26613 \cs{renewcommand}*\marg{\cs{glstreenamefmt}}[1]\marg{\idx{param}1}
26614 \cs{renewcommand}*\marg{\cs{glstreegroupheaderfmt}}[1]\marg{\cs{textbf}\marg{\idx{param}1}}
26615 \end{codeenv}
26616 (For a more compact layout, you could use \glostyle{mcolalttreegroup}
26617 instead.)
26618 I also need the \longarg{group} switch to make the sort method
26619 automatically assign letter groups.
26620
26621 The complete code is listed below. The document build is:
26622 \begin{verbatim}
26623 pdflatex sample-chemical
26624 bib2gls --group sample-chemical
26625 pdflatex sample-chemical
26626 \end{verbatim}
26627 The complete document is shown in \figureref{fig:sample-chemical.pdf}.
26628
26629 \lstinputlisting[firstline=5]{../examples/sample-chemical.tex}
26630
26631 \begin{figure}
26632 \figcontents
26633 {%
26634 \frame{\includegraphics[height=.9\textheight]{../examples/sample-chemical.pdf}}%
26635 }
26636 {\caption{\filefmt{sample-chemical.pdf}}}
26637 {fig:sample-chemical.pdf}
26638 \end{figure}
26639
26640 \filesection{sample-bacteria.tex}
26641
26642 This example just uses the \exfile{bacteria.bib} file. The aim here
26643 is to have a simple list of the bacteria referenced in the document.
26644 Bacteria names are often shown in the long form on first use
26645 (without the short form) and then the short form on subsequent use.
26646 This can easily be done with the \abbrstyle{long-only-short-only}
26647 style. Bacteria are usually typeset in italic. It's best to create a
26648 semantic command for this:
26649 \begin{codeenv}
26650 \cs{newcommand}\marg{\cmd{bacteriafont}}[1]\marg{\cs{emph}\marg{\idx{param}1}}
26651 \end{codeenv}
26652 There are two methods to apply this to the bacteria entries. The
26653 first is to redefine the formatting commands used by the
26654 \abbrstyle{long-only-short-only} style:
26655 \begin{codeenv}
26656 \cs{renewcommand}*\marg{\ics{glsabbrvonlyfont}}[1]\marg{\cmd{bacteriafont}\marg{\idx{param}1}}
26657 \cs{renewcommand}*\marg{\ics{glslongonlyfont}}[1]\marg{\cmd{bacteriafont}\marg{\idx{param}1}}
26658 \end{codeenv}
26659 This is fine if I don't intend to use this style for other types of
26660 abbreviations. However, I may decide to extend the document at a
26661 later date to include other abbreviations that need
26662 \abbrstyle{long-only-short-only} but shouldn't be emphasized.
26663 This can be done through the use of \idxpl{categoryattribute}.
26664 The font used for the \field{name} in the glossary is governed by
26665 the \catattr{glossnamefont} attribute, the font used for the
26666 \field{description} in the glossary is governed by the
26667 \catattr{glossdescfont} attribute and the font used by commands like
26668 \cs{gls} in the document is governed by the \catattr{textformat}
26669 attribute (\styfmt{glossaries-extra} v1.21+). So if I set
26670 the \field{category} to \code{bacteria} then I can do:
26671 \begin{codeenv}
26672 \cs{setabbreviationstyle}\oarg{bacteria}\marg{\abbrstyle{long-only-short-only}}
26673 \cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{textformat}}\marg{bacteriafont}
26674 \cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{glossnamefont}}\marg{bacteriafont}
26675 \end{codeenv}
26676 and (if the \field{description} field is displayed in the glossary):
26677 \begin{codeenv}
26678 \cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{glossdescfont}}\marg{bacteriafont}
26679 \end{codeenv}
26680 (Note that the attribute value is the control sequence name without
26681 the initial backslash.)
26682
26683 I'd like to use the \glostyle{bookindex} style, which is
26684 provided by the \isty{glossary-bookindex}
26685 package.\footnote{\styfmt{glossary-bookindex}
26686 is distributed with \styfmt{glossaries-extra} v1.21+.} This isn't loaded
26687 automatically, but it can be loaded through the
26688 \styopt{stylemods} package option:
26689 \begin{codeenv}
26690 \cmd{usepackage}[\styopt{record},\comment{use bib2gls}
26691 \styopt{nostyles},\comment{don't load default style packages}
26692 \styopt[bookindex]{stylemods},\comment{load glossary-bookindex.sty and patch styles}
26693 \styopt[bookindex]{style}]\marg{glossaries-extra}
26694 \end{codeenv}
26695 I've used the \styopt{nostyles} package option to suppress loading
26696 the default style packages, since I'm not using them. If you inspect
26697 the \ext{log} file, you may notice that \sty{glossary-tree} is still
26698 loaded. This is because it's required by \sty{glossary-bookindex}
26699 as the \glostyle{bookindex} style is based on the \glostyle{index}
26700 style provided by \sty{glossary-tree}.
26701 With this style I need to use the \longarg{group} switch to instruct
26702 the sort method to automatically create the letter groups.
26703
26704 The \glostyle{bookindex} style doesn't show the \field{description}
26705 field (which means I don't need the \catattr{glossdescfont}
26706 attribute) and, since the \abbrstyle{long-only-short-only} style sets
26707 the \field{name} to the short form by default, only the short form
26708 will show in the glossary. I'd rather it was just the long form.
26709 This could simply be done using \csopt{replicate-fields} to copy the
26710 \field{long} field to the \field{name} field:
26711 \begin{codeenv}
26712 \csopt[\field{long}=\field{name}]{replicate-fields}
26713 \end{codeenv}
26714 Again, I want to consider the possibility of adding other types of
26715 abbreviations and this might not be appropriate for them (for
26716 example, I might want some abbreviations with the long form followed
26717 by the short form in parentheses). Another
26718 approach is to redefine \ics{glsxtrbookindexname} which is used by
26719 the \glostyle{bookindex} style to display the name. This takes the
26720 entry's label as the argument. The default definition is:
26721 \begin{codeenv}
26722 \cs{newcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\cs{glossentryname}\marg{\idx{param}1}}
26723 \end{codeenv}
26724 This can be changed to test for the entry's category:
26725 \begin{codeenv}
26726 \cs{renewcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\comment{}
26727 \ics{glsifcategory}\marg{\idx{param}1}\marg{bacteria}
26728 \marg{\cs{glossentrynameother}\marg{\idx{param}1}\marg{\field{long}}}\comment{}
26729 \marg{\cs{glossentryname}\marg{\idx{param}1}}\comment{}
26730 }
26731 \end{codeenv}
26732 Note that I've used \ics{glossentrynameother} here rather than
26733 \ics{glsentrylong}. This ensures that it follows the same formatting
26734 as \ics{glossentryname} (so it will use \ics{glsnamefont} or the
26735 \catattr{glossnamefont} attribute, the \catattr{glossname}
26736 attribute, and the \idx{postnamehook}, if set). In this case it
26737 picks up the \catattr{glossnamefont} attribute, which is used
26738 instead of \cs{glsnamefont}.
26739
26740 If the \field{sort} field is missing for abbreviation styles, the
26741 fallback value is the \field{short} field (not the \field{name}
26742 field). In this case it would be better to fallback on the
26743 \field{long} field instead, which can be done with the
26744 \csopt{abbreviation-sort-fallback} option:
26745 \begin{codeenv}
26746 \csopt[\field{long}]{abbreviation-sort-fallback}
26747 \end{codeenv}
26748 If I do add other types of abbreviations, they will all be sorted
26749 according to the \field{long} form, but at least this way I can have
26750 some \meta{long} (\meta{short}) names as well.
26751
26752 The complete code is listed below. The document build is:
26753 \begin{verbatim}
26754 pdflatex sample-bacteria
26755 bib2gls --group sample-bacteria
26756 pdflatex sample-bacteria
26757 \end{verbatim}
26758 This simple example only references entries on the first page so all
26759 entries just have~1 in the number list. The complete document is
26760 shown in \figureref{fig:sample-bacteria.pdf}.
26761
26762 \lstinputlisting[firstline=5]{../examples/sample-bacteria.tex}
26763
26764 \begin{figure}
26765 \figcontents
26766 {%
26767 \frame{\includegraphics[height=.9\textheight]{../examples/sample-bacteria.pdf}}%
26768 }
26769 {\caption{\filefmt{sample-bacteria.pdf}}}
26770 {fig:sample-bacteria.pdf}
26771 \end{figure}
26772
26773 \filesection{sample-units1.tex}
26774
26775 This example uses the \exfile{baseunits.bib} and
26776 \exfile{derivedunits.bib} files. The aim here is to have a glossary
26777 in two blocks: base units and derived units. This can be achieved by
26778 first loading \exfile{baseunits.bib} with \csopt{group} set to the
26779 desired group title (\qt{Base Units} in this case) and then load
26780 \exfile{derivedunits.bib} with the \csopt{group} set to the desired
26781 title (\qt{Derived Units} in this case). Remember that the
26782 \field{group} field needs to be used as a label. If the group title
26783 contains any problematic characters or commands, then it's better to
26784 use labels:
26785 \begin{codeenv}
26786 \csopt[baseunits]{group}
26787 \end{codeenv}
26788 for the first \igls{resourceset} and
26789 \begin{codeenv}
26790 \csopt[derivedunits]{group}
26791 \end{codeenv}
26792 for the second, and then set the group titles:
26793 \begin{codeenv}
26794 \gls{glsxtrsetgrouptitle}\marg{baseunits}\marg{Base Units}
26795 \gls{glsxtrsetgrouptitle}\marg{derivedunits}\marg{Derived Units}
26796 \end{codeenv}
26797 I've used this method to make it easier to adapt to other languages
26798 that may need extended characters in the group titles.
26799 The \csopt{group} option requires the \longarg{group} switch to
26800 ensure that the \field{group} field is correctly assigned.
26801
26802 The \exfile{baseunits.bib} file use a custom \gls{entrytype}
26803 \atentryfmt{unit}, which must be aliased otherwise \bibgls\
26804 will ignore the entries. I decided to use \atentry{symbol} for
26805 semantic reasons:
26806 \begin{codeenv}
26807 \csopt[unit=symbol]{entry-type-aliases}
26808 \end{codeenv}
26809 Similarly for the custom \atentryfmt{measurement} \gls{entrytype} in
26810 \exfile{derivedunits.bib}:
26811 \begin{codeenv}
26812 \csopt[measurement=symbol]{entry-type-aliases}
26813 \end{codeenv}
26814 Remember that \atentry{symbol} uses the label as the default sort fallback,
26815 so I've changed it to use \field{name} instead:
26816 \begin{codeenv}
26817 \csopt[\field{name}]{symbol-sort-fallback}
26818 \end{codeenv}
26819 An alternative approach would be to alias \atentryfmt{unit}
26820 and \atentryfmt{measurement} to \atentry{entry} instead.
26821
26822 Since there's no \csopt{type} set, all entries end up in the
26823 \gls{mainglossary}, but since there are two resource commands the glossary
26824 ends up with sorted blocks.
26825
26826 The document doesn't include any commands like \cs{gls}, so
26827 I've use \csopt[all]{selection} to select all entries in the \ext{bib}
26828 files. There won't be any number lists since there are no records.
26829 I need a glossary style that shows the \field{symbol} field so I've
26830 used \glostyle{mcolindexgroup}. Again I've suppressed the automatic
26831 loading of the default styles with \styopt{nostyles} and used
26832 \styopt[mcols]{stylemods} to load \isty{glossary-mcols} and patch the
26833 styles. Note that although I've used \styopt{nostyles}, the
26834 \sty{glossary-tree} style is loaded as it's required by
26835 \sty{glossary-mcols}.
26836
26837 As with the previous example, the custom fields need to be aliased:
26838 \begin{codeenv}
26839 \csopt[
26840 \fieldfmt{unitname}=\field{name},
26841 \fieldfmt{unitsymbol}=\field{symbol},
26842 \fieldfmt{measurement}=\field{description}
26843 ]{field-aliases}
26844 \end{codeenv}
26845
26846 The complete document code is listed below. The document build is:
26847 \begin{verbatim}
26848 pdflatex sample-units1
26849 bib2gls --group sample-units1
26850 pdflatex sample-units1
26851 \end{verbatim}
26852 The complete document is shown in \figureref{fig:sample-units1.pdf}.
26853
26854 \lstinputlisting[firstline=5]{../examples/sample-units1.tex}
26855
26856 \begin{figure}
26857 \figcontents
26858 {%
26859 \frame{\includegraphics[height=.9\textheight]{../examples/sample-units1.pdf}}%
26860 }
26861 {\caption{\filefmt{sample-units1.pdf}}}
26862 {fig:sample-units1.pdf}
26863 \end{figure}
26864
26865 \filesection{sample-units2.tex}
26866
26867 This example is provided for comparison with
26868 \exfile{sample-units1.tex}. Instead of having a single glossary with
26869 sorted blocks this example has two glossaries:
26870 \begin{codeenv}
26871 \ics{newglossary*}\marg{baseunits}\marg{Base Units}
26872 \cs{newglossary*}\marg{derivedunits}\marg{Derived Units}
26873 \end{codeenv}
26874 I've used the \styopt{section} package option to use \ics{section*} for the
26875 glossary titles. This overrides the default \ics{chapter*} which is
26876 used with book or report type of classes. I've also used the
26877 \styopt{nomain} option to suppress the creation of the \gls{mainglossary}
26878 as I want to define my own glossary types instead.
26879
26880 As before the custom \glspl{entrytype} need to be aliased:
26881 \begin{codeenv}
26882 \csopt[unit=symbol]{entry-type-aliases}
26883 \end{codeenv}
26884 for the first \igls{resourceset} and
26885 \begin{codeenv}
26886 \csopt[measurement=symbol]{entry-type-aliases}
26887 \end{codeenv}
26888 for the second. Similarly for the custom entry fields:
26889 \begin{codeenv}
26890 \csopt[
26891 \fieldfmt{unitname}=\field{name},
26892 \fieldfmt{unitsymbol}=\field{symbol},
26893 \fieldfmt{measurement}=\field{description}
26894 ]{field-aliases}
26895 \end{codeenv}
26896 The \longarg{group} switch is needed to ensure that the
26897 \field{group} field is automatically assigned by the sort method.
26898
26899 The complete document code is listed below. The document build is:
26900 \begin{verbatim}
26901 pdflatex sample-units2
26902 bib2gls --group sample-units2
26903 pdflatex sample-units2
26904 \end{verbatim}
26905 The complete document is shown in \figureref{fig:sample-units2.pdf}.
26906
26907 \lstinputlisting[firstline=5]{../examples/sample-units2.tex}
26908
26909 \begin{figure}
26910 \figcontents
26911 {%
26912 \frame{\includegraphics[height=.9\textheight]{../examples/sample-units2.pdf}}%
26913 }
26914 {\caption{\filefmt{sample-units2.pdf}}}
26915 {fig:sample-units2.pdf}
26916 \end{figure}
26917
26918 \filesection{sample-units3.tex}
26919
26920 This is another example that uses the \exfile{baseunits.bib} and
26921 \exfile{derivedunits.bib} files. As before the custom fields need to be aliased:
26922 \begin{codeenv}
26923 \csopt[
26924 \fieldfmt{unitname}=\field{name},
26925 \fieldfmt{unitsymbol}=\field{symbol},
26926 \fieldfmt{measurement}=\field{description}
26927 ]{field-aliases}
26928 \end{codeenv}
26929 This time I want two glossaries containing all the units (base and
26930 derived) where the first glossary is ordered by name and the second
26931 is ordered by symbol. This can be done with a single resource
26932 command that instructs \bibgls\ to make the custom \atentryfmt{unit}
26933 and \atentryfmt{measurement} \glspl{entrytype} behave like
26934 \atentry{dualsymbol}:
26935 \begin{codeenv}
26936 \csopt[
26937 unit=dualsymbol,
26938 measurement=dualsymbol
26939 ]{entry-type-aliases}
26940 \end{codeenv}
26941 This causes the \field{name} and \field{symbol} fields to be swapped in the
26942 dual list. Remember that the fallback for the \field{sort} field is the label
26943 for the symbol \glspl{entrytype} so I need \csopt[\field{name}]{symbol-sort-fallback}
26944 to fallback on \field{name} field instead. (Alternative, I could just sort by
26945 the \field{name} field instead using \csopt[\field{name}]{sort-field}.)
26946
26947 The primary entries can still be sorted according to the default
26948 locale collator, but the dual entries need a sort method that's
26949 better suited to symbols. Fortunately, \bibgls\ has some (very
26950 limited) support for \isty{siunitx} and is able to interpret
26951 the \ics{si} commands in the sample \ext{bib} files. Since
26952 \idxpl{SIunit} are a mix of letters and numbers I've used one of the
26953 letter-number methods listed in
26954 \tableref{tab:sortoptionsletternumber}.
26955
26956 I've decided to define a custom style for the first glossary. Since
26957 it's based on the \glostyle{long3col-booktabs} style I need to
26958 load \isty{glossary-longbooktabs}, which can conveniently be done with
26959 the \styopt{stylemods} option. This uses \env{longtable} (provided
26960 by \isty{longtable}, which is automatically loaded) which means
26961 an extra \LaTeX\ call is required in the build process to ensure the
26962 column widths are correct. Again I'm using \styopt{nostyles} to
26963 suppress the automatic loading of the default styles, however
26964 \sty{glossary-tree} will be loaded as it's listed in the value of
26965 \styopt{stylemods} and \isty{glossary-long} will be loaded as it's
26966 required by \sty{glossary-longbooktabs}. I can't use my custom style
26967 in the \styopt{style} package option as it hasn't been defined at
26968 that point. The default \glostyle{list} style is now unavailable
26969 since \styopt{nostyles} has prevented it from being defined, so
26970 I've used \styopt[alttree]{style} to ensure there's a valid default
26971 style.
26972
26973 Since my custom style is based on one of the long styles, I need to
26974 set the length register \ics{glsdescwidth} to adjust the width of
26975 the description column:
26976 \begin{codeenv}
26977 \cmd{setlength}\marg{\cs{glsdescwidth}}\marg{.4\cmd{hsize}}
26978 \end{codeenv}
26979 The \glostyle{long3col-booktabs} style sets up a three column
26980 \env{longtable} so I just need to adjust the table header (to rename
26981 the column headers) and the way each row is formatted:
26982 \begin{codeenv}
26983 \ics{newglossarystyle}\marg{units}\comment{style name}
26984 \marg{\comment{base it on \glostyle{long3col-booktabs}}
26985 \ics{setglossarystyle}\marg{long3col-booktabs}\comment{}
26986 \cs{renewcommand}*\marg{\ics{glossaryheader}}\marg{\comment{}
26987 \ics{toprule}
26988 \ics{bfseries} Name \idx{colsep}
26989 \cs{bfseries} Measurement \idx{colsep}
26990 \cs{bfseries} Symbol
26991 \ics{tabularnewline}\ics{midrule}\ics{endhead}
26992 \ics{bottomrule}\ics{endfoot}}\comment{}
26993 \comment{main entries:}
26994 \cs{renewcommand}\marg{\ics{glossentry}}[2]\marg{\comment{}
26995 \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}
26996 \cs{glossentrydesc}\marg{\idx{param}\idx{param}1}\ics{glspostdescription} \idx{colsep}
26997 \cs{glossentrysymbol}\marg{\idx{param}\idx{param}1}\cs{tabularnewline}
26998 }\comment{}
26999 }
27000 \end{codeenv}
27001 There are no \glspl{sub-entry} in this document so I haven't bothered to
27002 redefine \ics{subglossentry}. (The tabular styles aren't appropriate
27003 for \glspl{hierarchicalglossary}.) This puts the symbol into the third
27004 column (rather than the \gls{locationlist}, which is ignored).
27005 This style supports the letter group separator (although it doesn't
27006 title the groups), so if I want this I need to use the
27007 \longarg{group} switch.
27008
27009 I also need to make sure I've defined a glossary for the dual
27010 entries:
27011 \begin{codeenv}
27012 \cs{newglossary*}\marg{units}\marg{Units of Measurement (by SI unit)}
27013 \end{codeenv}
27014 and specify the glossary types for the primary and dual entries:
27015 \begin{codeenv}
27016 \csopt[main]{type},
27017 \csopt[units]{dual-type}
27018 \end{codeenv}
27019 The complete document code is listed below. The document build is:
27020 \begin{verbatim}
27021 pdflatex sample-units3
27022 bib2gls --group sample-units3
27023 pdflatex sample-units3
27024 pdflatex sample-units3
27025 \end{verbatim}
27026 The two pages of the document are shown in
27027 \figureref{fig:sample-units3.pdf}.
27028
27029 \lstinputlisting[firstline=5]{../examples/sample-units3.tex}
27030
27031 \begin{figure}
27032 \figcontents
27033 {\pdftwocol{../examples/sample-units3.pdf}{2}}
27034 {\caption{\filefmt{sample-units3.pdf}}}
27035 {fig:sample-units3.pdf}
27036 \end{figure}
27037
27038 \filesection{sample-media.tex}
27039
27040 This example uses the sample files \exfile{books.bib},
27041 \exfile{films.bib}, \exfile{no-interpret-preamble.bib} and
27042 \exfile{interpret-preamble.bib}. The aim is to produce a combined
27043 list of books and films in a single glossary. The films are based on
27044 some of the books so some of the entries have the same name. The
27045 default setting for identical sort values is
27046 \csopt[id]{identical-sort-action}, which means that the ordering for
27047 the duplicate names is based on the entry labels. This can lead to
27048 the odd effect of sometimes having the film listed first
27049 (\code{film.thebigsleep} comes before \code{thebigsleep}) and
27050 sometimes having the book listed first (\code{brightonrock} comes
27051 before \code{film.brightonrock}).
27052
27053 One possible solution would be to also assign prefixes for the book
27054 labels, but \csopt{label-prefix} is applied to all primary entries
27055 for the given resource set and can't be applied selectively, so this
27056 would require editing the \exfile{books.bib} file.
27057
27058 A more consistent approach would be to fallback on the category.
27059 This means that the \field{category} field needs to be set. There
27060 are two simple ways to achieve this: use \csopt[same as base]{category}
27061 (which sets the \field{category} to \code{books} for entries in
27062 \exfile{books.bib} and to \code{films} for entries in
27063 \exfile{films.bib}) or alias the custom \fieldfmt{identifier} field to
27064 \field{category}. I've chosen the latter method and also provided
27065 aliases for the custom \fieldfmt{year} and \fieldfmt{cast} fields:
27066 \begin{codeenv}
27067 \csopt[\fieldfmt{identifier}=\field{category},\fieldfmt{year}=\field{user1},\fieldfmt{cast}=\field{user2}]{field-aliases},
27068 \csopt[\field{category}]{identical-sort-action}
27069 \end{codeenv}
27070 This ensures that books always come before films with the same
27071 title. An oddity is the film \qt{Whisky Galore!}\ which is one
27072 character different from the book \qt{Whisky Galore} but the default
27073 locale collator ignores punctuation so the two titles are considered
27074 identical by the collator (but not by \csopt[non-unique]{sort-suffix}).
27075 If a letter comparison was used instead, they would no longer be
27076 considered identical, but in this case the film would
27077 still be placed after the book since the film title is longer.
27078
27079 Since I've set the \field{category} I can provide semantic
27080 formatting commands (as for \exfile{sample-bacteria.tex}):
27081 \begin{codeenv}
27082 \cs{newcommand}*\marg{\cmd{bookfont}}[1]\marg{\cs{emph}\marg{\idx{param}1}}
27083 \cs{newcommand}*\marg{\cmd{filmfont}}[1]\marg{\ics{textsf}\marg{\ics{em} \idx{param}1}}
27084 \cs{glssetcategoryattribute}\marg{book}\marg{\catattr{textformat}}\marg{bookfont}
27085 \cs{glssetcategoryattribute}\marg{book}\marg{\catattr{glossnamefont}}\marg{bookfont}
27086 \cs{glssetcategoryattribute}\marg{film}\marg{\catattr{textformat}}\marg{filmfont}
27087 \cs{glssetcategoryattribute}\marg{film}\marg{\catattr{glossnamefont}}\marg{filmfont}
27088 \end{codeenv}
27089 I've given films a slightly different format to make them easier to
27090 distinguish from books of the same name.
27091
27092 Both \exfile{books.bib} and \exfile{films.bib} had the custom
27093 \fieldfmt{year} field, indicating the year of first publication
27094 or release, which I've assigned to the \field{user1} field.
27095 I can define \idxpl{postnamehook} for each category
27096 to append the year in brackets after the name is displayed in the
27097 glossary:
27098 \begin{codeenv}
27099 \cs{newcommand}*\marg{\postnamehook{book}}\marg{\comment{}
27100 \cs{ifglshasfield}\marg{\field{user1}}\marg{\cs{glscurrententrylabel}}\comment{}
27101 \marg{\cs{space}(published \cs{glscurrentfieldvalue})}\comment{}
27102 \marg{}\comment{}
27103 }
27104 \strut
27105 \cs{newcommand}*\marg{\postnamehook{film}}\marg{\comment{}
27106 \cs{ifglshasfield}\marg{\field{user1}}\marg{\cs{glscurrententrylabel}}\comment{}
27107 \marg{\cs{space}(released \cs{glscurrentfieldvalue})}\comment{}
27108 \marg{}\comment{}
27109 }
27110 \end{codeenv}
27111 As with the post-description hook, if you have at least
27112 \styfmt{glossaries-extra} v1.31, it's better to use:
27113 \begin{codeenv}
27114 \ics{glsdefpostname}\margm{category}
27115 \end{codeenv}
27116 instead of:
27117 \begin{codeenv}
27118 \cs{newcommand}\marg{\cs{glsxtrpostnamecategory}}
27119 \end{codeenv}
27120 as it can guard against accidental misspelling of the \code{glsxtrpostname}
27121 part of the command name.
27122
27123 I've assigned the \fieldfmt{cast} field to the \field{user2} field,
27124 and since this field uses \BibTeX's contributor markup I need to
27125 convert this to a form that's easier to customize:
27126 \begin{codeenv}
27127 \csopt[\field{user2}]{bibtex-contributor-fields}
27128 \end{codeenv}
27129 I'm not sorting by this field and it would look better in the
27130 document to list the forenames before the surname so I've also done:
27131 \begin{codeenv}
27132 \csopt[forenames]{contributor-order}
27133 \end{codeenv}
27134 Since I have at least version 2.28 of \sty{datatool-base} installed,
27135 the list will be formatted using \ics{DTLformatlist}. If I want an
27136 Oxford comma, I need to redefine \ics{DTLlistformatoxford} in the document:
27137 \begin{codeenv}
27138 \cs{renewcommand}*\marg{\cs{DTLlistformatoxford}}\marg{,}
27139 \end{codeenv}
27140 If I want to change \qt{\&} to \qt{and} I also need to redefine
27141 \ics{DTLandname}:
27142 \begin{codeenv}
27143 \cs{renewcommand}*\marg{\cs{DTLandname}}\marg{and}
27144 \end{codeenv}
27145 If \ics{DTLformatlist} isn't defined (\sty{datatool-base} v2.27 or
27146 earlier), the cast list will look a little odd as it uses a comma
27147 separator between all elements of this list, including the final
27148 pair (so there's no final \& or \qt{and}).
27149
27150 I've provided a \idx{postdescriptionhook}
27151 \ics{glsxtrpostdesccategory} to append the cast list:
27152 \begin{codeenv}
27153 \cs{newcommand}*\marg{\postdeschook{film}}\marg{\comment{}
27154 \cs{ifglshasfield}\marg{\field{user2}}\marg{\cs{glscurrententrylabel}}\comment{}
27155 \marg{\comment{}
27156 \cs{glsxtrrestorepostpunc} \comment{requires glossaries-extra v1.23+}
27157 \cs{cs.space}featuring \cs{glscurrentfieldvalue}
27158 }\comment{}
27159 \marg{}\comment{}
27160 }
27161 \end{codeenv}
27162 This uses \ics{glsxtrrestorepostpunc} to restore the
27163 post-description punctuation if it was suppressed with
27164 \ics{glsxtrnopostpunc}. This means that if I decide not to include
27165 the \field{user2} field then the post-description punctuation will
27166 be revert back to being suppressed for entries containing
27167 \cs{glsxtrnopostpunc} in the \field{description} field.
27168
27169 I haven't referenced any of the entries in the main body of the
27170 document, so I've used \csopt[all]{selection} to select all entries.
27171 This means that there are no number lists on the first document
27172 build (\LaTeX+\bibgls+\LaTeX) but the next build would show \glspl{location} for
27173 the books that have been referenced by the film entries. Since this
27174 looks a bit odd, I've added \csopt[false]{save-locations} to
27175 prevent \bibgls\ from saving the \glspl{location}.
27176
27177 I've used a style that shows letter group headings so I need to use
27178 the \longarg{group} switch.
27179 The complete document code is listed below. The document build is:
27180 \begin{verbatim}
27181 pdflatex sample-media
27182 bib2gls --group sample-media
27183 pdflatex sample-media
27184 \end{verbatim}
27185 The four pages of the document are shown in
27186 \figureref{fig:sample-media.pdf}.
27187
27188 \lstinputlisting[firstline=5]{../examples/sample-media.tex}
27189
27190 \begin{figure}
27191 \figcontents
27192 {\pdftwocol{../examples/sample-media.pdf}{4}}
27193 {\caption{\filefmt{sample-media.pdf}}}
27194 {fig:sample-media.pdf}
27195 \end{figure}
27196
27197 \filesection{sample-people.tex}
27198
27199 This example uses the files \exfile{people.bib},
27200 \exfile{no-interpret-preamble.bib} and \exfile{interpret-preamble.bib}. The
27201 aim here is to have a list of people ordered alphabetically by
27202 surname with a brief description, the same list ordered by date of
27203 birth and an index of all the people without their details but with
27204 a number list indicating where that person was mentioned in the
27205 document. The first two lists shouldn't include aliases but the
27206 index should. Not all the entries defined in \exfile{people.bib}
27207 are included in the document. Those that aren't either explicitly
27208 referenced or aliased are filtered by the \csopt{selection} criteria.
27209 I've used a style that shows letter group headings so I need to use
27210 the \longarg{group} switch.
27211
27212 Since this is just an example document all the \cs{gls} commands
27213 only occur on page~1, which means that each number list is just
27214 \qt{1}. A real document would have the references scattered about.
27215 The aliases haven't actually been referenced anywhere in the
27216 document.
27217
27218 The \fieldfmt{born}, \fieldfmt{died} and \fieldfmt{othername} fields will be
27219 ignored by default since they don't correspond to recognised keys,
27220 so the keys either need to be defined or the fields need to be
27221 mapped to existing keys. In this case I've decided to map them to
27222 the \field{user1}, \field{user2} and \field{user3} fields using
27223 \csopt{field-aliases}:
27224 \begin{codeenv}
27225 \csopt[\fieldfmt{born}=\field{user1},\fieldfmt{died}=\field{user2},\fieldfmt{othername}=\field{user3}]{field-aliases}
27226 \end{codeenv}
27227 Although the aliases haven't been referenced in the document, I've
27228 taken into account the possibility that they might later be added.
27229 To prevent them from showing in the first two lists I've filtered
27230 them out. This is easy to do since the aliases are all defined using
27231 \atentry{index} whereas the remaining (non-aliased) entries are
27232 defined using \atentry{entry} so \csopt{match} can be used to only
27233 select entries defined with \atentry{entry}:
27234 \begin{codeenv}
27235 \csopt[entrytype=entry]{match}
27236 \end{codeenv}
27237
27238 I'd like the first use of \ics{gls} to display the full name, except
27239 for the entry that has the \field{first} field set. The remaining
27240 entries only have \field{text} set to a shortened version of the
27241 name so they need to have the \field{name} field copied to the
27242 \field{first} field using \csopt{replicate-fields}:
27243 \begin{codeenv}
27244 \csopt[\field{name}=\marg{\field{first}}]{replicate-fields}
27245 \end{codeenv}
27246
27247 I'd like the first use to show the other name in parentheses where
27248 provided. The simplest way to achieve this is by defining the
27249 \idx{postlinkhook} \ics{glsxtrpostlinkcategory}. If the
27250 \field{category} field isn't specified it will default to
27251 \code{general} (for entries defined with \atentry{entry}), so I
27252 could just define \csfmt{glsxtrpostlinkgeneral} but to allow for
27253 the possibility of extending the document to incorporate other types
27254 of entries I decided to set the \field{category} to \code{people}
27255 through the use of the \csopt{category} option:
27256 \begin{codeenv}
27257 \csopt[people]{category}
27258 \end{codeenv}
27259
27260 This means that I now need to define a command called
27261 \csfmt{glsxtrpostlinkpeople} that will be used after instances of
27262 \cs{gls} etc where the entry has the \field{category} set to
27263 \code{people}. This first tests if that was the first use of the
27264 entry with \ics{glsxtrifwasfirstuse} and then tests if the
27265 \field{user3} field is set. If so, it does a space followed by that
27266 field's value in parentheses. The entry's label can be obtained from
27267 \ics{glslabel}:
27268 \begin{codeenv}
27269 \cs{newcommand}*\marg{\postlinkhook{people}}\marg{\comment{}
27270 \cs{glsxtrifwasfirstuse}
27271 \marg{\comment{}
27272 \cs{ifglshasfield}\marg{\field{user3}}\marg{\cs{glslabel}}\comment{}
27273 \marg{\cs{space}(\cs{glscurrentfieldvalue})}\comment{}
27274 \marg{}\comment{}
27275 }\comment{}
27276 \marg{}\comment{}
27277 }
27278 \end{codeenv}
27279
27280 I'd also like to do something similar after the name when the entry
27281 is displayed in the glossary. This means defining the \idx{postnamehook}
27282 \ics{glsxtrpostnamecategory}, in this case
27283 \csfmt{glsxtrpostnamepeople}. The entry's label is referenced
27284 with \ics{glscurrententrylabel}:
27285 \begin{codeenv}
27286 \cs{newcommand}*\marg{\postnamehook{people}}\marg{\comment{}
27287 \cs{ifglshasfield}\marg{\field{user3}}\marg{\cs{glscurrententrylabel}}\comment{}
27288 \marg{\cs{space}(\cs{glscurrentfieldvalue})}\comment{}
27289 \marg{}\comment{}
27290 }
27291 \end{codeenv}
27292 (A different command is used since \cs{gls} may occur in the
27293 description, which would interfere with the current entry label if
27294 they shared the same command to reference the label.)
27295
27296 The \idx{postdescriptionhook} can be used to append the birth and
27297 death dates. Although all the entries that have been selected from \exfile{people.bib} have a
27298 \fieldfmt{died} field, I've added a check for the corresponding
27299 \field{user3} field in case new references are added for people who are
27300 still alive:
27301 \begin{codeenv}
27302 \cs{newcommand}*\marg{\postdeschook{people}}\marg{\comment{}
27303 \cs{ifglshasfield}\marg{\field{user1}}\marg{\cs{glscurrententrylabel}}
27304 \marg{\comment{born}
27305 \cs{space}(\cs{glscurrentfieldvalue}\ics{comma}-{}-\cs{comma}\comment{}
27306 \cs{ifglshasfield}\marg{user2}\marg{\cs{glscurrententrylabel}}
27307 \marg{\comment{died}
27308 \cs{glscurrentfieldvalue}
27309 }\comment{}
27310 \marg{}\comment{}
27311 )\comment{}
27312 }\comment{}
27313 \marg{}\comment{}
27314 }
27315 \end{codeenv}
27316
27317 The first list is quite straight-forward and can be created with:
27318 \begin{codeenv}
27319 \gls!{GlsXtrLoadResources}\oarg{
27320 \csopt[people]{src},
27321 \csopt[entrytype=entry]{match},
27322 \csopt[people]{category},
27323 \csopt[\field{name}=\marg{\field{first}}]{replicate-fields},
27324 \csopt[\fieldfmt{born}=\field{user1},\fieldfmt{died}=\field{user2},\fieldfmt{othername}=\field{user3}]{field-aliases}
27325 }
27326 \end{codeenv}
27327 I have used the \csopt{sort} option and there's no document language,
27328 so \bibgls\ will sort according to my locale. The custom
27329 commands \gls{sortname} and \gls{sortvonname} ensure that the
27330 entries are all sorted alphabetically according to the surnames.
27331
27332 The second list can easily be created by adding the \csopt{secondary}
27333 option:
27334 \begin{codeenv}
27335 \csopt[date:\field{user1}:bybirth]{secondary}
27336 \end{codeenv}
27337 This sorts according to the \field{user1} field (which was
27338 originally the \fieldfmt{birth} field).
27339 Note that different locales have different default date formats.
27340 There may also be a difference in the default date format depending
27341 on the Java \idx{localeprovider}. For example, if you switch from
27342 using the \idx{JRE} to using the \idx{CLDR} you may find a change in
27343 the default format. In case the format provided in the \ext{bib}
27344 file isn't recognised, the required format can be set with:
27345 \begin{codeenv}
27346 \csopt[d MMM YYYY G]{secondary-date-sort-format}
27347 \end{codeenv}
27348
27349 Since the dates contain \glsname{idx.nbspchar}, this will need to be
27350 converted to a space in the sort value for the pattern to match.
27351 This can either be done with the \longarg{break-space} switch or
27352 add to the global \bibgls\ options in the document:
27353 \begin{codeenv}
27354 \gls{BibGlsOptions}\marg{break-space}
27355 \end{codeenv}
27356
27357 I've changed the date group headings by redefining \gls{bibglsdategroup} and
27358 \gls{bibglsdategrouptitle}, which means that the grouping in the
27359 \code{bybirth} glossary will be in the form \meta{year} \meta{era}:
27360 \begin{codeenv}
27361 \cs{newcommand}\marg{\gls{bibglsdategroup}}[7]\marg{\idx{param}1\idx{param}4\idx{param}7}
27362 \cs{newcommand}\marg{\gls{bibglsdategrouptitle}}[7]\marg{\cs{number}\idx{param}1\ \idx{param}4}
27363 \end{codeenv}
27364 I've also defined the \code{bybirth} glossary and supplied a title:
27365 \begin{codeenv}
27366 \cs{newglossary*}\marg{bybirth}\marg{People (Ordered by Birth)}
27367 \end{codeenv}
27368
27369 The first two glossaries have entries with fairly long names (especially those
27370 with the \idx{postnamehook}), so the best style is the
27371 \glostyle{altlistgroup}. The \sty{glossaries-extra-stylemods}
27372 package patches this style to discourage page breaks occurring after
27373 group headings, so I've also used the \styopt{stylemods}
27374 option to automatically load that package. I'd like to use the
27375 \glostyle{bookindex} style for the index, which is provided by
27376 \sty{glossary-bookindex}, so I need:
27377 \begin{codeenv}
27378 \styopt[list,bookindex]{stylemods}
27379 \end{codeenv}
27380 This ensures that \isty{glossary-list} and \sty{glossary-bookindex}
27381 are loaded and patches the list styles.
27382
27383 The first two glossaries would look better with a terminating
27384 \idx{full-stop}, so I've used the \styopt{postdot} package option.
27385 (The \glostyle{bookindex} style doesn't use the \field{description}
27386 field and therefore doesn't use the \idx{postdescriptionhook}.)
27387 The index glossary type can be defined with the \styopt{index}
27388 package option. I've set the default style to \glostyle{altlistgroup}
27389 but this can locally be changed to \glostyle{bookindex} when I
27390 display the index. The \styopt{record} option is needed to use
27391 \bibgls, so the \styfmt{glossaries-extra} package is loaded with:
27392 \begin{codeenv}
27393 \cmd{usepackage}[\styopt{record},\comment{using bib2gls}
27394 \styopt{index},\comment{create index glossary}
27395 \styopt{postdot},\comment{dot after descriptions}
27396 \comment{load glossary-list.sty and glossary-bookindex.sty and patch:}
27397 \styopt[list,bookindex]{stylemods},
27398 \styopt[altlistgroup]{style}]\marg{glossaries-extra}
27399 \end{codeenv}
27400
27401 The index needs to include all the entries that have already been
27402 defined but also needs to include the aliased entries. This means
27403 that existing entries simply need their label copied to the
27404 \code{index} glossary but the other entries need to be defined
27405 so this requires setting the \csopt{action} option:
27406 \begin{codeenv}
27407 \csopt[define or copy]{action}
27408 \end{codeenv}
27409 I would also like to have groups in the index (which the
27410 \glostyle{bookindex} style supports) so I need to specify a field
27411 in which to save the group information using
27412 \csopt{copy-action-group-field}:
27413 \begin{codeenv}
27414 \csopt[indexgroup]{copy-action-group-field}
27415 \end{codeenv}
27416 I need to remember to redefine \ics{glsxtrgroupfield} to this value before
27417 displaying the index:
27418 \begin{codeenv}
27419 \cs{renewcommand}\marg{\cs{glsxtrgroupfield}}\marg{indexgroup}
27420 \end{codeenv}
27421
27422 The aliased entries won't be selected by default since they haven't
27423 been used in the document, so I need to change the selection
27424 criteria with \csopt{selection}:
27425 \begin{codeenv}
27426 \csopt[recorded and deps and see]{selection}
27427 \end{codeenv}
27428
27429 In the index, I'd like the surnames first. This can be done by
27430 redefining the custom commands used in the \field{name} fields.
27431 There's a slight complication here. These commands aren't defined on
27432 the first \LaTeX\ run as their definitions are written to the
27433 \ext{glstex} file by \bibgls, so I can't use \cs{renewcommand} (although
27434 I could use \cs{glsrenewcommand}).
27435 Instead I've provided some custom commands:
27436 \begin{codeenv}
27437 \cs{newcommand}*\marg{\cmd{swaptwo}}[2]\marg{\idx{param}2, \idx{param}1}
27438 \cs{newcommand}*\marg{\cmd{swapthree}}[3]\marg{\idx{param}2 \idx{param}3, \idx{param}1}
27439 \end{codeenv}
27440 Now I just need to make an assignment using \ics{let}:
27441 \begin{codeenv}
27442 \cs{let}\gls{sortname}\cmd{swaptwo}
27443 \cs{let}\gls{sortart}\cmd{swaptwo}
27444 \cs{let}\gls{sortvonname}\cmd{swapthree}
27445 \end{codeenv}
27446 This doesn't perform any check to determine if the commands are
27447 already defined so there won't be a problem on the first run.
27448
27449 The first two glossaries shouldn't have number lists:
27450 \begin{codeenv*}
27451 \cs{printunsrtglossary}\oarg{\printglossopt[People (Alphabetical)]{title},\printglossopt{nonumberlist}}
27452 \cs{printunsrtglossary}\oarg{\printglossopt[bybirth]{type},\printglossopt[false]{target},\printglossopt{nonumberlist}}
27453 \end{codeenv*}
27454 I'd like to use \sty{hyperref} but I have to switch off the
27455 hypertargets for the second glossary otherwise I'll end up with
27456 duplicate targets. This is done with \code{\printglossopt[false]{target}}.
27457 All references using \cs{gls} etc will link to the first glossary.
27458
27459 I could also do this for the index but the cross-references in the
27460 aliased entries will link to the first glossary rather than the
27461 relevant entry in the index. The simplest way to fix this is to
27462 redefine \ics{glolinkprefix} to provide a different target:
27463 \begin{codeenv}
27464 \cs{renewcommand}*\marg{\cs{glolinkprefix}}\marg{idx:}
27465 \end{codeenv}
27466 These redefinitions need to be done before the index. I've decided
27467 to use the starred \ics{printunsrtglossary*} to localise these
27468 changes, although that's not needed for this document since the
27469 index comes right at the end:
27470 \begin{codeenv*}
27471 \cs{printunsrtglossary*}
27472 \oarg{\printglossopt[index]{type},\printglossopt[\glostyle{bookindex}]{style}}
27473 \marg{\comment{}
27474 \cs{let}\gls!{sortname}\cmd{swaptwo}
27475 \cs{let}\gls!{sortart}\cmd{swaptwo}
27476 \cs{let}\gls!{sortvonname}\cmd{swapthree}
27477 \cs{renewcommand}\marg{\cs{glsxtrgroupfield}}\marg{indexgroup}\comment{}
27478 \cs{renewcommand}*\marg{\cs{glolinkprefix}}\marg{idx:}\comment{}
27479 }
27480 \end{codeenv*}
27481 The complete document code is listed below. The document build is:
27482 \begin{verbatim}
27483 pdflatex sample-people
27484 bib2gls --group --break-space sample-people
27485 pdflatex sample-people
27486 \end{verbatim}
27487 The four pages of the document are shown in \figureref{fig:sample-people.pdf}.
27488
27489 \lstinputlisting[firstline=5]{../examples/sample-people.tex}
27490
27491 \begin{figure}
27492 \figcontents
27493 {\pdftwocol{../examples/sample-people.pdf}{4}}
27494 {\caption{\filefmt{sample-people.pdf}}}
27495 {fig:sample-people.pdf}
27496 \end{figure}
27497
27498 \filesection{sample-authors.tex}
27499
27500 This example uses the files \exfile{people.bib},
27501 \exfile{books.bib}, \exfile{no-interpret-preamble.bib} and
27502 \exfile{interpret-preamble2.bib}. The aim is to reference the books
27503 in \exfile{books.bib} and have them listed by author. This means
27504 finding a way of assigning each book entry a \field{parent} field that
27505 contains the label identifying the relevant author in \exfile{people.bib}.
27506 I've used a style that shows letter group headings so I need to use
27507 the \longarg{group} switch.
27508
27509 To recap, each author is defined in \exfile{people.bib} in the form:
27510 \begin{codeenv}
27511 \atentry{entry}\marg{dickens,
27512 \field{name}=\marg{\gls{sortname}\marg{Charles}\marg{Dickens}},
27513 \field{text}=\marg{Dickens},
27514 \field{description}=\marg{English writer and social critic},
27515 \fieldfmt{born}=\marg{7\idx{nbspchar}February 1812 AD},
27516 \fieldfmt{died}=\marg{9\idx{nbspchar}June 1870 AD},
27517 \fieldfmt{identifier}=\marg{person}
27518 }
27519 \end{codeenv}
27520 and each book is defined in \exfile{books.bib} in the form:
27521 \begin{codeenv}
27522 \atentry{entry}\marg{bleakhouse,
27523 \field{name}=\marg{Bleak House},
27524 \field{description}=\marg{novel by Charles Dickens},
27525 \fieldfmt{identifier}=\marg{book},
27526 \fieldfmt{author}=\marg{\gls{sortmediacreator}\marg{Charles}\marg{Dickens}},
27527 \fieldfmt{year}=\marg{1852}
27528 }
27529 \end{codeenv}
27530 There's a field here (the custom \fieldfmt{author} field) that contains
27531 the author's name, and this can be aliased to the \field{parent}
27532 field with \csopt{field-aliases}:
27533 \begin{codeenv}
27534 \csopt[\fieldfmt{author}=\field{parent}]{field-aliases}
27535 \end{codeenv}
27536 but the author's label in the \exfile{people.bib}
27537 file is just the \idx!{lowercase} surname.
27538
27539 Remember from \sectionref{sec:texparserlib} that the interpreter
27540 will be used on the \field{parent} field if the value contains
27541 \idx{escchar} or \idx{bgroupchar} or \idx{egroupchar} and
27542 \csopt[true]{interpret-label-fields}. This means that with this
27543 field alias and the interpreter on, \bibgls\ will attempt to
27544 interpret the field contents. So all that's needed is to ensure that
27545 \bibgls\ is given a definition of \gls{sortmediacreator} that
27546 ignores the first argument and converts the second argument to lower
27547 case. This definition is available in
27548 \exfile{interpret-preamble2.bib} but, since this file uses
27549 \cs{renewcommand} rather than \cs{providecommand},
27550 \csopt[false]{write-preamble} is required to prevent \LaTeX\ from
27551 picking up this definition.
27552
27553 As with the \exfile{sample-people.tex} example, I need to copy
27554 the \field{name} field to the \field{first} field if that field is
27555 missing using \csopt{replicate-fields}:
27556 \begin{codeenv}
27557 \csopt[\field{name}=\marg{\field{first}}]{replicate-fields}
27558 \end{codeenv}
27559 and I also want to provide a semantic command to format the book
27560 title, so the field aliases also need to convert the custom
27561 \fieldfmt{identifier} field to \field{category}:
27562 \begin{codeenv}
27563 \csopt[\fieldfmt{identifier}=\field{category},\fieldfmt{author}=\field{parent}]{field-aliases}
27564 \end{codeenv}
27565 so that the document can set the \catattr{textformat} and
27566 \catattr{glossnamefont} attributes:
27567 \begin{codeenv}
27568 \cs{newcommand}*\marg{\cmd{bookfont}}[1]\marg{\cs{emph}\marg{\idx{param}1}}
27569 \cs{glssetcategoryattribute}\marg{book}\marg{\catattr{textformat}}\marg{bookfont}
27570 \cs{glssetcategoryattribute}\marg{book}\marg{\catattr{glossnamefont}}\marg{bookfont}
27571 \end{codeenv}
27572 As with \exfile{sample-media.tex}, the terminating question mark at
27573 the end of some of the \field{name} fields can cause an awkward
27574 situation if \cs{gls} is used at the end of a sentence. This can be
27575 dealt with by getting \bibgls\ to make a note of the fields that
27576 end with sentence-terminating punctuation through the use of
27577 the \csopt{check-end-punctuation} option. In this example, the
27578 \field{name}, \field{text} and \field{first} fields are the same for
27579 all the books, so it's sufficient just to check the \field{name}
27580 field:
27581 \begin{codeenv}
27582 \csopt[\field{name}]{check-end-punctuation}
27583 \end{codeenv}
27584 With \sty{glossaries-extra} v1.23+ it's easy to hook into the
27585 \idx{postlinkhook} to check if
27586 \fielddisp{fieldendpunc}{nameendpunc} exists:
27587 \begin{codeenv}
27588 \cs{renewcommand}*\marg{\cs{glsxtrifcustomdiscardperiod}}[2]\marg{\comment{}
27589 \cs{GlsXtrIfFieldUndef}\marg{\fielddisp{fieldendpunc}{nameendpunc}}\marg{\cs{glslabel}}\marg{\idx{param}2}\marg{\idx{param}1}\comment{}
27590 }
27591 \end{codeenv}
27592 This will now cause the full stops following:
27593 \begin{codeenv}
27594 \cs{gls}\marg{whydidnttheyaskevans}.
27595 \end{codeenv}
27596 and
27597 \begin{codeenv}
27598 \cs{gls}\marg{doandroidsdreamofelectricsheep}.
27599 \end{codeenv}
27600 to be discarded.
27601
27602 The complete document code is listed below. The document build is:
27603 \begin{verbatim}
27604 pdflatex sample-authors
27605 bib2gls --group sample-authors
27606 pdflatex sample-authors
27607 \end{verbatim}
27608 The resulting document is shown in \figureref{fig:sample-authors.pdf}.
27609
27610 \lstinputlisting[firstline=5]{../examples/sample-authors.tex}
27611
27612 \begin{figure}
27613 \figcontents
27614 {%
27615 \frame{\includegraphics[height=.9\textheight]{../examples/sample-authors.pdf}}%
27616 }
27617 {\caption{\filefmt{sample-authors.pdf}}}
27618 {fig:sample-authors.pdf}
27619 \end{figure}
27620
27621 \filesection{sample-citations.tex}
27622
27623 This example uses the \BibTeX\ file \exfile{citations.bib} to create
27624 a document that has both a bibliography created by \BibTeX\ and
27625 glossaries created by \bibgls\ listing the authors and the titles.
27626 There are no glossary reference commands, such as \cs{gls}, but
27627 \bibgls\ can be run with \longarg{cite-as-record} to treat the
27628 \ics{citation} commands (written to the \ext{aux} file by \ics{cite})
27629 as ignored records. Since \cs{cite} doesn't record the page number,
27630 there are no associated \glspl{location}.
27631
27632 The \mainglossary\ isn't required, so I've used
27633 \styopt{nomain} to suppress its creation. I want to use both the
27634 \glostyle{altlist} and \glostyle{indexgroup} styles but none of the
27635 other styles, so I've used \styopt{nostyles} to prevent the
27636 automatic loading of the default style packages and
27637 \styopt{stylemods} to load the \sty{glossary-tree} and
27638 \sty{glossary-list} packages and patch the styles. A \idx{full-stop}
27639 is automatically placed after the descriptions with
27640 \styopt{postdot}.
27641 \begin{codeenv}
27642 \cs{usepackage}\oarg{\styopt{record},\comment{using bib2gls}
27643 \styopt{nomain},\comment{don't define main glossary}
27644 \styopt{postdot},\comment{full stop after descriptions}
27645 \styopt{nostyles},\comment{don't load default styles}
27646 \comment{load glossary-tree and glossary-list and patch styles:}
27647 \styopt[tree,list]{stylemods}
27648 }\marg{glossaries-extra}
27649 \end{codeenv}
27650 Next I need to create the glossaries for the list of authors and
27651 list of titles:
27652 \begin{codeenv}
27653 \cs{newglossary*}\marg{contributors}\marg{Authors}
27654 \cs{newglossary*}\marg{titles}\marg{Titles}
27655 \end{codeenv}
27656 The simplest way of assigning the authors to the \code{contributors}
27657 glossary and the titles to the \code{titles} glossary is to use:
27658 \begin{codeenv}
27659 \csopt[contributors]{type}
27660 \end{codeenv}
27661 in the \idx{resourceset} and provide a
27662 modified version of \gls{bibglsnewbibtexentry} that assigns
27663 \field{type} after the options:
27664 \begin{codeenv}
27665 \cs{newcommand}\marg{\gls{bibglsnewbibtexentry}}[4]\marg{\comment{}
27666 \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{}
27667 }
27668 \end{codeenv}
27669 The standard \BibTeX\ \glspl{entrytype} need aliasing to
27670 \atentry{bibtexentry}:
27671 \begin{codeenv}
27672 \csopt[\ics{GlsXtrBibTeXEntryAliases}]{entry-type-aliases}
27673 \end{codeenv}
27674 and the \fieldfmt{title} field is aliased to \field{name}:
27675 \begin{codeenv}
27676 \csopt[\fieldfmt{title}=\field{name}]{field-aliases}
27677 \end{codeenv}
27678 (The other fields aren't required for the glossary lists.)
27679 The \field{category} is set to the original \gls{entrytype}:
27680 \begin{codeenv}
27681 \csopt[same as original entry]{category}
27682 \end{codeenv}
27683 So, for example, an entry that's provided in the \ext{bib} file with
27684 \atentryfmt{article} has the \field{category} field set to
27685 \code{article}. (Compare this with \csopt[same as entry]{category}
27686 which would set the \field{category} to \code{bibtexentry}.)
27687 The spawned entries are all defined using \atentry{contributor} and
27688 aren't aliased so both the \gls{entrytype} and the original \gls{entrytype}
27689 are \code{contributor}.
27690
27691 In order to list the titles according to category, I've use this as
27692 the sort field:
27693 \begin{codeenv}
27694 \csopt[\field{category}]{sort-field}
27695 \end{codeenv}
27696 and setting the sort suffix to the \field{name} field sub-sorts
27697 the \atentry{bibtexentry} types according to the title
27698 (which was aliased to the \field{name}) and the
27699 \atentry{contributor} types according to the author:
27700 \begin{codeenv}
27701 \csopt[\field{name}]{sort-suffix}
27702 \end{codeenv}
27703
27704 Next the groups identified by the labels \code{article} and \code{book}
27705 are assigned titles.
27706 \begin{codeenv}
27707 \gls{glsxtrsetgrouptitle}\marg{article}\marg{Articles}
27708 \gls{glsxtrsetgrouptitle}\marg{book}\marg{Books}
27709 \end{codeenv}
27710 The \field{group} field is actually set to the associated letter by the default
27711 \csopt{sort} method. The desired labels are stored in the \field{category}
27712 field. Since the entries are sorted by category, then they are naturally
27713 in those sub-blocks, which means that the group titles can be set by locally
27714 redefining \ics{glsxtrgroupfield} to \code{category}:
27715 \begin{codeenv}
27716 \cs{printunsrtglossary*}[\printglossopt[titles]{type},\printglossopt[indexgroup]{style}]
27717 \marg{\comment{}
27718 \cs{renewcommand}\marg{\cs{glsxtrgroupfield}}\marg{\field{category}}\comment{}
27719 \cs{renewcommand}\marg{\cs{glstreenamefmt}}[1]\marg{\cs{emph}\marg{\idx{param}1}}\comment{}
27720 \cs{renewcommand}\marg{\cs{glstreegroupheaderfmt}}[1]\marg{\ics{textbf}\marg{\idx{param}1}}\comment{}
27721 }
27722 \end{codeenv}
27723 This again contradicts the advice given in
27724 \sectionref{sec:logicaldivisions} as I'm sorting by the
27725 \field{group} label. (Technically it's sorting by the
27726 \field{category} label but this is being used as the group.) In this
27727 case it's not a problem as the labels closely match the titles and
27728 the sorting options ensure that the groups aren't broken up.
27729
27730 There's no \field{description} field set for these entries, but the
27731 \idx{postdescriptionhook} can still be used to append information.
27732 In this case, I've appended a cross-reference to the bibliography.
27733 Since the bibliography entry and the glossary term both have the
27734 same label, the citation can easily be obtained with
27735 \code{\ics{cite}\marg{\cs{glscurrententrylabel}}}:
27736 \begin{codeenv}
27737 \cs{newcommand}\marg{\postdeschook{article}}\marg{\cs{cite}\marg{\cs{glscurrententrylabel}}}
27738 \cs{newcommand}\marg{\postdeschook{book}}\marg{\cs{cite}\marg{\cs{glscurrententrylabel}}}
27739 \end{codeenv}
27740 Note that this needs to be done for each \BibTeX\ \gls{entrytype}, but in
27741 this case the \ext{bib} file only contains \atentryfmt{article} and
27742 \atentryfmt{book} entries. (Similarly for the group titles above.)
27743
27744 The list of contributors can simply be displayed with:
27745 \begin{codeenv}
27746 \cs{printunsrtglossary}[\printglossopt[contributors]{type},\printglossopt[altlist]{style}]
27747 \end{codeenv}
27748 This will only list the names as there's no description, but again
27749 the \idx{postdescriptionhook} can be used, in this case for the \code{contributor}
27750 category. The hook iterates
27751 over the internal list provided by the \field{bibtexentry} field.
27752 This allows the titles to be listed as well:
27753 \begin{codeenv}
27754 \cs{newcommand}\marg{\postdeschook{contributor}}\marg{\comment{}
27755 \ics{glsxtrifhasfield}\marg{\field{bibtexentry}}\marg{\cs{glscurrententrylabel}}\comment{}
27756 \marg{\comment{}
27757 \cs{glsxtrfieldforlistloop}
27758 \marg{\cs{glscurrententrylabel}}\marg{\field{bibtexentry}}\comment{}
27759 \marg{\csfmt{contributorhandler}}\comment{}
27760 }\comment{}
27761 \marg{\ics{par} No titles.}\comment{}
27762 }
27763 \end{codeenv}
27764 The \idx{handler} macro displays the name of the associated
27765 \atentry{bibtexentry} term and the citation:
27766 \begin{codeenv}
27767 \cs{newcommand}\marg{\csfmt{contributorhandler}}[1]\marg{\cs{par}\ics{glsentryname}\marg{\idx{param}1} \cs{cite}\marg{\idx{param}1}}
27768 \end{codeenv}
27769
27770 The complete document code is listed below. The document build is:
27771 \begin{verbatim}
27772 pdflatex sample-citations
27773 bib2gls --cite-as-record sample-citations
27774 bibtex sample-citations
27775 pdflatex sample-citations
27776 pdflatex sample-citations
27777 \end{verbatim}
27778 The resulting document is shown in \figureref{fig:sample-citations.pdf}.
27779
27780 \lstinputlisting[firstline=7]{../examples/sample-citations.tex}
27781
27782 \begin{figure}
27783 \figcontents
27784 {\pdftwocol{../examples/sample-citations.pdf}{2}}
27785 {\caption{\filefmt{sample-citations.pdf}}}
27786 {fig:sample-citations.pdf}
27787 \end{figure}
27788
27789 \filesection{sample-msymbols.tex}
27790
27791 This example uses \exfile{bigmathsymbols.bib},
27792 \exfile{mathsrelations.bib}, \exfile{binaryoperators.bib},
27793 \exfile{unaryoperators.bib} and \exfile{mathgreek.bib}. The \isty{stix}
27794 package is required for some of the commands used in
27795 \exfile{bigmathsymbols.bib}, so that must be loaded in the document.
27796
27797 I'm using the \glostyle{mcolalttree} style for this document,
27798 which means that the \sty{glossary-mcols} package is required and
27799 the styles need patching, which can be done with
27800 the \styopt{stylemods} package option:
27801 \begin{codeenv}
27802 \cs{usepackage}\oarg{\styopt{record},\comment{using bib2gls}
27803 \styopt{nostyles},\comment{don't load default styles}
27804 \styopt{postdot},\comment{append a dot after descriptions}
27805 \styopt[mcols]{stylemods},\comment{load glossary-mcols.sty and patch}
27806 \styopt[mcolalttree]{style}}\marg{glossaries-extra}
27807 \end{codeenv}
27808
27809 I'm not referencing any of the entries in the document as I'm just
27810 generating a complete list of all the defined symbols. This means I
27811 need to tell \bibgls\ to select all entries and don't bother saving
27812 the \field{location} field:
27813 \begin{codeenv}
27814 \csopt[false]{save-locations},
27815 \csopt[all]{selection}
27816 \end{codeenv}
27817 Since I'm using a style that's based on \glostyle{alttree} I need to
27818 find the widest \field{name}, which can be done with \csopt{set-widest}.
27819
27820 The simplest way of dividing the glossary into logical blocks is to
27821 sort according to the category, but first I need to use \csopt{field-aliases}
27822 to convert the custom \fieldfmt{identifier} field to \field{category}:
27823 \begin{codeenv}
27824 \csopt[\fieldfmt{identifier}=\field{category}]{field-aliases}
27825 \end{codeenv}
27826 and sort by the \field{category} field:
27827 \begin{codeenv}
27828 \csopt[\field{category}]{sort-field}
27829 \end{codeenv}
27830 Since this will cause identical sort values, I need to provide a
27831 a way of ordering these identical values. Here I've decided
27832 to fallback on the \field{description} field:
27833 \begin{codeenv}
27834 \csopt[\field{description}]{identical-sort-action}
27835 \end{codeenv}
27836 This means that entries will be ordered by \field{category} and
27837 then \field{description}, which naturally creates blocks of symbol
27838 types in the glossary. This only uses a simple case-sensitive string
27839 comparison which is fine for English, but for another language it
27840 would be better to use \csopt{sort-suffix} as in the
27841 \exfile{sample-textsymbols.tex} file.
27842
27843 Remember that I want a small vertical gap between each logical
27844 block. These need the \field{group} field which, with the default
27845 locale sort, is obtained from the first letter of the sort value.
27846 In this case the sort value is obtained from the \field{category}
27847 field, and as each category happens to start with a different
27848 letter, this means I get the desired effect. However, in the event
27849 that I add more entries with a new category that happens to start
27850 with the same letter as an existing category, it's better to provide
27851 a more future-proof method, so I've set the \field{group} field to
27852 fetch its value from the \field{category} field:
27853 \begin{codeenv}
27854 \csopt[\field{category}=\field{group}]{replicate-fields}
27855 \end{codeenv}
27856 (Since the \csopt{field-aliases} option is always performed before
27857 \csopt{replicate-fields}, the \field{category} field will already
27858 have been set and is available for replicating.)
27859
27860 This means that I'm essentially sorting by the \field{group} labels,
27861 which this manual has warned against doing. In this case, it's an
27862 acceptable break from that rule as I've used options that ensure the
27863 groups aren't broken up during sorting and I'm not concerned with the group
27864 titles. A method such as that used in \exfile{sample-textsymbols2.tex}
27865 would end up with titled blocks, which I don't want here. By using
27866 resource options such as \csopt{field-aliases} and
27867 \csopt{replicate-fields} I can avoid the warning that's triggered
27868 with the default \longarg{warn-non-bib-fields}.
27869
27870 The complete document code is listed below. The document build is:
27871 \begin{verbatim}
27872 pdflatex sample-msymbols
27873 bib2gls sample-msymbols
27874 pdflatex sample-msymbols
27875 \end{verbatim}
27876 The resulting document is shown in \figureref{fig:sample-msymbols.pdf}.
27877
27878 \lstinputlisting[firstline=5]{../examples/sample-msymbols.tex}
27879
27880 \begin{figure}
27881 \figcontents
27882 {%
27883 \frame{\includegraphics[height=.9\textheight]{../examples/sample-msymbols.pdf}}%
27884 }
27885 {\caption{\filefmt{sample-msymbols.pdf}}}
27886 {fig:sample-msymbols.pdf}
27887 \end{figure}
27888
27889 \filesection{sample-maths.tex}
27890
27891 This example uses \exfile{bigmathsymbols.bib} and \exfile{mathsobjects.bib}.
27892 It has a fairly similar preamble to \exfile{sample-msymbols.tex},
27893 but \exfile{no-interpret-preamble.bib} and
27894 \exfile{interpret-preamble.bib} are now needed to provide
27895 the \gls!{sortart} command:
27896 \begin{codeenv}
27897 \gls{GlsXtrLoadResources}\oarg{
27898 \csopt[no-interpret-preamble]{src},
27899 \csopt[false]{interpret-preamble}
27900 }
27901 \end{codeenv}
27902 There's also an extra custom field to alias:
27903 \begin{codeenv}
27904 \csopt[\fieldfmt{identifier}=\field{category},\fieldfmt{format}=\field{user1}]{field-aliases}
27905 \end{codeenv}
27906 I've aliased \fieldfmt{format} to \field{user1} since \gls!{glsxtrfmt}
27907 defaults to that field. If I decided to use a different field I also
27908 need to remember to redefine \ics{GlsXtrFmtField} to match.
27909
27910 As with \exfile{sample-msymbols.tex} I'm sorting by the
27911 \field{category} label and this value is copied to the \field{group}
27912 field, but again I don't have a \gls{hierarchicalglossary} as the logical
27913 blocks don't have titles.
27914
27915 In this document I only want to select entries that have been
27916 indexed, so I've omitted the \csopt{selection} option I used in the
27917 \exfile{sample-msymbols.tex} example, however
27918 I still don't want any number lists so I still have
27919 \csopt[false]{save-locations}.
27920
27921 I want \gls!{glsxtrfmt} to index the term (which it doesn't by default) so
27922 that means I need to redefine \ics{GlsXtrFmtDefaultOptions}
27923 to prevent it from using \code{noindex}:
27924 \begin{codeenv}
27925 \cs{renewcommand}\marg{\cs{GlsXtrFmtDefaultOptions}}\marg{}
27926 \end{codeenv}
27927 I've provided some convenient wrapper commands that use
27928 \gls!{glsxtrfmt*} or the non-linking \gls!{glsxtrentryfmt} that
27929 are in the form:
27930 \begin{codeenv}
27931 \cs{newcommand}\marg{\cmd{set}}[2][]\marg{\gls{glsxtrfmt*}\oarg{\idx{param}1}\marg{set}\marg{\idx{param}2}}
27932 \cs{newcommand}\marg{\cmd{nlset}}[1]\marg{\gls{glsxtrentryfmt}\marg{set}\marg{\idx{param}1}}
27933 \end{codeenv}
27934 The use of the starred form allows:
27935 \begin{codeenv}
27936 \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{]}
27937 \end{codeenv}
27938 which produces:
27939 \[ \mathcal{A} = \bigcup_{i=1}^n \mathcal{B}_i \]
27940 Note the difference if the optional arguments aren't used:
27941 \begin{codeenv}
27942 \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{]}
27943 \end{codeenv}
27944 This produces:
27945 \[ \mathcal{A} = \bigcup{}_{i=1}^n \mathcal{B}{}_i \]
27946
27947 Be careful with the set cardinality example. You might be tempted to
27948 nest \csfmt{set} within the argument of \csfmt{setcard} but this
27949 results in nested hyperlinks. These are unpredictable and there's no
27950 consistent handling of them between different PDF viewers. It can
27951 also be confusing to the reader. If
27952 $\lvert\mathcal{B}_1\cup\mathcal{B}_2\rvert$
27953 shows up as what appears to be a single hyperlink, where would the
27954 reader expect the target? This is the reason for providing the
27955 non-linking commands like \csfmt{nlset} and \csfmt{nlsetcard}.
27956
27957 The complete document code is listed below. The document build is:
27958 \begin{verbatim}
27959 pdflatex sample-maths
27960 bib2gls sample-maths
27961 pdflatex sample-maths
27962 \end{verbatim}
27963 The resulting document is shown in \figureref{fig:sample-maths.pdf}.
27964
27965 \lstinputlisting[firstline=5]{../examples/sample-maths.tex}
27966
27967 \begin{figure}
27968 \figcontents
27969 {%
27970 \frame{\includegraphics[height=.9\textheight]{../examples/sample-maths.pdf}}%
27971 }
27972 {\caption{\filefmt{sample-maths.pdf}}}
27973 {fig:sample-maths.pdf}
27974 \end{figure}
27975
27976 \filesection{sample-textsymbols.tex}
27977
27978 This example uses \exfile{miscsymbols.bib}.
27979 This requires both \isty{marvosym} and (with the \styoptfmt{weather} option)
27980 \isty{ifsym}. Unfortunately both define the commands \csfmt{Sun}
27981 and \csfmt{Lightning}, so these commands need to be undefined after
27982 the first package is loaded and before the second.
27983 Since I want the definitions provide by \sty{ifsym} I have to first
27984 load \sty{marvosym}, then undefine the conflicting commands and then
27985 load \sty{ifsym}:
27986 \begin{codeenv}
27987 \cs{usepackage}\marg{etoolbox}
27988 \cs{usepackage}\marg{marvosym}
27989 \cs{undef}\cmd{Sun}
27990 \cs{undef}\cmd{Lightning}
27991 \cs{usepackage}\oarg{\styoptfmt{weather}}\marg{ifsym}
27992 \end{codeenv}
27993 The \sty{etoolbox} package is also loaded as it provides
27994 \ics{undef}. (An alternative is to modify the
27995 \exfile{miscsymbols.bib} file so that it uses \sty{ifsym}'s more
27996 generic \cs{textweathersymbol} command and omit the \styoptfmt{weather}
27997 option when loading the package, but the method used here
27998 demonstrates how to deal with such conflicts.)
27999
28000 The custom \gls{entrytype} \atentryfmt{icon} must be aliased for the
28001 entries to be recognised:
28002 \begin{codeenv}
28003 \csopt[icon=symbol]{entry-type-aliases}
28004 \end{codeenv}
28005
28006 Since none of the entries have a \field{name} or \field{description}
28007 field, the custom fields \fieldfmt{icon} and
28008 \fieldfmt{icondescription} need to be aliased to them.
28009 The document uses the \glostyle{alttreegroup} style where the groups
28010 are obtained from the \field{category}, which again I obtain from
28011 the custom \fieldfmt{identifier} field using:
28012 \begin{codeenv}
28013 \csopt[
28014 \fieldfmt{identifier}=\field{category},
28015 \fieldfmt{icon}=\field{name},
28016 \fieldfmt{icondescription}=\field{description}]{field-aliases},
28017 \csopt[\field{category}=\field{group}]{replicate-fields}
28018 \end{codeenv}
28019 The \field{group} field is just a label and an appropriate title needs to be
28020 supplied for each group label:
28021 \begin{codeenv}
28022 \cs{glsxtrsetgrouptitle}\marg{information}\marg{Information}
28023 \cs{glsxtrsetgrouptitle}\marg{mediacontrol}\marg{Media Controls}
28024 \cs{glsxtrsetgrouptitle}\marg{weather}\marg{Weather Symbols}
28025 \end{codeenv}
28026 This also requires sorting first by \field{category} and then
28027 fallback on another field. The most appropriate here is the
28028 \field{description} field, but instead of using
28029 \csopt{identical-sort-action}, I'm using \csopt{sort-suffix},
28030 which works better with the default locale sort when the fallback
28031 field consists of words or phrases.
28032 \begin{codeenv}
28033 \csopt[\field{category}]{sort-field},
28034 \csopt[\field{description}]{sort-suffix},
28035 \csopt[|]{sort-suffix-marker}
28036 \end{codeenv}
28037 Since I'm using one of the \glostyle{alttree} styles, I need to set
28038 the widest name:
28039 \begin{codeenv}
28040 \csopt{set-widest}
28041 \end{codeenv}
28042 In this case, \bibgls\ won't be able to determine the widest name
28043 since it doesn't recognise any of the commands, so it will have to
28044 use the fallback command, which will use one of the commands
28045 provided by the \sty{glossaries-extra-stylemods} package.
28046
28047 This is actually not the best method as \bibgls\ can't see the group
28048 titles as they're in the document, so it's only able to sort by the
28049 label. While this might work for English, it can become a problem
28050 for other languages that use extended Latin or non-Latin characters
28051 in their alphabet. A much better method is to treat this as a
28052 \gls{hierarchicalglossary} with topic titles as the \glspl{top-levelentry}.
28053 This is covered in the next example \exfile{sample-textsymbols2.tex}.
28054
28055 The complete document code is listed below. The document build is:
28056 \begin{verbatim}
28057 pdflatex sample-textsymbols
28058 bib2gls sample-textsymbols
28059 pdflatex sample-textsymbols
28060 \end{verbatim}
28061 The resulting document is shown in \figureref{fig:sample-textsymbols.pdf}.
28062
28063 \lstinputlisting[firstline=6]{../examples/sample-textsymbols.tex}
28064
28065 \begin{figure}
28066 \figcontents
28067 {%
28068 \frame{\includegraphics[height=.9\textheight]{../examples/sample-textsymbols.pdf}}%
28069 }
28070 {\caption{\filefmt{sample-textsymbols.pdf}}}
28071 {fig:sample-textsymbols.pdf}
28072 \end{figure}
28073
28074 \filesection{sample-textsymbols2.tex}
28075
28076 This example is a better approach than the
28077 \exfile{sample-textsymbols.tex} example above. As with the previous
28078 example, this requires both \isty{marvosym} and \isty{ifsym} so the
28079 same patch is applied to avoid conflict.
28080
28081 As before, the custom \gls{entrytype} \atentryfmt{icon} must be aliased for the
28082 entries to be recognised:
28083 \begin{codeenv}
28084 \csopt[icon=symbol]{entry-type-aliases}
28085 \end{codeenv}
28086
28087 The \exfile{topics.bib} file contains terms with
28088 labels that match the custom \fieldfmt{identifier} fields used in
28089 the \exfile{miscsymbols.bib} file. So both files are loaded and the
28090 \fieldfmt{identifier} field is now aliased to \field{parent}. These
28091 \glspl{parententry} represent the topics and unlike the previous example
28092 it's now possible to sort by the topic title (obtained from the
28093 \field{name} field) instead of by the label.
28094 \begin{codeenv}
28095 \csopt[topics,miscsymbols]{src},
28096 \csopt[
28097 \fieldfmt{identifier}=\field{parent},
28098 \fieldfmt{icon}=\field{name},
28099 \fieldfmt{icondescription}=\field{description}]{field-aliases},
28100 \end{codeenv}
28101 There's no \csopt{sort-field} option in this example. The default
28102 \field{sort} field is used. Since it's not set for any of the
28103 entries, the fallback value will be used. In the case of the topic
28104 titles (\atentry{index} and \atentry{indexplural}), I want to sort
28105 by the \field{name}, which is the default fallback if the
28106 \field{sort} field is missing for the index \glspl{entrytype}.
28107
28108 The default fallback for the \field{sort} field for \atentry{symbol}
28109 entries is the label, but in this case I want to use the
28110 \field{description} field:
28111 \begin{codeenv}
28112 \csopt[description]{symbol-sort-fallback}
28113 \end{codeenv}
28114 The best styles for this kind of glossary are the topic styles
28115 provided by \isty{glossary-topic}. This package was only added to
28116 \sty{glossaries-extra} v1.40, so you need to make sure you have at
28117 least that version installed.
28118
28119 In this case I've decided to use the \glostyle{topic} style. I can
28120 use it with or without the \csopt{set-widest} option.
28121 As with the previous example, \bibgls\ won't be able to determine
28122 the widest name since it doesn't recognise any of the commands
28123 contained in the \field{name} fields, so it will have to use the
28124 fallback method, which will use one of the commands provided by the
28125 \sty{glossaries-extra-stylemods} package. The \code{tree} option is
28126 needed to enable the appropriate commands:
28127 \begin{codeenv}
28128 \cmd{usepackage}\oarg{\styopt{record},
28129 \styopt{nostyles},
28130 \styopt{postdot},
28131 \styopt[tree,topic]{stylemods},
28132 \styopt[topic]{style}}\marg{glossaries-extra}
28133 \end{codeenv}
28134
28135 The complete document code is listed below. The document build is:
28136 \begin{verbatim}
28137 pdflatex sample-textsymbols2
28138 bib2gls --group sample-textsymbols2
28139 pdflatex sample-textsymbols2
28140 \end{verbatim}
28141 The resulting document is shown in \figureref{fig:sample-textsymbols2.pdf}.
28142
28143 \lstinputlisting[firstline=5]{../examples/sample-textsymbols2.tex}
28144
28145 \begin{figure}
28146 \figcontents
28147 {%
28148 \frame{\includegraphics[height=.9\textheight]{../examples/sample-textsymbols2.pdf}}%
28149 }
28150 {\caption{\filefmt{sample-textsymbols2.pdf}}}
28151 {fig:sample-textsymbols2.pdf}
28152 \end{figure}
28153
28154 \filesection{sample-markuplanguages.tex}
28155
28156 This example uses \exfile{markuplanguages.bib}. Since the file
28157 includes abbreviations, any commands that must be used before
28158 abbreviations are defined need to go before
28159 \gls!{GlsXtrLoadResources}. This includes the abbreviation style,
28160 which I've set to \abbrstyle{long-short-desc}:
28161 \begin{codeenv}
28162 \cs{setabbreviationstyle}\oarg{markuplanguage}\marg{\abbrstyle{long-short-desc}}
28163 \end{codeenv}
28164 This style sets the \field{name} field using
28165 \ics{glsxtrlongshortdescname}, which defaults to the long form
28166 followed by the short form in parentheses. I decided to switch this
28167 round so that the short form is shown first, which conveniently
28168 matches the default \csopt{abbreviation-sort-fallback}.
28169 \begin{codeenv}
28170 \cs{renewcommand}*\marg{\cs{glsxtrlongshortdescname}}\marg{\comment{}
28171 \cs{protect}\ics{glsabbrvfont}\marg{\ics{the}\ics{glsshorttok}}\cs{space}
28172 \ics{glsxtrparen}\marg{\ics{glslongfont}\marg{\cs{the}\ics{glslongtok}}}\comment{}
28173 }
28174 \end{codeenv}
28175 (The long form is still shown before the short form on the first use
28176 of \cs{gls} in the document. The switch in the above code only
28177 affects how the term is displayed in the glossary.)
28178
28179 This redefinition must be done before the abbreviations are defined
28180 as it's expanded when the \field{name} field is set. (Note the need
28181 to protect commands that shouldn't be expanded.) If I decide not to change
28182 the \field{name} format in this way, I would then need to use
28183 \csopt[long]{abbreviation-sort-fallback}.
28184
28185 I also decided to make use of the custom command \csfmt{abbrvtag}
28186 that marks up the letters in the \field{long} field used to obtain
28187 the abbreviation. As with the abbreviation style, this must be
28188 done before the abbreviations are defined:
28189 \begin{codeenv}
28190 \cs{GlsXtrEnableInitialTagging}\marg{markuplanguage}\marg{\cmd{abbrvtag}}
28191 \end{codeenv}
28192 If you accidentally place it after \gls{GlsXtrLoadResources}, you'll
28193 encounter an error on the second \LaTeX\ run (but not the first).
28194 This is because \ics{GlsXtrEnableInitialTagging} requires that the
28195 supplied command (\csfmt{abbrvtag} in this case) be undefined. On
28196 the first \LaTeX\ it's undefined, but on the second it picks up
28197 the \atentry{preamble} definition, which is now in the resource file.
28198
28199 The tagging format is governed by \ics{glsxtrtagfont} which
28200 underlines its argument by default. I've redefined it to also
28201 convert the letter to \idx{uppercase}:
28202 \begin{codeenv}
28203 \cs{renewcommand}*\marg{\cs{glsxtrtagfont}}[1]\marg{\ics{underline}\marg{\cs{glsuppercase}\marg{\idx{param}1}}}
28204 \end{codeenv}
28205 Note that in the \code{mathml} case, the first tag consists of more
28206 than one letter:
28207 \begin{codeenv}
28208 \field{long}=\marg{\cmd{abbrvtag}\marg{m\cs{NoCaseChange}\marg{ath}}ematical }\idx{stringconcat}markuplang
28209 \end{codeenv}
28210 Here \ics{NoCaseChange} prevents \ics{glsuppercase}
28211 from applying the case change.
28212
28213 The default \csopt{selection} criteria includes entries that have
28214 been indexed and any cross-references. Some of the
28215 \field{description} fields include \ics{glsxtrshort}, which \bibgls\ picks
28216 up and the referenced entry is included in the dependency list.
28217 However, I don't want any indexing
28218 performed by commands occurring in the glossary. This can be dealt
28219 with in one of two ways: either switch the format to \encap{glsignore}
28220 or suppress the indexing by changing the default options with
28221 \ics{GlsXtrSetDefaultGlsOpts}. In this case I decided to turn the
28222 records into ignored records:
28223 \begin{codeenv}
28224 \ics{GlsXtrSetDefaultNumberFormat}\marg{\encap{glsignore}}
28225 \end{codeenv}
28226 This means that some of the entries won't have \glspl{locationlist}, so
28227 I've defined a \idx{postdescriptionhook} that inserts a \idx{full-stop} after the
28228 \field{description} if there's no \gls{location} otherwise it inserts a
28229 comma:
28230 \begin{codeenv}
28231 \cs{newcommand}\marg{\postdeschook{markuplanguage}}\marg{\comment{}
28232 \cs{glsxtrifhasfield}\marg{\field{location}}\marg{\cs{glscurrententrylabel}}\comment{}
28233 \marg{,}\comment{}
28234 \marg{.}\comment{}
28235 }
28236 \end{codeenv}
28237 I've used \csopt{loc-suffix} to append a \idx{full-stop} after the
28238 \glspl{locationlist}. This doesn't affect the entries that haven't been
28239 indexed.
28240
28241 I decided to convert the first letter of the \field{name} field to
28242 \idx{uppercase}. Since the \field{name} is implicitly set for
28243 abbreviations based on the style, I've decided to implement this
28244 through the \catattr{glossname} attribute rather than using
28245 \csopt{name-case-change}:
28246 \begin{codeenv}
28247 \cs{glssetcategoryattribute}\marg{markuplanguage}\marg{\catattr{glossname}}\marg{firstuc}
28248 \end{codeenv}
28249 If this line causes an error when the glossary is displayed that goes
28250 away if it's commented out, make sure you have at least version 2.06
28251 of \sty{mfirstuc}. For most of the entries, this doesn't make a
28252 difference as they already start with a capital. It's only the
28253 \code{markdown} entry that's actually affected.
28254
28255 The description case change is dealt with by \bibgls\ instead:
28256 \begin{codeenv}
28257 \csopt[firstuc]{description-case-change}
28258 \end{codeenv}
28259 This works better than the \catattr{glossdesc} attribute as \bibgls\ can
28260 convert commands like \ics{glstext} into \ics{Glstext} which
28261 \ics{makefirstuc} can't do. (Although in this particular example,
28262 there's no difference as both instances of \cs{glstext} already
28263 produce \idx{uppercase} text.)
28264
28265 The complete document code is listed below. The document build is:
28266 \begin{verbatim}
28267 pdflatex sample-markuplanguages
28268 bib2gls --group sample-markuplanguages
28269 pdflatex sample-markuplanguages
28270 \end{verbatim}
28271 The resulting document is shown in \figureref{fig:sample-markuplanguages.pdf}.
28272
28273 \lstinputlisting[firstline=5]{../examples/sample-markuplanguages.tex}
28274
28275 \begin{figure}
28276 \figcontents
28277 {%
28278 \frame{\includegraphics[height=.9\textheight]{../examples/sample-markuplanguages.pdf}}%
28279 }
28280 {\caption{\filefmt{sample-markuplanguages.pdf}}}
28281 {fig:sample-markuplanguages.pdf}
28282 \end{figure}
28283
28284
28285 \filesection{sample-usergroups.tex}
28286
28287 This example uses \exfile{usergroups.bib}. This requires \XeLaTeX\
28288 or \LuaLaTeX\ as the \ext{bib} file includes \idx{non-ASCII} labels.
28289 The entries include fields in different languages, the main one
28290 being English. If an entry has a non-English \field{name} or
28291 \field{long} field, it also includes the custom field
28292 \fieldfmt{translation} that provides an (approximate) translation.
28293 If this field is present, the language is given by the first element
28294 of the custom \fieldfmt{language} field.
28295
28296 In this case, I'm providing keys for the custom
28297 \fieldfmt{language} and \fieldfmt{translation} fields, and, for a bit
28298 of variety from the other examples, I'm ignoring the custom
28299 \fieldfmt{identifier} field. The custom keys are provided with
28300 \ics{glsaddstoragekey}:
28301 \begin{codeenv}
28302 \cs{glsaddstoragekey}\marg{language}\marg{}\marg{\cmd{glsentrylanguage}}
28303 \cs{glsaddstoragekey}\marg{translation}\marg{}\marg{\cmd{glsentrytranslation}}
28304 \end{codeenv}
28305 The \ext{bib} file includes abbreviations. Remember that the
28306 abbreviation style must be set before the resource file is loaded:
28307 \begin{codeenv}
28308 \cs{setabbreviationstyle}\oarg{tug}\marg{\abbrstyle{long-short-user}}
28309 \end{codeenv}
28310 For this example, I'm explicitly setting the \field{category} field
28311 to \code{tug}:
28312 \begin{codeenv}
28313 \csopt[tug]{category}
28314 \end{codeenv}
28315 Some of the fields end with a \idx{full-stop}. This isn't a problem with
28316 the \field{long} field as the first use follows the long form with
28317 the short form in parentheses, but it will be a problem on
28318 subsequent use if the \field{short} field ends with a \idx{full-stop}.
28319 This means I need to check for end-of-sentence punctuation
28320 for the \field{short} field. It's also a good idea to do this for
28321 the \field{name} field for the non-abbreviations.
28322 \begin{codeenv}
28323 \csopt[\field{name},\field{short}]{check-end-punctuation}
28324 \end{codeenv}
28325 It's now possible to discard a \idx{full-stop} that follows
28326 \ics{gls}:
28327 \begin{codeenv}
28328 \cs{renewcommand}*\marg{\cs{glsxtrifcustomdiscardperiod}}[2]\marg{\comment{}
28329 \ics{ifglshasshort}\marg{\cs{glslabel}}\comment{}
28330 \marg{\comment{}
28331 \cs{glsxtrifwasfirstuse}\marg{}\comment{}
28332 \marg{\comment{}
28333 \cs{GlsXtrIfFieldUndef}\marg{\fielddisp{fieldendpunc}{shortendpunc}}\marg{\cs{glslabel}}\marg{\idx{param}2}\marg{\idx{param}1}\comment{}
28334 }\comment{}
28335 }\comment{}
28336 \marg{\comment{}
28337 \cs{GlsXtrIfFieldUndef}\marg{\fielddisp{fieldendpunc}{nameendpunc}}\marg{\cs{glslabel}}\marg{\idx{param}2}\marg{\idx{param}1}\comment{}
28338 }\comment{}
28339 }
28340 \end{codeenv}
28341 This first tests if the entry that's just been referenced has a
28342 \field{short} field. If it has, then the next test is to check if
28343 that was the first use for that entry. If it was, nothing is done.
28344 If it wasn't, then \cs{GlsXtrIfFieldUndef} is used to determine
28345 if \fielddisp{fieldendpunc}{shortendpunc} has been set. If it has
28346 been set then the period discard function is performed. If the
28347 entry doesn't have a \field{short} field, then the
28348 \fielddisp{fieldendpunc}{nameendpunc} field needs checking instead.
28349
28350 Since the document requires \XeLaTeX\ or \LuaLaTeX\ and has some
28351 \idx{non-ASCII} characters, it needs \sty{fontspec} and an
28352 appropriate font. In this case I've chosen \qt{Linux Libertine O}.
28353 If you don't have it installed, you'll need to change it.
28354 \begin{verbatim}
28355 \usepackage{fontspec}
28356 \setmainfont{Linux Libertine O}
28357 \end{verbatim}
28358 Since it's a multilingual document I also need \isty{polyglossia}
28359 with the main language set to \code{english}:
28360 \begin{codeenv}
28361 \cmd{usepackage}\marg{polyglossia}
28362 \ics{setmainlanguage}\oarg{variant=uk}\marg{english}
28363 \end{codeenv}
28364 Now comes the difficult bit. The document needs to determine what
28365 other languages need to be loaded. The \sty{tracklang} package
28366 provides a convenient interface when dealing with language tags.
28367 This is automatically loaded by \styfmt{glossaries} but I've loaded
28368 it here explicitly as a reminder:
28369 \begin{verbatim}
28370 \usepackage{tracklang}
28371 \end{verbatim}
28372 Once the \hyperref[sec:resourcesets]{resource file} has been loaded, I need to
28373 iterate over all the defined entries and check if the \fieldfmt{translation}
28374 field has been set. If it has, then the first language tag in the
28375 \fieldfmt{language} field will supply the language, but this needs to be
28376 converted from the \idx{IETF} language tag to a language name recognised by
28377 \isty{polyglossia}.
28378
28379 Iterating over all entries can be done with \ics{forglsentries}
28380 but remember that no entries will be defined before \bibgls\ has
28381 been run, so this does nothing on the first \LaTeX\ run.
28382 \begin{codeenv}
28383 \cs{forglsentries}\marg{\cmd{thislabel}}\marg{\comment{}
28384 \cs{glsxtrifhasfield}\marg{translation}\marg{\cmd{thislabel}}\comment{}
28385 \marg{\comment{}
28386 \comment{requires glossaries-extra v1.24}
28387 \cs{glsxtrforcsvfield}\marg{\cmd{thislabel}}\marg{language}\marg{\cmd{addfirstlang}}\comment{}
28388 }\comment{}
28389 \marg{}\comment{}
28390 }
28391 \end{codeenv}
28392 Within the outer (\cs{forglsentries}) \idx{loop}, there's a check
28393 for the \fieldfmt{translation} field using \ics{glsxtrifhasfield}.
28394 If it's present, then the first element of the \fieldfmt{language}
28395 field is required. The simplest way to get this is to use
28396 \ics{glsxtrforcsvfield} which iterates over all elements of the
28397 given field (\fieldfmt{language} in this case) and break out of the
28398 \idx{loop} (with \ics{glsxtrendfor}) once the language has been found.
28399
28400 The \idx{handler} function (\csfmt{addfirstlang}) is defined so that it
28401 adds the given language tag as a tracked language using
28402 \ics{TrackLocale}. This command sets
28403 \ics{TrackLangLastTrackedDialect} to the associated
28404 (\sty{tracklang}) dialect label for convenience. This dialect label
28405 can then be converted to the root language label using
28406 \ics{TrackedLanguageFromDialect}. If this language is supported
28407 by \isty{polyglossia}, then there should be a file called
28408 \metafilefmt{gloss-}{language}{.ldf}.
28409
28410 Some of the entries use the same language, so it's necessary to
28411 check if the language has already been defined before loading it.
28412 There's also a problem in that the language file should not be
28413 loaded in a scoped context, but both \ics{glsxtrforcsvfield}
28414 and the unstarred \ics{glsxtrifhasfield} add implicit grouping.
28415 To solve both problems, an internal \sty{etoolbox} list is
28416 defined:
28417 \begin{verbatim}
28418 \newcommand{\langlist}{}%
28419 \end{verbatim}
28420 and \ics{xifinlist} is used to first check if the language label is
28421 already in the list before adding it. Since this part of the code is
28422 scoped, the global \ics{listxadd} is used to add the language label
28423 to the list.
28424
28425 Next the \field{useri} field is set to
28426 \encapdisp{textlanguage}{text\meta{language}}
28427 which is the name of the control sequence used with
28428 \sty{polyglossia} to switch language for a short block of text. This means that
28429 \gls{glsxtrentryfmt}\margm{text} can be used to format \meta{text}
28430 in the relevant language. Finally, \ics{glsxtrendfor} is used to
28431 break out of the \idx{loop}.
28432 \begin{codeenv}
28433 \cs{newcommand}*\marg{\cmd{addfirstlang}}[1]\marg{\comment{}
28434 \cs{TrackLocale}\marg{\idx{param}1}\comment{}
28435 \ics{edef}\cmd{thislanguage}\marg{\comment{}
28436 \cs{TrackedLanguageFromDialect}\cs{TrackLangLastTrackedDialect}}\comment{}
28437 \ics{IfFileExists}\marg{gloss-\cmd{thislanguage}.ldf}\comment{}
28438 \marg{\comment{}
28439 \ics{xifinlist}\marg{\cmd{thislanguage}}\marg{\cmd{langlist}}\marg{}\comment{}
28440 \marg{\ics{listxadd}\marg{\cmd{langlist}}\marg{\cmd{thislanguage}}}\comment{}
28441 \ics{xGlsXtrSetField}\marg{\cmd{thislabel}}\marg{\field{useri}}\marg{\encapdisp{textlanguage}{text\cmd{thislanguage}}}\comment{}
28442 \ics{glsxtrendfor}
28443 }\comment{}
28444 \marg{}\comment{}
28445 }
28446 \end{codeenv}
28447 Once the \ics{forglsentries} \idx{loop} has found the appropriate
28448 languages, it's now necessary to iterate over the internal list
28449 \csfmt{langlist} and set the language:
28450 \begin{codeenv}
28451 \ics{forlistloop}\marg{\ics{setotherlanguage}}\marg{\cmd{langlist}}
28452 \end{codeenv}
28453 The \abbrstyle{long-short-user} style now needs to be adjusted
28454 to ensure that it picks up the appropriate language change.
28455 By default this style checks the \field{useri} field, so this needs
28456 to be changed to \fieldfmt{translation} by redefining
28457 \ics{glsxtruserfield}:
28458 \begin{codeenv}
28459 \cs{renewcommand}*\marg{\cs{glsxtruserfield}}\marg{translation}
28460 \end{codeenv}
28461 The command that governs the format of the parenthetical material
28462 (\ics{glsxtruserparen}) also needs adjusting. I've changed the
28463 space before the parenthesis to \ics{cs.space} because some of the
28464 long fields end with a \idx{full-stop} and this corrects the
28465 spacing. The \fieldfmt{translation} field is in English,
28466 so this needs to be encapsulated with \icsdisp{textlanguage}{textenglish}
28467 in case the surrounding text is in a different language.
28468 \begin{codeenv}
28469 \cs{renewcommand}*\marg{\cs{glsxtruserparen}}[2]\marg{\comment{}
28470 \cs{cs.space}
28471 \cs{glsxtrparen}\marg{\idx{param}1\comment{}
28472 \cs{ifglshasfield}\marg{\cs{glsxtruserfield}}\marg{\idx{param}2}\marg{,
28473 \csdisp{textlanguage}{textenglish}\marg{\cs{glscurrentfieldvalue}}}\marg{}}\comment{}
28474 }
28475 \end{codeenv}
28476 Next I've defined a convenient command for use in the \catattr{textformat}
28477 attributes for the custom \code{tug} category:
28478 \begin{codeenv}
28479 \cs{newcommand}*\marg{\cmd{tugtextformat}}[1]\marg{\comment{}
28480 \cs{glsxtrentryfmt}\marg{\cs{glslabel}}\marg{\idx{param}1}\comment{}
28481 }
28482 \end{codeenv}
28483 This uses \gls{glsxtrentryfmt} to encapsulate the given text
28484 in the appropriate language command (if provided). When this is set
28485 as the \catattr{textformat} attribute, it will be used instead of
28486 \ics{glstextformat}, which means that the entry label can be
28487 referenced with \cs{glslabel}.
28488
28489 There's a similar command for use in the \catattr{glossnamefont}
28490 attribute. This is used in the glossary, so the label is referenced
28491 with \cs{glscurrententrylabel}:
28492 \begin{codeenv}
28493 \cs{newcommand}*\marg{\cmd{tugnameformat}}[1]\marg{\comment{}
28494 \cs{glsxtrentryfmt}\marg{\cs{glscurrententrylabel}}\marg{\idx{param}1}\comment{}
28495 }
28496 \end{codeenv}
28497 The attributes can now be set to the relevant control sequence name:
28498 \begin{codeenv}
28499 \cs{glssetcategoryattribute}\marg{tug}\marg{\catattr{textformat}}\marg{tugtextformat}
28500 \cs{glssetcategoryattribute}\marg{tug}\marg{\catattr{glossnamefont}}\marg{tugnameformat}
28501 \end{codeenv}
28502
28503 The document uses the \glostyle{bookindex} style, which is set in
28504 the package options:
28505 \begin{codeenv}
28506 \cmd{usepackage}\oarg{\styopt{record},
28507 \styopt{nostyles},
28508 \styopt[bookindex]{stylemods},
28509 \styopt[bookindex]{style}
28510 }\marg{glossaries-extra}
28511 \end{codeenv}
28512 The \glostyle{bookindex} style ignores the \field{description} field, so I've
28513 provided a \idx{postnamehook} to append it in parentheses (with the
28514 translation, if provided):
28515 \begin{codeenv}
28516 \cs{newcommand}\marg{\postnamehook{tug}}\marg{\comment{}
28517 \ics{ifglshasdesc}\marg{\cs{glscurrententrylabel}}\comment{}
28518 \marg{\cs{cs.space}(\cs{glossentrydesc}\marg{\cs{glscurrententrylabel}}\comment{}
28519 \cs{glsxtrifhasfield}\marg{translation}\marg{\cs{glscurrententrylabel}}\comment{}
28520 \marg{, \csdisp{textlanguage}{textenglish}\marg{\cs{glscurrentfieldvalue}}}\comment{}
28521 \marg{}\comment{}
28522 )}\comment{}
28523 \marg{\comment{}
28524 \cs{glsxtrifhasfield}\marg{translation}\marg{\cs{glscurrententrylabel}}\comment{}
28525 \marg{\cs{cs.space}(\csdisp{textlanguage}{textenglish}\marg{\cs{glscurrentfieldvalue}})}\comment{}
28526 \marg{}\comment{}
28527 }\comment{}
28528 }
28529 \end{codeenv}
28530 Remember that this hook is included within the \field{name} font
28531 (provided by the \catattr{glossnamefont} attribute in this case)
28532 so \csdisp{textlanguage}{textenglish} is again used to switch the language to
28533 English for the translation.
28534
28535 The complete document code is listed below. The document build is:
28536 \begin{verbatim}
28537 xelatex sample-usergroups
28538 bib2gls --group sample-usergroups
28539 xelatex sample-usergroups
28540 xelatex sample-usergroups
28541 \end{verbatim}
28542 The two pages of the document are shown in
28543 \figureref{fig:sample-usergroups.pdf}. Since the entries have all
28544 been referenced on page~1, the \glspl{locationlist} are all simply~\qt{1}.
28545
28546 %\lstinputlisting[firstline=5]{../examples/sample-usergroups.tex}
28547 \begin{lstlisting}[escapechar=|]
28548 \documentclass{scrreprt}
28549
28550 \usepackage{fontspec}
28551 \setmainfont{Linux Libertine O}
28552
28553 \usepackage{polyglossia}
28554 \setmainlanguage[variant=uk]{english}
28555 \usepackage{tracklang}
28556 \usepackage{etoolbox}
28557
28558 \usepackage[record,% use bib2gls
28559 nostyles,% don't load default styles
28560 stylemods={bookindex},
28561 style={bookindex}
28562 ]{glossaries-extra}
28563
28564 \glsaddstoragekey{language}{}{\glsentrylanguage}
28565 \glsaddstoragekey{translation}{}{\glsentrytranslation}
28566
28567 \setabbreviationstyle[tug]{long-short-user}
28568
28569 \GlsXtrLoadResources[
28570 src={usergroups}, % data in usergroups.bib
28571 check-end-punctuation={name,short},
28572 category=tug
28573 ]
28574
28575 \renewcommand*{\glsxtrifcustomdiscardperiod}[2]{%
28576 \ifglshasshort{\glslabel}%
28577 {%
28578 \glsxtrifwasfirstuse{}%
28579 {%
28580 \GlsXtrIfFieldUndef{shortendpunc}{\glslabel}{#2}{#1}%
28581 }%
28582 }%
28583 {%
28584 \GlsXtrIfFieldUndef{nameendpunc}{\glslabel}{#2}{#1}%
28585 }%
28586 }
28587
28588 \newcommand{\langlist}{}%
28589
28590 \newcommand*{\addfirstlang}[1]{%
28591 \TrackLocale{#1}%
28592 \edef\thislanguage{%
28593 \TrackedLanguageFromDialect\TrackLangLastTrackedDialect}%
28594 \IfFileExists{gloss-\thislanguage.ldf}%
28595 {%
28596 \xifinlist{\thislanguage}{\langlist}{}%
28597 {\listxadd{\langlist}{\thislanguage}}%
28598 \xGlsXtrSetField{\thislabel}{useri}{text\thislanguage}%
28599 \glsxtrendfor
28600 }%
28601 {}%
28602 }
28603
28604 \forglsentries{\thislabel}{%
28605 \glsxtrifhasfield{translation}{\thislabel}%
28606 {%
28607 % requires glossaries-extra v1.24
28608 \glsxtrforcsvfield{\thislabel}{language}{\addfirstlang}%
28609 }%
28610 {}%
28611 }
28612
28613 \forlistloop{\setotherlanguage}{\langlist}
28614
28615 \renewcommand*{\glsxtruserfield}{translation}
28616
28617 \renewcommand*{\glsxtruserparen}[2]{%
28618 \
28619 \glsxtrparen{#1%
28620 \ifglshasfield{\glsxtruserfield}{#2}{,
28621 \textenglish{\glscurrentfieldvalue}}{}}%
28622 }
28623
28624 \newcommand*{\tugtextformat}[1]{%
28625 \glsxtrentryfmt{\glslabel}{#1}%
28626 }
28627
28628 \newcommand*{\tugnameformat}[1]{%
28629 \glsxtrentryfmt{\glscurrententrylabel}{#1}%
28630 }
28631
28632 \glssetcategoryattribute{tug}{textformat}{tugtextformat}
28633 \glssetcategoryattribute{tug}{glossnamefont}{tugnameformat}
28634
28635 \newcommand{\glsxtrpostnametug}{%
28636 \ifglshasdesc{\glscurrententrylabel}%
28637 {\ (\glossentrydesc{\glscurrententrylabel}%
28638 \glsxtrifhasfield{translation}{\glscurrententrylabel}%
28639 {, \textenglish{\glscurrentfieldvalue}}%
28640 {}%
28641 )}%
28642 {%
28643 \glsxtrifhasfield{translation}{\glscurrententrylabel}%
28644 {\ (\textenglish{\glscurrentfieldvalue})}%
28645 {}%
28646 }%
28647 }
28648
28649 \begin{document}
28650 \chapter{Sample}
28651 \section{First Use}
28652 \gls{TUG}. \gls{bgTeX}. \gls{latex-br}. \gls{CTeX}.
28653 \gls{CSTUG}. \gls{DANTE}. \gls{DKTUG}. \gls{EUG}.
28654 \gls{CervanTeX}. \gls{TirantloTeX}. \gls{GUTenberg}.
28655 \gls{UKTUG}. \gls{|\greekmono ɛϕτ|}. \gls{MaTeX}. \gls{ITALIC}.
28656 \gls{ÍsTeX}. \gls{GuIT}. \gls{KTS}. \gls{LTVG}.
28657 \gls{mxTeX}. \gls{NTG}. \gls{NTUG}. \gls{GUST}. \gls{GUTpt}.
28658 \gls{VietTUG}. \gls{LUGSA}.
28659
28660 \section{Next Use}
28661
28662 \gls{TUG}. \gls{bgTeX}. \gls{latex-br}. \gls{CTeX}.
28663 \gls{CSTUG}. \gls{DANTE}. \gls{DKTUG}. \gls{EUG}.
28664 \gls{CervanTeX}. \gls{TirantloTeX}. \gls{GUTenberg}.
28665 \gls{UKTUG}. \gls{|\greekmono ɛϕτ|}. \gls{MaTeX}. \gls{ITALIC}.
28666 \gls{ÍsTeX}. \gls{GuIT}. \gls{KTS}. \gls{LTVG}.
28667 \gls{mxTeX}. \gls{NTG}. \gls{NTUG}. \gls{GUST}. \gls{GUTpt}.
28668 \gls{VietTUG}. \gls{LUGSA}.
28669
28670 \printunsrtglossaries
28671 \end{document}
28672 \end{lstlisting}
28673
28674 \begin{figure}
28675 \figcontents
28676 {\pdftwocol{../examples/sample-usergroups.pdf}{2}}
28677 {\caption{\filefmt{sample-usergroups.pdf}}}
28678 {fig:sample-usergroups.pdf}
28679 \end{figure}
28680
28681 \filesection{sample-multi1.tex}
28682
28683 This example uses \exfile{bacteria.bib},
28684 \exfile{markuplanguages.bib}, \exfile{vegetables.bib}, \exfile{minerals.bib},
28685 \exfile{animals.bib}, \exfile{chemicalformula.bib},
28686 \exfile{baseunits.bib} and \exfile{derivedunits.bib}.
28687 Since there's one or more UTF-8 character, the document requires
28688 UTF-8 support:
28689 \begin{verbatim}
28690 \usepackage[T1]{fontenc}
28691 \usepackage[utf8]{inputenc}
28692 \end{verbatim}
28693
28694 The aim of this example document is to have a separate glossary
28695 (without number lists) for each type of data (bacteria, markup
28696 languages, vegetables, minerals, animals, chemical formula, base
28697 units and derived units) and also an
28698 index listing all referenced entries with number lists as well as
28699 aliased entries that haven't explicitly been used but the
28700 cross-reference term as been indexed. This requires:
28701 \begin{codeenv}
28702 \csopt[recorded and deps and see]{selection}
28703 \end{codeenv}
28704 to ensure the aliased entries are selected.
28705
28706 Since I don't need the default \mainglossary\ (I'm providing
28707 my own custom glossaries) I've used the \styopt{nomain} option to
28708 suppress its automatic creation, but I do want the \code{index}
28709 glossary so I've used the \styopt{index} package option. As with the
28710 other examples, I've used \styopt{nostyles} to suppress the creation
28711 of the default styles and used \styopt{stylemods} to load the
28712 particular style packages that I need and use
28713 \sty{glossaries-extra-stylemods} to patch them. The index needs to
28714 be in an unnumbered chapter, which is the default for book-like
28715 styles, but I want the other glossaries in unnumbered sections so
28716 I've used the \styopt{section} option. I just need to remember to
28717 switch this before displaying the index:
28718 \begin{codeenv}
28719 \cmd{usepackage}\oarg{\styopt{record},\comment{use bib2gls}
28720 \styopt{section},\comment{use \ics{section*} for glossary headings}
28721 \styopt{postdot},\comment{insert dot after descriptions in glossaries}
28722 \styopt{nomain},\comment{don't create 'main' glossary}
28723 \styopt{index},\comment{create 'index' glossary}
28724 \styopt{nostyles},\comment{don't load default styles}
28725 \comment{load and patch required style packages:}
28726 \styopt[list,mcols,tree,bookindex]{stylemods}
28727 }\marg{glossaries-extra}
28728 \end{codeenv}
28729 The remaining glossaries need defining:
28730 \begin{codeenv}
28731 \cs{newglossary*}\marg{bacteria}\marg{Bacteria}
28732 \cs{newglossary*}\marg{markuplanguage}\marg{Markup Languages}
28733 \cs{newglossary*}\marg{vegetable}\marg{Vegetables}
28734 \cs{newglossary*}\marg{mineral}\marg{Minerals}
28735 \cs{newglossary*}\marg{animal}\marg{Animals}
28736 \cs{newglossary*}\marg{chemical}\marg{Chemical Formula}
28737 \cs{newglossary*}\marg{baseunit}\marg{SI Units}
28738 \cs{newglossary*}\marg{derivedunit}\marg{Derived Units}
28739 \end{codeenv}
28740 As with \exfile{sample-bacteria.tex} and \exfile{sample-markuplanguages.tex}
28741 I need to set the abbreviation styles before the abbreviations are
28742 defined:
28743 \begin{codeenv}
28744 \cs{setabbreviationstyle}\oarg{bacteria}\marg{\abbrstyle{long-only-short-only}}
28745 \cs{setabbreviationstyle}\oarg{markuplanguage}\marg{\abbrstyle{long-short-desc}}
28746 \end{codeenv}
28747 Unlike the \exfile{sample-markuplanguages.tex} example, I'm not interested
28748 in tagging the initials in this case, but I still want to change the
28749 way the \field{name} field is set with the
28750 \abbrstyle{long-short-desc} abbreviation style:
28751 \begin{codeenv}
28752 \cs{renewcommand}*\marg{\cs{glsxtrlongshortdescname}}\marg{\comment{}
28753 \cs{protect}\cs{glsabbrvfont}\marg{\cs{the}\cs{glsshorttok}}\cs{space}
28754 \cs{glsxtrparen}\marg{\cs{glslongfont}\marg{\cs{the}\cs{glslongtok}}}\comment{}
28755 }
28756 \end{codeenv}
28757 Remember that this also needs to be set before the abbreviations are
28758 defined. The \catattr{textformat} and \catattr{glossnamefont}
28759 attributes may be set after definition:
28760 \begin{codeenv}
28761 \cs{newcommand}\marg{\cmd{bacteriafont}}[1]\marg{\cs{emph}\marg{\idx{param}1}}
28762 \cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{textformat}}\marg{bacteriafont}
28763 \cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{glossnamefont}}\marg{bacteriafont}
28764 \end{codeenv}
28765 The description font also needs to be set since this will contain
28766 the long form:
28767 \begin{codeenv}
28768 \cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{glossdescfont}}\marg{bacteriafont}
28769 \end{codeenv}
28770
28771 The \code{markuplanguage} glossary contains descriptions and some
28772 long names, so it's better suited to the \glostyle{altlist} style,
28773 in which case the descriptions would look better if they started
28774 with a capital letter:
28775 \begin{codeenv}
28776 \cs{glssetcategoryattribute}\marg{markuplanguage}\marg{\catattr{glossdesc}}\marg{firstuc}
28777 \end{codeenv}
28778 Remember that the \glostyle{altlist} style uses the
28779 \env{description} environment, which is governed by the document
28780 class (and may be modified by list-related packages). In this case,
28781 one of the KOMA-Script classes is used, so the list items are
28782 typeset in sans-serif.
28783
28784 There are various ways of dealing with the duplicated data in the
28785 index, such as using the \csopt{secondary} option or having a
28786 separate resource set with a copy \csopt{action}. In this case, I've
28787 decided to use a dual entry system. Since the entries aren't defined
28788 using any dual types, I've used \csopt{entry-type-aliases} to
28789 make \bibgls\ treat them as though they were, and I also need to
28790 alias the custom \atentryfmt{chemical}, \atentryfmt{unit} and
28791 \atentryfmt{measurement} \glspl{entrytype}:
28792 \begin{codeenv}
28793 \csopt[
28794 abbreviation=dualindexabbreviation,
28795 entry=dualindexentry,
28796 symbol=dualindexsymbol,
28797 unit=dualindexsymbol,
28798 measurement=dualindexsymbol,
28799 chemical=dualindexsymbol
28800 ]{entry-type-aliases}
28801 \end{codeenv}
28802 Note that I haven't aliased the \atentry{index} types as I only want
28803 these in the index and not replicated in a separate glossary.
28804
28805 The primary entries for the \atentry{dualindexabbreviation} type
28806 ignore the short form. It would be useful to store it. This could be
28807 done by copying the \field{short} field with
28808 \csopt{replicate-fields}. For example,
28809 \csopt[\field{short}=\field{symbol}]{replicate-fields}. However, this will cause the
28810 \field{symbol} field to be set for both the primary and dual
28811 entries, which will cause an unwanted duplication if the dual
28812 entries are displayed using a glossary style that shows the
28813 \field{symbol} field. Another field (such as \field{user1}) could be
28814 used instead or \gls{bibglsnewdualindexabbreviation} could be
28815 defined before \gls{GlsXtrLoadResources}:
28816 \begin{codeenv}
28817 \cs{newcommand}\marg{\gls{bibglsnewdualindexabbreviation}}[7]\marg{\comment{}
28818 \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\comment{}
28819 \field{name}=\marg{\cs{protect}\gls{bibglsuselongfont}\marg{\idx{param}4}\marg{\cs{glscategory}\marg{\idx{param}2}}},\comment{}
28820 \field{symbol}=\marg{\cs{protect}\gls{bibglsuseabbrvfont}\marg{\idx{param}5}\marg{\cs{glscategory}\marg{\idx{param}2}}},\comment{}
28821 \field{category}=\marg{index},\idx{param}3}\marg{}\comment{}
28822 }
28823 \end{codeenv}
28824 However, this will affect all \atentry{dualindexabbreviation}
28825 \glspl{entrytype}, but it's not necessary for the bacteria abbreviations.
28826 Instead it's simpler to just keep a record of the dual label so that
28827 the short form can be obtained from the dual entry:
28828 \begin{codeenv}
28829 \csopt{dual-field}
28830 \end{codeenv}
28831
28832 By default, the \atentry{dualindexabbreviation} \gls{entrytype} falls back on the
28833 \field{short} field if the \field{name} is omitted. In this case I
28834 want it to fall back on the \field{long} field instead.
28835 \begin{codeenv}
28836 \csopt[long]{abbreviation-name-fallback}
28837 \end{codeenv}
28838 Remember that the sort fallback for abbreviations is still \field{short} (but can be
28839 changed with \csopt{abbreviation-sort-fallback}), but I've changed
28840 the sort fallback for symbols:
28841 \begin{codeenv}
28842 \csopt[name]{symbol-sort-fallback}
28843 \end{codeenv}
28844 I also need to alias the custom fields (especially for those in the
28845 \exfile{chemicalformula.bib}, \exfile{baseunits.bib} and
28846 \exfile{derivedunits.bib} files):
28847 \begin{codeenv}
28848 \csopt[
28849 \fieldfmt{identifier}=\field{category},
28850 \fieldfmt{formula}=\field{symbol},
28851 \fieldfmt{chemicalname}=\field{name},
28852 \fieldfmt{unitname}=\field{name},
28853 \fieldfmt{unitsymbol}=\field{symbol},
28854 \fieldfmt{measurement}=\field{description}
28855 ]{field-aliases}
28856 \end{codeenv}
28857 There's a slight problem here. This ensures that the entries defined
28858 in \exfile{chemicalformula.bib} have a \field{name} and
28859 \field{symbol} field, which are swapped round for the dual
28860 (according to the default \csopt{dual-indexsymbol-map}) but these
28861 entries don't have a \field{description} field. Since I'd like to
28862 use the \glostyle{mcolalttreegroup} style, this will end up with
28863 the odd appearance of the formula (stored in the \field{name} field for the
28864 dual) followed by the chemical name (stored in the \field{symbol}
28865 field for the dual) in parenthesis. This is the default \meta{name}
28866 (\meta{symbol}) \meta{description} format for the style. I've fixed
28867 this by locally redefining \ics{glsxtralttreeSymbolDescLocation} for
28868 just that glossary:
28869 \begin{codeenv}
28870 \cs{printunsrtglossary*}\oarg{\printglossopt[chemical]{type},\printglossopt[mcolalttreegroup]{style}}
28871 \marg{\comment{}
28872 \cs{renewcommand}\cs{glsxtralttreeSymbolDescLocation}[2]\marg{\comment{}
28873 \ics{glossentrysymbol}\marg{\idx{param}1}\cs{glspostdescription}\ics{glsxtrAltTreePar}
28874 }\comment{}
28875 \cs{renewcommand}*\marg{\cs{glstreenamefmt}}[1]\marg{\idx{param}1}\comment{}
28876 \cs{renewcommand}*\marg{\cs{glstreegroupheaderfmt}}[1]\marg{\cs{textbf}\marg{\idx{param}1}}\comment{}
28877 }
28878 \end{codeenv}
28879 I've also redefined \cs{glstreenamefmt} to prevent the names
28880 appearing in bold, which means I also need to redefine
28881 \cs{glstreegroupheaderfmt} to keep the headers bold.
28882
28883 All the \atentryfmt{dualindex\meta{type}} \glspl{entrytype} provide a primary
28884 entry that behaves like \atentry{index}. The secondary behaves like
28885 \atentryfmt{\meta{type}}. This means that the primaries are
28886 conveniently gathered together with all the unaliased \atentry{index}
28887 entries, so the primary \gls{entrytype} needs to be set to \code{index}:
28888 \begin{codeenv}
28889 \csopt[index]{type}
28890 \end{codeenv}
28891 The dual \gls{entrytype} depends on the entry's category. Since I've
28892 defined my custom glossaries with a label that matches the
28893 custom \fieldfmt{identifier} field, I can both alias this custom field
28894 to the \field{category} field and also set \csopt{dual-type} so that
28895 it matches the category:
28896 \begin{codeenv}
28897 \csopt[\fieldfmt{identifier}=\field{category}]{field-aliases},
28898 \csopt[same as category]{dual-type}
28899 \end{codeenv}
28900 The primary entries (in the \code{index} glossary) need to be sorted
28901 alphabetically, and since the document is in English I'm sorting
28902 according to that language (identified by the language code
28903 \code{en}), but I also want to make sure that all the primary
28904 entries are sorted by the \field{name} field to avoid discrepancies
28905 in the fallback value for the \field{sort} field:
28906 \begin{codeenv}
28907 \csopt[en]{sort},
28908 \csopt[name]{sort-field}
28909 \end{codeenv}
28910 With \csopt[long]{abbreviation-name-fallback} now set,
28911 this means that \emph{Coxiella burnetii} comes after
28912 \emph{Clostridium tetani} in the index. I haven't changed the sort
28913 field for the dual entries, so in that case the
28914 \csopt{abbreviation-sort-fallback} and \csopt{symbol-sort-fallback}
28915 settings will be used with the duals. This means that
28916 \emph{C.\ burnetii} is between \emph{C.\ botulinum} and \emph{C.\
28917 perfringens} rather than after \emph{C.\ tetani}.
28918
28919 I'd like to sort the dual entries according to a letter-number rule
28920 (as for the above \exfile{sample-chemical.tex} and \exfile{sample-units3.tex}
28921 examples)
28922 but this would order \qt{b\'ilinite} after \qt{biotite} in the
28923 \code{minerals} glossary, so instead I'm also using the English sort
28924 rule for the duals, but with the numbers padded:
28925 \begin{codeenv}
28926 \csopt[en]{dual-sort},
28927 \csopt[2]{dual-sort-number-pad},
28928 \end{codeenv}
28929 This method doesn't work as well as the method used in
28930 \exfile{sample-chemical.tex} as it doesn't separate the capitals,
28931 digits and \idx!{lowercase} characters in the way that can be achieved with the
28932 letter-number methods. An improvement can be made by changing the
28933 break-points. I could use \csopt[upper-upper]{dual-break-at} but
28934 this would put \qt{seal} before \qt{sea lion} in the \code{animal}
28935 glossary, so instead I've used:
28936 \begin{codeenv}
28937 \csopt[upper-upper-word]{dual-break-at}
28938 \end{codeenv}
28939 This now puts \qt{sea lion} before \qt{seal}. Unfortunately the word
28940 break points will cause a break at the markers used to indicate
28941 positive and negative numbers that are inserted with
28942 \csopt{dual-sort-number-pad}, so these need to be changed to
28943 something that won't cause them to be discarded:
28944 \begin{codeenv}
28945 \csopt[0]{dual-sort-pad-minus},
28946 \csopt[1]{dual-sort-pad-plus}
28947 \end{codeenv}
28948
28949 The document loads \sty{hyperref} which means that all the \cs{gls}
28950 references will create hyperlinks. Since the primaries are in the
28951 index, the default prefixes mean that, for example,
28952 \code{\cs{gls}\marg{svg}} links to the \qt{scalable vector graphics} item in
28953 the index rather than to the abbreviation \qt{SVG} in the
28954 \code{markuplanguage} glossary. There are two alternatives: change
28955 \code{\cs{gls}\marg{svg}} to \code{\cs{gls}\marg{dual.svg}} or change the
28956 default prefixes, which is the more convenient approach and is the one used
28957 here:
28958 \begin{codeenv}
28959 \csopt[idx.]{label-prefix},
28960 \csopt[\empty]{dual-prefix}
28961 \end{codeenv}
28962 Now \code{\cs{gls}\marg{svg}} refers to the dual abbreviation \qt{SVG} and
28963 \code{\cs{gls}\marg{idx.svg}} refers to the primary entry \qt{scalable vector
28964 graphics}. Unfortunately this means that the records created with
28965 \code{\cs{gls}\marg{svg}} now refer to the dual abbreviation and will end up
28966 being displayed in the glossary instead of the index. This can be
28967 fixed with:
28968 \begin{codeenv}
28969 \csopt[primary]{combine-dual-locations}
28970 \end{codeenv}
28971 Which transfers the dual entry \glspl{location} to the corresponding
28972 primary.
28973
28974 The other problem is the cross-references in the \field{description}
28975 fields. Since the labels don't start with \qt{\idprefix{dual}} \bibgls\
28976 will assume they refer to the primary entries, which means that
28977 \qt{\idprefixfmt{idx}} (the value of \csopt{label-prefix}) will be
28978 inserted. This means that they'll link to the index rather than the
28979 glossary entry. It also means that the cross-references where the
28980 dual is an abbreviation won't behave like an abbreviation as the
28981 reference is to the primary (non-abbreviation) entry. This can be
28982 fixed by setting \csopt{cs-label-prefix} to the same value as
28983 \csopt{dual-prefix}:
28984 \begin{codeenv}
28985 \csopt[\empty]{cs-label-prefix}
28986 \end{codeenv}
28987 The index is displayed using the \glostyle{bookindex} style. This
28988 doesn't show the description or symbol by default, but it would be
28989 useful to include the symbol in parentheses after the name. This can
28990 be done by redefining \ics{glsxtrbookindexname}:
28991 \begin{codeenv}
28992 \cs{renewcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\comment{}
28993 \cs{glossentryname}\marg{\idx{param}1}\comment{}
28994 \cs{ifglshassymbol}\marg{\idx{param}1}\marg{\cs{space}(\cs{glossentrysymbol}\marg{\idx{param}1})}\marg{}\comment{}
28995 }
28996 \end{codeenv}
28997 However the chemical forumlae look a little odd in parentheses
28998 (especially those that contain parenthetical parts) but this can be
28999 fixed by adding a category check:
29000 \begin{codeenv}
29001 \cs{renewcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\comment{}
29002 \cs{glossentryname}\marg{\idx{param}1}\comment{}
29003 \cs{ifglshassymbol}\marg{\idx{param}1}\comment{}
29004 \marg{\comment{}
29005 \cs{glsifcategory}\marg{\idx{param}1}\marg{chemical}\comment{}
29006 \marg{, \cs{glossentrysymbol}\marg{\idx{param}1}}\comment{}
29007 \marg{\cs{space}(\cs{glossentrysymbol}\marg{\idx{param}1})}\comment{}
29008 }\comment{}
29009 \marg{}\comment{}
29010 }
29011 \end{codeenv}
29012 Unfortunately \ics{glossentrysymbol} doesn't pick up the
29013 \catattr{glossnamefont} attribute, so if the short form of the
29014 abbreviations is saved in the \field{symbol} field, using one of the
29015 methods discussed above, then the custom \csfmt{bacteriafont} won't
29016 be applied. (As from \sty{glossaries-extra} version 1.42, there is
29017 now the \catattr{glosssymbolfont} attribute that's used by
29018 \ics{glossentrysymbol}.)
29019
29020 A simple solution is to use \ics{glossentrynameother} instead:
29021 \begin{codeenv}
29022 \cs{renewcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\comment{}
29023 \cs{glossentryname}\marg{\idx{param}1}\comment{}
29024 \cs{ifglshassymbol}\marg{\idx{param}1}\comment{}
29025 \marg{\comment{}
29026 \cs{glsifcategory}\marg{\idx{param}1}\marg{chemical}\comment{}
29027 \marg{, \cs{glossentrysymbol}\marg{\idx{param}1}}\comment{}
29028 \marg{\cs{space}(\cs{glossentrynameother}\marg{\idx{param}1}\marg{\field{symbol}})}\comment{}
29029 }\comment{}
29030 \marg{}\comment{}
29031 }
29032 \end{codeenv}
29033 However, since I decided not to store the short form in the
29034 \field{symbol} field and just saved the dual entry label instead, I
29035 need to lookup the short form from the dual entry:
29036 \begin{codeenv}
29037 \cs{renewcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\comment{}
29038 \cs{glossentryname}\marg{\idx{param}1}\comment{}
29039 \cs{ifglshassymbol}\marg{\idx{param}1}\comment{}
29040 \marg{\comment{}
29041 \cs{glsifcategory}\marg{\idx{param}1}\marg{chemical}\comment{}
29042 \marg{, \ics{glossentrysymbol}\marg{\idx{param}1}}\comment{}
29043 \marg{\cs{space}(\ics{glossentrynameother}\marg{\idx{param}1}\marg{\field{symbol}})}\comment{}
29044 }\comment{}
29045 \marg{\comment{}
29046 \cs{glsifcategory}\marg{\idx{param}1}\marg{markuplanguage}\comment{}
29047 \marg{\comment{}
29048 \cs{glsxtrifhasfield}\marg{\field{short}}\marg{\cs{glsxtrusefield}\marg{\idx{param}1}\marg{\field{dual}}}\comment{}
29049 \marg{\cs{space}(\cs{glscurrentfieldvalue})}\comment{}
29050 \marg{}\comment{}
29051 }\comment{}
29052 \marg{}\comment{}
29053 }\comment{}
29054 }
29055 \end{codeenv}
29056 Not all of the markup languages are abbreviations so this uses
29057 \ics{glsxtrifhasfield} to check if the \field{short} field is set.
29058 The dual entry's label is easily obtained because \csopt{dual-field}
29059 has provided the \fieldfmt{dual} internal field and set it to the
29060 corresponding label.
29061
29062 It's sometimes useful for the index to include a reference to the
29063 term's definition. This can be done by making use of
29064 \idx{glsextrapostnamehook}, which can be redefined before the
29065 glossaries to automatically record each entry:
29066 \begin{codeenv}
29067 \cs{renewcommand}\marg{\cs{glsextrapostnamehook}}[1]\marg{\cs{glsadd}\oarg{\glsaddopt[\encap{hyperbf}]{format}}\marg{\idx{param}1}}
29068 \end{codeenv}
29069 This needs to be redefined to ignore its argument before the index,
29070 to avoid the redundant index record:
29071 \begin{codeenv}
29072 \cs{renewcommand}\marg{\cs{glsextrapostnamehook}}[1]\marg{}
29073 \end{codeenv}
29074 Remember that if any records are added within a glossary, an extra
29075 \LaTeX\ and \bibgls\ call are required to ensure that the \gls{locationlist}
29076 is correct, so the document build is:
29077 \begin{verbatim}
29078 pdflatex sample-multi1
29079 bib2gls --group sample-multi1
29080 pdflatex sample-multi1
29081 bib2gls --group sample-multi1
29082 pdflatex sample-multi1
29083 \end{verbatim}
29084 The complete document code is listed below.
29085 The resulting document is shown in \figureref{fig:sample-multi1.pdf}
29086 and \figureref{fig:sample-multi1.pdf2}.
29087
29088 \lstinputlisting[firstline=5]{../examples/sample-multi1.tex}
29089
29090 \begin{figure}
29091 \figcontents
29092 {\pdftwocol{../examples/sample-multi1.pdf}{4}}
29093 {\caption{\filefmt{sample-multi1.pdf} (pages~1 to~4)}}
29094 {fig:sample-multi1.pdf}
29095 \end{figure}
29096
29097 \begin{figure}
29098 \figcontents
29099 {\pdftwocol[5]{../examples/sample-multi1.pdf}{8}}
29100 {\caption{\filefmt{sample-multi1.pdf} (pages~5 to 8)}}
29101 {fig:sample-multi1.pdf2}
29102 \end{figure}
29103
29104 \filesection{sample-multi2.tex}
29105
29106 This example is an alternative approach to
29107 \exfile{sample-multi1.tex}. Instead of using dual \glspl{entrytype} to
29108 define entries that appear in both a glossary and the index, this
29109 example makes use of \csopt{record-label-prefix} to reselect the
29110 recorded entries for the index. This is more complicated but it
29111 allows the entries that have natural word ordering to use a locale
29112 sort method while the entries that are symbolic can use one of the
29113 letter-number sort methods.
29114
29115 This document uses some additional \ext{bib} files to the previous
29116 example, so it has extra glossaries, which all need to be defined:
29117 \begin{codeenv}
29118 \cs{newglossary*}\marg{bacteria}\marg{Bacteria}
29119 \cs{newglossary*}\marg{markuplanguage}\marg{Markup Languages}
29120 \cs{newglossary*}\marg{vegetable}\marg{Vegetables}
29121 \cs{newglossary*}\marg{mineral}\marg{Minerals}
29122 \cs{newglossary*}\marg{animal}\marg{Animals}
29123 \cs{newglossary*}\marg{chemical}\marg{Chemical Formula}
29124 \cs{newglossary*}\marg{baseunit}\marg{SI Units}
29125 \cs{newglossary*}\marg{measurement}\marg{Measurements}
29126 \cs{newglossary*}\marg{film}\marg{Films}
29127 \cs{newglossary*}\marg{book}\marg{Books}
29128 \cs{newglossary*}\marg{person}\marg{People}
29129 \cs{newglossary*}\marg{mediacontrol}\marg{Media Control Symbols}
29130 \cs{newglossary*}\marg{information}\marg{Information Symbols}
29131 \cs{newglossary*}\marg{weather}\marg{Weather Symbols}
29132 \end{codeenv}
29133 Note that this is a total of 15~glossaries (including the
29134 \code{index}). With the basic \ics{cs.makeglossaries} method, this would
29135 require 16 write registers (including the write register used to
29136 create the indexing style file), and a total of $15\times3 + 1 = 46$
29137 associated files. (This doesn't include the standard \ext{aux} file
29138 or the \iext{out} file created by \sty{hyperref}.) With \bibgls, no
29139 additional write registers are required and the number of associated
29140 \bibgls\ files is equal to the number of resource commands plus the
29141 transcript file (in this example, $9+1=10$).
29142
29143 Since this document requires \exfile!{people.bib}, \exfile!{books.bib}
29144 and \exfile!{films.bib} it also requires the files that
29145 supply the definitions of the custom commands
29146 (\exfile!{no-interpret-preamble.bib} and either
29147 \exfile!{interpret-preamble.bib} or \exfile!{interpret-preamble2.bib})
29148 to ensure the custom commands are provided both for the document and
29149 for \bibgls's interpreter.
29150
29151 The first resource set to be loaded simply reads
29152 \exfile{no-interpret-preamble.bib} with the preamble interpreter
29153 switched off:
29154 \begin{codeenv}
29155 \gls{GlsXtrLoadResources}\oarg{
29156 \csopt[no-interpret-preamble]{src},
29157 \csopt[false]{interpret-preamble}
29158 }
29159 \end{codeenv}
29160 This ensures that \LaTeX\ can pick up the provided commands and
29161 prevents them from being added to the interpreter.
29162
29163 The \exfile{people.bib} file is the next to be loaded with
29164 \exfile{interpret-preamble.bib}. This is loaded separately from the
29165 other resources as this needs the \field{name} field to be copied to
29166 \field{first} (if not already set), as in the
29167 \exfile{sample-people.tex} file. By having a separate resource set,
29168 this setting doesn't affect the other entries. I've also converted
29169 the date fields so that I can customise the format in the document.
29170 \begin{codeenv}
29171 \gls{GlsXtrLoadResources}\oarg{
29172 \csopt[interpret-preamble,people]{src},
29173 \csopt[
29174 \fieldfmt{identifier}=\field{category},
29175 \fieldfmt{born}=\field{user1},
29176 \fieldfmt{died}=\field{user2},
29177 \fieldfmt{othername}=\field{user3}
29178 ]{field-aliases},
29179 \csopt[\field{name}=\marg{\field{first}}]{replicate-fields},
29180 \csopt[person]{type},
29181 \csopt[false]{save-locations}
29182 \csopt[\field{user1},\field{user2}]{date-fields},
29183 \csopt[d MMM y G]{date-field-format}
29184 }
29185 \end{codeenv}
29186 As with the \exfile{sample-people.tex} document, I need to use the
29187 \longarg{break-space} switch to convert the \idx{nbspchar} to a
29188 normal breakable space so that it matches the given format. I've
29189 loaded the \sty{datetime2} package:\footnote{The
29190 \styoptfmt{en-GB} option to \sty{datetime2} also requires that
29191 \styfmt{datetime2-english} must be installed.}
29192 \begin{verbatim}
29193 \usepackage[en-GB]{datetime2}
29194 \end{verbatim}
29195 so that I can use \ics{DTMdisplaydate} to adjust the formatting:
29196 \begin{codeenv}
29197 \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}}
29198 \end{codeenv}
29199 This needs to go before the \idx{resourceset} is loaded. Note that
29200 the \styoptfmt{en-GB} option identifies the document locale as
29201 \code{en-GB} (since there are no language packages loaded).
29202
29203 Note that unlike \exfile{sample-people.tex} which had
29204 \csopt[people]{category}, this document obtains the \field{category} field
29205 from the custom \fieldfmt{identifier} field, which in this case
29206 has the value \code{person}. This means that the category hooks from
29207 \exfile{sample-people.tex} need to be renamed to reflect the
29208 different category label:
29209 \begin{codeenv}
29210 \cs{newcommand}*\marg{\postlinkhook{person}}{\comment{}
29211 \cs{glsxtrifwasfirstuse}
29212 \marg{\comment{}
29213 \cs{ifglshasfield}\marg{\field{user3}}\marg{\cs{glslabel}}\comment{}
29214 \marg{\cs{space}(\cs{glscurrentfieldvalue})}\comment{}
29215 \marg{}\comment{}
29216 }\comment{}
29217 \marg{}\comment{}
29218 }
29219 \strut
29220 \cs{newcommand}*\marg{\postnamehook{person}}\marg{\comment{}
29221 \cs{ifglshasfield}\marg{\field{user3}}\marg{\cs{glscurrententrylabel}}\comment{}
29222 \marg{\cs{space}(\cs{glscurrentfieldvalue})}\comment{}
29223 \marg{}\comment{}
29224 }
29225 \strut
29226 \cs{newcommand}*\marg{\postdeschook{person}}\marg{\comment{}
29227 \cs{ifglshasfield}\marg{\field{user1}}\marg{\cs{glscurrententrylabel}}
29228 \marg{\comment{born}
29229 \cs{space}(\cs{glscurrentfieldvalue}\cs{comma}-{}-\cs{comma}\comment{}
29230 \cs{ifglshasfield}\marg{\field{user2}}\marg{\cs{glscurrententrylabel}}
29231 \marg{\comment{died}
29232 \cs{glscurrentfieldvalue}
29233 }\comment{}
29234 \marg{}\comment{}
29235 )\comment{}
29236 }\comment{}
29237 \marg{}\comment{}
29238 }
29239 \end{codeenv}
29240 The other \ext{bib} files that require locale sorting can now be
29241 loaded, but remember that the abbreviation style settings must be
29242 set first since this resource set includes abbreviations:
29243 \begin{codeenv}
29244 \cs{setabbreviationstyle}\oarg{bacteria}\marg{\abbrstyle{long-only-short-only}}
29245 \cs{setabbreviationstyle}\oarg{markuplanguage}\marg{\abbrstyle{long-short-desc}}
29246 \strut
29247 \cs{renewcommand}*\marg{\cs{glsxtrlongshortdescname}}\marg{\comment{}
29248 \cs{protect}\cs{glsabbrvfont}\marg{\cs{the}\cs{glsshorttok}}\cs{space}
29249 \glsxtrparen{\glslongfont{\the\glslongtok}}%
29250 }
29251 \end{codeenv}
29252 Now the resource set can be loaded:
29253 \begin{codeenv}
29254 \gls{GlsXtrLoadResources}\oarg{
29255 \csopt[bacteria,markuplanguages,vegetables,
29256 minerals,animals,books,films]{src},
29257 \csopt[\fieldfmt{identifier}=\field{category}]{field-aliases},
29258 \csopt[same as category]{type},
29259 \csopt[false]{save-locations}
29260 }
29261 \end{codeenv}
29262 The semantic markup command and attributes are as for
29263 \exfile{sample-multi1.tex}:
29264 \begin{codeenv}
29265 \cs{newcommand}\marg{\cmd{bacteriafont}}[1]\marg{\cs{emph}\marg{\idx{param}1}}
29266 \cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{textformat}}\marg{bacteriafont}
29267 \cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{glossnamefont}}\marg{bacteriafont}
29268 \cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{glossdescfont}}\marg{bacteriafont}
29269 \cs{glssetcategoryattribute}\marg{markuplanguage}\marg{\catattr{glossdesc}}\marg{firstuc}
29270 \end{codeenv}
29271 Similarly for the books:
29272 \begin{codeenv}
29273 \cs{newcommand}\marg{\cmd{bookfont}}[1]\marg{\cs{emph}\marg{\idx{param}1}}
29274 \cs{glssetcategoryattribute}\marg{book}\marg{\catattr{textformat}}\marg{bookfont}
29275 \cs{glssetcategoryattribute}\marg{book}\marg{\catattr{glossnamefont}}\marg{bookfont}
29276 \end{codeenv}
29277 (as for \exfile{sample-media.tex}) and for films:
29278 \begin{codeenv}
29279 \cs{newcommand}\marg{\cmd{filmfont}}[1]\marg{\cs{emph}\marg{\idx{param}1}}
29280 \cs{glssetcategoryattribute}\marg{film}\marg{\catattr{textformat}}\marg{filmfont}
29281 \cs{glssetcategoryattribute}\marg{film}\marg{\catattr{glossnamefont}}\marg{filmfont}
29282 \end{codeenv}
29283
29284 Next come the chemical formulae:
29285 \begin{codeenv}
29286 \gls{GlsXtrLoadResources}\oarg{
29287 \csopt[chemicalformula]{src},
29288 \csopt[chemical=symbol]{entry-type-aliases},
29289 \csopt[
29290 \fieldfmt{identifier}=\field{category},
29291 \fieldfmt{formula}=\field{name},
29292 \fieldfmt{chemicalname}=\field{description}
29293 ]{field-aliases},
29294 \csopt[chemical]{type},
29295 \csopt{set-widest},
29296 \csopt[letternumber-case]{sort},
29297 \csopt[\field{name}]{symbol-sort-fallback},
29298 \csopt[false]{save-locations}
29299 }
29300 \end{codeenv}
29301 and the \idxpl{SIunit}, which are now combined into a single
29302 glossary:
29303 \begin{codeenv}
29304 \gls{GlsXtrLoadResources}\oarg{
29305 \csopt[baseunits,derivedunits]{src},
29306 \csopt[\fieldfmt{measurement}=\field{symbol},\fieldfmt{unit}=\field{symbol}]{entry-type-aliases},
29307 \csopt[
29308 \fieldfmt{unitname}=\field{description},
29309 \fieldfmt{unitsymbol}=\field{symbol},
29310 \fieldfmt{measurement}=\field{name}
29311 ]{field-aliases},
29312 \csopt[measurement]{category},
29313 \csopt[measurement]{type},
29314 \csopt{set-widest},
29315 \csopt[\field{name}]{symbol-sort-fallback},
29316 \csopt[false]{save-locations}
29317 }
29318 \end{codeenv}
29319 Here the \field{name} field is obtained from the custom
29320 \fieldfmt{measurement} field. Since this contains a word, the
29321 default locale sort is appropriate. I've locally redefined
29322 \ics{glsxtralttreeSymbolDescLocation} to place the symbol in
29323 parentheses after the description:
29324 \begin{codeenv}
29325 \cs{printunsrtglossary*}\oarg{\printglossopt[measurement]{type},\printglossopt[alttree]{style},\printglossopt{nogroupskip}}
29326 \marg{\comment{}
29327 \cs{renewcommand}\marg{\cs{glsxtralttreeSymbolDescLocation}}[2]\marg{\comment{}
29328 \cs{glossentrydesc}\marg{\idx{param}1}\comment{}
29329 \cs{ifglshassymbol}\marg{\idx{param}1}\marg{\cs{space}(\cs{glossentrysymbol}\marg{\idx{param}1})}\marg{}\comment{}
29330 \cs{glspostdescription}
29331 \cs{glsxtrAltTreePar}
29332 }\comment{}
29333 }
29334 \end{codeenv}
29335
29336 The base units are replicated in the \code{baseunit} glossary, this
29337 time with the \field{name} field obtained from the custom
29338 \fieldfmt{unitsymbol} field. This means that I need to find a way to
29339 prevent duplicate labels. The simplest method is to use
29340 \csopt{duplicate-label-suffix}:
29341 \begin{codeenv}
29342 \gls{GlsXtrLoadResources}\oarg{
29343 \csopt[baseunits]{src},
29344 \csopt[unit=symbol]{entry-type-aliases},
29345 \csopt[
29346 \fieldfmt{unitname}=\field{description},
29347 \fieldfmt{unitsymbol}=\field{name}
29348 ]{field-aliases},
29349 \csopt[measurement]{category},
29350 \csopt[baseunit]{type},
29351 \csopt[.copy]{duplicate-label-suffix},
29352 \csopt[\field{name}]{symbol-sort-fallback},
29353 \csopt[false]{save-locations}
29354 }
29355 \end{codeenv}
29356 I can't use \csopt{set-widest} here as it won't pick up the modified
29357 label and will instead use the label from the original entry.
29358 Instead I've used \cs{glsFindWidestTopLevelName} to find it:
29359 \begin{codeenv}
29360 \cs{printunsrtglossary*}\oarg{\printglossopt[baseunit]{type},\printglossopt[alttree]{style},\printglossopt{nogroupskip}}
29361 \marg{\comment{}
29362 \cs{glsFindWidestTopLevelName}\oarg{baseunit}\comment{}
29363 }
29364 \end{codeenv}
29365
29366 The text symbols from \exfile{miscsymbols.bib} are all loaded in a
29367 single \igls{resourceset}, where the \field{type} field can be
29368 obtained from the \field{category}, which in turns is obtained from
29369 the custom \fieldfmt{identifier} field. Since \bibgls\ doesn't
29370 recognise any of the symbol commands, I'm sorting according to the
29371 \field{description} field. (Even if \bibgls\ could determine a
29372 Unicode value for each of the symbols, sorting by the description
29373 makes more sense in this case.)
29374 \begin{codeenv}
29375 \gls{GlsXtrLoadResources}\oarg{
29376 \csopt[miscsymbols]{src},
29377 \csopt[
29378 \fieldfmt{identifier}=\field{category},
29379 \fieldfmt{icon}=\field{name},
29380 \fieldfmt{icondescription}=\field{description}
29381 ]{field-aliases},
29382 \csopt[icon=symbol]{entry-type-aliases},
29383 \csopt[same as category]{type},
29384 \csopt[\field{description}]{sort-field},
29385 \csopt[false]{save-locations},
29386 \csopt{set-widest}
29387 }
29388 \end{codeenv}
29389
29390 Finally, all recorded and cross-referenced terms are needed for the
29391 index. This includes entries that have already been defined in the
29392 earlier \iglspl{resourceset} (so a guard against duplicates is
29393 necessary) but it also includes entries from the \exfile{terms.bib}
29394 file that haven't yet been dealt with. I'd like the index to start
29395 with a \idx{symbolgroup} containing the icons from
29396 \exfile{miscsymbols.bib}. This needs to be dealt with separately from
29397 the rest of the index to keep them together in a single group:
29398 \begin{codeenv}
29399 \gls{GlsXtrLoadResources}\oarg{
29400 \csopt[miscsymbols]{src},
29401 \csopt[recorded no deps]{selection},
29402 \csopt[.copy]{duplicate-label-suffix},
29403 \csopt[icon=index]{entry-type-aliases},
29404 \csopt[
29405 \fieldfmt{identifier}=\field{category},
29406 \fieldfmt{icondescription}=\field{symbol},
29407 \fieldfmt{icon}=\field{name}
29408 ]{field-aliases},
29409 \csopt[index]{type},
29410 \csopt[\field{symbol}]{sort-field},
29411 \csopt[glssymbols]{group}
29412 }
29413 \end{codeenv}
29414 Since I know that there are no \glsdisp{parententry}{parents} or cross-references in this
29415 set of entries I've used \csopt[recorded no deps]{selection} to skip
29416 the dependency checks. In this \igls{resourceset}, the \field{name}
29417 field has the symbol command (obtained from the custom
29418 \fieldfmt{icon} field), and the \field{symbol} field has the symbol
29419 description (obtained from the custom \fieldfmt{icondescription}
29420 field), which is used as the sort field. I've set the \field{group}
29421 label to \code{glssymbols}, which keeps all these entries in a
29422 single group and the title will be obtained from
29423 \ics{glssymbolsgroupname}.
29424
29425 Before loading the final \igls{resourceset} \ics{glsxtrlongshortdescname} needs
29426 to be changed
29427 so that the abbreviations using the \abbrstyle{long-short-desc}
29428 style (that is, the abbreviations with the \field{category} set to
29429 \code{markuplanguage}) have the \field{name} field set to
29430 \meta{long} (\meta{short}):
29431 \begin{codeenv}
29432 \cs{renewcommand}*\marg{\cs{glsxtrlongshortdescname}}\marg{\comment{}
29433 \cs{protect}\cs{glslongfont}\marg{\cs{the}\cs{glslongtok}}\cs{space}
29434 \cs{glsxtrparen}\marg{\cs{glsabbrvfont}\marg{\cs{the}\cs{glsshorttok}}}\comment{}
29435 }
29436 \end{codeenv}
29437 The \abbrstyle{long-only-short-only} style has a similar command,
29438 but it was only introduced to \sty{glossaries-extra} version 1.25:
29439 \begin{codeenv}
29440 \cs{renewcommand}*\marg{\ics{glsxtronlyname}}{\comment{}
29441 \cs{protect}\cs{glsabbrvonlyfont}\marg{\cs{the}\cs{glslongtok}}\comment{}
29442 }
29443 \end{codeenv}
29444
29445 The abbreviations all need to be sorted according to the long form:
29446 \begin{codeenv}
29447 \csopt[\field{long}]{abbreviation-sort-fallback}
29448 \end{codeenv}
29449 The custom \glspl{entrytype} and fields again need to be aliased
29450 \begin{codeenv}
29451 \csopt[
29452 chemical=index,
29453 measurement=entry,
29454 unit=dualentry,
29455 icon=index
29456 ]{entry-type-aliases},
29457 \csopt[
29458 \fieldfmt{identifier}=\field{category},
29459 \fieldfmt{formula}=\field{symbol},
29460 \fieldfmt{chemicalname}=\field{name},
29461 \fieldfmt{unitname}=\field{description},
29462 \fieldfmt{unitsymbol}=\field{symbol},
29463 \fieldfmt{measurement}=\field{name},
29464 \fieldfmt{icon}=\field{symbol},
29465 \fieldfmt{icondescription}=\field{name}
29466 ]{field-aliases}
29467 \end{codeenv}
29468 The chemical formulae and icons are now defined using
29469 \atentry{index} with the \field{name} field set to a word form
29470 (chemical name and icon description). This means
29471 they're appropriate for alphabetical sorting. (Both \atentry{entry}
29472 and \atentry{symbol} require the \field{description} field, which is
29473 why I've aliased \atentryfmt{chemical} and \atentryfmt{icon}
29474 to \atentry{index} here.) The custom \atentryfmt{measurement}
29475 \gls{entrytype} has a \field{description} field (obtained from
29476 \fieldfmt{unitname}), so that's aliased to \atentry{entry} as again
29477 the \field{name} field is suitable for alphabetical sorting.
29478
29479 I've aliased \atentryfmt{unit} to \atentry{dualentry}
29480 rather than \atentry{symbol} as I want both the unit name and the
29481 measurement in the index and I've combined their \glspl{locationlist}:
29482 \begin{codeenv}
29483 \csopt[both]{combine-dual-locations}
29484 \end{codeenv}
29485 Both primary and dual entries need to go in the \code{index}
29486 glossary:
29487 \begin{codeenv}
29488 \csopt[index]{type},
29489 \csopt[index]{dual-type}
29490 \end{codeenv}
29491
29492 All \ext{bib} files used in the previous \iglspl{resourceset} are needed
29493 as well as the \exfile{terms.bib} file:
29494 \begin{codeenv}
29495 \csopt[terms,bacteria,markuplanguages,vegetables,minerals,
29496 animals,chemicalformula,baseunits,derivedunits,people,
29497 films,books,miscsymbols]{src}
29498 \end{codeenv}
29499 but this time I also want to select entries that haven't been
29500 recorded but have a cross-reference to a recorded entry:
29501 \begin{codeenv}
29502 \csopt{selection}[recorded and deps and see]
29503 \end{codeenv}
29504 Again it's necessary to provide a way to avoid duplicate entry
29505 labels, which can be done with
29506 \begin{codeenv}
29507 \csopt[.copy]{duplicate-label-suffix},
29508 \end{codeenv}
29509 as above. However, this will cause the cross-references (from the
29510 \field{alias} fields) to link to the glossary rather than the index.
29511 This may or may not confuse the reader. For consistency, it may be
29512 more suitable to have the cross-reference in the index link to the
29513 aliased entry in the index rather than in the glossary. I've
29514 therefore instead used:
29515 \begin{codeenv}
29516 \csopt[idx.]{label-prefix},
29517 \csopt[idx.]{record-label-prefix},
29518 \end{codeenv}
29519 This means that the entries defined in \exfile{terms.bib} need to be
29520 referenced with this prefix.
29521
29522 All instances of \cs{gls} will link to the original entry, so all
29523 entries except for those in the \exfile{terms.bib} file will link to
29524 the relevant glossary. Those in the \exfile{terms.bib} file will
29525 link to the index. It's possible to disable the hyperlinks for those
29526 entries, but the reader may find it useful to jump to the index to
29527 look up other \glspl{location} for that entry in the document.
29528
29529 To deal with the identical book and film titles, I'm again using the
29530 \field{category} to resolve identical sort values:
29531 \begin{codeenv}
29532 \csopt[\field{category}]{identical-sort-action}
29533 \end{codeenv}
29534 For the people who have a \field{first} field, I've decided that
29535 this would be more appropriate for the index as it's more compact
29536 than the \field{name}, so here I've done the reverse to earlier and copied the
29537 \field{first} field (if supplied) into the \field{name} field, but
29538 since the \field{name} field is already provided the override
29539 setting needs to be on:
29540 \begin{codeenv}
29541 \csopt{replicate-override},
29542 \csopt[\field{first}=\field{name}]{replicate-fields}
29543 \end{codeenv}
29544 As with \exfile{sample-people.tex} I've provided some custom
29545 commands to make it easier to locally redefine \gls{sortname} and
29546 \gls{sortvonname}:
29547 \begin{codeenv}
29548 \cs{newcommand}*\marg{\cmd{swaptwo}}[2]\marg{\idx{param}2, \idx{param}1}
29549 \cs{newcommand}*\marg{\cmd{swapthree}}[3]\marg{\idx{param}2 \idx{param}3, \idx{param}1}
29550 \end{codeenv}
29551 I've redefined \ics{glsxtrbookindexname} in a similar manner to
29552 \exfile{sample-multi1.tex} but it has some modifications:
29553 \begin{codeenv}
29554 \cs{renewcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\comment{}
29555 \cs{glossentryname}\marg{\idx{param}1}\comment{}
29556 \cs{ifglshassymbol}\marg{\idx{param}1}\comment{}
29557 \marg{\comment{}
29558 \cs{glsifcategory}\marg{\idx{param}1}\marg{chemical}\comment{}
29559 \marg{, \cs{glossentrysymbol}\marg{\idx{param}1}}\comment{}
29560 \marg{\cs{space}(\cs{glossentrynameother}\marg{\idx{param}1}\marg{\field{symbol}})}\comment{}
29561 }\comment{}
29562 \marg{\comment{}
29563 \cs{glsifcategory}\marg{\idx{param}1}\marg{film}\comment{}
29564 \marg{\cs{cs.space}(film)}\comment{}
29565 \marg{}\comment{}
29566 }\comment{}
29567 }
29568 \end{codeenv}
29569 This appends \qt{(film)} to film names. I've chosen this method
29570 rather than using the \idx{postnamehook} as I only want this in the
29571 index and not in the list of films.
29572
29573 For some of the entries that are referenced in the document, I've
29574 appended information in parentheses:
29575 \begin{codeenv}
29576 \cs{gls}\marg{Al2SO43} (\ics{glsdesc}\marg{Al2SO43})
29577 \end{codeenv}
29578 This is all right for odd instances, but if this always needs to be done
29579 on first use, then it's better to use the \idx{postlinkhook}, which
29580 is what I've done for the icons for comparison:
29581 \begin{codeenv}
29582 \cs{newcommand}*\marg{\postlinkhook{mediacontrol}}\marg{\comment{}
29583 \ics{glsxtrpostlinkAddDescOnFirstUse}
29584 }
29585 \strut
29586 \cs{newcommand}*\marg{\postlinkhook{information}}\marg{\comment{}
29587 \cs{glsxtrpostlinkAddDescOnFirstUse}
29588 }
29589 \strut
29590 \cs{newcommand}*\marg{\postlinkhook{weather}}\marg{\comment{}
29591 \cs{glsxtrpostlinkAddDescOnFirstUse}
29592 }
29593 \end{codeenv}
29594
29595 I've also provided some custom commands to make it easier to reference
29596 entries without worrying about the prefixes:
29597 \begin{codeenv}
29598 \cs{newcommand}\marg{\csfmt{unit}}\marg{\ics{glssymbol}}
29599 \cs{newcommand}\marg{\csfmt{measurement}}\marg{\cs{gls}}
29600 \gls{glsxtrnewgls}\marg{film.}\marg{\csfmt{film}}
29601 \end{codeenv}
29602
29603 As with \exfile{sample-multi1.tex}, it would be useful to include
29604 the page where the entries are defined in their corresponding lists.
29605 Again this can be done by redefining the general purpose
29606 non-category post-name hook \ics{glsextrapostnamehook}:
29607 \begin{codeenv}
29608 \cs{newcommand}*\marg{\cs{glsextrapostnamehook}}[1]\marg{\comment{}
29609 \cs{glsadd}\oarg{\glsaddopt[\encap{hyperbf}]{format}}\marg{\idx{param}1}\comment{}
29610 }
29611 \end{codeenv}
29612 This needs resetting before the index, since it's redundant to
29613 record an entry in the index. This will require an extra
29614 \bibgls+\LaTeX\ system call as this code can't be performed until
29615 the glossaries have been created.
29616
29617 The complete document code is listed below. The document build is:
29618 \begin{verbatim}
29619 pdflatex sample-multi2
29620 bib2gls --group --break-space sample-multi2
29621 pdflatex sample-multi2
29622 bib2gls --group --break-space sample-multi2
29623 pdflatex sample-multi2
29624 \end{verbatim}
29625 The resulting document is shown in \figureref{fig:sample-multi2.pdf},
29626 \figureref{fig:sample-multi2.pdf2} and \figureref{fig:sample-multi2.pdf3}.
29627
29628 \lstinputlisting[firstline=5]{../examples/sample-multi2.tex}
29629
29630 \begin{figure}
29631 \figcontents
29632 {\pdftwocol{../examples/sample-multi2.pdf}{4}}
29633 {\caption{\filefmt{sample-multi2.pdf} (pages~1 to~4)}}
29634 {fig:sample-multi2.pdf}
29635 \end{figure}
29636
29637 \begin{figure}
29638 \figcontents
29639 {\pdftwocol[5]{../examples/sample-multi2.pdf}{8}}
29640 {\caption{\filefmt{sample-multi2.pdf} (pages~5 to 8)}}
29641 {fig:sample-multi2.pdf2}
29642 \end{figure}
29643
29644 \begin{figure}
29645 \figcontents
29646 {\pdftwocol[9]{../examples/sample-multi2.pdf}{12}}
29647 {\caption{\filefmt{sample-multi2.pdf} (pages~9 and 12)}}
29648 {fig:sample-multi2.pdf3}
29649 \end{figure}
29650
29651 \setupglossaries{indexonlyfirst}
29652 \printstyoptsummary
29653 \printcommandsummary
29654 %\printcommandtopic
29655
29656 \bibliographystyle{plain}
29657 \bibliography{bib2gls-cite}
29658
29659 \renewcommand*{\glsxtrbookindexsubname}[1]{%
29660 \glsifcategory{#1}{command}%
29661 {%
29662 \glsxtrifhasfield{useri}{#1}%
29663 {\glossentrynameother{#1}{useri}}%
29664 {\glossentryname{#1}}%
29665 }%
29666 {\glossentryname{#1}}%
29667 }
29668 \newcommand{\locationfont}{\small}
29669 \newcommand{\widecrossreffont}{\footnotesize}
29670 \newcommand{\ifwidecrossref}[3]{%
29671 \dimen0=0pt\relax
29672 \glsxtrifhasfield*{see}{#1}%
29673 {\settowidth{\dimen0}{\locationfont\glsxtrusesee{#1}}}%
29674 {%
29675 \glsxtrifhasfield*{seealso}{#1}%
29676 {\settowidth{\dimen0}{\locationfont\glsxtruseseealso{#1}}}%
29677 {%
29678 \glsxtrifhasfield*{alias}{#1}%
29679 {\settowidth{\dimen0}{\locationfont\glsxtrusealias{#1}}}%
29680 {}%
29681 }%
29682 }%
29683 \ifdim\dimen0>0.4\linewidth #2\else#3\fi
29684 }
29685 \newcommand{\precrossref}{}
29686 \newcommand{\indexdotfill}{\,\cleaders\hbox to .44em{\hss\textcolor{lightgray}{.}\hss}\hfill\,}
29687 \renewcommand*{\glsxtrbookindexprelocation}[1]{%
29688 \glsxtrifhasfield*{location}{#1}%
29689 {\nobreak\indexdotfill
29690 \ifwidecrossref{#1}%
29691 {\def\precrossref{\widecrossreffont\glstreesubitem}}%
29692 {\def\precrossref{, }}%
29693 }%
29694 {%
29695 \ifwidecrossref{#1}{\nobreak\def\precrossref{\widecrossreffont\glstreesubitem}}%
29696 {\def\precrossref{\nobreak\indexdotfill}}%
29697 \glsxtrprelocation
29698 }%
29699 }
29700 \renewcommand{\glsxtrbookindexlocation}[2]{%
29701 \begingroup
29702 \locationfont
29703 #2%
29704 \glsxtrifhasfield{see}{#1}{\precrossref\glsxtrusesee{#1}}%
29705 {%
29706 \glsxtrifhasfield{seealso}{#1}%
29707 {\precrossref\glsxtruseseealso{#1}}%
29708 {%
29709 \glsxtrifhasfield{alias}{#1}{\precrossref\glsxtrusealias{#1}}{}%
29710 }%
29711 }%
29712 \endgroup
29713 \let\precrossref\empty
29714 }
29715 % With \printcommandtopic missing a lot of spawned entries will
29716 % appear in the index without a record. Without the topic list they
29717 % need to be skipped
29718 \renewcommand{\printunsrtglossaryentryprocesshook}[1]{%
29719 \glsxtrifhasfield*{progenitor}{#1}%
29720 {%\typeout{SKIPPING [has progenitor] #1}
29721 \printunsrtglossaryskipentry
29722 }%
29723 {%
29724 \GlsXtrIfFieldEqStr*{originalentrytype}{#1}{topic}%
29725 {%
29726 \glsxtrifhasfield*{location}{#1}%
29727 {}%
29728 {%
29729 \ifglshasdesc{#1}{}%
29730 {%
29731 %\typeout{SKIPPING [no location] #1}
29732 \printunsrtglossaryskipentry
29733 }%
29734 }%
29735 }%
29736 {%
29737 \GlsXtrIfFieldValueInCsvList*{#1}{category}%
29738 {abbreviationstyle,packageoption,glossarystyle,package}%
29739 {%
29740 \glsxtrifhasfield*{location}{#1}{}%
29741 {%\typeout{SKIPPING [topic \glscategory{#1} no location] #1}%
29742 \printunsrtglossaryskipentry
29743 }%
29744 }%
29745 {}%
29746 }%
29747 }%
29748 }
29749 \renewcommand*{\unicodecategoryfmt}[1]{\textsf{#1}}
29750 \glsrenewcommand*{\bibglspassim}{}
29751 \newcommand{\glsxtrpostnamecommand}{%
29752 \glsxtrifhasfield{userii}{\glscurrententrylabel}{ (\glscurrentfieldvalue)}{}%
29753 }
29754 \printunsrtglossary[type=index]
29755 \end{document}