| 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} |