Debian Codegraph @

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

raw
1 % arara: lualatex
2 % arara: bib2gls: {group: on} if missing("glstex") || changed(toFile("bib2gls.bib")) || found("log", "Warning: Glossary entry")
3 % arara: bibtex
4 % arara: lualatex if changed("glstex") || missing("toc")
5 % arara: bib2gls: {group: on}
6 % arara: lualatex
7 % arara: lualatex if found ("log", "Rerun")
8 \documentclass[titlepage=false,fontsize=12pt,captions=tableheading]{scrreprt}
9
10 \usepackage[no-math]{fontspec}
11 \setmainfont{Linux Libertine O}
12
13 \newfontface\cyrillicmono{FreeMono}[Scale=MatchLowercase]
14 \newcommand{\textcyrillicmono}[1]{{\cyrillicmono #1}}
15
16 \usepackage[x11names]{xcolor}
17 \usepackage{upquote}
18 \usepackage{hologo}
19 \usepackage{pifont}
20 \usepackage{graphicx}
21 \usepackage{tcolorbox}
22 \usepackage{datetime2}
23 \usepackage{siunitx}
24 \usepackage[version=4]{mhchem}
25
26 \usepackage{xr-hyper}
27 \usepackage[hidelinks]{hyperref}
28 \usepackage[record,
29 entrycounter,subentrycounter,%need to define counters for some examples
30 nostyles,stylemods={bookindex},style=index]{glossaries-extra}
31
32 \setupglossaries{entrycounter=false,subentrycounter=false}
33
34 \definecolor{field}{named}{DarkSlateGray4}
35 \definecolor{cs}{named}{DarkSeaGreen4}
36 \definecolor{styopt}{named}{DarkOrchid4}
37 \definecolor{entry}{named}{SteelBlue4}
38 \definecolor{comment}{named}{gray}
39 \definecolor{attribute}{named}{Purple4}
40 \definecolor{style}{named}{Blue4}
41
42 \newcommand{\extstyopt}{\textsuperscript{\textdagger}}
43
44 \newcommand{\dhyphen}{%
45 \texorpdfstring
46 {\discretionary{}{}{}\texttt{-}}%
47 {-}%
48 }
49
50 \renewrobustcmd{\-}{%
51 \discretionary
52 {{\rmfamily\char\ifnum\hyphenchar\font<0
53 \defaulthyphenchar\else\hyphenchar\font\fi
54 }}%
55 {}{}%
56 }
57
58 \setabbreviationstyle[common]{short-nolong}
59 \setabbreviationstyle[markwordsexample]{long-hyphen-short-hyphen}
60 \glssetcategoryattribute{markwordsexample}{markwords}{true}
61 \GlsXtrEnableInitialTagging{taggingexample}{\itag}
62 \glssetcategoryattribute{discardperiodexample}{discardperiod}{true}
63 \glssetcategoryattribute{initialism}{insertdots}{true}
64 \glssetcategoryattribute{initialism}{discardperiod}{true}
65 \glssetcategoryattribute{initialism}{retainfirstuseperiod}{true}
66 \setabbreviationstyle[initialism]{short-long}
67 \setabbreviationstyle[abbrvtrans]{long-short-user}
68 \setabbreviationstyle[longshortem]{long-short-em}
69 \setabbreviationstyle[shortsc]{short-sc-nolong}
70
71 \newcommand{\bibglspassim}{}
72 \newcommand{\bibglsseealsosep}{\par\hangindent .75em\parindent .75em\relax}
73
74 \newcommand*{\csfmt}[1]{%
75 \texorpdfstring
76 {\csfmtfont{\char`\\ #1}}%
77 {\string\\#1}%
78 }
79
80 \newcommand*{\csref}{\gls}
81
82 \newcommand{\texparserdefnote}{}
83
84 \newcommand*{\longargfmt}[1]{%
85 \texorpdfstring{\texttt{\longswitch #1}}%
86 {\string-\string-#1}%
87 }
88
89 \GlsXtrLoadResources[
90 src={bib2gls},
91 max-loc-diff=3,
92 entry-type-aliases={
93 exampleentry=entry,
94 examplesymbol=symbol,
95 exampleabbreviation=abbreviation
96 },
97 unknown-entry-alias={index},
98 field-aliases={note=user2},
99 symbol-sort-fallback={name},
100 break-at={none},
101 sort-replace={{,? +}{|},{\glshex2423}{ },
102 {\string\\([a-zA-Z])}{\glscapturedgroup1},
103 {([a-zA-Z])\string\.}{\glscapturedgroup1}}
104 ]
105
106 \DTMsavetimestamp{creation}{2017-01-20T15:39:00Z}
107
108 \IfFileExists{../java/Bib2Gls.java}
109 {
110 \DTMsavefilemoddate{moddate}{../java/Bib2Gls.java}
111 }
112 {
113 \DTMsavenow{moddate}
114 }
115
116 \newcommand{\bibgls}{\appfmt{bib2gls}}
117
118 \newcommand*{\BibTeX}{\hologo{BibTeX}}
119 \newcommand*{\eTeX}{\hologo{eTeX}}
120 \newcommand*{\XeLaTeX}{\hologo{XeLaTeX}}
121 \newcommand*{\LuaLaTeX}{\hologo{LuaLaTeX}}
122 \newcommand*{\pdfLaTeX}{\hologo{pdfLaTeX}}
123
124 \newcommand*{\ctanfile}[2]{%
125 \href{http://mirrors.ctan.org/macros/latex/contrib/#1/#2}{\nolinkurl{#2}}%
126 }
127
128 \newcommand{\hex}[1]{0x#1}
129
130 \newcommand{\qt}[1]{``#1''}
131
132 \newcommand{\qtt}[1]{\qt{\,\texttt{#1}\,}}
133
134 \newcommand{\incorrect}{\marginpar{\textcolor{red}{\ding{55}}}}
135 \newcommand{\correct}{\marginpar{\textcolor{green}{\ding{52}}}}
136
137 \newcounter{result}
138
139 \newenvironment{result}%
140 {%
141 \renewcommand{\glslinkpresetkeys}{\setkeys{glslink}{hyper=false,local}}%
142 \glsresetentrycounter
143 \stepcounter{result}%
144 \renewcommand{\GlsEntryCounterLabelPrefix}{glsentry\theresult-}%
145 \begin{quotation}%
146 \marginpar
147 [\raisebox{-2.5ex}{\ding{43}}]%
148 {\raisebox{-2.5ex}{\reflectbox{\ding{43}}}}%
149 \ignorespaces
150 }
151 {\end{quotation}\ignorespacesafterend}
152
153 \newcommand{\dequals}{%
154 \texorpdfstring
155 {\discretionary{}{}{}\texttt{=}\discretionary{}{}{}}%
156 {=}%
157 }
158
159 \newcommand{\dcomma}{%
160 \texorpdfstring
161 {\texttt{,}\discretionary{}{}{}}%
162 {,}%
163 }
164
165 \newcommand{\dcolon}{%
166 \texorpdfstring
167 {\texttt{:}\discretionary{}{}{}}%
168 {:}%
169 }
170
171 \pdfstringdefDisableCommands{%
172 \def\dhyphen{-}%
173 \def\dcolon{:}%
174 \def\dcomma{,}%
175 \def\dequals{,}%
176 \let\-\empty
177 }
178
179 \newcommand*{\csfmtfont}[1]{\texttt{#1}}
180
181 \newcommand*{\appfmt}[1]{\texorpdfstring{\texttt{#1}}{#1}}
182 \newcommand*{\styfmt}[1]{\texorpdfstring{\textsf{#1}}{#1}}
183 \newcommand*{\envfmt}[1]{\texorpdfstring{\textsf{#1}}{#1}}
184 \newcommand*{\optfmt}[1]{\texorpdfstring{\texttt{#1}}{#1}}
185 \newcommand*{\csoptfmt}[1]{\texorpdfstring{\textcolor{cs}{\optfmt{#1}}}{#1}}
186 \newcommand*{\styoptfmt}[1]{\texorpdfstring{\textcolor{styopt}{\optfmt{#1}}}{#1}}
187 \newcommand*{\fieldfmt}[1]{\texorpdfstring{\texttt{\color{field}#1}}{#1}}
188 \newcommand*{\entryfmt}[1]{\texorpdfstring{\texttt{\color{entry}#1}}{#1}}
189 \newcommand*{\atentryfmt}[1]{\entryfmt{@#1}}
190 \newcommand*{\abbrstylefmt}[1]{\texorpdfstring{\textsf{\color{style}#1}}{#1}}
191 \newcommand*{\glostylefmt}[1]{\texorpdfstring{\textsf{#1}}{#1}}
192 \newcommand*{\catattrfmt}[1]{\texorpdfstring{\textsf{\color{attribute}#1}}{#1}}
193 \newcommand*{\counterfmt}[1]{\texorpdfstring{\textsf{#1}}{#1}}
194 \newcommand*{\filefmt}[1]{\texorpdfstring{\texttt{#1}}{#1}}
195 \newcommand*{\metafilefmt}[3]{%
196 \filefmt{#1}\discretionary{}{}{}\meta{#2}\discretionary{}{}{}\filefmt{#3}%
197 }
198
199 \newcommand*{\extfmt}[1]{\filefmt{.#1}}%
200
201 \newcommand*{\argor}{\texorpdfstring{\protect\textbar}{|}}
202
203 \newrobustcmd*{\texmeta}[1]{{\normalfont\normalcolor$\langle$\emph{#1}$\rangle$}}
204
205 \newcommand*{\meta}[1]{%
206 \texorpdfstring{\ifmmode\text{\texmeta{#1}}\else\texmeta{#1}\fi}{#1}%
207 }
208
209 \newcommand*{\oarg}[1]{\discretionary{}{}{}[#1]}
210 \newcommand*{\oargm}[1]{\oarg{\meta{#1}}}
211
212 \newcommand*{\marg}[1]{\texorpdfstring
213 {\discretionary{}{}{}\char`\{#1\char`\} }%
214 {\{#1\}}%
215 }
216
217 \newcommand*{\margm}[1]{\marg{\meta{#1}}}
218
219 \newcommand{\switcharg}{}
220 \newcommand{\switchalt}{}
221
222 \makeatletter
223 \newcommand{\code}[1]{\texorpdfstring{{\ttfamily\obeyspaces #1}}{#1}}
224 \newcommand{\setupcodeenvfmts}{%
225 \def\cmd{\char`\\}%
226 \def\comment##1{\mbox{\textcolor{comment}{\idx{commentchar}\ ##1}}}%
227 \renewcommand*{\styfmt}[1]{##1}%
228 \renewcommand*{\counterfmt}[1]{##1}%
229 \renewcommand*{\catattrfmt}[1]{\textcolor{attribute}{##1}}%
230 \renewcommand*{\abbrstylefmt}[1]{\textcolor{style}{##1}}%
231 \renewcommand*{\csfmtfont}[1]{\textcolor{cs}{##1}}%
232 }
233 \newenvironment{codeenv}
234 {%
235 \renewcommand{\glslinkpresetkeys}{\setkeys{glslink}{noindex}}%
236 \setupcodeenvfmts
237 \begin{flushleft}\textcolor{lightgray}{\hrulefill}\par\nopagebreak
238 \medskip\nopagebreak
239 \ttfamily\obeylines\frenchspacing\@vobeyspaces}
240 {\nopagebreak\textcolor{lightgray}{\hrulefill}%
241 \end{flushleft}\ignorespacesafterend}
242
243 \newenvironment{codeenv*}
244 {%
245 \setupcodeenvfmts
246 \begin{flushleft}\ttfamily\obeylines\frenchspacing\@vobeyspaces
247 \parindent\z@\parfillskip\@flushglue\parskip\z@skip
248 }
249 {\end{flushleft}\ignorespacesafterend}
250
251 \makeatother
252
253 \newcommand{\primary}{\emph}
254 \newcommand{\primaryloc}[1]{\underline{\hyperbf{#1}}}
255
256 \newcommand{\pidx}[1][]{\gls[textformat=primary,format=primaryloc,#1]}
257 \newcommand{\pidxpl}[1][]{\glspl[textformat=primary,format=primaryloc,#1]}
258 \newcommand{\pIdx}[1][]{\Gls[textformat=primary,format=primaryloc,#1]}
259 \newcommand{\pIdxpl}[1][]{\Glspl[textformat=primary,format=primaryloc,#1]}
260
261 \newcommand{\idx}{\gls}
262 \newcommand{\idxpl}{\glspl}
263 \newcommand{\Idx}{\Gls}
264 \newcommand{\Idxpl}{\Glspl}
265
266 \glsxtrnewgls{ext.}{\ext}
267
268 \newcommand*{\iext}[1]{%
269 \glsxtrtitleorpdforheading{\idx{ext.#1}}{.#1}{\extfmt{#1}}%
270 }
271
272 \newcommand{\sty}{\gls}
273
274 \newcommand*{\isty}[1]{%
275 \texorpdfstring{\idx{#1}}{#1}%
276 }
277
278 \newcommand*{\env}[1]{%
279 \texorpdfstring{\idx{env.#1}}{#1}%
280 }
281
282 \newcommand*{\abbrstyle}[2][]{%
283 \texorpdfstring{\idx[#1]{abbrstyle.#2}}{#2}%
284 }
285
286 \newcommand*{\glostyle}[1]{%
287 \texorpdfstring{\idx{glostyle.#1}}{#1}%
288 }
289
290 \newcommand*{\catattr}[1]{%
291 \texorpdfstring{\idx{catattr.#1}}{#1}%
292 }
293
294 \newcommand*{\counter}[1]{%
295 \texorpdfstring{\idx{ctr.#1}}{#1}%
296 }
297
298 \newcommand*{\styopt}[2][]{%
299 \texorpdfstring%
300 {%
301 \gls{styopt.#2}\styoptfmt{\ifblank{#1}{}{\dequals\marg{#1}}}%
302 }%
303 {#2\ifblank{#1}{}{=#1}}%
304 }
305
306 \newcommand*{\keyvallist}{%
307 \texorpdfstring
308 {key\dequals value list}%
309 {key=value list}%
310 }
311
312 \newcommand{\nosecformatdef}[1]{%
313 \begin{definition}
314 \gls[format=primaryloc]{#1}%
315 \glsentryuseri{#1}%
316 \end{definition}\ignorespaces
317 }
318
319 \newcommand*{\cs}{\gls}
320
321 \newcommand*{\ics}[1][]{\cs[noindex=false,#1]}
322
323 \newcommand*{\icswithargs}[2][]{\cs{#2}\glsentryuseri{#2}}
324
325 \newcommand*{\postdeschook}[2][]{%
326 \glslink[#1]{idx.glsxtrpostdesccategory}{\csfmt{glsxtrpostdesc#2}}}
327
328 \newcommand*{\postlinkhook}[2][]{%
329 \glslink[#1]{idx.glsxtrpostlinkcategory}{\csfmt{glsxtrpostlink#2}}}
330
331
332 \glsxtrnewgls{file.}{\exfile}
333
334 \newcommand*{\csopt}[2][]{\gencsopt{#1}{opt}{#2}}%
335 \newcommand*{\glsopt}[2][]{\gencsopt{#1}{gls}{#2}}%
336 \newcommand*{\glsaddopt}[2][]{\gencsopt{#1}{glsadd}{#2}}%
337 \newcommand*{\printglossopt}[2][]{\gencsopt{#1}{printgloss}{#2}}%
338
339 \newcommand*{\gencsopt}[3]{%
340 \texorpdfstring%
341 {%
342 \gls{#2.#3}%
343 \csoptfmt{\ifblank{#1}{}{\dequals\marg{#1}}}%
344 }%
345 {#3\ifblank{#1}{}{=#1}}%
346 }
347
348 \newcommand*{\field}[1]{%
349 \texorpdfstring
350 {\gls{field.#1}}%
351 {#1}%
352 }
353
354 \newcommand*{\atentry}[2][]{%
355 \texorpdfstring
356 {\gls[#1]{entry.#2}}%
357 {#2}%
358 }
359
360 \newrobustcmd{\longswitch}{\string-{}\string-}
361
362 \newcommand*{\shortargfmt}[1]{%
363 \texorpdfstring{\texttt{\string-#1}}%
364 {\string-#1}%
365 }
366
367 \newcommand*{\longarg}[1]{%
368 \texorpdfstring
369 {\gls{switch.#1}}%
370 {\string-\string-#1}%
371 }
372
373 \definecolor{defbackground}{rgb}{1,1,0.75}
374
375 \newsavebox\borderedboxcontents
376 \newlength\borderedboxwidth
377
378 \newenvironment{definition}%
379 {%
380 \setlength{\fboxsep}{4pt}\setlength{\fboxrule}{1.25pt}%
381 \begin{lrbox}{\borderedboxcontents}%
382 \setlength\borderedboxwidth\linewidth
383 \addtolength\borderedboxwidth{-2\fboxrule}%
384 \addtolength\borderedboxwidth{-2\fboxsep}%
385 \begin{minipage}{\borderedboxwidth}
386 \flushleft\ttfamily\ignorespaces
387 }%
388 {%
389 \end{minipage}%
390 \end{lrbox}\par\medskip\noindent
391 \fcolorbox{black}{defbackground}{\usebox\borderedboxcontents}%
392 \medskip\par\noindent
393 \ignorespacesafterend
394 }
395
396 \newtcolorbox{important}{colback=red!5!white,colframe=red}
397
398 \newcommand*{\sectionref}[1]{section~\ref{#1}}
399 \newcommand*{\Sectionref}[1]{Section~\ref{#1}}
400
401 \newcommand{\doglossaryentry}[1]{%
402 \glsxtrglossentry{#1} & \glsentrydesc{#1}\glspostdescription\\%
403 }
404 \newcounter{localglossary}
405 \newenvironment{localglossary}
406 {%
407 \stepcounter{localglossary}%
408 \renewcommand{\glolinkprefix}{\thelocalglossary.}%
409 \GlsXtrStartUnsetBuffering*
410 }
411 {%
412 \par
413 \begin{tabular}{ll}
414 \GlsXtrForUnsetBufferedList\doglossaryentry
415 \end{tabular}
416 \GlsXtrStopUnsetBuffering
417 \par
418 }
419 \pagestyle{headings}
420
421 \newcommand{\glossarytitle}{Index}
422 \let\orgbibcite\bibcite
423 \renewcommand{\bibcite}[2]{}
424 \externaldocument{bib2gls}
425 \let\bibcite\orgbibcite
426
427 \newcommand{\addr}[1]{\\\href{https://www.#1/}{\nolinkurl{#1}}}
428 \title{\styfmt{glossaries-extra} and \bibgls: An Introductory Guide}
429 \author{Nicola Talbot\addr{dickimaw-books.com}}
430 \input{version}
431
432 \makeatletter
433 \begingroup
434 \renewcommand{\addr}[1]{}
435 \let\texorpdfstring\@secondoftwo
436 \DTMsetstyle{pdf}
437 \protected@edef\x{\endgroup
438 \noexpand\hypersetup{%
439 pdfinfo={
440 Title={\@title},
441 Author={\@author},
442 CreationDate={\DTMuse{creation}},
443 ModDate={\DTMuse{moddate}},
444 }%
445 }%
446 }\x
447
448 \makeatother
449
450 \begin{document}
451 \maketitle
452 \pagenumbering{alph}
453 \thispagestyle{empty}
454
455 \begin{abstract}
456 This document is an introductory guide to \bibgls\ and the
457 \sty{glossaries-extra} package to help you get started. For
458 further information, including more complex commands and settings,
459 see the main \bibgls\ user manual (\filefmt{bib2gls.pdf},
460 in the same directory as this document),
461 the \isty{glossaries-extra} user manual,
462 (distributed with the \sty{glossaries-extra}
463 package~\cite{glossaries-extra})
464 and the \isty{glossaries} user manual
465 (distributed with the \sty{glossaries} package~\cite{glossaries}).
466 See also the gallery~\cite{gallery} for examples.
467
468 The \sty{glossaries} package is the \emph{base} package. The
469 \sty{glossaries-extra} package internally loads the \sty{glossaries} package
470 and extends it, providing extra options or modifying the base
471 commands to increase flexibility. If you want to use \bibgls, you
472 must load \sty{glossaries-extra}, which provides the interface
473 required by \bibgls.
474 This document doesn't cover the other indexing methods described in
475 the base package. If you get an undefined control sequence or
476 unknown option error when trying out any of the examples here, check
477 that you are using the latest versions of \sty{glossaries},
478 \sty{glossaries-extra} and \bibgls.
479 \end{abstract}
480
481 \clearpage
482 \pagenumbering{roman}
483 \tableofcontents
484
485 \clearpage
486 \pagenumbering{arabic}
487
488 \chapter{Introduction}
489 \label{sec:beginintro}
490
491 The \sty{glossaries} package provides a way of defining terms,
492 notation or abbreviations that can then be used in the document.
493 This ensures consistent naming and formatting. (With the help of the
494 \sty{hyperref} package, it's also possible to create hyperlinks from
495 the reference to a place in the document that provides a definition
496 of the term, but more about that later.) Each entry (term,
497 notation or abbreviation) is defined using:
498 \nosecformatdef{newglossaryentry}
499 Here's a simple example:
500 \begin{codeenv}
501 \cmd{documentclass}\marg{article}
502 \strut
503 \ics{usepackage}\marg{glossaries}
504 \strut
505 \gls{newglossaryentry}\marg{duck}\comment{label}
506 \marg{\comment{ information about this term:}
507 \field{name}=\marg{duck},\comment{ display name}
508 \field{description}=\marg{a waterbird with webbed feet}\comment{description}
509 }
510 \strut
511 \gls{newglossaryentry}\marg{goose}\comment{ label}
512 \marg{\comment{information about this term:}
513 \field{name}=\marg{goose},\comment{display name}
514 \field{plural}=\marg{geese},\comment{plural form}
515 \field{description}=\marg{a large waterbird with a long neck, short legs,
516 webbed feet and a short broad bill}
517 }
518 \strut
519 \cmd{begin}\marg{document}
520 The pond contained a \gls{gls}\marg{duck} (\gls{glsentrydesc}\marg{duck}) and
521 a \gls{gls}\marg{goose} (\gls{glsentrydesc}\marg{goose}). \gls{Glspl}\marg{duck} and
522 \gls{glspl}\marg{goose} are fowl.
523 \cmd{end}\marg{document}
524 \end{codeenv}
525 The resulting text is:
526 \begin{result}
527 The pond contained a \gls{ex1.duck} (\glsentrydesc{ex1.duck}) and
528 a \gls{ex1.goose} (\glsentrydesc{ex1.goose}). \Glspl{ex1.duck} and
529 \glspl{ex1.goose} are fowl.
530 \end{result}
531 For convenience, the text produced by commands such as \cs{gls} is called the
532 \pidx{link-text} (even if there are no hyperlinks).
533
534 The first argument of \gls{newglossaryentry} is a label that
535 uniquely identifies the term (see \sectionref{sec:labels}). The
536 second argument is a comma-separated list of
537 \meta{setting}\dequals\meta{value} assignments. Each \meta{setting}
538 is referred to as a \qt{key} in the \isty{glossaries} manual or as a
539 \qt{field} in the \bibgls\ manual. A list of the available base keys
540 can be found in the \isty{glossaries} user manual. The
541 \isty{glossaries-extra} package provides some additional keys that
542 are described in the \sty{glossaries-extra} manual. The \bibgls\
543 user manual summarises all keys (fields) in \sectionref{sec:fields}.
544
545 The term \qt{field} not only includes the keys that may be used with
546 \gls{newglossaryentry} but also internal labels (which may or may
547 not have a corresponding key) that are used to store information.
548 Note that there are some fields that may be used in the document
549 that are considered internal fields by \bibgls\ because the field
550 value is typically set as a by-product of the way that \bibgls\
551 works. If these fields are set manually then you may get unexpected
552 results as this can break \bibgls's normal operation.
553
554 \begin{important}
555 If the field value contains commas or equal signs the value must be grouped
556 to hide those characters from the \meta{key}\dequals\meta{value} parser.
557 When using \bibgls, the field value must be delimited according to
558 the \ext{bib} file format.
559 \end{important}
560
561 The two main keys are \field{name} and \field{description}. The
562 \field{name} identifies how the term should be displayed in the
563 glossary (see \sectionref{sec:displaygloss}). It also provides the
564 default singular term, if not explicitly given. The default plural
565 is obtained by appending \qt{s} to the singular form. If this isn't
566 correct (as with \qt{geese}), then the plural form can be specified
567 with the \field{plural} key.
568
569 The description (set with the \field{description} key) is usually
570 only displayed in the glossary, but you can display it in the text
571 using:
572 \nosecformatdef{glsentrydesc}
573 as in the above example. This simply expands to the value of the
574 \field{description} field (or does nothing if there's no entry
575 associated with the given label).
576
577 The main command used to reference a term is:
578 \nosecformatdef{gls}
579 In the above example, \gls{gls} just displays the singular form, but you
580 can provide alternative text to use the first time a term is
581 referenced (see \sectionref{sec:firstuse}). The plural form is obtained with
582 the \pidx{variant} command:
583 \nosecformatdef{glspl}
584 There are other \idxpl{variant} of \gls{gls} that perform
585 \glslink{case-change}{case-changing}.
586 If you want to start a sentence with an entry then you can use:
587 \nosecformatdef{Gls}
588 for the singular form and
589 \nosecformatdef{Glspl}
590 for the plural form. For all capitals, use:
591 \nosecformatdef{GLS}
592 for the singular form and
593 \nosecformatdef{GLSpl}
594 for the plural form. Any mention of \gls{gls} and its
595 \idxpl{variant} in this guide or in the user manuals means that the
596 comments applied to \gls{gls} also apply to the plural and
597 case-changing versions.
598
599 The \meta{insert} optional argument is provided to insert additional material.
600 For example:
601 \begin{codeenv}
602 The \gls{gls}\marg{goose} liked the \gls{gls}\marg{duck}['s] hat.
603 \end{codeenv}
604 which produces (assuming the above definitions):
605 \begin{result}
606 The \gls{ex1.goose} liked the \gls{ex1.duck}['s] hat.
607 \end{result}
608 In some cases, there may not be a noticeable difference between the
609 above and the following:
610 \begin{codeenv}
611 The \gls{gls}\marg{goose} liked the \gls{gls}\marg{duck}'s hat.
612 \end{codeenv}
613 It depends on other settings, such as whether or not hyperlinks have
614 been enabled. (The inserted material is commonly moved inside the
615 hyperlink.) Take care if you need a literal open square bracket
616 following \code{\cs{gls}\margm{label}} as you need to prevent it from being
617 interpreted as the optional \meta{insert} argument. For example:
618 \begin{codeenv}
619 The \gls{gls}\marg{goose} liked the \gls{gls}\marg{duck}\marg{['s]} hat.
620 \end{codeenv}
621 which now produces:
622 \begin{result}
623 The \gls{ex1.goose} liked the \gls{ex1.duck}{['s]} hat.
624 \end{result}
625 An alternative in this case could be to define:
626 \begin{codeenv}
627 \cmd{newcommand}*\marg{\cmd{missing}}[1]\marg{[\gls*{param}1]}
628 \end{codeenv}
629 and then use:
630 \begin{codeenv}
631 The \gls{gls}\marg{goose} liked the \gls{gls}\marg{duck}\cmd{missing}\marg{'s} hat.
632 \end{codeenv}
633 This conveniently hides the open square bracket from \cs{gls}.
634
635 \begin{important}
636 Commands like \gls{gls} are \idx{robust}. Commands like
637 \gls{glsentrydesc} are \idx{expandable}. (See \sectionref{sec:robust}.)
638 If you want the entry to appear in a PDF bookmark, you need to use an
639 expandable command to reference it.
640 \end{important}
641
642 There are some helper commands that internally use
643 \gls{newglossaryentry}, such as \cs{newabbreviation} (described in
644 \sectionref{sec:abbreviations}) and \cs{glsxtrnewsymbol} (described
645 in \sectionref{sec:symbols}). If the description contains explicit paragraph
646 breaks then:
647 \nosecformatdef{longnewglossaryentry}
648 is required instead.
649
650 \section{Labels}
651 \label{sec:labels}
652
653 The label used to identify the entry can't contain any special characters, such
654 as \gls{commentchar} (percent), \gls{ampchar} (ampersand), \gls{param} (hash),
655 \gls{mshiftchar} (dollar), or \gls{nbspchar} (tilde). Be careful of packages
656 that make other characters active (such as \isty{babel} with its shortcuts). If
657 you are using \isty{inputenc}, this also includes extended Latin characters and
658 characters from other scripts.
659
660 Recent updates to the \LaTeX\ kernel mean that there's much better
661 support for UTF-8 characters. Ensure that you have at least
662 \sty{glossaries} v4.50, \sty{glossaries-extra} v1.49 and
663 \sty{mfirstuc} 2.08. It's now possible to have:
664 \begin{codeenv}
665 \gls{newglossaryentry}\marg{élite}\comment{label}
666 \marg{
667 \field{name} = \marg{élite},
668 \field{description} = \marg{group of people regarded as
669 the best of a particular society or organisation}
670 }
671 \end{codeenv}
672 Regardless of whether or not you use a native UTF-8 engine, provided
673 you have a new \TeX\ distribution.
674
675 \begin{important}
676 The UTF-8 information below refers to older
677 versions and older kernels.
678 \end{important}
679
680 If you want to include UTF-8 characters in the
681 label then you must use a \TeX\ engine with native Unicode support (that is,
682 \XeLaTeX\ or \LuaLaTeX).
683
684 For example, with no UTF-8 support (not even \sty{inputenc}):
685 \begin{codeenv}
686 \gls{newglossaryentry}\marg{elite}\comment{label (no UTF-8 support)}
687 \marg{
688 \field{name} = \marg{\marg{\gls{acute}e}lite},
689 \field{description} = \marg{group of people regarded as
690 the best of a particular society or organisation}
691 }
692 \end{codeenv}
693 or with \sty{inputenc}:
694 \begin{codeenv}
695 \gls{newglossaryentry}\marg{elite}\comment{label (UTF-8 not natively supported)}
696 \marg{
697 \field{name} = \marg{élite},
698 \field{description} = \marg{group of people regarded as
699 the best of a particular society or organisation}
700 }
701 \end{codeenv}
702 Whereas with \XeLaTeX\ or \LuaLaTeX\ you can do:
703 \begin{codeenv}
704 \gls{newglossaryentry}\marg{élite}\comment{label (UTF-8 natively supported)}
705 \marg{
706 \field{name} = \marg{élite},
707 \field{description} = \marg{group of people regarded as
708 the best of a particular society or organisation}
709 }
710 \end{codeenv}
711
712 You may have noticed the grouping of the initial (accented) letter
713 in the \gls{ASCII} example (\code{\marg{\gls{acute}e}lite}). This is
714 necessary to ensure that the first-letter case-changing commands,
715 such as \ics{Gls}, work. It also used to be required around the
716 \qtt{é} with \sty{inputenc}, but if you have up-to-date versions of
717 \sty{glossaries} and \sty{datatool} then it should no longer be
718 necessary. No special treatment is needed with \XeLaTeX\ or
719 \LuaLaTeX\ where \qtt{é} is a single token.
720
721 If you can't use extended characters in the label (because you're
722 not using \XeLaTeX\ or \LuaLaTeX), then simply stripping the accents
723 to create an \gls{ASCII} alternative may be sufficient, but take
724 care if this may cause a conflict. For example:
725 \begin{codeenv}
726 \gls{newglossaryentry}\marg{resume}\comment{label}
727 \marg{
728 \field{name} = \marg{resume},
729 \field{description} = \marg{continue after an interruption}
730 }
731 \strut
732 \gls{newglossaryentry}\marg{resumee}\comment{label}
733 \marg{
734 \field{name} = \marg{r\gls{acute}esum\gls{acute}e},
735 \field{description} = \marg{summary of something or curriculum vitae}
736 }
737 \end{codeenv}
738 For languages that use a non-Latin script, if you can't or don't
739 want to use \XeLaTeX\ or \LuaLaTeX, then you need to decide the most
740 appropriate \gls{ASCII} naming scheme.
741 For example:
742 \begin{codeenv}
743 \gls{newglossaryentry}\marg{goose}\comment{using translation for label}
744 \marg{
745 \field{name} = \marg{\textcyrillicmono{гусь}},
746 \field{plural} = \marg{\textcyrillicmono{гуси}},
747 \field{description} = \marg{\textnormal{\ldots}}
748 }
749 \end{codeenv}
750 or
751 \begin{codeenv}
752 \gls{newglossaryentry}\marg{hus}\comment{using closest ASCII match for label}
753 \marg{
754 \field{name} = \marg{\textcyrillicmono{гусь}},
755 \field{plural} = \marg{\textcyrillicmono{гуси}},
756 \field{description} = \marg{\textnormal{\ldots}}
757 }
758 \end{codeenv}
759
760 In addition to labels identifying entries, there are also labels
761 that identify other things, such as a glossary, category or letter
762 group. The same restrictions apply to those labels.
763
764 \section{First Use}
765 \label{sec:firstuse}
766
767 Each entry has a \pidx{firstuseflag} (boolean variable) that
768 determines whether or not the entry has been referenced in the
769 document. Commands like \gls{gls} and \gls{glspl} change the flag
770 to indicate that the entry has been used. Commands like
771 \gls{glsentrydesc} don't. Here's a modification of the earlier
772 example document that provides different versions depending on
773 whether or not the entry has already been referenced:
774 \begin{codeenv}
775 \cmd{documentclass}\marg{article}
776 \strut
777 \cmd{usepackage}\marg{glossaries}
778 \strut
779 \gls{newglossaryentry}\marg{duck}\comment{label}
780 \marg{\comment{information about this term:}
781 \field{name} = \marg{Duck (noun)},\comment{display name}
782 \field{first} = \marg{duck (quack, quack)},\comment{first use singular}
783 \field{firstplural} = \marg{ducks (quack, quack)},\comment{first use plural}
784 \field{text} = \marg{duck},\comment{subsequent use singular}
785 \field{description} = \marg{a waterbird with webbed feet}\comment{description}
786 }
787 \strut
788 \gls{newglossaryentry}\marg{goose}\comment{label}
789 \marg{\comment{information about this term:}
790 \field{name} = \marg{Goose (noun, pl.\ geese)},\comment{display name}
791 \field{first} = \marg{goose (honk, honk)},\comment{first use singular}
792 \field{firstplural} = \marg{geese (honk, honk)},\comment{first use plural}
793 \field{text} = \marg{goose},\comment{subsequent use singular}
794 \field{plural} = \marg{geese},\comment{subsequent use plural}
795 \field{description}=\marg{a large waterbird with a long neck, short legs,
796 webbed feet and a short broad bill}
797 }
798 \strut
799 \cmd{begin}\marg{document}
800 The pond contained a \gls{gls}\marg{duck}\cmd{footnote}\marg{\gls{glsentryname}\marg{duck}:
801 \gls{glsentrydesc}\marg{duck}} and two
802 \gls{glspl}\marg{goose}\cmd{footnote}\marg{\gls{glsentryname}\marg{goose}:
803 \gls{glsentrydesc}\marg{goose}}. \gls{Glspl}\marg{duck} and \gls{glspl}\marg{goose} are fowl.
804 \cmd{end}\marg{document}
805 \end{codeenv}
806 This now produces:
807 \begin{result}
808 The pond contained a \gls{ex2.duck}\footnote{\glsentryname{ex2.duck}:
809 \glsentrydesc{ex2.duck}} and two
810 \glspl{ex2.goose}\footnote{\glsentryname{ex2.goose}:
811 \glsentrydesc{ex2.goose}}. \Glspl{ex2.duck} and \glspl{ex2.goose} are fowl.
812 \end{result}
813 This uses:
814 \nosecformatdef{glsentryname}
815 which works in a similar way to \gls{glsentrydesc}. In this case,
816 \gls{glsentryname} simply expands to the value of the \field{name}
817 key. There's also a case-changing version:
818 \nosecformatdef{Glsentryname}
819 which changes the initial character to \idx{uppercase},
820 but (unlike \cs{glsentryname}) this command isn't expandable. If,
821 for example, I had instead set the duck's \field{name} key using:
822 \begin{codeenv}
823 \field{name} = \marg{duck (noun)}
824 \end{codeenv}
825 then I would need to use \code{\gls{Glsentryname}\marg{duck}}
826 instead.
827
828 So on \pidx{firstuse}, \cs{gls} uses the value of the \field{first} key
829 and \cs{glspl} uses the value of the \field{firstplural} key. On
830 \pidx{subsequentuse}, \cs{gls} uses the value of the \field{text} key and
831 \cs{glspl} uses the value of the \field{plural} key. \pIdx{regular}
832 abbreviations also follow this usage. \pIdx{non-regular}
833 abbreviations follow a different behaviour for \gls{gls} (and its
834 \idxpl{variant}) that's determined by the abbreviation style.
835
836 If the first use for a particular group of terms always has the
837 same pattern (such as following the term with a brief description or
838 alternative representation), then it's simpler to use one of the
839 automated methods provided, such as the abbreviation mechanism
840 (\sectionref{sec:abbreviations}) or changing the formatting
841 (\sectionref{sec:glsformats}).
842
843 You can test if an entry has been used with:
844 \nosecformatdef{ifglsused}
845 This requires that the entry (identified by \meta{label}) is
846 defined. If it isn't then neither \meta{true} nor \meta{false} is
847 done and an error or warning occurs. Otherwise, the command will do
848 \meta{true} if the entry has been used or \meta{false} if the entry
849 hasn't been used.
850
851 When using \bibgls, entries are never defined on the first \LaTeX\
852 run, so you may instead prefer:
853 \nosecformatdef{GlsXtrIfUnusedOrUndefined}
854 which does \meta{true} if either the entry hasn't been defined or
855 hasn't been marked as used, otherwise it does \meta{false}.
856
857 Neither \gls{ifglsused} nor \gls{GlsXtrIfUnusedOrUndefined} should
858 occur in the \idx{postlinkhook} (described later) as the entry will have already
859 been used by that point. Instead, you need \gls{glsxtrifwasfirstuse}
860 (see \sectionref{sec:postlinkhooks}).
861
862 \section{Categories}
863 \label{sec:categories}
864
865 The \isty{glossaries-extra} extension package provides the
866 \field{category} key, which isn't available with just the base
867 \sty{glossaries} package. The value of this key must be a
868 label as it's used to construct command names. You can choose
869 whatever label you like (as long as it conforms to the valid
870 labelling scheme, described in \sectionref{sec:labels}). If you
871 don't specify a category, then \gls{newglossaryentry} and
872 \gls{longnewglossaryentry} assume \code{general}. The helper
873 commands, such as \gls{newabbreviation}, have different defaults.
874
875 For example:
876 \begin{codeenv}
877 \gls{newglossaryentry}\marg{amethyst}
878 \marg{
879 \field{name} = \marg{amethyst},
880 \field{description} = \marg{a purple type of quartz},
881 \field{category} = \marg{mineral}
882 }
883 \end{codeenv}
884 The value of the \field{category} field for a given entry can be obtained
885 with:
886 \nosecformatdef{glscategory}
887 where \meta{label} identifies the entry. This command is expandable
888 and does nothing if the entry hasn't been defined. You can test the
889 value of the \field{category} field using:
890 \nosecformatdef{glsifcategory}
891 This checks if the \field{category} field for the entry given by
892 \meta{label} is set to \meta{category}, but doesn't perform any
893 expansion of \meta{category}. It generates an error if the entry
894 doesn't exist (or warning with \styopt[warn]{undefaction}).
895
896 The category allows you to apply certain types of formatting, such
897 as the \idx{postlinkhook} (\sectionref{sec:postlinkhooks}).
898 For abbreviations, the category also governs the abbreviation style (see
899 \sectionref{sec:abbreviations}) and can be used for filtering.
900 Categories may be assigned \pidxpl{attribute} that can also be used
901 to modify formatting or styles.
902
903 Unlike the \idx{postlinkhook}, which
904 needs to be defined before an entry is \emph{used} (with commands like
905 \gls{gls}), some \idxpl{attribute} need to be set before the entry
906 is \emph{defined}, so it's best to set them up as soon as possible in the
907 preamble (after loading \sty{glossaries-extra}).
908
909 \section{Adding Extra Information}
910 \label{sec:userkeys}
911
912 In addition to the \field{name} and \field{description} keys,
913 there's also a \field{symbol} key which allows you to store an
914 associated symbol. The value can be obtained with:
915 \nosecformatdef{glssymbol}
916 (which is robust and recognises the \idx{postlinkhook}) or with:
917 \nosecformatdef{glsentrysymbol}
918 (which behaves like \gls{glsentrydesc} and \gls{glsentryname}).
919 Neither of the above commands affect the \idx{firstuseflag}.
920 For example:
921 \begin{codeenv}
922 \cmd{documentclass}\marg{article}
923 \strut
924 \cmd{usepackage}[hidelinks]\marg{hyperref}
925 \cmd{usepackage}\marg{glossaries}
926 \strut
927 \gls{newglossaryentry}\marg{pi}\comment{label}
928 \marg{\comment{settings:}
929 \field{name} = \marg{Archimedes' constant},
930 \field{symbol} = \marg{\gls[noindex=false]{ensuremath}\marg{\cmd{pi}}},
931 \field{description} = \marg{ratio of a circle's circumference to its
932 diameter}
933 }
934 \strut
935 \gls{newglossaryentry}\marg{thetai}\comment{label}
936 \marg{\comment{settings:}
937 \field{name} = \marg{theta parameter},
938 \field{symbol} = \marg{\gls{ensuremath}\marg{\cmd{theta}\gls{sbchar}i}},
939 \field{description} = \marg{one of the model parameters}
940 }
941 \strut
942 \cmd{begin}\marg{document}
943 \gls{gls}\marg{pi} (\gls{glssymbol}\marg{pi}). Compare \gls{mshiftchar}\gls{glssymbol}\marg{thetai}\gls[noindex=false]{spchar}2\gls{mshiftchar}
944 with \gls{mshiftchar}\gls{glssymbol}\marg{thetai}[\gls{spchar}2]\gls{mshiftchar}.
945 \cmd{end}\marg{document}
946 \end{codeenv}
947 This produces:
948 \begin{result}
949 \gls{ex.pi} (\glssymbol{ex.pi}). Compare $\glssymbol{ex.thetai}^2$
950 with $\glssymbol{ex.thetai}[^2]$.
951 \end{result}
952 Note that in this case there is now a difference between using the
953 final optional \meta{insert} argument and simply appending the extra
954 material. This is a result of the hyperlink that causes an
955 interruption between the subscript \code{\gls{sbchar}i} and the following
956 superscript \code{\gls{spchar}2}. (In this case, there's no target for the
957 hyperlinks. That's covered in \sectionref{sec:displaygloss}.)
958
959 If you have additional information, such as a translation,
960 associated image or citation, then you can supply this with the six
961 user keys:
962 \field{user1}\glsaddeach{field.user2,field.user3,field.user4,field.user5},
963 \ldots, \field{user6}. The value of the
964 first field (\field{user1}) can be obtained with:
965 \nosecformatdef{glsuseri}
966 (which behaves like \gls{glssymbol}) or with:
967 \nosecformatdef{glsentryuseri}
968 (which behaves like \gls{glsentrysymbol}).
969 \glsaddeach{glsuserii,glsuseriii,glsuseriv,glsuserv,%
970 glsentryuserii,glsentryuseriii,glsentryuseriv,glsentryuserv}%
971 The other fields are similarly obtained using \idx{lowercase} Roman
972 numerals, so value of the sixth field (\field{user6}) can be obtained with:
973 \nosecformatdef{glsuservi}
974 (which behaves like \gls{glssymbol}) or with:
975 \nosecformatdef{glsentryuservi}
976 (which behaves like \gls{glsentrysymbol}).
977 For example:
978 \begin{codeenv}
979 \gls{newglossaryentry}\marg{polly.parrot}\comment{label}
980 \marg{\comment{}
981 \field{name} = \marg{Polly Parrot},
982 \field{description} = \marg{Senior assistant at the International Society
983 of Duck and Geese},
984 \field{user1} = \marg{British},\comment{nationality}
985 \field{user2} = \marg{1970-12-31},\comment{date of birth}
986 \field{user3} = \marg{female},\comment{gender}
987 \field{user4} = \marg{43 The Lane, Some Town, Noshire AB1 2XY},\comment{address}
988 \field{user5} = \marg{[email protected]}\comment{email}
989 }
990 \end{codeenv}
991
992 Alternatively you can define your own custom keys. If you don't need
993 commands equivalent to \gls{glssymbol}, then you can use:
994 \nosecformatdef{glsaddstoragekey}
995 where \meta{key} is the name of the new key, \meta{default value} is
996 the default value if the key isn't explicitly set and \meta{no link
997 cs} is the name of the command to access the field value (equivalent
998 to \gls{glsentrysymbol}). If you want commands equivalent to
999 \gls{glssymbol} that have the \meta{options} and \meta{insert}
1000 optional arguments and obey the \idx{postlinkhook}, then use
1001 \nosecformatdef{glsaddkey}
1002 The first three arguments are as for \gls{glsaddstoragekey}.
1003 The next argument \meta{no link ucfirst cs} is like \meta{no link
1004 cs} but converts the first letter to \idx{uppercase} (analogous to
1005 \gls{Glsentryname}). The final three commands behave like
1006 \gls{glssymbol}, but \meta{link ucfirst cs} converts the first
1007 letter to \idx{uppercase} and \meta{link allcaps cs} converts the entire
1008 value to \idx{uppercase}.
1009
1010 The new keys must be provided before the entries are defined (and
1011 the key definitions must come before the first \idx{resourceset}
1012 if you use \bibgls). For example:
1013 \begin{codeenv}
1014 \gls{glsaddstoragekey}\marg{\fieldfmt{nationality}}\marg{}\marg{\cmd{Nationality}}
1015 \gls{glsaddstoragekey}\marg{\fieldfmt{dateofbirth}}\marg{}\marg{\cmd{DateOfBirth}}
1016 \gls{glsaddstoragekey}\marg{\fieldfmt{gender}}\marg{}\marg{\cmd{Gender}}
1017 \gls{glsaddstoragekey}\marg{\fieldfmt{address}}\marg{}\marg{\cmd{Address}}
1018 \gls{glsaddstoragekey}\marg{\fieldfmt{email}}\marg{}\marg{\cmd{Email}}
1019 \gls{newglossaryentry}\marg{polly.parrot}\comment{label}
1020 \marg{\comment{}
1021 \field{name} = \marg{Polly Parrot},
1022 \field{description} = \marg{Senior assistant at the International Society
1023 of Duck and Geese},
1024 \fieldfmt{nationality} = \marg{British},\comment{nationality}
1025 \fieldfmt{dateofbirth} = \marg{1970-12-31},\comment{date of birth}
1026 \fieldfmt{gender} = \marg{female},\comment{gender}
1027 \fieldfmt{address} = \marg{43 The Lane, Some Town, Noshire AB1 2XY},\comment{address}
1028 \fieldfmt{email} = \marg{[email protected]}\comment{email}
1029 }
1030 \end{codeenv}
1031
1032 In addition to the commands like \gls{glssymbol} and
1033 \gls{glsentrysymbol}, there are other ways of accessing the field
1034 value or checking if the field has been set. In the commands listed
1035 below, the field label is the \emph{internal} label. In some cases,
1036 this is the same as the key, but there are a few that have a
1037 different internal label. See Table~\ref*{tab:internalfields} in the
1038 \bibgls\ user manual or Table~4.1 in the \sty{glossaries} user
1039 manual~\cite{glossaries}. Custom fields provided with
1040 \gls{glsaddkey} or \gls{glsaddstoragekey} have matching key and
1041 internal field labels.
1042
1043 The \sty{glossaries-extra} package provides a generic way of
1044 accessing a field, analogous to commands like \gls{glsentryname}:
1045 \nosecformatdef{glsxtrusefield}
1046 This expands to the field value if defined or does nothing if the
1047 entry or field isn't defined.
1048
1049 The base \sty{glossaries} package provides:
1050 \nosecformatdef{ifglshassymbol}
1051 which tests if the \field{symbol} field has been assigned. There are similar
1052 commands for other common fields. For a more general purpose test, you
1053 can use:
1054 \nosecformatdef{ifglshasfield}
1055 which checks if the given entry (identified by \meta{entry label},
1056 which must be defined) has the field identified by \meta{field label}
1057 set to a non-empty value. Within \meta{true}, you can access the
1058 field value with:
1059 \nosecformatdef{glscurrentfieldvalue}
1060 The \sty{glossaries-extra} package provides a similar command:
1061 \nosecformatdef{glsxtrifhasfield}
1062 which doesn't test if the entry exists. The unstarred form adds
1063 implicit grouping around \meta{true} or \meta{false} (allowing
1064 nested use). The starred form \gls{glsxtrifhasfield*} doesn't.
1065 You can compare the field value with a string using:
1066 \nosecformatdef{GlsXtrIfFieldEqStr}
1067 If you need the string to be (protected) fully expanded before
1068 comparison, you need:
1069 \nosecformatdef{GlsXtrIfFieldEqXpStr}
1070 If you additionally need the field value (protected) fully expanded
1071 before comparison, use:
1072 \nosecformatdef{GlsXtrIfXpFieldEqXpStr}
1073 For a complete list of field commands, see the
1074 \sty{glossaries-extra} user manual~\cite{glossaries-extra}.
1075
1076 The earlier \code{duck} and \code{goose} examples from
1077 \sectionref{sec:firstuse} can be rewritten to move the parenthetical
1078 material into separate keys:
1079 \begin{codeenv}
1080 \gls{newglossaryentry}\marg{duck}\comment{label}
1081 \marg{\comment{information about this term:}
1082 \field{name} = \marg{duck},
1083 \field{user1} = \marg{noun},
1084 \field{user2} = \marg{quack, quack},
1085 description = {a waterbird with webbed feet}
1086 }
1087 \strut
1088 \gls{newglossaryentry}\marg{goose}\comment{label}
1089 \marg{\comment{information about this term:}
1090 \field{name} = \marg{goose},
1091 \field{plural} = \marg{geese},
1092 \field{user1} = \marg{noun},
1093 \field{user2} = \marg{honk, honk},
1094 \field{description}=\marg{a large waterbird with a long neck, short legs,
1095 webbed feet and a short broad bill}
1096 }
1097 \end{codeenv}
1098 The \idx{postlinkhook} and glossary style can then be modified to
1099 include the additional information. For example:
1100 \begin{codeenv}
1101 \gls[noindex=false]{glsdefpostlink}\marg{general}\marg{\comment{post-link hook}
1102 \gls[noindex=false]{glsxtrifwasfirstuse}\marg{\cmd{space}(\gls{glsentryuserii}\marg{\gls{glslabel}})}{}\comment{}
1103 }
1104 \strut
1105 \gls[noindex=false]{glssetcategoryattribute}\marg{general}\marg{glossname}\marg{firstuc}
1106 \strut
1107 \gls[noindex=false]{glsdefpostname}\marg{general}\marg{\comment{post-name hook}
1108 \cmd{space}
1109 (\gls{glsentryuseri}\marg{\gls[noindex=false]{glscurrententrylabel}}\comment{}
1110 \gls{GlsXtrIfXpFieldEqXpStr}\marg{plural}\marg{\gls{glscurrententrylabel}}\comment{}
1111 \marg{\gls[noindex=false]{glsentrytext}\marg{\gls{glscurrententrylabel}}s}\marg{}\comment{}
1112 \marg{, pl.\gls{cs.space}\gls[noindex=false]{glsentryplural}{\gls{glscurrententrylabel}}}\comment{}
1113 )\comment{}
1114 }
1115 \end{codeenv}
1116 The \idx{postlinkhook} appends the value of the \field{user2} field
1117 after the \idx{firstuse} of \gls{gls} (or its \idxpl{variant}).
1118 The \catattr{glossname} attribute is set to \code{firstuc}, which
1119 converts the first letter of the \field{name} field to
1120 \idx{uppercase} when it's displayed in the glossary. The
1121 \idx{postnamehook} appends (in parentheses) the value of the
1122 \field{user1} field and then checks if the plural form is the same
1123 as the singular form with \qt{s} appended, and only displays the
1124 plural if they are different. See \sectionref{sec:glsformats} and
1125 \sectionref{sec:displaygloss} for further details.
1126
1127 \section{Accessibility Support}
1128 \label{sec:accsupp}
1129
1130 The base \sty{glossaries} package is distributed with the
1131 supplementary \sty{glossaries-accsupp} package, which uses the
1132 \sty{accsupp} package~\cite{accsupp} to provide accessibility support. With the
1133 \sty{glossaries-extra} extension package, the
1134 \sty{glossaries-accsupp} package needs to be loaded after \sty{glossaries}
1135 but before \sty{glossaries-extra} sets up the accessibility
1136 integration support. The simplest way to do this is with
1137 \sty{glossaries-extra}'s \styopt{accsupp} package option.
1138
1139 The accessibility support is provided through the PDF
1140 \code{ActualText} specification (via the \sty{accsupp} package).
1141 If you need \code{E} or \code{Alt} instead of \code{ActualText} then redefine:
1142 \nosecformatdef{glsaccsupp}
1143 as appropriate. For example:
1144 \begin{codeenv}
1145 \cmd{renewcommand}*\marg{\gls{glsaccsupp}}[2]\marg{\comment{}
1146 \cmd{BeginAccSupp}\marg{Alt=\marg{\gls{param}1}}\gls{param}2\cmd{EndAccSupp}\marg{}\comment{}
1147 }
1148 \end{codeenv}
1149
1150 The \sty{glossaries-accsupp} package provides additional keys (see
1151 Table~\ref{tab:accsuppfields} in the \bibgls\ user manual or
1152 Chapter~18 of the \sty{glossaries} user manual~\cite{glossaries}).
1153 The main keys are \field{access}, which provides an alternative to
1154 the \field{name} field, \field{symbolaccess}, which provides an
1155 alternative to the \field{symbol} field and \field{shortaccess},
1156 which provides an alternative to the \field{short} field,
1157 \field{firstaccess}, which provides an alternative to the
1158 \field{first} field, and \field{textaccess}, which provides an
1159 alternative to the \field{text} field. If any of the accessibility
1160 fields are unset, no accessibility support is provided for that
1161 field.
1162 For example:
1163 \begin{codeenv}
1164 \gls{newglossaryentry}\marg{R}\comment{label}
1165 \marg{\comment{settings:}
1166 \field{name} = \marg{\cmd{ensuremath}\marg{\cmd{Re}}},
1167 \field{access} = \marg{set of real numbers symbol},\comment{name access}
1168 \field{textaccess} = \marg{set of real numbers},\comment{text access}
1169 \field{firstaccess} = \marg{set of real numbers},\comment{first access}
1170 \field{description} = \marg{set of real numbers}
1171 }
1172 \end{codeenv}
1173 This means that when the \field{name} field is displayed in the
1174 glossary, the corresponding accessibility text is \qt{set of real
1175 numbers symbol}, but the \idx{link-text} for \gls{gls} is just
1176 \qt{set of real numbers} (for both \idx{firstuse} and subsequent
1177 use).
1178
1179 There are some category attributes that govern the default settings
1180 of some fields when using \gls{newabbreviation} (see
1181 \sectionref{sec:abbreviations}). If accessibility support is
1182 provided, there are some additional attributes (introduced to
1183 \sty{glossaries-extra} version 1.31):
1184 \begin{description}
1185 \item[\catattr{accessinsertdots}] This is a boolean attribute that behaves like
1186 \catattr{insertdots} but only applies to the \field{shortaccess}
1187 field, if it hasn't explicitly been set. This is useful for
1188 initialisms that should be read out as letters but the screen reader
1189 might interpret as a word. For example:
1190 \begin{codeenv}
1191 \gls{glssetcategoryattribute}\marg{initialism}\marg{\catattr{accessinsertdots}}\marg{true}
1192 \gls{newabbreviation}\oarg{\field{category}=initialism}\marg{pi}\marg{PI}\marg{Private Investigator}
1193 \end{codeenv}
1194 This means that the short form appears as just \qt{PI} in the
1195 document text, but the accessibility text is \qt{P.I.} which prompts
1196 the screen reader to read it as an abbreviation instead of the word
1197 \qt{pi}. Since the \field{shortaccess} field is an aid to the screen
1198 reader and doesn't modify the visible text, there's no check
1199 for the \catattr{retainfirstuseperiod} or \catattr{discardperiod}
1200 attributes for that field. This setting doesn't affect the
1201 accessibility support for the \field{name}, \field{first} or
1202 \field{text} fields.
1203
1204 \item[\catattr{nameshortaccess}] This is a boolean attribute, where
1205 the value \code{true} indicates the attribute is set. If the
1206 \field{shortaccess} field is assigned (either explicitly with the key or
1207 implicitly through the use of the \catattr{accessinsertdots}
1208 attribute) and the \field{access} field isn't specified, then if the
1209 \catattr{nameshortaccess} attribute is set this will copy the
1210 \field{shortaccess} field to the \field{access} field. For example:
1211 \begin{codeenv}
1212 \gls{glssetcategoryattribute}\marg{initialism}\marg{\catattr{accessinsertdots}}\marg{true}
1213 \gls{glssetcategoryattribute}\marg{initialism}\marg{\catattr{nameshortaccess}}\marg{true}
1214 \gls{newabbreviation}\oarg{\field{category}=initialism}\marg{pi}\marg{PI}\marg{Private Investigator}
1215 \end{codeenv}
1216 Abbreviations that behave like regular terms (such as
1217 \abbrstyle{short-nolong}) may also need \catattr{textshortaccess}
1218 and \catattr{firstshortaccess} set.
1219
1220 \item[\catattr{textshortaccess}] Like \catattr{nameshortaccess}, but
1221 applies to the \field{textaccess} field.
1222
1223 \item[\catattr{firstshortaccess}] Like \catattr{firstshortaccess}, but
1224 applies to the \field{firstaccess} field.
1225
1226 \item[\catattr{accessaposplural}] If the \field{shortaccess} field
1227 is set (either explicitly with the key or implicitly through the use
1228 of the \catattr{accessinsertdots} attribute) and the
1229 \field{shortpluralaccess} field isn't set, the
1230 \catattr{accessaposplural} boolean attribute behaves like
1231 \catattr{aposplural} but only applies to the
1232 \field{shortpluralaccess} field. If the \catattr{accessaposplural}
1233 attribute isn't set but the \catattr{aposplural} attribute is set,
1234 then that's used instead. If you want \catattr{aposplural} on but
1235 not apply it to \field{shortpluralaccess} then you need to set the
1236 \catattr{accessaposplural} attribute to \code{false}.
1237
1238 \item[\catattr{accessnoshortplural}] A boolean attribute like
1239 \catattr{accessaposplural} but analogous to \catattr{noshortplural}
1240 instead.
1241 \end{description}
1242 These attributes have no effect for entries that aren't defined
1243 using \gls{newabbreviation}. (These attributes apply to
1244 \gls{newacronym} provided it internally uses \gls{newabbreviation},
1245 which is does by default with \sty{glossaries-extra}.)
1246
1247 \section{Prefixes}
1248 \label{sec:prefixes}
1249
1250 The \sty{glossaries} package is distributed with the supplementary
1251 \sty{glossaries-prefix} package. This automatically loads
1252 \sty{glossaries}, but if you are using \sty{glossaries-extra}, it's
1253 best loaded after. This supplementary package supplies extra keys
1254 and some commands analogous to \gls{gls}. The main purpose is to
1255 provide a different prefix to \gls{gls}, depending on whether it's
1256 the \idx{firstuse} or subsequent use. For example, if the
1257 \idx{firstuse} starts with a vowel (or vowel sound), you may need \qt{an
1258 \gls{gls}\margm{label}} but if the subsequent use starts with a
1259 constant, you may need \qt{a \gls{gls}\margm{label}}. The prefix for
1260 the \idx{firstuse} form is specified in the \field{prefixfirst}
1261 field, and the prefix for the subsequent use form is specified in the
1262 \field{prefix} field. If a space is required between the prefix and
1263 \gls{gls}, this needs to be included, as the prefixing system allows
1264 for prefixes like l' which shouldn't be followed by a space.
1265
1266 To include the prefix, use:
1267 \nosecformatdef{pgls}
1268 instead of \gls{gls}. For example:
1269 \begin{codeenv}
1270 \cmd{documentclass}\marg{book}
1271 \strut
1272 \cmd{usepackage}\marg{glossaries-extra}
1273 \cmd{usepackage}\marg{glossaries-prefix}
1274 \strut
1275 \gls{newabbreviation}
1276 \oarg{\field{prefixfirst}=\marg{a\gls[noindex=false]{nbspchar}},\field{prefix}=\marg{an\cmd{space}}}
1277 \marg{svm}\marg{SVM}\marg{support vector machine}
1278 \strut
1279 \cmd{begin}\marg{document}
1280 With a prefix: \gls{pgls}\marg{svm} or \gls{pgls}\marg{svm}.
1281 Without a prefix: the \gls{gls}\marg{svm}.
1282 \cmd{end}\marg{document}
1283 \end{codeenv}
1284 This produces:
1285 \begin{result}
1286 With a prefix: a support vector machine (SVM) or an SVM. Without a
1287 prefix: the SVM.
1288 \end{result}
1289
1290 \section{Spaces}
1291 \label{sec:spaces}
1292
1293 With \LaTeX\ in general, spaces are sometimes significant and
1294 sometimes ignored. When defining entries, any spaces around the
1295 equal sign or comma are ignored. For example, if an entry is defined
1296 as
1297 \begin{codeenv}
1298 \gls{newglossaryentry}\marg{sample}
1299 \marg{
1300 \field{name} = \marg{sample} , \field{description} = \marg{an example}
1301 }
1302 \end{codeenv}
1303 then
1304 \begin{codeenv}
1305 /\gls{gls}\marg{sample}/
1306 \end{codeenv}
1307 will produce
1308 \begin{result}
1309 /sample/
1310 \end{result}
1311 (no spaces). Similarly with:
1312 \begin{codeenv}
1313 \gls{newglossaryentry}\marg{sample}
1314 \marg{
1315 \field{name} = sample , \field{description} = \marg{an example}
1316 }
1317 \end{codeenv}
1318 However, spaces at the start or end of the value that's provided as
1319 an argument (rather than in a \keyvallist) often aren't ignored.
1320
1321 The unstarred version of \gls{longnewglossaryentry} appends extra code to the end of the
1322 description, which removes any trailing spaces (and also the
1323 \gls{postdescriptionhook}). The starred version
1324 \gls{longnewglossaryentry*} (only available with \sty{glossaries-extra})
1325 doesn't. In both cases any leading spaces are retained. For example,
1326 if the entry is defined as:
1327 \begin{codeenv}
1328 \gls{longnewglossaryentry}\marg{sample}\marg{name=\marg{sample}}\marg{ an example }\incorrect
1329 \end{codeenv}
1330 then:
1331 \begin{codeenv}
1332 /\gls{glsentrydesc}\marg{sample}/
1333 \end{codeenv}
1334 produces:
1335 \begin{result}
1336 / an example/
1337 \end{result}
1338 (trailing space removed), whereas if the entry is defined as:
1339 \begin{codeenv}
1340 \gls{longnewglossaryentry*}\marg{sample}\marg{name=\marg{sample}}\marg{ an example }\incorrect
1341 \end{codeenv}
1342 then:
1343 \begin{codeenv}
1344 /\gls{glsentrydesc}\marg{sample}/
1345 \end{codeenv}
1346 produces:
1347 \begin{result}
1348 / an example /
1349 \end{result}
1350 (leading and trailing spaces retained).
1351
1352 Spaces in labels are significant. For example, in \verb|\gls{ duck }|
1353 the spaces are considered part of the label. If the entry was
1354 actually defined without spaces in the label then the entry
1355 referenced in \verb|\gls{ duck }| won't be found.
1356
1357 \section{Undefined References}
1358 \label{sec:undefaction}
1359
1360 If an entry that hasn't been defined is referenced with \gls{gls},
1361 by default an error is triggered. For example:
1362 \begin{codeenv}
1363 \cmd{documentclass}\marg{article}
1364 \strut
1365 \cmd{usepackage}\marg{glossaries}
1366 \strut
1367 \cmd{begin}\marg{document}
1368 A \gls{gls}\marg{duck}.
1369 \cmd{end}\marg{document}
1370 \end{codeenv}
1371 This produces the error:
1372 \begin{verbatim}
1373 Glossary entry `duck' has not been defined.
1374 \end{verbatim}
1375 If you instruct \LaTeX\ to ignore the error and continue, the result
1376 is
1377 \begin{result}
1378 A .
1379 \end{result}
1380 The \sty{glossaries-extra} package provides the option
1381 \styopt[warn]{undefaction}, which will convert the error to a
1382 warning. For example:
1383 \begin{codeenv}
1384 \cmd{documentclass}\marg{article}
1385 \strut
1386 \cmd{usepackage}[\styopt{undefaction}=warn]\marg{glossaries-extra}
1387 \strut
1388 \cmd{begin}\marg{document}
1389 A \gls{gls}\marg{duck}.
1390 \cmd{end}\marg{document}
1391 \end{codeenv}
1392 This now produces the warning:
1393 \begin{verbatim}
1394 Glossary entry `duck' has not been defined on input line 6
1395 \end{verbatim}
1396 (There are also other warnings about an empty \code{main} glossary.)
1397 The result is now:
1398 \begin{result}
1399 A ??.
1400 \end{result}
1401 This replaces the undefined reference with two question marks, just like
1402 undefined cross-references.
1403 Notice the difference between using \gls{ifglshasfield}:
1404 \begin{codeenv}
1405 \cmd{documentclass}\marg{article}
1406 \strut
1407 \cmd{usepackage}[\styopt{undefaction}=warn]\marg{glossaries-extra}
1408 \strut
1409 \cmd{begin}\marg{document}
1410 A \gls{gls}\marg{duck}
1411 (\gls{ifglshasfield}\marg{\gls[noindex=false]{field.useri}}\marg{duck}\marg{\gls{glscurrentfieldvalue}}\marg{not set}).
1412 \cmd{end}\marg{document}
1413 \end{codeenv}
1414 which produces:
1415 \begin{result}
1416 A ?? (??).
1417 \end{result}
1418 (and has two undefined warnings) and using \gls{glsxtrifhasfield}:
1419 \begin{codeenv}
1420 \cmd{documentclass}\marg{article}
1421 \strut
1422 \cmd{usepackage}[\styopt{undefaction}=warn]\marg{glossaries-extra}
1423 \strut
1424 \cmd{begin}\marg{document}
1425 A \gls{gls}\marg{duck}
1426 (\gls{glsxtrifhasfield}\marg{\field{useri}}\marg{duck}\marg{\gls{glscurrentfieldvalue}}\marg{not set}).
1427 \cmd{end}\marg{document}
1428 \end{codeenv}
1429 which only has one undefined warning and produces:
1430 \begin{result}
1431 A ?? (not set).
1432 \end{result}
1433
1434 When you incorporate \bibgls\ into the build process (see
1435 \sectionref{sec:bib2gls}), the first \LaTeX\ run doesn't have any
1436 entries defined. One of the actions that the \styopt{record} option
1437 automatically performs is to switch on \styopt[warn]{undefaction}, which avoids
1438 undefined errors on the first \LaTeX\ run. For example:
1439 \begin{codeenv}
1440 \cmd{documentclass}\marg{article}
1441 \strut
1442 \cmd{usepackage}[\styopt{record}]\marg{glossaries-extra}
1443 \strut
1444 \cmd{begin}\marg{document}
1445 A \gls{gls}\marg{duck}
1446 (\gls{glsxtrifhasfield}\marg{\field{useri}}\marg{duck}\marg{\gls{glscurrentfieldvalue}}\marg{not set}).
1447 \cmd{end}\marg{document}
1448 \end{codeenv}
1449 This produces the same result as the previous example, but there's
1450 only the one warning (about an undefined reference) and no warning
1451 about the empty \code{main} glossary.
1452
1453 \section{Robust, Fragile and Expandable Commands}
1454 \label{sec:robust}
1455
1456 Commands like \gls{gls} are \pidx{robust}. This protects them from
1457 premature expansion in situations that would otherwise break the
1458 command. If content containing a \idx{robust} command is written to
1459 an external file, the \idx{robust} command itself is written instead of its
1460 definition. For example, consider the following document:
1461 \begin{codeenv}
1462 \cmd{documentclass}\marg{article}
1463 \cmd{newcommand}\marg{\csfmt{test}}\marg{some sample text}
1464 \cmd{begin}\marg{document}
1465 \gls{tableofcontents}
1466 \gls[noindex=false]{section}\marg{\csfmt{test}}
1467 \cmd{end}\marg{document}
1468 \end{codeenv}
1469 In this case, \csfmt{test} is expandable. Its definition doesn't
1470 contain anything complicated. The \ext{toc} file (which is input by
1471 \csfmt{tableofcontents}\glsadd{toc}) contains the line:
1472 \begin{codeenv}
1473 \cmd{contentsline} \marg{section}\marg{\cmd{numberline} \marg{1}some sample text}\marg{1}
1474 \end{codeenv}
1475 So \csfmt{test} has been expanded to its definition when it was
1476 written to the \ext{toc} file. If \csfmt{test} is defined in terms
1477 of another command, that will also be expanded. For example:
1478 \begin{codeenv}
1479 \cmd{documentclass}\marg{article}
1480 \cmd{newcommand}\marg{\csfmt{sample}}\marg{\gls{emph}\marg{sample}}
1481 \cmd{newcommand}\marg{\csfmt{test}}\marg{some \csfmt{sample}\gls{cs.space}text}
1482 \cmd{begin}\marg{document}
1483 \gls{tableofcontents}
1484 \gls{section}\marg{\csfmt{test}}
1485 \cmd{end}\marg{document}
1486 \end{codeenv}
1487 The \ext{toc} file now contains:
1488 \begin{codeenv}
1489 \cmd{contentsline} \marg{section}\marg{\cmd{numberline} \marg{1}some \gls{emph} \marg{sample}\gls{cs.space}text}\marg{1}
1490 \end{codeenv}
1491 So \csfmt{sample} has also been expanded but neither
1492 \gls{emph} nor \idx{cs.space} (backslash space) have
1493 been expanded. \Idx{robust} commands don't expand. For example:
1494 \begin{codeenv}
1495 \cmd{documentclass}\marg{article}
1496 \strut
1497 \cmd{usepackage}\marg{glossaries}
1498 \strut
1499 \gls{newglossaryentry}\marg{duck}
1500 \marg{
1501 \field{name}=\marg{duck},
1502 \field{description}=\marg{a waterbird with webbed feet}
1503 }
1504 \strut
1505 \cmd{begin}\marg{document}
1506 \gls{tableofcontents}
1507 \gls{section}\marg{\gls{Gls}\marg{duck}: \gls{glsentrydesc}\marg{duck}}
1508 \cmd{end}\marg{document}
1509 \end{codeenv}
1510 The \ext{toc} file now contains:
1511 \begin{codeenv}
1512 \cmd{contentsline} \marg{section}\marg{\cmd{numberline} \marg{1}\gls{Gls} \marg{duck}: a waterbird with
1513 webbed feet}\marg{1}
1514 \end{codeenv}
1515 So \gls{Gls} doesn't expand, and the command itself is written to the
1516 \ext{toc} file, but \gls{glsentrydesc} does expand.
1517
1518 A \pidx{fragile} command is one that breaks (causes an error) when
1519 it's expanded in this type of context. One such command is \gls{footnote}.
1520 For example, the following won't work:
1521 \begin{codeenv}
1522 \cmd{documentclass}\marg{article}
1523 \strut
1524 \cmd{usepackage}\marg{glossaries}
1525 \strut
1526 \gls{newglossaryentry}\marg{duck}
1527 \marg{
1528 \field{name}=\marg{duck},
1529 \field{description}=\marg{a waterbird with webbed feet}
1530 }
1531 \strut
1532 \cmd{begin}\marg{document}
1533 \gls{tableofcontents}
1534 \gls{section}\marg{\gls{Gls}\marg{duck}\gls{footnote}\marg{\gls{glsentrydesc}\marg{duck}}}\incorrect
1535 \cmd{end}\marg{document}
1536 \end{codeenv}
1537 This causes the error:
1538 \begin{verbatim}
1539 ! Argument of \@sect has an extra }.
1540 \end{verbatim}
1541 Inserting \gls{protect} before the command prevents the attempted
1542 expansion, which makes the command behave as though it was robust:
1543 \begin{codeenv}
1544 \gls{section}\marg{\gls{Gls}\marg{duck}\gls{protect}\gls{footnote}\marg{\gls{glsentrydesc}\marg{duck}}}
1545 \end{codeenv}
1546 In this case, it's unlikely that you'd want the footnote to appear
1547 in the \gls{toc}, so it would be better to use the optional
1548 argument:
1549 \begin{codeenv}
1550 \gls{section}\oarg{Duck}\marg{\gls{Gls}\marg{duck}\gls{footnote}\marg{\gls{glsentrydesc}\marg{duck}}}\correct
1551 \end{codeenv}
1552 Now the \ext{toc} file is just:
1553 \begin{codeenv}
1554 \cmd{contentsline} \marg{section}\marg{\cmd{numberline} \marg{1}Duck}\marg{1}
1555 \end{codeenv}
1556 If the \field{description} field contains a \idx{fragile} command
1557 then \gls{glsentrydesc} will break in expandable contexts. For
1558 example, the following doesn't work:
1559 \begin{codeenv}
1560 \cmd{documentclass}\marg{article}
1561 \strut
1562 \cmd{usepackage}\marg{glossaries}
1563 \strut
1564 \gls{newglossaryentry}\marg{duck}
1565 \marg{
1566 \field{name}=\marg{duck},
1567 \field{description}=\marg{a waterbird\gls{footnote}\marg{a bird that lives on or
1568 near water} with webbed feet}
1569 }
1570 \strut
1571 \cmd{begin}\marg{document}
1572 \gls{tableofcontents}
1573 \gls{section}\marg{\gls{Gls}\marg{duck}: \gls{glsentrydesc}\marg{duck}}\incorrect
1574 \cmd{end}\marg{document}
1575 \end{codeenv}
1576 This is a contrived example. In this case, it would be better to
1577 also define the term \qt{waterbird}:
1578 \begin{codeenv}
1579 \cmd{documentclass}\marg{article}
1580 \strut
1581 \cmd{usepackage}\marg{glossaries}
1582 \strut
1583 \gls{newglossaryentry}\marg{waterbird}
1584 \marg{
1585 \field{name}=\marg{waterbird},
1586 \field{description}=\marg{a bird that lives on or near water}
1587 }
1588 \strut
1589 \gls{newglossaryentry}\marg{duck}
1590 \marg{
1591 \field{name}=\marg{duck},
1592 \field{description}=\marg{a \gls{gls}\marg{waterbird} with webbed feet}
1593 }
1594 \strut
1595 \cmd{begin}\marg{document}
1596 \gls{tableofcontents}
1597 \gls{section}\marg{\gls{Gls}\marg{duck}: \gls{glsentrydesc}\marg{duck}}
1598 \cmd{end}\marg{document}
1599 \end{codeenv}
1600 The \ext{toc} file now contains:
1601 \begin{codeenv}
1602 \cmd{contentsline} \marg{section}\marg{\cmd{numberline} \marg{1}\gls{Gls} \marg{duck}: a \gls{gls} \marg{waterbird}
1603 with webbed feet}\marg{1}
1604 \end{codeenv}
1605
1606 \begin{important}
1607 The examples in this section are used to illustrate the differences
1608 between \idx{fragile}, \idx{robust} and \idx{expandable} commands.
1609 In general, it's better not to use commands like \gls{gls} in
1610 headings or captions (see \sectionref{sec:headings}). Using
1611 commands like \gls{gls} in field values can be problematic (see
1612 \sectionref{sec:nested}).
1613 \end{important}
1614
1615 By default, most of the field values are expanded when the entry is
1616 defined. This allows for defining entries programmatically, but it
1617 can cause a problem if the value contains any \idx{fragile} commands.
1618 For example:
1619 \begin{codeenv}
1620 \cmd{documentclass}\marg{article}
1621 \strut
1622 \cmd{usepackage}\marg{glossaries}
1623 \strut
1624 \gls{newglossaryentry}\marg{duck}\comment{label}
1625 \marg{
1626 \field{name} = \marg{duck},
1627 \field{first} = \marg{duck\gls{footnote}\marg{quack, quack}},\incorrect
1628 \field{description} = \marg{a waterbird with webbed feet}
1629 }
1630 \strut
1631 \cmd{begin}\marg{document}
1632 A \gls{gls}\marg{duck}.
1633 \cmd{end}\marg{document}
1634 \end{codeenv}
1635 This causes the confusing error:
1636 \begin{verbatim}
1637 ! Undefined control sequence.
1638 \in@ #1#2->\begingroup \def \in@@
1639 \end{verbatim}
1640 In order for this example to work, the \idx{fragile} command must either be
1641 protected:
1642 \begin{codeenv}
1643 \gls{newglossaryentry}\marg{duck}\comment{label}
1644 \marg{
1645 \field{name} = \marg{duck},
1646 \field{first} = \marg{duck\gls{protect}\gls{footnote}\marg{quack, quack}},\correct
1647 \field{description} = \marg{a waterbird with webbed feet}
1648 }
1649 \end{codeenv}
1650 or the expansion must first be switched off:
1651 \begin{codeenv}
1652 \gls{glsnoexpandfields} \correct
1653 \gls{newglossaryentry}\marg{duck}\comment{label}
1654 \marg{
1655 \field{name} = \marg{duck},
1656 \field{first} = \marg{duck\gls{footnote}\marg{quack, quack}},
1657 \field{description} = \marg{a waterbird with webbed feet}
1658 }
1659 \end{codeenv}
1660 Since it's not possible to programmatically define entries with
1661 \bibgls, the expansion is automatically switched off as \bibgls\
1662 writes \gls{glsnoexpandfields} to the \ext{glstex} file (although
1663 you can disable this feature with \longarg{expand-fields}).
1664
1665 The reason why \gls{footnote} didn't cause a problem in the
1666 \field{description} field \emph{when the entry was defined} is that, by
1667 default, expansion isn't performed on the \field{name},
1668 \field{description} and \field{symbol} fields, regardless of whether
1669 or not \gls{glsnoexpandfields} has been used. This only applies to
1670 the point when the entries are being defined. Unprotected
1671 \idx{fragile} commands can still cause a problem if the value is
1672 later used in a problematic context (such as the earlier example
1673 where \gls{glsentrydesc} was used in a section heading).
1674
1675 \chapter{Abbreviations}
1676 \label{sec:abbreviations}
1677
1678 The abbreviation handling provided by the base \isty{glossaries}
1679 package is quite restrictive and only one abbreviation style can be
1680 used for all abbreviations. The \isty{glossaries-extra} package
1681 internally loads the \sty{glossaries} package and extends it,
1682 providing new options and a better abbreviation mechanism that
1683 allows different styles per category.
1684
1685 The base \sty{glossaries} package provides:
1686 \nosecformatdef{newacronym}
1687 The extension package \sty{glossaries-extra} provides:
1688 \nosecformatdef{newabbreviation}
1689 which internally uses \gls{newglossaryentry} with the
1690 \field{category} set to \code{abbreviation} (which can be
1691 overridden in the optional \meta{\keyvallist}).
1692 The \gls{glossaries-extra} package also redefines \gls{newacronym} in
1693 terms of \gls{newabbreviation} so that it effectively behaves like:
1694 \begin{codeenv}
1695 \gls{newabbreviation}\oarg{\gls[noindex=false]{field.type}=\gls{acronymtype},\field{category}=acronym,\meta{\keyvallist}}
1696 \margm{label}\margm{short}\margm{long}
1697 \end{codeenv}
1698 This makes it easier to transfer over from the base \sty{glossaries}
1699 package, but if you use \gls{newacronym} remember that the
1700 \field{category} is set to \code{acronym} instead of \code{abbreviation}.
1701
1702 In both cases, \meta{label} is the entry's label used to identify
1703 the abbreviation in commands like \gls{gls}, \meta{short} is the
1704 short form and \meta{long} is the long form. Any additional
1705 settings, such as the \field{category} or \field{description}
1706 can be set in the optional argument.
1707
1708 The style must be set \emph{before the abbreviations are defined}
1709 using:
1710 \nosecformatdef{setabbreviationstyle}
1711 where \meta{category} is the category label and \meta{style-name} is
1712 the name of the style. If the optional argument is omitted,
1713 \code{abbreviation} is assumed. The \sty{glossaries-extra} package
1714 automatically sets the default styles:
1715 \begin{codeenv*}
1716 \gls{setabbreviationstyle}\marg{\abbrstyle{long-short}}
1717 \gls{setabbreviationstyle}\oarg{acronym}\marg{\abbrstyle{short-nolong}}
1718 \end{codeenv*}
1719 This means that if you don't explicitly set the style then any
1720 abbreviation defined with \gls{newacronym} will use the
1721 \abbrstyle{short-nolong} style (unless you change the category in
1722 the optional argument) and other abbreviations will use the
1723 \abbrstyle{long-short} style.
1724
1725 If these styles aren't suitable, then you need to change them. Any
1726 abbreviation that's defined with a category that hasn't been
1727 assigned a style will fallback on the style for the default
1728 \code{abbreviation} category. There are many predefined styles to
1729 choose from and they come with commands to help adjust the
1730 formatting. See the \sty{glossaries-extra} user
1731 manual~\cite{glossaries-extra} for the
1732 complete list. The \sty{glossaries-extra} package also comes with a
1733 sample document
1734 \ctanfile{glossaries-extra/samples}{sample-abbr-styles.pdf}
1735 demonstrating all the predefined styles.
1736
1737 The style determines whether the abbreviation is treated as a
1738 \idx{regular} term. There are also some \idxpl{categoryattribute} that govern
1739 abbreviations (see below and \sectionref{sec:accsupp}). These
1740 should also be set before the abbreviation is defined.
1741
1742 Some of the styles set the \field{description} field (typically to
1743 the \meta{long} form). The styles that end with \code{-desc} don't,
1744 and so that key must be set explicitly in the \meta{\keyvallist} optional part.
1745
1746 Here's a simple example that uses both \gls{newabbreviation} and
1747 \gls{newacronym} to illustrate the difference:
1748 \begin{codeenv}
1749 \cmd{documentclass}\marg{article}
1750 \strut
1751 \cmd{usepackage}\marg{glossaries-extra}
1752 \strut
1753 \gls{newabbreviation}\marg{tug}\marg{TUG}\marg{\cmd{TeX}\gls{cs.space}Users Group}
1754 \gls{newabbreviation}\marg{cldr}\marg{CLDR}\marg{Unicode Common Locale Data
1755 Repository}
1756 \strut
1757 \gls{newacronym}\marg{SIunit}\marg{SI unit}\marg{International System of Units}
1758 \gls{newacronym}\marg{ascii}\marg{ASCII}\marg{American Standard Code for
1759 Information Interchange}
1760 \strut
1761 \cmd{begin}\marg{document}
1762 First use: \gls{gls}\marg{tug}, \gls{gls}\marg{cldr}, \gls{gls}\marg{SIunit}, \gls{gls}\marg{ascii}.
1763 Next use: \gls{gls}\marg{tug}, \gls{gls}\marg{cldr}, \gls{gls}\marg{SIunit}, \gls{gls}\marg{ascii}.
1764 \cmd{end}\marg{document}
1765 \end{codeenv}
1766 This produces:
1767 \begin{result}
1768 First use: \gls{TUG}, \gls{CLDR}, \gls{SIunit}, \gls{ASCII}.
1769 Next use: \gls{TUG}, \gls{CLDR}, \gls{SIunit}, \gls{ASCII}.
1770 \end{result}
1771 Note that the \idx{firstuse} of \code{SIunit} and \code{ascii} only
1772 show the short form. This is because the default style for the
1773 \code{acronym} category is the \abbrstyle{short-nolong} style, which
1774 doesn't show the long form with \gls{gls} (and its \idxpl{variant}).
1775
1776 The final optional \meta{insert} argument of commands like \gls{gls}
1777 is typically moved inside, depending on the style. For example:
1778 \begin{codeenv}
1779 \cmd{documentclass}\marg{article}
1780 \strut
1781 \cmd{usepackage}\marg{glossaries-extra}
1782 \strut
1783 \gls{newabbreviation}\marg{svm}\marg{SVM}\marg{support vector machine}
1784 \strut
1785 \cmd{begin}\marg{document}
1786 The \gls{gls}\marg{svm}\oarg{'s} parameters are\cmd{ldots}
1787 \cmd{end}\marg{document}
1788 \end{codeenv}
1789 This produces:
1790 \begin{result}
1791 The \gls{ex.svm}['s] parameters are\ldots
1792 \end{result}
1793 Compare this with:
1794 \begin{codeenv}
1795 The \gls{gls}\marg{svm}'s parameters are\cmd{ldots}\incorrect
1796 \end{codeenv}
1797 which produces:
1798 \begin{result}
1799 The \gls{ex.svm}'s parameters are\ldots
1800 \end{result}
1801
1802 \section{Only Long or Only Short}
1803 \label{sec:longorshort}
1804
1805 If you only want \gls{gls} to show the short form but not the long
1806 form (including on \idx{firstuse}), use one of the \code{-nolong}
1807 styles (such as \abbrstyle{short-nolong}). If you only want the long
1808 form and not the short form (including subsequent use), use one of
1809 the \code{-noshort} styles (such as \abbrstyle{long-noshort}).
1810
1811 If you want only the long form on \idx{firstuse} (without the short
1812 form) and only the short form subsequently then use one of the
1813 \code{-only} styles, such as \abbrstyle{long-only-short-only}.
1814
1815 If you need to reshow the full form, you can reset the
1816 \idx{firstuseflag} with:
1817 \nosecformatdef{glsreset}
1818 which will make the next instance of \code{\gls{gls}\margm{labe}}
1819 act according to \idx{firstuse}.
1820
1821 \begin{important}
1822 If you need an abbreviation in a caption or section title, see
1823 \sectionref{sec:headings}.
1824 \end{important}
1825
1826 Otherwise, if you want a \emph{specific} instance to show only the short
1827 form, without modifying the \idx{firstuseflag}, then use
1828 \nosecformatdef{glsxtrshort}
1829 If you want a specific instance to show only the long form, without
1830 modifying the \idx{firstuseflag}, then use
1831 \nosecformatdef{glsxtrlong}
1832 If you want a specific instance to show both the long and short form, without
1833 modifying the \idx{firstuseflag}, then use
1834 \nosecformatdef{glsxtrfull}
1835 Depending on the style, this may not exactly match the format
1836 produced by the \idx{firstuse} of \code{\gls{gls}\margm{label}}.
1837 Don't use these commands for every use. Change the style instead,
1838 which will make it easier to modify the document at a later date.
1839
1840 If you find these commands quite long-winded, there are some
1841 shortcuts available with the \styopt{shortcuts} option, but as these
1842 may interfere with other packages, you might want to consider
1843 investigating your text editor settings as the more sophisticated
1844 ones provide ways of inserting commonly-used commands to save typing.
1845
1846 \section{Plural Abbreviations}
1847 \label{sec:pluralabbr}
1848
1849 If the abbreviation represents something countable then the plural
1850 form can again be obtained with \gls{glspl}:
1851 \begin{codeenv}
1852 \cmd{documentclass}\marg{article}
1853 \strut
1854 \cmd{usepackage}\marg{glossaries-extra}
1855 \strut
1856 \gls{newabbreviation}\marg{svm}\marg{SVM}\marg{support vector machine}
1857 \strut
1858 \cmd{begin}\marg{document}
1859 First use: \gls{glspl}\marg{svm}. Next use: \gls{glspl}\marg{svm}.
1860 \cmd{end}\marg{document}
1861 \end{codeenv}
1862 This produces:
1863 \begin{result}
1864 First use: \glspl{ex.svm}. Next use: \glspl{ex.svm}.
1865 \end{result}
1866 The default plural short and long forms are obtained by
1867 appending the letter \qt{s} after the singular form. These can be
1868 changed on an individual basis with the \field{shortplural} and
1869 \field{longplural} keys. For example:
1870 \begin{codeenv}
1871 \gls{newabbreviation}
1872 [\field{longplural}=\marg{lower triangular matrices}]
1873 \marg{ltm}\marg{LTM}\marg{lower triangular matrix}
1874 \end{codeenv}
1875
1876 It may be that you prefer to keep the short plural form the same as
1877 the short singular value for all abbreviations within a particular
1878 category. You can implement this with the
1879 \catattr{noshortplural} attribute, which must be set to \code{true}
1880 before the abbreviations for that category are defined. For example:
1881 \begin{codeenv}
1882 \gls{glssetcategoryattribute}\marg{abbreviation}\marg{\catattr{noshortplural}}\marg{true}
1883 \gls{newabbreviation}\marg{svm}\marg{SVM}\marg{support vector machine}
1884 \end{codeenv}
1885 Now:
1886 \begin{codeenv}
1887 First use: \gls{glspl}\marg{svm}. Next use: \gls{glspl}\marg{svm}.
1888 \end{codeenv}
1889 produces:
1890 \begin{result}
1891 First use: support vector machines (SVM). Next use: SVM.
1892 \end{result}
1893 A related attribute is \catattr{aposplural} which inserts \qtt{'s}
1894 (apostrophe followed by \qt{s}) to form the default short plural to
1895 help avoid ambiguity with \idx{lowercase} abbreviations where it might
1896 not be obvious that the \qt{s} indicates a plural (rather than
1897 another letter in the abbreviation). Again, this needs to be set
1898 before the abbreviations for the given category (or categories) are
1899 defined (but check with your supervisor, publisher or editor as this
1900 usage is controversial).
1901
1902 \section{Abbreviation Markup}
1903 \label{sec:markwords}
1904
1905 The \catattr{markwords} attribute can be set to \code{true} to
1906 indicate that \gls{newabbreviation} should parse the long form and
1907 markup the words using:
1908 \nosecformatdef{glsxtrword}
1909 The words are separated with
1910 \nosecformatdef{glsxtrwordsep}
1911 For example:
1912 \begin{codeenv}
1913 \gls{glssetcategoryattribute}\marg{abbreviation}\marg{\catattr{markwords}}\marg{true}
1914 \gls{newabbreviation}\marg{ssl}\marg{SSL}\marg{Secure Sockets Layer}
1915 \end{codeenv}
1916 This is essentially the same as
1917 \begin{codeenv}
1918 \gls{newabbreviation}\marg{ssl}\marg{SSL}\marg{\gls{glsxtrword}\marg{Secure}\gls{glsxtrwordsep}
1919 \gls{glsxtrword}\marg{Sockets}\gls{glsxtrwordsep}\gls{glsxtrword}\marg{Layer}}
1920 \end{codeenv}
1921 This is typically used with the \code{-hyphen} abbreviation styles,
1922 such as \abbrstyle{long-hyphen-short-hyphen}.
1923 If the final optional \meta{insert} argument of commands like
1924 \gls{gls} starts with a hyphen, \gls{glsxtrwordsep} is locally
1925 changed to a hyphen.
1926
1927 For example:
1928 \begin{codeenv}
1929 \cmd{documentclass}\marg{article}
1930 \strut
1931 \cmd{usepackage}\marg{glossaries-extra}
1932 \strut
1933 \gls{setabbreviationstyle}\marg{\abbrstyle[noindex=false]{long-hyphen-short-hyphen}}
1934 \strut
1935 \gls{glssetcategoryattribute}\marg{abbreviation}\marg{\catattr{markwords}}\marg{true}
1936 \strut
1937 \gls{newabbreviation}\marg{ssl}\marg{SSL}\marg{Secure Sockets Layer}
1938 \strut
1939 \cmd{begin}\marg{document}
1940 First use: \gls{gls}\marg{ssl}\oarg{-enabled}. Next use: \gls{gls}\marg{ssl}\oarg{-enabled}.
1941 \cmd{end}\marg{document}
1942 \end{codeenv}
1943 This produces:
1944 \begin{result}
1945 First use: \gls{ex.ssl}[-enabled]. Next use: \gls{ex.ssl}[-enabled].
1946 \end{result}
1947 Compare this with:
1948 \begin{codeenv}
1949 First use: \gls{gls}\marg{ssl}-enabled. Next use: \gls{gls}\marg{ssl}-enabled.\incorrect
1950 \end{codeenv}
1951 which instead produces:
1952 \begin{result}
1953 First use: \gls{ex.ssl}-enabled. Next use: \gls{ex.ssl}-enabled.
1954 \end{result}
1955 Whereas:
1956 \begin{codeenv}
1957 First use: \gls{gls}\marg{ssl}\oarg{ enabled}. Next use: \gls{gls}\marg{ssl}\oarg{ enabled}.
1958 \end{codeenv}
1959 produces:
1960 \begin{result}
1961 First use: \gls{ex.ssl}[ enabled]. Next use: \gls{ex.ssl}[ enabled].
1962 \end{result}
1963 Note that this is different to the result obtained with the
1964 \abbrstyle{long-short} style which doesn't include the inserted
1965 material in the parentheses (and doesn't check if the inserted
1966 text starts with a hyphen).
1967
1968 There's a related attribute \catattr{markshortwords} which applies
1969 to the short form instead. This is only useful if the short form contains
1970 spaces.
1971
1972 Another markup-related attribute is \catattr{tagging}. In general,
1973 you don't need to explicitly set this attribute. Instead, you need
1974 to define a tagging command using:
1975 \nosecformatdef{GlsXtrEnableInitialTagging}
1976 This (robustly) defines \meta{cs} (a control sequence) to accept a
1977 single argument, which you need to use in the \meta{long} part of the
1978 abbreviation definition (it's not inserted automatically).
1979
1980 The \gls{GlsXtrEnableInitialTagging} command also sets the
1981 \catattr{tagging} attribute to \code{true} for each of the listed
1982 categories, which ensures that \meta{cs} uses
1983 \nosecformatdef{glsxtrtagfont}
1984 within the glossary (see \sectionref{sec:displaygloss}). Within the
1985 main text the command simply does its argument.
1986 For example:
1987 \begin{codeenv}
1988 \cmd{documentclass}\marg{article}
1989 \strut
1990 \cmd{usepackage}\marg{glossaries-extra}
1991 \strut
1992 \gls{GlsXtrEnableInitialTagging}\marg{abbreviation}\marg{\cmd{itag}}
1993 \strut
1994 \gls{newabbreviation}\marg{xml}\marg{XML}\marg{e\cmd{itag}\marg{x}tensible \cmd{itag}\marg{m}arkup
1995 \cmd{itag}\marg{l}anguage}
1996 \strut
1997 \cmd{begin}\marg{document}
1998 First use: \gls{gls}\marg{xml}. Next use: \gls{gls}\marg{xml}.
1999 \cmd{end}\marg{document}
2000 \end{codeenv}
2001 This produces:
2002 \begin{result}
2003 First use: \gls{ex.xml}. Next use: \gls{ex.xml}.
2004 \end{result}
2005 This doesn't show the markup as the tagging command (\csfmt{itag} in
2006 this example) simply expands to its argument in the main document
2007 text. The difference is only evident in the glossary.
2008
2009 If all your abbreviations are defined in a separate file, it's
2010 useful to provide a definition of the tagging command with
2011 \gls{providecommand} to ensure it's defined if you decide not to use
2012 \gls{GlsXtrEnableInitialTagging}. With \bibgls, you can include it
2013 in the \atentry{preamble}. For example:
2014 \begin{codeenv}
2015 \atentry{preamble}\marg{"\gls{providecommand}\marg{\cmd{itag}}\oarg{1}\marg{\gls{param}1}"}
2016 \end{codeenv}
2017
2018 \section{Dotted Abbreviations}
2019 \label{sec:dotabbr}
2020
2021 If an abbreviation ends with a \idx{full-stop}, it can be awkward
2022 when it appears at the end of a sentence, as you can end up with two
2023 dots by mistake. For example:
2024 \begin{codeenv}
2025 \cmd{documentclass}\marg{article}
2026 \strut
2027 \cmd{usepackage}\marg{glossaries-extra}
2028 \strut
2029 \gls{newabbreviation}\marg{dante}\marg{DANTE e.V.}
2030 \marg{Deutschsprachige Anwendervereinigung \cmd{TeX}\gls{cs.space}e.V.}
2031 \strut
2032 \gls{newabbreviation}\marg{gp}\marg{G.P.}\marg{General Practitioner}
2033 \strut
2034 \cmd{begin}\marg{document}
2035 \gls{gls}\marg{dante} is a local \cmd{TeX}\gls{cs.space}user group.
2036 The German-speaking local \cmd{TeX}\gls{cs.space}user group is \gls{gls}\marg{dante}.
2037 \strut
2038 A \gls{gls}\marg{gp} is a medical doctor.
2039 I went to my surgery to see the \gls{gls}\marg{gp}.
2040 \cmd{end}\marg{document}
2041 \end{codeenv}
2042 This results in:
2043 \begin{result}
2044 \gls{ex.dante} is a local \TeX\ user group.
2045 The German-speaking local \TeX\ user group is \gls{ex.dante}\relax.\incorrect
2046
2047 A \gls{ex.gp} is a medical doctor.
2048 I went to my surgery to see the \gls{ex.gp}\relax.\incorrect
2049 \end{result}
2050 The awkward double-dot is caused by the final dot in the
2051 short form followed by the sentence terminating \idx{full-stop}.
2052
2053 If the \catattr{discardperiod} attribute is set to \code{true}, the
2054 \idx{postlinkhook} will look ahead for a \idx{full-stop}. If it
2055 finds one, it will be discarded. For example:
2056 \begin{codeenv}
2057 \cmd{documentclass}\marg{article}
2058 \strut
2059 \cmd{usepackage}\marg{glossaries-extra}
2060 \strut
2061 \gls{glssetcategoryattribute}\marg{abbreviationdot}\marg{\catattr{discardperiod}}\marg{true}
2062 \strut
2063 \gls{newabbreviation}\oarg{\field{category}=abbreviationdot}
2064 \marg{dante}\marg{DANTE e.V.}\marg{Deutschsprachige Anwendervereinigung \cmd{TeX}\gls{cs.space}e.V.}
2065 \strut
2066 \gls{newabbreviation}\oarg{\field{category}=abbreviationdot}
2067 \marg{gp}\marg{G.P.}\marg{General Practitioner}
2068 \strut
2069 \cmd{begin}\marg{document}
2070 \gls{gls}\marg{dante} is a local \cmd{TeX}\gls{cs.space}user group.
2071 The German-speaking local \cmd{TeX}\gls{cs.space}user group is \gls{gls}\marg{dante}.
2072 \strut
2073 A \gls{gls}\marg{gp} is a medical doctor.
2074 I went to my surgery to see the \gls{gls}\marg{gp}.
2075 \cmd{end}\marg{document}
2076 \end{codeenv}
2077 This now results in:
2078 \begin{result}
2079 \gls{ex.dante} is a local \TeX\ user group.
2080 The German-speaking local \TeX\ user group is \gls{ex.dante}.
2081
2082 A \gls{ex.gp} is a medical doctor.
2083 I went to my surgery to see the \gls{ex.gp}.
2084 \end{result}
2085 This attribute only affects the \emph{non-plural} commands, such as
2086 \gls{gls} and \gls{glsxtrshort}. If the last paragraph in the above
2087 example is changed to:
2088 \begin{codeenv}
2089 A \gls{gls}\marg{gp} is a medical doctor.
2090 I went to my surgery to see the \gls{glspl}\marg{gp}.
2091 \end{codeenv}
2092 then the result is:
2093 \begin{result}
2094 A \gls{ex.gp} is a medical doctor.
2095 I went to my surgery to see the \glspl{ex.gp}.
2096 \end{result}
2097 In this case there's no need to discard the terminating
2098 \idx{full-stop} as the plural form doesn't end with one. If the
2099 plural form also ends with a \idx{full-stop} (for example, if the
2100 \catattr{noshortplural} attribute is also set) then you additionally
2101 need to set the \catattr{pluraldiscardperiod} attribute.
2102
2103 The \idx{postlinkhook} is also applied to other commands, such as
2104 \gls{glsxtrfull}, \gls{glsxtrlong}, \gls{glsxtrshort} and \gls{glssymbol}.
2105 For example:
2106 \begin{codeenv}
2107 I went to my surgery to see the \gls{glsxtrshort}\marg{gp}.
2108 \end{codeenv}
2109 results in:
2110 \begin{result}
2111 I went to my surgery to see the \glsxtrshort{ex.gp}.
2112 \end{result}
2113 In some cases, this may be inappropriate, for example:
2114 \begin{codeenv}
2115 I went to my surgery to see the \gls{glsxtrlong}\marg{gp}.
2116 \end{codeenv}
2117 results in:
2118 \begin{result}
2119 I went to my surgery to see the \glsxtrlong{ex.gp}.
2120 \end{result}
2121 In this case the terminating \idx{full-stop} shouldn't be discarded.
2122 There are several ways to prevent it. For example, moving the
2123 \idx{full-stop} into the \meta{insert} argument:
2124 \begin{codeenv}
2125 I went to my surgery to see the \gls{glsxtrlong}\marg{gp}\oarg{.}
2126 \end{codeenv}
2127 This results in:
2128 \begin{result}
2129 I went to my surgery to see the \glsxtrlong{ex.gp}[.]
2130 \end{result}
2131 Alternatively, insert \csfmt{relax} before the \idx{full-stop}:
2132 \begin{codeenv}
2133 I went to my surgery to see the \gls{glsxtrlong}\marg{gp}\cmd{relax}.
2134 \end{codeenv}
2135
2136 Depending on the abbreviation style, it may be inappropriate for the
2137 \idx{firstuse} to discard the \idx{full-stop}. In this case, it's a
2138 bit of a nuisance to keep track of whether the term is being
2139 referenced for the first time. Instead, set the
2140 \catattr{retainfirstuseperiod} attribute to \code{true}.
2141
2142 If you have many abbreviations defined without dots and then you
2143 later decide to insert them, you may prefer an automated approach.
2144 This can be done by setting the \catattr{insertdots} attribute to \code{true}.
2145 For example:
2146 \begin{codeenv}
2147 \cmd{documentclass}\marg{article}
2148 \strut
2149 \cmd{usepackage}\marg{glossaries-extra}
2150 \strut
2151 \gls{glssetcategoryattribute}\marg{initialism}\marg{\catattr{insertdots}}\marg{true}
2152 \gls{glssetcategoryattribute}\marg{initialism}\marg{\catattr{discardperiod}}\marg{true}
2153 \gls{glssetcategoryattribute}\marg{initialism}\marg{\catattr{retainfirstuseperiod}}\marg{true}
2154 \strut
2155 \gls{setabbreviationstyle}\oarg{initialism}\marg{\abbrstyle[noindex=false]{short-long}}
2156 \strut
2157 \gls{newabbreviation}\oarg{\field{category}=initialism}
2158 \marg{gp}\marg{GP}\marg{General Practitioner}
2159 \strut
2160 \cmd{begin}\marg{document}
2161 Today I went to my surgery to see the \gls{gls}\marg{gp}.
2162 Tomorrow I'm going to my surgery to see the \gls{gls}\marg{gp}.
2163 \cmd{end}\marg{document}
2164 \end{codeenv}
2165 This produces:
2166 \begin{result}
2167 Today I went to my surgery to see the \gls{ex2.gp}.
2168 Tomorrow I'm going to my surgery to see the \gls{ex2.gp}.
2169 \end{result}
2170
2171 \section{Translations}
2172 \label{sec:abbrvtrans}
2173
2174 If an abbreviation needs to be accompanied by a translation, then
2175 you can use a custom field or one of the supplied user fields
2176 described in \sectionref{sec:userkeys} to store the translation. The
2177 \code{-user} abbreviation styles can be used to include the extra
2178 information if the field is set. The \field{user1} field
2179 is the default, but you can change this by redefining:
2180 \nosecformatdef{glsxtruserfield}
2181 to the \emph{internal} field name. (For example, \field{userii} for
2182 \field{user2}.) In the sample document below, the translation is
2183 supplied in the default \field{user1} field:
2184 \begin{codeenv}
2185 \cmd{documentclass}\marg{article}
2186 \strut
2187 \cmd{usepackage}\marg{glossaries-extra}
2188 \strut
2189 \gls{setabbreviationstyle}\marg{\abbrstyle{long-short-user}}
2190 \strut
2191 \gls{newabbreviation}\oarg{\field{user1}=\marg{ribonucleic acid}}
2192 \marg{rna}\marg{RNA}\marg{ribonukleins\gls[noindex=false]{umlaut}aure}
2193 \strut
2194 \cmd{begin}\marg{document}
2195 First use: \gls{gls}\marg{rna}. Next use: \gls{gls}\marg{rna}.
2196 \cmd{end}\marg{document}
2197 \end{codeenv}
2198 This produces:
2199 \begin{result}
2200 First use: \gls{ex.rna}. Next use: \gls{ex.rna}.
2201 \end{result}
2202 If the field is empty, \abbrstyle{long-short-user} behaves like
2203 \abbrstyle{long-short}.
2204
2205 Here's an example where the native language is English:
2206 \begin{codeenv}
2207 \gls{newabbreviation}\marg{iso}\marg{ISO}\marg{International Organization for Standardization}
2208 \strut
2209 \gls{newabbreviation}\oarg{
2210 \field{user1} = \marg{Associa\gls{c}\marg{c}\gls{cs.tilde}ao Brasileria de Normas T\cs{acute}ecnicas},
2211 \field{user2} = \marg{pt-BR},
2212 \field{category} = \marg{foreignabbreviation}
2213 }
2214 \marg{abnt}\marg{ABNT}\marg{Brazilian National Standards Organization}
2215 \strut
2216 \gls{newabbreviation}\oarg{
2217 \field{user1} = \marg{Deutsches Institut f\gls{umlaut}ur Normung e.V.},
2218 \field{user2} = \marg{de-1996},
2219 \field{category} = \marg{foreignabbreviation}
2220 }\marg{din}\marg{DIN}\marg{German Institute for Standardization}
2221 \end{codeenv}
2222 The use of the custom \field{category} label
2223 \code{foreignabbrevaiation} means I can set up different abbreviation
2224 styles. For example:
2225 \begin{codeenv}
2226 \gls{setabbreviationstyle}\marg{short-nolong}
2227 \gls{setabbreviationstyle}\oarg{foreignabbreviation}\marg{long-short-user}
2228 \end{codeenv}
2229 This example differs from the previous one as there are now two
2230 foreign languages (Portuguese and German) with English as the native
2231 language. The previous had German as the native language and English
2232 as the sole foreign language. In this case, I've used the
2233 \field{user2} field to identify the language of the original text
2234 (stored in the \field{user1} field).
2235
2236 For example, suppose I'm using \sty{babel} with the language options
2237 \code{british}, \code{brazilian} and \code{ngerman}:
2238 \begin{codeenv}
2239 \cmd{usepackage}[main=british,brazilian,ngerman]\marg{babel}
2240 \end{codeenv}
2241 then I might want to modify \gls{glsxtruserparen} to use
2242 \gls{foreignlanguage}. This would be easier if the \field{user2}
2243 field used a recognised \sty{babel} dialect label, but that's less
2244 consistent across documents. For example, in another document I
2245 might use \code{UKenglish} or just \code{english} (or perhaps use
2246 \sty{polyglossia} instead).
2247
2248 The \sty{glossaries} package loads \sty{tracklang}~\cite{tracklang},
2249 which provides:
2250 \nosecformatdef{GetTrackedDialectFromLanguageTag}
2251 If the given language tag matches a document dialect that's been
2252 tracked (by \sty{tracklang}), this stores the \emph{\sty{tracklang}
2253 dialect label} in the control sequence \meta{cs} otherwise it sets
2254 that control sequence to empty. The match requires that five
2255 properties of the language tag and \sty{tracklang}'s dialect label
2256 are the same: root language, region, sub-language, variant and
2257 script. Some of these elements may be empty, in which case those
2258 elements must be empty for both. If the script is missing in either
2259 case, the default script for the given root language is assumed. For
2260 example, \code{Latn} for \code{en} (English).
2261
2262 \begin{important}
2263 The \sty{tracklang} dialect label isn't always the same as
2264 \sty{babel}'s dialect label.
2265 \end{important}
2266
2267 The simplest way to test if the \sty{tracklang} label matches the
2268 \sty{babel} label is to test for the existence of
2269 \csfmt{captions}\meta{label}. For example, using \sty{etoolbox}'s
2270 \gls{ifcsundef}:
2271 \begin{codeenv}
2272 \gls{GetTrackedDialectFromLanguageTag}\marg{pt-BR}\marg{\cmd{dialectlabel}}
2273 \gls{ifdefempty}\cmd{dialectlabel}
2274 \marg{}\comment{no exact match found}
2275 \marg{\comment{exact match found}
2276 \gls{ifcsundef}\marg{captions\cmd{dialectlabel}}
2277 \marg{}\comment{not a recognised \sty{babel} label}
2278 \marg{}\comment{recognised \sty{babel} label}
2279 }
2280 \end{codeenv}
2281 In the \qt{not a recognised \sty{babel} label} argument, you can
2282 find out if the \sty{tracklang} dialect label has a mapping to the
2283 closest known \sty{babel} dialect label with:
2284 \nosecformatdef{IfTrackedDialectHasMapping}
2285 If true, you can fetch the corresponding \sty{babel} label with:
2286 \nosecformatdef{GetTrackedDialectToMapping}
2287 If false, you can try the root language label instead, which can be
2288 obtained with:
2289 \nosecformatdef{TrackedLanguageFromDialect}
2290 For example:
2291 \begin{codeenv}
2292 \gls{GetTrackedDialectFromLanguageTag}\marg{pt-BR}\marg{\cmd{dialectlabel}}
2293 \gls{ifdefempty}\cmd{dialectlabel}
2294 \marg{}\comment{no exact match found}
2295 \marg{\comment{exact match found}
2296 \gls{ifcsundef}\marg{captions\cmd{dialectlabel}}
2297 \marg{\comment{not a recognised \sty{babel} label, use root language}
2298 \cmd{edef}\cmd{dialectlabel}\marg{\gls{TrackedLanguageFromDialect}\cmd{dialectlabel}}\comment{}
2299 }\comment{}
2300 \marg{}\comment{recognised \sty{babel} label}
2301 }
2302 \end{codeenv}
2303
2304 Consider the following document:
2305 \begin{codeenv}
2306 \cmd{documentclass}\marg{article}
2307 \strut
2308 \cmd{usepackage}[british]\marg{babel}
2309 \cmd{usepackage}\marg{tracklang}
2310 \strut
2311 \cmd{begin}\marg{document}
2312 \gls{GetTrackedDialectFromLanguageTag}\marg{en-GB}\marg{\cmd{trackeddialect}}\comment{}
2313 Tracked dialect label: \cmd{trackeddialect}.
2314 \gls{IfTrackedDialectHasMapping}\marg{\cmd{trackeddialect}}\comment{}
2315 \marg{Has mapping: \gls{GetTrackedDialectToMapping}\marg{\cmd{trackeddialect}}}\comment{}
2316 \marg{No mapping}.
2317 Root language: \gls{TrackedLanguageFromDialect}\marg{\cmd{trackeddialect}}.
2318 \cmd{end}\marg{document}
2319 \end{codeenv}
2320 In this case the \sty{tracklang} dialect label is the same as
2321 \sty{babel}'s dialect label. The above produces:
2322 \begin{result}
2323 Tracked dialect label: british. No mapping. Root language: english.
2324 \end{result}
2325 Now consider this document:
2326 \begin{codeenv}
2327 \cmd{documentclass}[en-MT]\marg{article}
2328 \strut
2329 \cmd{usepackage}[british]\oarg{babel}
2330 \cmd{usepackage}\marg{tracklang}
2331 \strut
2332 \cmd{begin}\marg{document}
2333 en-GB: \gls{GetTrackedDialectFromLanguageTag}\marg{en-GB}\marg{\cmd{trackeddialect}}\comment{} Tracked dialect label: \cmd{trackeddialect}.
2334 \gls{IfTrackedDialectHasMapping}\marg{\cmd{trackeddialect}}\comment{}
2335 \marg{Has mapping: \gls{GetTrackedDialectToMapping}\marg{\cmd{trackeddialect}}}\comment{}
2336 \marg{No mapping}.
2337 Root language: \gls{TrackedLanguageFromDialect}\marg{\cmd{trackeddialect}}.
2338 \strut
2339 en-MT: \gls{GetTrackedDialectFromLanguageTag}\marg{en-MT}\marg{\cmd{trackeddialect}}\comment{} Tracked dialect label: \cmd{trackeddialect}.
2340 \gls{IfTrackedDialectHasMapping}\marg{\cmd{trackeddialect}}\comment{}
2341 \marg{Has mapping: \gls{GetTrackedDialectToMapping}\marg{\cmd{trackeddialect}}}\comment{}
2342 \marg{No mapping}.
2343 Root language: \gls{TrackedLanguageFromDialect}\marg{\cmd{trackeddialect}}.
2344 \cmd{end}\marg{document}
2345 \end{codeenv}
2346 In this case the document requires Maltese English but \sty{babel}
2347 doesn't have an associated dialect so \code{british} is used
2348 instead in \sty{babel}'s options list. However, \sty{tracklang} does
2349 recognise \code{en-MT} as a document class option, which allows
2350 extra localisation from other locale-sensitive packages. (For
2351 example, \sty{datetime2} will use different time zone abbreviations.) If
2352 \sty{tracklang} picks up document class options, these override any
2353 \sty{babel} settings, but the mapping allows a way of accessing the
2354 captions hook provided by \sty{babel}.
2355
2356 The above document produces:
2357 \begin{result}
2358 en-GB: Tracked dialect label: . No mapping. Root language: .
2359
2360 en-MT: Tracked dialect label: maltaenglish. Has mapping: british.
2361 Root language: english.
2362 \end{result}
2363 So now, even though \sty{babel}'s \code{british} option has been
2364 used, en-GB isn't recognised as a tracked locale. Things are a
2365 little more complicated if the language tag is too specific compared
2366 to the \sty{babel} dialect label. For example, while the dialect
2367 label \code{nswissgerman} identifies the region, the \code{ngerman}
2368 label doesn't.
2369 \begin{codeenv}
2370 \cmd{documentclass}\marg{article}
2371 \strut
2372 \cmd{usepackage}[ngerman]\marg{babel}
2373 \cmd{usepackage}\marg{tracklang}
2374 \strut
2375 \cmd{begin}\marg{document}
2376 \gls{GetTrackedDialectFromLanguageTag}\marg{de-DE-1996}\marg{\cmd{trackeddialect}}\comment{}
2377 Tracked dialect label: \cmd{trackeddialect}.
2378 \gls{IfTrackedDialectHasMapping}\marg{\cmd{trackeddialect}}\comment{}
2379 \marg{Has mapping: \gls{GetTrackedDialectToMapping}\marg{\cmd{trackeddialect}}}\comment{}
2380 \marg{No mapping}.
2381 \end{codeenv}
2382 In this case no dialect label is found. The result is:
2383 \begin{result}
2384 Tracked dialect label: . No mapping.
2385 \end{result}
2386 This is because the document doesn't have a dialect that matches
2387 both the language \emph{and} region. As from \sty{tracklang} version
2388 1.3.6, \gls{GetTrackedDialectToMapping} sets:
2389 \nosecformatdef{TrackedDialectClosestSubMatch}
2390 to the closest dialect label that has the same root language if the
2391 exact match isn't found. This will be empty if there's no tracked
2392 dialect with the given root language (and may also be empty if an
2393 exact match is found).
2394
2395 Returning to \sty{glossaries-extra} with the original text stored in
2396 the \field{user1} field (identified by \gls{glsxtruserfield} in the
2397 \abbrstyle{long-short-user} style) and the language tag stored in
2398 the \field{user2} field, then if you have at least version 1.32 of
2399 \sty{glossaries-extra} and version 1.3.6 of \sty{tracklang} you
2400 can use:
2401 \nosecformatdef{GlsXtrForeignText}
2402 to encapsulate \meta{text} with:
2403 \nosecformatdef{foreignlanguage}
2404 where the field containing the appropriate locale tag is stored in
2405 the field given by:
2406 \nosecformatdef{GlsXtrForeignTextField}
2407 which defaults to the \field{userii} internal field for the entry
2408 identified by \meta{label} (corresponding to the \field{user2} field).
2409 For example:
2410 \begin{codeenv}
2411 \cmd{documentclass}\marg{article}
2412 \strut
2413 \cmd{usepackage}[main=british,brazilian,ngerman]\marg{babel}
2414 \cmd{usepackage}[\styopt{record}]\marg{glossaries-extra}
2415 \strut
2416 \gls{setabbreviationstyle}\oarg{foreignabbreviation}\marg{long-short-user}
2417 \strut
2418 \gls{newabbreviation}\marg{iso}\marg{ISO}\marg{International Organization for Standardization}
2419 \strut
2420 \gls{newabbreviation}\oarg{
2421 \field{user1} = \marg{Associa\gls{c}\marg{c}\gls{cs.tilde}ao Brasileria de Normas T\cs{acute}ecnicas},
2422 \field{user2} = \marg{pt-BR},
2423 \field{category} = \marg{foreignabbreviation}
2424 }
2425 \marg{abnt}\marg{ABNT}\marg{Brazilian National Standards Organization}
2426 \strut
2427 \gls{newabbreviation}\oarg{
2428 \field{user1} = \marg{Deutsches Institut f\gls{umlaut}ur Normung e.V.},
2429 \field{user2} = \marg{de-1996},
2430 \field{category} = \marg{foreignabbreviation}
2431 }\marg{din}\marg{DIN}\marg{German Institute for Standardization}
2432 \strut
2433 \cmd{renewcommand}*\marg{\gls{glsxtruserparen}}[2]\marg{\comment{}
2434 \gls[noindex=false]{glsxtrfullsep}\marg{\gls{param}2}\comment{}
2435 \gls[noindex=false]{glsxtrparen}
2436 \marg{\gls{param}1\comment{}
2437 \gls{ifglshasfield}\marg{\gls{glsxtruserfield}}\marg{\gls{param}2}\comment{}
2438 \marg{, \gls{emph}\marg{\gls{GlsXtrForeignText}\marg{\gls{param}2}\marg{\gls{glscurrentfieldvalue}}}}\comment{}
2439 \marg{}\comment{}
2440 }\comment{}
2441 }
2442 \strut
2443 \cmd{begin}\marg{document}
2444 \gls{gls}\marg{abnt}, \gls{gls}\marg{din}.
2445 \cmd{end}\marg{document}
2446 \end{codeenv}
2447 This essentially uses the earlier \sty{tracklang} code where an
2448 extra \gls{ifdefempty} is inserted, which sets the equivalent of
2449 \csfmt{trackeddialect} in the above to \gls{TrackedDialectClosestSubMatch}. If
2450 the test for the captions hook is false, then \gls{foreignlanguage}
2451 isn't used.
2452
2453
2454 \chapter{Symbols}
2455 \label{sec:symbols}
2456
2457 \Sectionref{sec:userkeys} described the \field{symbol} key, which can
2458 be used to additionally provide a symbol. For example:
2459 \begin{codeenv}
2460 \cmd{documentclass}\marg{article}
2461 \strut
2462 \cmd{usepackage}\marg{\gls[noindex=false]{siunitx}}\comment{provides \gls{si}}
2463 \cmd{usepackage}\marg{glossaries}
2464 \strut
2465 \gls{newglossaryentry}\marg{length}\comment{label}
2466 \marg{\comment{settings:}
2467 \field{name} = \marg{length},
2468 \field{symbol} = \marg{\gls{si}\marg{\cmd{metre}}},
2469 \field{description} = \marg{measurement between two points}
2470 }
2471 \strut
2472 \gls{newglossaryentry}\marg{area}\comment{label}
2473 \marg{\comment{settings:}
2474 \field{name} = \marg{area},
2475 \field{symbol} = \marg{\gls[noindex=false]{si}\marg{\cmd{metre}\cmd{squared}}},
2476 \field{description} = \marg{measurement of a surface}
2477 }
2478 \strut
2479 \cmd{begin}\marg{document}
2480 Measurements: \gls{gls}\marg{length} (\gls{glssymbol}\marg{length}) and
2481 \gls{gls}\marg{area} (\gls{glssymbol}\marg{area}).
2482 \cmd{end}\marg{document}
2483 \end{codeenv}
2484 This produces:
2485 \begin{result}
2486 Measurements: \gls{ex.length} (\glssymbol{ex.length}) and
2487 \gls{ex.area} (\glssymbol{ex.area}).
2488 \end{result}
2489
2490 It may be that you prefer to have the symbol in the \field{name}
2491 field instead. The example document below is a modification of the
2492 above and uses the \idx{postlinkhook} to append the description on
2493 \idx{firstuse} (see \sectionref{sec:postlinkhooks}).
2494 \begin{codeenv}
2495 \cmd{documentclass}\marg{article}
2496 \strut
2497 \cmd{usepackage}\marg{siunitx}
2498 \cmd{usepackage}\marg{glossaries-extra}
2499 \strut
2500 \gls[noindex=false]{glsnoexpandfields} \comment{name field contains \gls{si}}
2501 \strut
2502 \gls{glsdefpostlink}\marg{symbol}\marg{\gls{glsxtrpostlinkAddDescOnFirstUse}}
2503 \strut
2504 \gls{newglossaryentry}\marg{length}\comment{label}
2505 \marg{\comment{settings:}
2506 \field{name} = \marg{\gls{si}\marg{\cmd{metre}}},
2507 \field{description} = \marg{length},
2508 \field{category} = \marg{symbol}
2509 }
2510 \strut
2511 \gls{newglossaryentry}\marg{area}\comment{label}
2512 \marg{\comment{settings:}
2513 \field{name} = \marg{\gls{si}\marg{\cmd{metre}\cmd{squared}}},
2514 \field{description} = \marg{area},
2515 \field{category} = \marg{symbol}
2516 }
2517 \strut
2518 \cmd{begin}\marg{document}
2519 First use: \gls{gls}\marg{length} and \gls{gls}\marg{area}.
2520 Next use: \gls{gls}\marg{length} and \gls{gls}\marg{area}.
2521 \cmd{end}\marg{document}
2522 \end{codeenv}
2523 Note the need for \gls{glsnoexpandfields} (described in
2524 \sectionref{sec:robust}). This wasn't required in the previous
2525 example because the \sty{siunitx} commands were in the
2526 \field{symbol} field, which isn't expanded by default. The
2527 \field{name} field also isn't expanded by default, but its value is
2528 copied to the \field{text} and \field{first} fields, which are
2529 expanded by default. If \gls{glsnoexpandfields} is omitted from the
2530 above document, the following error would occur:
2531 \begin{verbatim}
2532 ! Undefined control sequence.
2533 \@glo@name ->\si {\metre
2534 }
2535 \end{verbatim}
2536 Although \gls{si} is robust, commands like \csfmt{metre} and
2537 \csfmt{squared} are only available within the argument of \gls{si}
2538 (and other similar commands provided by \sty{siunitx}) and so break
2539 in expandable contexts.
2540 With \gls{glsnoexpandfields}, the document compiles correctly and
2541 produces:
2542 \begin{result}
2543 \glsdefpostlink{symbol}{\glsxtrpostlinkAddDescOnFirstUse}%
2544 First use: \gls{ex2.length} and \gls{ex2.area}.
2545 Next use: \gls{ex2.length} and \gls{ex2.area}.
2546 \end{result}
2547
2548 The \sty{glossaries-extra}['s] \styopt{symbols} package option
2549 provides the command
2550 \nosecformatdef{glsxtrnewsymbol}
2551 which is a shortcut for
2552 \begin{codeenv}
2553 \gls{newglossaryentry}\margm{label}\marg{\field{name}=\margm{symbol},\field{category}=\marg{symbol},\gls[noindex=false]{field.sort}=\margm{label},
2554 \gls[noindex=false]{field.type}=\marg{symbols},\meta{\keyvallist}}
2555 \end{codeenv}
2556 So the above document can be changed to:
2557 \begin{codeenv}
2558 \cmd{documentclass}\marg{article}
2559 \strut
2560 \cmd{usepackage}\marg{siunitx}
2561 \cmd{usepackage}[\styopt{symbols}]\marg{glossaries-extra}
2562 \strut
2563 \gls{glsnoexpandfields}
2564 \strut
2565 \gls{glsdefpostlink}\marg{symbol}\marg{\gls{glsxtrpostlinkAddDescOnFirstUse}}
2566 \strut
2567 \gls{glsxtrnewsymbol}\oarg{\field{description} = \marg{length}}\marg{length}\marg{\gls{si}\marg{\cmd{metre}}}
2568 \strut
2569 \gls{glsxtrnewsymbol}\oarg{\field{description} = \marg{area}}\marg{area}\marg{\gls{si}\marg{\cmd{metre}\cmd{squared}}}
2570 \strut
2571 \cmd{begin}{document}
2572 First use: \gls{gls}\marg{length} and \gls{gls}\marg{area}.
2573 Next use: \gls{gls}\marg{length} and \gls{gls}\marg{area}.
2574 \cmd{end}\marg{document}
2575 \end{codeenv}
2576 The result is the same.
2577
2578 \section{Functions}
2579 \label{sec:functions}
2580
2581 Some symbols may represent functions. For example:
2582 \begin{codeenv}
2583 \cmd{documentclass}\marg{article}
2584 \strut
2585 \cmd{usepackage}[\styopt{symbols}]\marg{glossaries-extra}
2586 \strut
2587 \gls{glsnoexpandfields}
2588 \strut
2589 \gls{glsxtrnewsymbol}
2590 \oarg{\field{description} = \marg{derivative}}
2591 \marg{deriv}\comment{label}
2592 \marg{\gls{ensuremath}\marg{f'(x)}}\comment{symbol}
2593 \strut
2594 \cmd{begin}\marg{document}
2595 The derivative is denoted \gls{gls}\marg{deriv}.
2596 \cmd{end}\marg{document}
2597 \end{codeenv}
2598 This produces:
2599 \begin{result}
2600 The derivative is denoted \gls{ex.deriv}.
2601 \end{result}
2602 What if I need to change the variable for a specific instance, for
2603 example, if I want $f'(x_i)$ instead of $f'(x)$? I can just use:
2604 \begin{codeenv}
2605 The gradient at \gls{mshiftchar}x\gls{sbchar}i\gls{mshiftchar} is \gls{mshiftchar}f'(x\gls{sbchar}i)\gls{mshiftchar}.
2606 \end{codeenv}
2607 So far, none of the example documents have a glossary or list of
2608 terms. The ultimate aim when using the \styfmt{glossaries} package
2609 is to ensure consistent formatting and notation, and, where
2610 applicable, include a list of all terms referenced in the document.
2611 The use of commands like \gls{gls} helps to achieve this. If the
2612 notation needs to be changed, only the entry definition (and
2613 associated formatting commands) should need to be redefined without
2614 having to go through the whole document changing the code. Using
2615 commands like \gls{gls} also identifies which entries need to be
2616 included in the list of terms and, if \sty{hyperref} is loaded, can
2617 be hyperlinked to the relevant place in that list (see
2618 \sectionref{sec:displaygloss}).
2619
2620 So explicitly using \verb|f'(x_i)| won't index the \code{deriv} entry
2621 or mark it has having been used or create a hyperlink. One
2622 possibility is to use one of the following commands:
2623 \nosecformatdef{glslink}
2624 \nosecformatdef{glsdisp}
2625 They both work in much the same way, indexing the entry and
2626 displaying \meta{text} as the \idx{link-text}. The only difference is
2627 that \gls{glsdisp} also unsets the \idx{firstuseflag}, which marks the entry
2628 as having been used. For example:
2629 \begin{codeenv}
2630 The gradient at \gls{mshiftchar}x\gls{sbchar}i\gls{mshiftchar} is \gls{glslink}\marg{deriv}\marg{\gls{mshiftchar}f'(x\gls{sbchar}i)\gls{mshiftchar}}.
2631 \end{codeenv}
2632 This solves the problem of ensuring that the \code{deriv} entry is
2633 indexed and, if \sty{hyperref} is loaded, ensures that the
2634 \idx{link-text} has a hyperlink to the relevant place in the list of
2635 notation, but it doesn't solve the problem of consistent formatting.
2636
2637 One way of ensuring consistent formatting is to define a semantic
2638 command. For example:
2639 \begin{codeenv}
2640 \cmd{documentclass}\marg{article}
2641 \strut
2642 \cmd{usepackage}[\styopt{symbols}]\marg{glossaries-extra}
2643 \strut
2644 \gls{glsnoexpandfields}
2645 \strut
2646 \cmd{newcommand}\marg{\cmd{derivfn}}[1]\marg{f'(\gls{param}1)}
2647 \strut
2648 \gls{glsxtrnewsymbol}
2649 \oarg{\field{description} = \marg{derivative}}
2650 \marg{deriv}\comment{label}
2651 \marg{\gls{ensuremath}\marg{\cmd{derivfn}\marg{x}}}\comment{symbol}
2652 \strut
2653 \cmd{begin}\marg{document}
2654 The derivative is denoted \gls{gls}\marg{deriv}.
2655 The gradient at \gls{mshiftchar}x\gls{sbchar}i\gls{mshiftchar} is \gls{glslink}\marg{deriv}\marg{\gls{mshiftchar}\cmd{derivfn}\marg{x\gls{sbchar}i}\gls{mshiftchar}}.
2656 \cmd{end}\marg{document}
2657 \end{codeenv}
2658 This produces:
2659 \begin{result}
2660 \providecommand{\derivfn}[1]{f'(#1)}
2661 The derivative is denoted \gls{ex.deriv}.
2662 The gradient at $x_i$ is \glslink{ex.deriv}{$\derivfn{x_i}$}.
2663 \end{result}
2664 Now only \csfmt{derivfn} needs modifying if the notation must change.
2665 This requires remembering both the entry label (\code{deriv} in this
2666 case) and the associated formatting command (\csfmt{derivfn} in this
2667 case). The \sty{glossaries-extra} package provides a way of storing
2668 the associated formatting command in one of the additional keys (see
2669 \sectionref{sec:userkeys}). The field is identified by:
2670 \nosecformatdef{GlsXtrFmtField}
2671 which defaults to \field{useri} (the internal representation of the
2672 \field{user1} key). The value must be the name (without the leading
2673 backslash) of a control sequence that takes a \emph{single}
2674 mandatory argument. The above custom command \code{derivfn}
2675 satisfies this requirement, so the entry can be defined as:
2676 \begin{codeenv}
2677 \gls{glsxtrnewsymbol}
2678 \oarg{\comment{settings:}
2679 \field{description} = \marg{derivative},
2680 \field{user1} = \marg{derivfn}
2681 }
2682 \marg{deriv}\comment{label}
2683 \marg{\gls{ensuremath}\marg{\cmd{derivfn}\marg{x}}}\comment{symbol}
2684 \end{codeenv}
2685 The formatting command can now be applied using one of the
2686 following:
2687 \nosecformatdef{glsxtrfmt}
2688 \nosecformatdef{glsxtrfmt*}
2689 which internally use \gls{glslink} or:
2690 \nosecformatdef{glsxtrentryfmt}
2691 which doesn't (and so is more like using \gls{glsentryname}).
2692
2693 So an alternative approach is:
2694 \begin{codeenv}
2695 \cmd{documentclass}\marg{article}
2696 \strut
2697 \cmd{usepackage}[\styopt{symbols}]\marg{glossaries-extra}
2698 \strut
2699 \gls{glsnoexpandfields}
2700 \strut
2701 \cmd{newcommand}\marg{\cmd{derivfn}}[1]\marg{f'(\gls{param}1)}
2702 \strut
2703 \gls{glsxtrnewsymbol}
2704 \oarg{\comment{settings:}
2705 \field{description} = \marg{derivative},
2706 \field{user1} = \marg{derivfn}
2707 }
2708 \marg{deriv}\comment{label}
2709 \marg{\gls{ensuremath}\marg{\cmd{derivfn}\marg{x}}}\comment{symbol}
2710 \strut
2711 \cmd{begin}\marg{document}
2712 The derivative is denoted \gls{gls}\marg{deriv}.
2713 The gradient at \gls{mshiftchar}x\gls{sbchar}i\gls{mshiftchar} is \gls{mshiftchar}\gls{glsxtrfmt}\marg{deriv}\marg{x\gls{sbchar}i}\gls{mshiftchar}.
2714 \cmd{end}\marg{document}
2715 \end{codeenv}
2716 This again produces:
2717 \begin{result}
2718 The derivative is denoted \gls{ex.deriv}.
2719 The gradient at $x_i$ is $\glsxtrfmt{ex.deriv}{x_i}$.
2720 \end{result}
2721
2722 Both the starred \gls{glsxtrfmt*} and unstarred \gls{glsxtrfmt}
2723 format the \meta{text} argument using:
2724 \nosecformatdef{glsxtrfmtdisplay}
2725 where \meta{cs-name} is the control sequence name stored in the
2726 field identified by \gls{GlsXtrFmtField} and the \meta{insert} part
2727 is the final optional argument for the starred \gls{glsxtrfmt*} (if
2728 provided) otherwise it's empty. If the command identified by
2729 \meta{cs-name} doesn't exist (or if the field providing it isn't
2730 set) then just \meta{text}\meta{insert} is done.
2731
2732 \begin{important}
2733 Nested \idx{link-text} causes problems so don't use \gls{glsxtrfmt}
2734 in the optional part of commands like \gls{gls} or \gls{glssymbol}
2735 or in field values that are used by those types of command. Also
2736 don't use \gls{glsxtrfmt} within the \meta{text} or \meta{insert}
2737 part of another instance of \gls{glsxtrfmt} or in \gls{glslink} or
2738 \gls{glsdisp}. Use \gls{glsxtrentryfmt} instead.
2739 \end{important}
2740
2741 If more than one argument is required, then a helper macro is
2742 needed. For example:
2743 \begin{verbatim}
2744 \newcommand{\iderivfn}[2][f]{#1'(#2)}
2745 \newcommand{\derivfn}[1]{\iderivfn#1}
2746 \end{verbatim}
2747 Now to obtain $g'(x_i)$:
2748 \begin{codeenv}
2749 \gls{mshiftchar}\gls{glsxtrfmt}\marg{deriv}\marg{[g]\marg{x\gls{sbchar}i}}\gls{mshiftchar}
2750 \end{codeenv}
2751 Note that for this simplistic helper macro, the mandatory inner
2752 argument needs extra braces if it consists of more than a single
2753 token. For example:
2754 \begin{codeenv}
2755 \gls{mshiftchar}\gls{glsxtrfmt}\marg{deriv}\marg{\marg{x\gls{sbchar}i}}\gls{mshiftchar}
2756 \end{codeenv}
2757
2758 \section{Dealing with Automated Case-Changing}
2759 \label{sec:symfirstuc}
2760
2761 Commands like \gls{Gls} don't usually make much sense for symbols as
2762 a change in case can cause a change in meaning. For example,
2763 $\boldsymbol{x}$ might denote a vector and $\boldsymbol{X}$ might
2764 denote a matrix. However, you may have a mixed list of terms
2765 containing both symbols and words, and if you set the
2766 \catattr{glossname} attribute to \code{firstuc}, which automatically
2767 converts the first letter of each \field{name} to \idx{uppercase} in the
2768 glossary, then this can cause a problem for entries where the
2769 \field{name} starts with a symbol. The simplest solution is to
2770 insert an empty group at the start of the \field{name} field for
2771 such entries. For example:
2772 \begin{codeenv}
2773 \gls{glsxtrnewsymbol}
2774 \oarg{\field{description} = \marg{length}}\comment{settings}
2775 \marg{length}\comment{label}
2776 \marg{\marg{}\gls{si}\marg{\cmd{metre}}}\comment{name}
2777 \end{codeenv}
2778 This is done automatically by \bibgls, but if it causes any
2779 interference you can switch off the behaviour with
2780 \longarg{no-mfirstuc-math-protection}.
2781
2782 \chapter{Displaying the Definition}
2783 \label{sec:displaygloss}
2784
2785 The examples so far only use the defined entries in the documents
2786 with commands like \gls{gls} or \gls{glssymbol} or
2787 \gls{glsentrydesc}. These are useful for ensuring consistent
2788 formatting, but it's also helpful to have a place in the document
2789 where the term is formally defined. This can be partially solved
2790 by including the description in parentheses on \idx{firstuse},
2791 either by explicitly including the description in the \field{first}
2792 field or with the use of the \idx{postlinkhook}, but the
2793 \idx{firstuse} might not be the most appropriate place for the
2794 description.
2795
2796 \section{Listing the Terms (Glossary)}
2797 \label{sec:printgloss}
2798
2799 If you want a complete list of all defined terms, you can use:
2800 \nosecformatdef{printunsrtglossary}
2801 This lists all the terms for the given glossary (identified by the
2802 \printglossopt{type} key in \meta{options}, see
2803 \sectionref{sec:multigloss}) according to the order of the
2804 glossary's internal list of labels, which is typically in the order of
2805 definition. (As each entry is defined, its label is appended to the
2806 internal list of the associated glossary.)
2807
2808 You can change the default title with the \printglossopt{title} option. For
2809 example:
2810 \begin{codeenv}
2811 \gls{printunsrtglossary}\oarg{\printglossopt[Nomenclature]{title}}
2812 \end{codeenv}
2813 The title used in the \gls{toc} is assumed to be the same,
2814 but you can change it with \printglossopt{toctitle}. For example:
2815 \begin{codeenv}
2816 \gls{printunsrtglossary}\oarg{
2817 \printglossopt[List of Terms and Notation]{title},
2818 \printglossopt[Notation]{toctitle}
2819 }
2820 \end{codeenv}
2821
2822 The glossary style can be set with the \printglossopt{style} key
2823 in \meta{options}. Alternatively, you can set a default style with the
2824 \styopt{style} package option. There are many predefined styles to
2825 choose from (see the
2826 \href{https://www.dickimaw-books.com/gallery/glossaries-styles/}{\styfmt{glossaries}
2827 gallery}~\cite{glossarystylesgallery}). The styles are provided in supplementary packages, some
2828 of which are automatically loaded. Since each package adds to the
2829 document overhead, and some require additional packages to be
2830 loaded, when using \sty{glossaries-extra}, it's a good idea to
2831 disable the automatic loading of all styles with \styopt{nostyles}
2832 and then use \styopt{stylemods} to load the specific packages (along
2833 with the \sty{glossaries-extra-stylemods} package, which patches
2834 some of the predefined styles). For example, the
2835 \glostyle{index} style is provided by the \styfmt{glossary-tree}
2836 package, so \styopt[tree]{stylemods} will automatically load
2837 \styfmt{glossary-tree} and provide all the tree-like styles,
2838 including \glostyle{index}. The \styopt{stylemods} value may be a
2839 comma-separated list, so to load both \styfmt{glossary-tree} and
2840 \styfmt{glossary-long}, use \styopt[tree,long]{stylemods}.
2841 For example:
2842 \begin{codeenv}
2843 \cmd{documentclass}\marg{scrartcl}
2844 \cmd{usepackage}\marg{\gls[noindex=false]{mhchem}}\comment{provides \gls{ce}}
2845 \cmd{usepackage}[\styopt[dot]{postpunc},\comment{full stop after description}
2846 \styopt{nostyles},\comment{don't load default style packages}
2847 \comment{load glossaries-extra-stylemods.sty and glossary-tree.sty:}
2848 \styopt[tree]{stylemods}
2849 ]\marg{glossaries-extra}
2850 \strut
2851 \gls{newglossaryentry}\marg{area}
2852 \marg{
2853 \field{name} = \marg{\gls{ensuremath}\marg{A}},
2854 \field{description} = \marg{area}
2855 }
2856 \strut
2857 \gls{newglossaryentry}\marg{amethyst}
2858 \marg{
2859 \field{name} = \marg{amethyst},
2860 \field{description} = \marg{a purple type of quartz},
2861 \field{symbol} = \marg{\gls[noindex=false]{ce}\marg{SiO2}}
2862 }
2863 \strut
2864 \gls{newglossaryentry}\marg{circumference}
2865 \marg{
2866 \field{name} = \marg{\gls{ensuremath}\marg{C}},
2867 \field{description} = \marg{circumference}
2868 }
2869 \strut
2870 \gls{newglossaryentry}\marg{duck}
2871 \marg{
2872 \field{name} = \marg{duck},
2873 \field{description} = \marg{a waterbird with webbed feet}
2874 }
2875 \gls{newglossaryentry}\marg{goose}
2876 \marg{
2877 \field{name} = \marg{goose},
2878 \field{description} = \marg{a large waterbird with a long neck, short legs,
2879 webbed feet and a short broad bill}
2880 }
2881 \strut
2882 \gls{newglossaryentry}\marg{radius}
2883 \marg{
2884 \field{name} = \marg{\gls{ensuremath}\marg{r}},
2885 \field{description} = \marg{radius}
2886 }
2887 \strut
2888 \gls{newglossaryentry}\marg{pi}
2889 \marg{
2890 \field{name} = \marg{\gls{ensuremath}\marg{\cmd{pi}}},
2891 \field{description} = \marg{Archimedes' constant}
2892 }
2893 \strut
2894 \cmd{begin}\marg{document}
2895 \gls{printunsrtglossary}\oarg{\printglossopt[index]{style}}
2896 \cmd{end}\marg{document}
2897 \end{codeenv}
2898 This produces:
2899 \begin{result}
2900 \glsaddeach{ex3.goose,ex3.duck,ex2.amethyst,standalone.pi,%
2901 standalone.circumference,standalone.area,standalone.radius}%
2902 \setupglossaries{toc=false,section}%
2903 \glossariesextrasetup{postpunc=dot}%
2904 \renewcommand{\glsxtrgroupfield}{useriii}%
2905 \renewcommand*{\printunsrtglossaryentryprocesshook}[1]{%
2906 \glsifcategory{#1}{standalone}{}{\printunsrtglossaryskipentry}%
2907 }%
2908 \printunsrtglossary[style=index,title=Glossary,nonumberlist,target=false]
2909 \end{result}
2910 The \glostyle{index} glossary style checks if the \field{symbol}
2911 field has been set. If it has, then the symbol is added in
2912 parentheses (as in the amethyst example). Only some of the styles
2913 include the \field{symbol} field. (Table~15.1 in the
2914 \sty{glossaries} user manual~\cite{glossaries} gives an overview of
2915 the features supported by the predefined styles.)
2916
2917 The \glostyle{bookindex} style is provided by the
2918 \isty{glossary-bookindex} package, which is distributed with
2919 \sty{glossaries-extra}. This style is designed for indexes
2920 and omits both the description and the symbol by default. It's
2921 customized specifically for use with \bibgls. Without the
2922 \idxpl{locationlist} obtained by \bibgls, this simply becomes a list
2923 of the \field{name} values for each term.
2924
2925 The glossary is sub-divided into letter groups. By default, these
2926 sub-groups are separated with a vertical gap (for example, between
2927 duck and goose above). In the above example, the letter group is
2928 determined by the first character of the \field{sort} field. Since the
2929 default behaviour of both \sty{glossaries} and
2930 \sty{glossaries-extra} is to use \idx{makeindex}, the \field{sort}
2931 field (which is used by \idx{makeindex}) is set to the value of the
2932 \field{name} field (unless explicitly set) and then sanitized.
2933
2934 When using \gls{printunsrtglossary}, the \field{sort} field is
2935 irrelevant except to determine the letter group (unless the
2936 \field{group} field has been defined). The sub-group
2937 heading is displayed by some styles, such as the
2938 \glostyle{indexgroup} and \glostyle{bookindex} styles. For example, with:
2939 \begin{codeenv}
2940 \gls{printunsrtglossary}\oarg{\printglossopt[indexgroup]{style}}
2941 \end{codeenv}
2942 The glossary is now:
2943 \begin{result}
2944 \setupglossaries{toc=false,section}%
2945 \glossariesextrasetup{postpunc=dot}%
2946 \renewcommand{\glsxtrgroupfield}{useriii}%
2947 \renewcommand*{\printunsrtglossaryentryprocesshook}[1]{%
2948 \glsifcategory{#1}{standalone}{}{\printunsrtglossaryskipentry}%
2949 }%
2950 \printunsrtglossary[style=indexgroup,title=Glossary,nonumberlist,target=false]
2951 \end{result}
2952 This explains why there's a gap between $A$ (area) and amethyst as
2953 they don't belong to the same letter group. The \field{sort} field
2954 for the \code{area} entry is \verb|\ensuremath{A}| which has been
2955 sanitized, so it starts with a literal backslash (\idx{backslashchar}).
2956 This means that \code{area} is assigned to the symbols letter group. The
2957 symbols group occurs three times, because the list is following the
2958 order of definition.
2959
2960 \subsection{Groups and Locations}
2961 \label{sec:group}
2962
2963 \begin{important}
2964 The \field{group} and \field{location} fields are considered
2965 internal fields by \bibgls. They may be referenced within the
2966 document, but they should not be assigned in the \ext{bib} file.
2967 \bibgls\ assigns these fields according to the resource options and
2968 command line switches. Explicitly assigning them can cause
2969 unexpected results. See also \sectionref{sec:logicaldivisions} of
2970 the \bibgls\ manual.
2971 \end{important}
2972
2973 The \field{group} key isn't defined by default, but if it is defined
2974 then \gls{printunsrtglossary} will use the \field{group} field
2975 instead of trying to determine the group from the first character of
2976 the \field{sort} field (as in the example above). The value of the
2977 \field{group} field must be a label (see \sectionref{sec:labels}).
2978 A title may be assigned to a group with:
2979 \nosecformatdef{glsxtrsetgrouptitle}
2980 If a title hasn't been assigned, the label is used as the title.
2981 The above command is the preferred form, but the base
2982 \sty{glossaries} package checks for a control sequence in the form
2983 \csfmt{\meta{label}groupname} where \meta{label} is the group label.
2984 The \sty{glossaries-extra} package also recognises this form to
2985 ensure backward-compatibility. If the \field{group} field is empty
2986 the sub-group won't have a title.
2987
2988 For example, the following defines the \field{group} field with a
2989 custom command \csfmt{grouplabel} (that's not needed, but it's
2990 required by the \gls{glsaddstoragekey} syntax):
2991 \begin{codeenv}
2992 \cmd{documentclass}\marg{scrartcl}
2993 \cmd{usepackage}\marg{mhchem}
2994 \cmd{usepackage}[\styopt[dot]{postpunc},\comment{full stop after description}
2995 \styopt{nostyles},\comment{don't load default style packages}
2996 \styopt[tree]{stylemods}\comment{load glossary-tree.sty and patch styles}
2997 ]\marg{glossaries-extra}
2998 \strut
2999 \gls{glsaddstoragekey}\marg{group}\marg{}\marg{\cmd{grouplabel}}
3000 \gls{glsxtrsetgrouptitle}\marg{greek}\marg{Greek Symbols}
3001 \strut
3002 \gls{newglossaryentry}\marg{area}
3003 \marg{
3004 \field{name} = \marg{\gls{ensuremath}\marg{A}},
3005 \field{description} = \marg{area},
3006 \field{group} = \marg{A}
3007 }
3008 \strut
3009 \gls{newglossaryentry}\marg{amethyst}
3010 \marg{
3011 \field{name} = \marg{amethyst},
3012 \field{description} = \marg{a purple type of quartz},
3013 \field{symbol} = \marg{\gls{ce}\marg{SiO2}},
3014 \field{group} = \marg{A}
3015 }
3016 \strut
3017 \gls{newglossaryentry}\marg{circumference}
3018 \marg{
3019 \field{name} = \marg{\gls{ensuremath}\marg{C}},
3020 \field{description} = \marg{circumference},
3021 \field{group} = \marg{C}
3022 }
3023 \strut
3024 \gls{newglossaryentry}\marg{duck}
3025 \marg{
3026 \field{name} = \marg{duck},
3027 \field{description} = \marg{a waterbird with webbed feet},
3028 \field{group} = \marg{D}
3029 }
3030 \strut
3031 \gls{newglossaryentry}\marg{goose}
3032 \marg{
3033 \field{name} = \marg{goose},
3034 \field{description} = \marg{a large waterbird with a long neck, short legs,
3035 webbed feet and a short broad bill},
3036 \field{group} = \marg{G}
3037 }
3038 \strut
3039 \gls{newglossaryentry}\marg{radius}
3040 \marg{
3041 \field{name} = \marg{\gls{ensuremath}\marg{r}},
3042 \field{description} = \marg{radius},
3043 \field{group} = \marg{R}
3044 }
3045 \strut
3046 \gls{newglossaryentry}\marg{pi}
3047 \marg{
3048 \field{name} = \marg{\gls{ensuremath}\marg{\cmd{pi}}},
3049 \field{description} = \marg{Archimedes' constant},
3050 \field{group} = \marg{greek}
3051 }
3052 \strut
3053 \cmd{begin}\marg{document}
3054 \gls{printunsrtglossary}\oarg{\printglossopt[indexgroup]{style}}
3055 \cmd{end}\marg{document}
3056 \end{codeenv}
3057 This produces:
3058 \begin{result}
3059 \setupglossaries{toc=false,section}%
3060 \glossariesextrasetup{postpunc=dot}%
3061 \renewcommand{\glsxtrgroupfield}{useriv}%
3062 \glsxtrsetgrouptitle{greek}{Greek Symbols}%
3063 \renewcommand*{\printunsrtglossaryentryprocesshook}[1]{%
3064 \glsifcategory{#1}{standalone}{}{\printunsrtglossaryskipentry}%
3065 }%
3066 \printunsrtglossary[style=indexgroup,title=Glossary,nonumberlist,target=false]
3067 \end{result}
3068 Note that with this method \emph{every} entry must be assigned a
3069 group or it will be assigned to the empty group.
3070
3071 Similarly, if the \field{location} field is defined, you can use it
3072 to provide a \idx{locationlist}. The \styopt{record} package option
3073 conveniently defines both \field{group} and \field{location}, so the
3074 following can be used instead:
3075 \begin{codeenv}
3076 \cmd{usepackage}[
3077 \styopt{record},\comment{provides group and location fields (and other stuff)}
3078 postpunc=dot,nostyles,stylemods={tree}]\marg{glossaries-extra}
3079 \strut
3080 \gls{newglossaryentry}\marg{area}
3081 \marg{
3082 \field{name} = \marg{\gls{ensuremath}\marg{A}},
3083 \field{description} = \marg{area},
3084 \field{group} = \marg{A},
3085 \field{location} = \marg{page 1}
3086 }
3087 \end{codeenv}
3088 This very quickly becomes tedious and prone to errors as the entries
3089 have to be ordered manually, and every entry must be assigned the
3090 group and location (if required). Every time the location changes
3091 through edits to the document, the locations must be updated.
3092 However, this is exactly the method that \bibgls\ uses, but it does
3093 it automatically for you by selecting the required data from one or
3094 more \ext{bib} files and then creating a file containing all the
3095 glossary entry definitions with the fields set appropriately. The \ext{aux}
3096 file provides \bibgls\ with the indexing information so that it
3097 knows which entries to select and what the locations are, and how to
3098 order the definitions. See \sectionref{sec:bib2gls} for further
3099 information.
3100
3101 \subsection{Homographs and Hierarchical Terms}
3102 \label{sec:parent}
3103
3104 An entry may be assigned a parent with the \field{parent} key. The
3105 value must be the label of an entry that's already defined. You can
3106 test if an entry has the \field{parent} field set with:
3107 \nosecformatdef{ifglshasparent}
3108 If the \field{name} key is omitted, the value is assumed to be the same as
3109 the parent's \field{name}.
3110 For example:
3111 \begin{codeenv}
3112 \comment{parent:}
3113 \gls{newglossaryentry}\marg{glossary}\marg{\field{name}=\marg{glossary},\field{description}=\marg{}}
3114 \comment{children:}
3115 \gls{newglossaryentry}\marg{glossarycol}
3116 \marg{\comment{settings:}
3117 \field{parent} = \marg{glossary},\comment{parent label}
3118 \field{description} = \marg{collection of glosses}
3119 }
3120 \gls{newglossaryentry}\marg{glossarylist}
3121 \marg{\comment{settings:}
3122 \field{parent} = \marg{glossary},\comment{parent label}
3123 \field{description} = \marg{list of technical words}
3124 }
3125 \end{codeenv}
3126 In this case the entry with the label \code{glossary} is the
3127 \pidx{parent-entry}, and the entries with
3128 the labels \code{glossarycol} and \code{glossarylist} are
3129 \pidxpl{child-entry} (or sub-items). An entry that doesn't have a
3130 parent is a main or top-level or level~0 item. In this case, the
3131 \idxpl{child-entry} don't have the \field{name} key, so the name is
3132 obtained from the parent's name. This is an example of a
3133 \pidx{homograph}, where two words with different meanings
3134 have the same spelling. The parent entry has an empty description.
3135
3136 Here's another example:
3137 \begin{codeenv}
3138 \comment{parent:}
3139 \gls{newglossaryentry}\marg{mineral}\comment{label}
3140 \marg{\comment{settings:}
3141 \field{name} = \marg{mineral},
3142 \field{description} = \marg{natural inorganic substance}
3143 }
3144 \comment{sub-entries:}
3145 \gls{newglossaryentry}\marg{quartz}\comment{label}
3146 \marg{
3147 \field{parent} = \marg{mineral},\comment{parent label}
3148 \field{name} = \marg{quartz},
3149 \field{description} = \marg{hard mineral consisting of silica}
3150 }
3151 \gls{newglossaryentry}\marg{amethyst}\comment{label}
3152 \marg{
3153 \field{parent} = \marg{quartz},\comment{parent label}
3154 \field{name} = \marg{amethyst},
3155 \field{description} = \marg{a purple type of quartz}
3156 }
3157 \end{codeenv}
3158 In this case, the \idxpl{child-entry} have the \field{name} key
3159 set. This is an example of a set of \pidxpl{hierarchical-entry},
3160 where each \idx{child-entry} is a sub-category of the parent.
3161 Some glossary styles are appropriate for \idxpl{homograph} and some
3162 are appropriate for \idxpl{hierarchical-entry} and some are only
3163 appropriate for flat glossaries (no child entries).
3164 For example, the \glostyle{index}, \glostyle{indexgroup},
3165 \glostyle{tree} and \glostyle{treegroup} styles are appropriate
3166 for \idxpl{hierarchical-entry}:
3167 \begin{codeenv}
3168 \cmd{documentclass}\marg{scrartcl}
3169 \strut
3170 \cmd{usepackage}[\styopt{nostyles},\styopt[dot]{postpunc},\styopt[tree]{stylemods}]\marg{glossaries-extra}
3171 \strut
3172 \gls{newglossaryentry}\marg{animal}
3173 \marg{
3174 \field{name} = \marg{animal},
3175 \field{description} = \marg{living organism with a nervous system and sense organs
3176 that can move independently}
3177 }
3178 \strut
3179 \gls{newglossaryentry}\marg{bird}
3180 \marg{
3181 \field{parent} = \marg{animal},
3182 \field{name} = \marg{bird},
3183 \field{description} = \marg{warm-blooded egg-laying animal with feathers, wings
3184 and a beak}
3185 }
3186 \strut
3187 \gls{newglossaryentry}\marg{duck}
3188 \marg{
3189 \field{parent} = \marg{bird},
3190 \field{name} = \marg{duck},
3191 \field{description} = \marg{a waterbird with webbed feet}
3192 }
3193 \strut
3194 \gls{newglossaryentry}\marg{goose}
3195 \marg{
3196 \field{parent} = \marg{bird},
3197 \field{name} = \marg{goose},
3198 \field{description} = \marg{a large waterbird with a long neck, short legs,
3199 webbed feet and a short broad bill}
3200 }
3201 \strut
3202 \gls{newglossaryentry}\marg{mineral}
3203 \marg{
3204 \field{name} = \marg{mineral},
3205 \field{description} = \marg{natural inorganic substance}
3206 }
3207 \strut
3208 \gls{newglossaryentry}\marg{calcite}\comment{label}
3209 \marg{
3210 \field{parent} = \marg{mineral},\comment{parent label}
3211 \field{name} = \marg{calcite},
3212 \field{description} = \marg{a carbonate mineral}
3213 }
3214 \strut
3215 \gls{newglossaryentry}\marg{quartz}
3216 \marg{
3217 \field{parent} = \marg{mineral},
3218 \field{name} = \marg{quartz},
3219 \field{description} = \marg{hard mineral consisting of silica}
3220 }
3221 \strut
3222 \gls{newglossaryentry}\marg{amethyst}
3223 \marg{
3224 \field{parent} = \marg{quartz},
3225 \field{name} = \marg{amethyst},
3226 \field{description} = \marg{a purple type of quartz},
3227 }
3228 \strut
3229 \gls{newglossaryentry}\marg{citrine}
3230 \marg{
3231 \field{parent} = \marg{quartz},
3232 \field{name} = \marg{citrine},
3233 \field{description} = \marg{a form of quartz with a colour ranging
3234 from pale yellow to brown due to ferric impurities}
3235 }
3236 \strut
3237 \cmd{begin}\marg{document}
3238 \gls{printunsrtglossary}\oarg{style=indexgroup}
3239 \cmd{end}\marg{document}
3240 \end{codeenv}
3241 This produces:
3242 \begin{result}
3243 \glsaddeach{hier.animal,hier.bird,hier.duck,hier.goose,hier.mineral,%
3244 hier.calcite,hier.quartz,hier.amethyst,hier.citrine}%
3245 \setupglossaries{toc=false,section}%
3246 \glossariesextrasetup{postpunc=dot}%
3247 \renewcommand*{\printunsrtglossaryentryprocesshook}[1]{%
3248 \glsifcategory{#1}{hierarchical}{}{\printunsrtglossaryskipentry}%
3249 }%
3250 \printunsrtglossary[style=indexgroup,title=Glossary,nonumberlist,target=false]
3251 \end{result}
3252
3253 The \glostyle{treenoname} and \glostyle{treenonamegroup} styles are
3254 appropriate for \idxpl{homograph}. These are usually best with the
3255 \styopt{subentrycounter} package option, which defines the
3256 \counter{glossarysubentry} counter that's incremented and
3257 displayed for every level~1 entry (that is, an entry with a parent
3258 but not a grandparent). If the \styopt{entrycounter} option is also
3259 used, \counter{glossaryentry} is set as the master counter for
3260 \counter{glossarysubentry} (although it's not included in the
3261 display form of that counter), but \styopt{subentrycounter} may be used
3262 without \styopt{entrycounter}, in which case
3263 \counter{glossarysubentry} has no master counter. If
3264 \styopt{subentrycounter} is used as a package option and
3265 \styopt{entrycounter} is later switched on outside of the package
3266 option list (through \gls{setupglossaries} or in the optional argument of
3267 \gls{printunsrtglossary}) then it won't be made the master counter.
3268
3269 For example:
3270 \begin{codeenv}
3271 \cmd{documentclass}\marg{scrartcl}
3272 \strut
3273 \cmd{usepackage}[\styopt{subentrycounter},\comment{create glossarysubentry counter}
3274 \styopt[dot]{postpunc},\comment{append full stop after description}
3275 \styopt{nostyles},\styopt[tree]{stylemods}]\marg{glossaries-extra}
3276 \strut
3277 \gls{newglossaryentry}\marg{bow1}
3278 \marg{
3279 \field{name}=\marg{bow},
3280 \field{description}=\marg{(rhymes with toe)}
3281 }
3282 \strut
3283 \gls{newglossaryentry}\marg{bowknot}
3284 \marg{
3285 \field{parent} = \marg{bow1},
3286 \field{description} = \marg{a knot tied with two loops and loose ends}
3287 }
3288 \strut
3289 \gls{newglossaryentry}\marg{bowweapon}
3290 \marg{
3291 \field{parent} = \marg{bow1},
3292 \field{description} = \marg{a weapon for shooting arrows, made of curved wood
3293 joined at both ends with taut string}
3294 }
3295 \strut
3296 \gls{newglossaryentry}\marg{bow2}
3297 \marg{
3298 \field{name}=\marg{bow},
3299 \field{description}=\marg{(rhymes with cow)}
3300 }
3301 \strut
3302 \gls{newglossaryentry}\marg{bowbend}
3303 \marg{
3304 \field{parent} = \marg{bow2},
3305 \field{description} = \marg{bend head or upper body}
3306 }
3307 \strut
3308 \gls{newglossaryentry}\marg{bowpressure}
3309 \marg{
3310 \field{parent} = \marg{bow2},
3311 \field{description} = \marg{give in to pressure}
3312 }
3313 \strut
3314 \gls{newglossaryentry}\marg{bow3}
3315 \marg{
3316 \field{name}=\marg{bow},
3317 \field{description}=\marg{(also bows) the front end of a ship}
3318 }
3319 \strut
3320 \gls{newglossaryentry}\marg{glossary}\marg{\field{name}=\marg{glossary},\field{description}=\marg{}}
3321 \strut
3322 \gls{newglossaryentry}\marg{glossarycol}
3323 \marg{
3324 \field{parent} = \marg{glossary},
3325 \field{description} = \marg{collection of glosses}
3326 }
3327 \strut
3328 \gls{newglossaryentry}\marg{glossarylist}
3329 \marg{
3330 \field{parent} = \marg{glossary},
3331 \field{description} = \marg{list of technical words}
3332 }
3333 \strut
3334 \cmd{begin}\marg{document}
3335 \gls{printunsrtglossary}\oarg{style=treenoname}
3336 \cmd{end}\marg{document}
3337 \end{codeenv}
3338 This produces
3339 \begin{result}
3340 \glsaddeach{hom.bow1,hom.bowknot,hom.bowweapon,%
3341 hom.bow2,hom.bowbend,hom.bowpressure,hom.bow3,%
3342 hom.glossary,hom.glossarycol,hom.glossarylist}%
3343 \setupglossaries{toc=false,section,subentrycounter}%
3344 \glossariesextrasetup{postpunc=dot}%
3345 \renewcommand*{\printunsrtglossaryentryprocesshook}[1]{%
3346 \glsifcategory{#1}{homograph}{}{\printunsrtglossaryskipentry}%
3347 }%
3348 \printunsrtglossary[style=treenoname,title=Glossary,nonumberlist,target=false]
3349 \end{result}
3350 The empty description for the top-level \code{glossary} entry has
3351 caused an odd effect with a space occurring between the name and the
3352 post-description punctuation. This can be removed by redefining:
3353 \nosecformatdef{glstreenonamedesc}
3354 so that it checks if the \field{description} field has been set with:
3355 \nosecformatdef{ifglshasdesc}
3356 For example:
3357 \begin{codeenv}
3358 \cmd{renewcommand}\marg{\gls{glstreenonamedesc}}[1]\marg{\comment{}
3359 \gls{ifglshasdesc}\marg{\gls{param}1}
3360 \marg{\gls[noindex=false]{glstreepredesc}\gls{glossentrydesc}\marg{\gls{param}1}\gls{glspostdescription}}
3361 \marg{}\comment{do nothing, description field is empty}
3362 }
3363 \end{codeenv}
3364 Another variation is to check if the entry has children add use a
3365 colon instead of a \idx{full-stop}. The base \sty{glossaries}
3366 package provides:
3367 \nosecformatdef{ifglshaschildren}
3368 However this method is very inefficient as it has to iterate over
3369 all defined entries and check if any have the \field{parent} field
3370 set to \meta{entry label}. A more efficient method can be obtained
3371 with \bibgls\ and the \csopt{save-child-count} resource option,
3372 which will save the number of child entries that have been indexed
3373 in an internal field labelled \field{childcount} and a list of child
3374 entry labels is stored in the internal field labelled
3375 \field{childlist}. In this case, a more efficient method is to use:
3376 \nosecformatdef{GlsXtrIfHasNonZeroChildCount}
3377 which checks the \field{childcount} field for a non-zero value.
3378 If you don't use \bibgls, this command will always do \meta{false}
3379 (unless you explicitly set the internal fields to the correct
3380 values, which is tedious and has to be updated whenever
3381 definitions are added, deleted or have the \field{parent} field
3382 changed).
3383
3384 Another variation could use custom fields (see
3385 \sectionref{sec:userkeys}) to store the pronunciation guide (\qt{rhymes
3386 with \ldots}) and the alternative version (\qt{also \ldots}) as well
3387 as other information, such as whether the word is a noun or verb.
3388
3389 \subsection{Multiple Glossaries}
3390 \label{sec:multigloss}
3391
3392 The default glossary has the label \code{main}, but it can also be referenced
3393 with:
3394 \nosecformatdef{glsdefaulttype}
3395 The \styopt{nomain} package option suppresses the creation of the
3396 \code{main} glossary, in which case \gls{glsdefaulttype} will be set to
3397 the first glossary to be defined. (There must be at least one
3398 glossary defined, so if you use \styopt{nomain} you must provide
3399 another default.) If you use the \styopt{entrycounter} package
3400 option, the associated counter isn't reset at the start of the
3401 glossary. If you have multiple glossaries and you need it to be reset, add:
3402 \nosecformatdef{glsresetentrycounter}
3403 before the start of the appropriate glossary.
3404
3405 Abbreviations defined with \gls{newabbreviation}
3406 (see \sectionref{sec:abbreviations}) are, by default, assigned to the glossary
3407 given by:
3408 \nosecformatdef{glsxtrabbrvtype}
3409 This initially expands to \gls{glsdefaulttype}, but the
3410 \styopt{abbreviations} option redefines this to \code{abbreviations}
3411 and creates a glossary with that label.
3412
3413 Abbreviations defined with \gls{newacronym} are, by default,
3414 assigned to the glossary given by:
3415 \nosecformatdef{acronymtype}
3416 This initially expands to \gls{glsdefaulttype}, but the
3417 \styopt{abbreviations} option redefines this to
3418 \gls{glsxtrabbrvtype}. However, the \styopt{acronyms} option
3419 redefines \gls{acronymtype} to \code{acronym} and creates a glossary
3420 with that label. So if you use both the \styopt{abbreviations} and
3421 \styopt{acronyms} package options, you will have two extra
3422 glossaries created, one as the default for \gls{newabbreviation} and
3423 the other as the default for \gls{newacronym}.
3424
3425 The \styopt{symbols} package option creates a glossary with the
3426 label \code{symbols} and defines \gls{glsxtrnewsymbol} (see
3427 \sectionref{sec:symbols}) which sets the \field{type} to
3428 \code{symbols}. There are also similar package options
3429 \styopt{numbers} and \styopt{index}, which create the \code{numbers}
3430 glossary (and \gls{glsxtrnewnumber}) and the \code{index} glossary
3431 (and \gls{newterm}).
3432
3433 In each case, the default type can be overridden when defining an
3434 entry by using the \field{type} key in the assignment list. The
3435 value must be the label identifying a defined glossary.
3436
3437 You can provide your own custom glossary using:
3438 \nosecformatdef{newglossary*}
3439 where \meta{type} is the label used to identify the glossary and
3440 \meta{title} is the default title used by \gls{printunsrtglossary}.
3441 (The unstarred version has a different syntax and is only applicable
3442 with \gls{makeindex} or \gls{xindy}.) For example:
3443 \begin{codeenv}
3444 \gls{newglossary*}\marg{measurements}\marg{SI Units}
3445 \gls{newglossaryentry}\marg{length}
3446 \marg{\comment{settings:}
3447 \field{name} = \marg{\gls{si}\marg{\cmd{metre}}},
3448 \field{description} = \marg{length},
3449 \field{type} = \marg{measurements}\comment{glossary label}
3450 }
3451 \end{codeenv}
3452 In this case, the label identifying the new glossary is
3453 \code{measurements} and the title is \qt{SI Units}.
3454
3455 You can specify the glossary using the \printglossopt{type} setting
3456 in the optional argument of \gls{printunsrtglossary}. For example,
3457 the above \code{measurements} glossary can be displayed with:
3458 \begin{codeenv}
3459 \gls{printunsrtglossary}\oarg{\printglossopt[measurements]{type}}
3460 \end{codeenv}
3461 For convenience, there's a command that iterates over all defined
3462 glossaries (in the order of definition) and does
3463 \gls{printunsrtglossary}\oarg{\printglossopt[\meta{label}]{type}}
3464 for each glossary:
3465 \nosecformatdef{printunsrtglossaries}
3466 There's no optional argument for this command. When creating
3467 glossaries with package options, such as \styopt{abbreviations}, you
3468 may find an unexpected order as the options aren't always processed
3469 in the order in which they were specified. (Some
3470 \sty{glossaries-extra} options are passed to the base
3471 \sty{glossaries} package and are processed when that package is
3472 internally loaded not when the extension options are processed.) In
3473 which case you need to use \gls{printunsrtglossary} for each
3474 glossary in the required order. You will also need to do this if the
3475 glossary settings are different. (For example, if one glossary needs
3476 to use the \glostyle{tree} style and another needs to use the
3477 \glostyle{treenoname} style.)
3478
3479 You can also define an \pidx{ignoredglossary}, which is ignored by
3480 \gls{printunsrtglossaries}. This is a useful way of creating a
3481 glossary for common terms that shouldn't appear in a list or for
3482 stand-alone entries (see \sectionref{sec:standalone}). The unstarred
3483 form:
3484 \nosecformatdef{newignoredglossary}
3485 is useful for common terms where the list won't be displayed as it
3486 automatically suppresses hyperlinks for entries assigned to that
3487 glossary. The starred form:
3488 \nosecformatdef{newignoredglossary*}
3489 is useful for stand-alone entries as it doesn't automatically
3490 suppress the hyperlinks.
3491 Although \gls{printunsrtglossaries} skips \idxpl{ignoredglossary},
3492 it's still possible to display an \idx{ignoredglossary} with
3493 \gls{printunsrtglossary} but you'll need to use the
3494 \printglossopt{title} option to override the default title.
3495
3496 \subsection{Redisplaying or Filtering a Glossary}
3497 \label{sec:printglossagain}
3498
3499 It's possible to use \gls{printunsrtglossary} multiple times for the
3500 same glossary, but if you have hyperlinks you will need to either
3501 suppress the targets with \printglossopt[false]{target} or change
3502 the target name (see \sectionref{sec:targetnames}).
3503
3504 The starred form of \gls{printunsrtglossary} has an extra
3505 argument:
3506 \nosecformatdef{printunsrtglossary*}
3507 This may be used to make local assignments. It's equivalent to:
3508 \begin{codeenv}
3509 \cmd{begingroup} \meta{code}\gls{printunsrtglossary}\oargm{options}\cmd{endgroup}
3510 \end{codeenv}
3511 For example, if the \field{group} key has been defined (see
3512 \sectionref{sec:group}) you can locally switch to a different field
3513 for the group label by redefining:
3514 \nosecformatdef{glsxtrgroupfield}
3515 within \meta{code}.
3516 For example, if the \field{secondarygroup} field has been defined:
3517 \begin{codeenv}
3518 \gls{printunsrtglossary*}\marg{\comment{}
3519 \cmd{renewcommand}\marg{\gls{glsxtrgroupfield}}\marg{secondarygroup}\comment{}
3520 }
3521 \end{codeenv}
3522 Note that this just changes the group labels. The order is still
3523 according to the glossary's internal list of labels.
3524
3525 Unlike \gls{printglossary} (used with \gls{makeindex} and
3526 \gls{xindy}) which inputs a file containing the code to typeset the glossary,
3527 \gls{printunsrtglossary} iterates over the labels defined in the
3528 given glossary and adds the appropriate code to an internal command.
3529 Once the construction of the internal command is completed, it's
3530 then performed. (The construction of this internal command is done
3531 to avoid complications when iterating within \env{tabular}-like
3532 environments, as some of the styles use \env{longtable} or
3533 \env{supertabular}.) There's a hook just before the internal command is
3534 expanded:
3535 \nosecformatdef{printunsrtglossarypredoglossary}
3536 The glossary header and preamble are displayed before
3537 the loop starts, so this hook won't change them (but you can make
3538 local changes in \meta{code} outside of the hook).
3539 The style is also set before the loop, but the start
3540 and end of the \env{theglossary} environment (which is defined by
3541 the glossary styles) is included in the internal command, so minor
3542 adjustments to the style can be made in this hook.
3543
3544 There's another hook that's performed at each iteration:
3545 \nosecformatdef{printunsrtglossaryentryprocesshook}
3546 where \meta{label} is the current entry label. For example, the
3547 \glostyle{alttree} style needs to know the widest entry name in
3548 order to set up the correct indentation. The widest name is set
3549 using:
3550 \nosecformatdef{glssetwidest}
3551 but this requires knowing which entry has the widest name. There are
3552 some commands provided by the \sty{glossary-tree} and
3553 \sty{glossaries-extra-stylemods} packages that iterate over all
3554 entries, measuring each name, in order to find the widest, but since
3555 \gls{printunsrtglossary} already has to iterate over the list before
3556 typesetting it, this hook can be used to update the widest name at
3557 the same time. You can update the value with:
3558 \nosecformatdef{glsupdatewidest}
3559 which computes the width of \meta{text} and, if it's wider than the
3560 current widest name for the given level, sets the widest value to
3561 \meta{text} (without expanding it). If \meta{text} needs expanding
3562 you need to use:
3563 \nosecformatdef{eglsupdatewidest}
3564 The \meta{level} refers to the entry's hierarchical level with a
3565 value of~0 indicating top-level (that is, an entry without a parent).
3566 The level is stored in the internal \field{level} field and can only
3567 be accessed with \gls{glsxtrusefield} or similar commands
3568 (see \sectionref{sec:userkeys}).
3569
3570 You can also redefine this hook to filter the glossary list.
3571 If an entry shouldn't appear in the list, use:
3572 \nosecformatdef{printunsrtglossaryskipentry}
3573 For example, to only include entries that have the \field{category}
3574 set to \code{formula}:
3575 \begin{codeenv}
3576 \gls{printunsrtglossary*}\oarg{\printglossopt{target}=false,\printglossopt{title}=\marg{Formula}}
3577 \marg{\comment{local code:}
3578 \cmd{renewcommand}\marg{\gls{printunsrtglossaryentryprocesshook}}[1]\marg{\comment{}
3579 \gls{glsifcategory}\marg{\gls{param}1}\marg{formula}
3580 \marg{}\comment{category = formula}
3581 \marg{\gls{printunsrtglossaryskipentry}}\comment{}
3582 }\comment{}
3583 }
3584 \end{codeenv}
3585 This uses \gls{glsifcategory} to check the value of the entry's
3586 \field{category} field (see \sectionref{sec:categories}). Another
3587 conditional you might find useful is:
3588 \nosecformatdef{glsxtriflabelinlist}
3589 which tests if the given \meta{label} is in the comma-separated
3590 \meta{list} of labels. Both \meta{label} and \meta{list} are fully
3591 expanded before testing. This command is only intended for labels,
3592 which must be fully expandable.
3593 For example, the following excludes any entries that have the
3594 \field{category} set to \code{abbreviation} or \code{acronym}:
3595 \begin{codeenv}
3596 \gls{printunsrtglossary*}\oarg{\printglossopt{target}=false,\printglossopt{title}=\marg{Formula}}
3597 \marg{\comment{local code:}
3598 \cmd{renewcommand}\marg{\gls{printunsrtglossaryentryprocesshook}}[1]\marg{\comment{}
3599 \gls{glsxtriflabelinlist}
3600 \marg{\gls{glscategory}\marg{\gls{param}1}}\comment{category label for this entry}
3601 \marg{abbreviation,acronym}\comment{exclusion list}
3602 \marg{\gls{printunsrtglossaryskipentry}}\comment{skip (exclude)}
3603 \marg{}\comment{don't skip (include)}
3604 }\comment{}
3605 }
3606 \end{codeenv}
3607
3608 \subsection{Hyperlink Targets}
3609 \label{sec:targetnames}
3610
3611 The naming system used for the hyperlinks from commands like
3612 \gls{gls} and \gls{glssymbol} to the corresponding definition in the
3613 glossary is given by \meta{prefix}\meta{label} where \meta{label} is
3614 the entry's label and \meta{prefix} is given by:
3615 \nosecformatdef{glolinkprefix}
3616 This can locally be changed within commands like \gls{gls} and
3617 \gls{glssymbol} with the \glsopt{prefix} option. There is a matching
3618 \printglossopt{prefix} option for \gls{printunsrtglossary}.
3619 You can set an additional prefix in the glossary with
3620 \printglossopt[\meta{extra}]{targetnameprefix}, which means that the
3621 target name in the glossary is now
3622 \code{\meta{extra}\gls{glolinkprefix}\meta{label}} (so
3623 \printglossopt{targetnameprefix} doesn't modify \gls{glolinkprefix}
3624 but prepends an extra prefix).
3625
3626 If you change the prefix either by using the above options or by
3627 redefining \gls{glolinkprefix}, you need to make sure that the
3628 target names match for the links to work correctly.
3629 The \styopt[showtargets]{debug} package option can be used to show
3630 the target names in the document. The target is displayed in the
3631 document using:
3632 \nosecformatdef{glsshowtarget}
3633 which may be redefined as appropriate. For example:
3634 \begin{codeenv}
3635 \cmd{documentclass}\marg{article}
3636 \strut
3637 \cmd{usepackage}\marg{hyperref}
3638 \cmd{usepackage}[\styopt{debug}=showtargets]\marg{glossaries-extra}
3639 \strut
3640 \gls{newglossaryentry}\marg{sample}\marg{\field{name}=\marg{sample},\field{description}=\marg{an example}}
3641 \strut
3642 \cmd{begin}\marg{document}
3643 \gls{gls}\oarg{\glsopt{prefix}=\marg{TARGET.}}\marg{sample}.
3644 \strut
3645 \gls{printunsrtglossary}\oarg{\printglossopt{prefix}=\marg{TARGET.}}
3646 \gls{printunsrtglossary}\oarg{\printglossopt{prefix}=\marg{TARGET.},\printglossopt{targetnameprefix}=\marg{EXTRA.}}
3647 \cmd{end}\marg{document}
3648 \end{codeenv}
3649
3650 \section{Stand-alone Definitions}
3651 \label{sec:standalone}
3652
3653 The \sty{glossaries-extra} package provides:
3654 \nosecformatdef{glsxtrglossentry}
3655 which may be used to create a target for a particular entry (identified by
3656 \meta{label}). This displays the value of the \field{name} field,
3657 but it also obeys the \idx{postnamehook} (see
3658 \sectionref{sec:postfieldhooks}), the \catattr{glossname}
3659 and \catattr{glossnamefont} attributes (see
3660 \sectionref{sec:glossname}), and provides accessibility support if
3661 the \field{access} field is set (see \sectionref{sec:accsupp}).
3662 This command may be used for both top-level and child entries, and
3663 will obey the \styopt{entrycounter} (see below) and \styopt{subentrycounter}
3664 (see \sectionref{sec:parent}) package options according to the
3665 entry's hierarchical level.
3666
3667 This command doesn't display any of the other field values.
3668 If any are required, you need to add them afterwards.
3669 For the description, you can use \gls{glsentrydesc}, but it's better
3670 to use:
3671 \nosecformatdef{glossentrydesc}
3672 Unlike \gls{glsentrydesc}, which just displays the value of the
3673 \field{description} field, \gls{glossentrydesc} obeys the
3674 \catattr{glossdesc} and \catattr{glossdescfont} attributes
3675 (\sectionref{sec:glossname}). Alternatively, you can use:
3676 \nosecformatdef{Glossentrydesc}
3677 which converts the first letter of the description to
3678 \idx{uppercase}.
3679 To pick up the \styopt{postpunc} setting and the
3680 \glslink{postdescriptionhook}{post-description category hook},
3681 append \gls{glspostdescription}
3682 after the description (see \sectionref{sec:postfieldhooks}).
3683
3684 There's a similar command for symbols:
3685 \nosecformatdef{glossentrysymbol}
3686 There are currently no category attributes governing this
3687 command, but it does check for the \field{symbolaccess} field if
3688 accessibility support has been added (see \sectionref{sec:accsupp}).
3689 For other fields, you can use the commands described in
3690 \sectionref{sec:userkeys}.
3691
3692 If you need to substitute the \field{name} for another field in the
3693 target, you can use:
3694 \nosecformatdef{glsxtrglossentryother}
3695 instead of \code{\gls{glsxtrglossentry}\margm{label}},
3696 where \meta{label} identifies the entry and \meta{field} is the
3697 internal field label to use instead of the \field{name}. The
3698 \meta{header} argument is the code to use in the header (which
3699 should be left empty for the default value\footnote{The
3700 \meta{header} argument doesn't use standard \LaTeX\ optional syntax
3701 \code{\oargm{option}} because \gls{glsxtrglossentryother} has to be
3702 expandable in order for it to work correctly in section arguments.})\ if
3703 \gls{glsxtrglossentryother} is used in a sectioning command. This
3704 command obeys the \catattr{glossname} and \catattr{glossnamefont}
3705 attributes and the \idx{postnamehook}, even though it's not actually
3706 displaying the name. For example,
3707 \begin{codeenv}
3708 \cmd{section}\marg{\gls{glsxtrglossentryother}\marg{}\marg{duck}\marg{\field{plural}}}
3709 \end{codeenv}
3710
3711 Here's a complete example that uses \gls{glsxtrglossentry} after an
3712 equation to describe the notation:
3713 \begin{codeenv}
3714 \cmd{documentclass}\marg{article}
3715 \strut
3716 \cmd{usepackage}\marg{\gls[noindex=false]{xcolor}}\comment{provides colour}
3717 \cmd{usepackage}[colorlinks,linkcolor=purple]\marg{\gls[noindex=false]{hyperref}}
3718 \cmd{usepackage}[\styopt[dot]{postpunc}]\marg{glossaries-extra}
3719 \strut
3720 \gls{newglossaryentry}\marg{pi}
3721 \marg{
3722 \field{name} = \marg{\gls{ensuremath}\marg{\cmd{pi}}},
3723 \field{description} = \marg{Archimedes' constant}
3724 }
3725 \strut
3726 \gls{newglossaryentry}\marg{radius}
3727 \marg{
3728 \field{name} = \marg{\gls{ensuremath}\marg{r}},
3729 \field{description} = \marg{radius}
3730 }
3731 \strut
3732 \gls{newglossaryentry}\marg{area}
3733 \marg{
3734 \field{name} = \marg{\gls{ensuremath}\marg{A}},
3735 \field{description} = \marg{area}
3736 }
3737 \strut
3738 \cmd{begin}\marg{document}
3739 \cmd{begin}\marg{equation}
3740 \gls{gls}\marg{area} = \gls{gls}\marg{pi}\gls{gls}\marg{radius}[\gls{spchar}2]
3741 \cmd{end}\marg{equation}
3742 \cmd{begin}\marg{tabular}\marg{ll}
3743 \gls{glsxtrglossentry}\marg{area} \gls[noindex=false]{colsep} \gls{glossentrydesc}\marg{area}\gls{glspostdescription}\gls[noindex=false]{cs.backslash}
3744 \gls{glsxtrglossentry}\marg{pi} \gls{colsep} \gls{glossentrydesc}\marg{pi}\gls{glspostdescription}\gls{cs.backslash}
3745 \gls{glsxtrglossentry}\marg{radius} \gls{colsep} \gls{glossentrydesc}\marg{radius}\gls{glspostdescription}
3746 \cmd{end}\marg{tabular}
3747 \cmd{end}\marg{document}
3748 \end{codeenv}
3749 This produces:
3750 \begin{result}
3751 \setcounter{equation}{0}%
3752 \renewcommand{\theequation}{\arabic{equation}}%
3753 \renewcommand{\theHequation}{\thechapter.standalone1.\arabic{equation}}%
3754 \renewcommand{\glolinkprefix}{standalone1}%
3755 \renewcommand{\glstextformat}[1]{\textcolor{purple}{#1}}%
3756 \renewcommand{\glslinkpresetkeys}{\setkeys{glslink}{local}}%
3757 \glossariesextrasetup{postdot}%
3758 \begin{equation}
3759 \gls{standalone.area} = \gls{standalone.pi}\gls{standalone.radius}[^2]
3760 \end{equation}
3761 \begin{tabular}{ll}
3762 \glsxtrglossentry{standalone.area} & \glossentrydesc{standalone.area}\glspostdescription\\
3763 \glsxtrglossentry{standalone.pi} & \glossentrydesc{standalone.pi}\glspostdescription\\
3764 \glsxtrglossentry{standalone.radius} & \glossentrydesc{standalone.radius}\glspostdescription
3765 \end{tabular}
3766 \end{result}
3767 The purple text shows the hyperlinks to the relevant definition. As
3768 with \gls{printunsrtglossary}, the hypertargets are prefixed with
3769 \gls{glolinkprefix} (see \sectionref{sec:printglossagain}). This
3770 can be locally changed to avoid clashes if the definition needs to
3771 be reproduced later.
3772
3773 A more convenient approach to the above is to define an environment that can
3774 list all the referenced entries automatically. The
3775 \sty{glossaries-extra} package provides a way of buffering the
3776 boolean switch performed by \gls{gls} that ensures that the
3777 \idx{firstuseflag} is unset (see \sectionref{sec:buffering}).
3778 This is intended for use where the switch causes a problem, but it
3779 can also be used in this case to store a list of used entries (since
3780 there's no difference between \idx{firstuse} and subsequent use in
3781 this case, it won't affect the \idx{link-text}).
3782
3783 Here's a modified version of the above document:
3784 \begin{codeenv}
3785 \cmd{documentclass}\marg{article}
3786 \strut
3787 \cmd{usepackage}\marg{xcolor}
3788 \cmd{usepackage}[colorlinks,linkcolor=purple]\marg{hyperref}
3789 \cmd{usepackage}[\styopt[dot]{postpunc}]\marg{glossaries-extra}
3790 \strut
3791 \gls{newglossaryentry}\marg{pi}
3792 \marg{
3793 \field{name} = \marg{\gls{ensuremath}\marg{\cmd{pi}}},
3794 \field{description} = \marg{Archimedes' constant}
3795 }
3796 \strut
3797 \gls{newglossaryentry}\marg{radius}
3798 \marg{
3799 \field{name} = \marg{\gls{ensuremath}\marg{r}},
3800 \field{description} = \marg{radius}
3801 }
3802 \strut
3803 \gls{newglossaryentry}\marg{area}
3804 \marg{
3805 \field{name} = \marg{\gls{ensuremath}\marg{A}},
3806 \field{description} = \marg{area}
3807 }
3808 \strut
3809 \gls{newglossaryentry}\marg{circumference}
3810 \marg{
3811 \field{name} = \marg{\gls{ensuremath}\marg{C}},
3812 \field{description} = \marg{circumference}
3813 }
3814 \strut
3815 \cmd{newcommand}\marg{\cmd{doglossaryentry}}[1]\marg{\comment{handler macro}
3816 \gls{glsxtrglossentry}\marg{\gls{param}1} \gls{colsep} \gls{glossentrydesc}\marg{\gls{param}1}\gls{glspostdescription}\gls{cs.backslash}\comment{}
3817 }
3818 \strut
3819 \cmd{newcounter}\marg{localglossary}
3820 \strut
3821 \cmd{newenvironment}\marg{localglossary}
3822 \marg{\comment{}
3823 \cmd{stepcounter}\marg{localglossary}\comment{}
3824 \cmd{renewcommand}\marg{\gls{glolinkprefix}}\marg{\cmd{thelocalglossary}.}\comment{}
3825 \gls{GlsXtrStartUnsetBuffering}*
3826 }
3827 \marg{\comment{}
3828 \cmd{par}
3829 \cmd{begin}\marg{tabular}\marg{ll}
3830 \gls{GlsXtrForUnsetBufferedList}\cmd{doglossaryentry}
3831 \cmd{end}\marg{tabular}
3832 \gls{GlsXtrStopUnsetBuffering}
3833 \cmd{par}
3834 }
3835 \strut
3836 \cmd{begin}\marg{document}
3837 The area of a circle is given by:
3838 \cmd{begin}\marg{localglossary}
3839 \cmd{begin}\marg{equation}
3840 \gls{gls}\marg{area} = \gls{gls}\marg{pi}\gls{gls}\marg{radius}[\gls{spchar}2]
3841 \cmd{end}\marg{equation}
3842 \cmd{end}\marg{localglossary}
3843 The circumference of a circle is given by:
3844 \cmd{begin}\marg{localglossary}
3845 \cmd{begin}\marg{equation}
3846 \gls{gls}\marg{circumference} = 2\gls{gls}\marg{pi}\gls{gls}\marg{radius}
3847 \cmd{end}\marg{equation}
3848 \cmd{end}\marg{localglossary}
3849 \cmd{end}\marg{document}
3850 \end{codeenv}
3851 This produces:
3852 \begin{result}
3853 \setcounter{equation}{0}%
3854 \renewcommand{\theequation}{\arabic{equation}}%
3855 \renewcommand{\theHequation}{\thechapter.standalone2.\arabic{equation}}%
3856 \renewcommand{\glolinkprefix}{standalone2}%
3857 \renewcommand{\glstextformat}[1]{\textcolor{purple}{#1}}%
3858 \renewcommand{\glslinkpresetkeys}{}%
3859 \glossariesextrasetup{postdot}%
3860 The area of a circle is given by:
3861 \begin{localglossary}
3862 \begin{equation}
3863 \gls{standalone.area} = \gls{standalone.pi}\gls{standalone.radius}[^2]
3864 \end{equation}
3865 \end{localglossary}
3866 The circumference of a circle is given by:
3867 \begin{localglossary}
3868 \begin{equation}
3869 \gls{standalone.circumference} = 2\gls{standalone.pi}\gls{standalone.radius}
3870 \end{equation}
3871 \end{localglossary}
3872 \end{result}
3873 The custom \counterfmt{localglossary} counter is defined and incremented to
3874 ensure that the target prefix \gls{glolinkprefix} is unique for each
3875 environment. This definition of the custom \envfmt{localglossary}
3876 environment is intentionally kept trivial since the main point here is
3877 the demonstration of \gls{glsxtrglossentry} and the buffering rather
3878 than the actual formatting of the entries. Additional vertical
3879 spacing, appropriate alignment and a paragraph column specifier are
3880 left as an exercise for the reader.
3881
3882 \subsection{Numbering Top-Level Entries}
3883 \label{sec:entrycounter}
3884
3885 The \styopt{entrycounter} package option creates a new counter
3886 called \counter{glossaryentry}, which will automatically be
3887 incremented and displayed at the start of \gls{glsxtrglossentry}
3888 for top-level entries. (The \counter{glossarysubentry} counter created with the
3889 \styopt{subentrycounter} option, described in \sectionref{sec:parent},
3890 may be used independently of the \styopt{entrycounter} package option.) In
3891 the above example, this counter will need to depend on the custom
3892 \counterfmt{localglossary} counter to ensure that it's reset at the
3893 start of each \envfmt{localglossary} environment. This can easily be
3894 done by using the name of the master counter as the value of
3895 \styopt{counterwithin} (which automatically implements
3896 \styopt{entrycounter}), but the master counter must be defined
3897 first:
3898 \begin{codeenv}
3899 \cmd{newcounter}\marg{localglossary}
3900 \cmd{usepackage}[\styopt[localglossary]{counterwithin}]\marg{glossaries-extra}
3901 \end{codeenv}
3902 The default definition of \gls{theHglossaryentry} is:
3903 \begin{codeenv}
3904 \gls{currentglossary}.\gls[noindex=false]{theglossaryentry}
3905 \end{codeenv}
3906 The prefix \gls{currentglossary} is set by both
3907 \gls{printunsrtglossary} and \gls{glsxtrglossentry} to the current
3908 glossary label (given by the \printglossopt{type} option in
3909 \gls{printunsrtglossary} and by the entry's \field{type} field for
3910 \gls{glsxtrglossentry}). In the case of \gls{glsxtrglossentry}
3911 (and \gls{glsxtrglossentryother}), the value of
3912 \gls{currentglossary} is obtained from:
3913 \nosecformatdef{GlsXtrStandaloneGlossaryType}
3914 which defaults to the value of the \field{type} field for the
3915 current entry.
3916
3917 Since this example is using multiple stand-alone definitions that
3918 may repeat the same entry, this definition isn't appropriate and will
3919 cause duplicate destination warnings. The simplest solution is to redefine
3920 \gls{GlsXtrStandaloneGlossaryType} in terms of the custom
3921 \counterfmt{localglossary} counter value:
3922 \begin{codeenv}
3923 \cmd{renewcommand}\marg{\cmd{GlsXtrStandaloneGlossaryType}}\marg{\comment{}
3924 standalone.\cmd{thelocalglossary}.\cmd{arabic}\marg{\counter{glossaryentry}}\comment{}
3925 }
3926 \end{codeenv}
3927
3928 Unlike commands such as \gls{gls}, which can be problematic in moving
3929 arguments, \gls{glsxtrglossentry} is designed to work in section
3930 headings. For example:
3931 \begin{codeenv}
3932 \cmd{documentclass}\marg{article}
3933 \strut
3934 \cmd{usepackage}\marg{mhchem}
3935 \cmd{usepackage}[colorlinks,linkcolor=magenta]\marg{hyperref}
3936 \cmd{usepackage}[\styopt[dot]{postpunc}]\marg{glossaries-extra}
3937 \strut
3938 \gls{newglossaryentry}\marg{amethyst}
3939 \marg{
3940 \field{name} = \marg{amethyst},
3941 \field{description} = \marg{a purple type of quartz},
3942 \field{symbol} = \marg{\gls{ce}\marg{SiO2}},
3943 \field{category} = \marg{mineral}
3944 }
3945 \strut
3946 \gls{glssetcategoryattribute}\marg{mineral}\marg{glossname}\marg{firstuc}
3947 \strut
3948 \cmd{newcommand}\marg{\cmd{displayterm}}[1]\marg{\comment{}
3949 \cmd{subsection}\marg{\gls{glsxtrglossentry}\marg{\gls{param}1}}\comment{}
3950 Chemical formula: \gls{glossentrysymbol}\marg{\gls{param}1}.
3951 \gls{Glossentrydesc}\marg{\gls{param}1}\gls{glspostdescription}\cmd{par}
3952 }
3953 \cmd{begin}\marg{document}
3954 \gls{tableofcontents}
3955 \cmd{section}\marg{Types of Quartz}
3956 A reference to \gls{gls}\marg{amethyst}.
3957 \strut
3958 \cmd{displayterm}\marg{amethyst}
3959 \cmd{end}\marg{document}
3960 \end{codeenv}
3961 (Again, improvements to the actual formatting of the custom
3962 \csfmt{displayterm} is left as an exercise to the reader. Additional
3963 fields could contain, for example, the name of an image file to
3964 illustrated the entry. See the
3965 \href{https://www.dickimaw-books.com/gallery/}{\styfmt{glossaries}
3966 gallery}~\cite{gallery} for further ideas.)
3967
3968 The above example uses the \catattr{glossname} attribute to convert the first
3969 letter of the \field{name} to \idx{uppercase}. Unfortunately this can't be
3970 applied to the PDF bookmark or \gls{toc}. A solution to this
3971 would be to explicitly set the \field{name} with the first letter as
3972 an \idx{uppercase} character and the \field{text} field in
3973 \idx{lowercase}. For example:
3974 \begin{codeenv}
3975 \gls{newglossaryentry}\marg{amethyst}
3976 \marg{
3977 \field{name} = \marg{Amethyst},
3978 \field{text} = \marg{amethyst},
3979 \field{description} = \marg{a purple type of quartz},
3980 \field{symbol} = \marg{\gls{ce}\marg{SiO2}},
3981 \field{category} = \marg{mineral}
3982 }
3983 \end{codeenv}
3984 The \catattr{glossname} attribute can then be omitted. This is a bit
3985 inconvenient, but if you use \bibgls\ (see \sectionref{sec:bib2gls})
3986 this can be performed automatically with the
3987 \csopt{name-case-change} resource option.
3988
3989 \subsection{Stand-alone Hierarchical Entries}
3990 \label{sec:standalonehierarchy}
3991
3992 Sub-entries can also be displayed with \gls{glsxtrglossentry} or
3993 \gls{glsxtrglossentryother}. These check if the entry has a parent
3994 (with \gls{ifglshasparent}). If it doesn't, then it will display
3995 the \counter{glossaryentry} counter label if the
3996 \styopt{entrycounter} package option has been used. If the entry
3997 does have a parent, it uses:
3998 \nosecformatdef{GlsXtrStandaloneSubEntryItem}
3999 which checks the internal \field{level} field to
4000 determine the hierarchical level. If the \field{level} is~1 (that
4001 is, the entry has a parent but not a grandparent) then it will
4002 display the \counter{glossarysubentry} label if that counter has
4003 been defined, otherwise it does nothing.
4004
4005 Here's an example document with a top-level entry (\code{mineral}),
4006 a level~1 entry (\code{quartz}) and a level~2 entry (\code{amethyst}).
4007 \begin{codeenv}
4008 \cmd{documentclass}\marg{article}
4009 \strut
4010 \cmd{usepackage}\marg{xcolor}\comment{provides colour}
4011 \cmd{usepackage}[colorlinks,linkcolor=magenta]\marg{hyperref}
4012 \cmd{usepackage}[
4013 \styopt{entrycounter},\comment{enable top-level counter}
4014 \styopt{subentrycounter},\comment{enable level 1 counter}
4015 \styopt{postpunc}=\marg{dot},\comment{put full-stop after description}
4016 \styopt{nostyles},\comment{suppress automatic loading of default styles}
4017 \styopt[tree]{stylemods}\comment{load glossary-tree.sty}
4018 ]\marg{glossaries-extra}
4019 \strut
4020 \gls{newglossaryentry}\marg{mineral}
4021 \marg{
4022 \field{name} = \marg{mineral},
4023 \field{description} = \marg{natural inorganic substance},
4024 \field{category} = \marg{mineral}
4025 }
4026 \strut
4027 \gls{newglossaryentry}\marg{calcite}
4028 \marg{
4029 \field{parent} = \marg{mineral},
4030 \field{name} = \marg{calcite},
4031 \field{description} = \marg{a carbonate mineral},
4032 \field{category} = \marg{mineral}
4033 }
4034 \strut
4035 \gls{newglossaryentry}\marg{quartz}
4036 \marg{
4037 \field{parent} = \marg{mineral},
4038 \field{name} = \marg{quartz},
4039 \field{description} = \marg{hard mineral consisting of silica},
4040 \field{category} = \marg{mineral}
4041 }
4042 \strut
4043 \gls{newglossaryentry}\marg{amethyst}
4044 \marg{
4045 \field{parent} = \marg{quartz},
4046 \field{name} = \marg{amethyst},
4047 \field{description} = \marg{a purple type of quartz},
4048 \field{category} = \marg{mineral}
4049 }
4050 \strut
4051 \gls{glssetcategoryattribute}\marg{mineral}\marg{glossname}\marg{firstuc}
4052 \strut
4053 \cmd{renewcommand}\marg{\gls[noindex=false]{GlsXtrStandaloneGlossaryType}}\marg{standalone}
4054 \strut
4055 \cmd{newcommand}\marg{\cmd{displayterm}}\oarg{1}\marg{\comment{}
4056 \cmd{par}
4057 Definition \gls{glsxtrglossentry}\marg{\gls{param}1}:
4058 \gls{glossentrydesc}\marg{\gls{param}1}\gls{glspostdescription}\cmd{par}
4059 }
4060 \strut
4061 \cmd{begin}\marg{document}
4062 \cmd{displayterm}\marg{mineral}
4063 \cmd{displayterm}\marg{calcite}
4064 \cmd{displayterm}\marg{quartz}
4065 \cmd{displayterm}\marg{amethyst}
4066 \strut
4067 A reference to \gls{gls}\marg{mineral}.
4068 A reference to \gls{gls}\oarg{\printglossopt{prefix}={main.}}\marg{amethyst}.
4069 \strut
4070 \cmd{renewcommand}\marg{\gls[noindex=false]{GlsEntryCounterLabelPrefix}}\marg{main.glsentry-}
4071 \gls{glsresetentrycounter}
4072 \gls{printunsrtglossary}\oarg{\printglossopt{prefix}=\marg{main.},\printglossopt{style}=tree}
4073 \cmd{end}\marg{document}
4074 \end{codeenv}
4075 This produces:
4076 \begin{result}
4077 \renewcommand{\glslinkpresetkeys}{\setkeys{glslink}{local}}%
4078 \def\glolinkprefix{standalone.hier.}%
4079 \renewcommand{\glstextformat}[1]{\textcolor{magenta}{#1}}%
4080 \setupglossaries{entrycounter,subentrycounter,section,toc=false}%
4081 \glossariesextrasetup{postdot}%
4082 \glssetcategoryattribute{hierarchical}{glossname}{firstuc}%
4083 \renewcommand{\GlsXtrStandaloneGlossaryType}{standalone}%
4084 \newcommand{\displayterm}[1]{%
4085 \par
4086 \begingroup
4087 Definition \glsxtrglossentry{#1}:
4088 \glossentrydesc{#1}\glspostdescription\par
4089 \endgroup
4090 }%
4091 \displayterm{hier.mineral}
4092 \displayterm{hier.calcite}
4093 \displayterm{hier.quartz}
4094 \displayterm{hier.amethyst}
4095
4096 A reference to \gls{hier.mineral}.
4097 A reference to \gls[prefix={hierarchical.main.}]{hier.amethyst}.
4098
4099 \printunsrtglossary*[prefix={hierarchical.main.},style=tree,nonumberlist]
4100 {%
4101 \glsresetentrycounter
4102 \renewcommand{\GlsEntryCounterLabelPrefix}{main.glsentry-}%
4103 \renewcommand*{\printunsrtglossaryentryprocesshook}[1]{%
4104 \glsxtriflabelinlist{#1}{hier.mineral,hier.calcite,hier.quartz,hier.amethyst}%
4105 {}{\printunsrtglossaryskipentry}%
4106 }%
4107 }
4108 \end{result}
4109 Note the need to reset the \counter{glossaryentry} counter with
4110 \gls{glsresetentrycounter} before the main glossary. The top-level
4111 entry (\code{mineral}) has the label formatted as
4112 \qt{1.\textvisiblespace} and the level~1 entries (\code{calcite}
4113 and \code{quartz}) have their labels formatted as
4114 \qt{1)\textvisiblespace} and \qt{2)\textvisiblespace} but the
4115 level~2 entry (\code{amethyst}) doesn't have an associated number.
4116 If you want to number levels deeper than 1, you will have to provide
4117 your own custom counters. (If the stand-alone level~2 entry shows a
4118 number when you try this, then you've encountered a bug that's been
4119 fixed in \sty{glossaries-extra} version~1.31.)
4120
4121 The hyperlinks are shown in magenta. The first (\code{mineral}) links to the
4122 stand-alone target, and the second (\code{amethyst}) links to the entry in
4123 the main glossary.
4124
4125 \chapter{Changing the Formatting}
4126 \label{sec:glsformats}
4127
4128 All commands like \gls{gls} and \gls{glssymbol} by default
4129 encapsulate the \idx{link-text} within the argument of:
4130 \nosecformatdef{glstextformat}
4131 For example:
4132 \begin{codeenv}
4133 \cmd{documentclass}\marg{article}
4134 \strut
4135 \cmd{usepackage}\marg{xcolor}\comment{provides colour}
4136 \cmd{usepackage}\marg{pifont}\comment{provides \gls{ding}}
4137 \cmd{usepackage}\marg{glossaries-extra}
4138 \strut
4139 \gls{newglossaryentry}\marg{duck}\comment{label}
4140 \marg{
4141 \field{name} = \marg{duck},
4142 \field{description} = \marg{a waterbird with webbed feet}
4143 }
4144 \strut
4145 \gls{newglossaryentry}\marg{fleuron}\comment{label}
4146 \marg{
4147 \field{name} = \marg{fleuron},
4148 \field{symbol} = \marg{\gls[noindex=false]{ding}\marg{167}},
4149 \field{category} = \marg{ornament},
4150 \field{description} = \marg{typographic ornament}
4151 }
4152 \strut
4153 \gls{newabbreviation}\marg{tug}\marg{TUG}\marg{\cmd{TeX}\gls{cs.space}Users Group}
4154 \strut
4155 \cmd{renewcommand}\marg{\gls{glstextformat}}[1]\marg{\cmd{textcolor}\marg{violet}\marg{\gls{param}1}}
4156 \strut
4157 \cmd{begin}\marg{document}
4158 A \gls{gls}\marg{duck}, a \gls{gls}\marg{fleuron} (\gls{glssymbol}\marg{fleuron},
4159 \gls{glsentrydesc}\marg{fleuron}) and \gls{gls}\marg{tug}.
4160 \cmd{end}\marg{document}
4161 \end{codeenv}
4162 This produces:
4163 \begin{result}%
4164 \renewcommand{\glstextformat}[1]{\textcolor{violet}{#1}}%
4165 A \gls{ex1.duck}, a \gls{ex.fleuron} (\glssymbol{ex.fleuron},
4166 \glsentrydesc{ex.fleuron}) and \gls{TUG}.
4167 \end{result}
4168 Note that this has affected \gls{gls} and \gls{glssymbol} but not
4169 \gls{glsentrydesc}.
4170
4171 A distinction can be made between abbreviations (\idx{non-regular}
4172 terms) and \idx{regular} terms (non-abbreviations or abbreviations
4173 that are considered \idx{regular} entries).
4174 A \idx{regular} term is encapsulated with
4175 \nosecformatdef{glsxtrregularfont}
4176 and an abbreviation is encapsulated with
4177 \nosecformatdef{glsxtrabbreviationfont}
4178 For example:
4179 \begin{codeenv}
4180 \cmd{documentclass}\marg{article}
4181 \strut
4182 \cmd{usepackage}\marg{xcolor}\comment{provides colour}
4183 \cmd{usepackage}\marg{pifont}\comment{provides \gls{ding}}
4184 \cmd{usepackage}\marg{glossaries-extra}
4185 \strut
4186 \gls{newglossaryentry}\marg{duck}\comment{label}
4187 \marg{
4188 \field{name} = \marg{duck},
4189 \field{description} = \marg{a waterbird with webbed feet}
4190 }
4191 \strut
4192 \gls{newglossaryentry}\marg{fleuron}\comment{label}
4193 \marg{
4194 \field{name} = \marg{fleuron},
4195 \field{symbol} = \marg{\gls{ding}\marg{167}},
4196 \field{category} = \marg{ornament},
4197 \field{description} = \marg{typographic ornament}
4198 }
4199 \strut
4200 \gls{newabbreviation}\marg{tug}\marg{TUG}\marg{\cmd{TeX}\gls{cs.space}Users Group}
4201 \gls{newacronym}\marg{ascii}\marg{ASCII}\marg{American Standard Code for
4202 Information Interchange}
4203 \strut
4204 \cmd{renewcommand}\marg{\gls{glstextformat}}[1]\marg{\cmd{textcolor}\marg{violet}\marg{\gls{param}1}}
4205 \cmd{renewcommand}\marg{\gls{glsxtrregularfont}}[1]\marg{\cmd{underline}\marg{\gls{param}1}}
4206 \cmd{renewcommand}\marg{\gls{glsxtrabbreviationfont}}[1]\marg{\gls{emph}\marg{\gls{param}1}}
4207 \strut
4208 \cmd{begin}\marg{document}
4209 Two \gls{glspl}\marg{duck}, a \gls{gls}\marg{fleuron} (\gls{glssymbol}\marg{fleuron},
4210 \gls{glsentrydesc}\marg{fleuron}), \gls{gls}\marg{tug} and \gls{gls}\marg{ascii}.
4211 \cmd{end}\marg{document}
4212 \end{codeenv}
4213 This now produces:
4214 \begin{result}%
4215 \renewcommand{\glstextformat}[1]{\textcolor{violet}{#1}}%
4216 \renewcommand{\glsxtrregularfont}[1]{\underline{#1}}%
4217 \renewcommand{\glsxtrabbreviationfont}[1]{\emph{#1}}%
4218 Two \glspl{ex1.duck}, a \gls{ex.fleuron} (\glssymbol{ex.fleuron},
4219 \glsentrydesc{ex.fleuron}), \gls{TUG} and \gls{ASCII}.
4220 \end{result}
4221 Note the difference between the abbreviation defined with
4222 \gls{newabbreviation} and the one defined with \gls{newacronym}.
4223 The above example document is using the default styles, which is
4224 \abbrstyle{long-short} for the \code{abbreviation} category
4225 and \abbrstyle{short-nolong} for the \code{acronym} category.
4226 The \abbrstyle{short-nolong} style makes the abbreviation behave
4227 like a \idx{regular} entry and so it's governed by \gls{glsxtrregularfont}
4228 not by \gls{glsxtrabbreviationfont}.
4229
4230 The \gls{glstextformat} command is overridden by the
4231 \catattr{textformat} attribute. The value of this attribute must be
4232 the name (without the leading backslash) of a command that takes a
4233 single argument, which will be used instead of \gls{glstextformat}
4234 for any entry that has this attribute set for its category.
4235 For example:
4236 \begin{codeenv}
4237 \cmd{documentclass}\marg{article}
4238 \strut
4239 \cmd{usepackage}\marg{xcolor}\comment{provides colour}
4240 \cmd{usepackage}\marg{pifont}\comment{provides \gls{ding}}
4241 \cmd{usepackage}\marg{glossaries-extra}
4242 \strut
4243 \cmd{newcommand}\marg{\cmd{ornamentfmt}}[1]\marg{\cmd{textcolor}\marg{cyan}\marg{\gls{param}1}}
4244 \strut
4245 \gls{glssetcategoryattribute}\marg{ornament}\marg{\catattr{textformat}}\marg{ornamentfmt}
4246 \strut
4247 \gls{setabbreviationstyle}\marg{\abbrstyle[noindex=false]{long-short-em}}
4248 \gls{setabbreviationstyle}\oarg{acronym}\marg{\abbrstyle[noindex=false]{short-sc-nolong}}
4249 \strut
4250 \gls{newglossaryentry}\marg{duck}\comment{label}
4251 \marg{
4252 \field{name} = \marg{duck},
4253 \field{description} = \marg{a waterbird with webbed feet}
4254 }
4255 \strut
4256 \gls{newglossaryentry}\marg{fleuron}\comment{label}
4257 \marg{
4258 \field{name} = \marg{fleuron},
4259 \field{symbol} = \marg{\gls{ding}\marg{167}},
4260 \field{category} = \marg{ornament},
4261 \field{description} = \marg{typographic ornament}
4262 }
4263 \strut
4264 \gls{newabbreviation}\marg{tug}\marg{TUG}\marg{\cmd{TeX}\gls{cs.space}Users Group}
4265 \gls{newacronym}\marg{ascii}\comment{label}
4266 \marg{ascii}\comment{short form needs to be in lower case with sc styles}
4267 \marg{American Standard Code for Information Interchange}
4268 \strut
4269 \cmd{renewcommand}\marg{\gls{glstextformat}}[1]\marg{\cmd{textcolor}\marg{violet}\marg{\gls{param}1}}
4270 \cmd{renewcommand}\marg{\gls{glsxtrregularfont}}[1]\marg{\cmd{underline}\marg{\gls{param}1}}
4271 \cmd{renewcommand}\marg{\gls{glsxtrabbreviationfont}}[1]\marg{\gls{textbf}\marg{\gls{param}1}}
4272 \strut
4273 \cmd{begin}\marg{document}
4274 Two \gls{glspl}\marg{duck}, a \gls{gls}\marg{fleuron} (\gls{glssymbol}\marg{fleuron},
4275 \gls{glsentrydesc}\marg{fleuron}), \gls{gls}\marg{tug} and \gls{gls}\marg{ascii}.
4276 \cmd{end}\marg{document}
4277 \end{codeenv}
4278 This produces:
4279 \begin{result}
4280 \renewcommand{\glstextformat}[1]{\textcolor{violet}{#1}}%
4281 \renewcommand{\glsxtrregularfont}[1]{\underline{#1}}%
4282 \renewcommand{\glsxtrabbreviationfont}[1]{\textbf{#1}}%
4283 \newcommand{\ornamentfmt}[1]{\textcolor{cyan}{#1}}%
4284 \glssetcategoryattribute{ornament}{textformat}{ornamentfmt}%
4285 Two \glspl{ex1.duck}, a \gls{ex.fleuron} (\glssymbol{ex.fleuron},
4286 \glsentrydesc{ex.fleuron}), \gls{ex.tug} and \gls{ex.ascii}.
4287 \end{result}
4288 So \code{\gls{gls}\marg{fleuron}} and \code{\gls{glssymbol}\marg{fleuron}} are now
4289 formatted according to the custom command \csfmt{ornamentfmt} (cyan)
4290 not by \gls{glstextformat} (violet), but they are still affected by
4291 \gls{glsxtrregularfont} (underline).
4292
4293 The \code{tug} abbreviation has been assigned the
4294 \abbrstyle{long-short-em} style which encapsulates the short form
4295 with \gls{emph}, but it also obeys \gls{glsxtrabbreviationfont}
4296 (bold) and it's encapsulated by \gls{glstextformat} (violet), so the
4297 full form on \idx{firstuse} is all violet and bold with the short
4298 form in italics.
4299
4300 The \code{ascii} entry (which has the \field{category} set to
4301 \code{acronym}) has been assigned the \abbrstyle{short-sc-nolong}
4302 style, which encapsulates the short form with \gls{textsc} (so the
4303 short form must be converted to \idx{lowercase}) and identifies the
4304 entry as a \idx{regular} term, so it obeys \gls{glsxtrregularfont}
4305 (underline). Again, the \idx{link-text} is encapsulated with
4306 \gls{glstextformat} (violet) so the abbreviation is violet,
4307 underlined and in small-caps.
4308
4309 You can override a specific instance with the \glsopt{textformat}
4310 setting in the first optional argument of commands like \gls{gls}.
4311 For example, if the above is modified to:
4312 \begin{codeenv}
4313 Two \gls{glspl}\marg{duck}, a \gls{gls}\oarg{\glsopt{textformat}=textbf}\marg{fleuron}
4314 (\gls{glssymbol}\marg{fleuron}, \gls{glsentrydesc}\marg{fleuron}), \gls{gls}\marg{tug}
4315 and \gls{gls}\marg{ascii}.
4316 \end{codeenv}
4317 then the result is now:
4318 \begin{result}
4319 \renewcommand{\glstextformat}[1]{\textcolor{violet}{#1}}%
4320 \renewcommand{\glsxtrregularfont}[1]{\underline{#1}}%
4321 \renewcommand{\glsxtrabbreviationfont}[1]{\textbf{#1}}%
4322 \newcommand{\ornamentfmt}[1]{\textcolor{cyan}{#1}}%
4323 \glssetcategoryattribute{ornament}{textformat}{ornamentfmt}%
4324 Two \glspl{ex1.duck}, a \gls[textformat=textbf]{ex.fleuron}
4325 (\glssymbol{ex.fleuron}, \glsentrydesc{ex.fleuron}),
4326 \gls{ex.tug} and \gls{ex.ascii}.
4327 \end{result}
4328 In this case, only that specific instance is changed.
4329
4330 Take care if the formatting command needs to parse its argument as
4331 the argument won't be the actual text but consists of intermediary commands
4332 that determine the required text and any inner formatting, such as
4333 the formatting applied by abbreviation styles. See
4334 \sectionref{sec:expandedfmt} for further details.
4335
4336 \section{Post-Link Category Hooks}
4337 \label{sec:postlinkhooks}
4338
4339 Extra information can be appended after commands such as \gls{gls}
4340 by defining a \pidx{postlinkhook} for the given category. You can
4341 obtain the label of the entry that's just been referenced with:
4342 \nosecformatdef{glslabel}
4343 The \idx{postlinkhook} is a command in the form
4344 \nosecformatdef{glsxtrpostlinkcategory}
4345 where \meta{category} is the category label. This hook is
4346 implemented after any instances of commands such as \gls{gls} or
4347 \gls{glssymbol} (but not after commands like \gls{glsentryname},
4348 \gls{glsentrydesc} or \gls{glsentryname}, which may be used in the
4349 hook).
4350
4351 Consider the following document:
4352 \begin{codeenv}
4353 \cmd{documentclass}\marg{article}
4354 \strut
4355 \cmd{usepackage}\marg{pifont}\comment{provides \gls{ding}}
4356 \cmd{usepackage}\marg{glossaries-extra}
4357 \strut
4358 \gls{newglossaryentry}\marg{fleuron}\comment{label}
4359 \marg{
4360 \field{name} = \marg{fleuron},
4361 \field{symbol} = \marg{\gls{ding}\marg{167}},
4362 \field{description} = \marg{typographic ornament}
4363 }
4364 \strut
4365 \gls{newglossaryentry}\marg{pi}\comment{label}
4366 \marg{
4367 \field{name} = \marg{Archimedes' constant},
4368 \field{symbol} = \marg{\gls{ensuremath}\marg{\cmd{pi}}},
4369 \field{category} = \marg{constant},
4370 \field{description} = \marg{Archimedes' constant}
4371 }
4372 \strut
4373 \comment{post-link hook for 'constant' category:}
4374 \cmd{newcommand}\marg{\csfmt{glsxtrpostlinkconstant}}\marg{\comment{}
4375 \cmd{space} (\gls{glsentrysymbol}\marg{\gls{glslabel}})}
4376 \strut
4377 \cmd{begin}\marg{document}
4378 A \gls{gls}\marg{fleuron} and \gls{gls}\marg{pi}.
4379 \cmd{end}\marg{document}
4380 \end{codeenv}
4381 This produces:
4382 \begin{result}
4383 \newcommand{\glsxtrpostlinkconstant}{\space (\glsentrysymbol{\glslabel})}%
4384 A \gls{ex.fleuron} and \gls{ex.pi}.
4385 \end{result}
4386 The \code{fleuron} entry doesn't have the \field{category} key
4387 explicitly set, so it defaults to \code{general}, but the \code{pi}
4388 entry has the \field{category} set to \code{constant}, so it's
4389 affected by the \idx{postlinkhook} for that category, which in this
4390 case is given by \csfmt{glsxtrpostlinkconstant}. This hook is
4391 defined to use \gls{glsentrysymbol} where the entry label is obtained
4392 from \gls{glslabel}, which is set by \gls{gls} and similar commands.
4393
4394 \begin{important}
4395 If \code{\gls{glssymbol}\marg{\gls{glslabel}}} had been used instead of
4396 \code{\gls{glsentrysymbol}\marg{\gls{glslabel}}} it would've caused infinite
4397 recursion! Don't use commands like \gls{glssymbol}, \gls{glsdesc} or
4398 \gls{gls} in \idxpl{postlinkhook}.
4399 \end{important}
4400
4401 This means that \code{\gls{gls}\marg{pi}} is automatically followed by the
4402 symbol in parentheses, but \code{\gls{gls}\marg{fleuron}} isn't because it's
4403 governed by the \code{general} \idx{postlinkhook} instead. Note that
4404 the above is a simple example to demonstrate one of the uses of the
4405 \field{category} field.
4406
4407 Here's a minor modification that sets the category for the
4408 \code{fleuron} entry to \code{ornament} and creates another hook for
4409 that.
4410 \begin{codeenv}
4411 \cmd{documentclass}\marg{article}
4412 \strut
4413 \cmd{usepackage}\marg{pifont}\comment{provides \gls{ding}}
4414 \cmd{usepackage}\marg{glossaries-extra}
4415 \strut
4416 \gls{newglossaryentry}\marg{fleuron}\comment{label}
4417 \marg{
4418 \field{name} = \marg{fleuron},
4419 \field{symbol} = \marg{\gls{ding}\marg{167}},
4420 \field{category} = \marg{ornament},
4421 \field{description} = \marg{typographic ornament}
4422 }
4423 \strut
4424 \gls{newglossaryentry}\marg{pi}\comment{label}
4425 \marg{
4426 \field{name} = \marg{pi},
4427 \field{symbol} = \marg{\gls{ensuremath}\marg{\cmd{pi}}},
4428 \field{category} = \marg{constant},
4429 \field{description} = \marg{Archimedes' constant}
4430 }
4431 \strut
4432 \comment{post-link hook for 'ornament' category:}
4433 \cmd{newcommand}\marg{\csfmt{glsxtrpostlinkornament}}\marg{\comment{}
4434 \cmd{space} (\gls{glsentrydesc}\marg{\gls{glslabel}})}
4435 \strut
4436 \comment{post-link hook for 'constant' category:}
4437 \cmd{newcommand}\marg{\csfmt{glsxtrpostlinkconstant}}{\comment{}
4438 \cmd{space} (\gls{glsentrysymbol}\marg{\gls{glslabel}})}
4439 \strut
4440 \cmd{begin}\marg{document}
4441 A \gls{gls}\marg{fleuron} and \gls{gls}\marg{pi}. Another \gls{gls}\marg{fleuron} and
4442 \gls{gls}\marg{pi}. Symbols: \gls{glssymbol}\marg{fleuron} and \gls{glssymbol}\marg{pi}.
4443 \cmd{end}\marg{document}
4444 \end{codeenv}
4445 This produces:
4446 \begin{result}
4447 \newcommand{\glsxtrpostlinkornament}{\space (\glsentrydesc{\glslabel})}%
4448 \newcommand{\glsxtrpostlinkconstant}{\space (\glsentrysymbol{\glslabel})}%
4449 A \gls{ex.fleuron} and \gls{ex.pi}. Another \gls{ex.fleuron} and
4450 \gls{ex.pi}. Symbols: \glssymbol{ex.fleuron} and \glssymbol{ex.pi}.\incorrect
4451 \end{result}
4452 The \idx{postlinkhook} is repeated after every instance of \gls{gls}
4453 or \gls{glssymbol} etc. In the case of the \code{ornament} category,
4454 the description is appended in parentheses and in the case of the
4455 \code{constant} category the symbol is appended. This results in
4456 redundant repetition, especially with \verb|\glssymbol{pi}| which
4457 displays the symbol followed by the symbol in parentheses.
4458
4459 It's more likely that the information only needs to be appended
4460 after the \idx{firstuse}. You can determine if the
4461 \idx{postlinkhook} follows the \idx{firstuse} of the entry using:
4462 \nosecformatdef{glsxtrifwasfirstuse}
4463 For example:
4464 \begin{codeenv}
4465 \cmd{newcommand}\marg{\csfmt{glsxtrpostlinkconstant}}\marg{\comment{}
4466 \gls{glsxtrifwasfirstuse}\marg{\cmd{space} (\gls{glsentrysymbol}\marg{\gls{glslabel}})}\marg{}\comment{}
4467 }
4468 \end{codeenv}
4469 Commands that don't check or modify the \idx{firstuseflag}, such as
4470 \gls{glssymbol}, always set \gls{glsxtrifwasfirstuse} so that it
4471 expands to \meta{false}. This means that even if
4472 \code{\gls{glssymbol}\marg{pi}}
4473 is placed before the first instance of \code{\gls{gls}\marg{pi}} it still
4474 won't be treated as the first use of that entry.
4475
4476 For convenience, there's a shortcut command:
4477 \nosecformatdef{glsxtrpostlinkAddSymbolOnFirstUse}
4478 So an alternative definition is:
4479 \begin{codeenv}
4480 \cmd{newcommand}\marg{\csfmt{glsxtrpostlinkconstant}}\marg{\comment{}
4481 \gls{glsxtrpostlinkAddSymbolOnFirstUse}
4482 }
4483 \end{codeenv}
4484 This does nothing if the \field{symbol} field hasn't been set.
4485
4486 Similarly, there's a shortcut command for the description:
4487 \nosecformatdef{glsxtrpostlinkAddDescOnFirstUse}
4488 Version 1.31+ provides a combination:
4489 \nosecformatdef{glsxtrpostlinkAddSymbolDescOnFirstUse}
4490 If the \field{symbol} field is set, this displays the symbol
4491 followed by a comma and space. The description is always displayed
4492 at the end of the parenthetical material.
4493
4494 Also from \sty{glossaries-extra} v1.31, there's a shortcut
4495 command that you can use to define the \idx{postlinkhook}:
4496 \nosecformatdef{glsdefpostlink}
4497 This is just a shortcut for:
4498 \begin{codeenv}
4499 \csfmt{csdef}\marg{glsxtrpostlink\meta{category}}\margm{definition}
4500 \end{codeenv}
4501 So the above document can be changed to:
4502 \begin{codeenv}
4503 \cmd{documentclass}\marg{article}
4504 \strut
4505 \cmd{usepackage}\marg{pifont}\comment{provides \gls{ding}}
4506 \cmd{usepackage}\marg{glossaries-extra}
4507 \strut
4508 \gls{newglossaryentry}\marg{fleuron}\comment{label}
4509 \marg{
4510 \field{name} = \marg{fleuron},
4511 \field{symbol} = \marg{\gls{ding}\marg{167}},
4512 \field{category} = \marg{ornament},
4513 \field{description} = \marg{typographic ornament}
4514 }
4515 \strut
4516 \gls{newglossaryentry}\marg{pi}\comment{label}
4517 \marg{
4518 \field{name} = \marg{pi},
4519 \field{symbol} = \marg{\gls{ensuremath}\marg{\cmd{pi}}},
4520 \field{category} = \marg{constant},
4521 \field{description} = \marg{Archimedes' constant}
4522 }
4523 \strut
4524 \comment{post-link hook for 'ornament' category:}
4525 \gls{glsdefpostlink}\marg{ornament}\marg{\comment{}
4526 \gls{glsxtrpostlinkAddSymbolDescOnFirstUse}
4527 }
4528 \strut
4529 \comment{post-link hook for 'constant' category:}
4530 \gls{glsdefpostlink}\marg{constant}\marg{\comment{}
4531 \gls{glsxtrpostlinkAddSymbolOnFirstUse}
4532 }
4533 \strut
4534 \cmd{begin}\marg{document}
4535 Symbols: \gls{glssymbol}\marg{fleuron} and \gls{glssymbol}\marg{pi}.
4536 A \gls{gls}\marg{fleuron} and \gls{gls}\marg{pi}. Another \gls{gls}\marg{fleuron} and
4537 \gls{gls}\marg{pi}.
4538 \cmd{end}\marg{document}
4539 \end{codeenv}
4540 The result is now:
4541 \begin{result}%
4542 \glsdefpostlink{ornament}{\glsxtrpostlinkAddSymbolDescOnFirstUse}%
4543 \glsdefpostlink{constant}{\glsxtrpostlinkAddSymbolOnFirstUse}%
4544 Symbols: \glssymbol{ex.fleuron} and \glssymbol{ex.pi}.
4545 A \gls{ex.fleuron} and \gls{ex.pi}. Another \gls{ex.fleuron} and
4546 \gls{ex.pi}.
4547 \end{result}
4548
4549 \section{Glossary Name and Description Formatting}
4550 \label{sec:glossname}
4551
4552 When an entry's definition is displayed within
4553 \gls{printunsrtglossary} or \gls{glsxtrglossentry} (see
4554 \sectionref{sec:displaygloss}), the value of the \field{name} field
4555 is encapsulated by
4556 \nosecformatdef{glsnamefont}
4557 This may be overridden with the \catattr{glossnamefont} attribute
4558 whose value must be the name (without the leading backslash) of a
4559 control sequence that takes a single argument. If set, this control
4560 sequence is used instead of \gls{glsnamefont}.
4561
4562 By default \gls{glsnamefont} simply does its argument, but the
4563 glossary style may apply additional formatting. For example, the
4564 \glostyle{list} styles place the name in the optional argument of
4565 \csfmt{item} within the \envfmt{description} environment. With the
4566 standard document classes, this renders the name in bold, but other
4567 classes may apply different formatting.
4568
4569 The \glostyle{tree} styles defined by the \sty{glossary-tree} style
4570 encapsulate the name within:
4571 \nosecformatdef{glstreenamefmt}
4572 which does \code{\gls{textbf}\margm{text}} by default. So, for
4573 example, if \gls{glsnamefont} is redefined to use \gls{textit} and
4574 the \glostyle{tree} style is used, then the name will appear in
4575 italic bold. The letter group headings are encapsulated within:
4576 \nosecformatdef{glstreegroupheaderfmt}
4577 which defaults to \code{\gls{glstreenamefmt}\margm{text}}, so if you
4578 need to redefine \gls{glstreenamefmt} you may also need to redefine
4579 \gls{glstreegroupheaderfmt} if the headers should have different formatting.
4580 The \sty{glossaries-extra-stylemods} package (as from v1.31) now
4581 redefine both \gls{glstreenamefmt} and \gls{glstreegroupheaderfmt}
4582 to use:
4583 \nosecformatdef{glstreedefaultnamefmt}
4584 which does \code{\gls{textbf}\margm{text}} by default. This means
4585 that if you want to change both the header and name to a different
4586 font, you can just redefine \gls{glstreedefaultnamefmt}, and if you
4587 want to change only the font used for the name, then now you only
4588 need to redefine \gls{glstreenamefmt}, without also having to
4589 redefine \gls{glstreegroupheaderfmt}.
4590
4591 Case-changing can be automatically applied to the name with the
4592 \catattr{glossname} attribute, which may take one of the values:
4593 \code{firstuc} (convert the first letter to \idx{uppercase}), \code{title}
4594 (convert to title case) or \code{uc} (convert to all capitals).
4595 Alternatively, if you're using \bibgls, you can use the
4596 \csopt{name-case-change} resource option.
4597
4598 The description is similarly governed by the
4599 \catattr{glossdescfont}, which again should have the name (without
4600 the leading backslash) of a control sequence that takes a single
4601 argument. There's no equivalent of \gls{glsnamefont} for the
4602 description but the glossary or abbreviation style may apply
4603 particular formatting, which will be in addition to the formatting
4604 command given by \catattr{glossdescfont} (if set).
4605
4606 Case-changing is also available for descriptions with the
4607 \catattr{glossdesc} attribute, but this only has two allowed values:
4608 \code{firstuc} (convert the first letter to \idx{uppercase}) and
4609 \code{title} (convert to title case).
4610 Alternatively, if you're using \bibgls, you can use the
4611 \csopt{description-case-change} resource option.
4612
4613 \section{Post-Name and Post-Description Hooks}
4614 \label{sec:postfieldhooks}
4615
4616 Information can be appended to the \field{name} in the glossary for
4617 a particular category using the \pidx{postnamehook}, which is given
4618 by the command:
4619 \nosecformatdef{glsxtrpostnamecategory}
4620 The current entry's label can be referenced with:
4621 \nosecformatdef{glscurrententrylabel}
4622 For example, if the preferred glossary style doesn't include the
4623 \field{symbol} field, but you want the symbol displayed after the
4624 name for entries with the \field{category} field set to \code{symbol}:
4625 \begin{codeenv}
4626 \cmd{newcommand}\marg{\cmd{glsxtrpostnamesymbol}}\marg{\cmd{space}
4627 (\gls{glsentrysymbol}\marg{\gls{glscurrententrylabel}})}
4628 \end{codeenv}
4629 There's a convenient shortcut:
4630 \nosecformatdef{glsdefpostname}
4631 which defines \gls{glsxtrpostnamecategory} to \meta{definition}
4632 (using \gls{csdef}). There's also a more general purpose \idx{postnamehook}
4633 used regardless of the category:
4634 \nosecformatdef{glsextrapostnamehook}
4635
4636 The \idx{postnamehook} is placed inside the formatting command used
4637 for the \field{name} field in the glossary. It's only present in the
4638 glossary (see \sectionref{sec:printgloss}) or stand-alone entries
4639 (see \sectionref{sec:standalone}).
4640
4641 There is a similar \pidx{postdescriptionhook}. For a particular category,
4642 the hook is given by:
4643 \nosecformatdef{glsxtrpostdesccategory}
4644 There are some categories that have empty hooks already defined,
4645 such as
4646 \nosecformatdef{glsxtrpostdescgeneral}
4647 These will need \csfmt{renewcommand} rather than \csfmt{newcommand}.
4648 Again there's a shortcut command provided:
4649 \nosecformatdef{glsdefpostdesc}
4650 which just uses \gls{csdef}, so there's no check if the command is
4651 already defined.
4652 As with the \idx{postnamehook}, the entry's label can be accessed
4653 with \gls{glscurrententrylabel}.
4654
4655 Punctuation (such as a \idx{full-stop} or comma) can automatically be
4656 appended to the description in the
4657 glossary with the \styopt{postpunc} option. (Note that the
4658 unstarred form of \gls{longnewglossaryentry} interferes with this
4659 option. Use the starred form \gls{longnewglossaryentry*} instead.)
4660 The post-description punctuation (if set) is placed after the
4661 \glslink{postdescriptionhook}{post-description category hook} (if
4662 provided). Both the post-description category hook and the
4663 post-description punctuation are implemented by
4664 \nosecformatdef{glspostdescription}
4665 The \sty{glossaries-extra-stylemods}
4666 package (which can be loaded with the \styopt{stylemods} option)
4667 patches the predefined styles provided with the base
4668 \sty{glossaries} package to ensure that the standard styles all use
4669 \gls{glspostdescription}.
4670
4671
4672 \chapter{Problematic Areas}
4673 \label{sec:problems}
4674
4675 There are some places where the use of commands like \gls{gls} can
4676 cause problems. Common issues are listed below, with workarounds provided.
4677
4678 \section{Headings and Captions}
4679 \label{sec:headings}
4680
4681 The arguments of sectioning commands (such as \gls{chapter} or
4682 \gls{section}) and of captions (\gls{caption}) are
4683 \pidxpl{moving-argument}. The text is not only displayed at the
4684 point in the document where the command occurs, but may also be
4685 copied to the \gls{toc} or list of figures etc.
4686 Additionally, depending on the page style, the section argument may
4687 also be reproduced in the page header. This repeated use of the same
4688 material can cause complications, in particular it can prematurely
4689 triggering the \idx{firstuseflag} switch and cause unwanted
4690 indexing.
4691
4692 If the content appears in the page header and the page
4693 styles converts headers to upper case, this can also cause a
4694 problem. However, if you make sure you have \sty{glossaries} v4.50+,
4695 \sty{glossaries-extra} v1.49+ and \sty{mfirstuc} v2.08+ with a
4696 recent \TeX\ distribution, most of the case-changing problems should
4697 now no longer occur.
4698
4699 Here's an example that doesn't cause an error (because there's not
4700 enough text to trigger a page break) but does cause unexpected output:
4701 \begin{codeenv}
4702 \cmd{documentclass}\marg{book}
4703 \strut
4704 \cmd{usepackage}\marg{glossaries-extra}
4705 \strut
4706 \gls{setabbreviationstyle}\marg{\abbrstyle{long-short-sc}}
4707 \gls{newabbreviation}\marg{html}\marg{html}\marg{hypertext markup language}
4708 \strut
4709 \cmd{begin}\marg{document}
4710 \gls{tableofcontents}
4711 \gls{chapter}\marg{A chapter about \gls{gls}\marg{html}}
4712 Reference \gls{gls}\marg{html}.
4713 \cmd{end}\marg{document}
4714 \end{codeenv}
4715 On the first \LaTeX\ run, the \gls{toc} is empty as the
4716 associated \ext{toc} file didn't exist at the start. The chapter title
4717 appears as \qt{A chapter about hypertext markup language
4718 (\textsc{html})}, which shows the \idx{firstuse} of
4719 \code{\gls{gls}\marg{html}}. The \ext{toc} file (which was created
4720 but not read by \gls{tableofcontents}) now contains:
4721 \begin{codeenv}
4722 \cmd{contentsline} \marg{chapter}\marg{\cmd{numberline} \marg{1}A chapter about \gls{gls} \marg{html}}\marg{3}
4723 \end{codeenv}
4724 This means that on the next \LaTeX\ run, the \gls{toc} now
4725 includes \code{\gls{gls}\marg{html}}. Since the \gls{toc}
4726 occurs at the start of the document, this is now the \idx{firstuse}
4727 of \code{html}, so the full form is shown in the \gls{toc},
4728 but the chapter title is now \qt{A chapter about \textsc{html}}, which shows
4729 the subsequent use.
4730
4731 The \sty{glossaries-extra} package provides some commands that are
4732 designed for use in section or caption titles. These include:
4733 \nosecformatdef{glsfmtshort}
4734 which shows the short form of an abbreviation,
4735 \nosecformatdef{glsfmtlong}
4736 which shows the long form of an abbreviation,
4737 \nosecformatdef{glsfmtfull}
4738 which shows the full form of an abbreviation,
4739 \nosecformatdef{glsfmtname}
4740 which shows the entry's name,
4741 \nosecformatdef{glsfmtfirst}
4742 which shows the entry's \field{first} field, and
4743 \nosecformatdef{glsfmttext}
4744 which shows the entry's \field{text} field.
4745
4746 Here's a modified version of the above:
4747 \begin{codeenv}
4748 \cmd{documentclass}\marg{book}
4749 \strut
4750 \cmd{usepackage}\marg{lipsum}\comment{provides \cmd{lipsum}}
4751 \cmd{usepackage}\marg{glossaries-extra}
4752 \strut
4753 \gls{setabbreviationstyle}\marg{\abbrstyle{long-short-sc}}
4754 \gls{newabbreviation}\marg{html}\marg{html}\marg{hypertext markup language}
4755 \strut
4756 \cmd{begin}\marg{document}
4757 \gls{tableofcontents}
4758 \gls{chapter}\marg{A chapter about \gls{glsfmtlong}\marg{html}}
4759 Reference \gls{gls}\marg{html}.
4760 \cmd{lipsum} \comment{dummy text}
4761 \cmd{end}\marg{document}
4762 \end{codeenv}
4763 This now shows the long form in the \gls{toc} and the
4764 chapter title. Since \gls{glsfmtlong} doesn't affect the
4765 \idx{firstuseflag}, the reference after the chapter title now shows
4766 the \idx{firstuse} full form. There's no longer an error with the
4767 page header on the second page, but it's not quite right as the
4768 case-change hasn't been applied, so the page heading appears as:
4769 \begin{result}
4770 4\hfill \emph{CHAPTER 1. A CHAPTER ABOUT hypertext markup language}
4771 \end{result}
4772 This shouldn't occur any more, but if it does, it can be corrected by
4773 setting the \catattr{headuc} attribute to \code{true}:
4774 \begin{codeenv}
4775 \gls{glssetcategoryattribute}\marg{abbreviation}\marg{headuc}\marg{true}
4776 \end{codeenv}
4777 This now makes the page header too long, but remember that you can
4778 use the optional argument of sectioning commands to provide a
4779 shorter form for both the page heading and \gls{toc}:
4780 \begin{codeenv}
4781 \gls{chapter}\oarg{A chapter about \gls{glsfmtshort}\marg{html}}\marg{A chapter about
4782 \gls{glsfmtlong}\marg{html}}
4783 \end{codeenv}
4784 One final problem remains and it's due to the
4785 \abbrstyle{long-short-sc} abbreviation style which uses \gls{textsc}
4786 to display the short form in small capitals. The combination of
4787 italic and small capitals isn't supported with the default fonts and
4788 results in a font substitution. There's a similar problem in the
4789 \gls{toc} which displays the chapter title in bold. There's
4790 a warning at the end of the transcript:
4791 \begin{verbatim}
4792 Some font shapes were not available, defaults substituted.
4793 \end{verbatim}
4794 The conflict between bold and small capitals can be solved by
4795 switching to the T1 font encoding:
4796 \begin{codeenv}
4797 \cmd{usepackage}[T1]\marg{\sty[noindex=false]{fontenc}}
4798 \end{codeenv}
4799 The conflict between italic and small capitals can be solved with
4800 the \sty{slantsc} package. Another possibility is to redefine:
4801 \nosecformatdef{glsabbrvscfont}
4802 which is used by the \qt{sc} abbreviation styles:
4803 \begin{codeenv}
4804 \cmd{renewcommand}\marg{\gls{glsabbrvscfont}}[1]\marg{\comment{}
4805 \gls{glsxtrifinmark}\marg{\gls{glsuppercase}\marg{\gls{param}1}}\marg{\gls{textsc}\marg{\gls{param}1}}\comment{}
4806 }
4807 \end{codeenv}
4808 This uses:
4809 \nosecformatdef{glsxtrifinmark}
4810 which expands to \meta{true} in headings and the \gls{toc},
4811 otherwise it expands to \meta{false}. This use of
4812 \gls{glsuppercase} replaces the need for the \catattr{headuc}
4813 attribute. Both \catattr{headuc} and the above redefinition of
4814 \gls{glsabbrvscfont} will cause the abbreviation to appear in
4815 \idx{uppercase} in the \gls{toc}. If you don't want this,
4816 you can defer making these modifications until after the
4817 \gls{toc}. Alternatively, use:
4818 \nosecformatdef{glsxtrRevertTocMarks}
4819 which makes \gls{glsxtrifinmark} expand to \meta{false} in the
4820 \gls{toc}. For example:
4821 \begin{codeenv}
4822 \cmd{documentclass}\marg{book}
4823 \strut
4824 \cmd{usepackage}[T1]\marg{fontenc}
4825 \cmd{usepackage}\marg{lipsum}
4826 \cmd{usepackage}\marg{glossaries-extra}
4827 \strut
4828 \cmd{renewcommand}\marg{\gls{glsabbrvscfont}}[1]\marg{\comment{}
4829 \gls{glsxtrifinmark}\marg{\gls{glsuppercase}\marg{\gls{param}1}}\marg{\gls{textsc}{\gls{param}1}}\comment{}
4830 }
4831 \strut
4832 \gls{setabbreviationstyle}\marg{\abbrstyle{long-short-sc}}
4833 \gls{newabbreviation}\marg{html}\marg{html}\marg{hypertext markup language}
4834 \strut
4835 \cmd{begin}\marg{document}
4836 \gls{tableofcontents}
4837 \gls{chapter}\oarg{A chapter about \gls{glsfmtshort}\marg{html}}\marg{A chapter
4838 about \gls{glsfmtlong}\marg{html}}
4839 Reference \gls{gls}\marg{html}.
4840 \cmd{lipsum} \comment{dummy text}
4841 \cmd{end}\marg{document}
4842 \end{codeenv}
4843
4844
4845 \section{Nesting}
4846 \label{sec:nested}
4847
4848 Nesting refers to commands like \gls{gls} and \gls{glssymbol} being
4849 used in the \idx{link-text} of similar commands. This occurs if
4850 these commands are used in fields that form part of the
4851 \idx{link-text} or if they occur in the final \meta{insert}
4852 optional argument (which is included in the \idx{link-text}) or in the
4853 \idx{postlinkhook} (which isn't included in the \idx{link-text} but
4854 is still problematic).
4855
4856 The most serious problem is when the \idx{postlinkhook} includes one
4857 of these commands that references an entry with the same category
4858 (and therefore the same \idx{postlinkhook} code) as
4859 you can end up with an infinite loop. For example:
4860 \begin{codeenv}
4861 \gls{glsdefpostlink}\marg{symbol}\marg{ (\gls{glssymbol}\marg{\gls{glslabel}})}\comment{infinite loop!}\incorrect
4862 \end{codeenv}
4863 Instead, use \gls{glsentrysymbol}:
4864 \begin{codeenv}
4865 \gls{glsdefpostlink}\marg{symbol}\marg{ (\gls{glsentrysymbol}\marg{\gls{glslabel}})}\correct
4866 \end{codeenv}
4867 Better still, use commands like
4868 \gls{glsxtrpostlinkAddSymbolOnFirstUse} (see \sectionref{sec:postlinkhooks}).
4869
4870 \section{Shortcut Commands or Active Characters}
4871 \label{sec:activeshortcuts}
4872
4873 Some packages, such as \sty{babel}, provide shortcut commands or
4874 active characters that can be enabled through a particular setting.
4875 It's best not to use these in entry definitions.
4876 Instead use the full command name. The main problem comes when the
4877 shortcuts aren't enabled until the start of the \envfmt{document}
4878 environment. For example, the \code{ngerman} language setting in
4879 \sty{babel} makes the double quote character (\idx{doublequoteactivechar})
4880 active and it becomes a shortcut for \gls{umlaut} (the umlaut accent
4881 command):
4882 \begin{codeenv}
4883 \cmd{documentclass}\marg{article}
4884 \strut
4885 \cmd{usepackage}[ngerman]\marg{babel}
4886 \cmd{usepackage}\marg{glossaries-extra}
4887 \strut
4888 \gls{newabbreviation}\marg{rna}\marg{RNA}\marg{ribonukleins"aure}\incorrect
4889 \strut
4890 \cmd{begin}\marg{document}
4891 Explicit use: ribonukleins"aure.
4892 Reference: \gls{gls}\marg{rna}.
4893 \cmd{end}\marg{document}
4894 \end{codeenv}
4895 This produces:
4896 \begin{result}
4897 Explicit use: ribonukleins\"aure. Reference: ribonukleins"aure (RNA).
4898 \end{result}
4899 This is because the double quote character still had its normal
4900 meaning when the \code{rna} entry was defined, so the
4901 \idx{doublequotechar} in the long form is an actual double quote
4902 character not a shortcut for \gls{umlaut}.
4903
4904 Another problem occurs when you have a large file containing entry
4905 definitions that will be shared by multiple documents. If shortcut
4906 commands are used in the entry definitions then every document that
4907 uses those entries must ensure that the appropriate shortcut
4908 commands are set up before use. Also, when using \bibgls, it
4909 recognises commands like \gls{umlaut} but not \sty{babel}
4910 shorthands, so the sorting will be adversely affected if you simply
4911 use \idx{doublequoteactivechar} instead of \gls{umlaut}.
4912
4913 For large files that are written once (with minor subsequent edits),
4914 but reused many times for multiple documents, it's better to use the
4915 actual command (that simply requires the appropriate package to be
4916 loaded, if applicable, without specific options to enable it).
4917
4918
4919 \section{Formatting Commands that Need Direct Access to the Text}
4920 \label{sec:expandedfmt}
4921
4922 If you want to redefine any of the formatting commands
4923 \gls{glstextformat}, \gls{glsxtrregularfont} or
4924 \gls{glsxtrabbreviationfont}, remember that their argument isn't the
4925 actual text but consists of intermediary commands
4926 that determine the required text and any inner formatting, such as
4927 the formatting applied by abbreviation styles.
4928
4929 With the \glsopt{hyperoutside} setting on, the outermost level
4930 will be the command to apply the hyperlink with \gls{glstextformat}
4931 (or the equivalent provided by \catattr{textformat})
4932 inside the hyperlink text. (If hyperlinks aren't enabled the outer
4933 command simply does the hyperlink text.)
4934
4935 With \glsopt[false]{hyperoutside}, the outermost level will be
4936 \gls{glstextformat} (or equivalent) with the command that applies
4937 the hyperlink inside the formatting argument.
4938
4939 The next level down sets up the abbreviation styles for the given
4940 category (if appropriate). If the entry isn't an abbreviation or is
4941 an abbreviation classified as regular then
4942 \gls{glsxtrregularfont} is applied to the command that governs how
4943 regular entries are formatted. Otherwise \gls{glsxtrabbreviationfont}
4944 is applied to the command that governs how abbreviations are
4945 formatted.
4946
4947 Finally, there are tests applied to determine if this is the
4948 \idx{firstuse}, if the plural is required, if any case-changing is
4949 required, if the final optional argument has been given, or if a
4950 command such as \gls{glssymbol} has been used. These tests
4951 determine which field to obtain the \idx{link-text} from. With
4952 abbreviations, any formatting required by the abbreviation style is
4953 finally performed.
4954
4955 This makes it very difficult to apply a formatting command that
4956 needs direct access to the actual text that needs to be displayed.
4957 One possible method is to use:
4958 \nosecformatdef{GlsXtrExpandedFmt}
4959 which first (protected) fully expands \meta{text} and then performs
4960 \meta{cs}\margm{expanded text} where \meta{cs} is a control
4961 sequence. For example, the \isty{soul} package provides the command
4962 \gls{ul} to underline text, but it needs to be able to parse its
4963 argument to work. If I simply try to change the standard
4964 \gls{underline} to \gls{ul} in the earlier example from
4965 \sectionref{sec:glsformats}:
4966 \begin{codeenv}
4967 \cmd{renewcommand}\marg{\gls{glsxtrregularfont}}[1]\marg{\cmd{ul}\marg{\gls{param}1}}
4968 \end{codeenv}
4969 then this causes the error:
4970 \begin{verbatim}
4971 ! Package soul Error: Reconstruction failed.
4972 \end{verbatim}
4973 Instead I need:
4974 \begin{codeenv}
4975 \cmd{renewcommand}\marg{\gls{glsxtrregularfont}}[1]\marg{\gls{GlsXtrExpandedFmt}\cmd{ul}\marg{\gls{param}1}}
4976 \end{codeenv}
4977 \emph{and also} \gls{ding} now needs protection:
4978 \begin{codeenv}
4979 \gls{newglossaryentry}\marg{fleuron}\comment{label}
4980 \marg{
4981 \field{name} = \marg{fleuron},
4982 \field{symbol} = \marg{\gls{protect}\gls{ding}\marg{167}},
4983 \field{category} = \marg{ornament},
4984 \field{description} = \marg{typographic ornament}
4985 }
4986 \end{codeenv}
4987
4988 \section{Buffering Changes to the First Use Flag}
4989 \label{sec:buffering}
4990
4991 The \sty{soul} commands, described above, also have problems if the
4992 \idx{firstuseflag} is switched off within the argument. This can be
4993 demonstrated with the following:
4994 \begin{codeenv}
4995 \cmd{documentclass}\marg{article}
4996 \cmd{usepackage}\marg{soul}
4997 \cmd{usepackage}\marg{glossaries-extra}
4998 \gls{newabbreviation}\marg{ssl}\marg{SSL}\marg{Secure Sockets Layer}
4999 \cmd{begin}\marg{document}
5000 \cmd{ul}\marg{Some text about \gls{gls}\marg{ssl}.}
5001 \cmd{end}\marg{document}
5002 \end{codeenv}
5003 This produces the somewhat confusing error message:
5004 \begin{verbatim}
5005 Glossary entry `{ssl}' has not been defined.
5006 \end{verbatim}
5007 Enclosing \code{\gls{gls}\marg{ssl}} inside the argument of \csfmt{mbox}
5008 changes the error message to:
5009 \begin{verbatim}
5010 ! Package soul Error: Reconstruction failed.
5011 \end{verbatim}
5012 The only way to avoid an error is to switch on the \gls{glsunset}
5013 buffering, which modifies the internal command that normally changes
5014 the \idx{firstuseflag}. Instead, the entry label is simply stored in
5015 an internal list. The buffering is switched on with:
5016 \nosecformatdef{GlsXtrStartUnsetBuffering}
5017 The unstarred form of this command may result in multiple
5018 occurrences of an entry in the buffer's internal list. The starred form,
5019 which only adds an entry's label to the list if not already present,
5020 is better if the list needs to contain unique items.
5021
5022 The current buffer can be iterated over using;
5023 \nosecformatdef{GlsXtrForUnsetBufferedList}
5024 where \meta{cs} is a command that takes a single argument (the
5025 entry's label). Finally, entries in the buffer can be unset and the
5026 buffer cleared with:
5027 \nosecformatdef{GlsXtrStopUnsetBuffering}
5028
5029 The above example will work if it's changed to:
5030 \begin{codeenv}
5031 \cmd{documentclass}\marg{article}
5032 \cmd{usepackage}\marg{soul}
5033 \cmd{usepackage}\marg{glossaries-extra}
5034 \gls{newabbreviation}\marg{ssl}\marg{SSL}\marg{Secure Sockets Layer}
5035 \cmd{begin}\marg{document}
5036 \gls{GlsXtrStartUnsetBuffering}
5037 \cmd{ul}\marg{Some text about \cmd{mbox}\marg{\gls{gls}\marg{ssl}}.}
5038 \gls{GlsXtrStopUnsetBuffering}
5039 \cmd{end}\marg{document}
5040 \end{codeenv}
5041 Note the need for \csfmt{mbox}, which can cause a problem with
5042 line-breaking. Another problem is that if the entry is referenced
5043 multiple times within the same buffer, each use of \gls{gls} (or its
5044 \idxpl{variant}) will be treated as the \idx{firstuse}.
5045
5046 Another workaround is to use \glsopt{textformat} with a command that
5047 uses \gls{GlsXtrExpandedFmt} (see \sectionref{sec:expandedfmt}). For
5048 example:
5049 \begin{codeenv}
5050 \cmd{documentclass}\marg{article}
5051 \cmd{usepackage}\marg{soul}
5052 \cmd{usepackage}\marg{glossaries-extra}
5053 \strut
5054 \cmd{newrobustcmd}\marg{\cmd{gul}}[1]\marg{\comment{}
5055 \marg{\comment{}
5056 \cmd{def}\gls{glsxtrabbreviationfont}\gls{param}\gls{param}1\marg{\gls{GlsXtrExpandedFmt}\marg{\cmd{ul}}\marg{\gls{param}\gls{param}1}}\comment{}
5057 \cmd{def}\gls{glsxtrregularfont}\gls{param}\gls{param}1\marg{\gls{GlsXtrExpandedFmt}\marg{\cmd{ul}}\marg{\gls{param}\gls{param}1}}\comment{}
5058 \gls{param}1\comment{}
5059 }%
5060 }
5061 \strut
5062 \gls{newabbreviation}\marg{ssl}\marg{SSL}\marg{Secure Sockets Layer}
5063 \cmd{begin}\marg{document}
5064 \cmd{ul}\marg{Some text about }\gls{gls}\oarg{\glsopt{textformat}=gul}\marg{ssl}.
5065 \cmd{end}\marg{document}
5066 \end{codeenv}
5067
5068 \chapter{Incorporating \bibgls}
5069 \label{sec:bib2gls}
5070
5071 So far, the examples haven't actually used \bibgls, so what does it
5072 actually do? Recall the example document in \sectionref{sec:group},
5073 reproduced below:
5074 \begin{codeenv}
5075 \cmd{documentclass}\marg{scrartcl}
5076 \cmd{usepackage}\marg{mhchem}
5077 \cmd{usepackage}[\styopt[dot]{postpunc},\comment{full stop after description}
5078 \styopt{nostyles},\comment{don't load default style packages}
5079 \styopt[tree]{stylemods}\comment{load glossary-tree.sty and patch styles}
5080 ]\marg{glossaries-extra}
5081 \strut
5082 \gls{glsaddstoragekey}\marg{group}\marg{}\marg{\cmd{grouplabel}}
5083 \gls{glsxtrsetgrouptitle}\marg{greek}\marg{Greek Symbols}
5084 \strut
5085 \gls{newglossaryentry}\marg{area}
5086 \marg{
5087 \field{name} = \marg{\gls{ensuremath}\marg{A}},
5088 \field{description} = \marg{area},
5089 \field{group} = \marg{A}
5090 }
5091 \strut
5092 \gls{newglossaryentry}\marg{amethyst}
5093 \marg{
5094 \field{name} = \marg{amethyst},
5095 \field{description} = \marg{a purple type of quartz},
5096 \field{symbol} = \marg{\gls{ce}\marg{SiO2}},
5097 \field{group} = \marg{A}
5098 }
5099 \strut
5100 \gls{newglossaryentry}\marg{circumference}
5101 \marg{
5102 \field{name} = \marg{\gls{ensuremath}\marg{C}},
5103 \field{description} = \marg{circumference},
5104 \field{group} = \marg{C}
5105 }
5106 \strut
5107 \gls{newglossaryentry}\marg{duck}
5108 \marg{
5109 \field{name} = \marg{duck},
5110 \field{description} = \marg{a waterbird with webbed feet},
5111 \field{group} = \marg{D}
5112 }
5113 \strut
5114 \gls{newglossaryentry}\marg{goose}
5115 \marg{
5116 \field{name} = \marg{goose},
5117 \field{description} = \marg{a large waterbird with a long neck, short legs,
5118 webbed feet and a short broad bill},
5119 \field{group} = \marg{G}
5120 }
5121 \strut
5122 \gls{newglossaryentry}\marg{radius}
5123 \marg{
5124 \field{name} = \marg{\gls{ensuremath}\marg{r}},
5125 \field{description} = \marg{radius},
5126 \field{group} = \marg{R}
5127 }
5128 \strut
5129 \gls{newglossaryentry}\marg{pi}
5130 \marg{
5131 \field{name} = \marg{\gls{ensuremath}\marg{\cmd{pi}}},
5132 \field{description} = \marg{Archimedes' constant},
5133 \field{group} = \marg{greek}
5134 }
5135 \strut
5136 \cmd{begin}\marg{document}
5137 \gls{printunsrtglossary}\oarg{\printglossopt[indexgroup]{style}}
5138 \cmd{end}\marg{document}
5139 \end{codeenv}
5140 The document preamble is quite cluttered. It could be tidied up by
5141 moving all the \gls{newglossaryentry} code into a separate file
5142 called, say, \filefmt{entries.tex}. The main document code can now
5143 be simplified to:
5144 \begin{codeenv}
5145 \cmd{documentclass}\marg{scrartcl}
5146 \cmd{usepackage}\marg{mhchem}
5147 \cmd{usepackage}[
5148 \styopt{record},\comment{create \field{group} field and other stuff}
5149 \styopt[dot]{postpunc},\comment{full stop after description}
5150 \styopt{nostyles},\comment{don't load default style packages}
5151 \styopt[tree]{stylemods}\comment{load glossary-tree.sty and patch styles}
5152 ]\marg{glossaries-extra}
5153 \strut
5154 \gls{glsxtrsetgrouptitle}\marg{greek}\marg{Greek Symbols}
5155 \strut
5156 \gls[noindex=false]{input}\marg{entries}\comment{input entries.tex}
5157 \strut
5158 \cmd{begin}\marg{document}
5159 \gls{printunsrtglossary}\oarg{\printglossopt[indexgroup]{style}}
5160 \cmd{end}\marg{document}
5161 \end{codeenv}
5162 This is much neater, but maintaining the \filefmt{entries.tex} file is
5163 quite troublesome. Each entry must be defined in the correct order
5164 (that matches the desired listing in \gls{printunsrtglossary}) and
5165 only those entries that should appear in \gls{printunsrtglossary}
5166 should be defined (unless you want the laborious task of filtering
5167 them out, as in \sectionref{sec:printglossagain}). The \field{group}
5168 field needs setting for every entry, and if the \field{location}
5169 field also needs setting then the \filefmt{entries.tex} file will
5170 need to be modified every time new document edits cause a shift in
5171 the page numbers.
5172
5173 With \bibgls, you write all the entry definitions (without the
5174 \field{group} or \field{location} fields set) in one or more
5175 \ext{bib} files. It's then \bibgls\ that creates the equivalent of
5176 the above \filefmt{entries.tex} file with all the entry definitions
5177 in the correct order and with the \field{group} or \field{location}
5178 fields set, if appropriate. To avoid accidentally overwriting an
5179 important document file, \bibgls\ uses the extension \ext{glstex}
5180 rather than \ext{tex} (but it's still a file containing \LaTeX\ code
5181 that defines the entries using \gls{newabbreviation} or
5182 \gls{newglossaryentry}\footnote{Actually it uses
5183 \gls{longnewglossaryentry*} to allow for multi-paragraph descriptions,
5184 and \gls{longnewglossaryentry*} and \gls{newabbreviation} are used
5185 indirectly through helper commands.}).
5186
5187 Instead of using \gls{input} in the document preamble, you now need
5188 to use:
5189 \nosecformatdef{GlsXtrLoadResources}
5190 The \ext{glstex} file doesn't exist on the first \LaTeX\ run as
5191 \bibgls\ can only create the file once the \ext{aux} file has been
5192 created (since the \ext{aux} file contains all the information about
5193 which entries to select, the name of the \ext{bib} files where their
5194 definitions are stored and how to order them).
5195 So \gls{GlsXtrLoadResources} tests if the \ext{glstex} file exists
5196 before trying to input it. The \styopt{record} option is necessary
5197 because it:
5198 \begin{itemize}
5199 \item enables the \styopt[warn]{undefaction} option (the entries
5200 aren't defined on the first \LaTeX\ run);
5201 \item creates the \field{group} and \field{location} fields;
5202 \item disables the \gls{makeindex}\slash\gls{xindy} indexing and
5203 instead writes the indexing information as a record in the \ext{aux}
5204 file;
5205 \item loads \sty{glossaries-extra-bib2gls} (which provides
5206 extra commands specific to \bibgls).
5207 \end{itemize}
5208 Each time you use a command like \gls{gls} or \gls{glssymbol} (but
5209 not like \gls{glsentrysymbol}) in the document, a record is added to
5210 the \ext{aux} file containing the entry's label, the location (by
5211 default the page number) where the entry was used, and extra
5212 information including how to format the location. The default
5213 behaviour of \bibgls\ is to only select those entries that have
5214 records in the \ext{aux} file and any dependent entries.
5215
5216 The example above doesn't include any references (commands like
5217 \gls{gls}), so \bibgls\ won't select any entries and the
5218 \ext{glstex} file won't contain any definitions. This means that the
5219 glossary will be empty. If you want all entries from the specified
5220 \ext{bib} files selected then you need to change the \csopt{selection}
5221 setting:
5222 \begin{codeenv}
5223 \gls{GlsXtrLoadResources}\oarg{\csopt[all]{selection}}
5224 \end{codeenv}
5225 This doesn't explicitly name any \ext{bib} file. The default is
5226 \code{\gls{jobname}\ext{bib}} but you can change this with the
5227 \csopt{src} option. For example, if the entries are defined in
5228 \filefmt{entries.bib} (regular terms), \filefmt{symbols.bib}
5229 (symbols) and \filefmt{abbrvs.bib} (abbreviations) then you need
5230 to use:
5231 \begin{codeenv}
5232 \gls{GlsXtrLoadResources}\oarg{
5233 \csopt[entries,symbols,abbrvs]{src},\comment{bib files}
5234 \csopt[all]{selection}\comment{select all entries}
5235 }
5236 \end{codeenv}
5237
5238 You can have multiple instances of \gls{GlsXtrLoadResources}, but
5239 remember that each instance inputs a file containing definitions, and
5240 the glossary produced with \gls{printunsrtglossary} follows the same
5241 order. This means that you can have blocks within the same glossary
5242 that use different sorting methods. For example:
5243 \begin{codeenv}\renewcommand{\glslinkpresetkeys}{}%
5244 \gls{GlsXtrLoadResources}\oarg{
5245 \csopt[symbols]{src},\comment{bib file}
5246 \csopt[letter-case]{sort},\comment{sort according to character code}
5247 \csopt[symbol]{category},\comment{set this as the \field{category} field}
5248 \csopt[glssymbols]{group}\comment{set this as the \field{group} field}
5249 }
5250 \gls{GlsXtrLoadResources}\oarg{
5251 \csopt[entries,abbrvs]{src},\comment{bib files}
5252 \csopt[en-GB]{sort}
5253 }
5254 \end{codeenv}
5255 The first instance fetches the data from \filefmt{symbols.bib},
5256 sorts the entries according to the character code, sets the
5257 \field{category} field to \code{symbol}, and sets the
5258 \field{group} field to \code{glssymbols} for each definition
5259 written to the \ext{glstex} file. The \code{glssymbols} group label is recognised by
5260 the \sty{glossaries} package, and the title is obtained from the
5261 language-sensitive \gls{glssymbolsgroupname} command (\qt{Symbols}
5262 in English). So the glossary will start with a symbols group
5263 that contains all the entries selected from \filefmt{symbols.bib}.
5264 The rest of the glossary is obtained from the data selected from the
5265 \filefmt{entries.bib} and \filefmt{abbrvs.bib} file sorted according
5266 to the en-GB locale. These entries will have the \field{group} field
5267 set by the locale's sort rule.
5268
5269 The document build now needs to include a call to \bibgls. For
5270 example, if the main document file is called \filefmt{myDoc.tex}
5271 then the build process is:
5272 \begin{verbatim}
5273 pdflatex myDoc
5274 bib2gls --group myDoc
5275 pdflatex myDoc
5276 \end{verbatim}
5277 Omit the \longarg{group} switch if you want the \field{group} field
5278 left empty, and replace \code{pdflatex} with \code{xelatex} etc, as
5279 appropriate.
5280
5281 \section{The \extfmt{bib} Format}
5282 \label{sec:bibentries}
5283
5284 The \ext{bib} files define entry data in the form:
5285 \begin{codeenv}
5286 \gls[noindex=false]{atchar}\meta{entry type}\marg{\meta{id},
5287 \meta{field$_1$} = \margm{value},
5288 \ldots
5289 \meta{field$_n$} = \margm{value}
5290 }
5291 \end{codeenv}
5292 where \meta{id} is the entry's label. The most basic entry type is
5293 \atentry{entry}. For example:
5294 \begin{codeenv}
5295 \atentry{entry}\marg{goose,
5296 \field{name} = \marg{goose},
5297 \field{plural} = \marg{geese},
5298 \field{description} = \marg{a large waterbird with a long neck, short legs,
5299 webbed feet and a short broad bill}
5300 }
5301 \end{codeenv}
5302 This is analogous to:
5303 \begin{codeenv}
5304 \gls{newglossaryentry}\marg{goose}
5305 \marg{
5306 \field{name} = \marg{goose},
5307 \field{plural} = \marg{geese},
5308 \field{description} = \marg{a large waterbird with a long neck, short legs,
5309 webbed feet and a short broad bill}
5310 }
5311 \end{codeenv}
5312 You can use any of the defined keys, such as \field{symbol}:
5313 \begin{codeenv}
5314 \atentry{entry}\marg{amethyst,
5315 \field{name} = \marg{amethyst},
5316 \field{description} = \marg{a purple type of quartz},
5317 \field{symbol} = \marg{\gls{ce}\marg{SiO2}}
5318 }
5319 \end{codeenv}
5320 but avoid using internal fields. If you define custom keys in your
5321 document, make sure you define them all before the first instance of
5322 \gls{GlsXtrLoadResources} as all the recognised keys are written to
5323 the \ext{aux} file for \bibgls\ to detect. Any unrecognised fields
5324 in the \ext{bib} file are ignored.
5325
5326 \begin{important}
5327 The \atentry{entry} type is intended mainly for words or phrases,
5328 optionally with an associated \field{symbol}. If
5329 the \field{name} field contains symbols or other non-alphabetic
5330 content (such as punctuation that shouldn't be ignored by the sort
5331 comparator) see \sectionref{sec:@symbol}.
5332 \end{important}
5333
5334 \subsection{Defining Terms with Optional Descriptions}
5335 \label{sec:@index}
5336
5337 The \atentry{entry} type requires the \field{description} field and
5338 either the \field{name} or \field{parent} field. There's a similar
5339 command that doesn't have any required fields: \atentry{index}. If
5340 the \field{name} isn't supplied, it's assumed to be the same as the
5341 \meta{id}. If the \field{description} isn't supplied it's assumed to
5342 be empty. This type behaves like \atentry{entry}, but it sets the
5343 default \field{category} to \code{index}. So:
5344 \begin{codeenv}
5345 \atentry{index}\marg{duck}
5346 \end{codeenv}
5347 is analogous to:
5348 \begin{codeenv}
5349 \gls{newglossaryentry}\marg{duck}
5350 \marg{
5351 \field{name}=\marg{duck},
5352 \field{description}=\marg{},
5353 \field{category}=\marg{index}
5354 }
5355 \end{codeenv}
5356 and
5357 \begin{codeenv}
5358 \atentry{index}\marg{goose,
5359 \field{plural} = \marg{geese}
5360 }
5361 \end{codeenv}
5362 is analogous to:
5363 \begin{codeenv}
5364 \gls{newglossaryentry}\marg{goose}
5365 \marg{
5366 \field{name}=\marg{goose},
5367 \field{plural}=\marg{geese},
5368 \field{description}=\marg{},
5369 \field{category}=\marg{index}
5370 }
5371 \end{codeenv}
5372 If the name contains content that can't be used in a label (see
5373 \sectionref{sec:labels}), then
5374 you need the \field{name} field. For example:
5375 \begin{codeenv}
5376 \atentry{index}\marg{chateau,
5377 \field{name} = \marg{ch\gls[noindex=false]{cs.circum}ateau},
5378 \field{plural} = \marg{ch\gls{cs.circum}ateaux}
5379 }
5380 \end{codeenv}
5381 is analogous to:
5382 \begin{codeenv}
5383 \gls{newglossaryentry}\marg{chateau}
5384 \marg{
5385 \field{name}=\marg{ch\gls{cs.circum}ateau},
5386 \field{plural}=\marg{ch\gls{cs.circum}ateaux},
5387 \field{description}=\marg{},
5388 \field{category}=\marg{index}
5389 }
5390 \end{codeenv}
5391 There's a similar entry type \atentry{indexplural} that sets the
5392 \field{name} field (if not provided) to the plural form, which is
5393 obtained from the \field{plural} field, if set. Otherwise it's
5394 obtained by appending the plural suffix (\qt{s}) to the \field{text}
5395 field. If the \field{text} field isn't set it's obtained from the label.
5396 The other difference is that it sets the default \field{category} field to
5397 \code{indexplural}. For example,
5398 \begin{codeenv}
5399 \atentry{indexplural}\marg{duck}
5400 \end{codeenv}
5401 is analogous to:
5402 \begin{codeenv}
5403 \gls{newglossaryentry}\marg{duck}
5404 \marg{
5405 \field{name}=\marg{ducks},
5406 \field{text}=\marg{duck},
5407 \field{description}=\marg{},
5408 \field{category}=\marg{indexplural}
5409 }
5410 \end{codeenv}
5411 and
5412 \begin{codeenv}
5413 \atentry{indexplural}\marg{goose,
5414 \field{plural} = \marg{geese}
5415 }
5416 \end{codeenv}
5417 is analogous to:
5418 \begin{codeenv}
5419 \gls{newglossaryentry}\marg{goose}
5420 \marg{
5421 \field{name}=\marg{geese},
5422 \field{text}=\marg{goose},
5423 \field{plural}=\marg{geese},
5424 \field{description}=\marg{},
5425 \field{category}=\marg{indexplural}
5426 }
5427 \end{codeenv}
5428
5429 The \csopt[firstuc]{name-case-change} resource option converts the
5430 first letter of the \field{name} field to \idx{uppercase}, so with
5431 \begin{codeenv}
5432 \gls{GlsXtrLoadResources}\oarg{\csopt[firstuc]{name-case-change}}
5433 \end{codeenv}
5434 then
5435 \begin{codeenv}
5436 \atentry{index}\marg{duck}
5437 \end{codeenv}
5438 is now analogous to:
5439 \begin{codeenv}
5440 \gls{newglossaryentry}\marg{duck}
5441 \marg{
5442 \field{name}=\marg{Duck},
5443 \field{text}=\marg{duck},
5444 \field{description}=\marg{},
5445 \field{category}=\marg{index}
5446 }
5447 \end{codeenv}
5448 and
5449 \begin{codeenv}
5450 \atentry{indexplural}\marg{goose,
5451 \field{plural} = \marg{geese}
5452 }
5453 \end{codeenv}
5454 is now analogous to:
5455 \begin{codeenv}
5456 \gls{newglossaryentry}\marg{goose}
5457 \marg{
5458 \field{name}=\marg{Geese},
5459 \field{text}=\marg{goose},
5460 \field{plural}=\marg{geese},
5461 \field{description}=\marg{},
5462 \field{category}=\marg{indexplural}
5463 }
5464 \end{codeenv}
5465 and
5466 \begin{codeenv}
5467 \atentry{entry}\marg{amethyst,
5468 \field{name} = \marg{amethyst},
5469 \field{description} = \marg{a purple type of quartz},
5470 \field{symbol} = \marg{\gls{ce}\marg{SiO2}}
5471 }
5472 \end{codeenv}
5473 is now analogous to:
5474 \begin{codeenv}
5475 \gls{newglossaryentry}\marg{amethyst}
5476 \marg{
5477 \field{name}=\marg{Amethyst},
5478 \field{text}=\marg{amethyst},
5479 \field{description}=\marg{a purple type of quartz},
5480 \field{symbol} = \marg{\gls{ce}\marg{SiO2}}
5481 }
5482 \end{codeenv}
5483
5484 \subsection{Defining Abbreviations}
5485 \label{sec:@abbreviation}
5486
5487 Abbreviations can be defined with \atentry{abbreviation}. For
5488 example:
5489 \begin{codeenv}
5490 \atentry{abbreviation}\marg{html,
5491 \field{short} = \marg{HTML},
5492 \field{long} = \marg{hypertext markup language}
5493 }
5494 \end{codeenv}
5495 which is analogous to:
5496 \begin{codeenv}
5497 \gls{newabbreviation}\marg{html}\marg{HTML}\marg{hypertext markup language}
5498 \end{codeenv}
5499 (which sets the \field{category} to \code{abbreviation}).
5500 Alternatively, you can use \atentry{acronym}. For example:
5501 \begin{codeenv}
5502 \atentry{acronym}\marg{html,
5503 \field{short} = \marg{HTML},
5504 \field{long} = \marg{hypertext markup language}
5505 }
5506 \end{codeenv}
5507 which is analogous to:
5508 \begin{codeenv}
5509 \gls{newacronym}\marg{html}\marg{HTML}\marg{hypertext markup language}
5510 \end{codeenv}
5511 (which sets the \field{category} to \code{acronym}).
5512 If you decide to use one of the abbreviation styles that formats the
5513 \field{short} field with \gls{textsc} (for example,
5514 \abbrstyle{long-short-sc}) then the \field{short} value needs to be
5515 in \idx{lowercase}. (Remember that \gls{textsc} only changes
5516 \idx{lowercase} characters to small capitals. For example,
5517 \code{\gls{textsc}\marg{html}} is displayed as \textsc{html} but
5518 \code{\gls{textsc}\marg{HTML}} is displayed as \textsc{HTML}.)
5519 This can easily be accomplished with the
5520 \csopt{short-case-change} resource option. For example:
5521 \begin{codeenv}
5522 \gls{GlsXtrLoadResources}\oarg{\csopt[lc]{short-case-change}}
5523 \end{codeenv}
5524 Recall from \sectionref{sec:abbreviations} that the abbreviation
5525 style must be set \emph{before} the abbreviations are defined. This
5526 means that if you want to use \gls{setabbreviationstyle} it must
5527 come before \gls{GlsXtrLoadResources}.
5528
5529 The default sort value used by \bibgls\ is usually taken from the
5530 \field{name} field. This typically isn't supplied with abbreviations.
5531 The actual value depends on the abbreviation style, which \bibgls\
5532 doesn't know about, so \bibgls\ uses the \field{short}
5533 field instead for abbreviations. If you want to change this, for
5534 example, if you are using the \abbrstyle{long-noshort-desc} style,
5535 then use the \csopt{abbreviation-sort-fallback} option. For example:
5536 \begin{codeenv}
5537 \gls{GlsXtrLoadResources}\oarg{\csopt[long]{abbreviation-sort-fallback}}
5538 \end{codeenv}
5539
5540 \subsection{Defining Symbols}
5541 \label{sec:@symbol}
5542
5543 If the \field{name} field contains the symbol (rather than having a
5544 textual \field{name} and the symbol in \field{symbol}) then the
5545 notation can be defined with \atentry{symbol}. For example:
5546 \begin{codeenv}
5547 \atentry{symbol}\marg{pi,
5548 \field{name} = \marg{\gls{ensuremath}\marg{\cmd{pi}}},
5549 \field{description} = \marg{Archimedes' constant}
5550 }
5551 \end{codeenv}
5552 This behaves much like \atentry{entry} but there are two significant
5553 differences: the \field{category} defaults to \code{symbol} and the
5554 default value used when sorting is the label not the value of the \field{name}
5555 field. So in this case, the sort value defaults to \code{pi}.
5556 Therefore the above is analogous to:
5557 \begin{codeenv}
5558 \gls{newglossaryentry}\marg{pi}
5559 \marg{
5560 \field{name} = \marg{\gls{ensuremath}\marg{\cmd{pi}}},
5561 \field{description} = \marg{Archimedes' constant},
5562 \field{category} = \marg{symbol},
5563 \field{sort} = \marg{pi}
5564 }
5565 \end{codeenv}
5566 This is essentially like \gls{glsxtrnewsymbol} but it doesn't set
5567 the \field{type} field.
5568
5569 You can change the default value used for sorting symbols with the
5570 \csopt{symbol-sort-fallback} option. For example, to sort symbols according
5571 to the \field{name} field:
5572 \begin{codeenv}\renewcommand{\glslinkpresetkeys}{}%
5573 \gls{GlsXtrLoadResources}\oarg{
5574 \csopt[name]{symbol-sort-fallback},
5575 \csopt[none]{break-at}
5576 }
5577 \end{codeenv}
5578 This means that the sort value for the above example entry is now
5579 \code{\gls{ensuremath}\marg{\csfmt{pi}}}, which \bibgls's \TeX\
5580 interpreter converts to the Unicode symbol \hex{1D70B} (mathematical
5581 italic small pi, $\pi$). The interpreter used by \bibgls\ recognises
5582 all the standard mathematical Greek commands, and also the missing
5583 Greek commands \gls{omicron}, \gls{Alpha} etc (which are provided by
5584 \sty{glossaries-extra-bib2gls}). Using these commands rather than
5585 the Latin equivalent ensures correct sorting (\gls{omicron} comes
5586 between \csfmt{xi} and \csfmt{pi}, but \code{o} comes between \code{n}
5587 and \code{p}). See \sectionref{sec:texparserlib} (\TeX\ Parser
5588 Library) in the \bibgls\ user manual for further details.
5589
5590 \begin{important}
5591 The default sort method is designed for words and phrases, so
5592 non-letters, such as punctuation characters, are discarded.
5593 If your sort values include symbols that need to be taken into
5594 account by the comparator, use \csopt[none]{break-at} to prevent
5595 them from being discarded.
5596 \end{important}
5597
5598 Alternatively, you may prefer to sort symbols according to the
5599 description:
5600 \begin{codeenv}\renewcommand{\glslinkpresetkeys}{}%
5601 \gls{GlsXtrLoadResources}\oarg{\csopt[description]{symbol-sort-fallback}}
5602 \end{codeenv}
5603
5604 There's a similar entry type \atentry{number}, which behaves much
5605 like \atentry{symbol} except that it sets the default
5606 \field{category} to \code{number}. It also follows the
5607 \csopt{symbol-sort-fallback} setting. For example, the \code{pi}
5608 entry could be defined as:
5609 \begin{codeenv}
5610 \atentry{symbol}\marg{pi,
5611 \field{name} = \marg{\gls{ensuremath}\marg{\cmd{pi}}},
5612 \field{description} = \marg{Archimedes' constant},
5613 \fieldfmt{value} = \marg{3.141592654}
5614 }
5615 \end{codeenv}
5616 I've used a custom field here (\fieldfmt{value}) that \bibgls\ will
5617 ignore by default. I can instruct \bibgls\ to convert this to a
5618 known field with \csopt{field-aliases}. For example:
5619 \begin{codeenv}
5620 \gls{GlsXtrLoadResources}\oarg{\csopt[value=user1]{field-aliases}}
5621 \end{codeenv}
5622 This makes \bibgls\ treat;
5623 \begin{codeenv}
5624 \fieldfmt{value} = \marg{3.141592654}
5625 \end{codeenv}
5626 as though it had been:
5627 \begin{codeenv}
5628 \fieldfmt{user1} = \marg{3.141592654}
5629 \end{codeenv}
5630 This can now be used in one of the hooks (described in
5631 \sectionref{sec:glsformats}). For example, the
5632 \idx{postdescriptionhook}:
5633 \begin{codeenv}\renewcommand{\glslinkpresetkeys}{}%
5634 \gls{glsdefpostdesc}\marg{number}\marg{\comment{check if \field{user1} field given:}
5635 \gls{glsxtrifhasfield}\marg{\field{useri}}\marg{\gls{glscurrententrylabel}}
5636 \marg{ (\gls{glscurrentfieldvalue})}
5637 \marg{}\comment{not provided}
5638 }
5639 \end{codeenv}
5640 It can also be used if you want to order the entries numerically.
5641 For example:
5642 \begin{codeenv}\renewcommand{\glslinkpresetkeys}{}%
5643 \gls{GlsXtrLoadResources}\oarg{
5644 \csopt[value=user1]{field-aliases},
5645 \csopt[double]{sort},\comment{use double-precision numeric comparisons}
5646 \csopt[user1]{sort-field}
5647 }
5648 \end{codeenv}
5649 This uses \csopt{sort-field} to set the field used for sorting. This
5650 affects all entry types.
5651
5652 There are more examples in \sectionref{sec:examples} of the main
5653 \bibgls\ user manual.
5654
5655 \section{Indexing}
5656 \label{sec:record}
5657
5658 By default, \bibgls\ selects entries from the specified \ext{bib}
5659 files that have been directly indexed in the document or that are
5660 dependencies of selected entries. Indexing is performed through
5661 commands like \gls{gls} and \gls{glssymbol} (but not by commands
5662 like \gls{glsentrysymbol}). The \styopt{record} package option
5663 ensures that the indexing is done that matches the requirements of
5664 \bibgls\ (rather than the default \gls{makeindex} syntax).
5665
5666 Each instance of \gls{gls}, \gls{glssymbol} etc writes a
5667 \pidx{record} to the \ext{aux} file, that includes the entry's
5668 label, the location in the document where the record was triggered
5669 and the associated format to encapsulate the location. For example,
5670 if \code{\gls{gls}\marg{duck}} appears on page~3, the record label
5671 is \code{duck}, the location is~3 and the format is the default
5672 \gls{glsnumberformat}.
5673
5674 The format can be changed with the \glsopt{format} key. For example:
5675 \begin{codeenv}
5676 \gls{gls}\oarg{\glsopt{format}=hyperbf}\marg{duck}
5677 \end{codeenv}
5678 This sets the format to \code{hyperbf}, which makes a bold
5679 hyperlink, if \sty{hyperref} has been loaded, otherwise it just uses
5680 \gls{textbf}. The value of the \glsopt{format} option should be the
5681 name (without a leading backslash) of a text-block command that
5682 takes a single argument (the location to be formatted). The
5683 \sty{glossaries} package provides some commands like \gls{hyperbf}
5684 that may be used to ensure a hyperlink (if supported). The basic
5685 command is:
5686 \nosecformatdef{glshypernumber}
5687 which provides the hyperlink (if enabled) otherwise it just does its
5688 argument. So, if you want, for example, an underlined hyperlink:
5689 \begin{codeenv}
5690 \cmd{newcommand}\marg{\cmd{hyperul}}[1]\marg{\gls[noindex=false]{underline}\marg{\gls{glshypernumber}\marg{\gls{param}1}}}
5691 \end{codeenv}
5692 Now you can use \glsopt[hyperul]{format}.
5693
5694 There's a special command \gls{glsignore} that ignores its argument.
5695 With \gls{makeindex} and \gls{xindy}, this can lead to spurious
5696 commas in the \idx{locationlist}, because the location is still
5697 included in the list, even though the location itself isn't
5698 displayed (since it's discarded by \gls{glsignore}). However, \bibgls\
5699 recognises \glsopt[glsignore]{format} as a special \idx{ignoredrecord}. This
5700 indicates that \bibgls\ should select that particular entry but not
5701 include that record in the \idx{locationlist}.
5702
5703 If a selected entry depends on another entry that hasn't been
5704 indexed, for example, a parent entry, then the dependent entry will
5705 automatically be selected as well, by default. The dependent entry
5706 won't have a \idx{locationlist} if it hasn't been indexed anywhere.
5707 If you don't want the \idxpl{locationlist} to appear in a particular
5708 glossary, use \printglossopt{nonumberlist} in the optional argument
5709 of \gls{printunsrtglossary}.
5710
5711 If you want to index an entry without actually displaying any text,
5712 you can use:
5713 \nosecformatdef{glsadd}
5714 where \meta{label} is the entry's label. The \glsaddopt{format} key
5715 is again available in \meta{options}. For example:
5716 \begin{codeenv}
5717 \cmd{renewcommand}\marg{\gls{glsextrapostnamehook}}[1]\marg{\comment
5718 \gls{glsadd}\oarg{\glsaddopt{format}=hyperbf}\marg{\gls{param}1}\comment{}
5719 }
5720 \end{codeenv}
5721 This automatically indexes the given entry in the
5722 \idx{postnamehook}. This is redundant if you only have a single
5723 glossary, but may be useful if the entry is repeated in a later
5724 list. Alternatively, if you are using a dual entry type (see
5725 \sectionref{sec:dualentry} in the main \bibgls\ user manual), the
5726 hook could check for the existence of the dual label (identified by
5727 the \csopt{dual-field} resource option) and use that instead. For
5728 example:
5729 \begin{codeenv}\renewcommand{\glslinkpresetkeys}{}%
5730 \cmd{renewcommand}\marg{\gls{glsextrapostnamehook}}[1]\marg{\comment
5731 \gls{glsxtrifhasfield}\marg{\gls{GlsXtrDualField}}\marg{\gls{param}1}
5732 \marg{\comment{}
5733 \gls{glsadd}\oarg{\glsaddopt{format}=hyperbf}\marg{\gls{glscurrentfieldvalue}}\comment{}
5734 }\comment{}
5735 \marg{}\comment{no dual}
5736 }
5737 \end{codeenv}
5738
5739 If you want to index multiple entries at the same time with the same
5740 set of options, you can use:
5741 \nosecformatdef{glsaddeach}
5742 This just iterates through the comma-separated list of labels and
5743 performs \gls{glsadd}\oargm{options}\margm{label} for each label in
5744 \meta{label list}. For example, to ensure that \bibgls\ selects the
5745 entries with the labels \code{duck}, \code{goose} and \code{parrot},
5746 even if they aren't referenced in the document:
5747 \begin{codeenv}
5748 \gls{glsaddeach}\oarg{\glsaddopt[glsignore]{format}}\marg{duck,goose,parrot}
5749 \end{codeenv}
5750 To select all entries, regardless of whether or not they have been
5751 indexed, use the \csopt[all]{selection} resource option. There are
5752 other selection criteria. See the main \bibgls\ user manual for
5753 further details.
5754
5755 \section{Aliasing Fields and Entry Types}
5756 \label{sec:resourcealias}
5757
5758 In \sectionref{sec:abbrvtrans}, the \field{user1} key was used to
5759 store a translation:
5760 \begin{codeenv}
5761 \gls{newabbreviation}\oarg{\field{user1}=\marg{ribonucleic acid}}
5762 \marg{rna}\marg{RNA}\marg{ribonukleins\gls{umlaut}aure}
5763 \end{codeenv}
5764 You can also use the generic user fields in \ext{bib} files, but
5765 a more flexible approach is to use a semantic naming scheme in the
5766 \ext{bib} file and use resource aliasing to convert these custom
5767 field names into recognised keys. For example, the above
5768 abbreviation could be written in the \ext{bib} file as:
5769 \begin{codeenv}
5770 \atentry{abbreviation}\marg{rna,
5771 \field{short} = \marg{RNA},
5772 \field{long} = \marg{ribonukleins\gls{umlaut}aure},
5773 \fieldfmt{translation} = \marg{ribonucleic acid}
5774 }
5775 \end{codeenv}
5776 The custom \fieldfmt{translation} field will be ignored by \bibgls,
5777 unless it's first defined in the document or aliased in the resource
5778 options:
5779 \begin{codeenv}\renewcommand{\glslinkpresetkeys}{}%
5780 \gls{GlsXtrLoadResources}\oarg{
5781 \csopt[abbrvs]{src},\comment{entries defined in abbrvs.bib}
5782 \comment{treat \fieldfmt{translation} as though it's \field{user1}:}
5783 \csopt[translation=user1]{field-aliases}
5784 }
5785 \end{codeenv}
5786 This makes \bibgls\ behave as though the entry was defined in the
5787 \bibgls\ file as:
5788 \begin{codeenv}
5789 \atentry{abbreviation}\marg{rna,
5790 \field{short} = \marg{RNA},
5791 \field{long} = \marg{ribonukleins\gls{umlaut}aure},
5792 \field{user1} = \marg{ribonucleic acid}
5793 }
5794 \end{codeenv}
5795 The definition is now the same as the above example from
5796 \sectionref{sec:abbrvtrans}. The \ext{bib} entry type can also be
5797 aliased. Here's a modified version:
5798 \begin{codeenv}
5799 \atentryfmt{foreignabbreviation}\marg{rna,
5800 \field{short} = \marg{RNA},
5801 \fieldfmt{nativelong} = \marg{ribonukleins\gls{umlaut}aure},
5802 \fieldfmt{foreignlong} = \marg{ribonucleic acid}
5803 }
5804 \end{codeenv}
5805 and here are the aliases:
5806 \begin{codeenv}\renewcommand{\glslinkpresetkeys}{}%
5807 \gls{GlsXtrLoadResources}\oarg{
5808 \csopt[abbrvs]{src},\comment{entries defined in abbrvs.bib}
5809 \comment{treat \atentryfmt{foreignabbreviation} as though it's \atentry{abbreviation}:}
5810 \csopt[foreignabbreviation=abbreviation]{entry-type-aliases},
5811 \csopt[nativelong=long,foreignlong=user1]{field-aliases}
5812 }
5813 \end{codeenv}
5814 This has the same result, but suppose another document is in English
5815 rather than German:
5816 \begin{codeenv}\renewcommand{\glslinkpresetkeys}{}%
5817 \gls{GlsXtrLoadResources}\oarg{
5818 \csopt[abbrvs]{src},\comment{entries defined in abbrvs.bib}
5819 \csopt[foreignabbreviation=abbreviation]{entry-type-aliases},
5820 \csopt[foreignlong=long]{field-aliases}
5821 }
5822 \end{codeenv}
5823 Now the \field{long} field is set to the English version, and the
5824 German long form is ignored.
5825
5826 Here's another example where the native language is now English:
5827 \begin{codeenv}\renewcommand{\glslinkpresetkeys}{}%
5828 \atentry{abbreviation}\marg{iso,
5829 \field{short} = \marg{ISO},
5830 \field{long} = \marg{International Organization for Standardization}
5831 }
5832 \strut
5833 \atentryfmt{foreignabbreviation}\marg{abnt,
5834 \field{short} = \marg{ABNT},
5835 \fieldfmt{foreignlong} = \marg{Associa\gls{c}\marg{c}\gls{cs.tilde}ao Brasileria de Normas T\cs{acute}ecnicas},
5836 \fieldfmt{nativelong} = \marg{Brazilian National Standards Organization},
5837 \fieldfmt{language} = \marg{pt-BR}
5838 }
5839 \strut
5840 \atentryfmt{foreignabbreviation}\marg{din,
5841 \field{short} = \marg{DIN},
5842 \fieldfmt{foreignlong} = \marg{Deutsches Institut f\gls{umlaut}ur Normung e.V.},
5843 \fieldfmt{nativelong} = \marg{German Institute for Standardization},
5844 \fieldfmt{language} = \marg{de-DE-1996}
5845 }
5846 \end{codeenv}
5847 The aliasing is again identified in the resource options:
5848 \begin{codeenv}\renewcommand{\glslinkpresetkeys}{}%
5849 \gls{GlsXtrLoadResources}\oarg{
5850 \csopt[abbrvs]{src},\comment{entries defined in abbrvs.bib}
5851 \csopt[foreignabbreviation=abbreviation]{entry-type-aliases},
5852 \csopt[nativelong=long,foreignlong=user1,language=user2]{field-aliases},
5853 \csopt[same as original entry]{category}
5854 }
5855 \end{codeenv}
5856 This has an extra setting that assigns the \field{category} field to
5857 the original entry type (before any aliasing occurred) without the
5858 leading \gls{atchar} (and converted to \idx{lowercase}). This makes
5859 \bibgls\ act as though the abbreviations had actually been defined
5860 as:
5861 \begin{codeenv}
5862 \atentry{abbreviation}\marg{iso,
5863 \field{short} = \marg{ISO},
5864 \field{long} = \marg{International Organization for Standardization},
5865 \field{category} = \marg{abbreviation}
5866 }
5867 \strut
5868 \atentryfmt{abbreviation}\marg{abnt,
5869 \field{short} = \marg{ABNT},
5870 \field{user1} = \marg{Associa\gls{c}\marg{c}\gls{cs.tilde}ao Brasileria de Normas T\cs{acute}ecnicas},
5871 \field{long} = \marg{Brazilian National Standards Organization},
5872 \field{user2} = \marg{pt-BR},
5873 \field{category} = \marg{foreignabbreviation}
5874 }
5875 \strut
5876 \atentryfmt{abbreviation}\marg{din,
5877 \field{short} = \marg{DIN},
5878 \field{user1} = \marg{Deutsches Institut f\gls{umlaut}ur Normung e.V.},
5879 \field{long} = \marg{German Institute for Standardization},
5880 \field{user2} = \marg{de-1996},
5881 \field{category} = \marg{foreignabbreviation}
5882 }
5883 \end{codeenv}
5884 which is now the same as an earlier example in
5885 \sectionref{sec:abbrvtrans}.
5886 If I don't need a particular custom field (such as
5887 \fieldfmt{language} in the above), I can simply omit it from the
5888 aliasing, but it's available for other documents if the need arises.
5889 Here's the complete document modified from
5890 \sectionref{sec:abbrvtrans}:
5891 \begin{codeenv}
5892 \cmd{documentclass}\marg{article}
5893 \strut
5894 \cmd{usepackage}[main=british,brazilian,ngerman]\marg{babel}
5895 \cmd{usepackage}[\styopt{record}]\marg{glossaries-extra}
5896 \strut
5897 \gls{setabbreviationstyle}\oarg{foreignabbreviation}\marg{long-short-user}
5898 \strut
5899 \gls{GlsXtrLoadResources}\oarg{
5900 \csopt[abbrvs]{src},\comment{entries defined in abbrvs.bib}
5901 \csopt[foreignabbreviation=abbreviation]{entry-type-aliases},
5902 \csopt[nativelong=long,foreignlong=user1,language=user2]{field-aliases},
5903 \csopt[same as original entry]{category}
5904 }
5905 \strut
5906 \cmd{renewcommand}*\marg{\gls{glsxtruserparen}}[2]\marg{\comment{}
5907 \gls{glsxtrfullsep}\marg{\gls{param}2}\comment{}
5908 \gls{glsxtrparen}
5909 \marg{\gls{param}1\comment{}
5910 \gls{ifglshasfield}\marg{\gls{glsxtruserfield}}\marg{\gls{param}2}\comment{}
5911 \marg{, \gls{emph}\marg{\gls{GlsXtrForeignText}\marg{\gls{param}2}\marg{\gls{glscurrentfieldvalue}}}}\comment{}
5912 \marg{}\comment{}
5913 }\comment{}
5914 }
5915 \strut
5916 \cmd{begin}\marg{document}
5917 \gls{gls}\marg{abnt}, \gls{gls}\marg{din}.
5918 \cmd{end}\marg{document}
5919 \end{codeenv}
5920
5921 Here's another example where field and entry aliasing can make the
5922 \ext{bib} data more flexible:
5923 \begin{codeenv}
5924 \atentryfmt{mineral}\marg{amethyst,
5925 \fieldfmt{mineralname} = \marg{amethyst},
5926 \fieldfmt{mineraldescription} = \marg{a purple type of quartz},
5927 \fieldfmt{mineralformula} = \marg{\gls{ce}\marg{SiO2}}
5928 }
5929 \end{codeenv}
5930 For one document, I might use:
5931 \begin{codeenv}
5932 \gls{GlsXtrLoadResources}\oarg{
5933 \csopt[entries]{src},\comment{data in entries.bib}
5934 \csopt[mineral=symbol]{entry-type-aliases},
5935 \csopt[
5936 mineralformula=name,
5937 mineralname=description
5938 ]{field-aliases},
5939 \csopt[same as original entry]{category}
5940 }
5941 \end{codeenv}
5942 This makes the \code{amethyst} entry behave as though it was defined
5943 as:
5944 \begin{codeenv}
5945 \atentry{symbol}\marg{amethyst,
5946 \field{description} = \marg{amethyst},
5947 \field{name} = \marg{\gls{ce}\marg{SiO2}},
5948 \field{category} = \marg{mineral}
5949 }
5950 \end{codeenv}
5951 Another document might have:
5952 \begin{codeenv}
5953 \gls{GlsXtrLoadResources}\oarg{
5954 \csopt[entries]{src},\comment{data in entries.bib}
5955 \csopt[mineral=entry]{entry-type-aliases},
5956 \csopt[
5957 mineralformula=symbol,
5958 mineralname=name
5959 mineraldescription=description
5960 ]{field-aliases},
5961 \csopt[same as original entry]{category}
5962 }
5963 \end{codeenv}
5964 which now makes the \code{amethyst} entry behave as though it was defined
5965 as:
5966 \begin{codeenv}
5967 \atentry{entry}\marg{amethyst,
5968 \field{name} = \marg{amethyst},
5969 \field{description} = \marg{a purple type of quartz},
5970 \field{symbol} = \marg{\gls{ce}\marg{SiO2}},
5971 \field{category} = \marg{mineral}
5972 }
5973 \end{codeenv}
5974
5975 See \sectionref{sec:examples} in the main \bibgls\ user manual for
5976 more examples of aliasing fields and entry types.
5977
5978 \bibliographystyle{plain}
5979 \bibliography{bib2gls-cite}
5980
5981 \printunsrtglossary*
5982 [style=treegroup,title={Command Summary},nonumberlist]
5983 {%
5984 \renewcommand*{\printunsrtglossaryentryprocesshook}[1]{%
5985 \glsifcategory{#1}{command}{}{\printunsrtglossaryskipentry}%
5986 }%
5987 \glssetcategoryattribute{command}{glossdesc}{firstuc}%
5988 \renewcommand*{\csfmtfont}[1]{\texttt{\color{cs}#1}}%
5989 \renewcommand{\glstreenamefmt}{\texttt}%
5990 \renewcommand{\glstreegroupheaderfmt}{\textbf}%
5991 \renewcommand{\glstreesubitem}{\glspar\parindent=2em\hangindent2em}%
5992 \renewcommand{\glstreepredesc}{\glsadd{\glscurrententrylabel}%
5993 \nopagebreak\glstreesubitem}%
5994 \glsdefpostname{command}{\glsentryuseri{\glscurrententrylabel}}%
5995 \glsdefpostdesc{command}{.\nopagebreak\glstreesubitem
5996 \Glsentryuserii{\glscurrententrylabel}.%
5997 \glspar\medskip}%
5998 }
5999
6000 \renewcommand*{\glstarget}[2]{%
6001 \glsifcategory{#1}{command}{#2}%
6002 {%
6003 \glsifcategory{#1}{standalone}{#2}%
6004 {\glsdohypertarget{\glolinkprefix#1}{#2}}%
6005 }%
6006 }
6007 \renewcommand{\glstreeitem}{\par\parindent0pt}
6008 \renewcommand*{\glsxtrbookindexprelocation}[1]{%
6009 \glsxtrifhasfield{location}{#1}%
6010 {\enspace
6011 \textcolor{lightgray}{\nolinebreak\cleaders\hbox to .5em{\hss.\hss}\hfill}%
6012 \enspace}%
6013 {}%
6014 }
6015 \renewcommand*{\printunsrtglossaryentryprocesshook}[1]{%
6016 \glsxtriflabelinlist{\glscategory{#1}}{standalone,hierarchical,homograph}%
6017 {\printunsrtglossaryskipentry}{}%
6018 }%
6019 \printunsrtglossary[style=bookindex,title=Index]
6020 \end{document}