| 1 |
% arara: lualatex |
| 2 |
% arara: bib2gls: {group: on} if missing("glstex") || changed("bib") || found("log", "Warning: Glossary entry") |
| 3 |
% arara: bibtex |
| 4 |
% arara: lualatex if changed("glstex") || missing("toc") |
| 5 |
% arara: bib2gls: {group: on, packages: [mfirstuc-english]} |
| 6 |
% arara: lualatex |
| 7 |
% arara: lualatex |
| 8 |
\documentclass[titlepage=false,index=totoc,bibliography=totoc, |
| 9 |
fontsize=12pt,captions=tableheading]{scrreprt} |
| 10 |
|
| 11 |
\usepackage[autooneside=false]{scrlayer-scrpage} |
| 12 |
\usepackage{pifont} |
| 13 |
|
| 14 |
% Need support for less common extended characters |
| 15 |
% and need a mono font that supports hyphenation |
| 16 |
\usepackage[no-math]{fontspec} |
| 17 |
\setmainfont{Linux Libertine O} |
| 18 |
|
| 19 |
\newfontface\cyrillicmono{FreeMono}[Scale=MatchLowercase] |
| 20 |
\newcommand{\textcyrillicmono}[1]{{\cyrillicmono #1}} |
| 21 |
|
| 22 |
\newfontface\greekmono{FreeMono}[Scale=MatchLowercase] |
| 23 |
\newfontface\freeserif{FreeSerif} |
| 24 |
\newcommand{\devone}{{\freeserif\char"0967}} |
| 25 |
\newcommand{\devtwo}{{\freeserif\char"0968}} |
| 26 |
\newcommand{\devsix}{{\freeserif\char"096C}} |
| 27 |
\newcommand{\insularG}{{\freeserif\char"A77D}} |
| 28 |
\newcommand{\insularg}{{\freeserif\char"1D79}} |
| 29 |
\newcommand{\longs}{\char"017F} |
| 30 |
\newcommand{\Wynn}{\char"01F7} |
| 31 |
\newcommand{\wynn}{\char"01BF} |
| 32 |
|
| 33 |
\usepackage[x11names]{xcolor} |
| 34 |
\usepackage{alltt} |
| 35 |
\usepackage{array} |
| 36 |
\usepackage{upquote} |
| 37 |
\usepackage{etoolbox} |
| 38 |
|
| 39 |
\usepackage{hologo} |
| 40 |
\usepackage{amsmath} |
| 41 |
\usepackage{accents} |
| 42 |
\usepackage{tikz} |
| 43 |
\usepackage{tcolorbox} |
| 44 |
\usepackage{datetime2} |
| 45 |
\usepackage{mfirstuc-english} |
| 46 |
\usepackage{listings} |
| 47 |
\usepackage{scrhack} |
| 48 |
\usepackage[hidelinks]{hyperref} |
| 49 |
\usepackage{cleveref} |
| 50 |
\usepackage[% v1.47+ |
| 51 |
record,% use bib2gls |
| 52 |
index,% create index glossary |
| 53 |
entrycounter,% enable entry counting |
| 54 |
subentrycounter,% enable entry counting |
| 55 |
%debug=showtargets,% debugging information |
| 56 |
%debug=showwrgloss,% debugging information |
| 57 |
stylemods={mcols,bookindex},% adjust predefined styles and load glossary-mcols.sty and glossary-bookindex.sty |
| 58 |
style=bookindex |
| 59 |
] |
| 60 |
{glossaries-extra} |
| 61 |
|
| 62 |
\lstset{language={[LaTeX]TeX},upquote,basicstyle={\ttfamily\small}, |
| 63 |
commentstyle={\color{gray}}} |
| 64 |
|
| 65 |
\renewcommand*{\glsshowtarget}[1]{\texttt{\small [#1]}} |
| 66 |
|
| 67 |
\glsxtrprovidestoragekey{note}{}{} |
| 68 |
\glsxtrprovidestoragekey{package}{}{} |
| 69 |
\glsxtrprovidestoragekey{nametitle}{}{} |
| 70 |
|
| 71 |
\providecommand{\omicron}{o} |
| 72 |
|
| 73 |
% put break before dash to avoid confusion with a hyphen |
| 74 |
\newcommand{\dhyphen}{% |
| 75 |
\texorpdfstring |
| 76 |
{\discretionary{}{}{}\texttt{-}}% |
| 77 |
{-}% |
| 78 |
} |
| 79 |
|
| 80 |
% Redefine \- (used in entry names) so that hyphenation in command names, |
| 81 |
% switches options etc uses a serif hyphen to reduce confusion with an |
| 82 |
% actual hyphen in the code. |
| 83 |
\renewrobustcmd{\-}{% |
| 84 |
\discretionary |
| 85 |
{{\rmfamily\char\ifnum\hyphenchar\font<0 |
| 86 |
\defaulthyphenchar\else\hyphenchar\font\fi |
| 87 |
}}% |
| 88 |
{}{}% |
| 89 |
} |
| 90 |
|
| 91 |
\newcommand\dash{\,---\,} |
| 92 |
|
| 93 |
\renewcommand{\glsentrycounterlabel}{} |
| 94 |
\renewcommand{\glssubentrycounterlabel}{} |
| 95 |
\renewcommand\glstreeitem{\par\hangindent10pt} |
| 96 |
\renewcommand\glstreesubitem{\par\hangindent30pt\hspace*{15pt}} |
| 97 |
|
| 98 |
\newcommand{\bibglsseealsosep}{\glstreesubitem} |
| 99 |
|
| 100 |
\renewcommand*{\glsseesep}{, \glstreesubitem\quad} |
| 101 |
\renewcommand*{\glsseelastsep}{\glstreesubitem\quad\strut\llap{\andname\space}} |
| 102 |
|
| 103 |
\newcommand{\glsxtrpostnameabbreviation}{% |
| 104 |
\space(\glsentrylong{\glscurrententrylabel})% |
| 105 |
} |
| 106 |
|
| 107 |
\newcommand{\glsxtrpostnameenvironment}{\space environment} |
| 108 |
\newcommand{\glsxtrpostnamecounter}{\space counter} |
| 109 |
|
| 110 |
\newcommand*{\csfmtfont}[1]{\texttt{#1}} |
| 111 |
\newcommand*{\csfmtcolourfont}[1]{\texttt{\textcolor{cs}{#1}}} |
| 112 |
|
| 113 |
\newcommand*{\csfmt}[1]{% |
| 114 |
\texorpdfstring |
| 115 |
{\csfmtfont{\char`\\ #1}}% |
| 116 |
{\string\\#1}% |
| 117 |
} |
| 118 |
|
| 119 |
\newcommand{\texparserdefprefix}{} |
| 120 |
\newcommand{\texparserdefnotetarget}{% |
| 121 |
\raisebox{2ex}{\hypertarget{\texparserdefprefix texparserdef}{}}% |
| 122 |
\textsuperscript{*}Indicates command is |
| 123 |
recognised by \bibgls's interpreter although it may have |
| 124 |
a slightly different implementation. |
| 125 |
} |
| 126 |
\newcommand{\texparserdefnote}{\hyperlink{\texparserdefprefix texparserdef}{*}} |
| 127 |
|
| 128 |
\setabbreviationstyle{long-short-sc} |
| 129 |
\setabbreviationstyle[common]{short-sc-nolong} |
| 130 |
|
| 131 |
\glsxtrprovidestoragekey{unsortedprogeny}{}{} |
| 132 |
|
| 133 |
\newcommand*{\longargfmt}[1]{% |
| 134 |
\texorpdfstring{\texttt{\longswitch #1}}% |
| 135 |
{\string-\string-#1}% |
| 136 |
} |
| 137 |
|
| 138 |
\GlsXtrLoadResources[ |
| 139 |
entry-type-aliases={ |
| 140 |
bibglscommand=dualindexentry, |
| 141 |
mainglscommand=spawndualindexentry, |
| 142 |
glscommand=spawnentry, |
| 143 |
abbrvstylecommand=spawnentry, |
| 144 |
glostylecommand=spawnentry, |
| 145 |
resourceoption=dualindexentry, |
| 146 |
packageoption=dualindexentry, |
| 147 |
field=dualindexentry, |
| 148 |
entrytype=dualindexentry, |
| 149 |
switch=dualindexentry, |
| 150 |
samplefile=dualindexentry, |
| 151 |
examplecommand=dualindexentry, |
| 152 |
examplesymbol=symbol, |
| 153 |
exampleabbreviation=abbreviation, |
| 154 |
exampleentry=entry |
| 155 |
}, |
| 156 |
max-loc-diff={2}, |
| 157 |
see=omit,seealso=omit,alias=omit, |
| 158 |
field-aliases={topics=adoptparents,annote=user2}, |
| 159 |
replicate-fields={name=nametitle,progeny=unsortedprogeny}, |
| 160 |
word-boundaries={white space,cs space,dash}, |
| 161 |
field-case-change={nametitle=title}, |
| 162 |
interpret-fields={nametitle}, |
| 163 |
no-case-change-cs={fieldfmt,abbrstylefmt,glostylefmt}, |
| 164 |
short-case-change={lc}, |
| 165 |
dual-short-case-change={lc}, |
| 166 |
unknown-entry-alias={index}, |
| 167 |
save-original-entrytype, |
| 168 |
label-prefix={idx.}, |
| 169 |
save-loclist=false, |
| 170 |
sort={letternumber-nocase}, |
| 171 |
sort-replace={{\glshex2423}{ },{\string\\([a-zA-Z])}{\glscapturedgroup1}}, |
| 172 |
type={index}, |
| 173 |
dual-field={dualid}, |
| 174 |
match-action={add}, |
| 175 |
match-op={or}, |
| 176 |
match={ |
| 177 |
{category}={.*field}, |
| 178 |
{original entrytype}={.*(gls|style)command}, |
| 179 |
{original entrytype}={.*option}, |
| 180 |
{original entrytype}={abbreviationstyle}, |
| 181 |
{original entrytype}={glossarystyle}, |
| 182 |
}, |
| 183 |
dual-prefix={}, |
| 184 |
dual-type={main}, |
| 185 |
ext-prefixes={}, |
| 186 |
combine-dual-locations={primary}, |
| 187 |
selection={recorded and deps and see not also}, |
| 188 |
symbol-sort-fallback={name}, |
| 189 |
sort-label-list={progeny:letter-nocase:glsxtrentryparentname}, |
| 190 |
strip-missing-parents, |
| 191 |
save-child-count |
| 192 |
] |
| 193 |
|
| 194 |
\newglossary*{terms}{Glossary} |
| 195 |
\GlsXtrLoadResources[src=bib2gls-terms, |
| 196 |
name-case-change=title,replicate-fields={name=text}, |
| 197 |
type=terms,save-locations=false,category=term] |
| 198 |
|
| 199 |
\newcommand{\igls}[2][]{% |
| 200 |
\glsxtrifhasfield{useri}{#2}{\glsadd{\glscurrentfieldvalue}}{}% |
| 201 |
\gls[#1]{#2}% |
| 202 |
} |
| 203 |
\newcommand{\iglspl}[2][]{% |
| 204 |
\glsxtrifhasfield{useri}{#2}{\glsadd{\glscurrentfieldvalue}}{}% |
| 205 |
\glspl[#1]{#2}% |
| 206 |
} |
| 207 |
\newcommand{\primary}{\glsdisp{primaryentry}{primary}} |
| 208 |
\newcommand{\dual}{\glsdisp{dualentry}{dual}} |
| 209 |
\newcommand{\parent}{\glsdisp{parententry}{parent}} |
| 210 |
\newcommand{\child}{\glsdisp{childentry}{child}} |
| 211 |
\newcommand{\children}{\glsdisp{childentry}{children}} |
| 212 |
\newcommand{\hierarchicallevel}{\glsdisp{hierarchicalglossary}{hierarchical level}} |
| 213 |
\newcommand{\hierarchical}{\glsdisp{hierarchicalglossary}{hierarchical}} |
| 214 |
\newcommand{\hierarchically}{\glsdisp{hierarchicalglossary}{hierarchically}} |
| 215 |
\newcommand{\hierarchy}{\glsdisp{hierarchicalglossary}{hierarchy}} |
| 216 |
\newcommand{\mainglossary}{\glsdisp{mainglossary}{\code{main} glossary}} |
| 217 |
\newcommand{\supplementallocation}{\glsdisp{supplementalrecord}{supplemental |
| 218 |
location}} |
| 219 |
\newcommand{\supplementallocations}{\glsdisp{supplementalrecord}{supplemental |
| 220 |
locations}} |
| 221 |
\newcommand{\supplementarylocation}{\glsdisp{supplementalrecord}{supplementary |
| 222 |
location}} |
| 223 |
\newcommand{\supplementarylocations}{\glsdisp{supplementalrecord}{supplementary |
| 224 |
locations}} |
| 225 |
\newcommand{\supplementarydocument}{\glsdisp{supplementaldocument}{supplementary |
| 226 |
document}} |
| 227 |
\newcommand{\supplementarydocuments}{\glsdisp{supplementaldocument}{supplementary |
| 228 |
documents}} |
| 229 |
\newcommand{\supplemental}{\glsdisp{supplementaldocument}{supplemental}} |
| 230 |
\newcommand{\supplementary}{\glsdisp{supplementaldocument}{supplementary}} |
| 231 |
|
| 232 |
\glsxtraddlabelprefix{} |
| 233 |
\glsxtraddlabelprefix{idx.} |
| 234 |
|
| 235 |
\DTMsavetimestamp{creation}{2017-01-20T15:39:00Z} |
| 236 |
|
| 237 |
\IfFileExists{../java/common/BibGlsTeXApp} |
| 238 |
{ |
| 239 |
\DTMsavefilemoddate{moddate}{../java/common/BibGlsTeXApp.java} |
| 240 |
} |
| 241 |
{ |
| 242 |
\DTMsavenow{moddate} |
| 243 |
} |
| 244 |
|
| 245 |
\newif\ifmainmatter |
| 246 |
|
| 247 |
% ignore locations outside of main matter |
| 248 |
\GlsXtrSetDefaultNumberFormat{glsignore} |
| 249 |
|
| 250 |
\GlsXtrSetPlusModifier{format=glsnumberformat} |
| 251 |
\GlsXtrSetAltModifier{!}{format=glsignore} |
| 252 |
|
| 253 |
\newcommand{\frontmatter}{% |
| 254 |
\clearpage\pagenumbering{roman}% |
| 255 |
\pagestyle{scrheadings}% |
| 256 |
\automark[section]{chapter}% |
| 257 |
\mainmatterfalse |
| 258 |
} |
| 259 |
\newcommand{\mainmatter}{% |
| 260 |
\clearpage\pagenumbering{arabic}% |
| 261 |
\GlsXtrSetDefaultNumberFormat{glsnumberformat}% |
| 262 |
\mainmattertrue |
| 263 |
} |
| 264 |
|
| 265 |
\newcommand{\rightleftmark}[2]{\ifstrequal{#1}{#2}{#1}{#1: #2}} |
| 266 |
\makeatletter |
| 267 |
\newcommand{\setsecdepth}{\@ifstar\s@setsecdepth\@setsecdepth} |
| 268 |
\newcommand{\s@setsecdepth}[1]{% |
| 269 |
\setcounter{secnumdepth}{#1}% |
| 270 |
\automark[section]{chapter}% |
| 271 |
\let\@rightmark\rightleftmark |
| 272 |
} |
| 273 |
\newcommand{\@setsecdepth}[1]{% |
| 274 |
\setcounter{secnumdepth}{#1}% |
| 275 |
\ifnum#1 > 0 |
| 276 |
\automark[section]{chapter}% |
| 277 |
\else |
| 278 |
\automark{chapter}% |
| 279 |
\fi |
| 280 |
\let\@rightmark\@secondoftwo |
| 281 |
} |
| 282 |
\makeatother |
| 283 |
|
| 284 |
\newtcolorbox{important}{colback=red!5!white,colframe=red} |
| 285 |
|
| 286 |
\newcommand{\bibgls}{\appfmt{bib2gls}} |
| 287 |
|
| 288 |
\newcommand*{\BibTeX}{\hologo{BibTeX}} |
| 289 |
\newcommand*{\eTeX}{\hologo{eTeX}} |
| 290 |
\newcommand*{\XeLaTeX}{\hologo{XeLaTeX}} |
| 291 |
\newcommand*{\LuaLaTeX}{\hologo{LuaLaTeX}} |
| 292 |
\newcommand*{\pdfLaTeX}{\hologo{pdfLaTeX}} |
| 293 |
|
| 294 |
\newcommand{\langxml}{\hyperref[sec:lang.xml]{language resource file}} |
| 295 |
\newcommand{\texparserlib}{\hyperref[sec:texparserlib]{\TeX\ Parser |
| 296 |
Library}} |
| 297 |
|
| 298 |
\newcommand{\hex}[1]{0x#1} |
| 299 |
\newcommand{\hexsb}[1]{\textsubscript{\scriptsize\rmfamily#1}} |
| 300 |
\newcommand{\subfigfmt}[1]{(\emph{#1})} |
| 301 |
|
| 302 |
\newcommand{\qt}[1]{``#1''} |
| 303 |
|
| 304 |
\newcommand{\qtt}[1]{\qt{\,\texttt{#1}\,}} |
| 305 |
|
| 306 |
\newcommand{\qtdelim}[1]{\idx{doublequotechardelim}#1\idx{doublequotechardelim}} |
| 307 |
|
| 308 |
\newcommand{\ifnumhex}[1]{\cs{ifnum}\idx{doublequotecharhex}#1} |
| 309 |
|
| 310 |
\newcommand{\charhex}[1]{\cs{char}\idx{doublequotecharhex}#1} |
| 311 |
\newcommand{\icharhex}[1]{\ics{char}\idx[format=glsnumberformat,noindex=false]{doublequotecharhex}#1} |
| 312 |
|
| 313 |
\newcommand{\era}[1]{\texorpdfstring{\textsc{\MakeLowercase{#1}}}{#1}} |
| 314 |
|
| 315 |
\newcommand{\dequals}{% |
| 316 |
\texorpdfstring |
| 317 |
{\discretionary{}{}{}\texttt{=}\discretionary{}{}{}}% |
| 318 |
{=}% |
| 319 |
} |
| 320 |
|
| 321 |
\newcommand{\dcomma}{% |
| 322 |
\texorpdfstring |
| 323 |
{\texttt{,}\discretionary{}{}{}}% |
| 324 |
{,}% |
| 325 |
} |
| 326 |
|
| 327 |
\newcommand{\dcolon}{% |
| 328 |
\texorpdfstring |
| 329 |
{\texttt{:}\discretionary{}{}{}}% |
| 330 |
{:}% |
| 331 |
} |
| 332 |
|
| 333 |
\pdfstringdefDisableCommands{% |
| 334 |
\def\dhyphen{-}% |
| 335 |
\def\dcolon{:}% |
| 336 |
\def\dcomma{,}% |
| 337 |
\def\dequals{,}% |
| 338 |
\let\-\empty |
| 339 |
} |
| 340 |
|
| 341 |
% Provide commands that work like \gls[#1]{idx.#2}[#3] |
| 342 |
|
| 343 |
\glsxtrnewglslike{idx.}{\idx}{\idxpl}{\Idx}{\Idxpl} |
| 344 |
\newcommand{\idxlink}[3][]{\glslink[#1]{idx.#2}{#3}} |
| 345 |
|
| 346 |
\newcommand{\stringu}{\idx{cs.string}\gls{uhex}} |
| 347 |
|
| 348 |
\newcommand*{\filefmt}[1]{\texorpdfstring{\texttt{#1}}{#1}} |
| 349 |
\newcommand*{\metafilefmt}[3]{% |
| 350 |
\filefmt{#1}\discretionary{}{}{}\meta{#2}\discretionary{}{}{}\filefmt{#3}% |
| 351 |
} |
| 352 |
\newcommand*{\metametafilefmt}[5]{% |
| 353 |
\filefmt{#1}\discretionary{}{}{}\meta{#2}\discretionary{}{}{}\filefmt{#3}% |
| 354 |
\discretionary{}{}{}\meta{#4}\discretionary{}{}{}\filefmt{#5}% |
| 355 |
} |
| 356 |
|
| 357 |
\newcommand*{\primaryresourcefmt}{% |
| 358 |
\texorpdfstring |
| 359 |
{\texttt{\char`\\ jobname.glstex}}% |
| 360 |
{\string\\jobname.glstex}% |
| 361 |
} |
| 362 |
|
| 363 |
\newcommand*{\suppresourcefmt}[1]{% |
| 364 |
\texorpdfstring |
| 365 |
{\texttt{\char`\\ jobname-#1.glstex}}% |
| 366 |
{\string\\jobname-#1.glstex}% |
| 367 |
} |
| 368 |
|
| 369 |
\definecolor{field}{named}{DarkSlateGray4} |
| 370 |
\definecolor{cs}{named}{DarkSeaGreen4} |
| 371 |
\definecolor{styopt}{named}{DarkOrchid4} |
| 372 |
\definecolor{entry}{named}{SteelBlue4} |
| 373 |
\definecolor{comment}{named}{gray} |
| 374 |
\definecolor{attribute}{named}{Purple4} |
| 375 |
\definecolor{style}{named}{Blue4} |
| 376 |
|
| 377 |
\newcommand{\extstyopt}{\textsuperscript{\textdagger}} |
| 378 |
|
| 379 |
\newcommand*{\appfmt}[1]{\texorpdfstring{\texttt{#1}}{#1}} |
| 380 |
\newcommand*{\styfmt}[1]{\texorpdfstring{\textsf{#1}}{#1}} |
| 381 |
\newcommand*{\envfmt}[1]{\texorpdfstring{\textsf{#1}}{#1}} |
| 382 |
\newcommand*{\optfmt}[1]{\texorpdfstring{\texttt{#1}}{#1}} |
| 383 |
\newcommand*{\csoptfmt}[1]{\texorpdfstring{\textcolor{cs}{\optfmt{#1}}}{#1}} |
| 384 |
\newcommand*{\styoptfmt}[1]{\texorpdfstring{\textcolor{styopt}{\optfmt{#1}}}{#1}} |
| 385 |
\newcommand*{\fieldfmt}[1]{\texorpdfstring{\texttt{\color{field}#1}}{#1}} |
| 386 |
\newcommand*{\entryfmt}[1]{\texorpdfstring{\texttt{\color{entry}#1}}{#1}} |
| 387 |
\newcommand*{\atentryfmt}[1]{\entryfmt{@#1}} |
| 388 |
\newcommand*{\abbrstylefmt}[1]{\texorpdfstring{\textsf{#1}}{#1}} |
| 389 |
\newcommand*{\glostylefmt}[1]{\texorpdfstring{\textsf{#1}}{#1}} |
| 390 |
\newcommand*{\catattrfmt}[1]{\texorpdfstring{\textsf{#1}}{#1}} |
| 391 |
\newcommand*{\counterfmt}[1]{\texorpdfstring{\textsf{#1}}{#1}} |
| 392 |
\newcommand*{\idprefixfmt}[1]{% |
| 393 |
\texorpdfstring{\texttt{#1\spacefactor999 .}}{#1.}} |
| 394 |
\newcommand*{\xmltagfmt}[1]{\texorpdfstring{\texttt{#1}}{#1}} |
| 395 |
|
| 396 |
\newcommand*{\argor}{\texorpdfstring{\protect\textbar}{|}} |
| 397 |
|
| 398 |
\newrobustcmd*{\texmeta}[1]{{\normalfont\normalcolor$\langle$\emph{#1}$\rangle$}} |
| 399 |
|
| 400 |
\newcommand*{\meta}[1]{% |
| 401 |
\texorpdfstring{\ifmmode\text{\texmeta{#1}}\else\texmeta{#1}\fi}{#1}% |
| 402 |
} |
| 403 |
|
| 404 |
\newcommand*{\oarg}[1]{\discretionary{}{}{}[#1]} |
| 405 |
\newcommand*{\oargm}[1]{\oarg{\meta{#1}}} |
| 406 |
|
| 407 |
\newcommand*{\marg}[1]{\texorpdfstring |
| 408 |
{\discretionary{}{}{}\char`\{#1\char`\} }% |
| 409 |
{\{#1\}}% |
| 410 |
} |
| 411 |
|
| 412 |
\newcommand*{\margm}[1]{\marg{\meta{#1}}} |
| 413 |
|
| 414 |
\newcommand*{\file}[1]{% |
| 415 |
\texorpdfstring |
| 416 |
{\idx{file.#1}}% |
| 417 |
{#1}% |
| 418 |
} |
| 419 |
|
| 420 |
\newcommand{\texmfcnffmt}[1]{\texttt{#1}} |
| 421 |
|
| 422 |
\glsxtrnewgls{idx.texmfcnf.}{\texmfcnf} |
| 423 |
|
| 424 |
\newcommand*{\extfmt}[1]{\filefmt{.#1}}% |
| 425 |
|
| 426 |
\glsxtrnewgls[format=glsignore]{idx.ext.}{\ext} |
| 427 |
|
| 428 |
\newcommand*{\iext}[1]{% |
| 429 |
\glsxtrtitleorpdforheading{\idx{ext.#1}}{.#1}{\extfmt{#1}}% |
| 430 |
} |
| 431 |
|
| 432 |
\glsxtrnewgls[format=glsignore]{idx.}{\sty} |
| 433 |
|
| 434 |
\newcommand*{\isty}[1]{% |
| 435 |
\texorpdfstring{\idx[noindex=false]{#1}}{#1}% |
| 436 |
} |
| 437 |
|
| 438 |
\newcommand*{\env}[1]{% |
| 439 |
\texorpdfstring{\idx{env.#1}}{#1}% |
| 440 |
} |
| 441 |
|
| 442 |
\newcommand{\glsxtrpostdescenvironment}{environment} |
| 443 |
|
| 444 |
\newcommand*{\abbrstyle}[1]{% |
| 445 |
\texorpdfstring{\idx{abbrstyle.#1}}{#1}% |
| 446 |
} |
| 447 |
|
| 448 |
\newcommand*{\topicabbrstyle}[1]{% |
| 449 |
%\texorpdfstring{\idx[prefix=topic.]{abbrstyle.#1}}{#1}% |
| 450 |
\texorpdfstring{\idx{abbrstyle.#1}}{#1}% |
| 451 |
} |
| 452 |
|
| 453 |
\newcommand*{\glostyle}[1]{% |
| 454 |
\texorpdfstring{\idx{glostyle.#1}}{#1}% |
| 455 |
} |
| 456 |
|
| 457 |
\newcommand*{\topicglostyle}[1]{% |
| 458 |
%\texorpdfstring{\idx[prefix=topic.]{glostyle.#1}}{#1}% |
| 459 |
\texorpdfstring{\idx{glostyle.#1}}{#1}% |
| 460 |
} |
| 461 |
|
| 462 |
\newcommand*{\iglostyle}[1]{% |
| 463 |
\texorpdfstring{\idx[noindex=false]{glostyle.#1}}{#1}% |
| 464 |
} |
| 465 |
|
| 466 |
\newcommand*{\catattr}[1]{% |
| 467 |
\texorpdfstring{\idx{catattr.#1}}{#1}% |
| 468 |
} |
| 469 |
|
| 470 |
\newcommand*{\counter}[1]{% |
| 471 |
\texorpdfstring{\idx{ctr.#1}}{#1}% |
| 472 |
} |
| 473 |
|
| 474 |
\newcommand{\glsxtrpostdesccounter}{counter} |
| 475 |
|
| 476 |
\newcommand*{\idprefix}[1]{% |
| 477 |
\texorpdfstring{\idx{idprefix.#1}}{#1}% |
| 478 |
} |
| 479 |
|
| 480 |
|
| 481 |
\newcommand*{\styopt}[2][]{% |
| 482 |
\texorpdfstring% |
| 483 |
{% |
| 484 |
\gls{styopt.#2}\styoptfmt{\ifblank{#1}{}{\dequals\marg{#1}}}% |
| 485 |
}% |
| 486 |
{#2\ifblank{#1}{}{=#1}}% |
| 487 |
} |
| 488 |
|
| 489 |
\newcommand*{\istyopt}[2][]{% |
| 490 |
\texorpdfstring% |
| 491 |
{% |
| 492 |
\gls[noindex=false]{styopt.#2}\styoptfmt{\ifblank{#1}{}{\dequals\marg{#1}}}% |
| 493 |
}% |
| 494 |
{#2\ifblank{#1}{}{=#1}}% |
| 495 |
} |
| 496 |
|
| 497 |
\newcommand*{\styoptref}[1]{\gls[format=glsignore]{styopt.#1}} |
| 498 |
|
| 499 |
\newcommand*{\keyval}{% |
| 500 |
\texorpdfstring |
| 501 |
{\meta{key}\dequals \meta{value}}% |
| 502 |
{key=value}% |
| 503 |
} |
| 504 |
|
| 505 |
\newcommand*{\keyvallist}{% |
| 506 |
\texorpdfstring |
| 507 |
{key\dequals value list}% |
| 508 |
{key=value list}% |
| 509 |
} |
| 510 |
|
| 511 |
\newcommand{\cssectioncmd}{\subsection} |
| 512 |
|
| 513 |
\newcommand{\cssection}[2][\cssectioncmd]{% |
| 514 |
#1{\texorpdfstring{\glsxtrglossentry{#2}}{\string\\#2}}% |
| 515 |
} |
| 516 |
|
| 517 |
\newcommand{\nameparen}[1]{ (#1)} |
| 518 |
\newcommand{\prefixedcssection}[3][\cssectioncmd]{% |
| 519 |
{% |
| 520 |
\renewcommand{\nameparen}[1]{}% |
| 521 |
#1{\texorpdfstring{\glsxtrglossentry{#2.#3}}{\string\\#3}}% |
| 522 |
}% |
| 523 |
} |
| 524 |
|
| 525 |
\newcommand{\format}[1]{% |
| 526 |
\gls{#1}\glsentryuseri{#1}% |
| 527 |
} |
| 528 |
|
| 529 |
\newcommand{\formatdef}[1]{% |
| 530 |
\begin{definition}% |
| 531 |
\gls[hyper=false]{#1}\glsentryuseri{#1}% |
| 532 |
\end{definition}\ignorespaces |
| 533 |
} |
| 534 |
|
| 535 |
\newcommand{\nosecformatdef}[1]{% |
| 536 |
\begin{definition} |
| 537 |
\renewcommand{\GlsXtrStandaloneEntryName}[1]{\glstarget{##1}{\strut}\cs{##1}}% |
| 538 |
\glsadd{#1}\glsxtrglossentry{#1}% |
| 539 |
\glsentryuseri{#1}% |
| 540 |
\end{definition}\ignorespaces |
| 541 |
} |
| 542 |
|
| 543 |
\newcommand{\nosecdef}[1]{% |
| 544 |
\begin{flushleft}\ttfamily |
| 545 |
\renewcommand{\GlsXtrStandaloneEntryName}[1]{\glstarget{##1}{\strut}\cs{##1}}% |
| 546 |
\glsadd{#1}\glsxtrglossentry{#1}% |
| 547 |
\glsentryuseri{#1}% |
| 548 |
\end{flushleft}\ignorespaces |
| 549 |
} |
| 550 |
|
| 551 |
\newcommand{\inlinedef}[1]{% |
| 552 |
\code |
| 553 |
{% |
| 554 |
\glsadd{#1}\glsxtrglossentry{#1}% |
| 555 |
\glsentryuseri{#1}% |
| 556 |
}% |
| 557 |
} |
| 558 |
|
| 559 |
\newcommand*{\csref}{\gls} |
| 560 |
|
| 561 |
\newcommand*{\cs}[1]{% |
| 562 |
\glsdoifexists{idx.#1}% |
| 563 |
{\glsdohyperlink{\glolinkprefix cs.idx.#1}{\glsentryname{idx.#1}}}% |
| 564 |
} |
| 565 |
|
| 566 |
\glsxtridentifyglslike{idx.}{\cs} |
| 567 |
|
| 568 |
\newcommand*{\ics}[2][]{\glsadd[#1]{idx.#2}\cs{#2}} |
| 569 |
|
| 570 |
\newcommand*{\csdisp}[2]{% |
| 571 |
\texorpdfstring |
| 572 |
{\glsdohyperlink{\glolinkprefix cs.idx.#1}{\csfmt{#2}}}% |
| 573 |
{\string\\#2}% |
| 574 |
} |
| 575 |
|
| 576 |
\newcommand*{\icsdisp}[3][]{% |
| 577 |
\glsadd[#1]{idx.#2}\glsdohyperlink{\glolinkprefix cs.idx.#2}{\csfmt{#3}}% |
| 578 |
} |
| 579 |
|
| 580 |
\newcommand*{\encapdisp}[2]{% |
| 581 |
\texorpdfstring |
| 582 |
{\glsdohyperlink{\glolinkprefix cs.idx.#1}{\code{#2}}}% |
| 583 |
{#2}% |
| 584 |
} |
| 585 |
|
| 586 |
\glsxtridentifyglslike{idx.}{\ics} |
| 587 |
|
| 588 |
\newcommand*{\icswithargs}[2][]{\glsadd[#1]{idx.#2}\cs{#2}\glsentryuseri{#2}} |
| 589 |
|
| 590 |
\newcommand*{\postdeschook}[1]{% |
| 591 |
\glsdohyperlink{\glolinkprefix cs.idx.glsxtrpostdesccategory}{\csfmt{glsxtrpostdesc#1}}} |
| 592 |
\newcommand*{\postnamehook}[1]{% |
| 593 |
\glsdohyperlink{\glolinkprefix cs.idx.glsxtrpostnamecategory}{\csfmt{glsxtrpostname#1}}} |
| 594 |
\newcommand*{\postlinkhook}[1]{% |
| 595 |
\glsdohyperlink{\glolinkprefix cs.idx.glsxtrpostlinkcategory}{\csfmt{glsxtrpostlink#1}}} |
| 596 |
|
| 597 |
\newcommand*{\encap}[2][]{\glsadd[#1]{idx.#2}% |
| 598 |
{% |
| 599 |
\let\csfmt\code |
| 600 |
\glsdohyperlink{\glolinkprefix cs.idx.#2}{\glsentryname{idx.#2}}% |
| 601 |
}% |
| 602 |
} |
| 603 |
|
| 604 |
\newcommand{\optsection}[2][\subsection]{% |
| 605 |
\glsxtrifhasfield*{useri}{opt.#2}% |
| 606 |
{% |
| 607 |
#1[\texorpdfstring |
| 608 |
{\glsxtrheadname{opt.#2}\csoptfmt{=\glscurrentfieldvalue}}% |
| 609 |
{\glsentryname{opt.#2}=\glscurrentfieldvalue}] |
| 610 |
{\glsadd{opt.#2}\glsxtrglossentry{opt.#2}% |
| 611 |
\csoptfmt{=\glscurrentfieldvalue}% |
| 612 |
}% |
| 613 |
}% |
| 614 |
{% |
| 615 |
#1[\texorpdfstring{\glsxtrheadname{opt.#2}}{\glsentryname{opt.#2}}] |
| 616 |
{\glsadd{opt.#2}\glsxtrglossentry{opt.#2}}% |
| 617 |
}% |
| 618 |
} |
| 619 |
|
| 620 |
\glsxtrnewgls{file.}{\exfile} |
| 621 |
|
| 622 |
\newcommand{\filesection}[2][\section]{% |
| 623 |
#1[\texorpdfstring{\glsxtrheadname{file.#2}}{\glsentryname{file.#2}}] |
| 624 |
{\glsadd{file.#2}\glsxtrglossentry{file.#2}}% |
| 625 |
} |
| 626 |
|
| 627 |
\newcommand*{\csopt}[2][]{\gencsopt{#1}{opt}{#2}}% |
| 628 |
\newcommand*{\glsopt}[2][]{\gencsopt{#1}{idx.gls}{#2}}% |
| 629 |
\newcommand*{\glsaddopt}[2][]{\gencsopt{#1}{idx.glsadd}{#2}}% |
| 630 |
\newcommand*{\printglossopt}[2][]{\gencsopt{#1}{idx.printgloss}{#2}}% |
| 631 |
\newcommand*{\iprintglossopt}[2][]{\glsadd{idx.printgloss.#2}\gencsopt{#1}{idx.printgloss}{#2}}% |
| 632 |
|
| 633 |
\newcommand*{\gencsopt}[3]{% |
| 634 |
\texorpdfstring% |
| 635 |
{% |
| 636 |
\gls{#2.#3}% |
| 637 |
\csoptfmt{\ifblank{#1}{}{\dequals\marg{#1}}}% |
| 638 |
}% |
| 639 |
{#3\ifblank{#1}{}{=#1}}% |
| 640 |
} |
| 641 |
|
| 642 |
\newcommand*{\field}[1]{% |
| 643 |
\texorpdfstring |
| 644 |
{\gls{field.#1}}% |
| 645 |
{#1}% |
| 646 |
} |
| 647 |
|
| 648 |
\newcommand*{\fielddisp}[2]{% |
| 649 |
\texorpdfstring |
| 650 |
{\glsdisp{field.#1}{\fieldfmt{#2}}}% |
| 651 |
{#2}% |
| 652 |
} |
| 653 |
|
| 654 |
\newcommand*{\fielddef}[1]{% |
| 655 |
\glsadd{field.#1}% |
| 656 |
\glsxtrglossentry{field.#1}{}% |
| 657 |
} |
| 658 |
|
| 659 |
\newcommand*{\fieldref}[1]{\gls[format=glsignore]{field.#1}} |
| 660 |
|
| 661 |
\newglossarystyle{fieldstyle}{% |
| 662 |
\renewenvironment{theglossary}% |
| 663 |
{% |
| 664 |
\setlength{\glsdescwidth}{\dimexpr\linewidth-\maxnamewidth-4\tabcolsep}% |
| 665 |
\begin{longtable}{l>{\raggedright}p{\glsdescwidth}}% |
| 666 |
}% |
| 667 |
{\end{longtable}}% |
| 668 |
\renewcommand*{\glossaryheader}{% |
| 669 |
\noalign{\xdef\dofieldtabcaption{% |
| 670 |
\noexpand\caption\expandonce\fieldtablelotcaption |
| 671 |
{\expandonce\fieldtablecaption}}}% |
| 672 |
\dofieldtabcaption |
| 673 |
\fieldtablecaptionlabel |
| 674 |
\fieldtablepostcaption\tabularnewline |
| 675 |
\bfseries Field & \bfseries Description\tabularnewline |
| 676 |
\endfirsthead |
| 677 |
\caption*{\fieldtablecaption\ (Continued)}\tabularnewline |
| 678 |
\bfseries Field & \bfseries Description\tabularnewline |
| 679 |
\endhead |
| 680 |
}% |
| 681 |
\renewcommand*{\glsgroupheading}[1]{}% |
| 682 |
\renewcommand{\glossentry}[2]{% |
| 683 |
\glsadd{##1}% |
| 684 |
\glsentryitem{##1}\glstarget{##1}{\glossentryname{##1}} & |
| 685 |
\glossentrydesc{##1}\tabularnewline |
| 686 |
}% |
| 687 |
\renewcommand{\subglossentry}[3]{\glossentry{##2}{##3}}% |
| 688 |
\renewcommand*{\glsgroupskip}{}% |
| 689 |
} |
| 690 |
|
| 691 |
\newcommand*{\fieldhook}[1]{% |
| 692 |
\edef\currentcategory{\glscategory{#1}}% |
| 693 |
\glsxtriflabelinlist{\currentcategory}{\fieldcategories}% |
| 694 |
{% |
| 695 |
\settowidth{\dimen0}{\glsentryname{#1}}% |
| 696 |
\ifdim\dimen0>\maxnamewidth \setlength{\maxnamewidth}{\dimen0}\fi |
| 697 |
}% |
| 698 |
{\printunsrtglossaryskipentry}% |
| 699 |
} |
| 700 |
|
| 701 |
\newlength\maxnamewidth |
| 702 |
|
| 703 |
%\printfields[postcaption]{category list}[lot caption]{caption}{label} |
| 704 |
\newcommand*{\printfields}[2][]{% |
| 705 |
\ifstrempty{#1}% |
| 706 |
{% |
| 707 |
\def\fieldtablepostcaption{}% |
| 708 |
}% |
| 709 |
{% |
| 710 |
\def\fieldtablepostcaption{% |
| 711 |
\tabularnewline |
| 712 |
\multicolumn{2}{p{\linewidth}}{#1}% |
| 713 |
\tabularnewline |
| 714 |
}% |
| 715 |
}% |
| 716 |
\def\fieldcategories{#2}% |
| 717 |
\innerprintfields |
| 718 |
} |
| 719 |
|
| 720 |
\newcommand*{\innerprintfields}[3][]{% |
| 721 |
\printunsrtglossary*[style=fieldstyle]{% |
| 722 |
\renewcommand*\glossarysection[2][]{}% |
| 723 |
\ifstrempty{#1}% |
| 724 |
{% |
| 725 |
\def\fieldtablelotcaption{}% |
| 726 |
}% |
| 727 |
{% |
| 728 |
\def\fieldtablelotcaption{[#1]}% |
| 729 |
}% |
| 730 |
\def\fieldtablecaption{#2}% |
| 731 |
\def\fieldtablecaptionlabel{\label{#3}}% |
| 732 |
\setlength{\maxnamewidth}{0pt}% |
| 733 |
\let\printunsrtglossaryentryprocesshook\fieldhook |
| 734 |
}% |
| 735 |
} |
| 736 |
|
| 737 |
\renewcommand*{\glsxtrbookindexname}[1]{% |
| 738 |
\glsxtrifhasfield{dualid}{#1}% |
| 739 |
{% |
| 740 |
\glshyperlink[\glossentryname{#1}]{\glscurrentfieldvalue}% |
| 741 |
} |
| 742 |
{% |
| 743 |
\GlsXtrIfFieldEqStr{category}{#1}{command}% |
| 744 |
{\glsdohyperlink{\glolinkprefix cs.#1}{\glossentryname{#1}}}% |
| 745 |
{\glossentryname{#1}}% |
| 746 |
}% |
| 747 |
} |
| 748 |
|
| 749 |
\newcommand{\summarysubheaderfont}[1]{\textbf{\sffamily #1}} |
| 750 |
|
| 751 |
\newcommand{\summaryoptionhandler}[1]{% |
| 752 |
\par\smallskip\nopagebreak |
| 753 |
\par\noindent\hspace{1em}% |
| 754 |
\code{\gls{#1}\glsxtrifhasfield{useri}{#1}{=\glscurrentfieldvalue}{}}% |
| 755 |
\glsxtrifhasfield{note}{#1}% |
| 756 |
{\nolinebreak\hfill\mbox{\footnotesize\glscurrentfieldvalue}}% |
| 757 |
{}% |
| 758 |
\nopagebreak\par\hangindent2em\noindent\hspace{2em}\Glossentrydesc{#1}% |
| 759 |
} |
| 760 |
|
| 761 |
\newrobustcmd{\donote}[1]{% |
| 762 |
\glsxtrifhasfield{note}{#1}% |
| 763 |
{\nolinebreak\hfill\mbox{\normalfont\footnotesize\glscurrentfieldvalue}}% |
| 764 |
{}% |
| 765 |
} |
| 766 |
|
| 767 |
\newglossarystyle{commandsummary}% |
| 768 |
{% |
| 769 |
\setglossarystyle{index}% |
| 770 |
\renewcommand*{\glossaryheader}{\raggedright}% |
| 771 |
\renewcommand*{\glsgroupheading}[1]{% |
| 772 |
\glsxtrgetgrouptitle{##1}{\thisgrptitle}% |
| 773 |
\glsxtrbookindexbookmark{\thisgrptitle}{summary.##1}% |
| 774 |
\glsxtrbookindexformatheader{\thisgrptitle}% |
| 775 |
\nopagebreak\indexspace\nopagebreak\csuse{@afterheading}% |
| 776 |
}% |
| 777 |
\renewcommand*{\glossentry}[2]{% |
| 778 |
\glstreeitem \glstarget{cs.##1}{\strut}% |
| 779 |
\glsxtrifhasfield{dualid}{##1}% |
| 780 |
{% |
| 781 |
{% |
| 782 |
\let\csfmtfont\csfmtcolourfont |
| 783 |
\glshyperlink{\glscurrentfieldvalue}% |
| 784 |
}% |
| 785 |
\glsxtrifhasfield{useri}{##1}{\glscurrentfieldvalue}{}% |
| 786 |
\donote{##1}% |
| 787 |
\nopagebreak\par\hspace{10pt}% |
| 788 |
\Glossentrydesc{\glscurrentfieldvalue}% |
| 789 |
\ifglshasdesc{\glscurrentfieldvalue}{\@. }{}% |
| 790 |
}% |
| 791 |
{% |
| 792 |
{\let\csfmtfont\csfmtcolourfont\gls[hyper=false]{##1}}% |
| 793 |
\glsxtrifhasfield{useri}{##1}{\glscurrentfieldvalue}{}% |
| 794 |
\donote{##1}% |
| 795 |
\nopagebreak\par\hspace{10pt}% |
| 796 |
\Glossentrydesc{##1}% |
| 797 |
\ifglshasdesc{##1}{\@. }{}% |
| 798 |
}% |
| 799 |
\GlsXtrIfFieldEqStr{originalentrytype}{##1}{glscommand}% |
| 800 |
{% |
| 801 |
% Does this entry have options? |
| 802 |
\GlsXtrIfHasNonZeroChildCount{##1}% |
| 803 |
{% |
| 804 |
\glspar\medskip\glspar |
| 805 |
\summarysubheaderfont{Options:} |
| 806 |
\glsxtrfieldforlistloop{##1}{childlist}{\summaryoptionhandler}% |
| 807 |
}% |
| 808 |
{}% |
| 809 |
}% |
| 810 |
{% |
| 811 |
\GlsXtrIfHasNonZeroChildCount{##1}% |
| 812 |
{This command has \glscurrentfieldvalue\ forms:}{}% |
| 813 |
}% |
| 814 |
%\listtopics{##1}% |
| 815 |
\par\medskip |
| 816 |
}% |
| 817 |
\renewcommand*{\subglossentry}[3]{% |
| 818 |
\glstreesubitem \glstarget{cs.##2}{\strut}% |
| 819 |
\glsxtrifhasfield{dualid}{##2}% |
| 820 |
{% |
| 821 |
{% |
| 822 |
\let\csfmtfont\csfmtcolourfont |
| 823 |
\glshyperlink{\glscurrentfieldvalue}% |
| 824 |
}% |
| 825 |
\glsxtrifhasfield{useri}{##2}{\glscurrentfieldvalue}{}% |
| 826 |
\donote{##2}% |
| 827 |
\nopagebreak\par\hspace{20pt}% |
| 828 |
\ifglshasdesc{\glscurrentfieldvalue}% |
| 829 |
{\Glossentrydesc{\glscurrentfieldvalue}.}{}% |
| 830 |
}% |
| 831 |
{% |
| 832 |
{\let\csfmtfont\csfmtcolourfont\gls[hyper=false]{##2}}% |
| 833 |
\glsxtrifhasfield{useri}{##2}{\glscurrentfieldvalue}{}% |
| 834 |
\donote{##2}% |
| 835 |
\nopagebreak\par\hspace{20pt}% |
| 836 |
\ifglshasdesc{##2}{\Glossentrydesc{##2}.}{}% |
| 837 |
}% |
| 838 |
\par\medskip |
| 839 |
}% |
| 840 |
} |
| 841 |
|
| 842 |
\newcommand*{\commandsummaryhook}[1]{% |
| 843 |
\edef\currentcategory{\glscategory{#1}}% |
| 844 |
\ifdefstring{\currentcategory}{command}% |
| 845 |
{% |
| 846 |
\glsxtrifhasfield*{progenitor}{#1}% |
| 847 |
{\printunsrtglossaryskipentry}{}% |
| 848 |
}% |
| 849 |
{\printunsrtglossaryskipentry}% |
| 850 |
} |
| 851 |
|
| 852 |
\newcommand*{\printcommandsummary}{% |
| 853 |
\printunsrtglossary*[type=index, |
| 854 |
style=commandsummary, |
| 855 |
title={General Command Summary}, |
| 856 |
]% |
| 857 |
{% |
| 858 |
\def\glossarypreamble{This is an alphabetical summary of |
| 859 |
commands referenced in this document. See the |
| 860 |
relevent user guides for further details.\endgraf\medskip |
| 861 |
\texparserdefnotetarget}% |
| 862 |
\let\printunsrtglossaryentryprocesshook\commandsummaryhook |
| 863 |
\let\csref\cs |
| 864 |
\glsxtrlocalsetgrouptitle{glssymbols}{}% |
| 865 |
}% |
| 866 |
} |
| 867 |
|
| 868 |
\newcommand{\topicxrhandler}[1]{% |
| 869 |
\glsxtrifhasfield{parent}{#1}% |
| 870 |
{% |
| 871 |
\let\field\fieldfmt |
| 872 |
\hyperlink |
| 873 |
{topic.\glscurrentfieldvalue}% |
| 874 |
{\glsentryname{\glscurrentfieldvalue}}% |
| 875 |
}% |
| 876 |
{% |
| 877 |
\hyperlink{topic.#1}{\glsentryname{#1}}% |
| 878 |
}% |
| 879 |
} |
| 880 |
|
| 881 |
% \iffirstprogeny{entry label}{topic label}{true}{false} |
| 882 |
\makeatletter |
| 883 |
\newcommand{\iffirstprogeny}[2]{% |
| 884 |
\let\doiffirstprogeny\@secondoftwo |
| 885 |
\def\firstprogeny{}% |
| 886 |
\glsxtrifhasfield*{unsortedprogeny}{#1}% |
| 887 |
{% |
| 888 |
\edef\suppliedprogeny{#2}% |
| 889 |
\@for\thisprogeny:=\glscurrentfieldvalue\do{% |
| 890 |
\let\firstprogeny\thisprogeny |
| 891 |
\ifdefequal{\thisprogeny}{\suppliedprogeny}% |
| 892 |
{\let\doiffirstprogeny\@firstoftwo}% |
| 893 |
{\let\doiffirstprogeny\@secondoftwo}% |
| 894 |
\@endfortrue |
| 895 |
}% |
| 896 |
}% |
| 897 |
{}% |
| 898 |
\doiffirstprogeny |
| 899 |
} |
| 900 |
\makeatother |
| 901 |
|
| 902 |
\newcommand{\ifstylecommand}[1]{% |
| 903 |
\letcs\doifstylecommand{@firstoftwo}% |
| 904 |
\GlsXtrIfFieldEqStr{originalentrytype}{#1}{abbrvstylecommand}% |
| 905 |
{}% |
| 906 |
{% |
| 907 |
\GlsXtrIfFieldEqStr{originalentrytype}{#1}{glostylecommand}% |
| 908 |
{}% |
| 909 |
{\global\letcs\doifstylecommand{@secondoftwo}}% |
| 910 |
}% |
| 911 |
\doifstylecommand |
| 912 |
} |
| 913 |
|
| 914 |
\newcommand{\listtopics}[1]{% |
| 915 |
\glsxtrifhasfield{progeny}{#1}% |
| 916 |
{% |
| 917 |
\ifdefequal\glscurrentfieldvalue\glscurrententrylabel |
| 918 |
{}% |
| 919 |
{% |
| 920 |
\par\nopagebreak\medskip\par\footnotesize |
| 921 |
\sloppy |
| 922 |
\ifstylecommand{#1}% |
| 923 |
{\summarysubheaderfont{Styles:}}% |
| 924 |
{\summarysubheaderfont{Topics:}}% |
| 925 |
\space |
| 926 |
\let\DTLlistformatitem\topicxrhandler |
| 927 |
\DTLformatlist{\glscurrentfieldvalue}.\par |
| 928 |
}% |
| 929 |
}% |
| 930 |
{}% |
| 931 |
} |
| 932 |
|
| 933 |
\newglossarystyle{commandtopic}% |
| 934 |
{% |
| 935 |
\setglossarystyle{index}% |
| 936 |
%\renewcommand*{\glossaryheader}{\raggedright}% |
| 937 |
\renewcommand*{\glsgroupheading}[1]{}% |
| 938 |
\renewcommand*{\glossentry}[2]{% |
| 939 |
\glsfieldfetch{##1}{nametitle}{\thisvalue}% |
| 940 |
\section*{% |
| 941 |
\raisebox{2ex}% |
| 942 |
{\pdfbookmark[1]{\thisvalue}{topic.##1}\hypertarget{topic.##1}{}}% |
| 943 |
\glsdisp{##1}{\thisvalue}\donote{##1}% |
| 944 |
}% |
| 945 |
\expandafter\sectionmark\expandafter{\thisvalue}% |
| 946 |
\ifglshasdesc{##1}{\Glossentrydesc{##1}.}{}% |
| 947 |
\glsxtrifhasfield{seealso}{##1}% |
| 948 |
{% |
| 949 |
\par\smallskip |
| 950 |
\emph{See also:} |
| 951 |
\let\DTLlistformatitem\topicxrhandler |
| 952 |
\DTLformatlist{\glscurrentfieldvalue}.% |
| 953 |
\par\medskip\par |
| 954 |
}% |
| 955 |
{}% |
| 956 |
}% |
| 957 |
\renewcommand*{\subglossentry}[3]{% |
| 958 |
\glsifcategory{##2}{command}% |
| 959 |
{% |
| 960 |
\glsdohypertarget{topic.##2}{\strut}% |
| 961 |
\glsxtrifhasfield*{progenitor}{##2}% |
| 962 |
{\let\originallabel\glscurrentfieldvalue}% |
| 963 |
{\def\originallabel{##2}}% |
| 964 |
% |
| 965 |
\ifstylecommand{##2}% |
| 966 |
{% |
| 967 |
\iffirstprogeny{\originallabel}{##2}% |
| 968 |
{\letcs\dothisentry{@firstofone}}% |
| 969 |
{% |
| 970 |
\glspar |
| 971 |
\ifdefempty\firstprogeny |
| 972 |
{% |
| 973 |
{\let\csfmtfont\csfmtcolourfont\gls[noindex]{\originallabel}}% |
| 974 |
\glsxtrifhasfield{useri}{##2}{\glscurrentfieldvalue}{}% |
| 975 |
}% |
| 976 |
{% |
| 977 |
{\let\csfmtfont\csfmtcolourfont |
| 978 |
\hyperlink{topic.\firstprogeny}{\glsentryname{\firstprogeny}}}% |
| 979 |
\glsxtrifhasfield{useri}{##2}{\glscurrentfieldvalue}{}% |
| 980 |
\glsxtrifhasfield{parent}{\firstprogeny}% |
| 981 |
{\hfill |
| 982 |
{\footnotesize\emph{see} \hyperlink{topic.\glscurrentfieldvalue}% |
| 983 |
{\glsentryname{\glscurrentfieldvalue}}.}} |
| 984 |
{}% |
| 985 |
}% |
| 986 |
\letcs\dothisentry{@gobble}% |
| 987 |
}% |
| 988 |
}% |
| 989 |
{\letcs\dothisentry{@firstofone}}% |
| 990 |
\dothisentry |
| 991 |
{% |
| 992 |
\par\smallskip\par |
| 993 |
% hyperlink to index: |
| 994 |
{\let\csfmtfont\csfmtcolourfont\gls[format=glsignore]{\originallabel}}% |
| 995 |
\glsxtrifhasfield{useri}{##2}{\glscurrentfieldvalue}{}% |
| 996 |
\glsxtrifhasfield{note}{##2}% |
| 997 |
{\nolinebreak\hfill\mbox{\footnotesize\glscurrentfieldvalue}}% |
| 998 |
{}% |
| 999 |
\nopagebreak\par\smallskip\par\nopagebreak |
| 1000 |
\ifglshasdesc{##2}{\Glossentrydesc{##2}.}{}% |
| 1001 |
% Topics |
| 1002 |
\listtopics\originallabel |
| 1003 |
\par\smallskip |
| 1004 |
}% |
| 1005 |
}% |
| 1006 |
{% |
| 1007 |
\glsfieldfetch{##2}{nametitle}{\thisvalue}% |
| 1008 |
\subsection*{% |
| 1009 |
\raisebox{2ex}% |
| 1010 |
{\hypertarget{topic.##2}{}\pdfbookmark[2]{\thisvalue}{topic.##2}}% |
| 1011 |
\glsdisp{##2}{\thisvalue}\donote{##2}% |
| 1012 |
}% |
| 1013 |
\expandafter\subsectionmark\expandafter{\thisvalue}% |
| 1014 |
\ifglshasdesc{##2}{\Glossentrydesc{##2}.\glspar\nopagebreak\smallskip}{}% |
| 1015 |
}% |
| 1016 |
}% |
| 1017 |
} |
| 1018 |
|
| 1019 |
\newcommand*{\commandtopichook}[1]{% |
| 1020 |
\glsxtrifhasfield*{progenitor}{#1}% |
| 1021 |
{}% |
| 1022 |
{% |
| 1023 |
\GlsXtrIfFieldEqStr*{originalentrytype}{#1}{topic}% |
| 1024 |
{}% |
| 1025 |
{% |
| 1026 |
\glsxtrifhasfield*{parent}{#1}% |
| 1027 |
{% |
| 1028 |
\GlsXtrIfFieldEqStr*{originalentrytype}{\glscurrentfieldvalue}{topic}% |
| 1029 |
{}% |
| 1030 |
{\printunsrtglossaryskipentry}% |
| 1031 |
}% |
| 1032 |
{\printunsrtglossaryskipentry}% |
| 1033 |
}% |
| 1034 |
}% |
| 1035 |
} |
| 1036 |
|
| 1037 |
\newcommand*{\printcommandtopic}{% |
| 1038 |
\setsecdepth*{0}% |
| 1039 |
\automark[subsection]{section}% |
| 1040 |
\printunsrtglossary*[type=index, |
| 1041 |
style=commandtopic, |
| 1042 |
title={Summary by Topic of Glossary Commands}, |
| 1043 |
label={sec:topics}, |
| 1044 |
nogroupskip, |
| 1045 |
nonumberlist |
| 1046 |
]% |
| 1047 |
{% |
| 1048 |
\def\texparserdefprefix{topic.}% |
| 1049 |
\def\glossarypreamble{This is a summary of commands provided |
| 1050 |
by \styfmt{glossaries}, \styfmt{glossaries-extra} and |
| 1051 |
their supplementary packages that may be useful to |
| 1052 |
\bibgls\ users. Commands specific to other indexing methods |
| 1053 |
aren't listed unless they've been referenced in this manual. |
| 1054 |
See the appropriate user guides for further details. |
| 1055 |
\endgraf\medskip |
| 1056 |
\texparserdefnotetarget}% |
| 1057 |
\let\abbrstyle\topicabbrstyle |
| 1058 |
\let\glostyle\topicglostyle |
| 1059 |
\let\printunsrtglossaryentryprocesshook\commandtopichook |
| 1060 |
\let\csref\cs |
| 1061 |
}% |
| 1062 |
\setsecdepth{0}% |
| 1063 |
} |
| 1064 |
|
| 1065 |
\newglossarystyle{styoptsummary}% |
| 1066 |
{% |
| 1067 |
\setglossarystyle{mcolindex}% |
| 1068 |
\renewcommand{\glossarypreamble}{% |
| 1069 |
Most options are in the form \meta{option}=\meta{value} and |
| 1070 |
may have a default if \meta{value} is omitted, |
| 1071 |
but some options don't have values and should not have |
| 1072 |
one assigned. For boolean options, |
| 1073 |
if the value is omitted \styoptfmt{true} is assumed. |
| 1074 |
\extstyopt Indicates a value that's only provided by |
| 1075 |
\styfmt{glossaries-extra} and not by the base |
| 1076 |
\styfmt{glossaries} package. \par |
| 1077 |
}% |
| 1078 |
\renewcommand*{\glossaryheader}{}% |
| 1079 |
\renewcommand*{\glsgroupheading}[1]{% |
| 1080 |
\glsxtrgetgrouptitle{##1}{\thisgrptitle}% |
| 1081 |
\glsxtrbookindexbookmark{\thisgrptitle}{styopt.##1}% |
| 1082 |
\glsxtrbookindexformatheader{\thisgrptitle}% |
| 1083 |
\nopagebreak\indexspace\nopagebreak\csuse{@afterheading}% |
| 1084 |
}% |
| 1085 |
\renewcommand*{\glossentry}[2]{% |
| 1086 |
\item \glstarget{##1}{\strut}% |
| 1087 |
\glsxtrifhasfield{dualid}{##1}% |
| 1088 |
{% |
| 1089 |
\gls{\glscurrentfieldvalue}% |
| 1090 |
}% |
| 1091 |
{% |
| 1092 |
\gls[hyper=false]{##1}% |
| 1093 |
}% |
| 1094 |
\glsxtrifhasfield{useri}{##1}{=\glscurrentfieldvalue}{}% |
| 1095 |
\nopagebreak\par\hspace{10pt}% |
| 1096 |
\Glossentrydesc{##1}.% |
| 1097 |
\glsxtrifhasfield{package}{##1}% |
| 1098 |
{\nopagebreak\par \ding{43}Provided by |
| 1099 |
\ifdefstring{\glscurrentfieldvalue}{glossaries,glossaries-extra} |
| 1100 |
{\styfmt{glossaries} and modified by \styfmt{glossaries-extra}}% |
| 1101 |
{\styfmt{\glscurrentfieldvalue}}.}% |
| 1102 |
{}% |
| 1103 |
\glsxtrifhasfield{note}{##1}% |
| 1104 |
{\space \xmakefirstuc{\glscurrentfieldvalue}.}% |
| 1105 |
{}% |
| 1106 |
\par\medskip |
| 1107 |
}% |
| 1108 |
} |
| 1109 |
|
| 1110 |
\newcommand*{\styoptsummaryhook}[1]{% |
| 1111 |
\edef\currentcategory{\glscategory{#1}}% |
| 1112 |
\ifdefstring{\currentcategory}{packageoption}% |
| 1113 |
{}% |
| 1114 |
{\printunsrtglossaryskipentry}% |
| 1115 |
} |
| 1116 |
|
| 1117 |
\newcommand*{\printstyoptsummary}{% |
| 1118 |
\printunsrtglossary*[type=main, |
| 1119 |
style=styoptsummary, |
| 1120 |
title={Package Option Summary} |
| 1121 |
]% |
| 1122 |
{% |
| 1123 |
\let\printunsrtglossaryentryprocesshook\styoptsummaryhook |
| 1124 |
\glsxtrlocalsetgrouptitle{glssymbols}{@}% |
| 1125 |
}% |
| 1126 |
} |
| 1127 |
|
| 1128 |
\newcommand{\entrysection}[2][\subsection]{% |
| 1129 |
#1[\texorpdfstring{\glsxtrheadname{entry.#2}}{\glsentryname{entry.#2}}] |
| 1130 |
{\glsadd{entry.#2}\glsxtrglossentry{entry.#2}}% |
| 1131 |
} |
| 1132 |
|
| 1133 |
\newcommand{\entrydef}[1]{\glsadd{entry.#1}\glsxtrglossentry{entry.#1}} |
| 1134 |
|
| 1135 |
\newcommand*{\atentry}[2][]{% |
| 1136 |
\texorpdfstring |
| 1137 |
{\gls[#1]{entry.#2}}% |
| 1138 |
{#2}% |
| 1139 |
} |
| 1140 |
|
| 1141 |
\newcommand*{\atentrypageref}[1]{% |
| 1142 |
\atentry{#1} (page~\glsxtrpageref{entry.#1})}% |
| 1143 |
|
| 1144 |
\newcommand*{\atentryref}[1]{\gls[format=glsignore]{entry.#1}} |
| 1145 |
|
| 1146 |
\newcommand*{\entryref}[1]{\glslink[format=glsignore]{entry.#1}{\entryfmt{#1}}} |
| 1147 |
|
| 1148 |
\newcommand{\commonarg}[2][\subsection]{\argsection[#1]{common.#2}} |
| 1149 |
|
| 1150 |
\newcommand{\converterarg}[2][\subsection]{\argsection[#1]{converter.#2}} |
| 1151 |
|
| 1152 |
\newcommand{\convertglsbibarg}[2][\subsubsection]{\argsection[#1]{gls2bib.#2}} |
| 1153 |
|
| 1154 |
\newcommand{\datatoolbibarg}[2][\subsubsection]{\argsection[#1]{datatool2bib.#2}} |
| 1155 |
|
| 1156 |
\newcommand{\argsection}[2][\subsection]{% |
| 1157 |
\def\switcharg{}% |
| 1158 |
\def\switchalt{}% |
| 1159 |
\def\switchaltpdf{}% |
| 1160 |
\glsxtrifhasfield*{useri}{switch.#2}% |
| 1161 |
{% |
| 1162 |
\edef\switcharg{ \expandonce\glscurrentfieldvalue}% |
| 1163 |
}% |
| 1164 |
{}% |
| 1165 |
\ifglshassymbol{switch.#2}% |
| 1166 |
{% |
| 1167 |
\def\switchalt{ (or \protect\glsentrysymbol{switch.#2}\switcharg)}% |
| 1168 |
}% |
| 1169 |
{}% |
| 1170 |
#1[\texorpdfstring |
| 1171 |
{\glsxtrheadname{switch.#2}}% |
| 1172 |
{\glsentryname{switch.#2}}% |
| 1173 |
\switcharg\switchalt |
| 1174 |
] |
| 1175 |
{\glsadd{switch.#2}% |
| 1176 |
\glsxtrglossentry{switch.#2}\switcharg\switchalt}% |
| 1177 |
} |
| 1178 |
|
| 1179 |
\newrobustcmd{\longswitch}{\string-{}\string-} |
| 1180 |
|
| 1181 |
\newcommand*{\shortargfmt}[1]{% |
| 1182 |
\texorpdfstring{\texttt{\string-#1}}% |
| 1183 |
{\string-#1}% |
| 1184 |
} |
| 1185 |
|
| 1186 |
\newcommand*{\longarg}[1]{% |
| 1187 |
\texorpdfstring |
| 1188 |
{\gls{switch.#1}}% |
| 1189 |
{\string-\string-#1}% |
| 1190 |
} |
| 1191 |
|
| 1192 |
\newcommand*{\commonlongarg}[1]{% |
| 1193 |
\texorpdfstring |
| 1194 |
{\gls{switch.common.#1}}% |
| 1195 |
{\string-\string-#1}% |
| 1196 |
} |
| 1197 |
|
| 1198 |
\newcommand*{\converterlongarg}[1]{% |
| 1199 |
\texorpdfstring |
| 1200 |
{\gls{switch.converter.#1}}% |
| 1201 |
{\string-\string-#1}% |
| 1202 |
} |
| 1203 |
|
| 1204 |
\newcommand*{\convertglsbiblongarg}[1]{% |
| 1205 |
\texorpdfstring |
| 1206 |
{\gls{switch.gls2bib.#1}}% |
| 1207 |
{\string-\string-#1}% |
| 1208 |
} |
| 1209 |
|
| 1210 |
\newcommand*{\datatoolbiblongarg}[1]{% |
| 1211 |
\texorpdfstring |
| 1212 |
{\gls{switch.datatool2bib.#1}}% |
| 1213 |
{\string-\string-#1}% |
| 1214 |
} |
| 1215 |
|
| 1216 |
\newcommand*{\longargpageref}[1]{% |
| 1217 |
\longarg{#1} (page~\glsxtrpageref{switch.#1})}% |
| 1218 |
|
| 1219 |
\newcommand*{\longargorshort}[1]{% |
| 1220 |
\texorpdfstring |
| 1221 |
{\gls{switch.#1}\ifglshassymbol{switch.#1}{ or \glssymbol{switch.#1}}{}}% |
| 1222 |
{\string-\string-#1}% |
| 1223 |
} |
| 1224 |
|
| 1225 |
\newcommand*{\unicodecategoryfmt}[1]{\qt{\textsf{#1}}} |
| 1226 |
|
| 1227 |
\definecolor{defbackground}{rgb}{1,1,0.75} |
| 1228 |
\newsavebox\defsbox |
| 1229 |
\newlength\defwidth |
| 1230 |
|
| 1231 |
\newenvironment{definition}% |
| 1232 |
{% |
| 1233 |
\setlength{\fboxsep}{4pt}\setlength{\fboxrule}{1.25pt}% |
| 1234 |
\begin{lrbox}{\defsbox}% |
| 1235 |
\setlength\defwidth\linewidth |
| 1236 |
\addtolength\defwidth{-2\fboxrule}% |
| 1237 |
\addtolength\defwidth{-2\fboxsep}% |
| 1238 |
\begin{minipage}{\defwidth} |
| 1239 |
\flushleft\ttfamily\ignorespaces |
| 1240 |
}% |
| 1241 |
{% |
| 1242 |
\end{minipage}% |
| 1243 |
\end{lrbox}\par\medskip\noindent |
| 1244 |
\fcolorbox{black}{defbackground}{\usebox\defsbox}% |
| 1245 |
\medskip\par\noindent |
| 1246 |
\ignorespacesafterend |
| 1247 |
} |
| 1248 |
|
| 1249 |
\newcommand{\introguide}{\href{bib2gls-begin.pdf}{\qt{\styfmt{glossaries-extra} |
| 1250 |
and \bibgls: An Introductory Guide} (\filefmt{bib2gls-begin.pdf})}} |
| 1251 |
|
| 1252 |
\setcounter{tocdepth}{4} |
| 1253 |
|
| 1254 |
\newcommand*{\sectionref}[1]{\cref{#1}} |
| 1255 |
\newcommand*{\Sectionref}[1]{\Cref{#1}} |
| 1256 |
\newcommand*{\figureref}[1]{\hyperlink{#1-top}{figure~\ref*{#1}}} |
| 1257 |
\newcommand*{\Figureref}[1]{\hyperlink{#1-top}{Figure~\ref*{#1}}} |
| 1258 |
\newcommand*{\tableref}[1]{\cref{#1}} |
| 1259 |
\newcommand*{\Tableref}[1]{\Cref{#1}} |
| 1260 |
|
| 1261 |
\newcommand{\figcontents}[3]{% |
| 1262 |
\hypertarget{#3-top}{}% |
| 1263 |
\centering |
| 1264 |
#1\par |
| 1265 |
#2\label{#3}% |
| 1266 |
} |
| 1267 |
|
| 1268 |
\newlength\imagewidth |
| 1269 |
\newcount\tmpctr |
| 1270 |
|
| 1271 |
\newcommand*{\pdftwocol}[3][1]{% |
| 1272 |
\renewcommand{\tabcolsep}{2pt}% |
| 1273 |
\setlength{\imagewidth}{\dimexpr.5\linewidth-2\tabcolsep}% |
| 1274 |
\def\tabcontents{\begin{tabular}{@{}cc@{}}}% |
| 1275 |
\tmpctr\numexpr#1-1\relax |
| 1276 |
\loop |
| 1277 |
\advance\tmpctr by 1\relax |
| 1278 |
\eappto\tabcontents{\noexpand\frame{% |
| 1279 |
\noexpand\includegraphics[page=\the\tmpctr,width=\noexpand\imagewidth]{#2}}}% |
| 1280 |
\ifodd\tmpctr |
| 1281 |
\appto\tabcontents{&}% |
| 1282 |
\else |
| 1283 |
\appto\tabcontents{\\}% |
| 1284 |
\fi |
| 1285 |
\ifnum\tmpctr<#3 |
| 1286 |
\repeat |
| 1287 |
\appto\tabcontents{\end{tabular}}% |
| 1288 |
\tabcontents |
| 1289 |
} |
| 1290 |
|
| 1291 |
\makeatletter |
| 1292 |
\newcommand*{\tablelistcs}[2]{% |
| 1293 |
\tmpctr=0\relax |
| 1294 |
\def\tabcontents{}% |
| 1295 |
\loop |
| 1296 |
\advance\tmpctr by 1\relax |
| 1297 |
\appto\tabcontents{l}% |
| 1298 |
\ifnum\tmpctr<#1 |
| 1299 |
\repeat |
| 1300 |
% |
| 1301 |
\edef\tabcontents{\noexpand\begin{tabular}{@{}\tabcontents @{}}}% |
| 1302 |
\def\thislist{#2}% |
| 1303 |
\dtlsortlist{\thislist}{\dtlicompare}% |
| 1304 |
\tmpctr=1\relax |
| 1305 |
\@for\thislabel:=\thislist\do{% |
| 1306 |
\eappto\tabcontents{\noexpand\ics{\thislabel}}% |
| 1307 |
\ifnum\tmpctr<#1\relax |
| 1308 |
\appto\tabcontents{&}% |
| 1309 |
\advance\tmpctr by 1\relax |
| 1310 |
\else |
| 1311 |
\appto\tabcontents{\\}% |
| 1312 |
\tmpctr=1\relax |
| 1313 |
\fi |
| 1314 |
}% |
| 1315 |
\appto\tabcontents{\end{tabular}}% |
| 1316 |
\tabcontents |
| 1317 |
} |
| 1318 |
\makeatother |
| 1319 |
|
| 1320 |
% This is a bit fiddly. Need to represent \vec{v} in typewriter |
| 1321 |
% font for the interpreter examples. ($\mathtt{\vec{v}}$ doesn't |
| 1322 |
% work) |
| 1323 |
\newsavebox\varrow |
| 1324 |
\sbox\varrow{$\mathtt{\accentset{\to}{v}}$} |
| 1325 |
|
| 1326 |
\newcommand*{\mtx}[1]{\boldsymbol{#1}} |
| 1327 |
\newcommand*{\set}[1]{\mathcal{#1}} |
| 1328 |
\newcommand*{\card}[1]{|\set{#1}|} |
| 1329 |
\newcommand*{\imaginary}{i} |
| 1330 |
|
| 1331 |
\newcommand{\addr}[1]{\\\href{https://www.#1/}{\nolinkurl{#1}}} |
| 1332 |
\title{\bibgls: a command line Java application to convert |
| 1333 |
\filefmt{.bib} files to \filefmt{glossaries-extra.sty} resource |
| 1334 |
files} |
| 1335 |
\author{Nicola Talbot\addr{dickimaw-books.com}} |
| 1336 |
\input{version} |
| 1337 |
|
| 1338 |
\makeatletter |
| 1339 |
\renewcommand{\fps@figure}{htbp} |
| 1340 |
|
| 1341 |
\newcommand{\code}[1]{\texorpdfstring{{\ttfamily\obeyspaces #1}}{#1}} |
| 1342 |
|
| 1343 |
\newcommand{\setupcodeenvfmts}{% |
| 1344 |
\def\cmd{\char`\\}% |
| 1345 |
\def\comment##1{\mbox{\textcolor{comment}{\idx{commentchar}\ ##1}}}% |
| 1346 |
\renewcommand*{\styfmt}[1]{##1}% |
| 1347 |
\renewcommand*{\counterfmt}[1]{##1}% |
| 1348 |
\renewcommand*{\catattrfmt}[1]{\textcolor{attribute}{##1}}% |
| 1349 |
\renewcommand*{\abbrstylefmt}[1]{\textcolor{style}{##1}}% |
| 1350 |
\renewcommand*{\csfmtfont}[1]{\textcolor{cs}{##1}}% |
| 1351 |
} |
| 1352 |
|
| 1353 |
\newenvironment{codeenv} |
| 1354 |
{% |
| 1355 |
\GlsXtrStartUnsetBuffering |
| 1356 |
\renewcommand{\glslinkpresetkeys}{\setkeys{glslink}{noindex}}% |
| 1357 |
\setupcodeenvfmts |
| 1358 |
\begin{flushleft}\ttfamily\obeylines\frenchspacing\@vobeyspaces |
| 1359 |
\parindent\z@\parfillskip\@flushglue\parskip\z@skip |
| 1360 |
} |
| 1361 |
{\end{flushleft}\GlsXtrDiscardUnsetBuffering\ignorespacesafterend} |
| 1362 |
|
| 1363 |
\newenvironment{codeenv*} |
| 1364 |
{% |
| 1365 |
\GlsXtrStartUnsetBuffering |
| 1366 |
\setupcodeenvfmts |
| 1367 |
\begin{flushleft}\ttfamily\obeylines\frenchspacing\@vobeyspaces |
| 1368 |
\parindent\z@\parfillskip\@flushglue\parskip\z@skip |
| 1369 |
} |
| 1370 |
{\end{flushleft}\GlsXtrDiscardUnsetBuffering\ignorespacesafterend} |
| 1371 |
|
| 1372 |
\begingroup |
| 1373 |
\renewcommand{\addr}[1]{} |
| 1374 |
\let\texorpdfstring\@secondoftwo |
| 1375 |
\DTMsetstyle{pdf} |
| 1376 |
\protected@edef\x{\endgroup |
| 1377 |
\noexpand\hypersetup{% |
| 1378 |
pdfinfo={ |
| 1379 |
Title={\@title}, |
| 1380 |
Author={\@author}, |
| 1381 |
CreationDate={\DTMuse{creation}}, |
| 1382 |
ModDate={\DTMuse{moddate}}, |
| 1383 |
}% |
| 1384 |
}% |
| 1385 |
}\x |
| 1386 |
|
| 1387 |
\makeatother |
| 1388 |
|
| 1389 |
\renewcommand{\titlepagestyle}{empty} |
| 1390 |
|
| 1391 |
\begin{document} |
| 1392 |
\maketitle |
| 1393 |
\pagenumbering{alph} |
| 1394 |
\pagestyle{empty} |
| 1395 |
|
| 1396 |
\begin{abstract} |
| 1397 |
The \bibgls\ command line application can be used to extract |
| 1398 |
glossary information stored in a \ext{bib} file and convert it |
| 1399 |
into glossary entry definitions that can be read using |
| 1400 |
\styfmt{glossaries-extra}'s \gls{GlsXtrLoadResources} command. When used |
| 1401 |
in combination with the \styoptfmt{record} package option, \bibgls\ |
| 1402 |
can select only those entries that have been used in the document, |
| 1403 |
as well as any dependent entries, which reduces the \TeX\ resources |
| 1404 |
required by not defining unnecessary commands. |
| 1405 |
|
| 1406 |
Since \bibgls\ can also sort and collate the recorded \glspl{location} |
| 1407 |
present in the \ext{aux} file, it can simultaneously by-pass the |
| 1408 |
need to use \idx!{makeindex} or \idx!{xindy}, although \bibgls\ |
| 1409 |
can be used together with an external indexing application if required. (For |
| 1410 |
example, if a custom \idx{xindy} rule is needed.) |
| 1411 |
|
| 1412 |
An additional build may be required to ensure the \glspl{location} are |
| 1413 |
up-to-date as the page-breaking may be slightly different on the |
| 1414 |
first \LaTeX\ run due to the unknown references being replaced with |
| 1415 |
?? which can be significantly shorter than the actual text produced |
| 1416 |
when the reference is known. |
| 1417 |
|
| 1418 |
Note that \bibgls\ is a Java application, and requires at least |
| 1419 |
Java~8. Additionally, \sty{glossaries-extra} must be at least |
| 1420 |
version 1.12. These are minimum requirements, but the latest |
| 1421 |
versions are recommended. This |
| 1422 |
application was developed in response to the question |
| 1423 |
\qt{\href{http://tex.stackexchange.com/q/342544}{Is there a program |
| 1424 |
for managing glossary tags?}} on \TeX\ on |
| 1425 |
StackExchange~\cite{tex.sx.2016}. The \ext{bib} file can be managed in an |
| 1426 |
application such as JabRef. |
| 1427 |
|
| 1428 |
If you already have a \ext{tex} file containing |
| 1429 |
entry definitions using commands like \gls{newglossaryentry} |
| 1430 |
then you can use the supplementary tool \idx{convertgls2bib} |
| 1431 |
to convert the entries to the \ext{bib} format required by |
| 1432 |
\bibgls. See \sectionref{sec:gls2bib} for further details. |
| 1433 |
|
| 1434 |
The supplementary file \introguide\ is an |
| 1435 |
introductory guide to the \isty{glossaries-extra} package, which you |
| 1436 |
may prefer to start with if you are unfamiliar with the |
| 1437 |
\sty{glossaries} and \sty{glossaries-extra} packages. |
| 1438 |
\end{abstract} |
| 1439 |
|
| 1440 |
Additional resources: |
| 1441 |
\begin{itemize} |
| 1442 |
\item |
| 1443 |
\href{https://www.dickimaw-books.com/gallery/#bib2gls}{\bibgls\ gallery}. |
| 1444 |
\item |
| 1445 |
\href{https://www.dickimaw-books.com/faq.php?category=bib2gls}{\bibgls\ FAQ} |
| 1446 |
\end{itemize} |
| 1447 |
TUGboat articles: |
| 1448 |
\begin{itemize} |
| 1449 |
\item |
| 1450 |
\href{http://tug.org/TUGboat/tb40-1/tb124talbot-bib2gls.pdf}{Glossaries |
| 1451 |
with \bibgls}, issue 40:1, 2019. |
| 1452 |
\item |
| 1453 |
\href{http://tug.org/TUGboat/tb41-3/tb129talbot-bib2gls-more.pdf}{\bibgls: |
| 1454 |
selection, cross-references and locations}, issue 41:3, 2020. |
| 1455 |
\item \bibgls: sorting, issue \href{http://tug.org/TUGboat/Contents/contents42-2.html}{42:2, 2021}. |
| 1456 |
\end{itemize} |
| 1457 |
|
| 1458 |
\frontmatter |
| 1459 |
|
| 1460 |
\tableofcontents |
| 1461 |
\listoftables |
| 1462 |
\listoffigures |
| 1463 |
\printunsrtglossary*[type=terms,style=altlist,groups=false] |
| 1464 |
{% |
| 1465 |
\renewcommand{\glslistitem}[1]{% |
| 1466 |
\item[\glsentryitem{#1}% |
| 1467 |
\glstarget{#1}{\glossentryname{#1}}]% |
| 1468 |
\glsxtrifhasfield{useri}{#1}% |
| 1469 |
{\glsadd[format=glsnumberformat]{\glscurrentfieldvalue}}{}% |
| 1470 |
} |
| 1471 |
} |
| 1472 |
|
| 1473 |
\mainmatter |
| 1474 |
\chapter{Introduction} |
| 1475 |
|
| 1476 |
If you have extensively used the \styfmt{glossaries}~\cite{glossaries} or |
| 1477 |
\styfmt{glossaries-extra}~\cite{glossaries-extra} package, |
| 1478 |
you may have found yourself creating a large \iext{tex} file |
| 1479 |
containing many definitions that you frequently use in documents. |
| 1480 |
This file can then simply be loaded using \ics{input} or |
| 1481 |
\gls{loadglsentries}, but a large file like this can be difficult to |
| 1482 |
maintain and if the document only actually uses a small proportion |
| 1483 |
of those entries, the document build is unnecessarily slow due to |
| 1484 |
the time and resources taken on defining the unwanted entries. |
| 1485 |
|
| 1486 |
The aim of \bibgls\ is to allow the entries to be stored in a |
| 1487 |
\iext{bib} file, which can be maintained using a reference system |
| 1488 |
such as JabRef. The document build process |
| 1489 |
can now be analogous to that used with \idx{bibtex} (or |
| 1490 |
\appfmt{biber}), where only those entries that have been recorded in the |
| 1491 |
document (and possibly their dependent entries) will be extracted |
| 1492 |
from the \ext{bib} file. Since \bibgls\ can also perform |
| 1493 |
\hierarchical\ sorting and can collate \glspl{locationlist}, it doubles as |
| 1494 |
an indexing application, which means that the \idx{makeglossaries} |
| 1495 |
step can be skipped. |
| 1496 |
Note that \bibgls\ doesn't warn you if an entry that's referenced |
| 1497 |
in the document doesn't exist in any of the supplied \ext{bib} |
| 1498 |
files, but instead relies on the \styfmt{glossaries-extra} package |
| 1499 |
to generate the warning. So at the end of the document build check |
| 1500 |
the \ext{log} file for warnings. |
| 1501 |
|
| 1502 |
You can't use \ics{glsaddall} with \bibgls\ as that command works |
| 1503 |
by iterating over all defined entries and calling |
| 1504 |
\code{\ics{glsadd}\margm{label}}. On the first \LaTeX\ run there are no |
| 1505 |
entries defined, so \ics{glsaddall} does nothing. If you want to |
| 1506 |
select all entries, just use \csopt[all]{selection} instead (which |
| 1507 |
has the advantage over \ics{glsaddall} in that it doesn't create a |
| 1508 |
redundant \gls{location} for each entry). |
| 1509 |
|
| 1510 |
Note that \bibgls\ requires the extension package |
| 1511 |
\isty{glossaries-extra} and can't be used with just the base |
| 1512 |
\isty{glossaries} package, since it requires some of the extension |
| 1513 |
commands. See the \styfmt{glossaries-extra} user |
| 1514 |
manual~\cite{glossaries-extra} for information |
| 1515 |
on the differences between the basic package and the extended |
| 1516 |
package, as some of the default settings are different. |
| 1517 |
|
| 1518 |
Since information required by \bibgls\ is |
| 1519 |
written to the \iext{aux} file, it's not possible to run \bibgls\ |
| 1520 |
through \TeX's shell escape while the \ext{aux} file is open for |
| 1521 |
write access. (The \ext{aux} file is closed \emph{after} the end |
| 1522 |
document hook, so it can't be deferred with \ics{AtEndDocument}.) |
| 1523 |
This means that if you really want to run \bibgls\ |
| 1524 |
through \ics{write18} it must be done in the preamble with |
| 1525 |
\ics{immediate}. For example: |
| 1526 |
\begin{verbatim} |
| 1527 |
\immediate\write18{bib2gls \jobname} |
| 1528 |
\end{verbatim} |
| 1529 |
As from version 1.14 of \styfmt{glossaries-extra}, this can be done |
| 1530 |
automatically with the \styopt{automake} option if the \ext{aux} |
| 1531 |
file exists. (Remember that this will require the shell escape to be |
| 1532 |
enabled.) |
| 1533 |
|
| 1534 |
\section{Default Encoding} |
| 1535 |
\label{sec:defencoding} |
| 1536 |
|
| 1537 |
Both \XeLaTeX\ and \LuaLaTeX\ default to UTF-8 \igls{encoding}. With modern \TeX\ |
| 1538 |
distributions, \pdfLaTeX\ also defaults to UTF-8 but may be changed |
| 1539 |
with the \sty{inputenc} package. |
| 1540 |
The \sty{glossaries-extra} package writes the document encoding to |
| 1541 |
the \ext{aux} file so that \bibgls\ can pick it up. However, if it |
| 1542 |
doesn't match \bibgls\ expected encoding, it will have to close the |
| 1543 |
file and reopen it. |
| 1544 |
|
| 1545 |
The default encoding for Java applications, such as \bibgls, is the |
| 1546 |
default encoding of the \idx{JVM}. This typically matches the |
| 1547 |
operating system's default, but can be changed (see below). If you don't want |
| 1548 |
to alter the \idx{JVM}['s] default, you can set the \bibgls\ default |
| 1549 |
with \longarg{default-encoding}. |
| 1550 |
|
| 1551 |
In general, UTF-8 works best with \bibgls, but you need to be careful if your |
| 1552 |
\idx{JVM} isn't set up to use UTF-8 by default as you can end |
| 1553 |
up with encoding mismatches. This can happen with some versions of |
| 1554 |
Windows, so it's a good idea to double-check the \bibgls\ transcript |
| 1555 |
file to make sure all the encoding information is correct. |
| 1556 |
|
| 1557 |
The default encoding is written at the start of the \ext{glg} file. |
| 1558 |
For example: |
| 1559 |
\begin{verbatim} |
| 1560 |
Default encoding: UTF-8 |
| 1561 |
\end{verbatim} |
| 1562 |
When a file is opened, the associated encoding is written to the \ext{glg} |
| 1563 |
file. For example, when the \ext{aux} file is opened: |
| 1564 |
\begin{verbatim} |
| 1565 |
Reading myDoc.aux |
| 1566 |
Encoding: UTF-8 |
| 1567 |
\end{verbatim} |
| 1568 |
If the document encoding is detected in the \ext{aux} file |
| 1569 |
(which \bibgls\ should now be able to do), the encoding will |
| 1570 |
be written to the transcript. For example: |
| 1571 |
\begin{verbatim} |
| 1572 |
TeX character encoding: UTF-8 |
| 1573 |
\end{verbatim} |
| 1574 |
When a \ext{bib} file is read, the \csopt{charset} setting, |
| 1575 |
the detected encoding (from the encoding comment line, |
| 1576 |
see \sectionref{sec:bibencoding}), if found, and the encoding |
| 1577 |
actually used are written. For example, where \csopt{charset} hasn't |
| 1578 |
been set but an encoding comment line has been found: |
| 1579 |
\begin{verbatim} |
| 1580 |
Parsing bib files for resource myDoc.glstex. |
| 1581 |
Default encoding: not set |
| 1582 |
Detected encoding: UTF-8 |
| 1583 |
Reading symbols.bib |
| 1584 |
Encoding: UTF-8 |
| 1585 |
\end{verbatim} |
| 1586 |
|
| 1587 |
The file encodings used by \bibgls\ are as follows: |
| 1588 |
\begin{itemize} |
| 1589 |
\item Writing the \iext{glg} transcript file: default encoding. |
| 1590 |
|
| 1591 |
\item Reading the document \iext{log} file: \longarg{log-encoding} |
| 1592 |
setting, if supplied, otherwise the default encoding. |
| 1593 |
|
| 1594 |
Note that the \ext{log} file may not have the same encoding as the |
| 1595 |
\ext{tex} file~\cite{tex.sx.2013}. In the case of the T1 font |
| 1596 |
encoding, the encoding will be close enough to ISO-8859-1 for that |
| 1597 |
to be used with \bibgls. Any problematic character will trigger a |
| 1598 |
warning and \bibgls\ will quit reading the file. This will most |
| 1599 |
likely be in an overfull warning, by which point \bibgls\ should |
| 1600 |
have gathered all the information it requires. |
| 1601 |
|
| 1602 |
\item Reading the \iext{aux} file: the \longarg{tex-encoding} |
| 1603 |
setting, if supplied, or UTF-8 if \sty{fontspec} is detected in the |
| 1604 |
\ext{log} file, otherwise the default encoding. |
| 1605 |
|
| 1606 |
\item Reading the \iext{bib} files: the \csopt{charset} resource |
| 1607 |
option, if supplied, or the encoding specified by the encoding |
| 1608 |
comment line in the \ext{bib} file (see |
| 1609 |
\sectionref{sec:bibencoding}), otherwise the default encoding. |
| 1610 |
|
| 1611 |
\item Writing the \iext{glstex} files: the \longarg{tex-encoding} |
| 1612 |
setting, if supplied, or UTF-8 if \sty{fontspec} detected in the |
| 1613 |
\ext{log} file, or the document encoding picked up from the |
| 1614 |
\ext{aux} file, otherwise the default encoding. |
| 1615 |
\end{itemize} |
| 1616 |
For example: |
| 1617 |
\begin{verbatim} |
| 1618 |
bib2gls --log-encoding ISO-8859-1 --default-encoding UTF-8 myDoc |
| 1619 |
\end{verbatim} |
| 1620 |
|
| 1621 |
To change the default \igls{encoding} for the \idx{JVM} set the |
| 1622 |
\code{JAVA\_TOOL\_OPTIONS} environment variable to include |
| 1623 |
\code{-Dfile.encoding=\meta{encoding}} where \meta{encoding} is the |
| 1624 |
desired default encoding (such as UTF-8). Note that this will |
| 1625 |
affect all your installed Java applications, not just \bibgls, (for |
| 1626 |
example, JabRef). |
| 1627 |
|
| 1628 |
If you have a problem with non-ASCII characters not displaying |
| 1629 |
correctly in your document: |
| 1630 |
\begin{itemize} |
| 1631 |
\item Check that the file \gls{encoding} of your document \ext{tex} |
| 1632 |
and \ext{bib} files have been correctly set by your text editor. |
| 1633 |
\item Check that your document supports that \gls{encoding} (for example, |
| 1634 |
through the \isty{inputenc} package). |
| 1635 |
\item Check \bibgls's transcript file for the encoding information |
| 1636 |
to ensure that the settings are correct. |
| 1637 |
\end{itemize} |
| 1638 |
|
| 1639 |
\section{Example Use} |
| 1640 |
The glossary entries are stored in a \ext{bib} file. For |
| 1641 |
example, the file \filefmt{entries.bib} might contain: |
| 1642 |
\begin{codeenv} |
| 1643 |
\atentry{entry}\marg{bird, |
| 1644 |
\field{name}=\marg{bird}, |
| 1645 |
\field{description} = \marg{feathered animal} |
| 1646 |
} |
| 1647 |
\strut |
| 1648 |
\atentry{abbreviation}\marg{html, |
| 1649 |
\field{short}=\qtdelim{html}, |
| 1650 |
\field{long}=\marg{hypertext markup language} |
| 1651 |
} |
| 1652 |
\strut |
| 1653 |
\atentry{symbol}\marg{v, |
| 1654 |
\field{name}=\marg{\idx!{mshiftchar}\cs{vec}\marg{v}\idx!{mshiftchar}}, |
| 1655 |
\field{text}=\marg{\cs{vec}\marg{v}}, |
| 1656 |
\field{description}=\marg{a vector} |
| 1657 |
} |
| 1658 |
\strut |
| 1659 |
\atentry{index}\marg{goose,\field{plural}=\qtdelim{geese}} |
| 1660 |
\end{codeenv} |
| 1661 |
Here's an example document that uses this data: |
| 1662 |
\begin{codeenv} |
| 1663 |
\cmd{documentclass}\marg{article} |
| 1664 |
\strut |
| 1665 |
\cs{usepackage}\oarg{\styoptref{record}}\marg{glossaries-extra} |
| 1666 |
\strut |
| 1667 |
\gls{GlsXtrLoadResources}\oarg{ |
| 1668 |
\csopt[entries]{src},\comment{data in entries.bib} |
| 1669 |
\csopt[en-GB]{sort}\comment{sort according to 'en-GB' locale} |
| 1670 |
} |
| 1671 |
\strut |
| 1672 |
\cmd{begin}\marg{document} |
| 1673 |
\cs{Gls}\marg{bird} and \cs{gls}\marg{goose}. |
| 1674 |
Symbol: \idx{mshiftchar}\cs{gls}\marg{v}\idx{mshiftchar}. |
| 1675 |
Abbreviation: \cs{gls}\marg{html}. |
| 1676 |
\strut |
| 1677 |
\cs{printunsrtglossaries} |
| 1678 |
\cmd{end}\marg{document} |
| 1679 |
\end{codeenv} |
| 1680 |
If this document is called \filefmt{myDoc.tex}, the build |
| 1681 |
process is: |
| 1682 |
\begin{verbatim} |
| 1683 |
pdflatex myDoc |
| 1684 |
bib2gls myDoc |
| 1685 |
pdflatex myDoc |
| 1686 |
\end{verbatim} |
| 1687 |
(This manual assumes \appfmt{pdflatex} for simplicity. Replace |
| 1688 |
with \appfmt{latex}, \appfmt{xelatex} or \appfmt{lualatex} as |
| 1689 |
appropriate.) If you want \idxpl{lettergroup} (either headed, with |
| 1690 |
styles like \glostyle{indexgroup}, or just a blank line separator |
| 1691 |
with \styopt[false]{nogroupskip}) then you need to use the |
| 1692 |
\longarg{group} switch: |
| 1693 |
\begin{verbatim} |
| 1694 |
pdflatex myDoc |
| 1695 |
bib2gls --group myDoc |
| 1696 |
pdflatex myDoc |
| 1697 |
\end{verbatim} |
| 1698 |
|
| 1699 |
You can have multiple instances of \gls{GlsXtrLoadResources}. For |
| 1700 |
example: |
| 1701 |
\begin{codeenv} |
| 1702 |
\cmd{documentclass}\marg{article} |
| 1703 |
\strut |
| 1704 |
\cmd{usepackage}\oarg{\styopt{record},\styopt{index},\styopt{abbreviations},\styopt{symbols}}\marg{glossaries-extra} |
| 1705 |
\strut |
| 1706 |
\gls{GlsXtrLoadResources}\oarg{ |
| 1707 |
\csopt[entries]{src},\comment{data in entries.bib} |
| 1708 |
\csopt[en-GB]{sort},\comment{sort according to 'en-GB' locale} |
| 1709 |
\csopt[entrytype=\marg{entry}]{match},\comment{only select \atentry{entry}} |
| 1710 |
\csopt[main]{type}\comment{put these entries in the 'main' glossary} |
| 1711 |
} |
| 1712 |
\strut |
| 1713 |
\gls{GlsXtrLoadResources}\oarg{ |
| 1714 |
\csopt[entries]{src},\comment{data in entries.bib} |
| 1715 |
\csopt[en-GB]{sort},\comment{sort according to 'en-GB' locale} |
| 1716 |
\csopt[entrytype=\marg{abbreviation}]{match},\comment{only select \atentry{abbreviation}} |
| 1717 |
\csopt[abbreviations]{type}\comment{put these in the 'abbreviations' glossary} |
| 1718 |
} |
| 1719 |
\strut |
| 1720 |
\gls{GlsXtrLoadResources}\oarg{ |
| 1721 |
\csopt[entries]{src},\comment{data in entries.bib} |
| 1722 |
\csopt[letter-case]{sort},\comment{case-sensitive letter sort} |
| 1723 |
\csopt[entrytype=\marg{symbol}]{match},\comment{only select \atentry{symbol}} |
| 1724 |
\csopt[symbols]{type}\comment{put these entries in the 'symbols' glossary} |
| 1725 |
} |
| 1726 |
\strut |
| 1727 |
\gls{GlsXtrLoadResources}\oarg{ |
| 1728 |
\csopt[entries]{src},\comment{data in entries.bib} |
| 1729 |
\csopt[en-GB]{sort},\comment{sort according to 'en-GB' locale} |
| 1730 |
\csopt[entrytype=\marg{index}]{match},\comment{only select \atentry{index}} |
| 1731 |
\csopt[index]{type}\comment{put these entries in the 'index' glossary} |
| 1732 |
} |
| 1733 |
\strut |
| 1734 |
\cmd{begin}\marg{document} |
| 1735 |
\cs{Gls}\marg{bird} and \cs{gls}\marg{goose}. |
| 1736 |
Symbol: \idx!{mshiftchar}\cs{gls}\marg{v}\idx!{mshiftchar}. Abbreviation: \cs{gls}\marg{html}. |
| 1737 |
\cs{printunsrtglossaries} |
| 1738 |
\cmd{end}\marg{document} |
| 1739 |
\end{codeenv} |
| 1740 |
There are more examples provided in \sectionref{sec:examples} and |
| 1741 |
also in the \href{https://www.dickimaw-books.com/gallery/#bib2gls}{\bibgls\ gallery}. |
| 1742 |
|
| 1743 |
Note that there's no need to called \idx!{xindy} or \idx!{makeindex} |
| 1744 |
since \bibgls\ automatically sorts the entries and collates the \glspl{location} |
| 1745 |
after selecting the required entries from the \ext{bib} file and |
| 1746 |
before writing the temporary file that's input with |
| 1747 |
\gls{GlsXtrLoadResources} (or the shortcut |
| 1748 |
\gls{glsbibdata}).\footnote{This document will mostly use |
| 1749 |
\gls{GlsXtrLoadResources}.} This |
| 1750 |
means the entries are already defined in the correct order, and only |
| 1751 |
those entries that are required in the document are defined, so |
| 1752 |
\ics{printunsrtglossary} (or \ics{printunsrtglossaries}) may be used. |
| 1753 |
(The \qtt{unsrt} part of the command name indicates that all |
| 1754 |
defined entries should be listed in the order of definition from |
| 1755 |
\styfmt{glossaries-extra}'s point of view, see the supplementary |
| 1756 |
document \introguide\ for further details.) |
| 1757 |
|
| 1758 |
If you don't provide a value with the \styopt{record} option, then |
| 1759 |
\styopt[only]{record} is assumed. This saves the same indexing |
| 1760 |
information that's used with the \ics{cs.makeglossaries} and |
| 1761 |
\ics{makenoidxglossaries} methods (described in the main |
| 1762 |
\styfmt{glossaries} user manual~\cite{glossaries}). As from |
| 1763 |
\styfmt{glossaries-extra} version 1.37, you can instead use |
| 1764 |
\styopt[nameref]{record}, which saves some extra information for |
| 1765 |
each \gls{location} that's not available for the other indexing methods. |
| 1766 |
See \longarg{merge-nameref-on} for further details. |
| 1767 |
|
| 1768 |
If you additionally want to use an indexing application, such |
| 1769 |
as \idx{xindy}, you need the package option |
| 1770 |
\styopt[alsoindex]{record} and use \ics{cs.makeglossaries} |
| 1771 |
and \ics{printglossary} (or the iterative \ics{printglossaries}) as usual. |
| 1772 |
This requires a more complicated build process: |
| 1773 |
\begin{verbatim} |
| 1774 |
pdflatex myDoc |
| 1775 |
bib2gls myDoc |
| 1776 |
pdflatex myDoc |
| 1777 |
makeglossaries myDoc |
| 1778 |
pdflatex myDoc |
| 1779 |
\end{verbatim} |
| 1780 |
(The entries aren't defined until the second \LaTeX\ run, so the |
| 1781 |
indexing files required by \idx!{xindy} or \idx!{makeindex} can't be |
| 1782 |
created until then.) In this case, \bibgls\ is simply being used to |
| 1783 |
fetch the entry definitions from one or more \ext{bib} files, with |
| 1784 |
the sorting and collating performed by the other indexing |
| 1785 |
application (so the resource option list would need |
| 1786 |
\csopt[none]{sort} and \csopt[false]{save-locations}). In general, |
| 1787 |
it's best to avoid this hybrid method unless you have a particular |
| 1788 |
set of \idx{xindy} rules that can't be replicated with \bibgls. |
| 1789 |
|
| 1790 |
\section{Logical Divisions: \field{type} vs \field{group} vs \field{parent}} |
| 1791 |
\label{sec:logicaldivisions} |
| 1792 |
|
| 1793 |
If you have a document with many terms that need listing, it's |
| 1794 |
likely that you may want to divide the terms into separate blocks or |
| 1795 |
units for easier reading. There are three fields that are used |
| 1796 |
for this. |
| 1797 |
\begin{description} |
| 1798 |
\item[\field{type}] The highest division is the glossary to which |
| 1799 |
the entry belongs. The glossary must first be defined (see |
| 1800 |
\sectionref{sec:newglossary}) with an associated label used to |
| 1801 |
identify it. The title is assigned to the glossary when it is |
| 1802 |
defined or it can be overridden with the \printglossopt{title} key. |
| 1803 |
The glossary is displayed using \cs{printunsrtglossary} and the |
| 1804 |
title is placed in a sectioning command by default. |
| 1805 |
|
| 1806 |
\begin{important} |
| 1807 |
\bibgls\ does not provide any means of sorting glossary types. If |
| 1808 |
you use \ics{printunsrtglossaries} the order will be according to |
| 1809 |
the order in which the glossaries were defined. You may use |
| 1810 |
\cs{printunsrtglossary} to list individual glossaries in your own |
| 1811 |
preferred order. |
| 1812 |
\end{important} |
| 1813 |
|
| 1814 |
\item[\field{group}] The entries within a glossary can form \idxpl{group} |
| 1815 |
as a by-product of the sorting method. This must be enabled with the |
| 1816 |
\longarg{group} switch and isn't available for the sort methods |
| 1817 |
listed in \tableref{tab:sortoptionsnosort}. The group label is |
| 1818 |
stored in the \field{group} field. This is an internal field that |
| 1819 |
typically shouldn't be set in the \ext{bib} file. |
| 1820 |
|
| 1821 |
You can specify your own \idxpl{customgroup} but if you do so you must |
| 1822 |
ensure that the terms are ordered in such a way that they are |
| 1823 |
gathered according to group. This is typically done by splitting the |
| 1824 |
glossary into blocks using a separate \gls{GlsXtrLoadResources} with |
| 1825 |
the \csopt{group} option set. You control the order of the groups by |
| 1826 |
your ordering of \gls{GlsXtrLoadResources}. The group title can be |
| 1827 |
assigned using \gls{glsxtrsetgrouptitle} within the document. |
| 1828 |
|
| 1829 |
\begin{important} |
| 1830 |
\bibgls\ does not sort by group title. At most it can sort by the |
| 1831 |
group label (by changing the \csopt{sort-field}) but this is usually |
| 1832 |
an indication that you actually have a \gls{hierarchicalglossary} and you |
| 1833 |
ought to be using the \field{parent} field instead. (Compare |
| 1834 |
\exfile{sample-textsymbols.tex} and |
| 1835 |
\exfile{sample-textsymbols2.tex}.) |
| 1836 |
\end{important} |
| 1837 |
|
| 1838 |
\item[\field{parent}] An entry may have one or more \glspl{sub-entry}. |
| 1839 |
Most of the sort methods will produce a \hierarchical\ ordering that |
| 1840 |
ensures that the \glspl{sub-entry} are listed immediately after their |
| 1841 |
\gls{parententry}. The \gls{parententry} is identified by the \field{parent} |
| 1842 |
field which should contain the \glsdisp{parententry}{parent's} label. |
| 1843 |
|
| 1844 |
\begin{important} |
| 1845 |
\bibgls\ sorts the \parent\ and \child\ entries using the same |
| 1846 |
comparator. The sort methods listed in |
| 1847 |
\tableref{tab:sortoptionsnosort} disregard the \hierarchicallevel, |
| 1848 |
which can result in \glspl{childentry} becoming detached from their |
| 1849 |
\gls{parententry}. The other methods sort \hierarchically\ using the |
| 1850 |
same comparator but take the \hierarchicallevel\ into account. |
| 1851 |
\end{important} |
| 1852 |
|
| 1853 |
\end{description} |
| 1854 |
|
| 1855 |
Suppose you have a mixture of terms, abbreviations and symbols, then |
| 1856 |
you might want to have three glossaries that are listed in the table |
| 1857 |
of contents. In this case, you use the \field{type} field or the |
| 1858 |
\field{type} resource option. The ordering of the glossaries is |
| 1859 |
determined by the ordering of the \cs{printunsrtglossary} |
| 1860 |
commands within the document. For example: |
| 1861 |
\begin{codeenv} |
| 1862 |
\cs{printunsrtglossary} |
| 1863 |
\cs{printunsrtglossary}\oarg{\printglossopt[abbreviations]{type}} |
| 1864 |
\cs{printunsrtglossary}\oarg{\printglossopt[symbols]{type}} |
| 1865 |
\end{codeenv} |
| 1866 |
|
| 1867 |
Suppose that your list of terms spans many pages and you feel it |
| 1868 |
would be helpful to the reader to split it up into letter groups |
| 1869 |
then you would need to run \bibgls\ with the \longarg{group} switch |
| 1870 |
and use a glossary style that supports \idxpl{lettergroup} for that |
| 1871 |
glossary. For example: |
| 1872 |
\begin{codeenv} |
| 1873 |
\cs{printunsrtglossary}\oarg{\printglossopt[indexgroup]{style}} |
| 1874 |
\end{codeenv} |
| 1875 |
|
| 1876 |
Suppose that your list of symbols consists of pictographs, Latin characters |
| 1877 |
and Greek characters and you want them grouped together |
| 1878 |
in that order. Then you would use a separate |
| 1879 |
\gls{GlsXtrLoadResources} for each block and assign your own custom |
| 1880 |
group. This means ensuring that each \igls{resourceset} only selects |
| 1881 |
the terms for that group. The simplest way of doing this is to |
| 1882 |
have a separate \ext{bib} file for each set. For example: |
| 1883 |
\begin{codeenv} |
| 1884 |
\gls{glsxtrsetgrouptitle}\marg{pictographs}\marg{Pictographs} |
| 1885 |
\gls{glsxtrsetgrouptitle}\marg{latinsymbols}\marg{Latin Characters} |
| 1886 |
\gls{glsxtrsetgrouptitle}\marg{greeksymbols}\marg{Greek Characters} |
| 1887 |
\gls{GlsXtrLoadResources}\oarg{ |
| 1888 |
\csopt[generalsymbols]{src},\comment{data in generalsymbols.bib} |
| 1889 |
\csopt[pictographs]{group}, |
| 1890 |
\csopt[symbols]{type} |
| 1891 |
} |
| 1892 |
\gls{GlsXtrLoadResources}\oarg{ |
| 1893 |
\csopt[latinsymbols]{src},\comment{data in latinsymbols.bib} |
| 1894 |
\csopt[latin]{group}, |
| 1895 |
\csopt[symbols]{type} |
| 1896 |
} |
| 1897 |
\gls{GlsXtrLoadResources}\oarg{ |
| 1898 |
\csopt[greeksymbols]{src},\comment{data in greeksymbols.bib} |
| 1899 |
\csopt[greek]{group}, |
| 1900 |
\csopt[symbols]{type} |
| 1901 |
} |
| 1902 |
\end{codeenv} |
| 1903 |
|
| 1904 |
Suppose instead that you have many of these logical blocks and you |
| 1905 |
want them ordered according to the block title. In this case you |
| 1906 |
have a \gls{hierarchicalglossary} and you need to use the \field{parent} |
| 1907 |
field. You then need to select an appropriate \idx{glossarystyle}. |
| 1908 |
|
| 1909 |
If you only want to have a single \ext{bib} file that contains all |
| 1910 |
your entries and you want to share it across multiple documents then |
| 1911 |
the most flexible approach is to use custom fields and \glspl{entrytype} |
| 1912 |
that can be aliased according to the needs of the \glspl{resourceset}. |
| 1913 |
|
| 1914 |
For example, the file \filefmt{entries.bib}: |
| 1915 |
\begin{codeenv} |
| 1916 |
\comment{Encoding: UTF-8} |
| 1917 |
\strut |
| 1918 |
\atentryfmt{indexplural}\marg{latin,\field{text}=\marg{Latin character}} |
| 1919 |
\atentryfmt{indexplural}\marg{greek,\field{text}=\marg{Greek character}} |
| 1920 |
\atentryfmt{indexplural}\marg{pictograph} |
| 1921 |
\strut |
| 1922 |
\atentry{symbol}\marg{fx, |
| 1923 |
\field{name}=\marg{\cs{ensuremath}\marg{f(x)}}, |
| 1924 |
\field{description}=\marg{function of \idx{mshiftchar}x\idx{mshiftchar}}, |
| 1925 |
\fieldfmt{identifier}=\marg{latin} |
| 1926 |
} |
| 1927 |
\strut |
| 1928 |
\atentry{symbol}\marg{f\idx{aposchar}x, |
| 1929 |
\field{name}={\cs{ensuremath}\marg{f\idx{aposchar}(x)}}, |
| 1930 |
\field{description}=\marg{derivative of \cs{gls}\marg{fx}}, |
| 1931 |
\fieldfmt{identifier}=\marg{latin} |
| 1932 |
} |
| 1933 |
\strut |
| 1934 |
\atentry{symbol}\marg{pi, |
| 1935 |
\field{name}=\marg{\cs{ensuremath}\marg{\cs{pi}}}, |
| 1936 |
\field{description}=\marg{ratio of circumference to diameter}, |
| 1937 |
\fieldfmt{identifier}=\marg{greek} |
| 1938 |
} |
| 1939 |
\strut |
| 1940 |
\atentry{symbol}\marg{heart, |
| 1941 |
\field{name}=\marg{\cs{ensuremath}\marg{\ics{heartsuit}}}, |
| 1942 |
\field{description}=\marg{heart}, |
| 1943 |
\fieldfmt{identifier}=\marg{pictograph} |
| 1944 |
} |
| 1945 |
\strut |
| 1946 |
\atentry{symbol}\marg{diamond, |
| 1947 |
\field{name}=\marg{\cs{ensuremath}\marg{\ics{diamondsuit}}}, |
| 1948 |
\field{description}=\marg{diamond}, |
| 1949 |
\fieldfmt{identifier}=\marg{pictograph} |
| 1950 |
} |
| 1951 |
\strut |
| 1952 |
\atentry{abbreviation}\marg{html, |
| 1953 |
\field{short}=\marg{html}, |
| 1954 |
\field{long}=\marg{hypertext markup language}, |
| 1955 |
\fieldfmt{identifier}=\marg{markuplanguage} |
| 1956 |
} |
| 1957 |
\strut |
| 1958 |
\atentry{abbreviation}\marg{xml, |
| 1959 |
\field{short}=\marg{xml}, |
| 1960 |
\field{long}=\marg{extensible markup language}, |
| 1961 |
\fieldfmt{identifier}=\marg{markuplanguage} |
| 1962 |
} |
| 1963 |
\strut |
| 1964 |
\atentry{entry}\marg{duck, |
| 1965 |
\field{name}=\marg{duck}, |
| 1966 |
\field{description}=\marg{a waterbird with webbed feet}, |
| 1967 |
\fieldfmt{identifier}=\marg{animal} |
| 1968 |
} |
| 1969 |
\strut |
| 1970 |
\atentry{entry}\marg{parrot, |
| 1971 |
\field{name}=\marg{parrot}, |
| 1972 |
\field{description}=\marg{mainly tropical bird with bright plumage}, |
| 1973 |
\fieldfmt{identifier}=\marg{animal} |
| 1974 |
} |
| 1975 |
\end{codeenv} |
| 1976 |
This has a custom field \fieldfmt{identifier}. This will be ignored |
| 1977 |
by \bibgls\ unless defined or aliased in the document. |
| 1978 |
|
| 1979 |
Here's an example document that creates three glossary types (the |
| 1980 |
default \mainglossary\ and the glossaries created with the |
| 1981 |
\styopt{abbreviations} and \styopt{symbols} options). They are |
| 1982 |
listed in the order of \cs{printunsrtglossary} and their titles are |
| 1983 |
added to the table of contents. |
| 1984 |
|
| 1985 |
The custom \fieldfmt{identifier} fields are ignored for the |
| 1986 |
\glsdisp{mainglossary}{main} and abbreviation glossaries, but they are aliased for the |
| 1987 |
symbols to the \field{group} field. Since I've split the symbols |
| 1988 |
glossary into blocks with each block only containing entries that |
| 1989 |
have the same \field{group} value, this isn't a problem. It also |
| 1990 |
won't trigger a warning with \longarg{warn-non-bib-fields} as it's |
| 1991 |
being aliased rather than set in the \ext{bib} file. The blocks |
| 1992 |
appear in the same order as the corresponding \gls{GlsXtrLoadResources} |
| 1993 |
commands. The title for each block is provided in the document |
| 1994 |
using \gls{glsxtrsetgrouptitle}. |
| 1995 |
\begin{codeenv} |
| 1996 |
\cmd{documentclass}\marg{article} |
| 1997 |
\strut |
| 1998 |
\cmd{usepackage}\oarg{\styopt{record},\styopt{abbreviations},\styopt{symbols}}\marg{glossaries-extra} |
| 1999 |
\strut |
| 2000 |
\cs{renewcommand}\marg{\gls{GlsXtrDefaultResourceOptions}}\marg{ |
| 2001 |
\csopt[all]{selection},\csopt[entries]{src},\csopt[false]{save-locations}} |
| 2002 |
\strut |
| 2003 |
\gls{GlsXtrLoadResources}\oarg{\csopt[main]{type},\csopt[entrytype=entry]{match}} |
| 2004 |
\gls{GlsXtrLoadResources}\oarg{\csopt[abbreviations]{type}, |
| 2005 |
\csopt[entrytype=abbreviation]{match}} |
| 2006 |
\strut |
| 2007 |
\gls{glsxtrsetgrouptitle}\marg{pictograph}\marg{Pictographs} |
| 2008 |
\gls{GlsXtrLoadResources}\oarg{\csopt[symbols]{type}, |
| 2009 |
\csopt[identifier=\field{group}]{field-aliases}, |
| 2010 |
\csopt[\field{group}=pictograph]{match}} |
| 2011 |
\strut |
| 2012 |
\gls{glsxtrsetgrouptitle}\marg{latin}\marg{Latin Characters} |
| 2013 |
\gls{GlsXtrLoadResources}\oarg{\csopt[symbols]{type}, |
| 2014 |
\csopt[identifier=\field{group}]{field-aliases}, |
| 2015 |
\csopt[\field{group}=latin]{match}} |
| 2016 |
\strut |
| 2017 |
\gls{glsxtrsetgrouptitle}\marg{greek}\marg{Greek Characters} |
| 2018 |
\gls{GlsXtrLoadResources}\oarg{\csopt[symbols]{type}, |
| 2019 |
\csopt[identifier=\field{group}]{field-aliases}, |
| 2020 |
\csopt[\field{group}=greek]{match}} |
| 2021 |
\strut |
| 2022 |
\cmd{begin}\marg{document} |
| 2023 |
\cs{tableofcontents} |
| 2024 |
\cs{printunsrtglossary}\oarg{\printglossopt[abbreviations]{type}} |
| 2025 |
\cs{printunsrtglossary} |
| 2026 |
\cs{printunsrtglossary}\oarg{\printglossopt[symbols]{type},\printglossopt[\glostyle{treegroup}]{style}} |
| 2027 |
\cmd{end}\marg{document} |
| 2028 |
\end{codeenv} |
| 2029 |
|
| 2030 |
In the above example document, the symbols list is divided into |
| 2031 |
three groups, listed in the order: Pictographs, Latin characters and |
| 2032 |
Greek characters. If you want these titles ordered alphabetically |
| 2033 |
then you need a \hierarchical\ structure instead. This can be obtained |
| 2034 |
by aliasing the custom \fieldfmt{identifier} field to |
| 2035 |
\field{parent}: |
| 2036 |
\begin{codeenv} |
| 2037 |
\cmd{documentclass}\marg{article} |
| 2038 |
\strut |
| 2039 |
\cmd{usepackage}\oarg{\styopt{record},\styopt[topic]{stylemods},\styopt{abbreviations},\styopt{symbols}}\marg{glossaries-extra} |
| 2040 |
\strut |
| 2041 |
\cs{renewcommand}\marg{\gls{GlsXtrDefaultResourceOptions}}\marg{\comment{} |
| 2042 |
\csopt[all]{selection},\csopt[entries]{src},\csopt[false]{save-locations}} |
| 2043 |
\strut |
| 2044 |
\gls{GlsXtrLoadResources}\oarg{\csopt[main]{type},\csopt[entrytype=entry]{match}} |
| 2045 |
\gls{GlsXtrLoadResources}\oarg{\csopt[abbreviations]{type}, |
| 2046 |
\csopt[entrytype=abbreviation]{match}} |
| 2047 |
\strut |
| 2048 |
\gls{GlsXtrLoadResources}\oarg{\csopt[symbols]{type}, |
| 2049 |
\csopt[identifier=\field{parent}]{field-aliases}, |
| 2050 |
\csopt[entrytype=symbol,entrytype=indexplural]{match}} |
| 2051 |
\strut |
| 2052 |
\cmd{begin}\marg{document} |
| 2053 |
\cs{tableofcontents} |
| 2054 |
\cs{printunsrtglossary}\oarg{\printglossopt[abbreviations]{type}} |
| 2055 |
\cs{printunsrtglossary} |
| 2056 |
\cs{printunsrtglossary}\oarg{\printglossopt[symbols]{type},\printglossopt[\glostyle{topic}]{style}} |
| 2057 |
\cmd{end}\marg{document} |
| 2058 |
\end{codeenv} |
| 2059 |
The style used for the symbols list is now \glostyle{topic} rather |
| 2060 |
than \glostyle{treegroup}. This results in a slightly different |
| 2061 |
appearance. You can select the most appropriate style according to |
| 2062 |
your needs (see the gallery of predefined |
| 2063 |
styles~\cite{glossarystylesgallery}). The topic ordering is now: |
| 2064 |
Greek characters, Latin characters and Pictographs. |
| 2065 |
|
| 2066 |
\section{Defining a New Glossary} |
| 2067 |
\label{sec:newglossary} |
| 2068 |
|
| 2069 |
Some of the examples in this manual use \ics{newglossary*} to define |
| 2070 |
a new glossary type and some use \ics{newignoredglossary} or |
| 2071 |
\ics{newignoredglossary*}. You may be wondering why the starred |
| 2072 |
forms and why define an \igls{ignoredglossary}? |
| 2073 |
|
| 2074 |
The base \styfmt{glossaries} package was originally designed to work |
| 2075 |
with \idx!{makeindex}. Support for \idx!{xindy} was later added, but |
| 2076 |
both require three files per glossary type: the transcript file |
| 2077 |
(created by the indexing application), the file written by \LaTeX\ |
| 2078 |
(and input by the indexing application) and the file input by |
| 2079 |
\LaTeX\ (and written by the indexing application). So when a new glossary |
| 2080 |
is defined with \ics{newglossary}, this not only defines internal |
| 2081 |
control sequences that store the list of entry labels associated |
| 2082 |
with that glossary, the title and the entry format but also has to |
| 2083 |
define internal control sequences that store the three file |
| 2084 |
extensions. The starred form \cs{newglossary*} is just a shortcut |
| 2085 |
that forms the extensions from the glossary label. For the purposes |
| 2086 |
of \bibgls, this is simpler than the unstarred version since the |
| 2087 |
extensions are now irrelevant as they are only applicable to |
| 2088 |
\idx!{makeindex} and \idx!{xindy}. (Unless, of course, you are using |
| 2089 |
a hybrid method with \styopt[alsoindex]{record}.) |
| 2090 |
|
| 2091 |
Since some users wanted the ability to define entries that were |
| 2092 |
common enough to not be worth including in any glossary lists, the |
| 2093 |
concept of an \igls{ignoredglossary} was introduced, defined with |
| 2094 |
\cs{newignoredglossary}. This only requires an internal control |
| 2095 |
sequence to store the list of entry labels associated with that |
| 2096 |
glossary\footnote{All entries must be assigned to a glossary. If you |
| 2097 |
don't use the \field{type} field the default is used.}\ and the |
| 2098 |
associated internal command that governs the way that |
| 2099 |
commands like \cs{gls} are displayed for that glossary type. |
| 2100 |
Since this type of glossary has no associated files, it can't be |
| 2101 |
used with \cs{printglossary} and therefore isn't included in the |
| 2102 |
list of glossary labels that's iterated over by commands like |
| 2103 |
\cs{printglossaries}. Since there's no glossary list (and therefore |
| 2104 |
no targets), \cs{newignoredglossary} additionally disables hyperlinks for that |
| 2105 |
glossary type, but it doesn't disable indexing. The indexing macro |
| 2106 |
is still called, but because there's no associated file to write to, |
| 2107 |
it has no effect. With \bibgls, the indexing is written to the |
| 2108 |
\ext{aux} file and so does have an effect. |
| 2109 |
|
| 2110 |
Although \iglspl{ignoredglossary} can't be used with |
| 2111 |
\cs{printglossary}, they can be used with \cs{printunsrtglossary}, |
| 2112 |
which is designed to work without any indexing, but you need to |
| 2113 |
explicitly set the title in the optional argument to override the |
| 2114 |
default. \Idxpl{ignoredglossary} still can't be used in |
| 2115 |
\cs{printunsrtglossaries}, since they're not included in the list |
| 2116 |
that this command iterates over. |
| 2117 |
|
| 2118 |
So \cs{newignoredglossary} (or \cs{provideignoredglossary}) is |
| 2119 |
useful with \bibgls\ if you're happy to use \cs{printunsrtglossary} |
| 2120 |
with the \printglossopt{type} and \printglossopt{title} options as it reduces the overall |
| 2121 |
number of internal control sequences. \Idxpl{ignoredglossary} are |
| 2122 |
also useful for stand-alone definitions (\ics{glsxtrglossentry}) or |
| 2123 |
with \ics{printunsrtinnerglossary} as no title is required in those |
| 2124 |
cases (see \exfile{sample-nested.tex} for an example). |
| 2125 |
|
| 2126 |
Since there is now the possibility of targets (created within \cs{printunsrtglossary} or |
| 2127 |
\cs{printunsrtinnerglossary} or \cs{glsxtrglossentry}), it's convenient to |
| 2128 |
have an \igls{ignoredglossary} that doesn't suppress the hyperlinks, |
| 2129 |
which can be obtained with the starred form \ics{newignoredglossary*} |
| 2130 |
provided by \styfmt{glossaries-extra} (or \cs{provideignoredglossary*}). |
| 2131 |
|
| 2132 |
Some resource options, such as \csopt{master}, \csopt{secondary}, |
| 2133 |
and \csopt{trigger-type}, need to ensure that a |
| 2134 |
required glossary is defined. In this case, \bibgls\ uses |
| 2135 |
\ics{provideignoredglossary*} in the \iext{glstex} file |
| 2136 |
even if \longarg{no-provide-glossaries} is set. |
| 2137 |
Note that only \csopt{ignored-type} uses the unstarred |
| 2138 |
\ics{provideignoredglossary}. |
| 2139 |
|
| 2140 |
If you haven't already defined that glossary in the document with \cs{newglossary*}, |
| 2141 |
you'll need to set the title in the optional argument of |
| 2142 |
\cs{printunsrtglossary} if you don't want the default. The glossary |
| 2143 |
won't be defined on the first run (if the definition is only |
| 2144 |
provided in the \ext{glstex} file) but \cs{printunsrtglossary} will |
| 2145 |
just give a warning if the type is undefined so it won't interrupt |
| 2146 |
the document build. |
| 2147 |
|
| 2148 |
If you want \bibgls\ to automatically provide unknown glossaries for |
| 2149 |
all entries that have the \field{type} field set (unrelated to the |
| 2150 |
\csopt{master}, \csopt{secondary}, \csopt{trigger-type} |
| 2151 |
and \csopt{ignored-type} options) |
| 2152 |
then use the \longarg{provide-glossaries} switch. |
| 2153 |
|
| 2154 |
The base \sty{glossaries} package provides a command that can be |
| 2155 |
used to test the existence of a glossary: |
| 2156 |
\begin{codeenv} |
| 2157 |
\ics{ifglossaryexists}\margm{label}\margm{true}\margm{false} |
| 2158 |
\end{codeenv} |
| 2159 |
The unstarred version considers \glspl{ignoredglossary} as non-existent |
| 2160 |
(and so will do \meta{false} for an \gls{ignoredglossary}). As from |
| 2161 |
v4.46, this command now has a starred version |
| 2162 |
\ics{ifglossaryexists*} that considers \glspl{ignoredglossary} as |
| 2163 |
existing (and so will do \meta{true} for an \gls{ignoredglossary}). In |
| 2164 |
the event that you have an older version of \sty{glossaries}, the |
| 2165 |
\sty{glossaries-extra} package (v1.44+) will provide the starred |
| 2166 |
form if it hasn't been defined. (In general, it's best to have |
| 2167 |
up-to-date versions of both \sty{glossaries} and |
| 2168 |
\sty{glossaries-extra}.) |
| 2169 |
|
| 2170 |
\section{Resource Sets} |
| 2171 |
\label{sec:resourcesets} |
| 2172 |
|
| 2173 |
Each instance of \gls{GlsXtrLoadResources} (or |
| 2174 |
\gls{glsbibdata}) in the document represents a \igls{resourceset}. Each |
| 2175 |
\igls{resourceset} has one or more associated \iext{bib} files |
| 2176 |
that provides the data for that set. Command line switches |
| 2177 |
(\sectionref{sec:switches}) are applied to all \iglspl{resourceset}. |
| 2178 |
Resource options (\sectionref{sec:resourceopts}) are only applied to |
| 2179 |
that specific \igls{resourceset}. Each \igls{resourceset} is processed |
| 2180 |
in stages: |
| 2181 |
\begin{description} |
| 2182 |
|
| 2183 |
\item[Stage 1 (Initialisation)] Occurs after the \ext{aux} file has |
| 2184 |
been read, this stage parses the resource option list and ensures |
| 2185 |
options are valid and don't cause a conflict. The transcript will |
| 2186 |
show the message |
| 2187 |
\begin{alltt} |
| 2188 |
Initialising resource \meta{resource-name} |
| 2189 |
\end{alltt} |
| 2190 |
at this point. |
| 2191 |
|
| 2192 |
\item[Stage 2 (Parsing)] All the \iext{bib} files associated with |
| 2193 |
the \igls{resourceset} are parsed. Entry aliases (identified by |
| 2194 |
\csopt{entry-type-aliases}) are performed. The |
| 2195 |
\hyperref[sec:multientry]{multi-entry types}, such as |
| 2196 |
\atentry{bibtexentry} and \atentry{progenitor}, spawn their |
| 2197 |
associated \glspl{primaryentry}. Preamble information (provided by |
| 2198 |
\atentry{preamble}) is saved but is not interpreted at this stage. |
| 2199 |
The transcript will show the message |
| 2200 |
\begin{alltt} |
| 2201 |
Parsing bib files for resource \meta{resource-name} |
| 2202 |
\end{alltt} |
| 2203 |
at this point. |
| 2204 |
|
| 2205 |
\item[Stage 3 (Processing Entries)] |
| 2206 |
The transcript will show the message |
| 2207 |
\begin{alltt} |
| 2208 |
Processing resource \meta{resource-name} |
| 2209 |
\end{alltt} |
| 2210 |
at this point. |
| 2211 |
For each entry that was found in |
| 2212 |
the corresponding set of \ext{bib} files: |
| 2213 |
\begin{itemize} |
| 2214 |
\item Records are transferred to aliases if required (\csopt{alias-loc}). |
| 2215 |
\item Field checks and modifications are performed: |
| 2216 |
\begin{itemize} |
| 2217 |
\item field aliases are performed (\csopt{field-aliases}); |
| 2218 |
|
| 2219 |
\item known fields identified with \csopt{save-original-id} and |
| 2220 |
\csopt{save-original-entrytype} are set (internal fields that |
| 2221 |
don't have a corresponding key for use with \gls!{newglossaryentry} aren't |
| 2222 |
set until the \ext{glstex} file is written); |
| 2223 |
|
| 2224 |
\item ignored fields (identified by \csopt{ignore-fields}, not by \csopt{omit-fields}) are |
| 2225 |
removed; |
| 2226 |
|
| 2227 |
\item case-changes (for example, \csopt{short-case-change}) are |
| 2228 |
performed, except for the \field{name} field and fields identified |
| 2229 |
with \csopt{field-case-change}; |
| 2230 |
|
| 2231 |
\item suffixes are appended if required (for example, with |
| 2232 |
\csopt{short-plural-suffix}); |
| 2233 |
|
| 2234 |
\item field replications are made (\csopt{replicate-fields}), |
| 2235 |
and any of the above case-change or suffixes required |
| 2236 |
on the replicated fields are performed; |
| 2237 |
|
| 2238 |
\item the \field{group} field is assigned if \csopt[\meta{label}]{group} |
| 2239 |
is set; |
| 2240 |
|
| 2241 |
\item any variables (identified by \atentry{string}) are expanded |
| 2242 |
(if not already done in any of the previous steps); |
| 2243 |
|
| 2244 |
\item any fields that have been identified by |
| 2245 |
\csopt{bibtex-contributor-fields} are converted; |
| 2246 |
|
| 2247 |
\item any fields that have been identified with |
| 2248 |
\csopt{encapsulate-fields} are converted; |
| 2249 |
|
| 2250 |
\item any fields that have been identified with |
| 2251 |
\csopt{encapsulate-fields*} are converted; |
| 2252 |
|
| 2253 |
\item any fields that must be converted into a label form |
| 2254 |
(\csopt{labelify} or \csopt{labelify-list}) are processed; |
| 2255 |
|
| 2256 |
\item any fields identified by \csopt{dependency-fields} are parsed for |
| 2257 |
dependent entries; |
| 2258 |
|
| 2259 |
\item any fields whose value must be a label are interpreted |
| 2260 |
if \csopt{interpret-label-fields} is set; |
| 2261 |
|
| 2262 |
\item the \field{parent} field is adjusted according to the label prefix |
| 2263 |
settings (\csopt{label-prefix} etc); |
| 2264 |
|
| 2265 |
\item \ics{makefirstuc} protection is applied according to |
| 2266 |
\longarg{mfirstuc-protection} and \longarg{mfirstuc-math-protection}; |
| 2267 |
|
| 2268 |
\item fields are parsed for commands like \cs{gls} or |
| 2269 |
\cs{glshyperlink} and also checked for nested links if |
| 2270 |
\longarg{nested-link-check} is set; |
| 2271 |
|
| 2272 |
\item the \field{description} field is adjusted according to |
| 2273 |
\csopt{strip-trailing-nopost}; |
| 2274 |
|
| 2275 |
\item end punctuation is checked according to |
| 2276 |
\csopt{check-end-punctuation}; |
| 2277 |
|
| 2278 |
\item field assignments are made (\csopt{assign-fields}), |
| 2279 |
and any of the above case-change or suffixes required |
| 2280 |
by the destination fields are performed; |
| 2281 |
|
| 2282 |
\item \field{name} adjustment is performed if |
| 2283 |
\csopt{compound-adjust-name} is set (and the criteria is met); |
| 2284 |
|
| 2285 |
\item \field{name} case-change is performed if |
| 2286 |
\csopt{name-case-change} is set; |
| 2287 |
|
| 2288 |
\item if \csopt[true]{copy-alias-to-see} the \field{alias} is copied |
| 2289 |
to the \field{see} field; |
| 2290 |
|
| 2291 |
\item general field case changes identified by |
| 2292 |
\csopt{field-case-change} are performed; |
| 2293 |
|
| 2294 |
\item any fields that have been identified with |
| 2295 |
\csopt{interpret-fields} are replaced with their interpreted |
| 2296 |
values; |
| 2297 |
|
| 2298 |
\item any fields that have been identified with |
| 2299 |
\csopt{hex-unicode-fields} will have Unicode characters replaced; |
| 2300 |
|
| 2301 |
\item check for \field{nonumberlist}. |
| 2302 |
\end{itemize} |
| 2303 |
\item The dual version (if appropriate) is created. |
| 2304 |
\item \Glspl{record} are added to the entry's \igls{locationlist} (or transferred |
| 2305 |
to the \dual\slash\primary\ according to \csopt{combine-dual-locations}). |
| 2306 |
\item The \field{type}, \field{category} and \field{counter} fields |
| 2307 |
are set according to \csopt{type}, \csopt{dual-type}, |
| 2308 |
\csopt{category}, \csopt{dual-category}, \csopt{counter} and |
| 2309 |
\csopt{dual-counter}. |
| 2310 |
\item Filtering is applied (according to options like \csopt{match} |
| 2311 |
but not \csopt{selection} or \csopt{limit}). |
| 2312 |
\item Required fields are checked for existence. |
| 2313 |
\item Dependencies are registered (if |
| 2314 |
\csopt[recorded and deps]{selection} or \csopt[recorded and deps and |
| 2315 |
see]{selection}). |
| 2316 |
\item Any fields that have been identified by |
| 2317 |
\csopt{date-time-fields}, \csopt{date-fields} or \csopt{time-fields} |
| 2318 |
are converted. |
| 2319 |
\end{itemize} |
| 2320 |
If \csopt[recorded and deps and see]{selection} then any |
| 2321 |
\glspl{recordedentry} that have been cross-referenced by an |
| 2322 |
\gls{unrecordedentry}, will register a dependency with the |
| 2323 |
\gls{unrecordedentry}. |
| 2324 |
|
| 2325 |
The \gls{compoundentry} options \csopt{compound-dependent} and |
| 2326 |
\csopt{compound-add-hierarchy} are implemented, if enabled. |
| 2327 |
|
| 2328 |
Finally, \glspl{supplementalrecord} are added to entries. |
| 2329 |
|
| 2330 |
\item[Stage 4 (Selection, Sorting, Writing)] Entries are selected |
| 2331 |
from the list according to the \csopt{selection} setting, sorting is |
| 2332 |
performed (if required), truncation is applied (if \csopt{limit} is |
| 2333 |
set) and the \iext{glstex} file is written. |
| 2334 |
The transcript will show the message |
| 2335 |
\begin{alltt} |
| 2336 |
Selecting entries for resource \meta{resource-name} |
| 2337 |
\end{alltt} |
| 2338 |
or (if \csopt{master}) |
| 2339 |
\begin{alltt} |
| 2340 |
Processing master \meta{resource-name} |
| 2341 |
\end{alltt} |
| 2342 |
at this point. |
| 2343 |
|
| 2344 |
Options such as \csopt{copy-to-glossary} and \csopt{omit-fields} are |
| 2345 |
implemented when each entry has its definition written to the \ext{glstex} |
| 2346 |
file. This means that the omitted fields will still be available for actions |
| 2347 |
such as sorting, establishing dependencies, or field assignments. |
| 2348 |
|
| 2349 |
\end{description} |
| 2350 |
|
| 2351 |
Parent entries must always be in the same \igls{resourceset} as their |
| 2352 |
\glspl{childentry}. (They may be defined in different \ext{bib} files as |
| 2353 |
long as all those \ext{bib} files are listed in the same \csopt{src}.) |
| 2354 |
Other forms of dependencies may be in a |
| 2355 |
different \igls{resourceset} under certain circumstances. These types |
| 2356 |
of dependencies are instances of commands such as \cs{gls} being |
| 2357 |
found (for example, in the \field{description} field), or the |
| 2358 |
\glspl{cross-referencefield} (\field{see}, \field{seealso} or |
| 2359 |
\field{alias} or fields identified with \csopt{dependency-fields}) |
| 2360 |
in \glspl{recordedentry} that reference \glspl{unrecordedentry}. |
| 2361 |
|
| 2362 |
The \qt{cross-referenced by} dependencies enabled with |
| 2363 |
\csopt[recorded and deps and see]{selection} (where an |
| 2364 |
\gls{unrecordedentry} references a \gls{recordedentry} through the |
| 2365 |
\glspl{cross-referencefield}) \emph{aren't supported} across |
| 2366 |
\iglspl{resourceset} (even with \longarg{force-cross-resource-refs}). |
| 2367 |
|
| 2368 |
A \igls{crossresourceref} is a reference from a \gls{recordedentry} |
| 2369 |
provided in one \igls{resourceset} to an \gls{unrecordedentry} in |
| 2370 |
another \igls{resourceset}. Since the contents of each |
| 2371 |
\igls{resourceset}['s] preamble must be processed before fields can |
| 2372 |
be interpreted and one \igls{resourceset}['s] preamble may contain |
| 2373 |
definitions that override another, \iglspl{crossresourceref} can't |
| 2374 |
be supported if fields containing cross-referencing information need |
| 2375 |
to be interpreted. |
| 2376 |
|
| 2377 |
The \igls{crossresourceref} mode determines whether or not \bibgls\ |
| 2378 |
can support \iglspl{crossresourceref}. If enabled, the message |
| 2379 |
\begin{verbatim} |
| 2380 |
Cross-resource references allowed. |
| 2381 |
\end{verbatim} |
| 2382 |
will be written to the transcript otherwise the message is |
| 2383 |
\begin{verbatim} |
| 2384 |
Cross-resource references disabled. |
| 2385 |
\end{verbatim} |
| 2386 |
The mode can only be enabled if the following condition is satisfied: |
| 2387 |
\begin{itemize} |
| 2388 |
\item the interpreter is off (\longarg{no-interpret}), or |
| 2389 |
\item every \igls{resourceset} either doesn't have a preamble |
| 2390 |
(\atentry{preamble}) or has \csopt[false]{interpret-preamble} set. |
| 2391 |
\end{itemize} |
| 2392 |
If you know the preamble contents won't cause a problem, you |
| 2393 |
can force the \iglspl{crossresourceref} mode on with |
| 2394 |
\longarg{force-cross-resource-refs}. |
| 2395 |
|
| 2396 |
If you don't use either \csopt[recorded and |
| 2397 |
deps]{selection} or \csopt[recorded and deps and see]{selection} |
| 2398 |
then the dependencies aren't picked up for that \igls{resourceset} |
| 2399 |
(and so can't be cross-referenced from another \igls{resourceset}). |
| 2400 |
|
| 2401 |
Trails don't work with \iglspl{crossresourceref}. For example, if |
| 2402 |
entry $A$ has been recorded and depends on entry $B$ that hasn't been |
| 2403 |
recorded, then $B$ can be picked up from a different |
| 2404 |
\igls{resourceset}, but if $A$ and $B$ are in the same |
| 2405 |
\igls{resourceset} and $B$ is dependent on $C$ which is in a |
| 2406 |
different \igls{resourceset} then $C$ won't be picked up if it hasn't |
| 2407 |
been recorded because $B$ hasn't been recorded and is in a different |
| 2408 |
\igls{resourceset}. |
| 2409 |
|
| 2410 |
If the \igls{crossresourceref} mode is enabled then stage~3 and |
| 2411 |
stage~4 are processed in separate \idxpl{loop}, otherwise they are |
| 2412 |
processed in the same \idx{loop}. |
| 2413 |
|
| 2414 |
\section{\bibgls\ Quarks} |
| 2415 |
\label{sec:quarks} |
| 2416 |
|
| 2417 |
A \bibgls\ \idx{quark} is similar in principle to a \LaTeX3 quark, |
| 2418 |
in that it is a token that looks like a control sequence but isn't |
| 2419 |
intended to be interpreted as a \LaTeX\ command. Unlike \LaTeX3 |
| 2420 |
quarks, their name isn't prefixed with \csfmt{q\_} and can |
| 2421 |
coincidentally look the same as a \LaTeX\ command. This is |
| 2422 |
particularly the case with regular expressions that have escaped |
| 2423 |
characters to indicate a literal character. For example, in a |
| 2424 |
regular expression a pipe or vertical bar character \idx{regexpor} |
| 2425 |
indicates \qt{or}. If you want to match a literal pipe, you need to |
| 2426 |
identify this with \cs{quark.pipe}. This is distinct from, but |
| 2427 |
visually identical to, the \LaTeX\ command used to create a double |
| 2428 |
vertical bar in maths mode. |
| 2429 |
|
| 2430 |
The resource options provided in \gls{GlsXtrLoadResources} expand as |
| 2431 |
they are written to the \ext{aux} file. This allows commands to be |
| 2432 |
used within the resource options that expand to a complex option |
| 2433 |
that may be required multiple times. For example, |
| 2434 |
\ics{GlsXtrBibTeXEntryAliases} or \ics{glsxtrhyphenrules}. |
| 2435 |
Unfortunately, this means that quarks must be prevented from |
| 2436 |
expansion as they form part of the option syntax and are not |
| 2437 |
intended for use in the document. |
| 2438 |
|
| 2439 |
This means that, unless they happen to coincidentally be robust |
| 2440 |
commands, they must be preceded by either \ics{protect} or |
| 2441 |
\idx{cs.string}. Since \cs{protect} adds a space afterwards, |
| 2442 |
\idx{cs.string} is usually better if the syntax requires that spaces |
| 2443 |
after quarks are significant. |
| 2444 |
|
| 2445 |
This can lead to cumbersome expressions, but it's possible to |
| 2446 |
redefine \ics{glsxtrresourceinit} to locally redefine these quarks |
| 2447 |
to expand to detokenized forms of themselves. For example: |
| 2448 |
\begin{codeenv} |
| 2449 |
\cs{renewcommand}*\marg{\cs{glsxtrresourceinit}}\marg{\cmd{let}\cmd{u}\cs{glshex}} |
| 2450 |
\end{codeenv} |
| 2451 |
Since there are a number of these quarks, as from v1.51, |
| 2452 |
\sty{glossaries-extra-bib2gls} (which is automatically loaded with |
| 2453 |
\styopt{record}) provides \ics{GlsXtrResourceInitEscSequences}, |
| 2454 |
so you can change the above to the following: |
| 2455 |
\begin{codeenv} |
| 2456 |
\cs{renewcommand}*\marg{\cs{glsxtrresourceinit}}\marg{\comment{} |
| 2457 |
\cs{GlsXtrResourceInitEscSequences} |
| 2458 |
} |
| 2459 |
\end{codeenv} |
| 2460 |
Note that if new quarks, such as \gls{INTERPRETNOREPL} and \gls{REPLACESPCHARS}, |
| 2461 |
are added to \bibgls, they may not be included in \cs{GlsXtrResourceInitEscSequences} if they |
| 2462 |
were introduced to \bibgls\ after the version date of the \sty{glossaries-extra} |
| 2463 |
package installed on your system. In this case, you will need to add them. For example: |
| 2464 |
\begin{codeenv} |
| 2465 |
\cs{renewcommand}*\marg{\cs{glsxtrresourceinit}}\marg{\comment{} |
| 2466 |
\cs{GlsXtrResourceInitEscSequences} |
| 2467 |
\cmd{def}\gls{INTERPRETNOREPL}\marg{\idx{cs.string}\gls{INTERPRETNOREPL}}\comment{} |
| 2468 |
\cmd{def}\gls{REPLACESPCHARS}\marg{\idx{cs.string}\gls{REPLACESPCHARS}}\comment{} |
| 2469 |
} |
| 2470 |
\end{codeenv} |
| 2471 |
|
| 2472 |
|
| 2473 |
This will locally define the quarks listed below. Since |
| 2474 |
\cs{glsxtrresourceinit} is used in a scoped context, the |
| 2475 |
definitions only have an effect within the protected write, and so this |
| 2476 |
shouldn't interfere with the corresponding commands that are |
| 2477 |
required in the document. Note that these quarks should only be used |
| 2478 |
in their designated contexts. |
| 2479 |
|
| 2480 |
\begin{description} |
| 2481 |
|
| 2482 |
\item[General] \inlinedef{uhex} is recognised in certain resource options |
| 2483 |
(such as \csopt{field-concat-sep}) as indicating the Unicode |
| 2484 |
character with the given hexadecimal code. |
| 2485 |
|
| 2486 |
\item[Regular expressions] The following indicate a literal |
| 2487 |
character: |
| 2488 |
\glsadd{idx.periodchar}\inlinedef{quark.dot} |
| 2489 |
\glsadd{idx.backslashchar}\inlinedef{quark.backslash} |
| 2490 |
\glsadd{idx.slashchar}\inlinedef{quark.slash} |
| 2491 |
\glsadd{idx.pipechar}\inlinedef{quark.pipe} |
| 2492 |
\glsadd{idx.ampchar}\inlinedef{quark.amp} |
| 2493 |
\glsadd{idx.pluschar}\inlinedef{quark.plus} |
| 2494 |
\glsadd{idx.ltchar}\inlinedef{quark.lt} |
| 2495 |
\glsadd{idx.gtchar}\inlinedef{quark.gt} |
| 2496 |
\glsadd{idx.starchar}\inlinedef{quark.star} |
| 2497 |
\glsadd{idx.dollarchar}\inlinedef{quark.dollar} |
| 2498 |
\glsadd{idx.circumchar}\inlinedef{quark.circum} |
| 2499 |
\glsadd{idx.tildechar}\inlinedef{quark.tilde} |
| 2500 |
\glsadd{idx.openparenchar}\inlinedef{quark.openparen} |
| 2501 |
\glsadd{idx.closeparenchar}\inlinedef{quark.closeparen} |
| 2502 |
\glsadd{idx.opensqchar}\inlinedef{quark.opensq} |
| 2503 |
\glsadd{idx.closesqchar}\inlinedef{quark.closesq} |
| 2504 |
\glsadd{idx.doublequotechar}\inlinedef{quark.doublequote} |
| 2505 |
\glsadd{idx.hyphenchar}\inlinedef{quark.hyphen} |
| 2506 |
\glsadd{idx.questionchar}\inlinedef{quark.question} |
| 2507 |
\glsadd{idx.colonchar}\inlinedef{quark.colon} |
| 2508 |
\glsadd{idx.hashchar}\inlinedef{quark.hash}. |
| 2509 |
Note that \idxpl{regex} in resource options are typically |
| 2510 |
\gls{anchored}, so there shouldn't be any need to use \idx{regex.circum} |
| 2511 |
or \idx{regex.dollar} to denote the start and end. |
| 2512 |
|
| 2513 |
\item[Field assignments] The following commands may be used in the |
| 2514 |
\meta{element-list} syntax of \csopt{assign-fields}: |
| 2515 |
\gls{CS}, \gls{MGP}, \gls{LEN}, \gls{TRIM}, \gls{INTERPRET}, |
| 2516 |
\gls{INTERPRETNOREPL}, \gls{REPLACESPCHARS}, |
| 2517 |
\gls{LC}, \gls{UC}, \gls{FIRSTLC}, \gls{FIRSTUC}, and \gls{TITLE}. |
| 2518 |
|
| 2519 |
\item[Conditionals] The \meta{condition} part of the \csopt{assign-fields} |
| 2520 |
syntax recognises \gls{LEN}, \gls{CAT}, \gls{IN}, \gls{NIN}, \gls{PREFIXOF}, |
| 2521 |
\gls{NOTPREFIXOF}, \gls{SUFFIXOF}, \gls{NOTSUFFIXOF} and \gls{NULL}. |
| 2522 |
\end{description} |
| 2523 |
|
| 2524 |
Finally, this isn't actually a quark, but \inlinedef{cs} is defined |
| 2525 |
to expand to the literal string \csfmt{\meta{csname}} so you can use it for any |
| 2526 |
other escape sequences that aren't covered above. For example, |
| 2527 |
\code{\gls{cs}\marg{n}} for a newline \ics{n}. |
| 2528 |
|
| 2529 |
\section{Indexing} |
| 2530 |
|
| 2531 |
The dual index entries such as \atentry{dualindexentry} (described in |
| 2532 |
\sectionref{sec:dualentry}) are designed to provide a way of |
| 2533 |
including an entry in a glossary (with a description) and also |
| 2534 |
include the term (without the description) in an index. Additional |
| 2535 |
terms that should only appear in the index can be defined with |
| 2536 |
\atentry{index}. (See, for example, the \exfile{sample-multi1.tex} |
| 2537 |
and \exfile{sample-multi2.tex} sample files.) |
| 2538 |
|
| 2539 |
Although \bibgls\ is designed to create indexes as well as glossary |
| 2540 |
lists using the same interface (\cs{gls} etc), it is |
| 2541 |
possible to have a mixture of \bibgls\ and \ics{index}. For example: |
| 2542 |
\begin{codeenv} |
| 2543 |
\cmd{documentclass}\marg{report} |
| 2544 |
\strut |
| 2545 |
\cmd{usepackage}\marg{makeidx} |
| 2546 |
\cmd{usepackage}\oarg{\styopt{record}}\marg{glossaries-extra} |
| 2547 |
\strut |
| 2548 |
\cmd{makeindex} |
| 2549 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}} |
| 2550 |
\strut |
| 2551 |
\ics{glssetcategoryattribute}\marg{general}\marg{dualindex}\marg{true} |
| 2552 |
\cs{glssetcategoryattribute}\marg{symbol}\marg{dualindex}\marg{true} |
| 2553 |
\cs{glssetcategoryattribute}\marg{abbreviation}\marg{dualindex}\marg{true} |
| 2554 |
\strut |
| 2555 |
\cs{glssetcategoryattribute}\marg{general}\marg{indexname}\marg{hyperbf} |
| 2556 |
\cs{glssetcategoryattribute}\marg{symbol}\marg{indexname}\marg{hyperbf} |
| 2557 |
\cs{glssetcategoryattribute}\marg{abbreviation}\marg{indexname}\marg{hyperbf} |
| 2558 |
\strut |
| 2559 |
\cmd{begin}\marg{document} |
| 2560 |
\cmd{chapter}\marg{Example} |
| 2561 |
\cs{gls}\marg{bird}, \cs{gls}\marg{html}, \idx{mshiftchar}\cs{gls}\marg{v}\idx{mshiftchar} and \cs{glspl}\marg{goose}. |
| 2562 |
\strut |
| 2563 |
\cs{printunsrtglossaries} |
| 2564 |
\cmd{printindex} |
| 2565 |
\cmd{end}\marg{document} |
| 2566 |
\end{codeenv} |
| 2567 |
If the document is called \filefmt{myDoc.tex} then the document |
| 2568 |
build is: |
| 2569 |
\begin{verbatim} |
| 2570 |
pdflatex myDoc |
| 2571 |
bib2gls myDoc |
| 2572 |
pdflatex myDoc |
| 2573 |
makeindex myDoc.idx |
| 2574 |
pdflatex myDoc |
| 2575 |
\end{verbatim} |
| 2576 |
This requires an additional \LaTeX\ call between \bibgls\ and |
| 2577 |
\idx{makeindex} since the entries must be defined before they can be |
| 2578 |
indexed (and they can't be defined until \bibgls\ creates the |
| 2579 |
associated \ext{glstex} files). |
| 2580 |
|
| 2581 |
Note that this method will use the \field{sort} value obtained by \bibgls\ |
| 2582 |
as the \meta{sort} part within |
| 2583 |
\code{\cs{index}\marg{\meta{sort}@\meta{actual}}}. |
| 2584 |
Be careful if you use \idx{makeindex} as this can result in Unicode |
| 2585 |
characters appearing in the sort value, which \idx{makeindex} |
| 2586 |
doesn't support. |
| 2587 |
The \meta{actual} part is given by |
| 2588 |
\code{\ics{glsentryname}\margm{label}}. |
| 2589 |
(You can change the \meta{sort} and \meta{actual} parts by |
| 2590 |
redefining \ics{glsxtrautoindexassignsort} and |
| 2591 |
\ics{glsxtrautoindexentry}. See the \sty{glossaries-extra} manual |
| 2592 |
for further details.) |
| 2593 |
|
| 2594 |
\section{Security} |
| 2595 |
|
| 2596 |
\TeX\ Live come with security settings |
| 2597 |
\texmfcnf{openinany} and \texmfcnf{openoutany} that, respectively, |
| 2598 |
govern read and write file access (in addition to the operating |
| 2599 |
system's file permissions). \bibgls\ uses \idx{kpsewhich} to |
| 2600 |
determine these values and honours them. MikTeX doesn't use these |
| 2601 |
settings, so if these values are unset, \bibgls\ will default to |
| 2602 |
\code{a} (any) for \texmfcnf{openinany} and \code{p} (paranoid) for |
| 2603 |
\texmfcnf{openoutany}. |
| 2604 |
|
| 2605 |
The only external processes that are run by \bibgls\ are calls to |
| 2606 |
\idx{kpsewhich} to check the security settings and locate files on |
| 2607 |
\TeX's path. These are started with Java's \code{ProcessBuilder} |
| 2608 |
class so there should be no issues with spaces or shell special characters |
| 2609 |
in the argument. The \commonlongarg{debug} switch will write the process |
| 2610 |
call in the transcript file and will delimit the argument in the log |
| 2611 |
with single quote characters for convenience, but the process isn't |
| 2612 |
actually called in that way. |
| 2613 |
|
| 2614 |
\bibgls\ creates files with the extension \ext{glstex}, which are |
| 2615 |
input by \gls{GlsXtrLoadResources} (and therefore by the shortcut |
| 2616 |
\gls{glsbibdata}). This extension is fixed and is imposed |
| 2617 |
by both \bibgls\ and \gls{GlsXtrLoadResources}. \bibgls\ also creates |
| 2618 |
a transcript file with the default extension \ext{glg}. This may be |
| 2619 |
overridden by the \longarg{log-file} switch, but \bibgls\ always |
| 2620 |
forbids write access to any file with the following extensions: |
| 2621 |
\extfmt{tex}, \extfmt{ltx}, \extfmt{sty}, \extfmt{cls}, |
| 2622 |
\extfmt{bib}, \extfmt{dtx}, \extfmt{ins}, \extfmt{def} and |
| 2623 |
\extfmt{ldf}. |
| 2624 |
|
| 2625 |
\section{Localisation} |
| 2626 |
\label{sec:lang.xml} |
| 2627 |
|
| 2628 |
The messages produced by \bibgls\ are fetched from a resource file |
| 2629 |
called \metafilefmt{bib2gls-}{lang}{.xml}, where \meta{lang} is a |
| 2630 |
valid \idx{IETF} language tag. |
| 2631 |
|
| 2632 |
The appropriate file is searched for in the following order, where |
| 2633 |
\meta{locale} is the \gls{Java-locale} or the value supplied |
| 2634 |
by the \commonlongarg{locale} switch: |
| 2635 |
\begin{enumerate} |
| 2636 |
\item \meta{lang} exactly matches \meta{locale}. |
| 2637 |
For example, my locale is \code{en-GB}, so \bibgls\ will first search |
| 2638 |
for \filefmt{bib2gls-en-GB.xml}. This file doesn't exist, so it will |
| 2639 |
try again. |
| 2640 |
|
| 2641 |
\item If \meta{locale} has an associated script, the |
| 2642 |
next try is with \meta{lang} set to \meta{lang |
| 2643 |
code}\code{-}\meta{script} where \meta{lang code} is the two |
| 2644 |
letter ISO language code and \meta{script} is the script code. |
| 2645 |
For example, if \meta{locale} is \code{sr-RS-Latn} |
| 2646 |
then \bibgls\ will search for \filefmt{bib2gls-sr-Latn.xml} if |
| 2647 |
\filefmt{bib2gls-sr-RS-Latn.xml} doesn't exist. |
| 2648 |
|
| 2649 |
\item The final attempt is with \meta{lang} set to just the two |
| 2650 |
letter ISO language code. For example, \filefmt{bib2gls-sr.xml}. |
| 2651 |
\end{enumerate} |
| 2652 |
|
| 2653 |
If there is no match, \bibgls\ will fallback on the English resource file |
| 2654 |
\file{bib2gls-en.xml}. |
| 2655 |
(Currently only \file{bib2gls-en.xml} exists as my language skills aren't up |
| 2656 |
to translating it. Any volunteers who want to provide other language |
| 2657 |
resource files would be much appreciated.) |
| 2658 |
|
| 2659 |
In addition to the main language file, it's possible to have |
| 2660 |
supplementary files that provide text that matches the |
| 2661 |
\gls{resource-locale}. These are in files called |
| 2662 |
\metafilefmt{bib2gls-extra-}{lang}{.xml}, which has the same format |
| 2663 |
as \metafilefmt{bib2gls-}{lang}{.xml}. These supplementary files |
| 2664 |
will be loaded automatically if they exist and if you have |
| 2665 |
\styfmt{glossaries-extra} v1.51+ (which will save a list of all |
| 2666 |
tracked languages for the document). |
| 2667 |
|
| 2668 |
Note that if you use the \csopt[true]{loc-prefix} option, the |
| 2669 |
textual labels (\qt{Page} and \qt{Pages} in English) will be |
| 2670 |
first be attempted from the supplementary file with the tags |
| 2671 |
\code{tag.\meta{lang}.page} and \code{tag.\meta{lang}.pages} |
| 2672 |
(where \meta{lang} is the language code) and then, if not |
| 2673 |
found, from the main resource file using the tags \code{tag.page} |
| 2674 |
and \code{tag.pages}. In the event that the loaded resource file |
| 2675 |
doesn't match the document language and there's no supplementary |
| 2676 |
file, you will have to manually set |
| 2677 |
the correct translation (in English, this would be |
| 2678 |
\csopt[Page\dcomma Pages]{loc-prefix}). The default definition of |
| 2679 |
\gls!{bibglspassim} is also obtained from the resource file in a |
| 2680 |
similar manner. |
| 2681 |
|
| 2682 |
There are also keys in the resource file to assist case-conversion. |
| 2683 |
Currently, there's only support for the Dutch \qt{IJ} case. |
| 2684 |
|
| 2685 |
\section{Conditional Document Build} |
| 2686 |
|
| 2687 |
If you are using a document build method that tries to determine |
| 2688 |
whether or not \bibgls\ should be run, you can find the information |
| 2689 |
by searching the \iext{aux} file for instances of |
| 2690 |
\nosecdef{glsxtr@resource} |
| 2691 |
Each instance corresponds to an instance of \gls{GlsXtrLoadResources} (or \gls{glsbibdata}) |
| 2692 |
where \meta{filename} is the base name of the \iext{glstex} file |
| 2693 |
that \bibgls\ needs to create for this resource set. If the |
| 2694 |
\meta{options} part is missing the \csopt{src} option, then |
| 2695 |
\meta{filename} also indicates the base name for the \iext{bib} file. |
| 2696 |
In the case of \gls{glsbibdata}, the \csopt{src} option is |
| 2697 |
automatically set to the mandatory argument. |
| 2698 |
|
| 2699 |
So the simplest check to determine if \bibgls\ needs to be run is to test |
| 2700 |
if the \iext{aux} file contains \gls{glsxtr@resource}. For |
| 2701 |
example, with \idx{arara} version 4.0: |
| 2702 |
\begin{codeenv} |
| 2703 |
\% arara: bib2gls if found("aux", "glsxtr@resource") |
| 2704 |
\end{codeenv} |
| 2705 |
A sophisticated method could check if |
| 2706 |
\meta{filename}\ext{glstex} is missing or is older than the document |
| 2707 |
\ext{tex} file for each instance of \gls{glsxtr@resource} found in |
| 2708 |
the \ext{aux} file. |
| 2709 |
|
| 2710 |
It might also be possible, although far more complex, to |
| 2711 |
parse the \meta{options} part in each instance of \gls{glsxtr@resource} |
| 2712 |
for \csopt{src} and determine if the corresponding \ext{bib} file or |
| 2713 |
files are newer than the \ext{tex} file. |
| 2714 |
|
| 2715 |
It's not possible to determine if the \glspl{locationlist} require |
| 2716 |
updating, just as it's not possible to do this for the |
| 2717 |
\idx{toc}, list of figures, list of tables etc. (Or, if it could |
| 2718 |
be implemented, the required code would make the document build far |
| 2719 |
more complicated.) |
| 2720 |
|
| 2721 |
In general, the basic algorithm is: |
| 2722 |
\begin{enumerate} |
| 2723 |
\item Run \LaTeX\ (or PDF\LaTeX\ etc). |
| 2724 |
|
| 2725 |
\item If \gls{glsxtr@resource} is found in the \ext{aux} file then: |
| 2726 |
|
| 2727 |
\begin{enumerate} |
| 2728 |
\item run \bibgls; |
| 2729 |
\item run \LaTeX\ (or PDF\LaTeX\ etc). |
| 2730 |
\end{enumerate} |
| 2731 |
|
| 2732 |
\item If \ics{@istfilename} is found in the \ext{aux} file then: |
| 2733 |
|
| 2734 |
\begin{enumerate} |
| 2735 |
\item run \idx{makeglossaries} (or \idx{makeglossaries-lite}); |
| 2736 |
\item run \LaTeX\ (or PDF\LaTeX\ etc). |
| 2737 |
\end{enumerate} |
| 2738 |
|
| 2739 |
\end{enumerate} |
| 2740 |
This allows for the \styopt[alsoindex]{record} package option. See |
| 2741 |
also |
| 2742 |
\href{https://www.dickimaw-books.com/latex/buildglossaries}{\qt{Incorporating |
| 2743 |
\idx[hyper=false,noindex]{makeglossaries} or |
| 2744 |
\idx[hyper=false,noindex]{makeglossaries-lite} or \bibgls\ into |
| 2745 |
the document build}}~\cite{buildglossaries}. |
| 2746 |
|
| 2747 |
\section{Manual Installation} |
| 2748 |
|
| 2749 |
In general it's best to install \bibgls\ via your \TeX\ package manager. |
| 2750 |
However, if you are unable to do this or if you are testing a development version, |
| 2751 |
you can install manually using the instructions below. |
| 2752 |
Replace \meta{TEXMF} with the path to your local or home TEXMF tree |
| 2753 |
(for example, \filefmt{\glstildechar/texmf}). |
| 2754 |
|
| 2755 |
Copy the files provided to the following locations: |
| 2756 |
\begin{itemize} |
| 2757 |
\item \meta{TEXMF}\filefmt{/scripts/bib2gls/bib2gls.jar} |
| 2758 |
(Java application.) |
| 2759 |
\item \meta{TEXMF}\filefmt{/scripts/bib2gls/convertgls2bib.jar} |
| 2760 |
(Java application.) |
| 2761 |
\item \meta{TEXMF}\filefmt{/scripts/bib2gls/datatool2bib.jar} |
| 2762 |
(Java application.) |
| 2763 |
\item \meta{TEXMF}\filefmt{/scripts/bib2gls/bibglscommon.jar} |
| 2764 |
(Java library.) |
| 2765 |
\item \meta{TEXMF}\filefmt{/scripts/bib2gls/texparserlib.jar} |
| 2766 |
(Java library.) |
| 2767 |
\item \meta{TEXMF}\filefmt{/scripts/bib2gls/resources/bib2gls-en.xml} |
| 2768 |
(English resource file.) |
| 2769 |
\item \meta{TEXMF}\filefmt{/scripts/bib2gls/resources/bib2gls-extra-en.xml} |
| 2770 |
(Extra English resource file.) |
| 2771 |
\item \meta{TEXMF}\filefmt{/scripts/bib2gls/resources/bib2gls-extra-nl.xml} |
| 2772 |
(Extra Dutch resource file.) |
| 2773 |
\item \meta{TEXMF}\filefmt{/doc/support/bib2gls/bib2gls.pdf} |
| 2774 |
(This document.) |
| 2775 |
\item \meta{TEXMF}\filefmt{/doc/support/bib2gls/bib2gls-begin.pdf} |
| 2776 |
(Introductory guide.) |
| 2777 |
\end{itemize} |
| 2778 |
If you use the Unix \appfmt{man} command, copy the |
| 2779 |
\filefmt{bib2gls.1} and \filefmt{convertgls2bib.1} files to the |
| 2780 |
appropriate location. |
| 2781 |
|
| 2782 |
If you are using a Unix-like system, there are also bash scripts |
| 2783 |
provided called \file{bib2gls.sh}, \file{convertgls2bib.sh} and \file{datatool2bib.sh}. |
| 2784 |
Either copy them directly to somewhere on your path without the \iext{sh} |
| 2785 |
extension, for example: |
| 2786 |
\begin{verbatim} |
| 2787 |
cp bib2gls.sh ~/bin/bib2gls |
| 2788 |
cp convertgls2bib.sh ~/bin/convertgls2bib |
| 2789 |
cp datatool2bib.sh ~/bin/datatool2bib |
| 2790 |
\end{verbatim} |
| 2791 |
or copy the files to |
| 2792 |
\meta{TEXMF}\filefmt{/scripts/bib2gls/} and create a |
| 2793 |
symbolic link to them called just \filefmt{bib2gls}, |
| 2794 |
\filefmt{convertgls2bib} and \filefmt{datatool2bib} from somewhere on |
| 2795 |
your path, for example: |
| 2796 |
\begin{verbatim} |
| 2797 |
cp bib2gls.sh ~/texmf/scripts/bib2gls/ |
| 2798 |
cp convertgls2bib.sh ~/texmf/scripts/bib2gls/ |
| 2799 |
cp datatool2bib.sh ~/texmf/scripts/bib2gls/ |
| 2800 |
cd ~/bin |
| 2801 |
ln -s ~/texmf/scripts/bib2gls/bib2gls.sh bib2gls |
| 2802 |
ln -s ~/texmf/scripts/bib2gls/convertgls2bib.sh convertgls2bib |
| 2803 |
ln -s ~/texmf/scripts/bib2gls/datatool2bib.sh datatool2bib |
| 2804 |
\end{verbatim} |
| 2805 |
The \file{texparserlib.jar} file isn't an application but is a |
| 2806 |
library used by both \file{bib2gls.jar} and |
| 2807 |
\file{convertgls2bib.jar}, and so needs to be in the same class path. |
| 2808 |
(The library is in a separate |
| 2809 |
\href{https://github.com/nlct/texparser}{GitHub |
| 2810 |
repository}~\cite{texparser} as it's |
| 2811 |
also used by some of my other applications.) |
| 2812 |
|
| 2813 |
Windows users can create a \iext{bat} file that works in a |
| 2814 |
similar way to the bash scripts. To do this, create a file called |
| 2815 |
\file{bib2gls.bat} that contains the following: |
| 2816 |
\begin{verbatim} |
| 2817 |
@ECHO OFF |
| 2818 |
FOR /F "tokens=*" %%I IN ('kpsewhich --progname=bib2gls --format=texmfscripts |
| 2819 |
bib2gls.jar') DO SET JARPATH=%%I |
| 2820 |
java -jar "%JARPATH%" %* |
| 2821 |
\end{verbatim} |
| 2822 |
Save this file to somewhere on your system's path. |
| 2823 |
(Similarly for \filefmt{convertgls2bib} and \filefmt{datatool2bib}.) Note that \TeX\ |
| 2824 |
distributions for Windows usually convert \iext{jar} files to |
| 2825 |
executables. |
| 2826 |
|
| 2827 |
You may need to refresh \TeX's database to ensure that |
| 2828 |
\idx{kpsewhich} can find the \iext{jar} files. |
| 2829 |
To test that the application has been successfully installed, open a |
| 2830 |
command prompt or terminal and run the following command: |
| 2831 |
\begin{verbatim} |
| 2832 |
bib2gls --version |
| 2833 |
convertgls2bib --version |
| 2834 |
datatool2bib --version |
| 2835 |
\end{verbatim} |
| 2836 |
This should display the version information for both applications. |
| 2837 |
|
| 2838 |
\chapter{\texorpdfstring{\TeX}{TeX}\ Parser Library} |
| 2839 |
\label{sec:texparserlib} |
| 2840 |
|
| 2841 |
The \bibgls\ application requires the \TeX\ Parser Library |
| 2842 |
\file{texparserlib.jar}\footnote{\url{https://github.com/nlct/texparser}} |
| 2843 |
which is used to parse the \iext{aux} and \iext{bib} files. |
| 2844 |
|
| 2845 |
With the \longarg{interpret} switch on (default), this library is |
| 2846 |
also used to interpret the sort value when it contains a backslash |
| 2847 |
\idx{escchar} or a tilde \idx{nbspchar} or a dollar symbol |
| 2848 |
\idx{mshiftchar} or braces \idx{bgroupchar} \idx{egroupchar} |
| 2849 |
(and when the \csopt{sort} option is not |
| 2850 |
\optfmt{unsrt} or \optfmt{none} or \optfmt{use}).\footnote{The other |
| 2851 |
special characters are omitted from the check: the comment symbol |
| 2852 |
\idx{commentchar} is best avoided in field values, the subscript and |
| 2853 |
superscript characters \idx{sbchar} and \idx{spchar} should |
| 2854 |
either be encapsulated by \idx{mshiftchar} or by \cs{ensuremath}, which |
| 2855 |
will be picked up by the check for \idx{mshiftchar} or |
| 2856 |
\idx{escchar}, and the other special characters would |
| 2857 |
indicate something too complex for the interpreter to handle.} |
| 2858 |
|
| 2859 |
The other cases that the interpreter is used for are: |
| 2860 |
\begin{itemize} |
| 2861 |
\item when \csopt{set-widest} is used to determine the width of |
| 2862 |
the \field{name} field; |
| 2863 |
\item if \csopt{labelify} or \csopt{labelify-list} are set the |
| 2864 |
identified field values are first interpreted (if they contain |
| 2865 |
\idx{escchar} \idx{bgroupchar} \idx{egroupchar} |
| 2866 |
\idx{nbspchar} or \idx{mshiftchar}) before being converted to labels; |
| 2867 |
\item if \csopt[true]{interpret-label-fields} is set and the |
| 2868 |
\field{parent}, \field{category}, \field{type}, \field{group}, |
| 2869 |
\field{seealso} or \field{alias} fields contain \idx{escchar} |
| 2870 |
or \idx{bgroupchar} or \idx{egroupchar} the interpreter is used |
| 2871 |
since these fields must be just a label |
| 2872 |
(other special characters aren't checked as they won't expand to |
| 2873 |
characters allowed in a label). |
| 2874 |
\end{itemize} |
| 2875 |
|
| 2876 |
Information in the \ext{aux} file is parsed for specific commands |
| 2877 |
but the arguments of those commands are not interpreted so, for |
| 2878 |
example, UTF-8 characters that occur in any resource options will |
| 2879 |
need to be detokenized when using \sty{inputenc} to prevent |
| 2880 |
expansion when they are written to the \ext{aux} file. (In some |
| 2881 |
options, such as \csopt{sort-rule}, you can use \cs{glshex}\meta{hex} |
| 2882 |
syntax to specify a UTF-8 character.) Note that newer \LaTeX\ |
| 2883 |
kernels have better support for UTF-8 and this issue is less likely |
| 2884 |
to occur. |
| 2885 |
|
| 2886 |
The \longarg{no-interpret} switch will turn off the interpreter, but |
| 2887 |
the library will still be used to parse the \ext{aux} and \ext{bib} |
| 2888 |
files. Note that the \field{see} field doesn't use the interpreter |
| 2889 |
with \csopt[true]{interpret-label-fields} as |
| 2890 |
it may legitimately contain \LaTeX\ code in the optional tag part |
| 2891 |
(such as \cs{seealsoname} or \cs{alsoname}). |
| 2892 |
|
| 2893 |
The parser has a different concept of expansion to \TeX\ |
| 2894 |
and will expand some things that aren't expanded by \LaTeX\ |
| 2895 |
(such as \ics{MakeUppercase} and \ics{char}) and won't expand other commands |
| 2896 |
that would be expanded by \LaTeX\ (such as commands defined |
| 2897 |
in terms of complicated internals). |
| 2898 |
|
| 2899 |
If you get a \idx{StackOverflowError} while a field is being |
| 2900 |
interpreted (with a long stack trace that contains repeated file names and |
| 2901 |
line numbers) then it's likely you have an infinite \idx{loop}. For |
| 2902 |
example, this can be triggered if a field contains \csfmt{foo} that |
| 2903 |
has been defined as: |
| 2904 |
\begin{codeenv} |
| 2905 |
\cs{def}\cmd{foo}\marg{\cmd{foo}} |
| 2906 |
\end{codeenv} |
| 2907 |
This will obviously also cause an error in the \LaTeX\ document as |
| 2908 |
well (unless the document has a different definition that doesn't |
| 2909 |
have this unbounded recursion). |
| 2910 |
|
| 2911 |
The \file{texparserlib.jar} library is not a \TeX\ engine and there |
| 2912 |
are plenty of situations where it doesn't work. In particular, with |
| 2913 |
\bibgls, it's being used in a fragmented context without knowing |
| 2914 |
most of the packages used by the document or any custom commands or |
| 2915 |
environments provided within the document. |
| 2916 |
|
| 2917 |
\bibgls\ can detect from the log file a small |
| 2918 |
number of packages that the parser recognises. Note that in |
| 2919 |
some cases there's only very limited support. For example, |
| 2920 |
\isty{siunitx}'s \ics{si} and \ics{unit} commands are recognised but other |
| 2921 |
commands from that package aren't. See |
| 2922 |
\longargpageref{list-known-packages} for further details. |
| 2923 |
|
| 2924 |
Since the parser doesn't have a full set of commands available |
| 2925 |
within the \LaTeX\ document, when it encounters \ics{renewcommand} it |
| 2926 |
won't check if the command is undefined. If the command isn't |
| 2927 |
defined, it will simply behave like \cs{newcommand}. Whereas |
| 2928 |
with \ics{providecommand} the parser will only define the command |
| 2929 |
if it's unrecognised. |
| 2930 |
|
| 2931 |
The interpreter has its own internal implementation of the |
| 2932 |
glossary-related commands listed in \tableref{tab:bibglsdefs}. These |
| 2933 |
may be overridden by custom packages provided with the |
| 2934 |
\longarg{custom-packages} switch. Note that commands that reference |
| 2935 |
an entry, such as \cs{glsentryname}, aren't guaranteed to work |
| 2936 |
across \iglspl{resourceset} and will only be able to look up field |
| 2937 |
values that are known to \bibgls. (For example, the \field{name} |
| 2938 |
field for abbreviations is typically set by the associated |
| 2939 |
abbreviation style, which isn't available to \bibgls.) |
| 2940 |
|
| 2941 |
\begin{table}[htbp] |
| 2942 |
\caption{Glossary-Related Commands Implemented by the \bibgls\ Interpreter} |
| 2943 |
\label{tab:bibglsdefs} |
| 2944 |
\setlength{\tabcolsep}{4pt}% |
| 2945 |
\centering |
| 2946 |
\tablelistcs{3}{glsxtrprovidecommand,bibglsuppercase,bibglslowercase,bibglsfirstuc,% |
| 2947 |
bibglstitlecase,GlsXtrEnableInitialTagging,bibglscontributorlist,% |
| 2948 |
bibglshyperlink,glshyperlink,bibglscontributor,bibglsdatetime,% |
| 2949 |
bibglsdate,bibglstime,glsentryname,glsentrytext,glsentryshort,% |
| 2950 |
glsentrylong,glsentryfirst,glsentrysymbol,glsentryuseri,% |
| 2951 |
glsentryuserii,glsentryuseriii,glsentryuseriv,glsentryuserv,% |
| 2952 |
glsentryuservi,glsentryplural,glsentryfirstplural,glsentryshortpl,% |
| 2953 |
glsentrylongpl,glsentrysymbolplural,Glsentryname,Glsentrytext,% |
| 2954 |
Glsentryshort,Glsentrylong,Glsentryfirst,Glsentrysymbol,% |
| 2955 |
Glsentryuseri,Glsentryuserii,Glsentryuseriii,Glsentryuseriv,% |
| 2956 |
Glsentryuserv,Glsentryuservi,Glsentryplural,Glsentryfirstplural,Glsentryshortpl,% |
| 2957 |
Glsentrylongpl,Glsentrysymbolplural,bibglshashchar,bibglsunderscorechar,% |
| 2958 |
bibglsdollarchar,bibglsampersandchar,bibglscircumchar,glsbackslash,glstildechar,glsopenbrace,glsclosebrace,glspercentchar,% |
| 2959 |
glsxtrusefield,Glsxtrusefield,GLSxtrusefield,glsentrytitlecase,% |
| 2960 |
glsxtrhiernamesep,glsxtrhiername,Glsxtrhiername,GlsXtrhiername,% |
| 2961 |
GLSxtrhiername,GLSXTRhiername} |
| 2962 |
\end{table} |
| 2963 |
|
| 2964 |
If a command isn't recognised, you can provide it in the |
| 2965 |
\atentry{preamble} and use \ics{char} to map a symbol to the most |
| 2966 |
appropriate Unicode character. For example, suppose your document |
| 2967 |
loads a package that provides symbols for use on maps, such as |
| 2968 |
\csfmt{Harbour}, \csfmt{Battlefield} and \csfmt{Stadium}, then you |
| 2969 |
can provide versions of these commands just for \bibgls's |
| 2970 |
use:\footnote{These commands won't work with PDF\LaTeX, as the |
| 2971 |
\cs{char} values are too large, but they're fine for \bibgls.} |
| 2972 |
\begin{codeenv} |
| 2973 |
\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{Harbour}}\marg{\charhex{2693}} |
| 2974 |
\cs{providecommand}\marg{\cmd{Battlefield}}\marg{\charhex{2694}} |
| 2975 |
\cs{providecommand}\marg{\cmd{Stadium}}\marg{\charhex{26BD}}}} |
| 2976 |
\end{codeenv} |
| 2977 |
Since these use \cs{providecommand}, they won't overwrite the |
| 2978 |
document's version (provided these commands have been defined before |
| 2979 |
\gls!{GlsXtrLoadResources}). Alternatively, you can instruct \bibgls\ |
| 2980 |
to not write the \atentry{preamble} contents to the resource file |
| 2981 |
using \csopt[false]{write-preamble}. Now you can either sort these |
| 2982 |
symbols by |
| 2983 |
their Unicode values (\csopt[letter-case]{sort}) or provide a custom |
| 2984 |
rule that recognises these Unicode characters (for example, |
| 2985 |
\csopt[custom]{sort}, |
| 2986 |
\csopt[\cs{glshex}2694 \string< \cs{glshex}2693 \string< \cs{glshex}26BD]{sort-rule}). |
| 2987 |
|
| 2988 |
Another approach is to use \ics{IfTeXParserLib}, which is defined by |
| 2989 |
the \texparserlib\ to expand to its first argument. The |
| 2990 |
\sty{glossaries-extra-bib2gls} package provides a definition that |
| 2991 |
expands to its second argument, so that command may be used to |
| 2992 |
provide alternative code. For example: |
| 2993 |
\begin{codeenv} |
| 2994 |
\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{Ord}}[1]\marg{\comment{} |
| 2995 |
\cs{IfTeXParserLib} |
| 2996 |
\marg{\ics{bibglspaddigits}\marg{2}\marg{\idx{param}1}}\comment{interpreter} |
| 2997 |
\marg{\cs{MakeUppercase}\marg{\cmd{romannumeral} \idx{param}1}}\comment{document} |
| 2998 |
}}} |
| 2999 |
\atentry{index}\marg{John-IV, |
| 3000 |
\field{name}=\marg{John\idx{nbspchar}\cmd{Ord}\marg{4}} |
| 3001 |
} |
| 3002 |
\atentry{index}\marg{John-VI, |
| 3003 |
\field{name}=\marg{John\idx{nbspchar}\cmd{Ord}\marg{6}} |
| 3004 |
} |
| 3005 |
\atentry{index}\marg{John-IX, |
| 3006 |
\field{name}=\marg{John\idx{nbspchar}\cmd{Ord}\marg{9}} |
| 3007 |
} |
| 3008 |
\atentry{index}\marg{John-XII, |
| 3009 |
\field{name}=\marg{John\idx{nbspchar}\cmd{Ord}\marg{12}} |
| 3010 |
} |
| 3011 |
\end{codeenv} |
| 3012 |
The sort values for these entries will be: \qt{John 04}, \qt{John |
| 3013 |
06}, \qt{John 09} and \qt{John 12}, but in the document text they |
| 3014 |
will be typeset as \qt{John~IV}, \qt{John~VI}, \qt{John~IX} and |
| 3015 |
\qt{John~XII}. Note that \ics{bibglspaddigits} is only recognised by |
| 3016 |
the \bibgls\ interpreter. Alternatively, you can use the |
| 3017 |
\csopt{sort-number-pad} option to pad the numbers (or use |
| 3018 |
\ics{dtlpadleadingzeros} which is also recognised by the |
| 3019 |
\texparserlib\ and \sty{datatool-base} v3.0+). |
| 3020 |
|
| 3021 |
There is a similar command with reversed syntax \ics{IfNotBibGls}, |
| 3022 |
which is defined by \sty{glossaries-extra-bib2gls} to expand to its |
| 3023 |
first argument. The \bibgls\ interpreter defines this command to |
| 3024 |
expand to its second argument. |
| 3025 |
|
| 3026 |
\TeX\ syntax can be quite complicated and, in some cases, far too |
| 3027 |
complicated for simple \idxpl!{regex}. The \texparserlib\ performs |
| 3028 |
better than a simple pattern match, and that's the purpose of |
| 3029 |
\file{texparserlib.jar} and why it's used by \bibgls\ (and by |
| 3030 |
\idx!{convertgls2bib}). When the \commonlongarg{debug} mode is on, any |
| 3031 |
warnings or errors triggered by the interpreter will be written to |
| 3032 |
the transcript prefixed with \code{texparserlib:} (the results of |
| 3033 |
the conversions will be included in the transcript as informational |
| 3034 |
messages prefixed with \code{texparserlib:} even with |
| 3035 |
\commonlongarg{no-debug}). |
| 3036 |
|
| 3037 |
For example, suppose the \ext{bib} file includes: |
| 3038 |
\begin{codeenv} |
| 3039 |
\atentry{preamble}\marg{ |
| 3040 |
\qtdelim{\cs{providecommand}\marg{\cmd{mtx}}[1]\marg{\cs{boldsymbol}\marg{\idx{param}1}} |
| 3041 |
\cs{providecommand}\marg{\cmd{set}}[1]\marg{\ics{mathcal}\marg{\idx{param}1}} |
| 3042 |
\cs{providecommand}\marg{\cmd{card}}[1]\marg{|\cmd{set}\marg{\idx{param}1}|} |
| 3043 |
\cs{providecommand}\marg{\cmd{imaginary}}\marg{i}}} |
| 3044 |
\strut |
| 3045 |
\atentry{entry}\marg{M, |
| 3046 |
\field{name}=\marg{\marg{}\idx{mshiftchar}\cmd{mtx}\marg{M}\idx{mshiftchar}}, |
| 3047 |
\field{text}=\marg{\cmd{mtx}\marg{M}}, |
| 3048 |
\field{description}=\marg{a matrix} |
| 3049 |
} |
| 3050 |
\strut |
| 3051 |
\atentry{entry}\marg{v, |
| 3052 |
\field{name}=\marg{\marg{}\idx{mshiftchar}\cs{vec}\marg{v}\idx{mshiftchar}}, |
| 3053 |
\field{text}=\marg{\cs{vec}\marg{v}}, |
| 3054 |
\field{description}=\marg{a vector} |
| 3055 |
} |
| 3056 |
\strut |
| 3057 |
\atentry{entry}\marg{S, |
| 3058 |
\field{name}=\marg{\marg{}\idx{mshiftchar}\cmd{set}\marg{S}\idx{mshiftchar}}, |
| 3059 |
\field{text}=\marg{\cmd{set}\marg{S}}, |
| 3060 |
\field{description}=\marg{a set} |
| 3061 |
} |
| 3062 |
\strut |
| 3063 |
\atentry{entry}\marg{card, |
| 3064 |
\field{name}=\marg{\marg{}\idx{mshiftchar}\cmd{card}\marg{S}\idx{mshiftchar}}, |
| 3065 |
\field{text}=\marg{\cmd{card}\marg{S}}, |
| 3066 |
\field{description}=\marg{the cardinality of the set \idx{mshiftchar}\cmd{set}\marg{S}\idx{mshiftchar}} |
| 3067 |
} |
| 3068 |
\strut |
| 3069 |
\atentry{entry}\marg{i, |
| 3070 |
\field{name}=\marg{\marg{}\idx{mshiftchar}\cmd{imaginary}\idx{mshiftchar}}, |
| 3071 |
\field{text}=\marg{\cmd{imaginary}}, |
| 3072 |
\field{description}=\marg{square root of minus one (\idx{mshiftchar}\cmd{sqrt}\marg{-1}\idx{mshiftchar})} |
| 3073 |
} |
| 3074 |
\end{codeenv} |
| 3075 |
(The empty group at the start of the \field{name} fields |
| 3076 |
protects against the possibility that the \catattr{glossname} |
| 3077 |
category attribute might be set to \optfmt{firstuc}, which |
| 3078 |
automatically converts the first letter of the name to |
| 3079 |
\idx{uppercase} when displaying the glossary. See also |
| 3080 |
\longarg{mfirstuc-protection} and |
| 3081 |
\longarg{mfirstuc-math-protection}.) |
| 3082 |
|
| 3083 |
None of these entries have a \field{sort} field so the \field{name} |
| 3084 |
is used (see \sectionref{sec:fallbacks}). If the \gls{entrytype} had |
| 3085 |
been \atentry{symbol} instead, the fallback would be the entry's |
| 3086 |
label. This means that with \atentry{symbol} instead of |
| 3087 |
\atentry{entry}, and the default \csopt[sort]{sort-field}, and with |
| 3088 |
\csopt[letter-case]{sort}, these entries will be defined in the |
| 3089 |
order: \code{M}, \code{S}, \code{card}, \code{i}, \code{v} (since |
| 3090 |
this is the case-sensitive letter order of the labels) whereas with |
| 3091 |
\csopt[letter-nocase]{sort-field}, the order will be: \code{card}, |
| 3092 |
\code{i}, \code{M}, \code{S}, \code{v} (since this is the |
| 3093 |
case-insensitive letter order of the labels). |
| 3094 |
|
| 3095 |
However, with \atentry{entry}, the fallback field will be taken from |
| 3096 |
the \field{name} which in the above example contains \TeX\ code, so |
| 3097 |
\bibgls\ will use \file{texparserlib.jar} to interpret this code. |
| 3098 |
The library has several different ways of writing the processed |
| 3099 |
code. For simplicity, \bibgls\ uses the library's HTML output and |
| 3100 |
then strips the HTML markup and trims any leading or trailing |
| 3101 |
spaces. The library method that writes \idx{non-ASCII} characters |
| 3102 |
using \qtt{\&x\meta{hex};} markup is overridden by \bibgls\ to just |
| 3103 |
write the actual Unicode character, which means that the letter-based |
| 3104 |
sorting options will sort according to the integer value \meta{hex} |
| 3105 |
rather than the string \qtt{\&x\meta{hex};}. |
| 3106 |
|
| 3107 |
The interpreter is first passed the code provided with |
| 3108 |
\atentry{preamble}: |
| 3109 |
\begin{codeenv} |
| 3110 |
\cs{providecommand}\marg{\cmd{mtx}}[1]\marg{\cs{boldsymbol}\marg{\idx{param}1}} |
| 3111 |
\cs{providecommand}\marg{\cmd{set}}[1]\marg{\cs{mathcal}\marg{\idx{param}1}} |
| 3112 |
\cs{providecommand}\marg{\cmd{card}}[1]\marg{|\cmd{set}\marg{\idx{param}1}|} |
| 3113 |
\cs{providecommand}\marg{\cmd{imaginary}}\marg{i} |
| 3114 |
\end{codeenv} |
| 3115 |
(unless \csopt[false]{interpret-preamble}). |
| 3116 |
This means that the provided commands are now recognised by the |
| 3117 |
interpreter when it has to parse the fields later. |
| 3118 |
|
| 3119 |
In the case of the \code{M} entry in the example above, the |
| 3120 |
code that's passed to the interpreter is: |
| 3121 |
\begin{verbatim} |
| 3122 |
{}$\mtx{M}$ |
| 3123 |
\end{verbatim} |
| 3124 |
The transcript (\iext{glg}) file will show the results of the |
| 3125 |
conversion: |
| 3126 |
\begin{verbatim} |
| 3127 |
texparserlib: {}$\mtx{M}$ -> M |
| 3128 |
\end{verbatim} |
| 3129 |
So the \field{sort} value for this entry is set to \qtt{M}. The font |
| 3130 |
change (caused by math-mode and \ics{boldsymbol}) has been |
| 3131 |
ignored. The sort value therefore consists of a single Unicode |
| 3132 |
character \hex{4D} (Latin \idx!{uppercase} letter \qtt{M}, decimal value 77). |
| 3133 |
|
| 3134 |
For the \code{v} entry, the code is: |
| 3135 |
\begin{verbatim} |
| 3136 |
{}$\vec{v}$ |
| 3137 |
\end{verbatim} |
| 3138 |
The transcript shows: |
| 3139 |
\begin{alltt} |
| 3140 |
texparserlib: \marg{}\$\ics{vec}\marg{v}\$ -> \usebox\varrow |
| 3141 |
\end{alltt} |
| 3142 |
So the \field{sort} value for this entry is set to \qtt{\usebox\varrow}, |
| 3143 |
which consists of two Unicode characters \hex{76} |
| 3144 |
(Latin \idx!{lowercase} letter \qtt{v}, decimal value 118) and |
| 3145 |
\hex{20D7} (combining right arrow above, decimal value 8407). |
| 3146 |
|
| 3147 |
For the \code{set} entry, the code is: |
| 3148 |
\begin{verbatim} |
| 3149 |
{}$\set{S}$ |
| 3150 |
\end{verbatim} |
| 3151 |
The transcript shows: |
| 3152 |
\begin{verbatim} |
| 3153 |
texparserlib: {}$\set{S}$ -> S |
| 3154 |
\end{verbatim} |
| 3155 |
So the \field{sort} value for this entry is set to \qtt{S} (again |
| 3156 |
ignoring the font change). This consists of a single Unicode |
| 3157 |
character \hex{53} (Latin \idx!{uppercase} letter \qtt{S}, decimal value~83). |
| 3158 |
|
| 3159 |
For the \code{card} entry, the code is: |
| 3160 |
\begin{verbatim} |
| 3161 |
{}$\card{S}$ |
| 3162 |
\end{verbatim} |
| 3163 |
The transcript shows: |
| 3164 |
\begin{verbatim} |
| 3165 |
texparserlib: {}$\card{S}$ -> |S| |
| 3166 |
\end{verbatim} |
| 3167 |
So the \field{sort} value for this entry is set to \qtt{|S|} |
| 3168 |
(the \textbar\ characters from the definition of \csfmt{card} provided |
| 3169 |
in \atentry{preamble} have been included, but the |
| 3170 |
font change has been discarded). In this case the sort value |
| 3171 |
consists of three Unicode characters \hex{7C} (vertical line, decimal |
| 3172 |
value 124), |
| 3173 |
\hex{53} (Latin \idx!{uppercase} letter \qtt{S}, decimal value 83) and |
| 3174 |
\hex{7C} again. |
| 3175 |
If \csopt[false]{interpret-preamble} had been used, \csfmt{card} |
| 3176 |
wouldn't be recognised and would be discarded leaving just \qtt{S} |
| 3177 |
as the sort value. |
| 3178 |
|
| 3179 |
(Note that if \ics{vert} is used instead of \textbar\ then it would |
| 3180 |
be converted into the mathematical operator \hex{2223} and result in |
| 3181 |
a different order.) |
| 3182 |
|
| 3183 |
For the \code{i} entry, the code is: |
| 3184 |
\begin{verbatim} |
| 3185 |
{}$\imaginary$ |
| 3186 |
\end{verbatim} |
| 3187 |
The transcript shows: |
| 3188 |
\begin{verbatim} |
| 3189 |
texparserlib: {}$\imaginary$ -> i |
| 3190 |
\end{verbatim} |
| 3191 |
So the \field{sort} value for this entry is set to \qtt{i}. |
| 3192 |
If \csopt[false]{interpret-preamble} had been used, \csfmt{imaginary} |
| 3193 |
wouldn't be recognised and would be discarded, leaving an empty sort |
| 3194 |
value. |
| 3195 |
|
| 3196 |
This means that in the case of the default \csopt[sort]{sort-field} with |
| 3197 |
\csopt[letter-case]{sort}, these entries will be defined in |
| 3198 |
the order: \code{M} ($\mtx{M}$), \code{S} ($\set{S}$), |
| 3199 |
\code{i} ($\imaginary$), \code{v} ($\vec{v}$) and |
| 3200 |
\code{card} ($\card{S}$). |
| 3201 |
In this case, the entries have been sorted according to |
| 3202 |
the character codes. If you run \bibgls\ with \commonlongarg{verbose} |
| 3203 |
the decimal character codes will be included in the transcript. |
| 3204 |
For this example: |
| 3205 |
\begin{alltt} |
| 3206 |
i -> 'i' [105] |
| 3207 |
card -> '|S|' [124 83 124] |
| 3208 |
M -> 'M' [77] |
| 3209 |
S -> 'S' [83] |
| 3210 |
v -> '\usebox\varrow' [118 8407] |
| 3211 |
\end{alltt} |
| 3212 |
|
| 3213 |
The \longarg{group} option (in addition to \commonlongarg{verbose}) |
| 3214 |
will place the letter group in |
| 3215 |
parentheses before the character code list: |
| 3216 |
\begin{alltt} |
| 3217 |
i -> 'i' (i) [105] |
| 3218 |
card -> '|S|' [124 83 124] |
| 3219 |
M -> 'M' (M) [77] |
| 3220 |
S -> 'S' (S) [83] |
| 3221 |
v -> '\usebox\varrow' (v) [118 8407] |
| 3222 |
\end{alltt} |
| 3223 |
(Note that the \code{card} entry doesn't have a letter |
| 3224 |
group since the vertical bar character isn't considered a |
| 3225 |
letter.) |
| 3226 |
|
| 3227 |
If \csopt[letter-nocase]{sort} is used instead then, after conversion |
| 3228 |
by the interpreter, the sort values will all be changed to |
| 3229 |
\idx{lowercase}. The order is now: \code{i} ($\imaginary$), |
| 3230 |
\code{M} ($\mtx{M}$), \code{S} ($\set{S}$), |
| 3231 |
\code{v} ($\vec{v}$) and \code{card} ($\card{S}$). |
| 3232 |
The transcript (with \commonlongarg{verbose}) now shows |
| 3233 |
\begin{alltt} |
| 3234 |
i -> 'i' [105] |
| 3235 |
card -> '|s|' [124 115 124] |
| 3236 |
M -> 'm' [109] |
| 3237 |
S -> 's' [115] |
| 3238 |
v -> '\usebox\varrow' [118 8407] |
| 3239 |
\end{alltt} |
| 3240 |
With \longarg{group} (in addition to \commonlongarg{verbose}) |
| 3241 |
the letter groups are again included: |
| 3242 |
\begin{alltt} |
| 3243 |
i -> 'i' (I) [105] |
| 3244 |
card -> '|s|' [124 115 124] |
| 3245 |
M -> 'm' (M) [109] |
| 3246 |
S -> 's' (S) [115] |
| 3247 |
v -> '\usebox\varrow' (V) [118 8407] |
| 3248 |
\end{alltt} |
| 3249 |
Note that the letter groups are \idx{uppercase} not \idx{lowercase}. |
| 3250 |
Again the \code{card} entry doesn't have an associated |
| 3251 |
letter group. |
| 3252 |
|
| 3253 |
If a locale-based sort is used, the ordering will follow the |
| 3254 |
locale's alphabet rules. For example, with \csopt[en]{sort} |
| 3255 |
(English, no region or variant), the order becomes: |
| 3256 |
\code{card} ($\card{S}$), \code{i} ($\imaginary$), |
| 3257 |
\code{M} ($\mtx{M}$), \code{S} ($\set{S}$) and |
| 3258 |
\code{v} ($\vec{v}$). The transcript (with \commonlongarg{verbose}) |
| 3259 |
shows the collation keys instead: |
| 3260 |
\begin{alltt} |
| 3261 |
i -> 'i' [0 92 0 0 0 0] |
| 3262 |
card -> '|S|' [0 66 0 102 0 66 0 0 0 0] |
| 3263 |
M -> 'M' [0 96 0 0 0 0] |
| 3264 |
S -> 'S' [0 102 0 0 0 0] |
| 3265 |
v -> '\usebox\varrow' [0 105 0 0 0 0] |
| 3266 |
\end{alltt} |
| 3267 |
Again the addition of the \longarg{group} switch will show |
| 3268 |
the letter groups.\footnote{For more information on collation keys see the |
| 3269 |
\href{http://docs.oracle.com/javase/8/docs/api/java/text/CollationKey.html}{CollationKey} |
| 3270 |
class in Java's API~\cite{collationkey}.} |
| 3271 |
|
| 3272 |
Suppose I add a new symbol to my \ext{bib} file: |
| 3273 |
\begin{codeenv} |
| 3274 |
\atentry{symbol}\marg{angstrom, |
| 3275 |
\field{name}=\marg{\ics{AA}}, |
| 3276 |
\field{description}=\marg{\cs{AA} ngstr\ics{umlaut}om} |
| 3277 |
} |
| 3278 |
\end{codeenv} |
| 3279 |
and I also use this entry in the document.\footnote{A better method |
| 3280 |
is to use \sty{siunitx} instead.} Then with |
| 3281 |
\csopt[en]{sort}, the order is: \code{card} ($\card{S}$), |
| 3282 |
\code{angstrom} (\AA), \code{i} ($\imaginary$), \code{M} |
| 3283 |
($\mtx{M}$), \code{S} ($\set{S}$), and \code{v} ($\vec{v}$). |
| 3284 |
The \longarg{group} switch shows that the \code{angstrom} entry |
| 3285 |
(\AA) has been placed in the \qt{A} letter group. |
| 3286 |
|
| 3287 |
However, if I change the locale to \csopt[sv]{sort}, the |
| 3288 |
\code{angstrom} entry is moved to the end of the list and the |
| 3289 |
\longarg{group} switch shows that it's been placed in the \qt{\AA} |
| 3290 |
letter group. |
| 3291 |
|
| 3292 |
\label{locale.provider}If you are using Java~8, you can set the |
| 3293 |
\code{java.locale.providers} property~\cite{javacldr} to use |
| 3294 |
the \idx{CLDR} \idx{localeprovider}, which has more extensive |
| 3295 |
support for locales than the native \idx{JRE}. For example: |
| 3296 |
\begin{verbatim} |
| 3297 |
java.locale.providers=CLDR,JRE |
| 3298 |
\end{verbatim} |
| 3299 |
This should be enabled by default for Java~9. The property |
| 3300 |
can either be set in a script that runs \bibgls, for example, |
| 3301 |
\begin{verbatim} |
| 3302 |
java -Djava.locale.providers=CLDR,JRE,SPI -jar "$jarpath" "$@" |
| 3303 |
\end{verbatim} |
| 3304 |
(where \verb|$jarpath| is the path to the \file{bib2gls.jar} |
| 3305 |
file and \verb|"$@"| is the argument list) or you can set the |
| 3306 |
property as the default for all Java applications by adding |
| 3307 |
the definition to the \code{JAVA\_TOOL\_OPTIONS} environment |
| 3308 |
variable~\cite{javaoptions}. |
| 3309 |
For example, in a bash shell: |
| 3310 |
\begin{verbatim} |
| 3311 |
export JAVA_TOOL_OPTIONS='-Djava.locale.providers=CLDR,JRE,SPI' |
| 3312 |
\end{verbatim} |
| 3313 |
or in Windows: |
| 3314 |
\begin{verbatim} |
| 3315 |
set JAVA_TOOL_OPTIONS=-Djava.locale.providers=CLDR,JRE,SPI |
| 3316 |
\end{verbatim} |
| 3317 |
Note that newer versions of Java support \idx{CLDR} by |
| 3318 |
default, and the \idx{JRE} synonym for the \code{COMPAT} provider is now |
| 3319 |
deprecated.\footnote{https://www.oracle.com/java/technologies/javase/jdk21-suported-locales.html} |
| 3320 |
|
| 3321 |
\chapter{Command Line Options} |
| 3322 |
\label{sec:switches} |
| 3323 |
\setsecdepth{1} |
| 3324 |
|
| 3325 |
The syntax of \bibgls\ is: |
| 3326 |
\begin{alltt} |
| 3327 |
bib2gls \oargm{options} \meta{filename} |
| 3328 |
\end{alltt} |
| 3329 |
where \meta{filename} is the name of the \ext{aux} file. (The |
| 3330 |
extension may be omitted.) Only one \meta{filename} is permitted. |
| 3331 |
Available options are listed below. |
| 3332 |
|
| 3333 |
If you are using an automated build system that makes it difficult |
| 3334 |
to change the command line options and you have at least version |
| 3335 |
1.54 of \sty{glossaries-extra} and at least version 4.0 of \bibgls, |
| 3336 |
then most (but not all) switches can be specified within the |
| 3337 |
argument of |
| 3338 |
\nosecformatdef{BibGlsOptions} |
| 3339 |
This command may be placed anywhere within the preamble, but the |
| 3340 |
options will always be processed before the resource commands. This |
| 3341 |
command may be used multiple times. |
| 3342 |
Unlike the resource options, which are local to the resource set, the options |
| 3343 |
described here are global and are applied to all resource sets, |
| 3344 |
where applicable. |
| 3345 |
For example: |
| 3346 |
\begin{codeenv} |
| 3347 |
\gls{BibGlsOptions}\marg{replace-quotes=true} |
| 3348 |
\gls{GlsXtrLoadResources} |
| 3349 |
\gls{BibGlsOptions}\marg{collapse-same-location-range=true} |
| 3350 |
\end{codeenv} |
| 3351 |
This is equivalent to: |
| 3352 |
\begin{codeenv} |
| 3353 |
\gls{BibGlsOptions}\marg{replace-quotes=true,collapse-same-location-range=true} |
| 3354 |
\gls{GlsXtrLoadResources} |
| 3355 |
\end{codeenv} |
| 3356 |
The \meta{options} list should be a \keyvallist\ where the \meta{key} |
| 3357 |
is the same as the long switch without the preceding |
| 3358 |
\code{\longswitch} and any \code{\longswitch no-\meta{option}} should |
| 3359 |
be specified as \code{\meta{option}=false} within |
| 3360 |
\gls{BibGlsOptions}. |
| 3361 |
For example, to set global options via the command line: |
| 3362 |
\begin{verbatim} |
| 3363 |
bib2gls --group --no-replace-quotes myDoc |
| 3364 |
\end{verbatim} |
| 3365 |
Alternatively, the document may contain: |
| 3366 |
\begin{codeenv} |
| 3367 |
\gls{BibGlsOptions}\marg{group=true,replace-quotes=false} |
| 3368 |
\end{codeenv} |
| 3369 |
You can omit the value if it is \code{true}, so the above can also |
| 3370 |
be written: |
| 3371 |
\begin{codeenv} |
| 3372 |
\gls{BibGlsOptions}\marg{group,replace-quotes=false} |
| 3373 |
\end{codeenv} |
| 3374 |
|
| 3375 |
\begin{important} |
| 3376 |
Options that must be set before the \ext{log} and \ext{aux} file are read can |
| 3377 |
only be set via the command line switch. |
| 3378 |
\end{important} |
| 3379 |
|
| 3380 |
\section{Common Options} |
| 3381 |
\label{sec:commonswitches} |
| 3382 |
|
| 3383 |
These command line switches are common to \bibgls\ and the |
| 3384 |
supplementary command line conversion tools |
| 3385 |
|
| 3386 |
\commonarg{help} |
| 3387 |
|
| 3388 |
Display the help message and quit. |
| 3389 |
This option cannot be set in \gls{BibGlsOptions}. |
| 3390 |
|
| 3391 |
\commonarg{version} |
| 3392 |
|
| 3393 |
Display the version information and quit. As from v2.5, this now |
| 3394 |
includes the version number of the \file{texparserlib.jar} library. |
| 3395 |
This option cannot be set in \gls{BibGlsOptions}. |
| 3396 |
|
| 3397 |
\commonarg{verbose} |
| 3398 |
|
| 3399 |
Switches on the verbose mode. This writes extra information to the |
| 3400 |
terminal and transcript file. |
| 3401 |
This option cannot be set in \gls{BibGlsOptions}. |
| 3402 |
|
| 3403 |
\commonarg{no-verbose} |
| 3404 |
|
| 3405 |
Switches off the verbose mode. This is the default behaviour. |
| 3406 |
Some messages are written to the terminal. To completely suppress |
| 3407 |
all messages (except errors), switch on the silent mode. |
| 3408 |
For additional information messages, switch on the verbose mode. |
| 3409 |
This option cannot be set in \gls{BibGlsOptions}. |
| 3410 |
|
| 3411 |
\commonarg{quiet} |
| 3412 |
|
| 3413 |
Suppresses all messages except for errors that would normally be |
| 3414 |
written to the terminal. Warnings and informational messages are |
| 3415 |
written to the transcript file, which can be inspected afterwards. |
| 3416 |
This option cannot be set in \gls{BibGlsOptions}. |
| 3417 |
|
| 3418 |
\commonarg{silent} |
| 3419 |
|
| 3420 |
Synonym of \commonlongarg{quiet}. |
| 3421 |
This option cannot be set in \gls{BibGlsOptions}. |
| 3422 |
|
| 3423 |
\commonarg{locale} |
| 3424 |
|
| 3425 |
Specify the preferred \langxml, where \meta{lang} is a valid \idx{IETF} language tag. |
| 3426 |
This option requires an appropriate \metafilefmt{bib2gls-}{lang}{.xml} |
| 3427 |
resource file otherwise \bibgls\ will fallback on English. |
| 3428 |
This also sets the default \gls{document-locale} when the \optfmt{doc} |
| 3429 |
keyword (in options such as \csopt[doc]{sort}) is |
| 3430 |
used and the document doesn't have any language support. |
| 3431 |
Note that the \optfmt{locale} keyword (in options such as \csopt[locale]{sort}) |
| 3432 |
uses the \gls{Java-locale} and is not governed by this switch. |
| 3433 |
This option cannot be set in \gls{BibGlsOptions}. |
| 3434 |
|
| 3435 |
If a document doesn't have any locale support or has support |
| 3436 |
for more than one language then it's best to explicitly set |
| 3437 |
the required locale in the appropriate \idx{resourceset} using |
| 3438 |
the \csopt{locale} resource option, to specify the default |
| 3439 |
\gls{resource-locale}, or set the locale for individual options, |
| 3440 |
such as \csopt{sort}. |
| 3441 |
|
| 3442 |
\commonarg{debug} |
| 3443 |
|
| 3444 |
Sometimes when things go wrong it can be hard to diagnose the problem |
| 3445 |
from the normal messages. If you report an issue, you may be asked |
| 3446 |
to switch on debugging mode to help identify a non-reproducible |
| 3447 |
error and provide the transcript file. |
| 3448 |
|
| 3449 |
The \commonlongarg{debug} optional value can be used to adjust the level of |
| 3450 |
debugging information. If \meta{n} is present, it must be a non-negative |
| 3451 |
integer indicating the debugging mode. If omitted, 1 is assumed. This option |
| 3452 |
also switches on the verbose mode. A value of 0 is equivalent to |
| 3453 |
\commonlongarg{no-debug}. This option cannot be set in \gls{BibGlsOptions}. |
| 3454 |
|
| 3455 |
The value of \meta{n} determines how much extra information is |
| 3456 |
provided. If \meta{n} is greater than 0 then all \bibgls\ debugging |
| 3457 |
information is written. The amount of debugging information provided |
| 3458 |
by the \texparserlib\ is determined by a bitwise operation on |
| 3459 |
\meta{n}. For example, if \meta{n} is 1 then I/O information is |
| 3460 |
included. If \meta{n} is 2 then information is included when an |
| 3461 |
object is popped off a stack. If \meta{n} is 3 then both I/O and |
| 3462 |
popped information is provided. |
| 3463 |
|
| 3464 |
Note that messages such as \qt{Can't find language resource} or |
| 3465 |
about a failed \idx{kpsewhich} call are informational and don't |
| 3466 |
necessarily mean an error has occurred. Error messages will always |
| 3467 |
be written to the transcript regardless of the debug or verbose |
| 3468 |
setting. An error message will start with \qt{Error:~} and a warning |
| 3469 |
message will start with \qt{Warning:~}. Unknown commands will throw |
| 3470 |
an exception with a stack trace in debug mode. |
| 3471 |
|
| 3472 |
\commonarg{debug-mode} |
| 3473 |
|
| 3474 |
This option is an alternative to \commonlongarg{debug} where the value |
| 3475 |
of \meta{n} needs to be calculated. |
| 3476 |
This option cannot be set in \gls{BibGlsOptions}. |
| 3477 |
Debugging mode requires a |
| 3478 |
transcript file, which is automatically created with \bibgls, but is |
| 3479 |
optional for the converter tools (see \sectionref{sec:tex2bib}). The |
| 3480 |
\meta{setting} is required and should be a comma-separated list of |
| 3481 |
any of the following keywords. |
| 3482 |
|
| 3483 |
\begin{itemize} |
| 3484 |
\item\optfmt{all}: enable all debugging information |
| 3485 |
(likely to result in a very large transcript file). |
| 3486 |
|
| 3487 |
\item\optfmt{catcode}: \texparserlib\ category code changes. |
| 3488 |
|
| 3489 |
\item\optfmt{cs}: \texparserlib\ command definitions. |
| 3490 |
|
| 3491 |
\item\optfmt{decl}: information about declarations. |
| 3492 |
|
| 3493 |
\item\optfmt{expansion}: \texparserlib\ expansions |
| 3494 |
(may result in a large transcript file). |
| 3495 |
|
| 3496 |
\item\optfmt{expansion-list}: \texparserlib\ stack expansions |
| 3497 |
(may result in a large transcript file). |
| 3498 |
|
| 3499 |
\item\optfmt{expansion-once}: \texparserlib\ one-level expansions |
| 3500 |
(may result in a large transcript file). |
| 3501 |
|
| 3502 |
\item\optfmt{expansion-once-list}: \texparserlib\ one-level list expansions |
| 3503 |
(may result in a large transcript file). |
| 3504 |
|
| 3505 |
\item\optfmt{io}: I/O information, such as opening or closing files |
| 3506 |
and fetching tokens. |
| 3507 |
|
| 3508 |
\item\optfmt{popped}: information about objects popped from stacks. |
| 3509 |
|
| 3510 |
\item\optfmt{process}: \texparserlib\ macro process |
| 3511 |
(may result in a large transcript file). |
| 3512 |
|
| 3513 |
\item\optfmt{process-generic-cs}: \texparserlib\ generic command process. |
| 3514 |
|
| 3515 |
\item\optfmt{process-stack}: \texparserlib\ stack process |
| 3516 |
(may result in a large transcript file). |
| 3517 |
|
| 3518 |
\item\optfmt{process-stack-list}: \texparserlib\ stack process with |
| 3519 |
list detail (may result in a large transcript file). |
| 3520 |
|
| 3521 |
\item\optfmt{read}: \texparserlib\ file codepoint read |
| 3522 |
(likely to result in a very large transcript file). |
| 3523 |
|
| 3524 |
\item\optfmt{settings}: \texparserlib\ settings information. |
| 3525 |
|
| 3526 |
\item\optfmt{sty-data}: data associated with packages used to store |
| 3527 |
information that may not exactly correspond to the way the |
| 3528 |
information is stored in \LaTeX. In the case of \bibgls, this will |
| 3529 |
typically just be data read from recognised \iext{aux} commands. |
| 3530 |
|
| 3531 |
\end{itemize} |
| 3532 |
|
| 3533 |
For example: |
| 3534 |
\begin{codeenv} |
| 3535 |
bib2gls \commonlongarg{debug-mode} catcode,sty-data \meta{filename} |
| 3536 |
\end{codeenv} |
| 3537 |
|
| 3538 |
\commonarg{no-debug} |
| 3539 |
|
| 3540 |
Switches off the debugging mode. |
| 3541 |
This option cannot be set in \gls{BibGlsOptions}. |
| 3542 |
|
| 3543 |
\section{File Options} |
| 3544 |
|
| 3545 |
\argsection{aux-input-action} |
| 3546 |
|
| 3547 |
Determines what \bibgls\ should do if it encounters \ics{@input} in |
| 3548 |
the \ext+{aux} file. The \meta{setting} may be one of the following: |
| 3549 |
\begin{description} |
| 3550 |
\item[\optfmt{follow}] follow the reference (that is, input the file). |
| 3551 |
|
| 3552 |
\item[\optfmt{skip after bibglsaux}] follow the reference until |
| 3553 |
\gls{@bibgls@input} is encountered, after which skip all remaining |
| 3554 |
instances of \ics{@input} (default). If there is no |
| 3555 |
\styopt{bibglsaux} file, this setting is no different from |
| 3556 |
\optfmt{follow}. |
| 3557 |
|
| 3558 |
\item[\optfmt{skip-after-bibglsaux}] synonym of \optfmt{skip after |
| 3559 |
bibglsaux}. |
| 3560 |
|
| 3561 |
\item[\optfmt{skip}] skip the reference. Be careful with this |
| 3562 |
setting if you haven't used \styopt{bibglsaux} or |
| 3563 |
\gls{glsxtrsetbibglsaux} as you may cause \bibgls\ to miss records. |
| 3564 |
However, if you are using \csopt[all]{selection} and you're not |
| 3565 |
interested in locations then this might help speed up \bibgls's |
| 3566 |
processing time. |
| 3567 |
\end{description} |
| 3568 |
|
| 3569 |
This setting is designed to work with \sty{glossaries-extra}['s] |
| 3570 |
\styopt{bibglsaux} package option or with |
| 3571 |
\nosecdef{glsxtrsetbibglsaux} |
| 3572 |
which does the same thing. |
| 3573 |
This specifies a special \ext{aux} file containing the records that |
| 3574 |
\bibgls\ will read but \LaTeX\ will skip. |
| 3575 |
The reference will be written to the \ext{aux} file with |
| 3576 |
\nosecdef{@bibgls@input} |
| 3577 |
which is defined by \sty{glossaries-extra} to simply ignore its |
| 3578 |
argument but \bibgls\ will input the file (regardless of the |
| 3579 |
\longarg{aux-input-action} setting). |
| 3580 |
|
| 3581 |
Since the \styopt{bibglsaux} file contains all records and is |
| 3582 |
typically written to the \ext{aux} file after all the commands that |
| 3583 |
\bibgls\ is interested in, it's unlikely that the additional |
| 3584 |
\ext{aux} files (created by \ics{include}) will be of any interest |
| 3585 |
to \bibgls. Therefore the default setting is to ignore all |
| 3586 |
\cs{@input} after \gls{@bibgls@input}. |
| 3587 |
|
| 3588 |
\argsection{dir} |
| 3589 |
|
| 3590 |
This option cannot be set in \gls{BibGlsOptions}. |
| 3591 |
|
| 3592 |
By default \bibgls\ assumes that the output files should be written |
| 3593 |
in the current working directory. The input \iext{bib} files are assumed to be |
| 3594 |
either in the current working directory or on \TeX's path (in which |
| 3595 |
case \idx{kpsewhich} will be used to find them). |
| 3596 |
|
| 3597 |
If your \iext{aux} file isn't in the current working directory (for |
| 3598 |
example, you have run \TeX\ with \shortargfmt{output-directory}) |
| 3599 |
then you need to take care how you invoke \bibgls. |
| 3600 |
|
| 3601 |
Suppose I have a file called \filefmt{test-entries.bib} that |
| 3602 |
contains my entry definitions and a document called |
| 3603 |
\filefmt{mydoc.tex} that selects the \ext{bib} file using: |
| 3604 |
\begin{codeenv} |
| 3605 |
\gls{GlsXtrLoadResources}\oarg{\csopt[test-entries]{src}} |
| 3606 |
\end{codeenv} |
| 3607 |
(\filefmt{test-entries.bib} is in the same directory as |
| 3608 |
\filefmt{mydoc.tex}). |
| 3609 |
If I compile this document using |
| 3610 |
\begin{verbatim} |
| 3611 |
pdflatex -output-directory tmp mydoc |
| 3612 |
\end{verbatim} |
| 3613 |
then the auxiliary file \filefmt{mydoc.aux} will be written to the |
| 3614 |
\filefmt{tmp} sub-directory. The resource information is listed in |
| 3615 |
the \ext{aux} file as |
| 3616 |
\begin{codeenv} |
| 3617 |
\gls{glsxtr@resource}\marg{\csopt[test-entries]{src}}\marg{mydoc} |
| 3618 |
\end{codeenv} |
| 3619 |
If I run \bibgls\ from the \filefmt{tmp} directory, then it won't |
| 3620 |
be able to find the \filefmt{test-entries.bib} file (since it's in |
| 3621 |
the parent directory). |
| 3622 |
|
| 3623 |
If I run \bibgls\ from the same directory as \filefmt{mydoc.tex} |
| 3624 |
using |
| 3625 |
\begin{verbatim} |
| 3626 |
bib2gls tmp/mydoc |
| 3627 |
\end{verbatim} |
| 3628 |
then the \ext{aux} file is found and the transcript file is |
| 3629 |
\filefmt{tmp/mydoc.glg} (since the default path name is the same as the |
| 3630 |
\ext{aux} file but with the extension changed to \iext{glg}) but the |
| 3631 |
output file \filefmt{mydoc.glstex} will be written to the current |
| 3632 |
directory. |
| 3633 |
|
| 3634 |
This works fine from \TeX's point of view as it can find the |
| 3635 |
\iext{glstex} file, but it may be that you'd rather the \ext{glstex} |
| 3636 |
file was tidied away into the \filefmt{tmp} directory along with all |
| 3637 |
the other files. In this case you need to invoke \bibgls\ with the |
| 3638 |
\longargorshort{dir} option: |
| 3639 |
\begin{verbatim} |
| 3640 |
bib2gls -d tmp mydoc |
| 3641 |
\end{verbatim} |
| 3642 |
|
| 3643 |
\argsection{log-file} |
| 3644 |
|
| 3645 |
Sets the name of the \bibgls\ transcript file. By default, the name is the |
| 3646 |
same as the \iext{aux} file but with a \iext{glg} extension. Note that |
| 3647 |
if you use \bibgls\ in combination with \idx{xindy} or |
| 3648 |
\idx{makeindex}, you will need to change the transcript file name to |
| 3649 |
prevent conflict. |
| 3650 |
This option cannot be set in \gls{BibGlsOptions}. |
| 3651 |
|
| 3652 |
The transcript file encoding is governed by |
| 3653 |
\longarg{log-encoding}. |
| 3654 |
|
| 3655 |
\argsection{tex-encoding} |
| 3656 |
|
| 3657 |
This option cannot be set in \gls{BibGlsOptions}. |
| 3658 |
|
| 3659 |
In general, it's best to have all your files (\ext{aux}, \ext{bib} |
| 3660 |
and \iext{glstex}) in the same \igls{encoding} that matches your |
| 3661 |
default encoding (see \sectionref{sec:defencoding}). However, if |
| 3662 |
your \iext{aux} and \iext{glstex} files have a different encoding to |
| 3663 |
your default, you can use \longarg{tex-encoding} to specify the |
| 3664 |
\TeX\ encoding. If omitted the default encoding is used. See |
| 3665 |
\sectionref{sec:defencoding}. |
| 3666 |
|
| 3667 |
Note that \bibgls\ will try to detect the document encoding from the |
| 3668 |
\ext{aux} file to ensure that the \iext{glstex} files match it. |
| 3669 |
However, at that point, it's too late to establish the encoding of |
| 3670 |
the \ext{aux} file, which has already been opened. So if the |
| 3671 |
\ext{aux} file encoding doesn't match the default encoding, you can |
| 3672 |
specify the correct encoding to use with \longarg{tex-encoding}. |
| 3673 |
|
| 3674 |
If you are using \sty{fontspec}, \bibgls\ can detect this |
| 3675 |
from the \ext{log} file instead and will assume UTF-8. |
| 3676 |
|
| 3677 |
\argsection{log-encoding} |
| 3678 |
|
| 3679 |
The \igls{encoding} of the \iext{log} file. If omitted, the default |
| 3680 |
encoding will be used. See \sectionref{sec:defencoding}. (Note |
| 3681 |
that the \ext{log} file may not have the same encoding as the |
| 3682 |
\ext{tex} file~\cite{tex.sx.2013}.) |
| 3683 |
This option cannot be set in \gls{BibGlsOptions}. |
| 3684 |
|
| 3685 |
\argsection{default-encoding} |
| 3686 |
|
| 3687 |
The default \igls{encoding} used by \bibgls\ to read and write files is |
| 3688 |
governed by the \idx{JVM}. This typically matches your operating |
| 3689 |
system's default encoding. If this is incorrect, you can either |
| 3690 |
globally change the encoding for the \idx{JVM}, which will affect |
| 3691 |
all Java applications installed on your device, or you can use |
| 3692 |
\longarg{default-encoding} just to set the default for \bibgls. |
| 3693 |
See \sectionref{sec:defencoding}. |
| 3694 |
This option cannot be set in \gls{BibGlsOptions}. |
| 3695 |
|
| 3696 |
\argsection{date-in-header} |
| 3697 |
|
| 3698 |
The comment header block at the start of the \iext{glstex} files |
| 3699 |
will include the file modification date in the first line (after the |
| 3700 |
version information). This setting can interfere with |
| 3701 |
the document build process or version control if you are testing for |
| 3702 |
file differences rather than file modification dates when only the |
| 3703 |
timestamp changes. |
| 3704 |
|
| 3705 |
\argsection{no-date-in-header} |
| 3706 |
|
| 3707 |
The comment header block at the start of the \iext{glstex} files |
| 3708 |
won't include the file modification date (default). |
| 3709 |
If used in \gls{BibGlsOptions}, this option should be specified as |
| 3710 |
\begin{codeenv} |
| 3711 |
\gls{BibGlsOptions}\marg{date-in-header=false} |
| 3712 |
\end{codeenv} |
| 3713 |
|
| 3714 |
\section{Interpreter Options} |
| 3715 |
|
| 3716 |
\argsection{break-space} |
| 3717 |
|
| 3718 |
The interpreter treats a tilde character \idx{nbspchar} as a normal |
| 3719 |
space. Similarly \ics{nobreakspace} just produces a space. |
| 3720 |
|
| 3721 |
\argsection{no-break-space} |
| 3722 |
|
| 3723 |
The interpreter treats a tilde character \idx{nbspchar} as a non-breakable |
| 3724 |
space (default). Similarly the interpreter will define |
| 3725 |
\ics{nobreakspace} to produce a non-breakable space character (\hex{00A0}). |
| 3726 |
If used in \gls{BibGlsOptions}, this option should be specified as |
| 3727 |
\begin{codeenv} |
| 3728 |
\gls{BibGlsOptions}\marg{break-space=false} |
| 3729 |
\end{codeenv} |
| 3730 |
|
| 3731 |
\argsection{custom-packages} |
| 3732 |
|
| 3733 |
Instruct the interpreter to parse the package files identified in |
| 3734 |
\meta{list}. The package files need to be quite simple. When this |
| 3735 |
switch is used, the interpreter can recognise \ics{ProvidesPackage}, |
| 3736 |
\ics{DeclareOption} (and \ics{DeclareOption*}), |
| 3737 |
\ics{ProcessOptions}, \ics{PackageError} and \ics{RequirePackage}, |
| 3738 |
but it can't deal with complicated code. In the case of |
| 3739 |
\ics{RequirePackage}, support will also be governed by |
| 3740 |
\longarg{custom-packages}. This option has a cumulative action. |
| 3741 |
|
| 3742 |
Multiple instances of this switch can occur on the command line. |
| 3743 |
If used in \gls{BibGlsOptions}, the nature of the \keyvallist\ |
| 3744 |
parser means that multiple instances within the same option list |
| 3745 |
will override each other. Instead, you will need a comma-separated |
| 3746 |
list as the argument. |
| 3747 |
For example, from the command line: |
| 3748 |
\begin{verbatim} |
| 3749 |
bib2gls --custom-packages 'pkg1,pkg2,pkg3' myDoc |
| 3750 |
\end{verbatim} |
| 3751 |
This is equivalent to: |
| 3752 |
\begin{verbatim} |
| 3753 |
bib2gls --custom-packages pkg1 --custom-packages pkg2 --custom-packages pkg3 myDoc |
| 3754 |
\end{verbatim} |
| 3755 |
Alternatively, within the document: |
| 3756 |
\begin{codeenv} |
| 3757 |
\gls{BibGlsOptions}\marg{custom-packages=\marg{pkg1,pkg2,pkg3}} |
| 3758 |
\end{codeenv} |
| 3759 |
|
| 3760 |
\argsection{datatool-sort-markers} |
| 3761 |
|
| 3762 |
The \sty{datatool-base} package provides some marker commands |
| 3763 |
designed for use with \ics{DTLsortwordlist}: \ics{datatoolasciistart}, |
| 3764 |
\ics{datatoolpersoncomma}, \ics{datatoolplacecomma}, |
| 3765 |
\ics{datatoolsubjectcomma}, \ics{datatoolparenstart}, |
| 3766 |
\ics{datatoolctrlboundary}, \ics{datatoolasciiend}, and |
| 3767 |
\ics{datatoolparen}. These commands by default will be defined by the |
| 3768 |
interpreter to match their normal \sty{datatool-base} behaviour (see the |
| 3769 |
\sty{datatool} documentation for further details). Additionally, |
| 3770 |
\ics{dtltexorsort} will be redefined to expand to its \emph{first} argument. |
| 3771 |
|
| 3772 |
Note that you don't need to request the \sty{datatool-base} package, |
| 3773 |
unless you require support for other commands provided by that |
| 3774 |
package. |
| 3775 |
|
| 3776 |
The \longarg{datatool-sort-markers} switch will instead define these |
| 3777 |
commands to match their localised definitions within |
| 3778 |
\cs{DTLsortwordlist}. This means that \ics{dtltexorsort} will be |
| 3779 |
defined to expand to its \emph{second} argument and the marker |
| 3780 |
commands will expand to content that includes special control codes. |
| 3781 |
Note that language-sensitive sort methods typically ignore control |
| 3782 |
codes, so these would either need to be used with a character-code |
| 3783 |
comparator or a custom sort method would need to be used. |
| 3784 |
For example: |
| 3785 |
\begin{codeenv} |
| 3786 |
\csopt[\ics{glsxtrcontrolIrules} |
| 3787 |
;\cs{glshex} 0 |
| 3788 |
;\cs{glsxtrspacerules} |
| 3789 |
;\cs{glsxtrnonprintablerules} |
| 3790 |
;\cs{glsxtrcombiningdiacriticrules} |
| 3791 |
,\cs{glsxtrhyphenrules} |
| 3792 |
<\ics{glsxtrcontrolIIrules} |
| 3793 |
<\cs{glsxtrgeneralpuncrules} |
| 3794 |
<\cs{glsxtrdigitrules} |
| 3795 |
<\cs{glsxtrfractionrules} |
| 3796 |
<\ics{glsxtrGeneralLatinIrules} |
| 3797 |
<\cs{glshex} 7F |
| 3798 |
]{sort-rule} |
| 3799 |
\end{codeenv} |
| 3800 |
|
| 3801 |
Instead of \ics{dtltexorsort} (which varies according to this setting), you may |
| 3802 |
prefer to use \ics{IfTeXParserLib} or \ics{IfNotBibGls}. |
| 3803 |
|
| 3804 |
\argsection{no-datatool-sort-markers} |
| 3805 |
|
| 3806 |
Define the \sty{datatool-base} marker commands |
| 3807 |
(including \cs{dtltexorsort}) to match their normal definition. |
| 3808 |
|
| 3809 |
\argsection{ignore-packages} |
| 3810 |
|
| 3811 |
This option is cumulative. When the document \iext{log} file is |
| 3812 |
parsed for known packages, \bibgls\ will skip the check for any |
| 3813 |
listed in \meta{list}. Note that this option simply instructs |
| 3814 |
\bibgls\ to ignore the package information in the log file. Any packages |
| 3815 |
that are identified with \longarg{packages} will be passed to the |
| 3816 |
interpreter if support is available, even if the package is also |
| 3817 |
listed in \longarg{ignore-packages}. Note that |
| 3818 |
unknown packages can't be included in the ignored \meta{list}. |
| 3819 |
This option cannot be set in \gls{BibGlsOptions}. |
| 3820 |
|
| 3821 |
\argsection{interpret} |
| 3822 |
|
| 3823 |
Switch on the interpreter mode (default). See \sectionref{sec:texparserlib} |
| 3824 |
for more details. |
| 3825 |
|
| 3826 |
\argsection{no-interpret} |
| 3827 |
|
| 3828 |
Switch off the interpreter mode. See \sectionref{sec:texparserlib} |
| 3829 |
for more details about the interpreter. |
| 3830 |
If used in \gls{BibGlsOptions}, this option should be specified as |
| 3831 |
\begin{codeenv} |
| 3832 |
\gls{BibGlsOptions}\marg{interpret=false} |
| 3833 |
\end{codeenv} |
| 3834 |
|
| 3835 |
\argsection{list-known-packages} |
| 3836 |
|
| 3837 |
This option will list all the packages supported by the \texparserlib\ |
| 3838 |
and will then exit \bibgls. |
| 3839 |
This option cannot be set in \gls{BibGlsOptions}. |
| 3840 |
|
| 3841 |
The results are divided into two |
| 3842 |
sections: those packages that are searched for in the \iext{log} |
| 3843 |
file and those packages that aren't searched for in the \iext{log} |
| 3844 |
file but have some support available. Some of the support is very |
| 3845 |
limited. Package options aren't detected. |
| 3846 |
The transcript file is always searched for \isty{glossaries-extra} |
| 3847 |
to ensure that the version is new enough to support \bibgls. |
| 3848 |
|
| 3849 |
Packages that fall into the first category are: |
| 3850 |
\isty{amsmath}, \isty{amssymb}, \isty{bpchem}, \isty{fontenc}, |
| 3851 |
\isty{fontspec}, \isty{fourier}, |
| 3852 |
\isty{hyperref}, \isty{lipsum}, \isty{MnSymbol}, \isty{mhchem}, \isty{natbib}, |
| 3853 |
\isty{pifont}, \isty{siunitx} (limited), \isty{stix}, |
| 3854 |
\isty{textcase}, \isty{textcomp}, \isty{tipa}, \isty{upgreek} and |
| 3855 |
\isty{wasysym}. (You can omit checking for specific packages with |
| 3856 |
\longarg{ignore-packages}.) These are packages that provide commands |
| 3857 |
that might be needed within entry fields. The check for |
| 3858 |
\isty{fontspec} is to simply determine whether or not UTF-8 |
| 3859 |
characters are allowed in labels (for \csopt{labelify} and |
| 3860 |
\csopt{labelify-list}). (Now that there is better support for UTF-8 |
| 3861 |
with \pdfLaTeX, UTF-8 characters will be allowed in labels if the |
| 3862 |
detected versions of \isty{glossaries} and \isty{glossaries-extra} |
| 3863 |
are new enough, but note that you will also need a relatively new |
| 3864 |
\LaTeX\ kernel as well.) |
| 3865 |
|
| 3866 |
Packages that fall into the second category are: |
| 3867 |
\isty{booktabs}, \isty{color}, \isty{datatool-base} (very limited), |
| 3868 |
\isty{datatool} (very limited), \isty{etoolbox} (very limited), \isty{graphics}, |
| 3869 |
\isty{graphicx}, \isty{ifthen}, \isty{jmlrutils}, |
| 3870 |
\isty{mfirstuc-english}, \isty{probsoln}, \isty{shortvrb}, |
| 3871 |
and \isty{xspace}. These are less likely to be needed within fields |
| 3872 |
and so aren't checked for by default. If they are needed then you |
| 3873 |
can instruct \bibgls\ to support them with \longarg{packages}. |
| 3874 |
|
| 3875 |
Note that \sty{mfirstuc} is always automatically loaded, but |
| 3876 |
\sty{mfirstuc-english} is not implemented unless explicitly |
| 3877 |
requested with \code{\longarg{packages} mfirstuc-english}. |
| 3878 |
|
| 3879 |
If you're wondering about the selection, the \file{texparserlib.jar} |
| 3880 |
library was originally written for another application that required |
| 3881 |
support for some of them. |
| 3882 |
|
| 3883 |
\argsection{packages} |
| 3884 |
|
| 3885 |
Instruct the interpreter to assume the packages listed |
| 3886 |
in \meta{list} have been used by the document. |
| 3887 |
This option has a cumulative action so \code{\longarg{packages} |
| 3888 |
"wasysym,pifont"} is the same as \code{\longarg{packages} wasysym |
| 3889 |
\longarg{packages} pifont}. |
| 3890 |
|
| 3891 |
This option may also be used in \gls{BibGlsOptions} but, as with |
| 3892 |
\longarg{custom-packages}, multiple instances of the \code{packages} |
| 3893 |
key in the same option list will override each other. |
| 3894 |
|
| 3895 |
Note that there's only a limited number of packages supported by the |
| 3896 |
\texparserlib. This option is provided for cases where you're |
| 3897 |
using a command from a package that the interpreter doesn't support |
| 3898 |
but it happens to have the same name and meaning as a command from |
| 3899 |
a package that the interpreter does support. You can also use it to |
| 3900 |
provide support for known packages that aren't checked for when the |
| 3901 |
\ext{log} file is parsed. If you want \bibgls\ to parse an |
| 3902 |
unsupported package use \longarg{custom-packages}. |
| 3903 |
|
| 3904 |
\argsection{support-unicode-script} |
| 3905 |
|
| 3906 |
Text superscript (\ics{textsuperscript}) and subscript |
| 3907 |
(\ics{textsubscript}) will use Unicode super/subscript characters |
| 3908 |
if available (default). For example, |
| 3909 |
\begin{codeenv} |
| 3910 |
\cs{textsuperscript}\marg{(2)} |
| 3911 |
\end{codeenv} |
| 3912 |
will be converted to \code{\textsuperscript{(2)}}, which consists |
| 3913 |
of: \hex{207D} (superscript left parenthesis) |
| 3914 |
\hex{00B2} (superscript two) \hex{207E} (superscript right |
| 3915 |
parenthesis). If the entire contents of the argument can't be |
| 3916 |
represented by Unicode characters, the interpreter uses \verb|<sup>| |
| 3917 |
and \verb|<sub>| markup, which is then stripped by \bibgls. For |
| 3918 |
example, |
| 3919 |
\begin{codeenv} |
| 3920 |
\cs{textsuperscript}\marg{(2,3)} |
| 3921 |
\end{codeenv} |
| 3922 |
will be converted to |
| 3923 |
\begin{verbatim} |
| 3924 |
<sup>(2,3)</sup> |
| 3925 |
\end{verbatim} |
| 3926 |
(since there's no superscript comma). The markup is stripped leaving |
| 3927 |
just \code{(2,3)}. |
| 3928 |
|
| 3929 |
Superscripts and subscripts in maths mode always use markup |
| 3930 |
regardless of this setting. Some supported packages that use |
| 3931 |
\idx{spchar} or \idx{sbchar} as shortcuts within an encapsulating |
| 3932 |
command may internally use the same code as \cs{textsuperscript} and |
| 3933 |
\cs{textsubscript}, in which case they will be sensitive to this |
| 3934 |
setting. |
| 3935 |
|
| 3936 |
\argsection{no-support-unicode-script} |
| 3937 |
|
| 3938 |
Text superscript (\cs{textsuperscript}) and subscript |
| 3939 |
(\cs{textsubscript}) won't use Unicode super/subscript characters. |
| 3940 |
Note that if other commands are provided that expand to Unicode |
| 3941 |
superscript or subscript characters, then they won't be affected by |
| 3942 |
this setting. For example, if \csfmt{superiortwo} is defined as |
| 3943 |
\begin{codeenv} |
| 3944 |
\cs{providecommand}\marg{\cmd{superiortwo}}\marg{\charhex{B2}} |
| 3945 |
\end{codeenv} |
| 3946 |
then it will be interpreted as \hex{00B2} (superscript two) even if |
| 3947 |
this setting is on. |
| 3948 |
|
| 3949 |
If used in \gls{BibGlsOptions}, this option should be specified as |
| 3950 |
\begin{codeenv} |
| 3951 |
\gls{BibGlsOptions}\marg{support-unicode-script=false} |
| 3952 |
\end{codeenv} |
| 3953 |
|
| 3954 |
\argsection{obey-aux-catcode} |
| 3955 |
|
| 3956 |
By default, the \ext{aux} parser ignores category code changing |
| 3957 |
commands. This option will instruct the parser to implement the |
| 3958 |
category code, but note that it can only do this for known commands |
| 3959 |
that the parser is able to implement. |
| 3960 |
This option cannot be set in \gls{BibGlsOptions}. |
| 3961 |
|
| 3962 |
\argsection{no-obey-aux-catcode} |
| 3963 |
|
| 3964 |
Instructs the \ext{aux} parser to ignore category code changing |
| 3965 |
commands. (Default.) |
| 3966 |
This option cannot be set in \gls{BibGlsOptions}. |
| 3967 |
|
| 3968 |
\section{Record Options} |
| 3969 |
|
| 3970 |
\argsection{cite-as-record} |
| 3971 |
|
| 3972 |
Treat instances of \code{\ics{citation}\margm{label}} found in the |
| 3973 |
\ext{aux} file as though it was actually an \idx{ignoredrecord}: |
| 3974 |
\begin{codeenv} |
| 3975 |
\gls{glsxtr@record}\margm{label}\marg{}\marg{\counter{page}}\marg{\encap{glsignore}}\marg{} |
| 3976 |
\end{codeenv} |
| 3977 |
Note that \code{\cs{citation}\marg{*}} will always be skipped. Use |
| 3978 |
\csopt[all]{selection} to select all entries. |
| 3979 |
This switch is most useful in conjunction with |
| 3980 |
\atentrypageref{bibtexentry}. |
| 3981 |
|
| 3982 |
\argsection{no-cite-as-record} |
| 3983 |
|
| 3984 |
Don't check for instances of \ics{citation} in the \ext{aux} file |
| 3985 |
(default). |
| 3986 |
If used in \gls{BibGlsOptions}, this option should be specified as |
| 3987 |
\begin{codeenv} |
| 3988 |
\gls{BibGlsOptions}\marg{cite-as-record=false} |
| 3989 |
\end{codeenv} |
| 3990 |
|
| 3991 |
\argsection{collapse-same-location-range} |
| 3992 |
|
| 3993 |
Collapse any \idx{explicit-range} into a normal \gls{record} if |
| 3994 |
the start and end \glspl{location} are the same (default). |
| 3995 |
This record will be treated as a normal \gls{location} that can be |
| 3996 |
merged with neighbouring \glspl{location}, regardless of |
| 3997 |
\csopt{merge-ranges}. |
| 3998 |
|
| 3999 |
\argsection{no-collapse-same-location-range} |
| 4000 |
|
| 4001 |
Don't collapse any \idx{explicit-range} into a normal |
| 4002 |
\gls{record} if the start and end \glspl{location} are the same. |
| 4003 |
The \idx{explicit-range} will only be able to merge with |
| 4004 |
neighbouring \glspl{location} if \csopt[true]{merge-ranges}. |
| 4005 |
If used in \gls{BibGlsOptions}, this option should be specified as |
| 4006 |
\begin{codeenv} |
| 4007 |
\gls{BibGlsOptions}\marg{collapse-same-location-range=false} |
| 4008 |
\end{codeenv} |
| 4009 |
|
| 4010 |
\argsection{shift-zero-sections} |
| 4011 |
|
| 4012 |
Shift up \glspl{location} ending with \qtt{.0} for any section counters |
| 4013 |
deeper than \counter{chapter}. This action is applied recursively. |
| 4014 |
\strong{The setting is ignored for \glspl{location} with other types of |
| 4015 |
counter.} |
| 4016 |
|
| 4017 |
For example, suppose the indexing counter has been set to |
| 4018 |
\counter{subsection}. This could be done globally through the |
| 4019 |
\styopt{counter} package option: |
| 4020 |
\begin{codeenv} |
| 4021 |
\cmd{usepackage}\oarg{\styopt{counter}=\counter{subsection},\styopt{record}}\marg{glossaries-extra} |
| 4022 |
\end{codeenv} |
| 4023 |
or set for a specific glossary: |
| 4024 |
\begin{codeenv} |
| 4025 |
\cs{newglossary*}\marg{samples}\marg{Samples}\oarg{\counter{subsection}} |
| 4026 |
\end{codeenv} |
| 4027 |
or automatically for a particular format: |
| 4028 |
\begin{codeenv} |
| 4029 |
\cs{GlsXtrAutoAddOnFormat}\marg{primaryfmt}\marg{\glsopt{counter}=\counter{subsection},\glsopt{format}=primaryfmt} |
| 4030 |
\end{codeenv} |
| 4031 |
or for an individual entry: |
| 4032 |
\begin{codeenv} |
| 4033 |
\cs{gls}\oarg{\glsopt{counter}=\counter{subsection}}\margm{sample} |
| 4034 |
\end{codeenv} |
| 4035 |
|
| 4036 |
If, however, entries are referenced before the first subsection of a |
| 4037 |
section (or chapter), this can lead to locations that end with \qtt{.0} (because |
| 4038 |
the \counter{subsection} counter is zero at that point). |
| 4039 |
Suppose the package option \code{\styopt{counter}=\counter{subsection}} |
| 4040 |
is in effect and the document starts with: |
| 4041 |
\begin{codeenv} |
| 4042 |
\cmd{chapter}\marg{Sample Chapter} |
| 4043 |
\cs{gls}\marg{sample}. |
| 4044 |
\cmd{section}\marg{Sample Section} |
| 4045 |
\cs{gls}\marg{sample}. |
| 4046 |
\cmd{subsection}\marg{Sample Sub-Section} |
| 4047 |
\cs{gls}\marg{sample}. |
| 4048 |
\end{codeenv} |
| 4049 |
Then the \gls{locationlist} for the \qtt{sample} entry will be: |
| 4050 |
1.0.0, 1.1.0, 1.1.1 and, if \sty{hyperref} is also loaded, the anchors |
| 4051 |
will be \code{subsection.1.0.0}, \code{subsection.1.1.0} |
| 4052 |
and \code{subsection.1.1.1}, but of these, only the last one is |
| 4053 |
defined. The transcript will contain warnings such as: |
| 4054 |
\begin{quote} |
| 4055 |
pdfTeX warning (dest): name\marg{subsection.1.0.0} has been referenced but does not |
| 4056 |
exist, replaced by a fixed one |
| 4057 |
\end{quote} |
| 4058 |
|
| 4059 |
There are two ways to deal with this. The first is quite tedious and |
| 4060 |
involves changing the \glsopt{counter} setting according to the |
| 4061 |
current sectioning level: |
| 4062 |
\begin{codeenv} |
| 4063 |
\cmd{chapter}\marg{Sample Chapter} |
| 4064 |
\cs{gls}\oarg{\glsopt{counter}=\counter{chapter}}\marg{sample}. |
| 4065 |
\cmd{section}\marg{Sample Section} |
| 4066 |
\cs{gls}\oarg{\glsopt{counter}=\counter{section}}\marg{sample}. |
| 4067 |
\cmd{subsection}\marg{Sample Sub-Section} |
| 4068 |
\cs{gls}\oarg{\glsopt{counter}=\counter{subsection}}\marg{sample}. |
| 4069 |
\end{codeenv} |
| 4070 |
This method is not only tedious but doesn't lend itself well to |
| 4071 |
editing where the document structure changes with new sections |
| 4072 |
introduced or removed. |
| 4073 |
|
| 4074 |
An easier solution is to use the \longarg{shift-zero-sections} |
| 4075 |
switch. This setting can also be used in \gls{BibGlsOptions}: |
| 4076 |
\begin{codeenv} |
| 4077 |
\gls{BibGlsOptions}\marg{shift-zero-sections} |
| 4078 |
\end{codeenv} |
| 4079 |
|
| 4080 |
Each \gls{record} that has a \gls{location} ending with \qtt{.0} and has a |
| 4081 |
sectioning counter below \counter{chapter} will have the \qtt{.0} |
| 4082 |
removed and the counter will be changed to the counter for the next |
| 4083 |
level up. So the \gls{record} with counter \counter{subsection} and |
| 4084 |
\gls{location} \qtt{1.0.0} will have the counter changed to \counter{section} |
| 4085 |
and the \gls{location} will be changed to \qtt{1.0} but this function is |
| 4086 |
performed recursively. Since \qtt{1.0} also ends with \qtt{.0} and |
| 4087 |
the counter level is still less than \counter{chapter}, the function is |
| 4088 |
repeated: the counter is now changed from \counter{section} to \counter{chapter} |
| 4089 |
and the \gls{location} is changed from \qtt{1.0} to \qtt{1}. |
| 4090 |
|
| 4091 |
For the above example, this action will change the |
| 4092 |
\gls{locationlist} for the \qtt{sample} entry to: 1, 1.1, 1.1.1 and, |
| 4093 |
if \sty{hyperref} is also loaded, the anchors will be |
| 4094 |
\code{chapter.1}, \code{section.1.1} and \code{subsection.1.1.1} |
| 4095 |
which are now all valid. |
| 4096 |
|
| 4097 |
\argsection{no-shift-zero-sections} |
| 4098 |
|
| 4099 |
Don't adjust records with sectioning locations ending in \qtt{.0} (default). |
| 4100 |
If used in \gls{BibGlsOptions}, this option should be specified as: |
| 4101 |
\begin{codeenv} |
| 4102 |
\gls{BibGlsOptions}\marg{shift-zero-sections=false} |
| 4103 |
\end{codeenv} |
| 4104 |
|
| 4105 |
\argsection{map-format} |
| 4106 |
|
| 4107 |
This sets up the rule of precedence for partial \gls{location} |
| 4108 |
matches (see \sectionref{sec:locationopts}). The argument may be |
| 4109 |
a comma-separated list of \meta{map}\code{:}\meta{value} pairs. |
| 4110 |
Alternatively, you can have multiple instances of |
| 4111 |
\longarg{map-format} \meta{map}\dcolon\meta{value} which have a |
| 4112 |
cumulative effect on the command line. You can also use |
| 4113 |
\code{map-format} as an option within \gls{BibGlsOptions}, but |
| 4114 |
multiple instances of this key in the same option list will override |
| 4115 |
each other. |
| 4116 |
|
| 4117 |
For example, |
| 4118 |
\begin{verbatim} |
| 4119 |
bib2gls --map-format "emph:hyperbf" mydoc |
| 4120 |
\end{verbatim} |
| 4121 |
This essentially means that if there's a \gls{record} conflict |
| 4122 |
involving \encap{emph}, try replacing \encap{emph} with |
| 4123 |
\encap{hyperbf} and see if that resolves the conflict. |
| 4124 |
|
| 4125 |
Note that if the conflict includes a \idx{range} formation, the |
| 4126 |
\idx{range} takes precedence. |
| 4127 |
The mapping tests are applied as the records are |
| 4128 |
read. For example, suppose the records are listed in the \ext{aux} |
| 4129 |
file as: |
| 4130 |
\begin{codeenv} |
| 4131 |
\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{emph}}\marg{3} |
| 4132 |
\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{hypersf}}\marg{3} |
| 4133 |
\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{hyperbf}}\marg{3} |
| 4134 |
\end{codeenv} |
| 4135 |
and \bibgls\ is invoked with |
| 4136 |
\begin{verbatim} |
| 4137 |
bib2gls --map-format "emph:hyperbf,hypersf:hyperit" mydoc |
| 4138 |
\end{verbatim} |
| 4139 |
or |
| 4140 |
\begin{verbatim} |
| 4141 |
bib2gls --map-format emph:hyperbf --map-format hypersf:hyperit mydoc |
| 4142 |
\end{verbatim} |
| 4143 |
then \bibgls\ will process these \glspl{record} as follows: |
| 4144 |
\begin{enumerate} |
| 4145 |
\item Accept the first \gls{record} (\encap{emph}) since there's |
| 4146 |
currently no conflict. (This is the first \gls{record} for page~3 for the |
| 4147 |
entry given by \code{gls.sample}.) |
| 4148 |
\item The second \gls{record} (\encap{hypersf}) conflicts |
| 4149 |
with the existing \gls{record} (\encap{emph}). Neither has |
| 4150 |
the format \encap{glsnumberformat} or \encap{glsignore} so \bibgls\ consults |
| 4151 |
the mappings provided by \longarg{map-format}. |
| 4152 |
\begin{itemize} |
| 4153 |
\item The \encap{hypersf} format (from the new record) is mapped to |
| 4154 |
\encap{hyperit}, |
| 4155 |
so \bibgls\ checks if the existing \gls{record} |
| 4156 |
has this format. In this case it doesn't (the format is |
| 4157 |
\code{emph}). So \bibgls\ moves on to the next test: |
| 4158 |
|
| 4159 |
\item The \encap{emph} format (from the existing record) is mapped |
| 4160 |
to \encap{hyperbf}, |
| 4161 |
so \bibgls\ checks if the new record has this format. |
| 4162 |
In this case it doesn't (the format is \encap{hypersf}). |
| 4163 |
|
| 4164 |
Since the provided mappings haven't resolved this conflict, |
| 4165 |
the new record is discarded with a warning. Note that there's |
| 4166 |
no look ahead to the next record. (There may be other |
| 4167 |
records for other entries also used on page~3 interspersed between these records.) |
| 4168 |
\end{itemize} |
| 4169 |
\item The third \gls{record} (\encap{hyperbf}) conflicts |
| 4170 |
with the existing \gls{record} (\encap{emph}). Neither has |
| 4171 |
the format \encap{glsnumberformat} or \encap{glsignore} so \bibgls\ again consults |
| 4172 |
the mappings provided by \longarg{map-format}. |
| 4173 |
\begin{itemize} |
| 4174 |
\item The new \gls{record}['s] \encap{hyperbf} format has no mapping provided, |
| 4175 |
so \bibgls\ moves on to the next test: |
| 4176 |
|
| 4177 |
\item The existing \gls{record}['s] \encap{emph} format has a mapping |
| 4178 |
provided (\encap{hyperbf}). This matches the new \gls{record}['s] format, |
| 4179 |
so the new \gls{record} takes precedence. |
| 4180 |
|
| 4181 |
This means that the \gls{locationlist} ends up with the \encap{hyperbf} |
| 4182 |
location for page~3. |
| 4183 |
\end{itemize} |
| 4184 |
\end{enumerate} |
| 4185 |
|
| 4186 |
If, on the other hand, the mappings are given as |
| 4187 |
\begin{verbatim} |
| 4188 |
--map-format "emph:hyperit,hypersf:hyperit,hyperbf:hyperit" |
| 4189 |
\end{verbatim} |
| 4190 |
then all the three conflicting \glspl{record} (\encap{emph}, |
| 4191 |
\encap{hypersf} and \encap{hyperbf}) will end up being replaced |
| 4192 |
by a single \gls{record} with \encap{hyperit} as the format. |
| 4193 |
|
| 4194 |
Multiple conflicts will typically be rare as there's usually little |
| 4195 |
reason for more than two or three different \gls{location} formats within |
| 4196 |
the same list. (For example, \encap{glsnumberformat} as the default |
| 4197 |
and \encap{hyperbf} or \encap{hyperit} for a |
| 4198 |
\gls{principallocation}.) |
| 4199 |
|
| 4200 |
\argsection{merge-nameref-on} |
| 4201 |
|
| 4202 |
The \styopt[nameref]{record} package option (introduced to |
| 4203 |
\sty{glossaries-extra} version 1.37) provides extra information |
| 4204 |
in the record when indexing, obtained from \ics{@currentlabelname}, |
| 4205 |
\ics{@currentHref} and \ics{theHentrycounter}. Instead of writing the record as: |
| 4206 |
\begin{codeenv} |
| 4207 |
\format{glsxtr@record} |
| 4208 |
\end{codeenv} |
| 4209 |
the record is written as: |
| 4210 |
\nosecdef{glsxtr@record@nameref} |
| 4211 |
If \isty{hyperref} hasn't been loaded \meta{title} and \meta{href} |
| 4212 |
will always be empty. The most reliable target is given by |
| 4213 |
\code{\meta{counter}.\meta{hcounter}}, where \meta{counter} is the |
| 4214 |
associated counter name and \meta{hcounter} is |
| 4215 |
obtained from \cs{theHentrycounter}, which is set to the hyper |
| 4216 |
target command \csfmt{theH}\meta{counter} during indexing. Since |
| 4217 |
this information can't be included in the \gls{location} when indexing |
| 4218 |
with \idx!{makeindex} or \idx!{xindy}, the base \sty{glossaries} |
| 4219 |
package tries to obtain a prefix from which the target name can be |
| 4220 |
formed. This doesn't work if \csfmt{theH}\meta{counter} can't be |
| 4221 |
formed from \meta{prefix}\csfmt{the}\meta{counter}, which results in |
| 4222 |
broken links. Since \bibgls\ doesn't have the same restrictions, the |
| 4223 |
actual target can be included in the record. You can then customize |
| 4224 |
the document to choose whether to use \meta{href} (to link to the |
| 4225 |
nearest anchor) or \meta{hcounter} to link to the place where the |
| 4226 |
indexing counter was incremented. |
| 4227 |
|
| 4228 |
The \code{nameref} record will be written to the \igls{locationlist} using: |
| 4229 |
\nosecdef{glsxtrdisplaylocnameref} |
| 4230 |
The \meta{file} part will be empty for normal internal \glspl{location}, |
| 4231 |
and will be set to the corresponding file name for |
| 4232 |
\glsdisp{supplementalrecord}{supplemental locations}. |
| 4233 |
|
| 4234 |
With \sty{hyperref}, \meta{title} is initially empty. The \meta{href} will be |
| 4235 |
\code{Doc-Start} at the start of the document and is updated |
| 4236 |
globally on every instance of \ics{refstepcounter}. The |
| 4237 |
\meta{title} is updated locally by certain commands, such as |
| 4238 |
\ics{section} or \ics{caption}. This means that the \meta{href} |
| 4239 |
may not always correspond to the \meta{title}, so using |
| 4240 |
the \styopt[nameref]{record} package option can have unpredictable |
| 4241 |
results if the \meta{title} is used as link text with \meta{href} as |
| 4242 |
the target. |
| 4243 |
|
| 4244 |
For compactness, \bibgls\ tries to merge duplicate or near |
| 4245 |
duplicate records. There are four possible rules that it will |
| 4246 |
use for \code{nameref} records, identified by \meta{rule} in the |
| 4247 |
\longarg{merge-nameref-on} switch: |
| 4248 |
\begin{itemize} |
| 4249 |
\item \optfmt{location}: merge records that match on the |
| 4250 |
\meta{prefix}, \meta{counter} and \meta{location} parts (as regular |
| 4251 |
records); |
| 4252 |
\item \optfmt{title}: merge records that match on the \meta{counter} |
| 4253 |
and \meta{title} parts; |
| 4254 |
\item \optfmt{href}: merge records that match on the \meta{counter} |
| 4255 |
and \meta{href} parts; |
| 4256 |
\item \optfmt{hcounter}: merge records that match on the \meta{counter} |
| 4257 |
and \meta{hcounter} parts. |
| 4258 |
\end{itemize} |
| 4259 |
The default \meta{rule} is \optfmt{hcounter}. Note that for all |
| 4260 |
rules the \meta{counter} must match. See the \qt{Nameref Record} |
| 4261 |
section of the \sty{glossaries-extra} user manual for further |
| 4262 |
details. |
| 4263 |
|
| 4264 |
\argsection{merge-wrglossary-records} |
| 4265 |
|
| 4266 |
For use with the \styopt{indexcounter} package option |
| 4267 |
(\styfmt{glossaries-extra} v1.29+), this switch merges an entry's |
| 4268 |
\counter{wrglossary} records for the same page \gls{location}. This is the |
| 4269 |
default setting. (See also \csopt{save-index-counter}.) |
| 4270 |
|
| 4271 |
\argsection{no-merge-wrglossary-records} |
| 4272 |
|
| 4273 |
Don't merge an entry's \counter{wrglossary} records. This means that you |
| 4274 |
may end up with duplicate page numbers in the entry's \gls{locationlist}, |
| 4275 |
but they will link to different parts of the page. |
| 4276 |
If used in \gls{BibGlsOptions}, this option should be specified as |
| 4277 |
\begin{codeenv} |
| 4278 |
\gls{BibGlsOptions}\marg{merge-wrglossary-records=false} |
| 4279 |
\end{codeenv} |
| 4280 |
|
| 4281 |
\argsection{record-count} |
| 4282 |
|
| 4283 |
Switch on record counting. This will ensure that when each entry |
| 4284 |
is written to the \iext{glstex} file, \bibgls\ will additionally |
| 4285 |
set the following fields |
| 4286 |
\begin{itemize} |
| 4287 |
\item \field{recordcount}: set to the total |
| 4288 |
number of records found for the entry; |
| 4289 |
\item \field{recordcount.counter}: set to the total |
| 4290 |
number of records found for the entry for the given counter. |
| 4291 |
\end{itemize} |
| 4292 |
These fields can then be used with the \gls{rgls}-like commands. |
| 4293 |
|
| 4294 |
This option is governed by the \longarg{record-count-rule}, which |
| 4295 |
can be used to exclude certain types of records from the count. The |
| 4296 |
default rule is \optfmt{all}, which includes all |
| 4297 |
\idxpl{ignoredrecord}. |
| 4298 |
|
| 4299 |
The default behaviour of |
| 4300 |
\nosecdef{rgls} |
| 4301 |
is to check the \field{recordcount} field against the \catattr{recordcount} |
| 4302 |
attribute value. This attribute can be set with |
| 4303 |
\nosecdef{GlsXtrSetRecordCountAttribute} |
| 4304 |
where \meta{category list} is a comma-separated list |
| 4305 |
of category labels and \meta{value} is a positive integer. |
| 4306 |
If the value of the \field{recordcount} field is greater than |
| 4307 |
\meta{value} then \gls{rgls} behaves like \ics{gls}, otherwise |
| 4308 |
it does |
| 4309 |
\nosecdef{rglsformat} |
| 4310 |
instead. |
| 4311 |
If the use of \gls{rglsformat} is triggered in this way, |
| 4312 |
then \gls{rgls} writes a \gls{record} to the \iext{aux} file |
| 4313 |
with the \glsopt{format} set to \encap{glstriggerrecordformat}. |
| 4314 |
This ensures that the \gls{recordcount} is correct on the next run, |
| 4315 |
but the \gls{record} isn't added to the \gls{locationlist} as |
| 4316 |
\bibgls\ recognises it as a special \igls{ignoredrecord}. |
| 4317 |
Note that the entry will still appear in the usual glossary unless |
| 4318 |
you assign it to a different one with \csopt{trigger-type}. |
| 4319 |
|
| 4320 |
If the \catattr{recordcount} attribute hasn't been set |
| 4321 |
\gls{rgls} behaves like \ics{gls}. (That is, \gls{rgls} |
| 4322 |
uses the same internal command used by \ics{gls}.) You can use |
| 4323 |
\ics{glsxtrenablerecordcount} to redefine \ics{gls} |
| 4324 |
to \gls{rgls}, so that you can continue to use \ics{gls} |
| 4325 |
without having to switch command name. |
| 4326 |
|
| 4327 |
For example: |
| 4328 |
\begin{codeenv} |
| 4329 |
\gls{GlsXtrLoadResources}\oarg{ |
| 4330 |
\csopt[abbrevs]{src},\comment{entries defined in abbrevs.bib} |
| 4331 |
\csopt[ignored]{trigger-type}, |
| 4332 |
\csopt[abbreviation]{category} |
| 4333 |
} |
| 4334 |
\cs{glsxtrenablerecordcount} |
| 4335 |
\gls{GlsXtrSetRecordCountAttribute}\marg{abbreviation}\marg{1} |
| 4336 |
\end{codeenv} |
| 4337 |
See the \sty{glossaries-extra} user manual~\cite{glossaries-extra} |
| 4338 |
for further details. |
| 4339 |
|
| 4340 |
\begin{important} |
| 4341 |
Take care not to confuse the \field{recordcount} field with the \field{indexed} |
| 4342 |
field. The \field{indexed} field keeps a running total of the number of times an |
| 4343 |
entry has been recorded \emph{so far}, and is updated every time the entry is |
| 4344 |
indexed during the current \LaTeX\ run. The \field{recordcount} field stores the total number of records |
| 4345 |
obtained by \bibgls\ from the \ext{aux} file. |
| 4346 |
\end{important} |
| 4347 |
|
| 4348 |
\argsection{no-record-count} |
| 4349 |
|
| 4350 |
Switch off record counting. (Default.) |
| 4351 |
If used in \gls{BibGlsOptions}, this option should be specified as |
| 4352 |
\begin{codeenv} |
| 4353 |
\gls{BibGlsOptions}\marg{record-count=false} |
| 4354 |
\end{codeenv} |
| 4355 |
|
| 4356 |
\argsection{record-count-unit} |
| 4357 |
|
| 4358 |
Automatically implements \longarg{record-count} and additionally |
| 4359 |
sets the \field{recordcount.counter.location} fields. |
| 4360 |
These fields can then be used with the \gls{rgls}-like |
| 4361 |
commands. This option is governed by \longarg{record-count-rule}, |
| 4362 |
to determine which records should be counted. |
| 4363 |
|
| 4364 |
\argsection{no-record-count-unit} |
| 4365 |
|
| 4366 |
Switches off unit record counting. (Default.) |
| 4367 |
Note that you need \longarg{no-record-count} to completely |
| 4368 |
switch off record counting. |
| 4369 |
If used in \gls{BibGlsOptions}, this option should be specified as |
| 4370 |
\begin{codeenv} |
| 4371 |
\gls{BibGlsOptions}\marg{record-count-unit=false} |
| 4372 |
\end{codeenv} |
| 4373 |
|
| 4374 |
\argsection{record-count-rule} |
| 4375 |
|
| 4376 |
Automatically implements \longarg{record-count} and sets the rule |
| 4377 |
that determines which records should contribute to the count. |
| 4378 |
The \meta{rule} may be one of: |
| 4379 |
\begin{itemize} |
| 4380 |
\item \code{all} or \code{a}: these keywords indicate that all |
| 4381 |
records should be included in the count (default). |
| 4382 |
\item \code{non-ignored} or \code{n}: these keywords indicate that |
| 4383 |
\idxpl{ignoredrecord} should be excluded in the count. |
| 4384 |
\item \code{c/\meta{regex}/}: only records where the associated |
| 4385 |
counter name matches the regular expression \meta{regex} should be |
| 4386 |
included in the count. |
| 4387 |
\item \code{f/\meta{regex}/}: only records where the associated |
| 4388 |
format matches the regular expression \meta{regex} should be |
| 4389 |
included in the count. |
| 4390 |
\item \code{f/\meta{format-regex}/c/\meta{counter-regex}/\meta{op}}: |
| 4391 |
this combines the format and counter name match. The trailing |
| 4392 |
\meta{op} is optional. If present, it should be one of the keywords: |
| 4393 |
\code{and} (boolean AND) or \code{or} (boolean OR). If omitted, |
| 4394 |
\code{and} is assumed. |
| 4395 |
\end{itemize} |
| 4396 |
|
| 4397 |
For example: |
| 4398 |
\begin{verbatim} |
| 4399 |
bib2gls --record-count-rule 'f/.*(bf|it)/c/(sub)?section/or' myDoc |
| 4400 |
\end{verbatim} |
| 4401 |
This will only count records where the format matches the regular |
| 4402 |
expression \code{.*(bf|it)} (for example, \code{hyperbf} or |
| 4403 |
\code{hyperit}) or the counter name matches \code{section} or |
| 4404 |
\code{subsection} (but not \code{subsubsection}, since the |
| 4405 |
expressions are \gls{anchored}). |
| 4406 |
|
| 4407 |
This syntax doesn't permit the use of the sequence \code{/c/} |
| 4408 |
appearing in the regular expressions, but both the format and |
| 4409 |
counter name are either control sequence names or are a substring of |
| 4410 |
a control sequence name, so they should typically just be |
| 4411 |
alphabetical strings. |
| 4412 |
\argsection{retain-formats} |
| 4413 |
|
| 4414 |
It's possible that you may not want to lose certain \gls{location} |
| 4415 |
formats, even if it means having duplicate \glspl{location}. For example, |
| 4416 |
if you want to move a \gls{principallocation} using |
| 4417 |
\csopt[remove]{save-principal-locations}. In which case, use this |
| 4418 |
switch with a comma-separated list of formats that should be |
| 4419 |
retained. Note that exact duplicates will still be merged. |
| 4420 |
This switch has a cumulative effect. |
| 4421 |
|
| 4422 |
Take care if you use this switch and you have an \idx{explicit-range} with |
| 4423 |
coincident start and end locations. If the |
| 4424 |
\glsdisp{principallocation}{principal record} is between |
| 4425 |
the start and end format markers then the \idx{range} can't collapse |
| 4426 |
to an ordinary \gls{record}. (You may need to use |
| 4427 |
\csopt[true]{merge-ranges}.) |
| 4428 |
|
| 4429 |
\argsection{no-retain-formats} |
| 4430 |
|
| 4431 |
Normal \gls{location} merging rules apply (default). |
| 4432 |
If used in \gls{BibGlsOptions}, this option should be specified as |
| 4433 |
\begin{codeenv} |
| 4434 |
\gls{BibGlsOptions}\marg{retain-formats=false} |
| 4435 |
\end{codeenv} |
| 4436 |
|
| 4437 |
\section{Bib File Options} |
| 4438 |
|
| 4439 |
\argsection{warn-non-bib-fields} |
| 4440 |
|
| 4441 |
If any internal fields are found in the \ext{bib} file, this setting |
| 4442 |
will issue a warning as their use can cause unexpected results. |
| 4443 |
The fields checked for are those listed in Tables~\ref{tab:internalfields} |
| 4444 |
and \ref{tab:baseinternalfields} with a few exceptions, notably |
| 4445 |
\field{type} and \field{sort}. Ideally you shouldn't need to use |
| 4446 |
\field{sort} as there should be an appropriate fallback set up to |
| 4447 |
use if \field{sort} isn't set, such as the label for symbols or the |
| 4448 |
name for terms or the short form for abbreviations (see \sectionref{sec:fallbacks}). |
| 4449 |
|
| 4450 |
This is the default setting and was added as some users were |
| 4451 |
confused over which fields could be used in the \ext{bib} file. |
| 4452 |
The use of these fields can break \bibgls's normal behaviour and |
| 4453 |
cause unexpected results. |
| 4454 |
|
| 4455 |
The check is performed before field aliasing, so it's possible to |
| 4456 |
alias a field to an internal field, such as \field{group}, without |
| 4457 |
triggering this warning. If you do this you need to make sure you |
| 4458 |
have taken appropriate precautions to avoid unexpected results. |
| 4459 |
|
| 4460 |
\argsection{no-warn-non-bib-fields} |
| 4461 |
|
| 4462 |
Switches off the check for non-bib fields. If you use this option |
| 4463 |
you need to make sure you have taken appropriate precautions to |
| 4464 |
avoid unexpected results. |
| 4465 |
If used in \gls{BibGlsOptions}, this option should be specified as |
| 4466 |
\begin{codeenv} |
| 4467 |
\gls{BibGlsOptions}\marg{warn-non-bib-fields=false} |
| 4468 |
\end{codeenv} |
| 4469 |
|
| 4470 |
\argsection{warn-unknown-entry-types} |
| 4471 |
|
| 4472 |
If any unknown \glspl{entrytype} are found in the \ext{bib} file, \bibgls\ |
| 4473 |
will issue a warning with this option set (default). |
| 4474 |
|
| 4475 |
\argsection{no-warn-unknown-entry-types} |
| 4476 |
|
| 4477 |
This option will suppress the warning if an unknown \glspl{entrytype} are |
| 4478 |
found in the \ext{bib} file. |
| 4479 |
If used in \gls{BibGlsOptions}, this option should be specified as |
| 4480 |
\begin{codeenv} |
| 4481 |
\gls{BibGlsOptions}\marg{warn-unknown-entry-types=false} |
| 4482 |
\end{codeenv} |
| 4483 |
|
| 4484 |
\section{Field Options} |
| 4485 |
|
| 4486 |
\argsection{group} |
| 4487 |
|
| 4488 |
The \styfmt{glossaries-extra} \styopt{record} package option |
| 4489 |
automatically creates a new internal field called \field{group}. If the |
| 4490 |
\longarg{group} switch is used with the default \csopt[auto]{group} |
| 4491 |
option then, when sorting, \bibgls\ will try |
| 4492 |
to determine the \idx{group} for each entry and assign it to the |
| 4493 |
\field{group} field. (Some \csopt{sort} options ignore this |
| 4494 |
setting.) This value will be picked up by \ics{printunsrtglossary} |
| 4495 |
if group headings are required (for example with the |
| 4496 |
\glostyle{indexgroup} style) or if group separators are required |
| 4497 |
(for example, the \glostyle{index} style with the default |
| 4498 |
\styopt[false]{nogroupskip}). If you don't require grouping within |
| 4499 |
the glossary, there's no need to use this switch. Note that this |
| 4500 |
switch doesn't automatically select an appropriate glossary style. |
| 4501 |
|
| 4502 |
If you want \idxpl{sub-group}, you will need to use the \csopt{group-level} |
| 4503 |
resource option and ensure you have \sty{glossaries-extra} v1.49+. |
| 4504 |
\Idxpl{smallgroup} can be merged with the \csopt{merge-small-groups} |
| 4505 |
resource option. |
| 4506 |
|
| 4507 |
\begin{important} |
| 4508 |
The \field{group} field should typically not be set in the \ext{bib} |
| 4509 |
file and will trigger a warning if found. The explicit use of the |
| 4510 |
\field{group} key will override \bibgls's normal group formation |
| 4511 |
behaviour, which can cause unexpected results. The custom use of the |
| 4512 |
\field{group} field requires some care. As a general rule, if you |
| 4513 |
find yourself wanting to use the \field{group} field in the |
| 4514 |
\ext{bib} file, then the chances are that what you actually have is |
| 4515 |
a \gls{hierarchicalglossary} (list of topics) and what you really |
| 4516 |
need is the \field{parent} field. Compare the example files |
| 4517 |
\exfile{sample-textsymbols.tex} and |
| 4518 |
\exfile{sample-textsymbols2.tex}. See also |
| 4519 |
\sectionref{sec:logicaldivisions}. |
| 4520 |
\end{important} |
| 4521 |
There are eight types of groups: |
| 4522 |
\begin{description} |
| 4523 |
\item[\idx{lettergroup}] The first non-ignored character of the |
| 4524 |
sort value is alphabetic. This type of group occurs when using the |
| 4525 |
alphabetic sort methods listed in \tableref{tab:sortoptionsrule} or |
| 4526 |
with the letter sort methods listed in |
| 4527 |
\tableref{tab:sortoptionsletter} or with the letter-number sort |
| 4528 |
methods listed in \tableref{tab:sortoptionsletternumber}. The group |
| 4529 |
label is obtained from \gls!{bibglslettergroup}. |
| 4530 |
|
| 4531 |
\item[\idx{nonlettergroup} (or \idx{symbolgroup})] |
| 4532 |
The first non-ignored character of all the sort values within this group |
| 4533 |
are non-alphabetical. This type of group occurs when using the |
| 4534 |
alphabetic sort methods listed in \tableref{tab:sortoptionsrule} or |
| 4535 |
with the letter sort methods listed in |
| 4536 |
\tableref{tab:sortoptionsletter} or with the letter-number sort |
| 4537 |
methods listed in \tableref{tab:sortoptionsletternumber}. |
| 4538 |
The alphabetic sort methods ignore many punctuation |
| 4539 |
characters, so an entry that has a non-alphabetic initial |
| 4540 |
character in the sort value may actually be placed in a |
| 4541 |
\idx{lettergroup}. |
| 4542 |
The group label is obtained from \gls!{bibglsothergroup}. |
| 4543 |
|
| 4544 |
\item[\idx{emptygroup}] The sort value is empty when sorting with an |
| 4545 |
alphabetical, letter or letter-number method, typically a |
| 4546 |
result of the original value consisting solely of commands that \bibgls\ |
| 4547 |
can't interpret. The group label is obtained from \gls!{bibglsemptygroup}. |
| 4548 |
|
| 4549 |
\item[\idx{numbergroup}] The entries were sorted by one of the |
| 4550 |
numeric comparisons listed in \tableref{tab:sortoptionsnumerical}. |
| 4551 |
The group label is obtained from \gls!{bibglsnumbergroup}. |
| 4552 |
|
| 4553 |
\item[\idx{datetimegroup}] The entries were sorted by one of the date-time |
| 4554 |
comparisons listed in \tableref{tab:sortoptionsdatetime} (where both |
| 4555 |
date and time are present). |
| 4556 |
The group label is obtained from \gls!{bibglsdatetimegroup}. |
| 4557 |
|
| 4558 |
\item[\idx{dategroup}] The entries were sorted by one of the date |
| 4559 |
comparisons (where the time is omitted). |
| 4560 |
The group label is obtained from \gls!{bibglsdategroup}. |
| 4561 |
|
| 4562 |
\item[\idx{timegroup}] The entries were sorted by one of the time |
| 4563 |
comparisons (where the date is omitted). |
| 4564 |
The group label is obtained from \gls!{bibglstimegroup}. |
| 4565 |
|
| 4566 |
\item[\idx{customgroup}] The group label is explicitly set either by |
| 4567 |
aliasing a field (with \csopt{field-aliases}) or by using the |
| 4568 |
\csopt[\meta{label}]{group} resource option. You will need to use |
| 4569 |
\gls{glsxtrsetgrouptitle} in the document to provide an associated title if the |
| 4570 |
\meta{label} isn't the same as the title. Remember that with older |
| 4571 |
\LaTeX\ kernels, the label can't contain any active characters, so |
| 4572 |
you can't use non-ASCII characters in \meta{label} with |
| 4573 |
\sty{inputenc} (but you can use non-ASCII alphanumerics with |
| 4574 |
\sty{fontspec}). To ensure better support for UTF-8 with \pdfLaTeX, make sure you |
| 4575 |
have a recent \TeX\ distribution and up-to-date versions of |
| 4576 |
\sty{glossaries} and \sty{glossaries-extra}. |
| 4577 |
|
| 4578 |
\end{description} |
| 4579 |
|
| 4580 |
The \idx{lettergroup} titles will typically have the first character |
| 4581 |
converted to \idx{uppercase} for the alphabet sort methods |
| 4582 |
(\tableref{tab:sortoptionsrule}). A \qt{letter} may not necessarily |
| 4583 |
be a single character (depending on the sort rule), but may be |
| 4584 |
composed of multiple characters, such as a \idx{digraph} (two |
| 4585 |
characters) or \idx{trigraph} (three characters). |
| 4586 |
|
| 4587 |
For example, if the sort rule recognises the digraph \qt{dz} as a |
| 4588 |
letter, then it will be converted to \qt{Dz} for the group title. |
| 4589 |
There are some exceptions to this. For example, the Dutch digraph |
| 4590 |
\qt{ij} should be \qt{IJ} rather than \qt{Ij}. This is indicated |
| 4591 |
by the following line in the \langxml: |
| 4592 |
\begin{verbatim} |
| 4593 |
<entry key="grouptitle.case.ij">IJ</entry> |
| 4594 |
\end{verbatim} |
| 4595 |
If there isn't a \idx{grouptitle.case.lc} key (where |
| 4596 |
\meta{lc} is the \idx!{lowercase} version), then only the first character |
| 4597 |
will be converted to \idx{uppercase} otherwise the value supplied by the |
| 4598 |
resource file is used. This resource key is only checked for |
| 4599 |
the alphabetical comparisons listed in |
| 4600 |
\tableref{tab:sortoptionsrule}. If the initial part of the sort |
| 4601 |
value isn't recognised as a letter according to the sort rule, then |
| 4602 |
the entry will be in a \idx{nonlettergroup} (even if the character is |
| 4603 |
alphabetical). |
| 4604 |
|
| 4605 |
The letter (\tableref{tab:sortoptionsletter}) and letter-number |
| 4606 |
(\tableref{tab:sortoptionsletternumber}) methods only select the |
| 4607 |
first character of the sort value for the group. If the character is |
| 4608 |
alphabetical\footnote{according to Java's |
| 4609 |
\code{Character.isAlphabetic(int)} method} then it will be a |
| 4610 |
\idx{lettergroup} otherwise it's a \idx{nonlettergroup}. The case-insensitive |
| 4611 |
ordering (such as \csopt[letter-nocase]{sort}) will convert the |
| 4612 |
letter group character to \idx{uppercase}. The case-sensitive ordering |
| 4613 |
(such as \csopt[letter-case]{sort}) won't change the case. |
| 4614 |
|
| 4615 |
Glossary styles with navigational links to groups (such as |
| 4616 |
\glostyle{indexhypergroup}) require an extra run for the ordinary |
| 4617 |
\cs{cs.makeglossaries} and \cs{makenoidxglossaries} methods. For |
| 4618 |
example, for the document \filefmt{myDoc.tex}: |
| 4619 |
\begin{verbatim} |
| 4620 |
pdflatex myDoc |
| 4621 |
makeglossaries myDoc |
| 4622 |
pdflatex myDoc |
| 4623 |
pdflatex myDoc |
| 4624 |
\end{verbatim} |
| 4625 |
On the first \appfmt{pdflatex} call, there's no glossary. On the second |
| 4626 |
\appfmt{pdflatex}, there's a glossary but the glossary must be |
| 4627 |
processed to find the group information, which is written to the |
| 4628 |
\iext{aux} file as |
| 4629 |
\nosecdef{@gls@hypergroup} |
| 4630 |
The third \appfmt{pdflatex} reads this information and is then able |
| 4631 |
to create the navigation links. |
| 4632 |
|
| 4633 |
With \bibgls, if the \optfmt{type} is provided (through the |
| 4634 |
\field{type} field or via options such as \csopt{type} and |
| 4635 |
\csopt{dual-type}) then this information can be determined when |
| 4636 |
\bibgls\ is ready to write the \iext{glstex} file, which means that |
| 4637 |
the extra \LaTeX\ run isn't necessary. If \bibgls\ doesn't know |
| 4638 |
the glossary type then it will fallback on the original method |
| 4639 |
which requires an extra \LaTeX\ run. |
| 4640 |
|
| 4641 |
For example: |
| 4642 |
\begin{codeenv} |
| 4643 |
\cmd{documentclass}\marg{article} |
| 4644 |
\cmd{usepackage}\oarg{colorlinks}\marg{hyperref} |
| 4645 |
\cmd{usepackage}\oarg{\styopt{record},\styopt{abbreviations},\styopt[indexhypergroup]{style}}\marg{glossaries-extra} |
| 4646 |
\strut |
| 4647 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\comment{data in entries.bib} |
| 4648 |
\csopt[main]{type}\comment{put these entries in the 'main' glossary} |
| 4649 |
} |
| 4650 |
\strut |
| 4651 |
\gls{GlsXtrLoadResources}\oarg{\csopt[abbrvs]{src},\comment{data in abbrvs.bib} |
| 4652 |
\csopt[abbreviations]{type}\comment{put entries in the 'abbreviations' glossary} |
| 4653 |
} |
| 4654 |
\end{codeenv} |
| 4655 |
Here the \csopt{type} is set and \bibgls\ can detect that |
| 4656 |
\isty{hyperref} has been loaded, so if the \longarg{group} switch |
| 4657 |
is used, then the group hyperlinks can be set (using |
| 4658 |
\gls!{bibglshypergroup}). This means that the build process is |
| 4659 |
just: |
| 4660 |
\begin{verbatim} |
| 4661 |
pdflatex myDoc |
| 4662 |
bibtex --group myDoc |
| 4663 |
pdflatex myDoc |
| 4664 |
\end{verbatim} |
| 4665 |
Note that this requires \isty{glossaries} v4.53+ and |
| 4666 |
\isty{glossaries-extra} v1.53. If your version of \sty{glossaries} |
| 4667 |
or \sty{glossaries-extra} is too old, an extra \LaTeX\ run is |
| 4668 |
required. |
| 4669 |
|
| 4670 |
If \isty{hyperref} isn't loaded or the \longarg{group} switch |
| 4671 |
isn't used or the \field{type} isn't set or your version of |
| 4672 |
\sty{glossaries} is too old, then the information can't be saved in |
| 4673 |
the \ext{glstex} file. |
| 4674 |
|
| 4675 |
For example: |
| 4676 |
\begin{codeenv} |
| 4677 |
\cmd{documentclass}\marg{article} |
| 4678 |
\cmd{usepackage}\oarg{colorlinks}\marg{hyperref} |
| 4679 |
\cmd{usepackage}\oarg{\styopt{record},\styopt{abbreviations},\styopt[indexhypergroup]{style}}\marg{glossaries-extra} |
| 4680 |
\strut |
| 4681 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}}\comment{data in entries.bib} |
| 4682 |
\gls{GlsXtrLoadResources}\oarg{\csopt[abbrvs]{src}}\comment{data in abbrvs.bib} |
| 4683 |
\end{codeenv} |
| 4684 |
This requires the build process: |
| 4685 |
\begin{verbatim} |
| 4686 |
pdflatex myDoc |
| 4687 |
bibtex --group myDoc |
| 4688 |
pdflatex myDoc |
| 4689 |
pdflatex myDoc |
| 4690 |
\end{verbatim} |
| 4691 |
because the group hyperlink information can't be determined by |
| 4692 |
\bibgls, so it's best to always set the \optfmt{type} if you want |
| 4693 |
hyper-group styles, and make sure you have an up-to-date version of |
| 4694 |
\styfmt{glossaries} (and \styfmt{glossaries-extra}). |
| 4695 |
|
| 4696 |
\argsection{no-group} |
| 4697 |
|
| 4698 |
Don't automatically set the \field{group} field with |
| 4699 |
\csopt[auto]{group} (default). The glossary won't have groups even if a |
| 4700 |
group style, such as \glostyle{indexgroup}, is used (unless the |
| 4701 |
\field{group} field is set to a custom value). |
| 4702 |
If used in \gls{BibGlsOptions}, this option should be specified as |
| 4703 |
\begin{codeenv} |
| 4704 |
\gls{BibGlsOptions}\marg{group=false} |
| 4705 |
\end{codeenv} |
| 4706 |
|
| 4707 |
\argsection{no-expand-fields} |
| 4708 |
|
| 4709 |
By default, \gls{newglossaryentry} and similar commands expand field values |
| 4710 |
(except for \field{name}, \field{symbol} and \field{description}). |
| 4711 |
This is useful if constructing field values programmatically |
| 4712 |
(for example in a \idx!{loop}) but can cause a problem if certain fragile |
| 4713 |
commands are included in the field. |
| 4714 |
|
| 4715 |
The switch \longarg{no-expand-fields} makes \bibgls\ write |
| 4716 |
\gls{glsnoexpandfields} to the \iext{glstex} file, which |
| 4717 |
switches off the expansion. Since \bibgls\ is simply |
| 4718 |
fetching the data from \iext{bib} files, it's unlikely |
| 4719 |
that this automatic expansion is required and since it can |
| 4720 |
also be problematic this option is on by default. You can |
| 4721 |
switch it off with \longarg{expand-fields}. |
| 4722 |
|
| 4723 |
If used in \gls{BibGlsOptions}, this option should be specified as |
| 4724 |
\begin{codeenv} |
| 4725 |
\gls{BibGlsOptions}\marg{expand-fields=false} |
| 4726 |
\end{codeenv} |
| 4727 |
|
| 4728 |
\argsection{expand-fields} |
| 4729 |
|
| 4730 |
Don't write \gls{glsnoexpandfields} to the \iext{glstex} file, |
| 4731 |
allowing fields to expand when the entries are defined. |
| 4732 |
Remember that this doesn't include the \field{name}, \field{symbol} |
| 4733 |
or \field{description} fields, which need to have their |
| 4734 |
expansion switched on with \gls{glssetexpandfield} |
| 4735 |
before the entries are defined (that is, before using |
| 4736 |
\gls!{GlsXtrLoadResources}). |
| 4737 |
|
| 4738 |
\argsection{mfirstuc-protection} |
| 4739 |
|
| 4740 |
If you have \isty{mfirstuc} v2.08+, \isty{glossaries} v4.50+ |
| 4741 |
and \isty{glossaries-extra} v1.49+ then this setting shouldn't be |
| 4742 |
required any more as there's now better \idx{sentencecase} handling. |
| 4743 |
If these versions are detected in the \ext{log} file then the |
| 4744 |
default will switch to \longarg{no-mfirstuc-protection} |
| 4745 |
otherwise the default is \longarg{mfirstuc-protection}. If this causes any |
| 4746 |
problems, use \longarg{mfirstuc-protection} to re-enable this |
| 4747 |
setting. The information below relates to older versions. |
| 4748 |
|
| 4749 |
Commands like \ics{Gls} use \ics{makefirstuc} provided by the |
| 4750 |
\isty{mfirstuc} package. This command has limitations and one of the |
| 4751 |
things that can break it is the use of a referencing command |
| 4752 |
at the start of its argument. The \sty{glossaries-extra} package has |
| 4753 |
more detail about the problem in the \qt{Nested Links} section of |
| 4754 |
the user manual~\cite{glossaries-extra}. If a glossary field starts |
| 4755 |
with one of these problematic commands, the recommended method (if |
| 4756 |
the command can't be replaced) is to insert an empty group in front |
| 4757 |
of it. |
| 4758 |
|
| 4759 |
For example, the following definition |
| 4760 |
\begin{codeenv} |
| 4761 |
\gls{newabbreviation}\marg{shtml}\marg{shtml}\marg{\ics{glsps}\marg{ssi} enabled \cs{glsps}\marg{short}\marg{html}} |
| 4762 |
\end{codeenv} |
| 4763 |
will cause a problem for \code{\cs{Gls}\marg{shtml}} on first use. |
| 4764 |
The above example would be written in a \ext{bib} file as: |
| 4765 |
\begin{codeenv} |
| 4766 |
\atentry{abbreviation}\marg{shtml, |
| 4767 |
\field{short}=\marg{shtml}, |
| 4768 |
\field{long}=\marg{\cs{glsps}\marg{ssi} enabled \cs{glsps}\marg{html}} |
| 4769 |
} |
| 4770 |
\end{codeenv} |
| 4771 |
The default \sty{mfirstuc} protection will automatically insert an empty |
| 4772 |
group before \code{\cs{glsps}\marg{ssi}} when writing the definition |
| 4773 |
in the \ext{glstex} file. |
| 4774 |
|
| 4775 |
The argument for this switch should either be a comma-separated list |
| 4776 |
of fields or the keyword \code{all} (which indicates all fields). |
| 4777 |
\bibgls\ will automatically insert an empty group at the start of |
| 4778 |
the listed fields that start with a problematic command, and a |
| 4779 |
warning will be written to the transcript. Unknown fields are |
| 4780 |
skipped even if they're included in the list. An empty argument is |
| 4781 |
equivalent to \longarg{no-mfirstuc-protection}. The default value is |
| 4782 |
\code{all}. |
| 4783 |
|
| 4784 |
\argsection{no-mfirstuc-protection} |
| 4785 |
|
| 4786 |
Switches off the \isty{mfirstuc} protection mechanism described |
| 4787 |
above. |
| 4788 |
If used in \gls{BibGlsOptions}, this option should be specified as |
| 4789 |
\begin{codeenv} |
| 4790 |
\gls{BibGlsOptions}\marg{mfirstuc-protection=false} |
| 4791 |
\end{codeenv} |
| 4792 |
|
| 4793 |
\argsection{mfirstuc-math-protection} |
| 4794 |
|
| 4795 |
If you have \isty{mfirstuc} v2.08+, \isty{glossaries} v4.50+ and |
| 4796 |
\isty{glossaries-extra} v1.49+ then this setting shouldn't be |
| 4797 |
required any more as there's now better \idx{sentencecase} handling. If |
| 4798 |
these versions are detected in the \ext{log} file then the default |
| 4799 |
will switch to \longarg{no-mfirstuc-math-protection}. If this causes |
| 4800 |
any problems, use \longarg{mfirstuc-math-protection} to re-enable |
| 4801 |
this setting. The information below relates to older versions. |
| 4802 |
|
| 4803 |
This setting works in the same way as \longarg{mfirstuc-protection} but |
| 4804 |
guards against fields starting with inline maths |
| 4805 |
(\idx{mshiftchar}\ldots\idx{mshiftchar}). For example, if the |
| 4806 |
\field{name} field starts with |
| 4807 |
\code{\idx{mshiftchar}x\idx{mshiftchar}} and the glossary style |
| 4808 |
automatically tries to convert the first letter of the name to |
| 4809 |
\idx{uppercase}, then this will cause a problem. |
| 4810 |
|
| 4811 |
With \longarg{mfirstuc-math-protection} set, \bibgls\ will |
| 4812 |
automatically insert an empty group at the start of the field and |
| 4813 |
write a warning in the transcript. This setting is on by default. |
| 4814 |
|
| 4815 |
\argsection{no-mfirstuc-math-protection} |
| 4816 |
|
| 4817 |
Switches off the above. |
| 4818 |
If used in \gls{BibGlsOptions}, this option should be specified as |
| 4819 |
\begin{codeenv} |
| 4820 |
\gls{BibGlsOptions}\marg{mfirstuc-math-protection=false} |
| 4821 |
\end{codeenv} |
| 4822 |
|
| 4823 |
\argsection{nested-link-check} |
| 4824 |
|
| 4825 |
By default, \bibgls\ will parse certain fields for potential nested links. |
| 4826 |
(See the section \qt{Nested Links} in the \sty{glossaries-extra} |
| 4827 |
user manual~\cite{glossaries-extra}.) |
| 4828 |
|
| 4829 |
The default set of fields to check are: \field{name}, \field{text}, |
| 4830 |
\field{plural}, \field{first}, \field{firstplural}, \field{long}, |
| 4831 |
\field{longplural}, \field{short}, \field{shortplural} and |
| 4832 |
\field{symbol}. |
| 4833 |
|
| 4834 |
You can change this set of fields using |
| 4835 |
\longarg{nested-link-check} \meta{value} where \meta{value} may be |
| 4836 |
\optfmt{none} (don't parse any of the fields) or a comma-separated |
| 4837 |
list of fields to be checked. |
| 4838 |
|
| 4839 |
\argsection{no-nested-link-check} |
| 4840 |
|
| 4841 |
Equivalent to \longarg{nested-link-check} \optfmt{none}. |
| 4842 |
If used in \gls{BibGlsOptions}, this option should be specified as |
| 4843 |
\begin{codeenv} |
| 4844 |
\gls{BibGlsOptions}\marg{nested-link-check=none} |
| 4845 |
\end{codeenv} |
| 4846 |
or |
| 4847 |
\begin{codeenv} |
| 4848 |
\gls{BibGlsOptions}\marg{nested-link-check=false} |
| 4849 |
\end{codeenv} |
| 4850 |
|
| 4851 |
\argsection{shortcuts} |
| 4852 |
|
| 4853 |
Some entries may reference another entry within a field, using |
| 4854 |
commands like \ics{gls}, so \bibgls\ parses the fields for these |
| 4855 |
commands to determine dependent entries to allow them to be selected |
| 4856 |
even if they haven't been used within the document. |
| 4857 |
The \styopt{shortcuts} package option provided by |
| 4858 |
\styfmt{glossaries-extra} defines various synonyms, such as \ics{ac} |
| 4859 |
which is equivalent to \ics{gls}. By default the value of the |
| 4860 |
\styopt{shortcuts} option will be picked up by \bibgls\ when parsing the |
| 4861 |
\iext{aux} file. This then allows \bibgls\ to additionally search for |
| 4862 |
those shortcut commands while parsing the fields. |
| 4863 |
|
| 4864 |
You can override the \styopt{shortcuts} setting using |
| 4865 |
\longarg{shortcuts} \meta{value} (where \meta{value} may take |
| 4866 |
any of the allowed values for the \styopt{shortcuts} package option), |
| 4867 |
but in general there is little need to use this switch. |
| 4868 |
|
| 4869 |
\argsection{trim-fields} |
| 4870 |
|
| 4871 |
Trim leading and trailing spaces from all field values. For example, |
| 4872 |
if the \ext{bib} file contains: |
| 4873 |
\begin{codeenv} |
| 4874 |
\atentry{entry}\marg{sample, |
| 4875 |
\field{name} = \marg{sample}, |
| 4876 |
\field{description} = \marg{ |
| 4877 |
an example |
| 4878 |
} |
| 4879 |
} |
| 4880 |
\end{codeenv} |
| 4881 |
This will cause spurious spaces in the \field{description} field. |
| 4882 |
Using \longarg{trim-fields} will automatically trim the values |
| 4883 |
before writing the \iext{glstex} file. |
| 4884 |
|
| 4885 |
Note that even without this trimming option on, fields that are |
| 4886 |
set as keys within \cs{longnewglossaryentry} or the optional |
| 4887 |
argument of \cs{newabbreviation} will automatically have the leading and |
| 4888 |
trailing spaces internally trimmed by the \isty{xkeyval} package, so |
| 4889 |
this trimming action only affects fields that aren't set in this |
| 4890 |
way, such as the \field{description}, \field{long} and \field{short} |
| 4891 |
fields. If you specifically require a space at the start or end of a |
| 4892 |
field then use a spacing command, such as \cs{cs.space} or \cs{space} |
| 4893 |
or \idx{nbspchar}. |
| 4894 |
|
| 4895 |
\argsection{trim-only-fields} |
| 4896 |
|
| 4897 |
Only trim leading and trailing spaces from the fields identified in |
| 4898 |
the comma-separated \meta{list}. This option has a cumulative effect |
| 4899 |
but is cancelled by \longarg{no-trim-fields} (which switches off all |
| 4900 |
trimming) and by \longarg{trim-fields} (which switches on trimming |
| 4901 |
for all fields). This option may not be used with |
| 4902 |
\longarg{trim-except-fields}. |
| 4903 |
|
| 4904 |
For example, to only trim the \field{description} field: |
| 4905 |
\begin{verbatim} |
| 4906 |
bib2gls --trim-only-fields description myDoc |
| 4907 |
\end{verbatim} |
| 4908 |
|
| 4909 |
\argsection{trim-except-fields} |
| 4910 |
|
| 4911 |
Trim all leading and trailing spaces from fields except those identified in |
| 4912 |
the comma-separated \meta{list}. This option has a cumulative effect |
| 4913 |
but is cancelled by \longarg{no-trim-fields} (which switches off all |
| 4914 |
trimming) and by \longarg{trim-fields} (which switches on trimming |
| 4915 |
for all fields). This option may not be used with |
| 4916 |
\longarg{trim-only-fields}. See the above note about \sty{xkeyval}. |
| 4917 |
|
| 4918 |
For example, to trim all fields except \field{short} and |
| 4919 |
\field{long}: |
| 4920 |
\begin{verbatim} |
| 4921 |
bib2gls --trim-except-fields short,long myDoc |
| 4922 |
\end{verbatim} |
| 4923 |
Or |
| 4924 |
\begin{verbatim} |
| 4925 |
bib2gls --trim-except-fields short --trim-except-fields long myDoc |
| 4926 |
\end{verbatim} |
| 4927 |
|
| 4928 |
\argsection{no-trim-fields} |
| 4929 |
|
| 4930 |
Don't trim any leading or trailing spaces from field values (but see |
| 4931 |
the above note about \sty{xkeyval}). This is the default setting. |
| 4932 |
If used in \gls{BibGlsOptions}, this option should be specified as |
| 4933 |
\begin{codeenv} |
| 4934 |
\gls{BibGlsOptions}\marg{trim-fields=false} |
| 4935 |
\end{codeenv} |
| 4936 |
|
| 4937 |
\section{Other Options} |
| 4938 |
|
| 4939 |
\argsection{force-cross-resource-refs} |
| 4940 |
|
| 4941 |
Force \igls{crossresourceref} mode on (see |
| 4942 |
\sectionref{sec:resourcesets}). |
| 4943 |
|
| 4944 |
\argsection{no-force-cross-resource-refs} |
| 4945 |
|
| 4946 |
Don't force \igls{crossresourceref} mode on (default). |
| 4947 |
The mode will be enabled if applicable (see |
| 4948 |
\sectionref{sec:resourcesets}). |
| 4949 |
If used in \gls{BibGlsOptions}, this option should be specified as |
| 4950 |
\begin{codeenv} |
| 4951 |
\gls{BibGlsOptions}\marg{force-cross-resource-refs=false} |
| 4952 |
\end{codeenv} |
| 4953 |
|
| 4954 |
\argsection{provide-glossaries} |
| 4955 |
|
| 4956 |
This setting will make \bibgls\ add the line |
| 4957 |
\begin{codeenv} |
| 4958 |
\ics{provideignoredglossary*}\margm{type} |
| 4959 |
\end{codeenv} |
| 4960 |
to the \ext{glstex} file before an entry is defined where that entry |
| 4961 |
has the \field{type} field set to an unknown glossary type (\bibgls\ |
| 4962 |
can detect from the \ext{aux} file all glossaries that have been |
| 4963 |
defined with \cs{newglossary} but not those defined with \cs{newignoredglossary}). |
| 4964 |
|
| 4965 |
This ensures that the glossary exists, but the use of |
| 4966 |
\ics{provideignoredglossary} (rather than \cs{newignoredglossary}) |
| 4967 |
will prevent an error if the glossary has already been defined. |
| 4968 |
|
| 4969 |
\argsection{no-provide-glossaries} |
| 4970 |
|
| 4971 |
This setting prevents \bibgls\ from providing unknown glossaries, |
| 4972 |
except in a few documented situations (the \csopt{master}, |
| 4973 |
\csopt{trigger-type}, \csopt{ignored-type} and \csopt{secondary} options). This is the |
| 4974 |
default since it's a useful way of detecting misspelt glossary |
| 4975 |
labels. It's harder to detect the problem if a misspelt label has |
| 4976 |
caused an entry to be added to a hidden glossary. |
| 4977 |
If used in \gls{BibGlsOptions}, this option should be specified as |
| 4978 |
\begin{codeenv} |
| 4979 |
\gls{BibGlsOptions}\marg{provide-glossaries=false} |
| 4980 |
\end{codeenv} |
| 4981 |
|
| 4982 |
\argsection{replace-quotes} |
| 4983 |
|
| 4984 |
Single and double-quote characters (\idx{aposchar} and |
| 4985 |
\idx{doublequotechar}) will be written as \cs{bibglsaposchar} and |
| 4986 |
\cs{bibglsdoublequotechar} in field values and group information |
| 4987 |
written to the \ext{glstex} file. |
| 4988 |
|
| 4989 |
\argsection{no-replace-quotes} |
| 4990 |
|
| 4991 |
Single and double-quote characters (\idx{aposchar} and |
| 4992 |
\idx{doublequotechar}) will be written as those actual characters |
| 4993 |
(default). |
| 4994 |
If used in \gls{BibGlsOptions}, this option should be specified as |
| 4995 |
\begin{codeenv} |
| 4996 |
\gls{BibGlsOptions}\marg{replace-quotes=false} |
| 4997 |
\end{codeenv} |
| 4998 |
|
| 4999 |
\chapter{\iext{bib} Format} |
| 5000 |
\label{sec:bib} |
| 5001 |
\setsecdepth{1} |
| 5002 |
|
| 5003 |
\bibgls\ recognises certain \glspl{entrytype}. Any unrecognised types will |
| 5004 |
be ignored and a warning will be written to the transcript file. |
| 5005 |
Bib file entry types can be divided into: special entry types and |
| 5006 |
glossary entry types. The resource options mostly apply only to |
| 5007 |
the glossary entry types (except where noted). |
| 5008 |
|
| 5009 |
The glossary entry types correspond to glossary entries that can be |
| 5010 |
referenced in the document with commands like \ics{gls}. |
| 5011 |
They are defined in the usual \ext{bib} format: |
| 5012 |
\begin{codeenv*} |
| 5013 |
\idx{atchar}\meta{entry-type}\marg{\meta{id}, |
| 5014 |
\meta{field-name-1} = \margm{text}, |
| 5015 |
\ldots |
| 5016 |
\meta{field-name-n} = \margm{text} |
| 5017 |
} |
| 5018 |
\end{codeenv*} |
| 5019 |
where \meta{entry-type} is the \gls{entrytype} (listed below), |
| 5020 |
\meta{field-name-1}, \ldots, \meta{field-name-n} are the field names and |
| 5021 |
\meta{id} is a unique label. The label can't contain any spaces or |
| 5022 |
commas, and most special characters are forbidden. The hyphen character and |
| 5023 |
some other punctuation characters are allowed by \bibgls, but you need to make |
| 5024 |
sure that your document hasn't made them active. In general it's best to |
| 5025 |
stick with alpha-numeric labels. The field values may be delimited by braces |
| 5026 |
\margm{text} or double-quotes \code{\qtdelim{\meta{text}}}. |
| 5027 |
|
| 5028 |
The \csopt{label-prefix} option can be used to instruct \bibgls\ to |
| 5029 |
insert prefixes to the labels (\meta{id}) when the data is read. |
| 5030 |
Remember to use these prefixes when you reference the entries in the |
| 5031 |
document, but don't include them when you reference them in the |
| 5032 |
\ext{bib} file. There are some special prefixes that have a |
| 5033 |
particular meaning to \bibgls: \qt{\idprefix{dual}} and |
| 5034 |
\qt{\idprefix{extn}} where \meta{n} is a positive integer. |
| 5035 |
In the first case, \idprefix{dual} references the dual element of a |
| 5036 |
dual entry (see \atentry{dualentry}). This prefix will be |
| 5037 |
replaced by the value of the \csopt{dual-prefix} option. The |
| 5038 |
\idprefix{extn} prefix is used to reference an entry from a |
| 5039 |
different set of resources (loaded by another |
| 5040 |
\gls{GlsXtrLoadResources} command). This prefix is replaced by the |
| 5041 |
corresponding element of the list supplied by \csopt{ext-prefixes}, |
| 5042 |
but this is only supported if the \igls{crossresourceref} mode is enabled |
| 5043 |
(see \sectionref{sec:resourcesets}). |
| 5044 |
|
| 5045 |
In the event that the \field{sort} value falls back on the label, |
| 5046 |
the original label supplied in the \ext{bib} file is used, not the |
| 5047 |
prefixed label. |
| 5048 |
|
| 5049 |
\section{Encoding} |
| 5050 |
\label{sec:bibencoding} |
| 5051 |
|
| 5052 |
If you are using \XeLaTeX\ or \LuaLaTeX\ (which are natively UTF-8) |
| 5053 |
or if you are using a modern \TeX\ distribution \pdfLaTeX\ with |
| 5054 |
UTF-8 support, then you can have UTF-8 characters in the \meta{id} |
| 5055 |
of your entries. (Avoid \TeX\ special characters, active characters |
| 5056 |
or characters that are part of the \ext{bib} syntax.) |
| 5057 |
|
| 5058 |
You can set the character \igls{encoding} in the \ext{bib} file using: |
| 5059 |
\begin{codeenv} |
| 5060 |
\idx{commentchar} Encoding: \meta{encoding-name} |
| 5061 |
\end{codeenv} |
| 5062 |
where \meta{encoding-name} is the name of the character \gls{encoding}. |
| 5063 |
For example: |
| 5064 |
\begin{verbatim} |
| 5065 |
% Encoding: UTF-8 |
| 5066 |
\end{verbatim} |
| 5067 |
You can also set the \gls{encoding} using the \csopt{charset} option, |
| 5068 |
but it's simpler to include the above comment on the first line of |
| 5069 |
the \ext{bib} file. (This comment is also searched for by JabRef |
| 5070 |
to determine the \gls{encoding}, so it works for both applications.) |
| 5071 |
If you don't use either method \bibgls\ will |
| 5072 |
have to search the entire \ext{bib} file, which is inefficient and |
| 5073 |
you may end up with a mismatched \gls{encoding}. |
| 5074 |
|
| 5075 |
\begin{important} |
| 5076 |
The encoding comment line must come before any non-ASCII content |
| 5077 |
otherwise a malformed input error may occur while parsing the file |
| 5078 |
for the comment line. |
| 5079 |
\end{important} |
| 5080 |
|
| 5081 |
If there is no encoding line in the \ext{bib} file and the |
| 5082 |
\csopt{charset} option hasn't been used, then the default encoding |
| 5083 |
will be assumed (see \sectionref{sec:defencoding}). |
| 5084 |
|
| 5085 |
\section{Fields} |
| 5086 |
\label{sec:fields} |
| 5087 |
|
| 5088 |
Each \gls{entrytype} may have required fields, optional fields and |
| 5089 |
ignored fields. These are set using a \keyvallist\ within |
| 5090 |
\code{@\meta{entry-type}\marg{\meta{id},\meta{fields}}} in the |
| 5091 |
\ext{bib} file. Most keys recognised by |
| 5092 |
\gls{newglossaryentry} may be used as a field unless \bibgls\ |
| 5093 |
considers them an internal field (see below). In general, you |
| 5094 |
shouldn't need to use the \field{sort} field. |
| 5095 |
|
| 5096 |
If an optional field is missing and \bibgls\ needs to access it for |
| 5097 |
some reason, \bibgls\ will try to fallback on another value. The |
| 5098 |
actual fallback value depends on the \gls{entrytype}. The most common |
| 5099 |
fallback is that used if the \field{sort} field is missing, which is |
| 5100 |
typically the case. This approach allows different \glspl{entrytype} to |
| 5101 |
have different fields used for sorting (see \sectionref{sec:fallbacks}). |
| 5102 |
|
| 5103 |
Predefined fields for use in \ext{bib} files are listed in |
| 5104 |
Tables~\ref{tab:fields}, \ref{tab:bib2glsfields}, |
| 5105 |
\ref{tab:prefixfields} and~\ref{tab:accsuppfields}. If you add any |
| 5106 |
custom keys in your document using \ics{glsaddkey} or |
| 5107 |
\ics{glsaddstoragekey}, those commands must be placed before the |
| 5108 |
first use of \gls{GlsXtrLoadResources} to ensure that \bibgls\ |
| 5109 |
recognises them as a valid field name. |
| 5110 |
|
| 5111 |
\begin{important} |
| 5112 |
If you define your own custom keys, ensure that they don't contain |
| 5113 |
spaces, commas (\idx{commasep}), equal signs (\idx{equalsassign}) or |
| 5114 |
any other character that isn't supported by the \ext{bib} format. |
| 5115 |
Additionally, if you want to use \csopt{assign-fields}, ensure |
| 5116 |
that you don't use any of the assignment special characters, such as |
| 5117 |
plus (\idx{concat-plus}), within any |
| 5118 |
field names. |
| 5119 |
\end{important} |
| 5120 |
|
| 5121 |
Internal fields that may be assigned within the document (the |
| 5122 |
\LaTeX\ assignment code having been written by \bibgls\ in the |
| 5123 |
\iext{glstex} file) are listed in Table~\ref{tab:internalfields}. |
| 5124 |
These typically shouldn't be used in the \ext{bib} file. Some of |
| 5125 |
these fields can be set for a particular document using a resource |
| 5126 |
option, such as \csopt{type} or \csopt{group}. With |
| 5127 |
\longarg{warn-non-bib-fields} set, \bibgls\ will check for internal |
| 5128 |
fields that can cause interference with its normal operations and |
| 5129 |
will warn if any are found in the \ext{bib} file. |
| 5130 |
|
| 5131 |
There are also some fields that are set and used by |
| 5132 |
\styfmt{glossaries} or \styfmt{glossaries-extra} listed in |
| 5133 |
Table~\ref{tab:baseinternalfields} that aren't recognised by \bibgls. |
| 5134 |
In most cases these fields don't have a designated key and are only |
| 5135 |
intended for internal use by \bibgls\ or by the \styfmt{glossaries} or |
| 5136 |
\styfmt{glossaries-extra} package. Note that the value of the \field{sort} field |
| 5137 |
written to the \ext{bib} file doesn't always exactly match the sort |
| 5138 |
value used by \bibgls\ (which is stored in \field{bib2gls@sort}). |
| 5139 |
Any special characters found in the sort value are always substituted |
| 5140 |
before writing the \ext{bib} file to avoid syntax errors. |
| 5141 |
|
| 5142 |
Any unrecognised fields will be ignored by \bibgls. This is more |
| 5143 |
convenient than using \ics{input} or \gls{loadglsentries}, which |
| 5144 |
requires all the keys used in the file to be defined, regardless of |
| 5145 |
whether or not you actually need them in the document. |
| 5146 |
|
| 5147 |
Other entries can be cross-referenced using the \field{see}, |
| 5148 |
\field{seealso} or \field{alias} fields or |
| 5149 |
by using commands like \ics{gls} or \ics{glsxtrp} in any of the |
| 5150 |
recognised fields. These will automatically be selected if the |
| 5151 |
\csopt{selection} setting includes dependencies, but you may need to |
| 5152 |
rebuild the document to ensure the \glspl{locationlist} are correct. Use |
| 5153 |
of the \ics{glssee} command will create an \igls{ignoredrecord} and the |
| 5154 |
\field{see} field will be set to the relevant information. If an |
| 5155 |
entry has the \field{see} field already set, any instance of |
| 5156 |
\ics{glssee} in the document for that entry will be appended to the |
| 5157 |
\field{see} field (provided you have at least v1.14 of |
| 5158 |
\sty{glossaries-extra}). In general, it's best just to use the |
| 5159 |
\field{see} field and not use \ics{glssee}. |
| 5160 |
|
| 5161 |
The \field{seealso} key was only added to \sty{glossaries-extra} |
| 5162 |
v1.16, but this field may be used with \bibgls\ even if you only |
| 5163 |
have version 1.14 or 1.15. If the key isn't available, |
| 5164 |
\code{\field{seealso}=\margm{xr-list}} will be treated as |
| 5165 |
\code{\field{see}=\marg{[\ics{seealsoname}]\meta{xr-list}}} (the resource |
| 5166 |
option \csopt{seealso} won't have an effect). You can't use both |
| 5167 |
\field{see} and \field{seealso} for the same entry with \bibgls. |
| 5168 |
Note that the \field{seealso} field doesn't allow for the optional |
| 5169 |
\oargm{tag} part. If you need a different tag, either use \field{see} |
| 5170 |
or change the definition of \ics{seealsoname} or |
| 5171 |
\ics{glsxtruseseealsoformat}. Note that, unless you are using |
| 5172 |
\idx!{xindy}, \ics{glsxtrindexseealso} just does |
| 5173 |
\ics{glssee}\oarg{\ics{seealsoname}}, and so will be treated as \field{see} |
| 5174 |
rather than \field{seealso} by \bibgls. Again, it's better to just |
| 5175 |
use the \field{seealso} field directly. |
| 5176 |
|
| 5177 |
You can identify an arbitrary field as containing a list of dependent entry |
| 5178 |
labels with \csopt{dependency-fields}. This instructs \bibgls\ to parse the |
| 5179 |
listed fields for dependencies in a similar manner to the \field{see} field, |
| 5180 |
but it doesn't add any information to the cross-referencing part of the |
| 5181 |
\gls{locationlist}. The option may be used in combination with the \field{see} or |
| 5182 |
\field{seealso} fields. |
| 5183 |
|
| 5184 |
\clearpage |
| 5185 |
|
| 5186 |
\printfields |
| 5187 |
{basefield,extrafield} |
| 5188 |
{Fields Provided by \styfmt{glossaries-extra}} |
| 5189 |
{tab:fields} |
| 5190 |
|
| 5191 |
\clearpage |
| 5192 |
|
| 5193 |
\printfields |
| 5194 |
{bib2glsfield} |
| 5195 |
{Fields Provided by \bibgls} |
| 5196 |
{tab:bib2glsfields} |
| 5197 |
|
| 5198 |
\printfields |
| 5199 |
{prefixfield}% |
| 5200 |
[Fields Provided by \styfmt{glossaries-prefix}]% |
| 5201 |
{Fields Provided by \isty{glossaries-prefix}} |
| 5202 |
{tab:prefixfields} |
| 5203 |
|
| 5204 |
\printfields |
| 5205 |
[% |
| 5206 |
Don't load \isty{glossaries-accsupp} directly (with \ics{usepackage}) |
| 5207 |
when using \styfmt{glossaries-extra}. Load using the |
| 5208 |
\glsadd{idx.accsupp}\styopt{accsupp} |
| 5209 |
package option instead. |
| 5210 |
%\begin{codeenv} |
| 5211 |
%\cs{usepackage}\oarg{\styopt{record},\styopt{accsupp}}\marg{glossaries-extra} |
| 5212 |
%\end{codeenv} |
| 5213 |
]% |
| 5214 |
{accessfield}% |
| 5215 |
[Fields Provided by \styfmt{glossaries-accsupp}]% |
| 5216 |
{Fields Provided by \isty{glossaries-accsupp}} |
| 5217 |
{tab:accsuppfields} |
| 5218 |
|
| 5219 |
\printfields |
| 5220 |
[% |
| 5221 |
You may define and assign \field{bibtextype} as a key (although it's more |
| 5222 |
likely to be aliased). Don't define any of the others listed in this |
| 5223 |
table, and don't use any of them in the \ext{bib} file. A possible |
| 5224 |
exception is the \field{type} field, but it's more flexible to set |
| 5225 |
that through a resource option. The explicit use of \field{group} |
| 5226 |
within a \ext{bib} file can cause unpredictable |
| 5227 |
results and is best set through a resource option or by \bibgls. |
| 5228 |
In general, you shouldn't need to set the \field{sort} field as |
| 5229 |
appropriate fallbacks should produce useful sort values |
| 5230 |
(see \sectionref{sec:fallbacks}).% |
| 5231 |
]% |
| 5232 |
{internalfield}% |
| 5233 |
[Fields Set by \bibgls]% |
| 5234 |
{Fields Sometimes Set by \bibgls\ in the \iext{glstex} File}% |
| 5235 |
{tab:internalfields} |
| 5236 |
|
| 5237 |
\printfields |
| 5238 |
[% |
| 5239 |
Don't define any of these as keys and don't use any of them in the \ext{bib} |
| 5240 |
file.% |
| 5241 |
]% |
| 5242 |
{baseinternalfield}% |
| 5243 |
[Internal Fields Set by \styfmt{glossaries} or \styfmt{glossaries-extra} |
| 5244 |
or \bibgls]% |
| 5245 |
{Internal Fields Set by \isty{glossaries} or \isty{glossaries-extra} |
| 5246 |
or \bibgls}% |
| 5247 |
{tab:baseinternalfields} |
| 5248 |
|
| 5249 |
\printfields |
| 5250 |
[% |
| 5251 |
Only available for \atentry{compoundset}. These correspond to the |
| 5252 |
arguments of \ics{multiglossaryentry}.% |
| 5253 |
]% |
| 5254 |
{compoundsetfield}% |
| 5255 |
{Compound Set Fields}% |
| 5256 |
{tab:compoundsetfields} |
| 5257 |
|
| 5258 |
\clearpage |
| 5259 |
|
| 5260 |
\section{String Concatenation} |
| 5261 |
\label{sec:bibstringconcat} |
| 5262 |
|
| 5263 |
The \ext{bib} format allows you to perform string \gls{concatenation}. |
| 5264 |
That is, join fragments together to form a single value. |
| 5265 |
The \gls{concatenation} operator in \ext{bib} files is |
| 5266 |
\idx{stringconcat}. |
| 5267 |
For example, if the following string is defined: |
| 5268 |
\begin{codeenv} |
| 5269 |
\atentry{string}\marg{markuplang=\marg{markup language}} |
| 5270 |
\end{codeenv} |
| 5271 |
Then values can be obtained by concatenating this string with other |
| 5272 |
strings. For example: |
| 5273 |
\begin{codeenv} |
| 5274 |
\atentry{abbreviation}\marg{xml, |
| 5275 |
\field{short}=\marg{XML}, |
| 5276 |
\field{long}=\marg{extensible } \idx{stringconcat} markuplang |
| 5277 |
} |
| 5278 |
\atentry{abbreviation}\marg{html, |
| 5279 |
\field{short}=\marg{HTML}, |
| 5280 |
\field{long}=\marg{hypertext } \idx{stringconcat} markuplang |
| 5281 |
} |
| 5282 |
\end{codeenv} |
| 5283 |
This is equivalent to: |
| 5284 |
\begin{codeenv} |
| 5285 |
\atentry{abbreviation}\marg{xml, |
| 5286 |
\field{short}=\marg{XML}, |
| 5287 |
\field{long}=\marg{extensible markup language} |
| 5288 |
} |
| 5289 |
\atentry{abbreviation}\marg{html, |
| 5290 |
\field{short}=\marg{HTML}, |
| 5291 |
\field{long}=\marg{hypertext markup language} |
| 5292 |
} |
| 5293 |
\end{codeenv} |
| 5294 |
|
| 5295 |
Note that some resource options allow string \gls{concatenation} in |
| 5296 |
their syntax. That uses a different operator. See |
| 5297 |
\sectionref{sec:optstringconcat} for further details. |
| 5298 |
|
| 5299 |
\section{Special Entry Types} |
| 5300 |
\label{sec:specialentrytypes} |
| 5301 |
|
| 5302 |
The bib entry types described in this section don't correspond to |
| 5303 |
any glossary entry type. They aren't affected by most of the |
| 5304 |
resource options, including sorting or filtering. |
| 5305 |
|
| 5306 |
\subsection{Comments} |
| 5307 |
\label{sec:bibcomments} |
| 5308 |
|
| 5309 |
The original \ext{bib} file format as defined by \BibTeX\ doesn't |
| 5310 |
have a designated comment character, but instead treats anything |
| 5311 |
outside of \code{@\meta{entry}\margm{data}} as unwanted material |
| 5312 |
that's ignored. This can catch out users who try to do something |
| 5313 |
like: |
| 5314 |
\begin{verbatim} |
| 5315 |
%@misc{sample, title={Sample} } |
| 5316 |
\end{verbatim} |
| 5317 |
In this case, the percent character is simply discarded and the |
| 5318 |
line is treated as: |
| 5319 |
\begin{verbatim} |
| 5320 |
@misc{sample, title={Sample} } |
| 5321 |
\end{verbatim} |
| 5322 |
Some applications that parse \ext{bib} files are less tolerant of |
| 5323 |
unwanted material. In the case of \bibgls, the percent character is |
| 5324 |
treated as a comment character and other unwanted material |
| 5325 |
should be omitted. Avoid using comments within field values. |
| 5326 |
Comments are best placed outside of entry definitions. |
| 5327 |
|
| 5328 |
The most common type of comment is the \gls{encoding} comment, described |
| 5329 |
above. \BibTeX's \entrydef{comment} is also supported by \bibgls\ |
| 5330 |
for general comments, but not for the \gls{encoding}. |
| 5331 |
|
| 5332 |
\subsection{Preamble} |
| 5333 |
\label{sec:preamble} |
| 5334 |
|
| 5335 |
As with \BibTeX, \atentry{preamble} is also supported by \bibgls. |
| 5336 |
This will be written to the \ext{glstex} file unless |
| 5337 |
prevented with \csopt[false]{write-preamble}. |
| 5338 |
The \texparserlib\ used by \bibgls\ will parse the contents of |
| 5339 |
\atentry{preamble} unless \csopt[false]{interpret-preamble} |
| 5340 |
(or the interpreter is switched off with \longarg{no-interpret}). |
| 5341 |
|
| 5342 |
\subsection{Compound Entry Sets} |
| 5343 |
\label{sec:compoundsetentry} |
| 5344 |
|
| 5345 |
A \gls{compoundentry} isn't a normal glossary entry |
| 5346 |
but corresponds to a multi-entry (compound or combined) set provided |
| 5347 |
by \sty{glossaries-extra} v1.48+, which is defined by the command |
| 5348 |
\ics{multiglossaryentry} (or \ics{providemultiglossaryentry}). |
| 5349 |
These are referred to as multi-entries in \sty{glossaries-extra} but |
| 5350 |
are referred to as \glspl{compoundentry} here to avoid confusion |
| 5351 |
with the \glspl{multientrytype}. They are referenced with commands |
| 5352 |
like \ics{mgls} not with the \cs{gls} set of commands. |
| 5353 |
As such, they don't belong in any glossary list, although their |
| 5354 |
component elements do. |
| 5355 |
|
| 5356 |
\begin{important} |
| 5357 |
Most resource options don't apply to this \gls{entrytype}. Options |
| 5358 |
specific to \glspl{compoundentry} are listed in |
| 5359 |
\sectionref{sec:compoundentries}. |
| 5360 |
\end{important} |
| 5361 |
|
| 5362 |
Essentially, a label is defined that refers to a set of labels |
| 5363 |
corresponding to entries that \emph{have already been defined}. One |
| 5364 |
element in the set is considered the \gls{compmainlabel}. Entry |
| 5365 |
labels may appear in multiple sets. |
| 5366 |
|
| 5367 |
\begin{important} |
| 5368 |
Although the \sty{glossaries-extra} package allows the same label to |
| 5369 |
be used for a regular entry and a compound entry, the \ext{bib} |
| 5370 |
format doesn't allow this. |
| 5371 |
\end{important} |
| 5372 |
|
| 5373 |
A \gls{compoundentry} provides a convenient way to apply commands |
| 5374 |
like \ics{gls} to multiple entries in one command (such as \ics{mgls}). |
| 5375 |
\Gls{compoundentry} labels may only be used in the \cs{mgls}-like |
| 5376 |
commands or in a \gls{cross-referencefield}. |
| 5377 |
|
| 5378 |
For example, consider the following document: |
| 5379 |
\begin{codeenv} |
| 5380 |
\cmd{documentclass}\marg{article} |
| 5381 |
\cmd{usepackage}\marg{hyperref} |
| 5382 |
\cmd{usepackage}[\styopt{record},\styopt[tree]{style}]\marg{glossaries-extra} |
| 5383 |
\cs{setabbreviationstyle}\marg{long-only-short-only} |
| 5384 |
\cs{renewcommand}*\marg{\cs{glsxtronlyname}}\marg{\comment{} |
| 5385 |
\cs{protect}\cs{glslongonlyfont}\marg{\cs{the}\cs{glslongtok}}\comment{} |
| 5386 |
} |
| 5387 |
\cs{newabbreviation}\marg{clostridium}\marg{C.}\marg{Clostridium} |
| 5388 |
\gls{newglossaryentry}\marg{botulinum}\marg{name=botulinum, |
| 5389 |
description=\marg{},parent=clostridium} |
| 5390 |
\gls{newglossaryentry}\marg{perfringens}\marg{name=perfringens, |
| 5391 |
description=\marg{},parent=clostridium} |
| 5392 |
\cmd{begin}\marg{document} |
| 5393 |
\cs{gls}\marg{clostridum} \cs{gls}\marg{botulinum}, |
| 5394 |
\cs{gls}\marg{clostridum} \cs{gls}\marg{perfringens}, |
| 5395 |
\cs{gls}\marg{clostridum} \cs{gls}\marg{botulinum}. |
| 5396 |
\cs{printunsrtglossary} |
| 5397 |
\cmd{end}\marg{document} |
| 5398 |
\end{codeenv} |
| 5399 |
This produces: |
| 5400 |
\begin{quote} |
| 5401 |
Clostridium botulinum, |
| 5402 |
C. perfringens, |
| 5403 |
C. botulinum. |
| 5404 |
\end{quote} |
| 5405 |
followed by the glossary. This is very cumbersome. Defining a |
| 5406 |
\gls{compoundentry} label simply provides a shortcut: |
| 5407 |
\begin{codeenv*} |
| 5408 |
\ics{multiglossaryentry}\marg{cbot}\marg{clostridium,botulinum} |
| 5409 |
\ics{multiglossaryentry}\marg{cperf}\marg{clostridium,perfringens} |
| 5410 |
\end{codeenv*} |
| 5411 |
(This has to be done after the entries have been defined.) Now the |
| 5412 |
entries can be more compactly referenced: |
| 5413 |
\begin{codeenv*} |
| 5414 |
\ics{mgls}\marg{cbot}, |
| 5415 |
\ics{mgls}\marg{cperf}, |
| 5416 |
\ics{mgls}\marg{cbot}. |
| 5417 |
\end{codeenv*} |
| 5418 |
Each \gls{compoundentry} set must contain at least two elements. The |
| 5419 |
\gls{compmainlabel} is the label of the element that is considered |
| 5420 |
the main entry of the set. If the \gls{compmainlabel} isn't |
| 5421 |
identified in \cs{multiglossaryentry} then it's assumed to be the |
| 5422 |
last element in the set. |
| 5423 |
|
| 5424 |
In the above example, \code{botulinum} is the \gls{compmainlabel} of |
| 5425 |
the \code{cbot} set, and \code{perfringens} is the |
| 5426 |
\gls{compmainlabel} of the \code{cperf} set. In both sets, |
| 5427 |
\code{clostridium} is the \qt{\gls{compotherlabel}}. If there are |
| 5428 |
more than two elements in the set then \qt{others} refers to all the |
| 5429 |
elements except for the \gls{compmainlabel}. An entry can be a |
| 5430 |
\gls{compmainlabel} of one set and an \gls{compotherlabel} of |
| 5431 |
another set. |
| 5432 |
|
| 5433 |
The options, which can be applied to all sets with |
| 5434 |
\ics{multiglossaryentrysetup} or to a specific set using the |
| 5435 |
first optional argument of \ics{multiglossaryentry}, determine |
| 5436 |
if each element of the list has a separate hyperlink to their |
| 5437 |
own target, or if only the main element should have a hyperlink, or |
| 5438 |
if the entire content of \ics{mgls} should be a single hyperlink to |
| 5439 |
the main entry's target. |
| 5440 |
|
| 5441 |
With \bibgls, the component entries that form the set should be in \ext{bib} files as usual. |
| 5442 |
The \gls{compoundentry} set may either be defined in the document \ext{tex} |
| 5443 |
file using \ics{multiglossaryentry} (or \ics{providemultiglossaryentry}) |
| 5444 |
or they can be defined in the \ext{bib} file using |
| 5445 |
\atentry{compoundset}. Remember that the set can only be defined |
| 5446 |
after the entries that make up the elements of the set have been |
| 5447 |
defined. If any \ext{bib} files in a \gls{resourceset} contain |
| 5448 |
\atentry{compoundset}, the definitions will be added at the end of |
| 5449 |
the \ext{glstex} file (using \gls{bibglsdefcompoundset}). |
| 5450 |
|
| 5451 |
If you have multiple \glspl{resourceset} that reuse the same |
| 5452 |
\ext{bib} file containing \atentry{compoundset} then either redefine |
| 5453 |
\gls{bibglsdefcompoundset} to use \ics{providemultiglossaryentry} or |
| 5454 |
prevent duplicate definitions with \csopt[false]{compound-write-def}. |
| 5455 |
|
| 5456 |
The elements of the set will still need to be indexed as usual to |
| 5457 |
ensure that they have \glspl{record} to enable selection. |
| 5458 |
If any element hasn't been selected, the \gls{compoundentry} define won't |
| 5459 |
be written to the \ext{glstex} file, regardless of the |
| 5460 |
\csopt{compound-write-def} setting. |
| 5461 |
|
| 5462 |
The above example can be converted to \bibgls\ as follows |
| 5463 |
(\glspl{compoundentry} defined in the document \ext{tex} file): |
| 5464 |
\begin{codeenv} |
| 5465 |
\cmd{documentclass}\marg{article} |
| 5466 |
\cmd{usepackage}\marg{hyperref} |
| 5467 |
\cmd{usepackage}[\styopt{record},\styopt[tree]{style}]\marg{glossaries-extra} |
| 5468 |
\cs{setabbreviationstyle}\marg{long-only-short-only} |
| 5469 |
\cs{renewcommand}*\marg{\cs{glsxtronlyname}}\marg{\comment{} |
| 5470 |
\cs{protect}\cs{glslongonlyfont}\marg{\cs{the}\cs{glslongtok}}\comment{} |
| 5471 |
} |
| 5472 |
\gls{GlsXtrLoadResources}\oarg{\csopt[bacteria]{src}} |
| 5473 |
\cs{multiglossaryentry}\marg{cbot}\marg{clostridium,botulinum} |
| 5474 |
\cs{multiglossaryentry}\marg{cperf}\marg{clostridium,perfringens} |
| 5475 |
\cmd{begin}\marg{document} |
| 5476 |
\cs{mgls}\marg{cbot}, \cs{mgls}\marg{cperf}, \cs{mgls}\marg{cbot}. |
| 5477 |
\cs{printunsrtglossary} |
| 5478 |
\cmd{end}\marg{document} |
| 5479 |
\end{codeenv} |
| 5480 |
Note that \cs{multiglossaryentry} must come after \gls{GlsXtrLoadResources}. |
| 5481 |
|
| 5482 |
The \file{bacteria.bib} contains the definitions in the usual way: |
| 5483 |
\begin{codeenv} |
| 5484 |
\atentry{abbreviation}\marg{clostridium, |
| 5485 |
\field{short}=\marg{C.}, |
| 5486 |
\field{long}=\marg{Clostridium} |
| 5487 |
} |
| 5488 |
\atentry{index}\marg{botulinum, |
| 5489 |
\field{parent}=\marg{clostridium} |
| 5490 |
} |
| 5491 |
\atentry{index}\marg{perfringens, |
| 5492 |
\field{parent}=\marg{clostridium} |
| 5493 |
} |
| 5494 |
\end{codeenv} |
| 5495 |
|
| 5496 |
Alternatively, the \glspl{compoundentry} can be defined in the |
| 5497 |
\ext{bib} file instead: |
| 5498 |
\begin{codeenv} |
| 5499 |
\atentry{compoundset}\marg{cbot, |
| 5500 |
\field{elements}=\marg{clostridium,botulinum} |
| 5501 |
} |
| 5502 |
\atentry{compoundset}\marg{cperf, |
| 5503 |
\field{elements}=\marg{clostridium,perfringens} |
| 5504 |
} |
| 5505 |
\end{codeenv} |
| 5506 |
The \cs{multiglossaryentry} commands should now be removed from the |
| 5507 |
\ext{tex} file. |
| 5508 |
|
| 5509 |
There's a difference between these two methods on the first \LaTeX\ |
| 5510 |
build. In the first example, \code{cbot} is known, so |
| 5511 |
\code{\cs{mgls}\marg{cbot}} can perform |
| 5512 |
\code{\cs{gls}\marg{clostridum} \cs{gls}\marg{botulinum}}. These |
| 5513 |
commands aren't yet defined so they are both replaced by \qt{??} |
| 5514 |
(resulting in \qt{?? ??}). As usual, the \gls{locationlist} is |
| 5515 |
unreliable until entries are defined and the unknown markers \qt{??} |
| 5516 |
can be replaced with the correct content. If the document is in a |
| 5517 |
file called \filefmt{myDoc.tex} then the document build: |
| 5518 |
\begin{codeenv} |
| 5519 |
pdflatex myDoc |
| 5520 |
bib2gls myDoc |
| 5521 |
pdflatex myDoc |
| 5522 |
\end{codeenv} |
| 5523 |
will have \glspl{location} in the resulting PDF file, but they may |
| 5524 |
be incorrect if the associated temporary files were initially |
| 5525 |
missing. |
| 5526 |
|
| 5527 |
In the second example, \code{cbot} is unknown, so |
| 5528 |
\code{\cs{mgls}\marg{cbot}} is simply displayed as \qt{??}. |
| 5529 |
In this case, the \ext{aux} file contains information that |
| 5530 |
\code{cbot} has been referenced, but there are no associated |
| 5531 |
\glspl{record}. The entries that belong to the \code{cbot} set will |
| 5532 |
be selected as they are considered dependent on the |
| 5533 |
\gls{compoundentry}. In this case, if you are starting from scratch |
| 5534 |
(no associated temporary files), you will need: |
| 5535 |
\begin{codeenv} |
| 5536 |
pdflatex myDoc |
| 5537 |
bib2gls myDoc |
| 5538 |
pdflatex myDoc |
| 5539 |
bib2gls myDoc |
| 5540 |
pdflatex myDoc |
| 5541 |
\end{codeenv} |
| 5542 |
At this point, the \glspl{locationlist} will appear. |
| 5543 |
After that, you can reduce the document build to: |
| 5544 |
\begin{codeenv} |
| 5545 |
pdflatex myDoc |
| 5546 |
bib2gls myDoc |
| 5547 |
pdflatex myDoc |
| 5548 |
\end{codeenv} |
| 5549 |
(Until you later add new entries.) |
| 5550 |
|
| 5551 |
If you don't want \glspl{location} for the |
| 5552 |
\glslink{compotherlabel}{other elements} then set the |
| 5553 |
\idx{encap} to \encap{glsignore}: |
| 5554 |
\begin{codeenv*} |
| 5555 |
\ics{multiglossaryentrysetup}\marg{encapothers=\encap{glsignore}} |
| 5556 |
\end{codeenv*} |
| 5557 |
|
| 5558 |
\entrysection{compoundset} |
| 5559 |
The following fields are available: |
| 5560 |
\begin{description} |
| 5561 |
\item[\field{elements}] The comma-separated list of element labels. |
| 5562 |
This corresponds to the final argument of \cs{multiglossaryentry}. |
| 5563 |
(Required.) |
| 5564 |
\item[\field{main}] The \gls{compmainlabel}. This field is optional. |
| 5565 |
If omitted, the main label is assumed to be the last element. |
| 5566 |
\item[\field{options}] A comma-separated list of options. This |
| 5567 |
corresponds to the first optional argument of |
| 5568 |
\cs{multiglossaryentry}. This field may be omitted. |
| 5569 |
\end{description} |
| 5570 |
These fields can only be used in this \gls{entrytype}. |
| 5571 |
|
| 5572 |
\section{Glossary Entry Types} |
| 5573 |
\label{sec:glossaryentrytypes} |
| 5574 |
|
| 5575 |
Each of the bib entry types listed below corresponds to one or more glossary |
| 5576 |
entries, which may be referenced in the document with commands such |
| 5577 |
as \cs{gls}. |
| 5578 |
|
| 5579 |
\subsection{Standard Entry Types} |
| 5580 |
\label{sec:standardentry} |
| 5581 |
|
| 5582 |
\entrysection{string} |
| 5583 |
|
| 5584 |
The standard \atentry{string} is available and can be used to define |
| 5585 |
variables that may be used in field values. Don't include braces or |
| 5586 |
double-quote delimiters when referencing a variable. You can use |
| 5587 |
\idx{stringconcat} to concatenate strings. |
| 5588 |
For example: |
| 5589 |
\begin{codeenv} |
| 5590 |
\atentry{string}\marg{ssi=\marg{server-side includes}} |
| 5591 |
\atentry{string}\marg{html=\marg{hypertext markup language}} |
| 5592 |
\strut |
| 5593 |
\atentry{abbreviation}\marg{shtml, |
| 5594 |
\field{short}=\qtdelim{shtml}, |
| 5595 |
\field{long}=ssi \idx{stringconcat} \qtdelim{ enabled } \idx{stringconcat} html, |
| 5596 |
\field{see}=\marg{ssi,html} |
| 5597 |
} |
| 5598 |
\strut |
| 5599 |
\atentry{abbreviation}\marg{html, |
| 5600 |
\field{short}=\qtdelim{html}, |
| 5601 |
\field{long}=html |
| 5602 |
} |
| 5603 |
\strut |
| 5604 |
\atentry{abbreviation}\marg{ssi, |
| 5605 |
\field{short}=\qtdelim{ssi}, |
| 5606 |
\field{long}=ssi |
| 5607 |
} |
| 5608 |
\end{codeenv} |
| 5609 |
Note the difference between \code{=\qtdelim{ssi}} (a field value delimited by |
| 5610 |
double-quotes), the undelimited \code{=ssi} (a reference to the |
| 5611 |
variable), the grouped \code{=\marg{ssi,html}} (a field value |
| 5612 |
delimited by braces) and \code{ssi} the entry label. |
| 5613 |
|
| 5614 |
\entrysection{preamble} |
| 5615 |
|
| 5616 |
The standard \atentry{preamble} is available and can be used to |
| 5617 |
provide command definitions used within field values. |
| 5618 |
For example: |
| 5619 |
\begin{codeenv} |
| 5620 |
\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{mtx}}[1]\marg{\cs{boldsymbol}\marg{\idx{param}1}}}} |
| 5621 |
\strut |
| 5622 |
\atentry{entry}\marg{matrix, |
| 5623 |
\field{name}=\marg{matrix}, |
| 5624 |
\field{plural}=\marg{matrices}, |
| 5625 |
\field{description}=\marg{rectangular array of values, denoted \idx{mshiftchar}\cmd{mtx}\marg{M}\idx{mshiftchar}} |
| 5626 |
} |
| 5627 |
\end{codeenv} |
| 5628 |
Alternatively you can use \ics{glsxtrprovidecommand} which behaves |
| 5629 |
the same as \ics{providecommand} within the document but behaves |
| 5630 |
like \ics{renewcommand} within \bibgls, which allows you to change |
| 5631 |
\bibgls's internal definition of a command without affecting the |
| 5632 |
definition within the document (if it's already been defined before |
| 5633 |
the resource file is input). In general, it's best to just use |
| 5634 |
\cs{providecommand}. |
| 5635 |
|
| 5636 |
The \texparserlib\ used by \bibgls\ will parse the contents of |
| 5637 |
\atentry{preamble} before trying to interpret the field value used |
| 5638 |
as a \hyperref[sec:fallbacks]{fallback} when \field{sort} is omitted (unless |
| 5639 |
\csopt[false]{interpret-preamble} is set in the resource options). |
| 5640 |
For example: |
| 5641 |
\begin{codeenv} |
| 5642 |
\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{set}}[1]\marg{\cs{mathcal}\marg{\idx{param}1}} |
| 5643 |
\cs{providecommand}\marg{\cmd{card}}[1]\marg{|\cmd{set}\marg{\idx{param}1}|}}} |
| 5644 |
\strut |
| 5645 |
\atentry{entry}\marg{S, |
| 5646 |
\field{name}=\marg{\marg{}\idx{mshiftchar}\cmd{set}\marg{S}\idx{mshiftchar}}, |
| 5647 |
\field{text}=\marg{\cmd{set}\marg{S}}, |
| 5648 |
\field{description}=\marg{a set} |
| 5649 |
} |
| 5650 |
\atentry{entry}\marg{card, |
| 5651 |
\field{name}=\marg{\marg{}\idx{mshiftchar}\cmd{card}\marg{S}\idx{mshiftchar}}, |
| 5652 |
\field{text}=\marg{\cmd{card}\marg{S}}, |
| 5653 |
\field{description}=\marg{the cardinality of \cs{gls}\marg{S}} |
| 5654 |
} |
| 5655 |
\end{codeenv} |
| 5656 |
Neither entry has the \field{sort} field, so \bibgls\ has to fall |
| 5657 |
back on the \field{name} field and, since this contains the special |
| 5658 |
characters \idx{escchar} (backslash), \idx{mshiftchar} (maths |
| 5659 |
shift), \idx{bgroupchar} (begin group) and |
| 5660 |
\idx{egroupchar} (end group), the \texparserlib\ is used to interpret it. |
| 5661 |
The definitions provided by \atentry{preamble} allow \bibgls\ to |
| 5662 |
deduce that the \field{sort} value of the \code{S} entry is just |
| 5663 |
\code{S} and the \field{sort} value of the \code{card} entry is |
| 5664 |
\verb"|S|" (see \sectionref{sec:texparserlib}). |
| 5665 |
|
| 5666 |
What happens if you also need to use these commands in the document? |
| 5667 |
The definitions provided in \atentry{preamble} won't be available |
| 5668 |
until the \iext{glstex} file has been created, which means the |
| 5669 |
commands won't be defined on the first \LaTeX\ run. |
| 5670 |
|
| 5671 |
There are several approaches: |
| 5672 |
\begin{enumerate} |
| 5673 |
\item Just define the commands in the document. This means the |
| 5674 |
commands are available, but \bibgls\ won't be able to correctly |
| 5675 |
interpret the \field{name} fields. |
| 5676 |
|
| 5677 |
\item Define the commands in both the document and in |
| 5678 |
\atentry{preamble}. For example: |
| 5679 |
\begin{codeenv} |
| 5680 |
\cs{newcommand}\marg{\cmd{set}}[1]\marg{\cs{mathcal}\marg{\idx{param}1}} |
| 5681 |
\cs{newcommand}\marg{\cmd{card}}[1]\marg{|\cmd{set}\marg{\idx{param}1}|} |
| 5682 |
\gls{GlsXtrLoadResources}\oarg{\csopt[my-data]{src}} |
| 5683 |
\end{codeenv} |
| 5684 |
Alternatively: |
| 5685 |
\begin{codeenv} |
| 5686 |
\gls{GlsXtrLoadResources}\oarg{\csopt[my-data]{src}} |
| 5687 |
\cs{providecommand}\marg{\cmd{set}}[1]\marg{\cs{mathcal}\marg{\idx{param}1}} |
| 5688 |
\cs{providecommand}\marg{\cmd{card}}[1]\marg{|\cmd{set}\marg{\idx{param}1}|} |
| 5689 |
\end{codeenv} |
| 5690 |
If the provided definitions match those given in the \ext{bib} file, |
| 5691 |
there's no difference. If they don't match then in the first example |
| 5692 |
the document definitions will take precedence (but the interpreter |
| 5693 |
will use the \atentry{preamble} definitions) and in the second |
| 5694 |
example the \atentry{preamble} definitions will take precedence. |
| 5695 |
For example, the document may define \csfmt{card} as: |
| 5696 |
\begin{codeenv} |
| 5697 |
\cs{newcommand}\marg{\cmd{card}}[1]\marg{\ics{vert}\cmd{set}\marg{\idx{param}1}\cs{vert}} |
| 5698 |
\end{codeenv} |
| 5699 |
|
| 5700 |
\item Make use of \gls{glsxtrfmt} provided by \styfmt{glossaries-extra} which |
| 5701 |
allows you to store the name of the formatting command in a field. |
| 5702 |
The default is the \field{user1} field, but this can be changed to |
| 5703 |
another field by redefining \ics{GlsXtrFmtField}. |
| 5704 |
|
| 5705 |
The \ext{bib} file can now look like this: |
| 5706 |
\begin{codeenv} |
| 5707 |
\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{set}}[1]\marg{\cs{mathcal}\marg{\idx{param}1}} |
| 5708 |
\cs{providecommand}\marg{\cmd{card}}[1]\marg{|\cmd{set}\marg{\idx{param}1}|}}} |
| 5709 |
\strut |
| 5710 |
\atentry{symbol}\marg{S, |
| 5711 |
\field{name}=\marg{\marg{}\idx{mshiftchar}\cmd{set}\marg{S}\idx{mshiftchar}}, |
| 5712 |
\field{text}=\marg{\cmd{set}\marg{S}}, |
| 5713 |
\field{user1}=\marg{set}, |
| 5714 |
\field{description}=\marg{a set} |
| 5715 |
} |
| 5716 |
\atentry{symbol}\marg{cardS, |
| 5717 |
\field{name}=\marg{\marg{}\idx{mshiftchar}\cmd{card}\marg{S}\idx{mshiftchar}}, |
| 5718 |
\field{text}=\marg{\cmd{card}\marg{S}}, |
| 5719 |
\field{user1}=\marg{card}, |
| 5720 |
\field{description}=\marg{the cardinality of \cs{gls}\marg{S}} |
| 5721 |
} |
| 5722 |
\end{codeenv} |
| 5723 |
Within the document, you can format \meta{text} using the formatting |
| 5724 |
command provided in the \field{user1} field with: |
| 5725 |
\nosecformatdef{glsxtrfmt} |
| 5726 |
(which internally uses \ics{glslink}) or |
| 5727 |
\nosecformatdef{glsxtrentryfmt} |
| 5728 |
which just applies the appropriate formatting command to |
| 5729 |
\meta{text}. Version 1.23+ of \sty{glossaries-extra} also provides a |
| 5730 |
starred form of the linking command: |
| 5731 |
\nosecformatdef{glsxtrfmt*} |
| 5732 |
which inserts additional material inside the link text but outside |
| 5733 |
the formatting command. |
| 5734 |
|
| 5735 |
If the entry given by \meta{label} hasn't been defined, |
| 5736 |
then \gls!{glsxtrfmt} just does \meta{text} (followed by \meta{insert} for |
| 5737 |
the starred version) and a warning is issued. (There's no warning |
| 5738 |
if the entry is defined but the field hasn't been set.) |
| 5739 |
The \meta{options} are as for \ics{glslink} but \ics{glslink} will |
| 5740 |
actually be using: |
| 5741 |
\begin{codeenv} |
| 5742 |
\ics{glslink}\oarg{\meta{def-options},\meta{options}}\margm{label}\marg{\cmd{}\meta{csname}\margm{text}\meta{insert}} |
| 5743 |
\end{codeenv} |
| 5744 |
where the default options \meta{def-options} are given by |
| 5745 |
\ics{GlsXtrFmtDefaultOptions}. The default definition of this is |
| 5746 |
just \code{noindex} which suppresses the automatic indexing or |
| 5747 |
recording action. (See the \sty{glossaries-extra} |
| 5748 |
manual~\cite{glossaries-extra} for further details.) The |
| 5749 |
\meta{insert} part is omitted for the unstarred form. |
| 5750 |
|
| 5751 |
This means that the document doesn't need to actually provide |
| 5752 |
\verb|\set| or \verb|\card| but can instead use, for example, |
| 5753 |
\begin{codeenv} |
| 5754 |
\gls{glsxtrfmt}\marg{S}\marg{A} |
| 5755 |
\gls{glsxtrentryfmt}\marg{cardS}\marg{B} |
| 5756 |
\end{codeenv} |
| 5757 |
instead of: |
| 5758 |
\begin{verbatim} |
| 5759 |
\set{A} |
| 5760 |
\card{B} |
| 5761 |
\end{verbatim} |
| 5762 |
The first \LaTeX\ run will simply ignore the formatting and produce |
| 5763 |
a warning. |
| 5764 |
|
| 5765 |
Since this is a bit cumbersome to write, you can provide shortcut |
| 5766 |
commands. For example: |
| 5767 |
\begin{codeenv} |
| 5768 |
\gls{GlsXtrLoadResources}\oarg{\csopt[my-data]{src}} |
| 5769 |
\cs{newcommand}\marg{\cmd{gset}}[2][]\marg{\gls{glsxtrfmt}\oarg{\idx{param}1}\marg{S}\marg{\idx{param}2}} |
| 5770 |
\cs{newcommand}\marg{\cmd{gcard}}[2][]\marg{\gls{glsxtrfmt}\oarg{\idx{param}1}\marg{cardS}\marg{\idx{param}2}} |
| 5771 |
\end{codeenv} |
| 5772 |
Whilst this doesn't seem a great deal different from simply |
| 5773 |
providing the definitions of \csfmt{set} and \csfmt{card} in the |
| 5774 |
document, this means you don't have to worry about remembering |
| 5775 |
the names of the actual commands provided in the \ext{bib} file |
| 5776 |
(just the entry labels) and the use of \gls{glsxtrfmt} will |
| 5777 |
automatically produce a hyperlink to the glossary entry if the |
| 5778 |
\isty{hyperref} package has been loaded. |
| 5779 |
\end{enumerate} |
| 5780 |
|
| 5781 |
Here's an alternative \ext{bib} that defines entries with a term, a |
| 5782 |
description and a symbol: |
| 5783 |
\begin{codeenv} |
| 5784 |
\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{setfmt}}[1]\marg{\cs{mathcal}\marg{\idx{param}1}} |
| 5785 |
\cs{providecommand}\marg{\cmd{cardfmt}}[1]\marg{|\cmd{setfmt}\marg{\idx{param}1}|}}} |
| 5786 |
\strut |
| 5787 |
\atentry{entry}\marg{set, |
| 5788 |
\field{name}=\marg{set}, |
| 5789 |
\field{symbol}=\marg{\cmd{setfmt}\marg{S}}, |
| 5790 |
\field{user1}=\marg{setfmt}, |
| 5791 |
\field{description}=\marg{collection of values} |
| 5792 |
} |
| 5793 |
\atentry{entry}\marg{cardinality, |
| 5794 |
\field{name}=\marg{cardinality}, |
| 5795 |
\field{symbol}=\marg{\cmd{cardfmt}\marg{S}}, |
| 5796 |
\field{user1}=\marg{cardfmt}, |
| 5797 |
\field{description}=\marg{the number of elements in the \cs{gls}\marg{set} \idx{mshiftchar}\cs{glssymbol}\marg{set}\idx{mshiftchar}} |
| 5798 |
} |
| 5799 |
\end{codeenv} |
| 5800 |
I've changed the entry labels and the names of the formatting commands. |
| 5801 |
The definitions in the document need to reflect the change in label |
| 5802 |
but not the change in the formatting commands: |
| 5803 |
\begin{codeenv} |
| 5804 |
\cs{newcommand}\marg{\cmd{gset}}[2][]\marg{\gls{glsxtrfmt}\oarg{\idx{param}1}\marg{set}\marg{\idx{param}2}} |
| 5805 |
\cs{newcommand}\marg{\cmd{gcard}}[2][]\marg{\gls{glsxtrfmt}\oarg{\idx{param}1}\marg{cardinality}\marg{\idx{param}2}} |
| 5806 |
\end{codeenv} |
| 5807 |
|
| 5808 |
Here's another approach that allows for a more complicated argument |
| 5809 |
for the cardinality. (For example, if the argument is an expression |
| 5810 |
involving set unions or intersections.) |
| 5811 |
The \ext{bib} file is now: |
| 5812 |
\begin{codeenv} |
| 5813 |
\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{setfmt}}[1]\marg{\cs{mathcal}\marg{\idx{param}1}} |
| 5814 |
\cs{providecommand}\marg{\cmd{cardfmt}}[1]\marg{|\idx{param}1|}}} |
| 5815 |
\strut |
| 5816 |
\atentry{entry}\marg{set, |
| 5817 |
\field{name}=\marg{set}, |
| 5818 |
\field{symbol}=\marg{\cmd{setfmt}\marg{S}}, |
| 5819 |
\field{user1}=\marg{setfmt}, |
| 5820 |
\field{description}=\marg{collection of values} |
| 5821 |
} |
| 5822 |
\atentry{entry}\marg{cardinality, |
| 5823 |
\field{name}=\marg{cardinality}, |
| 5824 |
\field{symbol}=\marg{\cmd{cardfmt}\marg{\cmd{setfmt}\marg{S}}}, |
| 5825 |
\field{user1}=\marg{cardfmt}, |
| 5826 |
\field{description}=\marg{the number of elements in the \cs{gls}\marg{set} \idx{mshiftchar}\cs{glssymbol}\marg{set}\idx{mshiftchar}} |
| 5827 |
} |
| 5828 |
\end{codeenv} |
| 5829 |
This has removed the \csfmt{setfmt} command from the definition of |
| 5830 |
\csfmt{cardfmt}. Now the definitions in the document are: |
| 5831 |
\begin{codeenv} |
| 5832 |
\cs{newcommand}\marg{\cmd{gset}}[1]\marg{\gls{glsxtrentryfmt}\marg{set}\marg{\idx{param}1}} |
| 5833 |
\cs{newcommand}\marg{\cmd{gcard}}[2][]\marg{\gls{glsxtrfmt}\oarg{\idx{param}1}\marg{cardinality}\marg{\idx{param}2}} |
| 5834 |
\end{codeenv} |
| 5835 |
This allows for code such as: |
| 5836 |
\begin{verbatim} |
| 5837 |
\[ \gcard{\gset{A} \cap \gset{B}} \] |
| 5838 |
\end{verbatim} |
| 5839 |
which will link back to the \code{cardinality} entry in the |
| 5840 |
glossary and avoids any hyperlinking with \csfmt{gset}. |
| 5841 |
Alternatively to avoid links with \csfmt{gcard} as well: |
| 5842 |
\begin{codeenv} |
| 5843 |
\cs{newcommand}\marg{\cmd{gset}}[1]\marg{\gls{glsxtrentryfmt}\marg{set}\marg{\idx{param}1}} |
| 5844 |
\cs{newcommand}\marg{\cmd{gcard}}[1]\marg{\gls{glsxtrentryfmt}\marg{cardinality}\marg{\idx{param}1}} |
| 5845 |
\end{codeenv} |
| 5846 |
Now \csfmt{gset} and \csfmt{gcard} are simply formatting commands, |
| 5847 |
but their actual definitions are determined in the \ext{bib} file. |
| 5848 |
|
| 5849 |
\subsection{Single Entry Types} |
| 5850 |
\label{sec:singleentry} |
| 5851 |
|
| 5852 |
The \glspl{entrytype} described in this section create a single glossary |
| 5853 |
definition per entry (from \styfmt{glossaries-extra}'s point of view). |
| 5854 |
For example: |
| 5855 |
\begin{codeenv} |
| 5856 |
\atentry{entry}\marg{matrix, |
| 5857 |
\field{name}=\marg{matrix}, |
| 5858 |
\field{plural}=\marg{matrices}, |
| 5859 |
\field{description}=\marg{rectangular array of values} |
| 5860 |
} |
| 5861 |
\end{codeenv} |
| 5862 |
is analogous to: |
| 5863 |
\begin{codeenv} |
| 5864 |
\gls{newglossaryentry}\marg{matrix}\comment{label} |
| 5865 |
\marg{\comment{fields} |
| 5866 |
\field{name}=\marg{matrix}, |
| 5867 |
\field{plural}=\marg{matrices}, |
| 5868 |
\field{description}=\marg{rectangular array of values} |
| 5869 |
} |
| 5870 |
\end{codeenv} |
| 5871 |
The \csopt{secondary} option allows the creation of a fake glossary |
| 5872 |
with the entry labels in its internal list in a different order. |
| 5873 |
This means that the same data can be displayed in two separate lists |
| 5874 |
without duplicating the resources required by each glossary entry. |
| 5875 |
|
| 5876 |
\Sectionref{sec:dualentry} describes \bibgls\ \glspl{entrytype} |
| 5877 |
that create two separate (but related) \styfmt{glossaries-extra} |
| 5878 |
definitions per \ext{bib} entry. |
| 5879 |
|
| 5880 |
\entrysection{entry} |
| 5881 |
|
| 5882 |
Regular terms are defined by the \atentry{entry} field. This requires the |
| 5883 |
\field{description} field and either \field{name} or \field{parent}. |
| 5884 |
For example: |
| 5885 |
\begin{codeenv} |
| 5886 |
\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{mtx}}[1]\marg{\cs{boldsymbol}\marg{\idx{param}1}}}} |
| 5887 |
\strut |
| 5888 |
\atentry{entry}\marg{matrix, |
| 5889 |
\field{name}=\marg{matrix}, |
| 5890 |
\field{plural}=\marg{matrices}, |
| 5891 |
\field{description}=\marg{rectangular array of values, denoted \cs{gls}\marg{M}}, |
| 5892 |
\field{seealso}=\marg{vector} |
| 5893 |
} |
| 5894 |
\strut |
| 5895 |
\atentry{entry}\marg{M, |
| 5896 |
\field{name}=\marg{\cs{ensuremath}\marg{M}}, |
| 5897 |
\field{description}=\marg{a \cs{gls}\marg{matrix}} |
| 5898 |
} |
| 5899 |
\strut |
| 5900 |
\atentry{entry}\marg{vector, |
| 5901 |
\field{name} = \qtdelim{vector}, |
| 5902 |
\field{description} = \marg{column or row of values, denoted \cs{gls}\marg{v}}, |
| 5903 |
\field{seealso}=\marg{matrix} |
| 5904 |
} |
| 5905 |
\strut |
| 5906 |
\atentry{entry}\marg{v, |
| 5907 |
\field{name}=\marg{\cs{ensuremath}\marg{\cs{vec}\marg{v}}}, |
| 5908 |
\field{description}=\marg{a \cs{gls}\marg{vector}} |
| 5909 |
} |
| 5910 |
\end{codeenv} |
| 5911 |
|
| 5912 |
If the \field{sort} field is missing the default is obtained from |
| 5913 |
the \field{name} field (unless overridden by options like |
| 5914 |
\csopt{entry-sort-fallback}). For \hierarchical\ entries, if the |
| 5915 |
\field{name} field is omitted it will be obtained from the |
| 5916 |
\glsdisp{parententry}{parent's} \field{name}. |
| 5917 |
See \sectionref{sec:fallbacks}. |
| 5918 |
|
| 5919 |
Terms defined using \atentry{entry} will be written to the output |
| 5920 |
(\ext{glstex}) file using the command \gls!{bibglsnewentry}. |
| 5921 |
|
| 5922 |
\entrysection{symbol} |
| 5923 |
|
| 5924 |
The \atentry{symbol} \gls{entrytype} is much like \atentry{entry}, but it's |
| 5925 |
designed specifically for symbols, so in the previous example, the |
| 5926 |
\code{M} and \code{v} terms would be better defined using the |
| 5927 |
\atentry{symbol} \gls{entrytype} instead. For example: |
| 5928 |
\begin{codeenv} |
| 5929 |
\atentry{symbol}\marg{M, |
| 5930 |
\field{name}=\marg{\cs{ensuremath}\marg{M}}, |
| 5931 |
\field{description}=\marg{a \cs{gls}\marg{matrix}} |
| 5932 |
} |
| 5933 |
\end{codeenv} |
| 5934 |
|
| 5935 |
The required fields are \field{name} or \field{parent}. The |
| 5936 |
\field{description} field is required if the \field{name} field is |
| 5937 |
missing. If the \field{sort} field is omitted, the default fallback is |
| 5938 |
given by the entry label (unless overridden by options like |
| 5939 |
\csopt{symbol-sort-fallback}). Note that this is different from |
| 5940 |
\atentry{entry} where the sort defaults to \field{name} if omitted. |
| 5941 |
See \sectionref{sec:fallbacks}. |
| 5942 |
|
| 5943 |
Terms that are defined using \atentry{symbol} will be written to |
| 5944 |
the output file using the command \gls!{bibglsnewsymbol}. |
| 5945 |
|
| 5946 |
\entrysection{number} |
| 5947 |
|
| 5948 |
The \atentry{number} \gls{entrytype} is like \atentry{symbol}, but it's for |
| 5949 |
numbers. The numbers don't have to be explicit digits and may have a |
| 5950 |
symbolic representation. There's no real difference between the |
| 5951 |
behaviour of \atentry{number} and \atentry{symbol} except that terms |
| 5952 |
defined using \atentry{number} will be written to the output file |
| 5953 |
using the command \gls!{bibglsnewnumber}. |
| 5954 |
|
| 5955 |
For example, the file \filefmt{constants.bib} might define |
| 5956 |
mathematical constants like this: |
| 5957 |
\begin{codeenv} |
| 5958 |
\atentry{number}\marg{pi, |
| 5959 |
\field{name}=\marg{\cs{ensuremath}\marg{\ics{pi}}}, |
| 5960 |
\field{description}=\marg{the ratio of the length of the circumference |
| 5961 |
of a circle to its diameter}, |
| 5962 |
\field{user1}=\marg{3.14159} |
| 5963 |
} |
| 5964 |
\strut |
| 5965 |
\atentry{number}\marg{e, |
| 5966 |
\field{name}=\marg{\cs{ensuremath}\marg{e}}, |
| 5967 |
\field{description}=\marg{base of natural logarithms}, |
| 5968 |
\field{user1}=\marg{2.71828} |
| 5969 |
} |
| 5970 |
\end{codeenv} |
| 5971 |
This stores the approximate value in the \field{user1} field. This |
| 5972 |
can be used to sort the entries in numerical order according to the |
| 5973 |
values rather than the symbols: |
| 5974 |
\begin{codeenv} |
| 5975 |
\gls{GlsXtrLoadResources}\oarg{ |
| 5976 |
\csopt[constants]{src},\comment{constants.bib} |
| 5977 |
\csopt[number]{category},\comment{set the category for all selected entries} |
| 5978 |
\csopt[double]{sort},\comment{numerical double-precision sort} |
| 5979 |
\csopt[user1]{sort-field}\comment{sort according to 'user1' field} |
| 5980 |
} |
| 5981 |
\end{codeenv} |
| 5982 |
The \csopt[number]{category} option makes it easy to adjust the |
| 5983 |
glossary format to include the \field{user1} field: |
| 5984 |
\begin{codeenv} |
| 5985 |
\ics{glsdefpostdesc}\marg{number}\marg{\comment{} |
| 5986 |
\cs{ifglshasfield}\marg{useri}\marg{\cs{glscurrententrylabel}}\comment{} |
| 5987 |
\marg{ (approximate value: \cs{glscurrentfieldvalue})}\comment{} |
| 5988 |
\marg{}\comment{} |
| 5989 |
} |
| 5990 |
\end{codeenv} |
| 5991 |
|
| 5992 |
\entrysection{index} |
| 5993 |
|
| 5994 |
The \atentry{index} \gls{entrytype} is designed for entries that don't |
| 5995 |
have a description. Only the label is required. If \field{name} is |
| 5996 |
omitted, it's assumed to be the same as the label, even if |
| 5997 |
\field{parent} is present. (Note this is different to the fallback |
| 5998 |
behaviour of \atentry{entry}, which fetches the name from the |
| 5999 |
\gls{parententry}.) If the name contains any characters that can't be used in |
| 6000 |
the label, you must use the \field{name} field. If the \field{sort} |
| 6001 |
field is missing the default fallback is obtained from the \field{name}. |
| 6002 |
Note that the \atentry{index} \gls{entrytype} is \emph{not} governed by |
| 6003 |
\csopt{entry-sort-fallback} (but it is governed by |
| 6004 |
\csopt{custom-sort-fallbacks}). This allows \atentry{index} and |
| 6005 |
\atentry{entry} to have different fallbacks if the \field{sort} |
| 6006 |
field is missing. |
| 6007 |
See \sectionref{sec:fallbacks}. |
| 6008 |
|
| 6009 |
Example: |
| 6010 |
\begin{codeenv} |
| 6011 |
\atentry{index}\marg{duck} |
| 6012 |
\atentry{index}\marg{goose,\field{plural}=\marg{geese}} |
| 6013 |
\atentry{index}\marg{sealion,\field{name}=\marg{sea lion}} |
| 6014 |
\atentry{index}\marg{facade,\field{name}=\marg{fa\ics{c}\marg{c}ade}} |
| 6015 |
\end{codeenv} |
| 6016 |
|
| 6017 |
Terms that are defined using \atentry{index} will be written to the output |
| 6018 |
file using the command \gls!{bibglsnewindex}. |
| 6019 |
|
| 6020 |
\entrysection{indexplural} |
| 6021 |
|
| 6022 |
The \atentry{indexplural} \gls{entrytype} is similar to the |
| 6023 |
\atentry{index} \gls{entrytype} except that the \field{name} field, if |
| 6024 |
missing, is obtained from the \field{plural} field. If the |
| 6025 |
\field{plural} field is missing it's obtained from the \field{text} |
| 6026 |
field with the plural suffix appended. If the \field{text} field is |
| 6027 |
missing, it's obtained from the original entry label. If the |
| 6028 |
\field{sort} field is missing the default is obtained from the |
| 6029 |
\field{name} field. (As with \atentry{index}, \atentry{indexplural} |
| 6030 |
is \emph{not} governed by \csopt{entry-sort-fallback}, but it is |
| 6031 |
governed by \csopt{custom-sort-fallbacks}.) |
| 6032 |
See \sectionref{sec:fallbacks}. |
| 6033 |
All fields are optional. For example: |
| 6034 |
\begin{codeenv} |
| 6035 |
\atentry{indexplural}\marg{goose, |
| 6036 |
\field{plural} = \marg{geese} |
| 6037 |
} |
| 6038 |
\strut |
| 6039 |
\atentry{indexplural}\marg{duck} |
| 6040 |
\strut |
| 6041 |
\atentry{indexplural}\marg{chateau, |
| 6042 |
\field{text} = \marg{ch\ics{cs.circum}ateau}, |
| 6043 |
\field{plural} = \marg{ch\cs{cs.circum}ateaux} |
| 6044 |
} |
| 6045 |
\end{codeenv} |
| 6046 |
This is equivalent to: |
| 6047 |
\begin{codeenv} |
| 6048 |
\atentry{indexplural}\marg{goose, |
| 6049 |
\field{name} = \marg{geese}, |
| 6050 |
\field{text} = \marg{goose}, |
| 6051 |
\field{plural} = \marg{geese} |
| 6052 |
} |
| 6053 |
\strut |
| 6054 |
\atentry{indexplural}\marg{duck, |
| 6055 |
\field{name} = \marg{ducks}, |
| 6056 |
\field{text} = \marg{duck}, |
| 6057 |
\field{plural} = \marg{ducks} |
| 6058 |
} |
| 6059 |
\strut |
| 6060 |
\atentry{indexplural}\marg{chateau, |
| 6061 |
\field{name} = \marg{ch\cs{cs.circum}ateaux}, |
| 6062 |
\field{text} = {ch\cs{cs.circum}ateau}, |
| 6063 |
\field{plural} = {ch\cs{cs.circum}ateaux} |
| 6064 |
} |
| 6065 |
\end{codeenv} |
| 6066 |
|
| 6067 |
Terms that are defined using \atentry{indexplural} will be written to the output |
| 6068 |
file using the command \gls!{bibglsnewindexplural}. |
| 6069 |
|
| 6070 |
\entrysection{abbreviation} |
| 6071 |
|
| 6072 |
The \atentry{abbreviation} \gls{entrytype} is designed for abbreviations. |
| 6073 |
The required fields are \field{short} and \field{long}. If the |
| 6074 |
\field{sort} key is missing, \bibgls\ will use the field given by |
| 6075 |
\csopt{abbreviation-sort-fallback}, which defaults to the \field{short} field. |
| 6076 |
(If you want an equivalent of \gls!{newdualentry}, use |
| 6077 |
\atentry{dualabbreviationentry} instead.) |
| 6078 |
|
| 6079 |
If you use \csopt[name]{sort-field} (rather than the default |
| 6080 |
\csopt[sort]{sort-field}), then the fallback for the |
| 6081 |
\field{name} field is always the \field{short} field, regardless of |
| 6082 |
the \csopt{abbreviation-sort-fallback} setting, unless you use |
| 6083 |
\csopt{abbreviation-name-fallback} to change the fallback for the |
| 6084 |
\field{name} field. |
| 6085 |
See \sectionref{sec:fallbacks}. |
| 6086 |
|
| 6087 |
Note that you must set the abbreviation style before loading the |
| 6088 |
resource file to ensure that the abbreviations are defined |
| 6089 |
correctly, however \bibgls\ has no knowledge of the abbreviation |
| 6090 |
style so it doesn't know if the \field{description} field must be |
| 6091 |
included or if the default \field{sort} value isn't simply the value |
| 6092 |
of the \field{short} field. |
| 6093 |
|
| 6094 |
You can instruct \bibgls\ to sort by the \field{long} field instead |
| 6095 |
using \csopt[long]{abbreviation-sort-fallback}. You can also tell \bibgls\ to |
| 6096 |
ignore certain fields using \csopt{ignore-fields}, so you can |
| 6097 |
include a \field{description} field in the \ext{bib} file if |
| 6098 |
you sometimes need it, and then instruct \bibgls\ to ignore it when |
| 6099 |
you don't want it. |
| 6100 |
|
| 6101 |
For example: |
| 6102 |
\begin{codeenv} |
| 6103 |
\atentry{abbreviation}\marg{html, |
| 6104 |
\field{short} = \marg{html}, |
| 6105 |
\field{long} = \marg{hypertext markup language}, |
| 6106 |
\field{description} = \marg{a markup language for creating web pages} |
| 6107 |
} |
| 6108 |
\end{codeenv} |
| 6109 |
If you want the \abbrstyle{long-noshort-desc} style, then you can put |
| 6110 |
the following in your document (where the \ext{bib} file is called |
| 6111 |
\filefmt{entries-abbrv.bib}): |
| 6112 |
\begin{codeenv} |
| 6113 |
\ics{setabbreviationstyle}\marg{long-noshort-desc} |
| 6114 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries-abbrv]{src}, |
| 6115 |
\csopt[long]{abbreviation-sort-fallback}} |
| 6116 |
\end{codeenv} |
| 6117 |
Whereas, if you want the \abbrstyle{long-short-sc} style, then you can |
| 6118 |
instead do: |
| 6119 |
\begin{codeenv} |
| 6120 |
\cs{setabbreviationstyle}\marg{long-short-sc} |
| 6121 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries-abbrv]{src},\csopt[description]{ignore-fields}} |
| 6122 |
\end{codeenv} |
| 6123 |
or to convert the short value to \idx{uppercase} and use the |
| 6124 |
\abbrstyle{long-short-sm} style instead: |
| 6125 |
\begin{codeenv} |
| 6126 |
\cs{setabbreviationstyle}\marg{long-short-sm} |
| 6127 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries-abbrv]{src}, |
| 6128 |
\csopt[uc]{short-case-change},\comment{convert short value to upper case} |
| 6129 |
\csopt[description]{ignore-fields}} |
| 6130 |
\end{codeenv} |
| 6131 |
|
| 6132 |
Case-changing can be applied with \csopt{short-case-change} to |
| 6133 |
convert the case of the \field{short} field, as illustrated above. |
| 6134 |
If you use a style that obtains the \field{description} from the |
| 6135 |
\field{long} form, but you want to apply a case-change to the |
| 6136 |
\field{description} field with \csopt{description-case-change}, then |
| 6137 |
you can copy the \field{long} field to the \field{description} with |
| 6138 |
\csopt[\field{long}=\field{description}]{replicate-fields}. |
| 6139 |
|
| 6140 |
For example, if \filefmt{entries-abbrv.bib} contains: |
| 6141 |
\begin{codeenv} |
| 6142 |
\atentry{abbreviation}\marg{html, |
| 6143 |
\field{short} = \marg{html}, |
| 6144 |
\field{long} = \marg{hypertext markup language} |
| 6145 |
} |
| 6146 |
\end{codeenv} |
| 6147 |
then the document may include: |
| 6148 |
\begin{codeenv} |
| 6149 |
\cs{setabbreviationstyle}\marg{long-short-sc} |
| 6150 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries-abbrv]{src}, |
| 6151 |
\csopt[firstuc]{description-case-change}, |
| 6152 |
\csopt[\field{long}=\field{description}]{replicate-fields}} |
| 6153 |
\end{codeenv} |
| 6154 |
Note that this can cause a problem for styles that set the |
| 6155 |
\field{description} field to the \field{long} form encapsulated by a |
| 6156 |
style command (such as with the \abbrstyle{long-em-short-em} style) |
| 6157 |
as this will override the style setting. |
| 6158 |
|
| 6159 |
Similarly, if you want to change the case of the \field{name} field: |
| 6160 |
\begin{codeenv} |
| 6161 |
\cs{setabbreviationstyle}\marg{long-short-sc} |
| 6162 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries-abbrv]{src}, |
| 6163 |
\csopt[firstuc]{description-case-change}, |
| 6164 |
\csopt[uc]{name-case-change}, |
| 6165 |
\csopt[\field{long}=\field{description},\field{short}=\field{name}]{replicate-fields}} |
| 6166 |
\end{codeenv} |
| 6167 |
Again, this will lose any custom formatting command that would |
| 6168 |
usually be applied by the abbreviation style to the \field{name} |
| 6169 |
field (and \field{description}, if applicable). |
| 6170 |
|
| 6171 |
Terms defined using \atentry{abbreviation} will be written to the output |
| 6172 |
file using the command \gls!{bibglsnewabbreviation}. |
| 6173 |
|
| 6174 |
\entrysection{acronym} |
| 6175 |
|
| 6176 |
The \atentry{acronym} \gls{entrytype} is like \atentry{abbreviation} except that |
| 6177 |
the term is written to the output file using the command |
| 6178 |
\gls!{bibglsnewacronym}. |
| 6179 |
|
| 6180 |
\entrysection{contributor} |
| 6181 |
|
| 6182 |
The \atentry{contributor} \gls{entrytype} is primarily provided for |
| 6183 |
use by the \atentry{bibtexentry} type. You may use it explicitly if |
| 6184 |
you want, but you need to take care that it doesn't clash with |
| 6185 |
\atentry{bibtexentry}. It behaves much like \atentry{index} except |
| 6186 |
that the term is written to the \ext{glstex} file using the command |
| 6187 |
\gls!{bibglsnewcontributor}. There are no required fields. As with |
| 6188 |
\atentry{index}, if the \field{name} field is missing, the fallback |
| 6189 |
value is the entry's label (see \sectionref{sec:fallbacks}). When |
| 6190 |
this \gls{entrytype} is automatically created by |
| 6191 |
\atentry{bibtexentry}, the \field{name} is set to |
| 6192 |
\begin{codeenv} |
| 6193 |
\gls{bibglscontributor}\margm{forenames}\margm{von}\margm{surname}\margm{suffix} |
| 6194 |
\end{codeenv} |
| 6195 |
|
| 6196 |
If you do explicitly use \atentry{contributor} you need to make sure it's |
| 6197 |
defined \emph{before} the first instance of \atentry{bibtexentry} that |
| 6198 |
tries to access it, but within the same resource set. If you ensure that |
| 6199 |
the label of \atentry{contributor} matches the contributor label generated by |
| 6200 |
\atentry{bibtexentry} then they can have their dependency lists |
| 6201 |
updated, and |
| 6202 |
the \field{bibtexentry} and \field{bibtexentry@entrytype} internal |
| 6203 |
fields can be set for the |
| 6204 |
\atentry{contributor} entry. For example: |
| 6205 |
\begin{codeenv} |
| 6206 |
\atentry{contributor}\marg{KnuthDonaldE, |
| 6207 |
\field{name}=\marg{\gls{bibglscontributor}\marg{Donald E.}\marg{}\marg{Knuth}\marg{}}, |
| 6208 |
\field{description}=\marg{Famous mathematician and computer scientist who |
| 6209 |
created \cmd{TeX}} |
| 6210 |
} |
| 6211 |
\strut |
| 6212 |
@book\marg{texbook, |
| 6213 |
title = \marg{The {\cmd{TeX} book}}, |
| 6214 |
author = \marg{Donald E. Knuth}, |
| 6215 |
publisher = \marg{Addison-Wesley}, |
| 6216 |
year = 1986 |
| 6217 |
} |
| 6218 |
\end{codeenv} |
| 6219 |
The resource options then need to include: |
| 6220 |
\begin{codeenv} |
| 6221 |
\csopt[\ics{GlsXtrBibTeXEntryAliases}]{entry-type-aliases}, |
| 6222 |
\csopt[ |
| 6223 |
\marg{[ \cs{cs.string}\csfmt{-}\cs{cs.string}\csfmt{.}]}\marg{} |
| 6224 |
]{labelify-replace} |
| 6225 |
\end{codeenv} |
| 6226 |
|
| 6227 |
If the \atentry{contributor} entry is deferred until after the |
| 6228 |
corresponding \atentry{bibtexentry} then you will end up with a label clash. |
| 6229 |
|
| 6230 |
\subsection{Dual Entry Types} |
| 6231 |
\label{sec:dualentry} |
| 6232 |
|
| 6233 |
The \glspl{entrytype} described in this section create two separate (but |
| 6234 |
related) \styfmt{glossaries-extra} entry definitions per \ext{bib} |
| 6235 |
entry. The first of these entries is considered the |
| 6236 |
\igls{primaryentry}, and the second is the \igls{dualentry}. |
| 6237 |
The naming scheme is \code{@dual}\meta{entry-type} where both the |
| 6238 |
\primary\ and \dual\ are considered to have the same type of entry |
| 6239 |
(such as \atentry{dualsymbol} where both the \primary\ and \dual\ |
| 6240 |
are functionally like \atentry{symbol}) or |
| 6241 |
\code{@dual}\meta{primary}\meta{dual} where the \primary\ is |
| 6242 |
functionally like \code{@}\meta{primary} and the \dual\ is |
| 6243 |
functionally like \code{@}\meta{dual}. |
| 6244 |
|
| 6245 |
If you need a field to store the \glsdisp{dualentry}{dual} |
| 6246 |
description in (and you're not simply swapping known fields around), |
| 6247 |
then you can use the special \field{dualdescription} field and add |
| 6248 |
it to your map. |
| 6249 |
|
| 6250 |
If the fields provided by the \isty{glossaries-prefix} are defined, |
| 6251 |
there will be additional mappings for the special internal fields |
| 6252 |
\field{dualprefix}, \field{dualprefixfirst}, |
| 6253 |
\field{dualprefixplural}, and \field{dualprefixfirstplural}. |
| 6254 |
|
| 6255 |
For example: |
| 6256 |
\begin{codeenv} |
| 6257 |
\atentry{dualabbreviationentry}\marg{svm, |
| 6258 |
\field{short} = \marg{SVM}, |
| 6259 |
\field{long} = \marg{support vector machine}, |
| 6260 |
\field{description} = \marg{statistical pattern recognition technique} |
| 6261 |
} |
| 6262 |
\end{codeenv} |
| 6263 |
is like: |
| 6264 |
\begin{codeenv} |
| 6265 |
\atentry{abbreviation}\marg{svm, |
| 6266 |
\field{short} = \marg{SVM}, |
| 6267 |
\field{long} = \marg{support vector machine}, |
| 6268 |
} |
| 6269 |
\atentry{entry}\marg{dual.svm, |
| 6270 |
\field{text} = \marg{SVM}, |
| 6271 |
\field{name} = \marg{support vector machine}, |
| 6272 |
\field{description} = \marg{statistical pattern recognition technique} |
| 6273 |
} |
| 6274 |
\end{codeenv} |
| 6275 |
and is analogous to: |
| 6276 |
\begin{codeenv} |
| 6277 |
\gls{newabbreviation}\marg{svm}\marg{SVM}\marg{support vector machine} |
| 6278 |
\gls{newglossaryentry}\marg{dual.svm}\marg{\field{name}=\marg{support vector machine},\field{text}=\marg{SVM}, |
| 6279 |
\field{description}=\marg{statistical pattern recognition technique}} |
| 6280 |
\end{codeenv} |
| 6281 |
but both entries are considered dependent on each other. This means |
| 6282 |
that if you only reference the \gls{primaryentry} (using \ics{gls} etc) |
| 6283 |
then the \gls{dualentry} will still be selected if the \csopt{selection} |
| 6284 |
setting includes dependencies. |
| 6285 |
|
| 6286 |
The creation of the \gls{dualentry} involves mapping or copying |
| 6287 |
fields from the \gls{primaryentry}. Each \gls{dualentry} type has a |
| 6288 |
set of mappings. If a field in the set of mappings is missing, its |
| 6289 |
fallback value is used (see \sectionref{sec:fallbacks}). Any fields |
| 6290 |
that aren't listed in the mappings are simply copied, except for the |
| 6291 |
\field{alias} field, which will never be copied to the |
| 6292 |
\gls{dualentry}, nor can it be mapped. The alias will only apply to |
| 6293 |
the \gls{primaryentry}. The \gls{dualentry} is given the label |
| 6294 |
\meta{prefix}\meta{id} where \meta{prefix} is set by the |
| 6295 |
\csopt{dual-prefix} option and \meta{id} is the label supplied in |
| 6296 |
the \ext{bib} file. |
| 6297 |
|
| 6298 |
If \csopt[combine]{dual-sort} then the \glspl{dualentry} will be sorted |
| 6299 |
along with the \glspl{primaryentry}, otherwise the \csopt{dual-sort} |
| 6300 |
indicates how to sort the dual entries and the dual entries will be |
| 6301 |
appended to the end of the \ext{glstex} file. The |
| 6302 |
\csopt{dual-sort-field} determines what field to use for the sort |
| 6303 |
value if the dual entries should be sorted separately. |
| 6304 |
|
| 6305 |
Take care if you have a mixture of \glspl{entrytype} (such as |
| 6306 |
\atentry{dualindexentry}, \atentry{dualindexsymbol} |
| 6307 |
and \atentry{index}) and you're not |
| 6308 |
using the default \csopt[combine]{dual-sort}. Remember that the |
| 6309 |
\glspl{primaryentry} are all sorted together along with the single |
| 6310 |
entries types described in \sectionref{sec:dualentry} (but they may |
| 6311 |
be assigned to different glossary types), and then the dual entries |
| 6312 |
are sorted together (but may be assigned to different glossary |
| 6313 |
types). This may result in an odd ordering if some of the primaries |
| 6314 |
and some of the duals are assigned to the same glossary. For |
| 6315 |
example, don't mix \atentry{dualindexabbreviation} (duals are |
| 6316 |
abbreviations) with \atentry{dualabbreviationentry} (primaries |
| 6317 |
are abbreviations) when you aren't using \csopt[combine]{dual-sort} |
| 6318 |
(unless you have two different glossaries for the \primary\ vs |
| 6319 |
\dual\ abbreviations). |
| 6320 |
|
| 6321 |
Remember that \bibgls\ is designed to take advantage of |
| 6322 |
\ics{printunsrtglossary}, which simply iterates over all defined |
| 6323 |
entries in the order in which they were defined (or, more precisely, |
| 6324 |
the order of the internal list of entry labels associated with that |
| 6325 |
glossary). The aim of \bibgls\ is to write the entry definitions to |
| 6326 |
the \ext{glstex} file so that the internal list of labels is in the |
| 6327 |
appropriate order. |
| 6328 |
|
| 6329 |
For example, suppose the file \filefmt{entries.bib} contains: |
| 6330 |
\begin{codeenv} |
| 6331 |
\atentry{index}\marg{aardvark} |
| 6332 |
\atentry{index}\marg{mouse} |
| 6333 |
\atentry{index}\marg{zebra} |
| 6334 |
\atentry{dualindexabbreviation}\marg{xml, |
| 6335 |
\field{short}=\marg{XML}, |
| 6336 |
\field{long}=\marg{extensible markup language} |
| 6337 |
} |
| 6338 |
\atentry{dualabbreviationentry}\marg{ssi, |
| 6339 |
\field{short}=\marg{SSI}, |
| 6340 |
\field{long}=\marg{server-side includes}, |
| 6341 |
\field{description}=\marg{directives placed in \cs{gls}\marg{html} pages |
| 6342 |
evaluated by the server} |
| 6343 |
} |
| 6344 |
\atentry{dualindexabbreviation}\marg{html, |
| 6345 |
\field{short}=\marg{HTML}, |
| 6346 |
\field{long}=\marg{hypertext markup language} |
| 6347 |
} |
| 6348 |
\atentry{dualabbreviationentry}\marg{css, |
| 6349 |
\field{short}=\marg{CSS}, |
| 6350 |
\field{long}=\marg{cascading stylesheets}, |
| 6351 |
\field{description}=\marg{a language that describes the style of an |
| 6352 |
\cs{gls}\marg{html} document} |
| 6353 |
} |
| 6354 |
\end{codeenv} |
| 6355 |
This contains a mixture of \glspl{entrytype}, including |
| 6356 |
\atentry{dualindexabbreviation} (where the \dual\ is the |
| 6357 |
abbreviation) and \atentry{dualabbreviationentry} (where the |
| 6358 |
\primary\ is the abbreviation). |
| 6359 |
|
| 6360 |
Now consider the following document: |
| 6361 |
\begin{codeenv} |
| 6362 |
\cmd{documentclass}\marg{article} |
| 6363 |
\strut |
| 6364 |
\cmd{usepackage}[\styopt{record},\styopt{abbreviations}]\marg{glossaries-extra} |
| 6365 |
\strut |
| 6366 |
\gls{GlsXtrLoadResources}\oarg{\csopt[all]{selection},\csopt[entries]{src}} |
| 6367 |
\strut |
| 6368 |
\cmd{begin}\marg{document} |
| 6369 |
\cs{printunsrtglossaries} |
| 6370 |
\cmd{end}\marg{document} |
| 6371 |
\end{codeenv} |
| 6372 |
This uses the default \csopt[combine]{sort}, so all the entries are |
| 6373 |
sorted together, resulting in the order: |
| 6374 |
\code{aardvark}, |
| 6375 |
\code{dual.css}, |
| 6376 |
\code{css}, |
| 6377 |
\code{html}, |
| 6378 |
\code{dual.html}, |
| 6379 |
\code{mouse}, |
| 6380 |
\code{dual.ssi}, |
| 6381 |
\code{ssi}, |
| 6382 |
\code{xml}, |
| 6383 |
\code{dual.xml}, |
| 6384 |
\code{zebra}. |
| 6385 |
|
| 6386 |
The \LaTeX\ code written to the \iext{glstex} file is essentially |
| 6387 |
(but not exactly): |
| 6388 |
\begin{codeenv} |
| 6389 |
\comment{from \atentry{index}\marg{aardvark}:} |
| 6390 |
\gls{newglossaryentry}\marg{aardvark}\marg{\field{name}=\marg{aardvark},\field{description}=\marg{}} |
| 6391 |
\strut |
| 6392 |
\comment{\dual\ of \atentry{dualabbreviationentry}\marg{css,\ldots}:} |
| 6393 |
\gls{newglossaryentry}\marg{dual.css}\marg{\field{name}=\marg{cascading stylesheets},\marg{text}=\marg{CSS}, |
| 6394 |
\field{description}=\marg{a language that describes the style of an |
| 6395 |
\cs{glsxtrshort}\marg{html} document}} |
| 6396 |
\strut |
| 6397 |
\comment{\primary\ of \atentry{dualabbreviationentry}\marg{css,\ldots}:} |
| 6398 |
\gls{newabbreviation}\marg{css}\marg{CSS}\marg{cascading stylesheets} |
| 6399 |
\strut |
| 6400 |
\comment{\primary\ of \atentry{dualindexabbreviation}\marg{html,\ldots}:} |
| 6401 |
\gls{newglossaryentry}\marg{html}\marg{\field{name}=\marg{HTML},\field{description}=\marg{}} |
| 6402 |
\strut |
| 6403 |
\comment{\dual\ of \atentry{dualindexabbreviation}\marg{html,\ldots}:} |
| 6404 |
\gls{newabbreviation}\marg{dual.html}\marg{HTML}\marg{hypertext markup language} |
| 6405 |
\strut |
| 6406 |
\comment{from \atentry{index}\marg{mouse}:} |
| 6407 |
\gls{newglossaryentry}\marg{mouse}\marg{\marg{name}=\marg{mouse},\field{description}=\marg{}} |
| 6408 |
\strut |
| 6409 |
\comment{\dual\ of \atentry{dualabbreviationentry}\marg{ssi,\ldots}:} |
| 6410 |
\gls{newglossaryentry}\marg{dual.ssi}\marg{\field{name}=\marg{server-side includes},\field{text}=\marg{SSI}, |
| 6411 |
\field{description}=\marg{directives placed in \cs{glsxtrshort}\marg{html} pages |
| 6412 |
evaluated by the server}} |
| 6413 |
\strut |
| 6414 |
\comment{\primary\ of \atentry{dualabbreviationentry}\marg{ssi,\ldots}:} |
| 6415 |
\gls{newabbreviation}\marg{ssi}\marg{SSI}\marg{server-side includes} |
| 6416 |
\strut |
| 6417 |
\comment{\primary\ of \atentry{dualindexabbreviation}\marg{xml,\ldots}:} |
| 6418 |
\gls{newglossaryentry}\marg{xml}\marg{\field{name}=\marg{XML},\field{description}=\marg{}} |
| 6419 |
\strut |
| 6420 |
\comment{\dual\ of \atentry{dualindexabbreviation}\marg{xml,\ldots}:} |
| 6421 |
\gls{newabbreviation}\marg{dual.xml}\marg{XML}\marg{extensible markup language} |
| 6422 |
\strut |
| 6423 |
\comment{from \atentry{index}\marg{zebra}:} |
| 6424 |
\gls{newglossaryentry}\marg{zebra}\marg{\field{name}=\marg{zebra},\field{description}=\marg{}} |
| 6425 |
\end{codeenv} |
| 6426 |
Since the document uses the \styopt{abbreviations} package option, |
| 6427 |
\gls{newabbreviation} automatically assigns the abbreviation |
| 6428 |
to the \code{abbreviations} glossary (created through that package |
| 6429 |
option). This means that the \glsdisp{mainglossary}{\code{main} (default) glossary} |
| 6430 |
contains the entries (in order): |
| 6431 |
\begin{itemize} |
| 6432 |
\item \code{aardvark} (name: aardvark), |
| 6433 |
\item \code{dual.css} (name: cascading stylesheets), |
| 6434 |
\item \code{html} (name: HTML), |
| 6435 |
\item \code{mouse} (name: mouse), |
| 6436 |
\item \code{dual.ssi} (name: server-side includes), |
| 6437 |
\item \code{xml} (name: XML), |
| 6438 |
\item \code{zebra} (name: zebra). |
| 6439 |
\end{itemize} |
| 6440 |
The \code{abbreviations} glossary contains: |
| 6441 |
\begin{itemize} |
| 6442 |
\item \code{css} (short: CSS), |
| 6443 |
\item \code{dual.html} (short: HTML), |
| 6444 |
\item \code{ssi} (short: SSI), |
| 6445 |
\item \code{dual.xml} (short: XML). |
| 6446 |
\end{itemize} |
| 6447 |
|
| 6448 |
Since all the entries were combined and sorted together, the |
| 6449 |
resulting glossaries are both ordered alphabetically (using |
| 6450 |
\field{short} for the abbreviations and \field{name} for the rest), |
| 6451 |
but note that you need to take care when referencing the |
| 6452 |
abbreviations if you want to make use of the abbreviation style. You |
| 6453 |
need \verb|\gls{css}| and \verb|\gls{ssi}| for the \primary\ |
| 6454 |
abbreviations created with \atentry{dualabbreviationentry} and |
| 6455 |
\verb|\gls{dual.html}| and \verb|\gls{dual.xml}| for the \dual\ |
| 6456 |
abbreviations created with \atentry{dualindexabbreviation}. Also |
| 6457 |
the \field{name} of the \primary\slash \dual\ alternative of the |
| 6458 |
abbreviations is also inconsistent (short form for \code{html} and |
| 6459 |
\code{xml} and long form for \code{dual.css} and \code{dual.ssi}), |
| 6460 |
as different field mappings are used. |
| 6461 |
|
| 6462 |
If the document is changed so that the \glspl{dualentry} are now |
| 6463 |
sorted and written after all the \glspl{primaryentry} have been dealt |
| 6464 |
with: |
| 6465 |
\begin{codeenv} |
| 6466 |
\gls{GlsXtrLoadResources}\oarg{ |
| 6467 |
\csopt[entries]{src}, |
| 6468 |
\csopt[letter-nocase]{dual-sort}, |
| 6469 |
\csopt[all]{selection} |
| 6470 |
} |
| 6471 |
\end{codeenv} |
| 6472 |
then \bibgls\ first orders the \glsdisp{primaryentry}{primaries}: |
| 6473 |
\begin{itemize} |
| 6474 |
\item \code{aardvark} (name: aardvark), |
| 6475 |
\item \code{css} (short: CSS), |
| 6476 |
\item \code{html} (name: HTML), |
| 6477 |
\item \code{mouse} (name: mouse), |
| 6478 |
\item \code{ssi} (short: SSI), |
| 6479 |
\item \code{xml} (name: XML), |
| 6480 |
\item \code{zebra} (name: zebra) |
| 6481 |
\end{itemize} |
| 6482 |
and writes them to the \ext{glstex} file |
| 6483 |
(functionally like): |
| 6484 |
\begin{codeenv} |
| 6485 |
\comment{from \atentry{index}\marg{aardvark}:} |
| 6486 |
\gls{newglossaryentry}\marg{aardvark}\marg{\field{name}=\marg{aardvark},\field{description}=\marg{}} |
| 6487 |
\strut |
| 6488 |
\comment{\primary\ of \atentry{dualabbreviationentry}\marg{css,\ldots}:} |
| 6489 |
\gls{newabbreviation}\marg{css}\marg{CSS}\marg{cascading stylesheets} |
| 6490 |
\strut |
| 6491 |
\comment{\primary\ of \atentry{dualindexabbreviation}\marg{html,\ldots}:} |
| 6492 |
\gls{newglossaryentry}\marg{html}\marg{\field{name}=\marg{HTML},\field{description}=\marg{}} |
| 6493 |
\strut |
| 6494 |
\comment{from \atentry{index}\marg{mouse}:} |
| 6495 |
\gls{newglossaryentry}\marg{mouse}\marg{\field{name}=\marg{mouse},\field{description}=\marg{}} |
| 6496 |
\strut |
| 6497 |
\comment{\primary\ of \atentry{dualabbreviationentry}\marg{ssi,\ldots}:} |
| 6498 |
\gls{newabbreviation}\marg{ssi}\marg{SSI}\marg{server-side includes} |
| 6499 |
\strut |
| 6500 |
\comment{\primary\ of \atentry{dualindexabbreviation}\marg{xml,\ldots}:} |
| 6501 |
\gls{newglossaryentry}\marg{xml}\marg{\field{name}=\marg{XML},\field{description}=\marg{}} |
| 6502 |
\strut |
| 6503 |
\comment{from \atentry{index}\marg{zebra}:} |
| 6504 |
\gls{newglossaryentry}\marg{zebra}\marg{\field{name}=\marg{zebra},\field{description}=\marg{}} |
| 6505 |
\end{codeenv} |
| 6506 |
Then \bibgls\ orders the \glsdisp{dualentry}{duals}: |
| 6507 |
\begin{itemize} |
| 6508 |
\item \code{dual.css} (name: cascading stylesheets), |
| 6509 |
\item \code{dual.html} (short: HTML), |
| 6510 |
\item \code{dual.ssi} (name: server-side includes), |
| 6511 |
\item \code{dual.xml} (short: XML) |
| 6512 |
\end{itemize} |
| 6513 |
and writes them to the \ext{glstex} file |
| 6514 |
(functionally like): |
| 6515 |
\begin{codeenv} |
| 6516 |
\comment{\dual\ of \atentry{dualabbreviationentry}\marg{css,\ldots}:} |
| 6517 |
\gls{newglossaryentry}\marg{dual.css}\marg{\field{name}=\marg{cascading stylesheets},\field{text}=\marg{CSS}, |
| 6518 |
\field{description}=\marg{a language that describes the style of an |
| 6519 |
\cs{glsxtrshort}\marg{html} document}} |
| 6520 |
\strut |
| 6521 |
\comment{\dual\ of \atentry{dualindexabbreviation}\marg{html,\ldots}:} |
| 6522 |
\gls{newabbreviation}\marg{dual.html}\marg{HTML}\marg{hypertext markup language} |
| 6523 |
\strut |
| 6524 |
\comment{\dual\ of \atentry{dualabbreviationentry}\marg{ssi,\ldots}:} |
| 6525 |
\gls{newglossaryentry}\marg{dual.ssi}\marg{\field{name}=\marg{server-side includes},\field{text}=\marg{SSI}, |
| 6526 |
\field{description}=\marg{directives placed in \cs{glsxtrshort}\marg{html} pages |
| 6527 |
evaluated by the server}} |
| 6528 |
\strut |
| 6529 |
\comment{\dual\ of \atentry{dualindexabbreviation}\marg{xml,\ldots}:} |
| 6530 |
\gls{newabbreviation}\marg{dual.xml}\marg{XML}\marg{extensible markup language} |
| 6531 |
\end{codeenv} |
| 6532 |
When the \ext{glstex} file is input (during the next \LaTeX\ run) |
| 6533 |
the entries are defined in the order: |
| 6534 |
\begin{enumerate} |
| 6535 |
\item \code{aardvark} (type: \code{main}), |
| 6536 |
\item \code{css} (type: \code{abbreviations}), |
| 6537 |
\item \code{html} (type: \code{main}), |
| 6538 |
\item \code{mouse} (type: \code{main}), |
| 6539 |
\item \code{ssi} (type: \code{abbreviations}), |
| 6540 |
\item \code{xml} (type: \code{main}), |
| 6541 |
\item \code{zebra} (type: \code{main}), |
| 6542 |
\item \code{dual.css} (type: \code{main}), |
| 6543 |
\item \code{dual.html} (type: \code{abbreviations}), |
| 6544 |
\item \code{dual.ssi} (type: \code{main}), |
| 6545 |
\item \code{dual.xml} (type: \code{abbreviations}). |
| 6546 |
\end{enumerate} |
| 6547 |
This means that the \glsdisp{mainglossary}{\code{main} glossary's} internal list is in the |
| 6548 |
order: |
| 6549 |
\begin{itemize} |
| 6550 |
\item \code{aardvark} (aardvark), |
| 6551 |
\item \code{html} (HTML), |
| 6552 |
\item \code{mouse} (mouse), |
| 6553 |
\item \code{xml} (XML), |
| 6554 |
\item \code{zebra} (zebra), |
| 6555 |
\item \code{dual.css} (cascading stylesheets), |
| 6556 |
\item \code{dual.ssi} (server-side includes) |
| 6557 |
\end{itemize} |
| 6558 |
and the \code{abbreviations} glossary's internal list is in the order: |
| 6559 |
\begin{itemize} |
| 6560 |
\item \code{css} (CSS), |
| 6561 |
\item \code{ssi} (SSI), |
| 6562 |
\item \code{dual.html} (HTML), |
| 6563 |
\item \code{dual.xml} (XML). |
| 6564 |
\end{itemize} |
| 6565 |
The lists are no longer in alphabetical order as they have a mixture |
| 6566 |
of \primary\ and \dual\ entries that were separated before sorting. |
| 6567 |
|
| 6568 |
The above is a fairly contrived example as it wouldn't make sense |
| 6569 |
in a real document to have glossary terms (that include a |
| 6570 |
description) mixed with index terms (that don't include a |
| 6571 |
description). |
| 6572 |
A better solution would be to use |
| 6573 |
\atentry{tertiaryindexabbreviationentry} instead of |
| 6574 |
\atentry{dualabbreviationentry}. |
| 6575 |
|
| 6576 |
\entrysection{dualentry} |
| 6577 |
|
| 6578 |
The \atentry{dualentry} \gls{entrytype} is similar to \atentry{entry} but |
| 6579 |
actually defines two entries. |
| 6580 |
The \gls{dualentry} contains the same information as the \gls{primaryentry} |
| 6581 |
but some of the fields are swapped around. |
| 6582 |
The default mappings are: |
| 6583 |
\begin{itemize} |
| 6584 |
\item \field{name} $\mapsto$ \field{description} |
| 6585 |
\item \field{plural} $\mapsto$ \field{descriptionplural} |
| 6586 |
\item \field{description} $\mapsto$ \field{name} |
| 6587 |
\item \field{descriptionplural} $\mapsto$ \field{plural} |
| 6588 |
\end{itemize} |
| 6589 |
If the prefix fields are defined, then the default mappings |
| 6590 |
additionally include: |
| 6591 |
\begin{itemize} |
| 6592 |
\item \field{prefix} $\mapsto$ \field{dualprefix} |
| 6593 |
\item \field{prefixplural} $\mapsto$ \field{dualprefixplural} |
| 6594 |
\item \field{prefixfirst} $\mapsto$ \field{dualprefixfirst} |
| 6595 |
\item \field{prefixfirstplural} $\mapsto$ \field{dualprefixfirstplural} |
| 6596 |
\item \field{dualprefix} $\mapsto$ \field{prefix} |
| 6597 |
\item \field{dualprefixplural} $\mapsto$ \field{prefixplural} |
| 6598 |
\item \field{dualprefixfirst} $\mapsto$ \field{prefixfirst} |
| 6599 |
\item \field{dualprefixfirstplural} $\mapsto$ \field{prefixfirstplural} |
| 6600 |
\end{itemize} |
| 6601 |
The required fields are as for \atentry{entry}. |
| 6602 |
|
| 6603 |
For example: |
| 6604 |
\begin{codeenv} |
| 6605 |
\atentry{dualentry}\marg{child, |
| 6606 |
\field{name}=\marg{child}, |
| 6607 |
\field{plural}=\marg{children}, |
| 6608 |
\field{description}=\marg{enfant} |
| 6609 |
} |
| 6610 |
\end{codeenv} |
| 6611 |
is like: |
| 6612 |
\begin{codeenv} |
| 6613 |
\atentry{entry}\marg{child, |
| 6614 |
\field{name}=\marg{child}, |
| 6615 |
\field{plural}=\marg{children}, |
| 6616 |
\field{description}=\marg{enfant} |
| 6617 |
\field{descriptionplural}=\marg{enfants} |
| 6618 |
} |
| 6619 |
\strut |
| 6620 |
\atentry{entry}\marg{dual.child, |
| 6621 |
\field{description}=\marg{child}, |
| 6622 |
\field{descriptionplural}=\marg{children}, |
| 6623 |
\field{name}=\marg{enfant} |
| 6624 |
\field{plural}=\marg{enfants} |
| 6625 |
} |
| 6626 |
\end{codeenv} |
| 6627 |
where \idprefix{dual} is replaced by the value of the |
| 6628 |
\csopt{dual-prefix} option. However, instead of defining the entries |
| 6629 |
with \csfmt{bibglsnewentry} both the \primary\ and \dual\ entries are |
| 6630 |
defined using \gls!{bibglsnewdualentry}. The \field{category} |
| 6631 |
and \field{type} fields can be set for the \gls{dualentry} using the |
| 6632 |
\csopt{dual-category} and \csopt{dual-type} options. |
| 6633 |
|
| 6634 |
For example: |
| 6635 |
\begin{codeenv} |
| 6636 |
\cs{newglossary*}\marg{english}\marg{English} |
| 6637 |
\cs{newglossary*}\marg{french}\marg{French} |
| 6638 |
\strut |
| 6639 |
\gls{GlsXtrLoadResources}\oarg{ |
| 6640 |
\csopt[entries-dual]{src},\comment{data in entries-dual.bib} |
| 6641 |
\csopt[english]{type},\comment{put \glspl{primaryentry} in glossary 'english'} |
| 6642 |
\csopt[french]{dual-type},\comment{put \glspl{dualentry} in glossary 'french'} |
| 6643 |
\csopt[dictionary]{category},\comment{set the \primary\ category to 'dictionary'} |
| 6644 |
\csopt[dictionary]{dual-category},\comment{set the \dual\ category to 'dictionary'} |
| 6645 |
\csopt[en]{sort},\comment{sort \glspl{primaryentry} according to language 'en'} |
| 6646 |
\csopt[fr]{dual-sort}\comment{sort \glspl{dualentry} according to language 'fr'} |
| 6647 |
} |
| 6648 |
\end{codeenv} |
| 6649 |
|
| 6650 |
If you need to keep the same name but have different descriptions |
| 6651 |
then you can use \field{dualdescription} and set up a mapping to use |
| 6652 |
it. For example: |
| 6653 |
\begin{codeenv} |
| 6654 |
\atentry{dualentry}\marg{sample, |
| 6655 |
\field{name}=\marg{sample}, |
| 6656 |
\field{description}=\marg{\primary\ sample description}, |
| 6657 |
\field{dualdescription}=\marg{\dual\ sample description} |
| 6658 |
} |
| 6659 |
\end{codeenv} |
| 6660 |
The mapping can then be: |
| 6661 |
\begin{codeenv} |
| 6662 |
\csopt[\marg{\field{description}}, |
| 6663 |
\marg{\field{dualdescription}}]{dual-entry-map} |
| 6664 |
\end{codeenv} |
| 6665 |
|
| 6666 |
\entrysection{dualindexentry} |
| 6667 |
|
| 6668 |
There are no required fields. The \gls{primaryentry} behaves like |
| 6669 |
\atentry{index} and the \gls{dualentry} behaves |
| 6670 |
like \atentry{entry}. The default field mapping is: |
| 6671 |
\begin{itemize} |
| 6672 |
\item \field{name} $\mapsto$ \field{name} |
| 6673 |
\end{itemize} |
| 6674 |
If the prefix fields are defined, then the default mappings |
| 6675 |
additionally include: |
| 6676 |
\begin{itemize} |
| 6677 |
\item \field{prefix} $\mapsto$ \field{dualprefix} |
| 6678 |
\item \field{prefixplural} $\mapsto$ \field{dualprefixplural} |
| 6679 |
\item \field{prefixfirst} $\mapsto$ \field{dualprefixfirst} |
| 6680 |
\item \field{prefixfirstplural} $\mapsto$ \field{dualprefixfirstplural} |
| 6681 |
\item \field{dualprefix} $\mapsto$ \field{prefix} |
| 6682 |
\item \field{dualprefixplural} $\mapsto$ \field{prefixplural} |
| 6683 |
\item \field{dualprefixfirst} $\mapsto$ \field{prefixfirst} |
| 6684 |
\item \field{dualprefixfirstplural} $\mapsto$ \field{prefixfirstplural} |
| 6685 |
\end{itemize} |
| 6686 |
This doesn't actually perform any swapping of fields, but it |
| 6687 |
provides the field used for backlinks (if |
| 6688 |
\csopt{dual-indexentry-backlink} is set). The reason that the |
| 6689 |
\primary\ (rather than the \dual) is like \atentry{index} is to allow the |
| 6690 |
primaries to merge with any \atentry{index} entries found in the |
| 6691 |
resource set, since glossary entries with descriptions are likely to |
| 6692 |
be a subset of all indexed entries. |
| 6693 |
|
| 6694 |
If no \field{name} is given, the \gls{dualentry} is assigned the |
| 6695 |
(unprefixed) entry label. For example: |
| 6696 |
\begin{codeenv} |
| 6697 |
\atentry{dualindexentry}\marg{array, |
| 6698 |
\field{description}=\marg{ordered list of values} |
| 6699 |
} |
| 6700 |
\end{codeenv} |
| 6701 |
This is effectively like: |
| 6702 |
\begin{codeenv} |
| 6703 |
\atentry{index}\marg{array} |
| 6704 |
\strut |
| 6705 |
\atentry{entry}\marg{dual.array, |
| 6706 |
\field{name}=\marg{array}, |
| 6707 |
\field{description}=\marg{ordered list of values} |
| 6708 |
} |
| 6709 |
\end{codeenv} |
| 6710 |
The \glspl{primaryentry} are defined using |
| 6711 |
\gls!{bibglsnewdualindexentry}, |
| 6712 |
which by default sets the \field{category} to \optfmt{index} |
| 6713 |
(although this may be overridden, for example, by the \csopt{category} option). |
| 6714 |
The \glspl{dualentry} are defined with |
| 6715 |
\gls!{bibglsnewdualindexentrysecondary}. |
| 6716 |
|
| 6717 |
This is the most convenient way of having an entry that's also |
| 6718 |
automatically indexed. For example, suppose the file |
| 6719 |
\filefmt{terms.bib} contains: |
| 6720 |
\begin{codeenv} |
| 6721 |
\atentry{index}\marg{duck} |
| 6722 |
\atentry{index}\marg{zebra} |
| 6723 |
\atentry{index}\marg{aardvark} |
| 6724 |
\end{codeenv} |
| 6725 |
and suppose the file \filefmt{entries.bib} contains: |
| 6726 |
\begin{codeenv} |
| 6727 |
\atentry{dualindexentry}\marg{array, |
| 6728 |
\field{description}=\marg{ordered list of values} |
| 6729 |
} |
| 6730 |
\strut |
| 6731 |
\atentry{dualindexentry}\marg{vector, |
| 6732 |
\field{name}=\marg{vector}, |
| 6733 |
\field{description}=\marg{column or row of values} |
| 6734 |
} |
| 6735 |
\strut |
| 6736 |
\atentry{dualindexentry}\marg{set, |
| 6737 |
\field{description}=\marg{collection of values} |
| 6738 |
} |
| 6739 |
\strut |
| 6740 |
\atentry{dualindexentry}\marg{matrix, |
| 6741 |
\field{plural}=\marg{matrices}, |
| 6742 |
\field{description}=\marg{rectangular array of values} |
| 6743 |
} |
| 6744 |
\end{codeenv} |
| 6745 |
These entries can be used in an example document that has an |
| 6746 |
index and a glossary: |
| 6747 |
\begin{codeenv} |
| 6748 |
\cmd{documentclass}\marg{article} |
| 6749 |
\strut |
| 6750 |
\cmd{usepackage}[colorlinks]\marg{hyperref} |
| 6751 |
\cmd{usepackage}[\styopt{record},\styopt{index},\styopt[mcols]{stylemods}]\marg{glossaries-extra} |
| 6752 |
\strut |
| 6753 |
\gls{GlsXtrLoadResources}\oarg{ |
| 6754 |
\csopt[terms,entries]{src}, |
| 6755 |
\csopt[index]{type}, |
| 6756 |
\csopt[idx.]{label-prefix}, |
| 6757 |
\csopt[gls.]{dual-prefix}, |
| 6758 |
\csopt[primary]{combine-dual-locations}, |
| 6759 |
\csopt[main]{dual-type} |
| 6760 |
} |
| 6761 |
\strut |
| 6762 |
\cmd{begin}\marg{document} |
| 6763 |
\cs{gls}\marg{gls.array}, \cs{gls}\marg{gls.vector}, \cs{gls}\marg{gls.set}, \cs{gls}\marg{gls.matrix}. |
| 6764 |
\strut |
| 6765 |
\cs{gls}\marg{idx.duck}, \cs{gls}\marg{idx.aardvark}, \cs{gls}\marg{idx.zebra}. |
| 6766 |
\strut |
| 6767 |
\cs{renewcommand}\marg{\cs{glstreenamefmt}}[1]\marg{\ics{textsc}\marg{\idx{param}1}} |
| 6768 |
\cs{printunsrtglossary}\oarg{\printglossopt[main]{type},\printglossopt[index]{style},\iprintglossopt{nogroupskip}} |
| 6769 |
\strut |
| 6770 |
\cs{renewcommand}\marg{\cs{glstreenamefmt}}[1]\marg{\idx{param}1} |
| 6771 |
\cs{renewcommand}\marg{\cs{glstreegroupheaderfmt}}[1]\marg{\cs{textbf}\marg{\idx{param}1}} |
| 6772 |
\cs{printunsrtglossary}\oarg{\printglossopt[index]{type},\printglossopt[mcolindexgroup]{style}} |
| 6773 |
\cmd{end}\marg{document} |
| 6774 |
\end{codeenv} |
| 6775 |
This uses \csopt{combine-dual-locations} to combine the \glspl{location} |
| 6776 |
for the \primary\ and \dual\ entries so that they only appear in the |
| 6777 |
index. |
| 6778 |
|
| 6779 |
To avoid the inconvenience of remembering which prefix to use, you can |
| 6780 |
set up the prefixes with \ics{glsxtraddlabelprefix} and reference entries |
| 6781 |
with \ics{dgls}, \ics{dGls} etc instead of \cs{gls}, \cs{Gls} etc. |
| 6782 |
|
| 6783 |
\entrysection{dualindexabbreviation} |
| 6784 |
|
| 6785 |
The \atentry{dualindexabbreviation} \gls{entrytype} is similar to |
| 6786 |
\atentry{dualindexentry} and again, by default, the |
| 6787 |
field mapping is: |
| 6788 |
\begin{itemize} |
| 6789 |
\item \field{name} $\mapsto$ \field{name} |
| 6790 |
\end{itemize} |
| 6791 |
If the prefix fields are defined, then the default mappings |
| 6792 |
additionally include: |
| 6793 |
\begin{itemize} |
| 6794 |
\item \field{prefix} $\mapsto$ \field{dualprefix} |
| 6795 |
\item \field{prefixplural} $\mapsto$ \field{dualprefixplural} |
| 6796 |
\item \field{prefixfirst} $\mapsto$ \field{dualprefixfirst} |
| 6797 |
\item \field{prefixfirstplural} $\mapsto$ \field{dualprefixfirstplural} |
| 6798 |
\item \field{dualprefix} $\mapsto$ \field{prefix} |
| 6799 |
\item \field{dualprefixplural} $\mapsto$ \field{prefixplural} |
| 6800 |
\item \field{dualprefixfirst} $\mapsto$ \field{prefixfirst} |
| 6801 |
\item \field{dualprefixfirstplural} $\mapsto$ \field{prefixfirstplural} |
| 6802 |
\end{itemize} |
| 6803 |
However in this case the required fields are \field{short} and |
| 6804 |
\field{long}. The \field{name} for the \gls{primaryentry} defaults to |
| 6805 |
\field{short} if omitted. (This may be changed with the |
| 6806 |
\csopt{abbreviation-name-fallback} option.) The fallback for the |
| 6807 |
\field{sort} field is given by \csopt{abbreviation-sort-fallback}, |
| 6808 |
which defaults to the \field{short} field (see \sectionref{sec:fallbacks}). |
| 6809 |
|
| 6810 |
For example: |
| 6811 |
\begin{codeenv} |
| 6812 |
\atentry{dualindexabbreviation}\marg{html, |
| 6813 |
\field{short} = \marg{HTML}, |
| 6814 |
\field{long} = \marg{hypertext markup language} |
| 6815 |
} |
| 6816 |
\end{codeenv} |
| 6817 |
is like: |
| 6818 |
\begin{codeenv} |
| 6819 |
\atentry{index}\marg{html,\field{name}=\marg{HTML}} |
| 6820 |
\strut |
| 6821 |
\atentry{abbreviation}\marg{dual.html, |
| 6822 |
\field{short} = \marg{HTML}, |
| 6823 |
\field{long} = \marg{hypertext markup language} |
| 6824 |
} |
| 6825 |
\end{codeenv} |
| 6826 |
The \primary\ term is defined using |
| 6827 |
\gls!{bibglsnewdualindexabbreviation}, which encapsulates the |
| 6828 |
\field{name} to match the font used by |
| 6829 |
the \dual\ abbreviation. The encapsulation command depends |
| 6830 |
on the \csopt{abbreviation-name-fallback} value. If it's |
| 6831 |
the \field{short} field then \gls{bibglsuseabbrvfont} is |
| 6832 |
used, otherwise \gls{bibglsuselongfont} is used. |
| 6833 |
|
| 6834 |
The \primary\ definition also |
| 6835 |
by default sets the \field{category} to \optfmt{index} (although |
| 6836 |
this again may be overridden). |
| 6837 |
The \dual\ term is defined using |
| 6838 |
\gls!{bibglsnewdualindexabbreviationsecondary}. |
| 6839 |
|
| 6840 |
\entrysection{dualindexsymbol} |
| 6841 |
|
| 6842 |
The \atentry{dualindexsymbol} \gls{entrytype} is similar to |
| 6843 |
\atentry{dualindexentry}, but by default the |
| 6844 |
field mappings are: |
| 6845 |
\begin{itemize} |
| 6846 |
\item \field{symbol} $\mapsto$ \field{name} |
| 6847 |
\item \field{name} $\mapsto$ \field{symbol} |
| 6848 |
\item \field{symbolplural} $\mapsto$ \field{plural} |
| 6849 |
\item \field{plural} $\mapsto$ \field{symbolplural} |
| 6850 |
\end{itemize} |
| 6851 |
If the prefix fields are defined, then the default mappings |
| 6852 |
additionally include: |
| 6853 |
\begin{itemize} |
| 6854 |
\item \field{prefix} $\mapsto$ \field{dualprefix} |
| 6855 |
\item \field{prefixplural} $\mapsto$ \field{dualprefixplural} |
| 6856 |
\item \field{prefixfirst} $\mapsto$ \field{dualprefixfirst} |
| 6857 |
\item \field{prefixfirstplural} $\mapsto$ \field{dualprefixfirstplural} |
| 6858 |
\item \field{dualprefix} $\mapsto$ \field{prefix} |
| 6859 |
\item \field{dualprefixplural} $\mapsto$ \field{prefixplural} |
| 6860 |
\item \field{dualprefixfirst} $\mapsto$ \field{prefixfirst} |
| 6861 |
\item \field{dualprefixfirstplural} $\mapsto$ \field{prefixfirstplural} |
| 6862 |
\end{itemize} |
| 6863 |
The required field is: \field{symbol}. |
| 6864 |
If the \field{name} field is omitted, the \dual\ entry is assigned a |
| 6865 |
symbol from the original (unprefixed) label. |
| 6866 |
The \glspl{primaryentry} are defined using |
| 6867 |
\gls!{bibglsnewdualindexsymbol}, |
| 6868 |
which by default sets the \field{category} to \optfmt{index}, |
| 6869 |
and the \glspl{dualentry} are defined using |
| 6870 |
\gls!{bibglsnewdualindexsymbolsecondary}, |
| 6871 |
which by default sets the \field{category} to \optfmt{symbol}. |
| 6872 |
For example: |
| 6873 |
\begin{codeenv} |
| 6874 |
\atentry{dualindexsymbol}\marg{pi, |
| 6875 |
\field{symbol}=\marg{\cs{ensuremath}\marg{\ics{pi}}}, |
| 6876 |
\field{description}=\marg{ratio of a circle's circumference to its diameter} |
| 6877 |
} |
| 6878 |
\end{codeenv} |
| 6879 |
is like: |
| 6880 |
\begin{codeenv} |
| 6881 |
\atentry{index}\marg{pi,\field{symbol}=\marg{\cs{ensuremath}\marg{\cs{pi}}}} |
| 6882 |
\strut |
| 6883 |
\atentry{symbol}\marg{dual.pi, |
| 6884 |
\field{name}=\marg{\cs{ensuremath}\marg{\cs{pi}}}, |
| 6885 |
\field{symbol}=\marg{pi}, |
| 6886 |
\field{description}=\marg{ratio of a circle's circumference to its diameter} |
| 6887 |
} |
| 6888 |
\end{codeenv} |
| 6889 |
|
| 6890 |
For example, suppose I have a file called \filefmt{symbols.bib} that |
| 6891 |
contains: |
| 6892 |
\begin{codeenv} |
| 6893 |
\atentry{dualindexsymbol}\marg{pi, |
| 6894 |
\field{symbol}=\marg{\cs{ensuremath}\marg{\cs{pi}}}, |
| 6895 |
\field{description}=\marg{ratio of a circle's circumference to its diameter} |
| 6896 |
} |
| 6897 |
\strut |
| 6898 |
\atentry{dualindexsymbol}\marg{e, |
| 6899 |
\field{name}=\marg{Euler's number}, |
| 6900 |
\field{symbol}=\marg{\cs{ensuremath}\marg{e}}, |
| 6901 |
\field{description}=\marg{base of the natural logarithm} |
| 6902 |
} |
| 6903 |
\end{codeenv} |
| 6904 |
Then the previous example document can be modified to have an index, |
| 6905 |
a glossary and a list of symbols: |
| 6906 |
\begin{codeenv} |
| 6907 |
\cmd{documentclass}\marg{report} |
| 6908 |
\strut |
| 6909 |
\cmd{usepackage}[colorlinks]\marg{hyperref} |
| 6910 |
\cmd{usepackage}[\styopt{record},\styopt{symbols},\styopt{index},\styopt[mcols]{stylemods}]\marg{glossaries-extra} |
| 6911 |
\strut |
| 6912 |
\cs{newcommand}\marg{\gls{bibglsnewdualindexsymbolsecondary}}[5]\marg{\comment{} |
| 6913 |
\cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{category}=symbol,\comment{} |
| 6914 |
\field{symbol}=\marg{\idx{param}4},\idx{param}2,\field{type}=\marg{symbols}}\marg{\idx{param}5}\comment{} |
| 6915 |
} |
| 6916 |
\strut |
| 6917 |
\cs{newcommand}\marg{\cmd{indexprimary}}[1]\marg{\ics{glsadd}\oarg{\glsaddopt[\encap{hyperbf}]{format}}\marg{idx.\idx{param}1}} |
| 6918 |
\strut |
| 6919 |
\cs{glsdefpostdesc}\marg{symbol}\marg{\cmd{indexprimary}\marg{\cs{glscurrententrylabel}}} |
| 6920 |
\cs{glsdefpostdesc}\marg{general}\marg{\cmd{indexprimary}\marg{\cs{glscurrententrylabel}}} |
| 6921 |
\strut |
| 6922 |
\gls{GlsXtrLoadResources}\oarg{ |
| 6923 |
\csopt[entries,terms,symbols]{src}, |
| 6924 |
\csopt[index]{type}, |
| 6925 |
\csopt{set-widest}, |
| 6926 |
\csopt[idx.]{label-prefix}, |
| 6927 |
\csopt[\empty]{dual-prefix}, |
| 6928 |
\csopt[primary]{combine-dual-locations}, |
| 6929 |
\csopt[letter-case]{dual-sort}, |
| 6930 |
\csopt[main]{dual-type} |
| 6931 |
} |
| 6932 |
\strut |
| 6933 |
\gls{glsxtrnewglslike}\oarg{\glsopt[false]{hyper}}\marg{idx.}\marg{\cmd{idx}}\marg{\cmd{idxpl}}\marg{\cmd{Idx}}\marg{\cmd{Idxpl}} |
| 6934 |
\strut |
| 6935 |
\cmd{begin}\marg{document} |
| 6936 |
\cs{gls}\marg{array}, \cs{gls}\marg{vector}, \cs{gls}\marg{set}, \cs{glspl}\marg{matrix}. |
| 6937 |
\cmd{idx}\marg{duck}, \cmd{idx}\marg{aardvark}, \cmd{idx}\marg{zebra}. |
| 6938 |
\cs{gls}\marg{e} and \cs{gls}\marg{pi}. |
| 6939 |
\strut |
| 6940 |
\cmd{newpage} |
| 6941 |
\cs{gls}\marg{array}, \cmd{idx}\marg{vector}, \cmd{idx}\marg{set}, \cs{gls}\marg{matrix}. |
| 6942 |
\strut |
| 6943 |
\cmd{newpage} |
| 6944 |
\cs{gls}\marg{array}, \cs{gls}\marg{vector}, \cs{gls}\marg{set}, \cs{gls}\marg{matrix}. |
| 6945 |
\strut |
| 6946 |
\cs{renewcommand}\marg{\cs{glstreenamefmt}}[1]\marg{\cs{textsc}\marg{\idx{param}1}} |
| 6947 |
\cs{printunsrtglossary}\oarg{\printglossopt[main]{type},\printglossopt{nogroupskip},\printglossopt[\glostyle{alttree}]{style}} |
| 6948 |
\strut |
| 6949 |
\cs{renewcommand}\marg{\cs{glstreenamefmt}}[1]\marg{\idx{param}1} |
| 6950 |
\cs{printunsrtglossary}\oarg{\printglossopt[symbols]{type},\printglossopt{nogroupskip},\printglossopt[index]{style}} |
| 6951 |
\strut |
| 6952 |
\cs{renewcommand}\marg{\cs{glstreenamefmt}}[1]\marg{\idx{param}1} |
| 6953 |
\cs{renewcommand}\marg{\cs{glstreegroupheaderfmt}}[1]\marg{\cs{textbf}\marg{\idx{param}1}} |
| 6954 |
\cs{printunsrtglossary}\oarg{\printglossopt[index]{type},\printglossopt[\glostyle{mcolindexgroup}]{style}} |
| 6955 |
\strut |
| 6956 |
\cmd{end}\marg{document} |
| 6957 |
\end{codeenv} |
| 6958 |
Here I've provided some convenient commands for referencing the |
| 6959 |
\primary\ (index) terms (\csfmt{idx}, \csfmt{idxpl}, \csfmt{Idx} |
| 6960 |
and \csfmt{Idxpl}). This means I don't need to worry about the |
| 6961 |
label prefix and it also switches off the hyperlinks (with |
| 6962 |
\code{\glsopt[false]{hyper}}). These custom |
| 6963 |
commands are defined using: |
| 6964 |
\nosecformatdef{glsxtrnewglslike} |
| 6965 |
which, in this case, essentially does: |
| 6966 |
\begin{codeenv} |
| 6967 |
\cs{newcommand}\marg{\cmd{idx}}[2][]\marg{\cs{gls}\oarg{\glsopt[false]{hyper},\idx{param}1}\marg{idx.\idx{param}2}} |
| 6968 |
\cs{newcommand}\marg{\cmd{Idx}}[2][]\marg{\cs{Gls}\oarg{\glsopt[false]{hyper},\idx{param}1}\marg{idx.\idx{param}2}} |
| 6969 |
\cs{newcommand}\marg{\cmd{idxpl}}[2][]\marg{\cs{glspl}\oarg{\glsopt[false]{hyper},\idx{param}1}\marg{idx.\idx{param}2}} |
| 6970 |
\cs{newcommand}\marg{\cmd{Idxpl}}[2][]\marg{\cs{Glspl}\oarg{\glsopt[false]{hyper},\idx{param}1}\marg{idx.\idx{param}2}} |
| 6971 |
\end{codeenv} |
| 6972 |
but the new commands will also recognise the \ics{gls} modifiers, so |
| 6973 |
\verb|\idx+| will behave like \verb|\gls+| which wouldn't be |
| 6974 |
possible if \csfmt{idx} was defined using \ics{newcommand} in the |
| 6975 |
above manner. There's a similar command: |
| 6976 |
\nosecformatdef{glsxtrnewgls} |
| 6977 |
if no case-changing versions are required. |
| 6978 |
|
| 6979 |
I've also redefined \gls!{bibglsnewdualindexsymbolsecondary} to put |
| 6980 |
the dual entries created with \atentry{dualindexsymbol} into |
| 6981 |
the \code{symbols} glossary (which is created with the |
| 6982 |
\styopt{symbols} package option), so it overrides the |
| 6983 |
\csopt[main]{dual-type} setting. |
| 6984 |
|
| 6985 |
This command also sets the \field{category} |
| 6986 |
to \code{symbol}, so I can redefine the post-description hook |
| 6987 |
for symbols (\ics{glsxtrpostdescsymbol}) to automatically index |
| 6988 |
the symbol definition. Similarly for the \code{general} |
| 6989 |
post-description hook \ics{glsxtrpostdescgeneral}. |
| 6990 |
|
| 6991 |
Since the post-description hook isn't done until the glossary has |
| 6992 |
been created, this requires a slightly longer build process. If the |
| 6993 |
document file is called \filefmt{myDoc.tex}, then the complete |
| 6994 |
document build is: |
| 6995 |
\begin{verbatim} |
| 6996 |
pdflatex myDoc |
| 6997 |
bib2gls -g myDoc |
| 6998 |
pdflatex myDoc |
| 6999 |
bib2gls -g myDoc |
| 7000 |
pdflatex myDoc |
| 7001 |
\end{verbatim} |
| 7002 |
|
| 7003 |
As from \sty{glossaries-extra-bib2gls} version 1.37, an alternative |
| 7004 |
method is to identify possible label prefixes with |
| 7005 |
\ics{glsxtraddlabelprefix} or \ics{glsxtrprependlabelprefix} and use |
| 7006 |
\ics{dgls}, \ics{dglspl}, \ics{dGls} or \ics{dGlspl}. See the |
| 7007 |
\styfmt{glossaries-extra} user manual~\cite{glossaries-extra} for |
| 7008 |
further details. |
| 7009 |
|
| 7010 |
\entrysection{dualindexnumber} |
| 7011 |
|
| 7012 |
The \atentry{dualindexnumber} \gls{entrytype} is almost identical to |
| 7013 |
\atentry{dualindexsymbol}, but the \glspl{primaryentry} are defined using |
| 7014 |
\gls!{bibglsnewdualindexnumber}, |
| 7015 |
which by default sets the \field{category} to \optfmt{index}, |
| 7016 |
and the \glspl{dualentry} are defined using |
| 7017 |
\gls!{bibglsnewdualindexnumbersecondary}, |
| 7018 |
which by default sets the \field{category} to \optfmt{number}. |
| 7019 |
|
| 7020 |
\entrysection{dualabbreviationentry} |
| 7021 |
|
| 7022 |
The \atentry{dualabbreviationentry} \gls{entrytype} is similar to |
| 7023 |
\atentry{dualentry}, but by default the |
| 7024 |
field mappings are: |
| 7025 |
\begin{itemize} |
| 7026 |
\item \field{long} $\mapsto$ \field{name} |
| 7027 |
\item \field{longplural} $\mapsto$ \field{plural} |
| 7028 |
\item \field{short} $\mapsto$ \field{text} |
| 7029 |
\end{itemize} |
| 7030 |
If the prefix fields are defined, then the default mappings |
| 7031 |
additionally include: |
| 7032 |
\begin{itemize} |
| 7033 |
\item \field{prefix} $\mapsto$ \field{dualprefix} |
| 7034 |
\item \field{prefixplural} $\mapsto$ \field{dualprefixplural} |
| 7035 |
\item \field{prefixfirst} $\mapsto$ \field{dualprefixfirst} |
| 7036 |
\item \field{prefixfirstplural} $\mapsto$ \field{dualprefixfirstplural} |
| 7037 |
\item \field{dualprefix} $\mapsto$ \field{prefix} |
| 7038 |
\item \field{dualprefixplural} $\mapsto$ \field{prefixplural} |
| 7039 |
\item \field{dualprefixfirst} $\mapsto$ \field{prefixfirst} |
| 7040 |
\item \field{dualprefixfirstplural} $\mapsto$ \field{prefixfirstplural} |
| 7041 |
\end{itemize} |
| 7042 |
You may need to add a mapping from \field{shortplural} to |
| 7043 |
\field{plural} if the default is inappropriate. |
| 7044 |
(In \bibgls\ version 1.0 this \gls{entrytype} was originally called |
| 7045 |
\atentry{dualentryabbreviation}. In version 1.1, it was renamed |
| 7046 |
\atentry{dualabbreviationentry} which makes for a more consistent naming scheme |
| 7047 |
\code{@dual}\meta{primary}\meta{dual}.) |
| 7048 |
|
| 7049 |
The required fields are: \field{short}, \field{long} and |
| 7050 |
\field{description}. This \gls{entrytype} is designed to emulate the |
| 7051 |
example \gls{newdualentry} command given in the \sty{glossaries} |
| 7052 |
user manual~\cite{glossaries}. The \gls{primaryentry} is an abbreviation with the given |
| 7053 |
\field{short} and \field{long} fields (but not the |
| 7054 |
\field{description}) and the secondary entry is a regular entry with |
| 7055 |
the \field{name} copied from the \field{long} field. |
| 7056 |
The fallback for the \field{sort} is given by |
| 7057 |
\csopt{abbreviation-sort-fallback}, which defaults to the |
| 7058 |
\field{short} field (see \sectionref{sec:fallbacks}). |
| 7059 |
|
| 7060 |
For example: |
| 7061 |
\begin{codeenv} |
| 7062 |
\atentry{dualabbreviationentry}\marg{svm, |
| 7063 |
\field{long} = \marg{support vector machine}, |
| 7064 |
\field{short} = \marg{SVM}, |
| 7065 |
\field{description} = \marg{statistical pattern recognition technique} |
| 7066 |
} |
| 7067 |
\end{codeenv} |
| 7068 |
is rather like doing: |
| 7069 |
\begin{codeenv} |
| 7070 |
\atentry{abbreviation}\marg{svm, |
| 7071 |
\field{long} = \marg{support vector machine}, |
| 7072 |
\field{short} = \marg{SVM} |
| 7073 |
} |
| 7074 |
\strut |
| 7075 |
\atentry{entry}\marg{dual.svm, |
| 7076 |
\field{name} = \marg{support vector machine}, |
| 7077 |
\field{description} = \marg{statistical pattern recognition technique} |
| 7078 |
} |
| 7079 |
\end{codeenv} |
| 7080 |
but \code{dual.svm} will automatically be selected if \code{svm} |
| 7081 |
is indexed in the document. If \code{dual.svm} isn't explicitly |
| 7082 |
indexed, it won't have a \gls{locationlist}. |
| 7083 |
|
| 7084 |
If the \field{sort} field is missing \bibgls\ by default falls back |
| 7085 |
on the \field{name} field. If this is missing, this sort value will |
| 7086 |
fallback on the \field{short} field. This means that if \field{name} |
| 7087 |
isn't explicitly given in \atentry{dualabbreviationentry}, then the |
| 7088 |
\gls{primaryentry} will be sorted according to \field{short} but the |
| 7089 |
\dual\ will be sorted according its \field{name} (which has been copied |
| 7090 |
from the \primary\ \field{long}). |
| 7091 |
|
| 7092 |
Entries provided using \atentry{dualabbreviationentry} will be defined |
| 7093 |
with: |
| 7094 |
\begin{codeenv} |
| 7095 |
\gls{bibglsnewdualabbreviationentry} |
| 7096 |
\end{codeenv} |
| 7097 |
(which uses \gls{newabbreviation}) for the \glspl{primaryentry} and with : |
| 7098 |
\begin{codeenv} |
| 7099 |
\gls{bibglsnewdualabbreviationentrysecondary} |
| 7100 |
\end{codeenv} |
| 7101 |
(which uses \gls{longnewglossaryentry}) for the secondary entries. |
| 7102 |
This means that if the \styopt{abbreviations} package option is |
| 7103 |
used, the \gls{primaryentry} will be put in the |
| 7104 |
\optfmt{abbreviations} glossary and the secondary entry in the |
| 7105 |
\mainglossary\. Use the \csopt{type} and \csopt{dual-type} options |
| 7106 |
to override this. |
| 7107 |
|
| 7108 |
\entrysection{dualentryabbreviation} |
| 7109 |
|
| 7110 |
This \gls{entrytype} is deprecated as from \bibgls\ version 1.1. It's functionally |
| 7111 |
equivalent to \atentry{dualabbreviationentry} but its name |
| 7112 |
doesn't fit the general dual entry naming scheme. |
| 7113 |
|
| 7114 |
\entrysection{dualsymbol} |
| 7115 |
|
| 7116 |
This is like \atentry{dualentry} but the default mappings are: |
| 7117 |
\begin{itemize} |
| 7118 |
\item \field{name} $\mapsto$ \field{symbol} |
| 7119 |
\item \field{plural} $\mapsto$ \field{symbolplural} |
| 7120 |
\item \field{symbol} $\mapsto$ \field{name} |
| 7121 |
\item \field{symbolplural} $\mapsto$ \field{plural} |
| 7122 |
\end{itemize} |
| 7123 |
If the prefix fields are defined, then the default mappings |
| 7124 |
additionally include: |
| 7125 |
\begin{itemize} |
| 7126 |
\item \field{prefix} $\mapsto$ \field{dualprefix} |
| 7127 |
\item \field{prefixplural} $\mapsto$ \field{dualprefixplural} |
| 7128 |
\item \field{prefixfirst} $\mapsto$ \field{dualprefixfirst} |
| 7129 |
\item \field{prefixfirstplural} $\mapsto$ \field{dualprefixfirstplural} |
| 7130 |
\item \field{dualprefix} $\mapsto$ \field{prefix} |
| 7131 |
\item \field{dualprefixplural} $\mapsto$ \field{prefixplural} |
| 7132 |
\item \field{dualprefixfirst} $\mapsto$ \field{prefixfirst} |
| 7133 |
\item \field{dualprefixfirstplural} $\mapsto$ \field{prefixfirstplural} |
| 7134 |
\end{itemize} |
| 7135 |
The \field{name} and \field{symbol} fields are required. |
| 7136 |
For example: |
| 7137 |
\begin{codeenv} |
| 7138 |
\atentry{dualsymbol}\marg{pi, |
| 7139 |
\field{name}=\marg{pi}, |
| 7140 |
\field{symbol}=\marg{\cs{ensuremath}\marg{\cs{pi}}}, |
| 7141 |
\field{description}=\marg{the ratio of the length of the circumference |
| 7142 |
of a circle to its diameter} |
| 7143 |
} |
| 7144 |
\end{codeenv} |
| 7145 |
|
| 7146 |
Entries are defined using \gls!{bibglsnewdualsymbol}, which by |
| 7147 |
default sets the \field{category} to \optfmt{symbol}. |
| 7148 |
|
| 7149 |
\entrysection{dualnumber} |
| 7150 |
|
| 7151 |
This is almost identical to \atentry{dualsymbol} but entries are |
| 7152 |
defined using \gls!{bibglsnewdualnumber}, which by default sets |
| 7153 |
the \field{category} to \optfmt{number}. |
| 7154 |
|
| 7155 |
The above example could be defined as a number since $\pi$ is a |
| 7156 |
constant: |
| 7157 |
\begin{codeenv} |
| 7158 |
\atentry{dualnumber}\marg{pi, |
| 7159 |
\field{name}=\marg{pi}, |
| 7160 |
\field{symbol}=\marg{\cs{ensuremath}\marg{\cs{pi}}}, |
| 7161 |
\field{description}=\marg{the ratio of the length of the circumference |
| 7162 |
of a circle to its diameter}, |
| 7163 |
\field{user1}=\marg{3.14159} |
| 7164 |
} |
| 7165 |
\end{codeenv} |
| 7166 |
|
| 7167 |
This has stored the approximate value in the \field{user1} field. |
| 7168 |
The post-description hook could then be adapted to show this. |
| 7169 |
\begin{codeenv} |
| 7170 |
\cs{glsdefpostdesc}\marg{number}\marg{\comment{} |
| 7171 |
\cs{ifglshasfield}\marg{useri}\marg{\cs{glscurrententrylabel}} |
| 7172 |
\marg{ (approximate value: \cs{glscurrentfieldvalue})}\comment{} |
| 7173 |
\marg{}\comment{} |
| 7174 |
} |
| 7175 |
\end{codeenv} |
| 7176 |
|
| 7177 |
This use of the \field{user1} field means that the dual entries |
| 7178 |
could be sorted numerically according to the approximate value: |
| 7179 |
\begin{codeenv} |
| 7180 |
\cmd{usepackage}[\styopt{record},\styopt{postdot},\styopt{numbers},\styopt[index]{style}]\marg{glossaries-extra} |
| 7181 |
\strut |
| 7182 |
\gls{GlsXtrLoadResources}\oarg{ |
| 7183 |
\csopt[entries]{src},\comment{entries.bib} |
| 7184 |
\csopt[numbers]{dual-type}, |
| 7185 |
\csopt[double]{dual-sort},\comment{decimal sort} |
| 7186 |
\csopt[user1]{dual-sort-field} |
| 7187 |
} |
| 7188 |
\end{codeenv} |
| 7189 |
|
| 7190 |
\entrysection{dualabbreviation} |
| 7191 |
|
| 7192 |
The \atentry{dualabbreviation} \gls{entrytype} is similar to |
| 7193 |
\atentry{dualentry}, but by default the |
| 7194 |
field mappings are: |
| 7195 |
\begin{itemize} |
| 7196 |
\item \field{short} $\mapsto$ \field{dualshort} |
| 7197 |
\item \field{shortplural} $\mapsto$ \field{dualshortplural} |
| 7198 |
\item \field{long} $\mapsto$ \field{duallong} |
| 7199 |
\item \field{longplural} $\mapsto$ \field{duallongplural} |
| 7200 |
\item \field{dualshort} $\mapsto$ \field{short} |
| 7201 |
\item \field{dualshortplural} $\mapsto$ \field{shortplural} |
| 7202 |
\item \field{duallong} $\mapsto$ \field{long} |
| 7203 |
\item \field{duallongplural} $\mapsto$ \field{longplural} |
| 7204 |
\end{itemize} |
| 7205 |
If the prefix fields are defined, then the default mappings |
| 7206 |
additionally include: |
| 7207 |
\begin{itemize} |
| 7208 |
\item \field{prefix} $\mapsto$ \field{dualprefix} |
| 7209 |
\item \field{prefixplural} $\mapsto$ \field{dualprefixplural} |
| 7210 |
\item \field{prefixfirst} $\mapsto$ \field{dualprefixfirst} |
| 7211 |
\item \field{prefixfirstplural} $\mapsto$ \field{dualprefixfirstplural} |
| 7212 |
\item \field{dualprefix} $\mapsto$ \field{prefix} |
| 7213 |
\item \field{dualprefixplural} $\mapsto$ \field{prefixplural} |
| 7214 |
\item \field{dualprefixfirst} $\mapsto$ \field{prefixfirst} |
| 7215 |
\item \field{dualprefixfirstplural} $\mapsto$ \field{prefixfirstplural} |
| 7216 |
\end{itemize} |
| 7217 |
The required fields are: \field{short}, \field{long}, |
| 7218 |
\field{dualshort} and \field{duallong}. |
| 7219 |
This includes some new fields: \field{dualshort}, |
| 7220 |
\field{dualshortplural}, \field{duallong} and |
| 7221 |
\field{duallongplural}. If these aren't already defined, they |
| 7222 |
will be provided in the \iext{glstex} file with |
| 7223 |
\begin{codeenv} |
| 7224 |
\ics{glsxtrprovidestoragekey}\margm{key}\marg{}\marg{} |
| 7225 |
\end{codeenv} |
| 7226 |
Note that this use with an empty third argument prevents |
| 7227 |
the creation of a field access command (analogous to |
| 7228 |
\ics{glsentrytext}). The value can be accessed with |
| 7229 |
\ics{glsxtrusefield} instead. Remember that the field won't be |
| 7230 |
available until the \ext{glstex} file has been created. |
| 7231 |
|
| 7232 |
Note that \bibgls\ doesn't know what abbreviation styles |
| 7233 |
are in used, so if the \field{sort} field is missing |
| 7234 |
it will fallback on the \field{short} field. If the abbreviations |
| 7235 |
need to be sorted according to the \field{long} field instead, |
| 7236 |
use \csopt[long]{abbreviation-sort-fallback} (see \sectionref{sec:fallbacks}). |
| 7237 |
|
| 7238 |
Terms that are defined using \atentry{dualabbreviation} will be |
| 7239 |
written to the output file using \gls!{bibglsnewdualabbreviation}. |
| 7240 |
|
| 7241 |
If the \csopt{dual-abbrv-backlink} option is on, the default field |
| 7242 |
used for the backlinks is the \field{dualshort} field, so you'll need |
| 7243 |
to make sure you adapt the glossary style to show that field. The |
| 7244 |
simplest way to do this is through the category \idx{postdescriptionhook}. |
| 7245 |
|
| 7246 |
For example, if the entries all have the \field{category} set |
| 7247 |
to \optfmt{abbreviation}, then this requires redefining |
| 7248 |
\ics{glsxtrpostdescabbreviation} (either with \cs{renewcommand} |
| 7249 |
or via \cs{glsdefpostdesc}). |
| 7250 |
|
| 7251 |
Here's an example dual abbreviation for a document where English is |
| 7252 |
the primary language and German is the secondary language: |
| 7253 |
\begin{codeenv} |
| 7254 |
\atentry{dualabbreviation}\marg{rna, |
| 7255 |
\field{short}=\marg{RNA}, |
| 7256 |
\field{dualshort}=\marg{RNS}, |
| 7257 |
\field{long}=\marg{ribonucleic acid}, |
| 7258 |
\field{duallong}=\marg{Ribonukleins\"aure} |
| 7259 |
} |
| 7260 |
\end{codeenv} |
| 7261 |
If the abbreviation is in the file called |
| 7262 |
\filefmt{entries-dual-abbrv.bib}, then here's an example document: |
| 7263 |
\begin{codeenv} |
| 7264 |
\cmd{documentclass}\marg{article} |
| 7265 |
\strut |
| 7266 |
\cmd{usepackage}[T1]\marg{fontenc} |
| 7267 |
\cmd{usepackage}[utf8]\marg{inputenc} |
| 7268 |
\strut |
| 7269 |
\cmd{usepackage}[ngerman,main=english]\marg{babel} |
| 7270 |
\cmd{usepackage}[colorlinks]\marg{hyperref} |
| 7271 |
\cmd{usepackage}[\styopt{record},\styopt{nomain}]\marg{glossaries-extra} |
| 7272 |
\strut |
| 7273 |
\cs{newglossary*}\marg{english}\marg{English} |
| 7274 |
\cs{newglossary*}\marg{german}\marg{German} |
| 7275 |
\strut |
| 7276 |
\cs{setabbreviationstyle}\marg{long-short} |
| 7277 |
\strut |
| 7278 |
\cs{glsdefpostdesc}\marg{abbreviation}\marg{\comment{} |
| 7279 |
\cs{ifglshasfield}\marg{dualshort}\marg{\cs{glscurrententrylabel}} |
| 7280 |
\marg{\comment{} |
| 7281 |
\cmd{space}(\cs{glscurrentfieldvalue})\comment{} |
| 7282 |
}\comment{} |
| 7283 |
\marg{}\comment{} |
| 7284 |
} |
| 7285 |
\strut |
| 7286 |
\gls{GlsXtrLoadResources}\oarg{ |
| 7287 |
\csopt[entries-dual-abbrv]{src},\comment{entries-dual-abbrv.bib} |
| 7288 |
\csopt[english]{type},\comment{put \primary\ entries in glossary 'english'} |
| 7289 |
\csopt[german]{dual-type},\comment{put \dual\ entries in glossary 'german'} |
| 7290 |
\csopt[en.]{label-prefix},\comment{\primary\ label prefix} |
| 7291 |
\csopt[de.]{dual-prefix},\comment{\dual\ label prefix} |
| 7292 |
\csopt[en]{sort},\comment{sort \glspl{primaryentry} according to language 'en'} |
| 7293 |
\csopt[de-1996]{dual-sort},\comment{sort \glspl{dualentry} according to 'de-1996'} |
| 7294 |
\comment{(German new orthography)} |
| 7295 |
\csopt{dual-abbrv-backlink}\comment{add links in the glossary to the opposite entry} |
| 7296 |
} |
| 7297 |
\strut |
| 7298 |
\cmd{begin}\marg{document} |
| 7299 |
\strut |
| 7300 |
English: \cs{gls}\marg{en.rna}; \cs{gls}\marg{en.rna}. |
| 7301 |
\strut |
| 7302 |
German: \cs{gls}\marg{de.rna}; \cs{gls}\marg{de.rna}. |
| 7303 |
\strut |
| 7304 |
\cs{printunsrtglossaries} |
| 7305 |
\cmd{end}\marg{document} |
| 7306 |
\end{codeenv} |
| 7307 |
If the \csopt{label-prefix} is omitted, then only the dual entries |
| 7308 |
will have a prefix: |
| 7309 |
\begin{codeenv} |
| 7310 |
English: \cs{gls}\marg{rna}; \cs{gls}\marg{rna}. |
| 7311 |
\strut |
| 7312 |
German: \cs{gls}\marg{de.rna}; \cs{gls}\marg{de.rna}. |
| 7313 |
\end{codeenv} |
| 7314 |
Another variation is to use the \abbrstyle{long-short-user} |
| 7315 |
abbreviation style and modify the associated \ics{glsxtruserfield} so that |
| 7316 |
the \field{duallong} field is selected for the parenthetical |
| 7317 |
material: |
| 7318 |
\begin{codeenv} |
| 7319 |
\cs{renewcommand}*\marg{\cs{glsxtruserfield}}\marg{duallong} |
| 7320 |
\end{codeenv} |
| 7321 |
This means that the first use of the \gls{primaryentry} is displayed as |
| 7322 |
\begin{quote} |
| 7323 |
ribonucleic acid (RNA, Ribonukleins\"aure) |
| 7324 |
\end{quote} |
| 7325 |
and the first use of the dual entry is displayed as: |
| 7326 |
\begin{quote} |
| 7327 |
Ribonukleins\"aure (RNS, ribonucleic acid) |
| 7328 |
\end{quote} |
| 7329 |
|
| 7330 |
Here's an example to be used with the \abbrstyle{long-short-desc} |
| 7331 |
style: |
| 7332 |
\begin{codeenv} |
| 7333 |
\atentry{dualabbreviation}\marg{rna, |
| 7334 |
\field{short}=\marg{RNA}, |
| 7335 |
\field{dualshort}=\marg{RNS}, |
| 7336 |
\field{long}=\marg{ribonucleic acid}, |
| 7337 |
\field{duallong}=\marg{Ribonukleins\"aure} |
| 7338 |
\field{description}=\marg{a polymeric molecule}, |
| 7339 |
\field{user1}=\marg{Ein polymeres Molek\"ul} |
| 7340 |
} |
| 7341 |
\end{codeenv} |
| 7342 |
This stores the dual description in the \field{user1} field, |
| 7343 |
so this needs a mapping. |
| 7344 |
The new example document is much the same as the previous one, except |
| 7345 |
that the \csopt{dual-abbrv-map} option is needed to include the |
| 7346 |
mapping between the \field{description} and \field{user1} fields: |
| 7347 |
\begin{codeenv} |
| 7348 |
\cmd{documentclass}\marg{article} |
| 7349 |
\strut |
| 7350 |
\cmd{usepackage}[T1]\marg{fontenc} |
| 7351 |
\cmd{usepackage}[utf8]\marg{inputenc} |
| 7352 |
\strut |
| 7353 |
\cmd{usepackage}[ngerman,main=english]\marg{babel} |
| 7354 |
\cmd{usepackage}[colorlinks]\marg{hyperref} |
| 7355 |
\cmd{usepackage}[\styopt{record},\styopt{nomain}]\marg{glossaries-extra} |
| 7356 |
\strut |
| 7357 |
\cs{newglossary*}\marg{english}\marg{English} |
| 7358 |
\cs{newglossary*}\marg{german}\marg{German} |
| 7359 |
\strut |
| 7360 |
\cs{setabbreviationstyle}\marg{long-short-desc} |
| 7361 |
\strut |
| 7362 |
\cs{glsdefpostdesc}\marg{abbreviation}\marg{\comment{} |
| 7363 |
\cs{ifglshasfield}\marg{dualshort}\marg{\cs{glscurrententrylabel}} |
| 7364 |
\marg{\comment{} |
| 7365 |
\cmd{space}(\cs{glscurrentfieldvalue})\comment{} |
| 7366 |
}\comment{} |
| 7367 |
\marg{}\comment{} |
| 7368 |
} |
| 7369 |
\strut |
| 7370 |
\gls{GlsXtrLoadResources}\oarg{ |
| 7371 |
\csopt[entries-dual-abbrv-desc]{src},\comment{entries-dual-abbrv-desc.bib} |
| 7372 |
\csopt[english]{type},\comment{put \glspl{primaryentry} in glossary 'english'} |
| 7373 |
\csopt[german]{dual-type},\comment{put \glspl{dualentry} in glossary 'german'} |
| 7374 |
\csopt[en.]{label-prefix},\comment{\primary\ label prefix} |
| 7375 |
\csopt[de.]{dual-prefix},\comment{\dual\ label prefix} |
| 7376 |
\csopt[en]{sort},\comment{sort \glspl{primaryentry} according to language 'en'} |
| 7377 |
\csopt[long]{abbreviation-sort-fallback},\comment{fallback on 'long' field} |
| 7378 |
\csopt[de-1996]{dual-sort},\comment{sort \glspl{dualentry} according to 'de-1996'} |
| 7379 |
\comment{(German new orthography)} |
| 7380 |
\csopt{dual-abbrv-backlink},\comment{add links in the glossary to the opposite entry} |
| 7381 |
\comment{ dual key mappings:} |
| 7382 |
\csopt[\comment{} |
| 7383 |
\marg{short,shortplural,long,longplural,dualshort,dualshortplural, |
| 7384 |
duallong,duallongplural,description,user1}, |
| 7385 |
\marg{dualshort,dualshortplural,duallong,duallongplural,short,shortplural, |
| 7386 |
long,longplural,user1,description} |
| 7387 |
]{dual-abbrv-map} |
| 7388 |
} |
| 7389 |
\strut |
| 7390 |
\cmd{begin}\marg{document} |
| 7391 |
\strut |
| 7392 |
English: \cs{gls}\marg{en.rna}; \cs{gls}\marg{en.rna}. |
| 7393 |
\strut |
| 7394 |
German: \cs{gls}\marg{de.rna}; \cs{gls}\marg{de.rna}. |
| 7395 |
\strut |
| 7396 |
\cs{printunsrtglossaries} |
| 7397 |
\cmd{end}\marg{document} |
| 7398 |
\end{codeenv} |
| 7399 |
Note that since this document uses the \abbrstyle{long-short-desc} |
| 7400 |
abbreviation style, the \csopt{abbreviation-sort-fallback} needs to be changed |
| 7401 |
to \optfmt{long}. |
| 7402 |
|
| 7403 |
If I change the order of the mapping to: |
| 7404 |
\begin{codeenv} |
| 7405 |
\csopt[\comment{} |
| 7406 |
\marg{long,longplural,short,shortplural,dualshort,dualshortplural, |
| 7407 |
duallong,duallongplural,description,user1}, |
| 7408 |
\marg{duallong,duallongplural,dualshort,dualshortplural,short,shortplural, |
| 7409 |
long,longplural,user1,description} |
| 7410 |
]{dual-abbrv-map} |
| 7411 |
\end{codeenv} |
| 7412 |
Then the back-link field will switch to \field{duallong}. The |
| 7413 |
\idx{postdescriptionhook} can be modified to allow for this: |
| 7414 |
\begin{codeenv} |
| 7415 |
\cs{glsdefpostdesc}\marg{abbreviation}\marg{\comment{} |
| 7416 |
\cs{ifglshasfield}\marg{duallong}\marg{\cs{glscurrententrylabel}} |
| 7417 |
\marg{\comment{} |
| 7418 |
\cmd{space}(\cs{glscurrentfieldvalue})\comment{} |
| 7419 |
}\comment{} |
| 7420 |
\marg{}\comment{} |
| 7421 |
} |
| 7422 |
\end{codeenv} |
| 7423 |
|
| 7424 |
An alternative is to use the \abbrstyle{long-short-user-desc} style |
| 7425 |
without the \idx!{postdescriptionhook}: |
| 7426 |
\begin{codeenv} |
| 7427 |
\cs{setabbreviationstyle}\marg{long-short-user-desc} |
| 7428 |
\cs{renewcommand}*\marg{\cs{glsxtruserfield}}\marg{duallong} |
| 7429 |
\end{codeenv} |
| 7430 |
However be careful with this approach as it can cause nested |
| 7431 |
hyperlinks. In this case it's better to use the |
| 7432 |
\abbrstyle{long-postshort-user-desc} style which defers the |
| 7433 |
parenthetical material until after the link-text: |
| 7434 |
\begin{codeenv} |
| 7435 |
\cs{setabbreviationstyle}\marg{long-postshort-user-desc} |
| 7436 |
\cs{renewcommand}*\marg{\cs{glsxtruserfield}}\marg{duallong} |
| 7437 |
\end{codeenv} |
| 7438 |
If the back-link field has been switched to \field{duallong} then |
| 7439 |
the \idx!{postdescriptionhook} is no longer required. |
| 7440 |
|
| 7441 |
\entrysection{dualacronym} |
| 7442 |
|
| 7443 |
As \atentry{dualabbreviation} but defines the entries with |
| 7444 |
\gls!{bibglsnewdualacronym}. |
| 7445 |
|
| 7446 |
\subsection{Tertiary Entry Types} |
| 7447 |
\label{sec:tertiaryentry} |
| 7448 |
|
| 7449 |
A \igls{tertiaryentry} type is essentially a \gls{dualentry} that creates three |
| 7450 |
separate (but related) \styfmt{glossaries-extra} entry definitions per |
| 7451 |
\ext{bib} entry. As with \glspl{dualentry}, the first of these |
| 7452 |
is the \gls{primaryentry}. The second and third are referred to as the |
| 7453 |
\igls{secondaryentry} and \igls{tertiaryentry}. |
| 7454 |
|
| 7455 |
The \gls{tertiaryentry} is effectively an appendage of the |
| 7456 |
\gls{secondaryentry}{secondary}, and is defined by the same associated |
| 7457 |
\csfmt{bibglsnew\ldots secondary} command that defines the |
| 7458 |
\gls{secondaryentry}. Therefore the \glsdisp{secondaryentry}{secondary} |
| 7459 |
and \glsdisp{tertiaryentry}{tertiary} are both considered the |
| 7460 |
\dual\ and are treated as a single entry for the purposes of sorting |
| 7461 |
and collating. |
| 7462 |
|
| 7463 |
The \gls{tertiaryentry} will never have any \glspl{location}. Any \glspl{record} |
| 7464 |
found will be assigned to the \glsdisp{secondaryentry}{secondary} |
| 7465 |
(and may then be moved to the \primary\ with |
| 7466 |
\csopt[primary]{combine-dual-locations}). The |
| 7467 |
\glsdisp{tertiaryentry}{tertiary} will always have the same order as |
| 7468 |
the \glsdisp{secondaryentry}{secondary} and will have the same |
| 7469 |
\field{group} value. You can set the \field{type} for the |
| 7470 |
\glsdisp{tertiaryentry}{tertiary} with \csopt{tertiary-type} and the |
| 7471 |
\field{category} with \csopt{tertiary-category}. The label prefix |
| 7472 |
defaults to \idprefix{tertiary} and can be changed with |
| 7473 |
\csopt{tertiary-prefix}. |
| 7474 |
|
| 7475 |
\entrysection{tertiaryindexabbreviationentry} |
| 7476 |
|
| 7477 |
This \gls{entrytype} is very similar to |
| 7478 |
\atentry{dualindexabbreviation} but creates a \gls{tertiaryentry} as |
| 7479 |
well. The required fields are: \field{short} and \field{long} (as for |
| 7480 |
\atentry{dualindexabbreviation}) and also \field{description}. The |
| 7481 |
mappings are shared by both \glspl{entrytype}. For example: |
| 7482 |
\begin{codeenv} |
| 7483 |
\atentry{tertiaryindexabbreviationentry}\marg{html, |
| 7484 |
\field{short} = \marg{HTML}, |
| 7485 |
\field{long} = \marg{hypertext markup language}, |
| 7486 |
\field{description} = \marg{a markup language for creating web pages} |
| 7487 |
} |
| 7488 |
\end{codeenv} |
| 7489 |
is analogous to: |
| 7490 |
\begin{codeenv} |
| 7491 |
\gls{newglossaryentry}\marg{html,\field{name}=\marg{HTML},\field{description}=\marg{}} |
| 7492 |
\strut |
| 7493 |
\gls{newabbreviation}\marg{dual.html}\marg{HTML}\marg{hypertext markup language} |
| 7494 |
\strut |
| 7495 |
\gls{newglossaryentry}\marg{tertiary.html, |
| 7496 |
\field{name}=\marg{hypertext markup language}, |
| 7497 |
\field{description}=\marg{a markup language for creating web pages} |
| 7498 |
} |
| 7499 |
\end{codeenv} |
| 7500 |
The last two are actually defined using one command: |
| 7501 |
\begin{codeenv} |
| 7502 |
\gls{bibglsnewtertiaryindexabbreviationentrysecondary} |
| 7503 |
\marg{dual.html}\comment{\glsdisp{secondaryentry}{secondary} label} |
| 7504 |
\marg{tertiary.html}\comment{\glsdisp{tertiaryentry}{tertiary} label} |
| 7505 |
\marg{\ldots}\comment{\glsdisp{secondaryentry}{secondary} fields} |
| 7506 |
\marg{\ldots}\comment{\glsdisp{tertiaryentry}{tertiary} fields} |
| 7507 |
\marg{HTML}\comment{\primary\ name} |
| 7508 |
\marg{HTML}\comment{short} |
| 7509 |
\marg{hypertext markup language}\comment{long} |
| 7510 |
\marg{a markup language for creating web pages}\comment{description} |
| 7511 |
\end{codeenv} |
| 7512 |
The \gls!{bibglsnewtertiaryindexabbreviationentrysecondary} |
| 7513 |
command is provided in the \iext{glstex} file as: |
| 7514 |
\begin{codeenv} |
| 7515 |
\cs{providecommand}\marg{\gls{bibglsnewtertiaryindexabbreviationentrysecondary}}[8]\marg{\comment{} |
| 7516 |
\gls{newabbreviation}\oarg{\idx{param}3}\marg{\idx{param}1}\marg{\idx{param}6}\marg{\idx{param}7}\comment{} |
| 7517 |
\cs{longnewglossaryentry*}\marg{\idx{param}2}\comment{} |
| 7518 |
\marg{\field{name}=\marg{\cmd{protect}\gls{bibglsuselongfont}\marg{\idx{param}7}\marg{\ics{glscategory}\marg{\idx{param}1}}},\idx{param}4}\comment{} |
| 7519 |
\marg{\idx{param}8}\comment{} |
| 7520 |
} |
| 7521 |
\end{codeenv} |
| 7522 |
which defines the \glsdisp{secondaryentry}{secondary} as an |
| 7523 |
abbreviation using \csfmt{newabbreviation} and the |
| 7524 |
\glsdisp{tertiaryentry}{tertiary} as a regular entry using |
| 7525 |
\csfmt{longnewglossaryentry}. This means that the |
| 7526 |
\gls{tertiaryentry} is always defined immediately after the |
| 7527 |
corresponding \gls{secondaryentry}. The \primary\ may be defined |
| 7528 |
earlier or later in the file depending on the way the entries are |
| 7529 |
sorted and on the \csopt{dual-sort} setting. |
| 7530 |
|
| 7531 |
\subsection{Multi-Entry Types} |
| 7532 |
\label{sec:multientry} |
| 7533 |
|
| 7534 |
A \gls{multientrytype} is an entry that may spawn multiple |
| 7535 |
\glspl{primaryentry}. This means that both the \gls{mainentry} and the |
| 7536 |
\glspl{spawnedentry} are sorted together along with all the other |
| 7537 |
\glspl{primaryentry}. In the case of \atentry{spawndualindexentry}, |
| 7538 |
the \glsdisp{mainentry}{main} and \glspl{spawnedentry} are \primary. |
| 7539 |
The \gls{mainentry}['s] \dual\ is created as per \atentry{dualindexentry}. |
| 7540 |
|
| 7541 |
\entrysection{bibtexentry} |
| 7542 |
|
| 7543 |
The \atentry{bibtexentry} type will typically need to be aliased |
| 7544 |
as it's designed for converting \BibTeX\ entries into \bibgls\ |
| 7545 |
entries. For example, to make \bibgls\ treat \atentryfmt{article} |
| 7546 |
and \atentryfmt{book} as though they were both |
| 7547 |
\atentry{bibtexentry}: |
| 7548 |
\begin{codeenv} |
| 7549 |
\csopt[ |
| 7550 |
article=bibtexentry, |
| 7551 |
book=bibtexentry |
| 7552 |
]{entry-type-aliases} |
| 7553 |
\end{codeenv} |
| 7554 |
For convenience, \isty{glossaries-extra-bib2gls} v1.29+ |
| 7555 |
provides \ics{GlsXtrBibTeXEntryAliases} which covers all the |
| 7556 |
standard \BibTeX\ \glspl{entrytype}. Alternatively, you can use |
| 7557 |
\csopt[bibtexentry]{unknown-entry-alias} to alias all entries |
| 7558 |
that aren't recognised by \bibgls. If you use |
| 7559 |
\csopt[same as original entry]{category}, the \field{category} |
| 7560 |
field will be set to the original \gls{entrytype} (for example, |
| 7561 |
\code{article} or \code{book}). Similarly you can use |
| 7562 |
\csopt[same as original entry]{type} to set the \field{type} |
| 7563 |
field (but remember that the glossary types will need to be defined |
| 7564 |
in the document). |
| 7565 |
|
| 7566 |
There are no required fields. The fallback for the \field{sort} |
| 7567 |
field is given by \csopt{bibtexentry-sort-fallback} (see |
| 7568 |
\sectionref{sec:fallbacks}). If you want to access any of the |
| 7569 |
\BibTeX\ fields, you will need to alias or define them. For |
| 7570 |
example: |
| 7571 |
\begin{codeenv} |
| 7572 |
\csopt[ |
| 7573 |
\fieldfmt{title}=\field{name} |
| 7574 |
]{field-aliases} |
| 7575 |
\end{codeenv} |
| 7576 |
Since \BibTeX's \fieldfmt{type} field conflicts with \bibgls's |
| 7577 |
\field{type} field, when \bibgls\ parses \atentry{bibtexentry} |
| 7578 |
if will convert \fieldfmt{type} to \field{bibtextype}, so you |
| 7579 |
must use \field{bibtextype} as the identifier when aliasing. |
| 7580 |
|
| 7581 |
Alternatively, you can use \ics{GlsXtrProvideBibTeXFields} which |
| 7582 |
uses \ics{glsaddstoragekey} to provide all the standard \BibTeX\ |
| 7583 |
fields. (Remember that new fields must be defined before the first |
| 7584 |
\igls{resourceset}.) |
| 7585 |
|
| 7586 |
The \atentry{bibtexentry} essentially creates an \atentry{index} |
| 7587 |
form of entry, but it additionally defines a \atentry{contributor} |
| 7588 |
entry for each listed author or editor |
| 7589 |
and updates the dependency lists: each \atentry{contributor} is |
| 7590 |
added to the \glsdisp{mainentry}{main} |
| 7591 |
\atentry{bibtexentry}'s list of dependencies (so if the |
| 7592 |
\atentry{bibtexentry} has a \gls{record} then all its satellite |
| 7593 |
\atentry{contributor}s are selected with the default |
| 7594 |
\csopt[recorded and deps]{selection}), and |
| 7595 |
each \atentry{contributor} is treated as having a cross-reference to |
| 7596 |
the \glsdisp{mainentry}{main} \atentry{bibtexentry} (so if a \atentry{contributor} |
| 7597 |
has a \gls{record} then all the linked \atentry{bibtexentry} terms will |
| 7598 |
be selected if \csopt[recorded and deps and see]{selection}). |
| 7599 |
You can instruct \bibgls\ to treat \ics{citation} as an |
| 7600 |
\igls{ignoredrecord} using \longarg{cite-as-record}. |
| 7601 |
|
| 7602 |
Each contributor is effectively defined as: |
| 7603 |
\begin{codeenv} |
| 7604 |
\atentry{contributor}\marg{\meta{label}, |
| 7605 |
\field{name}=\marg{\gls{bibglscontributor}\margm{forenames}\margm{von}\margm{surname}\margm{suffix}} |
| 7606 |
} |
| 7607 |
\end{codeenv} |
| 7608 |
The label is obtained by converting the \field{name} |
| 7609 |
to a label, using the same function as \csopt{labelify} (which |
| 7610 |
means it's governed by \csopt{labelify-replace}). |
| 7611 |
|
| 7612 |
The \fieldfmt{author} and \fieldfmt{editor} fields are always |
| 7613 |
checked, even if those fields aren't recognised by \bibgls, (which |
| 7614 |
they aren't by default). These checks are performed before field |
| 7615 |
aliases are applied. If neither field is present, no additional |
| 7616 |
entries are spawned. If the dependent \atentry{contributor} entry |
| 7617 |
has already been defined, it won't be redefined, but will have the |
| 7618 |
new \atentry{bibtexentry} added to its internal \field{bibtexentry} |
| 7619 |
field. |
| 7620 |
|
| 7621 |
The \glsdisp{mainentry}{main} \atentry{bibtexentry} is defined using |
| 7622 |
\gls{bibglsnewbibtexentry} and is followed by: |
| 7623 |
\begin{codeenv} |
| 7624 |
\gls{glsxtrfieldlistadd}\margm{id}\marg{bibtexcontributor}\margm{contributor-id} |
| 7625 |
\end{codeenv} |
| 7626 |
where \meta{id} is the label identifying the \glsdisp{mainentry}{main} |
| 7627 |
\atentry{bibtexentry} and \meta{contributor-id} is the |
| 7628 |
label identifying the contributor, for each contributor that has |
| 7629 |
been selected. |
| 7630 |
|
| 7631 |
Each contributor is defined using \gls{bibglsnewcontributor}. The definition |
| 7632 |
is followed by: |
| 7633 |
\begin{codeenv} |
| 7634 |
\gls{glsxtrfieldlistadd}\margm{contributor-id}\marg{bibtexentry}\margm{id} |
| 7635 |
\gls{glsxtrfieldlistadd}\margm{contributor-id}\marg{bibtexentry@\meta{entry-type}}\margm{id} |
| 7636 |
\end{codeenv} |
| 7637 |
for each selected \atentry{bibtexentry} associated with that contributor. The |
| 7638 |
second line provides the internal list field |
| 7639 |
\field{bibtexentry@entrytype}, where \meta{entry-type} is the |
| 7640 |
original \gls{entrytype} (before it was aliased to |
| 7641 |
\atentry{bibtexentry} and converted to \idx!{lowercase}). |
| 7642 |
For example \code{article} or \code{book}. |
| 7643 |
|
| 7644 |
You can iterate over these internal list fields using |
| 7645 |
\glsadd{idx.loop}\ics{glsxtrfielddolistloop} or \ics{glsxtrfieldforlistloop}. |
| 7646 |
For example: |
| 7647 |
\begin{codeenv} |
| 7648 |
\cs{newcommand}\marg{\csfmt{contributorhandler}}[1]\marg{\csfmt{par}\cs{glsentryname}\marg{\#1}} |
| 7649 |
|
| 7650 |
\cs{newcommand}\marg{\postdeschook{contributor}}\marg{\comment{} |
| 7651 |
\cs{glsxtrifhasfield}\marg{bibtexentry}\marg{\cs{glscurrententrylabel}}\comment{} |
| 7652 |
\marg{\comment{} |
| 7653 |
\cs{glsxtrfieldforlistloop} |
| 7654 |
\marg{\cs{glscurrententrylabel}}\marg{bibtexentry}\comment{} |
| 7655 |
\marg{\csfmt{contributorhandler}}\comment{} |
| 7656 |
}\comment{} |
| 7657 |
\marg{\csfmt{par} No titles.}\comment{} |
| 7658 |
} |
| 7659 |
\end{codeenv} |
| 7660 |
(where the resource option \csopt[\fieldfmt{title}=\field{name}]{field-aliases} |
| 7661 |
has been used). |
| 7662 |
|
| 7663 |
Here's an example that uses the test \file{xampl.bib} file that's |
| 7664 |
provided with \TeX\ distributions: |
| 7665 |
\begin{codeenv} |
| 7666 |
\cmd{documentclass}\marg{article} |
| 7667 |
\strut |
| 7668 |
\cmd{usepackage}[\styopt{record},\styopt{nomain}]\marg{glossaries-extra} |
| 7669 |
\strut |
| 7670 |
\cs{newglossary*}\marg{contributors}\marg{Authors/Editors} |
| 7671 |
\cs{newglossary*}\marg{titles}\marg{Titles} |
| 7672 |
\strut |
| 7673 |
\cs{newcommand}\marg{\gls{bibglsnewbibtexentry}}[4]\marg{\comment{} |
| 7674 |
\cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}={\idx{param}3},\idx{param}2,\field{type}=\marg{titles}}\marg{\idx{param}4}\comment{} |
| 7675 |
} |
| 7676 |
\strut |
| 7677 |
\gls{GlsXtrLoadResources}\oarg{ |
| 7678 |
\csopt[xampl]{src}, |
| 7679 |
\csopt[false]{write-preamble}, |
| 7680 |
\csopt[ |
| 7681 |
\ics{GlsXtrBibTeXEntryAliases} |
| 7682 |
]{entry-type-aliases}, |
| 7683 |
\csopt[ |
| 7684 |
\fieldfmt{title}=\field{name} |
| 7685 |
]{field-aliases}, |
| 7686 |
\csopt[ |
| 7687 |
\fieldfmt{note}=\field{name} |
| 7688 |
]{replicate-fields}, |
| 7689 |
\csopt[ |
| 7690 |
\marg{[ \cs{cs.string}\csfmt{-}\cs{cs.string}\csfmt{.}]}\marg{} |
| 7691 |
]{labelify-replace}, |
| 7692 |
\csopt[contributors]{type}, |
| 7693 |
\csopt[same as original entry]{category}, |
| 7694 |
\csopt[\field{category}]{sort-field}, |
| 7695 |
\csopt[\field{name}]{sort-suffix} |
| 7696 |
} |
| 7697 |
\strut |
| 7698 |
\gls{glsxtrsetgrouptitle}\marg{article}\marg{Articles} |
| 7699 |
\gls{glsxtrsetgrouptitle}\marg{booklet}\marg{Booklets} |
| 7700 |
\gls{glsxtrsetgrouptitle}\marg{book}\marg{Books} |
| 7701 |
\gls{glsxtrsetgrouptitle}\marg{inbook}\marg{Book Chapters} |
| 7702 |
\gls{glsxtrsetgrouptitle}\marg{misc}\marg{Miscellaneous} |
| 7703 |
\strut |
| 7704 |
\cs{newcommand}\marg{\csfmt{contributorhandler}}[1]\marg{\csfmt{par}\ics{glsentryname}\marg{\idx{param}1} (\idx{param}1)} |
| 7705 |
\strut |
| 7706 |
\cs{newcommand}\marg{\postdeschook{contributor}}{\comment{} |
| 7707 |
\cs{glsxtrifhasfield}\marg{bibtexentry}\marg{\cs{glscurrententrylabel}}\comment{} |
| 7708 |
\marg{\comment{} |
| 7709 |
\ics{glsxtrfieldforlistloop} |
| 7710 |
\marg{\cs{glscurrententrylabel}}\marg{bibtexentry}\comment{} |
| 7711 |
\marg{\csfmt{contributorhandler}}\comment{} |
| 7712 |
}\comment{} |
| 7713 |
\marg{\csfmt{par} No titles.}\comment{} |
| 7714 |
} |
| 7715 |
\strut |
| 7716 |
\csfmt{begin}\marg{document} |
| 7717 |
Sample\idx{nbspchar}\ics{cite}\marg{book-minimal,article-full,inbook-full,misc-minimal}. |
| 7718 |
Another sample\idx{nbspchar}\cs{cite}\marg{booklet-minimal,misc-full,article-minimal}. |
| 7719 |
\strut |
| 7720 |
\csfmt{bibliographystyle}\marg{plain} |
| 7721 |
\ics{bibliography}\marg{xampl} |
| 7722 |
\strut |
| 7723 |
\cs{printunsrtglossary}[\printglossopt[contributors]{type},\printglossopt[altlist]{style}] |
| 7724 |
\cs{printunsrtglossary*}[\printglossopt[titles]{type},\printglossopt[indexgroup]{style}] |
| 7725 |
\marg{\comment{} |
| 7726 |
\cs{renewcommand}\marg{\ics{glsxtrgroupfield}}\marg{category}\comment{} |
| 7727 |
\cs{renewcommand}\marg{\cs{glstreenamefmt}}[1]\marg{\cs{emph}\marg{\idx{param}1}}\comment{} |
| 7728 |
\cs{renewcommand}\marg{\cs{glstreegroupheaderfmt}}[1]\marg{\cs{textbf}\marg{\idx{param}1}}\comment{} |
| 7729 |
} |
| 7730 |
\strut |
| 7731 |
\csfmt{end}\marg{document} |
| 7732 |
\end{codeenv} |
| 7733 |
If the file is called \filefmt{myDoc.tex} then the document build |
| 7734 |
is: |
| 7735 |
\begin{codeenv} |
| 7736 |
pdflatex myDoc |
| 7737 |
bib2gls \longarg{cite-as-record} myDoc |
| 7738 |
bibtex myDoc |
| 7739 |
pdflatex myDoc |
| 7740 |
pdflatex myDoc |
| 7741 |
\end{codeenv} |
| 7742 |
|
| 7743 |
\entrysection{progenitor} |
| 7744 |
|
| 7745 |
The \atentryfmt{progenitor} type of entries are the only place where |
| 7746 |
the \field{adoptparents} field is permitted. The value should be a |
| 7747 |
comma-separated list of labels. The \field{adoptparents} field |
| 7748 |
must be set and must contain a least one label. If the value |
| 7749 |
contains any of the characters \idx{backslashchar} (backslash), |
| 7750 |
\idx{bgroupchar} (open brace) or \idx{egroupchar} (close brace) then |
| 7751 |
the field will be interpreted (if the default \longarg{interpret} settings |
| 7752 |
is on). |
| 7753 |
|
| 7754 |
Since entries are spawned before fields are processed, the |
| 7755 |
\field{adoptparents} field is parsed before any field aliases |
| 7756 |
(\csopt{field-aliases}) or replication (\csopt{replicate-fields}) |
| 7757 |
takes place. However, if the \field{adoptparents} field isn't found, |
| 7758 |
\bibgls\ will check for a simple mapping in both the |
| 7759 |
\csopt{field-aliases} and \csopt{replicate-fields} settings. |
| 7760 |
|
| 7761 |
This \gls{entrytype} creates a \glsdisp{mainentry}{main} \igls[textformat=emph]{progenitor} |
| 7762 |
term (with all the given fields except \field{adoptparents}) |
| 7763 |
and $n$ spawned \igls[textformat=emph]{progeny} terms, where |
| 7764 |
$n$ is the number of elements in the \field{adoptparents} field, |
| 7765 |
that are dependent on the \glsdisp{mainentry}{main term}. |
| 7766 |
|
| 7767 |
Each of the spawned \gls{progeny} entries have the field identified by |
| 7768 |
\csopt{adopted-parent-field} (\field{parent} by default) set to the |
| 7769 |
corresponding element in the \field{adoptparents} field. |
| 7770 |
|
| 7771 |
All fields from the original definition are copied except for the |
| 7772 |
\field{adoptparents}, \field{alias} and \field{parent} fields. The |
| 7773 |
\field{parent} field is never copied, regardless of the value of |
| 7774 |
\csopt{adopted-parent-field}. If the adopted parent field is |
| 7775 |
changed to one that's contained in the original entry, it's value |
| 7776 |
will be from \field{adoptparents} not the value from the original |
| 7777 |
entry. |
| 7778 |
|
| 7779 |
The copied fields follow the same conditions as normal |
| 7780 |
entries. (For example, unknown fields are ignored, case-changes are |
| 7781 |
applied, if appropriate, and the \field{type} field must reference a |
| 7782 |
valid glossary, if set.) If \csopt{progenitor-type} is set, then |
| 7783 |
this assignment is made after the \igls{progeny} are created |
| 7784 |
and only applies to the \glsdisp{mainentry}{main} \igls{progenitor} entry. The |
| 7785 |
type for the \gls{progeny} can be set with \csopt{progeny-type}. |
| 7786 |
For example, \csopt[same as parent]{progeny-type} will ensure |
| 7787 |
that the \igls{progeny} are in the same glossary type as |
| 7788 |
their \gls{parententry}. |
| 7789 |
|
| 7790 |
For example, an entry defined as: |
| 7791 |
\begin{codeenv} |
| 7792 |
\atentry{progenitor}\marg{\meta{id}, |
| 7793 |
\field{adoptparents} = \marg{\meta{parent-1 id},\ldots,\meta{parent-N id}}, |
| 7794 |
\meta{field-name-1} = \margm{text}, |
| 7795 |
\ldots |
| 7796 |
\meta{field-name-n} = \margm{text} |
| 7797 |
} |
| 7798 |
\end{codeenv} |
| 7799 |
is essentially like: |
| 7800 |
\begin{codeenv} |
| 7801 |
\atentry{index}\marg{\meta{id}, |
| 7802 |
\field{progeny} = \marg{\meta{parent-1 id}.\meta{id},\ldots,\meta{parent-N id}.\meta{id}}, |
| 7803 |
\meta{field-name-1} = \margm{text}, |
| 7804 |
\ldots |
| 7805 |
\meta{field-name-n} = \margm{text} |
| 7806 |
} |
| 7807 |
\strut |
| 7808 |
\atentry{index}\marg{\meta{parent-1 id}.\meta{id}, |
| 7809 |
\field{progenitor} = \margm{id}, |
| 7810 |
\field{parent} = \margm{parent-1 id}, |
| 7811 |
\meta{field-name-1} = \margm{text}, |
| 7812 |
\ldots |
| 7813 |
\meta{field-name-n} = \margm{text} |
| 7814 |
} |
| 7815 |
\strut |
| 7816 |
\ldots |
| 7817 |
\strut |
| 7818 |
\atentry{index}\marg{\meta{parent-N id}.\meta{id}, |
| 7819 |
\field{progenitor} = \margm{id}, |
| 7820 |
\field{parent} = \margm{parent-N id}, |
| 7821 |
\meta{field-name-1} = \margm{text}, |
| 7822 |
\ldots |
| 7823 |
\meta{field-name-n} = \margm{text} |
| 7824 |
} |
| 7825 |
\end{codeenv} |
| 7826 |
This creates the \glsdisp{mainentry}{main} (\gls{progenitor}) \meta{id} entry, which |
| 7827 |
contains all the fields (except for \field{adoptparents}) that were |
| 7828 |
in the original \atentry{progenitor} definition and has the new |
| 7829 |
field \field{progeny} set to the comma-separated list of |
| 7830 |
\gls{spawnedentry} labels. The \glspl{mainentry} are defined in the \ext{glstex} file |
| 7831 |
with \gls{bibglsnewprogenitor}. |
| 7832 |
|
| 7833 |
In addition to the \glsdisp{mainentry}{main} \meta{id} entry, the |
| 7834 |
above also creates the spawned \gls{progeny} entries |
| 7835 |
\code{\meta{parent-1 id}.\meta{id}}, \ldots, \code{\meta{parent-N |
| 7836 |
id}.\meta{id}} that are dependent on the \glsdisp{mainentry}{main} \meta{id} entry. |
| 7837 |
|
| 7838 |
The \glspl{spawnedentry} have the \field{parent} field set to the |
| 7839 |
corresponding label obtained from the \field{adoptparents} list. |
| 7840 |
This \gls{parententry} must also be defined, as usual for the |
| 7841 |
\field{parent} field. (This restriction obviously doesn't apply if |
| 7842 |
\csopt{adopted-parent-field} is changed from the default |
| 7843 |
\field{parent}.) The spawned entries are defined in the \ext{glstex} |
| 7844 |
file with \gls{bibglsnewspawnedindex} |
| 7845 |
|
| 7846 |
If the \glsdisp{mainentry}{main} \gls{progenitor} entry is referenced in the document |
| 7847 |
then (assuming the default selection criteria) the |
| 7848 |
\glspl{spawnedentry} will also be automatically selected. You can |
| 7849 |
check for the existence of the \field{progenitor} field using |
| 7850 |
\cs{glsxtrifhasfield} and fetch the \field{location} field from the |
| 7851 |
\gls{mainentry}, if required. |
| 7852 |
|
| 7853 |
Although the \glspl{spawnedentry} are considered dependents of the |
| 7854 |
\gls{mainentry}, the reverse doesn't apply. If a \gls{spawnedentry} is referenced |
| 7855 |
in the document (with \code{\meta{parent-id}.\meta{id}}) then the |
| 7856 |
\gls{mainentry} and its other spawned entries aren't automatically |
| 7857 |
selected. |
| 7858 |
|
| 7859 |
For example, suppose the file \filefmt{entries.bib} contains: |
| 7860 |
\begin{codeenv} |
| 7861 |
\atentry{indexplural}\marg{stylesheet, \field{text}=\marg{stylesheet language}} |
| 7862 |
\strut |
| 7863 |
\atentry{index}\marg{webdesign, \field{name}=\marg{web design}} |
| 7864 |
\strut |
| 7865 |
\atentry{indexplural}\marg{markup, \field{text}=\marg{markup language}} |
| 7866 |
\strut |
| 7867 |
\atentry{progenitor}\marg{xml, |
| 7868 |
\field{name}=\marg{XML}, |
| 7869 |
\field{adoptparents}=\marg{markup} |
| 7870 |
} |
| 7871 |
\strut |
| 7872 |
\atentry{progenitor}\marg{css, |
| 7873 |
\field{name}=\marg{CSS}, |
| 7874 |
\field{adoptparents}=\marg{stylesheet,webdesign} |
| 7875 |
} |
| 7876 |
\strut |
| 7877 |
\atentry{progenitor}\marg{html, |
| 7878 |
\field{name}=\marg{HTML}, |
| 7879 |
\field{adoptparents}=\marg{markup,webdesign} |
| 7880 |
} |
| 7881 |
\strut |
| 7882 |
\atentry{progenitor}\marg{xsl, |
| 7883 |
\field{name}=\marg{XSL}, |
| 7884 |
\field{adoptparents}=\marg{stylesheet} |
| 7885 |
} |
| 7886 |
\end{codeenv} |
| 7887 |
and if the document contains: |
| 7888 |
\begin{codeenv} |
| 7889 |
\cmd{documentclass}\marg{article} |
| 7890 |
\strut |
| 7891 |
\cmd{usepackage}\oarg{\styopt{record},\styopt[tree]{stylemods},\styopt[index]{style}}\marg{glossaries-extra} |
| 7892 |
\strut |
| 7893 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[all]{selection}} |
| 7894 |
\strut |
| 7895 |
\cs{newcommand}*\marg{\cs{glstreenamefmt}}[1]\marg{\idx{param}1} |
| 7896 |
\cmd{begin}\marg{document} |
| 7897 |
\cs{printunsrtglossaries} |
| 7898 |
\cmd{end}\marg{document} |
| 7899 |
\end{codeenv} |
| 7900 |
Then the resulting list will be: |
| 7901 |
\begin{quote} |
| 7902 |
\setlength{\parindent}{0pt}% |
| 7903 |
\setlength{\parskip}{0pt plus 0.3pt}% |
| 7904 |
\glstreeitem CSS\par |
| 7905 |
\glstreeitem HTML\par |
| 7906 |
\glstreeitem markup language\par |
| 7907 |
\glstreesubitem HTML\par |
| 7908 |
\glstreesubitem XML\par |
| 7909 |
\glstreeitem stylesheet language\par |
| 7910 |
\glstreesubitem CSS\par |
| 7911 |
\glstreesubitem XSL\par |
| 7912 |
\glstreeitem web design\par |
| 7913 |
\glstreesubitem CSS\par |
| 7914 |
\glstreesubitem HTML\par |
| 7915 |
\glstreeitem XML\par |
| 7916 |
\glstreeitem XSL\par |
| 7917 |
\end{quote} |
| 7918 |
This allows the HTML and CSS entries to be listed under multiple |
| 7919 |
parents. |
| 7920 |
|
| 7921 |
The following \atentryfmt{spawn\meta{single-type}} commands are all forms |
| 7922 |
of \atentry{progenitor} that create the given |
| 7923 |
\atentryfmt{\meta{single-type}} of entry. The \glspl{spawnedentry} are actually |
| 7924 |
created with the private \gls{entrytype} \atentryfmt{spawned\meta{type}}. In the |
| 7925 |
case of \atentry{progenitor}, the \glspl{spawnedentry} are defined as |
| 7926 |
a \atentryfmt{spawnedindex} entry. These special |
| 7927 |
\atentryfmt{spawned\meta{type}} \glspl{entrytype} aren't intended for use |
| 7928 |
in the \ext{bib} file, but if you reference the \gls{entrytype} (for |
| 7929 |
example, with \csopt[same as entry]{category}) you will get |
| 7930 |
\atentryfmt{spawned\meta{type}} as the \gls{entrytype}. The |
| 7931 |
original \gls{entrytype} for the \glspl{spawnedentry} is the same as |
| 7932 |
the original entry for the \glsdisp{mainentry}{main} \atentry{progenitor} entry. |
| 7933 |
|
| 7934 |
There is currently only one form of \dual\ \atentry{progenitor} entry and that's |
| 7935 |
\atentry{spawndualindexentry}. Only the \glsdisp{mainentry}{main} \gls{progenitor} entry |
| 7936 |
is a \gls{dualentry}. The spawned \gls{progeny} are all \atentry{index} |
| 7937 |
\glspl{primaryentry}. |
| 7938 |
|
| 7939 |
\entrysection{spawnindex} |
| 7940 |
|
| 7941 |
As \atentry{progenitor}, but the \glspl{mainentry} are defined in the |
| 7942 |
\ext{glstex} file with \gls{bibglsnewspawnindex} and the |
| 7943 |
spawned entries are defined with \gls{bibglsnewspawnedindex}. |
| 7944 |
|
| 7945 |
\entrysection{spawnindexplural} |
| 7946 |
|
| 7947 |
As \atentry{progenitor}, except that it creates |
| 7948 |
\atentry{indexplural} terms instead of \atentry{index}. |
| 7949 |
As with \atentry{indexplural}, if the \field{name} field isn't set, |
| 7950 |
it's assigned to the same value as the \field{plural} field (or the |
| 7951 |
\hyperref[sec:fallbacks]{fallback} for the \field{plural}, if not defined). |
| 7952 |
|
| 7953 |
The \glspl{mainentry} are defined in the |
| 7954 |
\ext{glstex} file with \gls{bibglsnewspawnindexplural} and the |
| 7955 |
\glspl{spawnedentry} are defined with \gls{bibglsnewspawnedindexplural}. |
| 7956 |
|
| 7957 |
\entrysection{spawnentry} |
| 7958 |
|
| 7959 |
As \atentry{progenitor}, except that it creates |
| 7960 |
\atentry{entry} terms instead of \atentry{index}. |
| 7961 |
As with \atentry{entry}, the \field{description} field is required |
| 7962 |
and either \field{name} or \field{parent}. |
| 7963 |
|
| 7964 |
The \glspl{mainentry} are defined in the |
| 7965 |
\ext{glstex} file with \gls{bibglsnewspawnentry} and the |
| 7966 |
\glspl{spawnedentry} are defined with \gls{bibglsnewspawnedentry}. |
| 7967 |
|
| 7968 |
\entrysection{spawnabbreviation} |
| 7969 |
|
| 7970 |
As \atentry{progenitor}, except that it creates |
| 7971 |
\atentry{abbreviation} terms instead of \atentry{index}. |
| 7972 |
As with \atentry{abbreviation}, the \field{short} and \field{long} |
| 7973 |
fields are required. |
| 7974 |
|
| 7975 |
The \glspl{mainentry} are defined in the |
| 7976 |
\ext{glstex} file with \gls{bibglsnewspawnabbreviation} and the |
| 7977 |
\glspl{spawnedentry} are defined with \gls{bibglsnewspawnedabbreviation}. |
| 7978 |
|
| 7979 |
\entrysection{spawnacronym} |
| 7980 |
|
| 7981 |
As \atentry{progenitor}, except that it creates |
| 7982 |
\atentry{acronym} terms instead of \atentry{index}. |
| 7983 |
As with \atentry{acronym}, the \field{short} and \field{long} |
| 7984 |
fields are required. |
| 7985 |
|
| 7986 |
The \glspl{mainentry} are defined in the |
| 7987 |
\ext{glstex} file with \gls{bibglsnewspawnacronym} and the |
| 7988 |
\glspl{spawnedentry} are defined with \gls{bibglsnewspawnedacronym}. |
| 7989 |
|
| 7990 |
\entrysection{spawnsymbol} |
| 7991 |
|
| 7992 |
As \atentry{progenitor}, except that it creates |
| 7993 |
\atentry{symbol} terms instead of \atentry{index}. |
| 7994 |
As with \atentry{symbol}, the required fields are \field{name} or |
| 7995 |
\field{parent}, and the \field{description} field is required if the |
| 7996 |
\field{name} field is missing. |
| 7997 |
|
| 7998 |
The \glspl{mainentry} are defined in the |
| 7999 |
\ext{glstex} file with \gls{bibglsnewspawnsymbol} and the |
| 8000 |
\glspl{spawnedentry} are defined with \gls{bibglsnewspawnedsymbol}. |
| 8001 |
|
| 8002 |
\entrysection{spawnnumber} |
| 8003 |
|
| 8004 |
As \atentry{progenitor}, except that it creates |
| 8005 |
\atentry{number} terms instead of \atentry{index}. |
| 8006 |
As with \atentry{number}, the required fields are \field{name} or |
| 8007 |
\field{parent}, and the \field{description} field is required if the |
| 8008 |
\field{name} field is missing. |
| 8009 |
|
| 8010 |
The \glspl{mainentry} are defined in the |
| 8011 |
\ext{glstex} file with \gls{bibglsnewspawnnumber} and the |
| 8012 |
\glspl{spawnedentry} are defined with \gls{bibglsnewspawnednumber}. |
| 8013 |
|
| 8014 |
\entrysection{spawndualindexentry} |
| 8015 |
|
| 8016 |
As \atentry{progenitor}, except that the \glsdisp{mainentry}{main} (\gls{progenitor}) |
| 8017 |
entry behaves like \atentry{dualindexentry}. The spawned |
| 8018 |
\gls{progeny} behave like \atentry{index} are so are all considered |
| 8019 |
\glspl{primaryentry}. The \field{adoptparents} field should therefore reference |
| 8020 |
\glspl{primaryentry} with the default \csopt[parent]{adopted-parent-field}. |
| 8021 |
|
| 8022 |
The \glsdisp{mainentry}{main} \primary\ and |
| 8023 |
\glsdisp{secondaryentry}{secondary} (\dual) entries are defined in |
| 8024 |
the \ext{glstex} file with \gls{bibglsnewspawndualindexentry} and |
| 8025 |
\gls{bibglsnewspawndualindexentrysecondary}. The spawned |
| 8026 |
\gls{progeny} are defined with \gls{bibglsnewspawnedindex}. |
| 8027 |
|
| 8028 |
\chapter{Resource File Options} |
| 8029 |
\label{sec:resourceopts} |
| 8030 |
|
| 8031 |
Make sure that you use \isty{glossaries-extra} with the |
| 8032 |
\styopt{record} package option. This ensures that \bibgls\ can pick |
| 8033 |
up the required information from the \iext{aux} file, and both |
| 8034 |
\styopt[only]{record} and \styopt[nameref]{record} additionally |
| 8035 |
load the supplementary \isty{glossaries-extra-bib2gls} package. |
| 8036 |
These two \styopt{record} option values also |
| 8037 |
switch on the \styopt[none]{sort} package option (if you have a new |
| 8038 |
enough version of the base \isty{glossaries} package), which means |
| 8039 |
that there's no attempt to assign or process the \field{sort} key if |
| 8040 |
it's omitted from \gls{newglossaryentry} (or similar commands). The |
| 8041 |
\field{sort} key will be provided by \bibgls\ for informational |
| 8042 |
purposes, but there's no need for \LaTeX\ to write it to any |
| 8043 |
external files (unless you use \styopt[hybrid]{record}, |
| 8044 |
in which case you need to prevent \bibgls\ from sorting using the |
| 8045 |
\csopt[none]{sort} resource option). |
| 8046 |
|
| 8047 |
The \iext{glstex} resource files created by \bibgls\ are loaded in |
| 8048 |
the document using: |
| 8049 |
\nosecformatdef{GlsXtrLoadResources} |
| 8050 |
You can have multiple \gls{GlsXtrLoadResources} commands within your |
| 8051 |
document. The associated data for each |
| 8052 |
resource file is called the \igls{resourceset} (see |
| 8053 |
\sectionref{sec:resourcesets}). |
| 8054 |
|
| 8055 |
There's a shortcut command: |
| 8056 |
\nosecformatdef{glsbibdata} |
| 8057 |
This simply does: |
| 8058 |
\begin{codeenv} |
| 8059 |
\gls{GlsXtrLoadResources}\oarg{\csopt[\margm{bib-list}]{src},\meta{options}} |
| 8060 |
\end{codeenv} |
| 8061 |
|
| 8062 |
Note that the older command \inlinedef{glsxtrresourcefile} is deprecated |
| 8063 |
as from \sty{glossaries-extra} v1.55 because it has the potential to cause |
| 8064 |
a filename clash. If you actually intend to share |
| 8065 |
\glspl{resourceset}\dash as opposed to sharing \ext{bib} files\dash |
| 8066 |
across multiple documents then you need to use the \csopt{master} |
| 8067 |
resource option (see \sectionref{sec:master}). |
| 8068 |
|
| 8069 |
The optional argument \meta{options} is a comma-separated |
| 8070 |
\keyvallist. Allowed options are listed below. The option list |
| 8071 |
applies only to that specific \meta{filename}\ext{glstex} and are |
| 8072 |
not carried over to the next instance of \gls{GlsXtrLoadResources}. |
| 8073 |
Only the definitions provided in \atentry{preamble} (if the |
| 8074 |
interpreter is on and \csopt[true]{interpret-preamble}) are carried |
| 8075 |
over to the next resource set and, possibly, |
| 8076 |
\iglspl{crossresourceref} if permitted (see |
| 8077 |
\sectionref{sec:resourcesets}). The \sty{glossaries-extra} package |
| 8078 |
doesn't parse the options, but just writes the information to the |
| 8079 |
\ext{aux} file. This means that any invalid options will be reported |
| 8080 |
by \bibgls\ not by \sty{glossaries-extra}. |
| 8081 |
|
| 8082 |
As from \sty{glossaries-extra} v1.40 you can provide a default set |
| 8083 |
of options by redefining: |
| 8084 |
\nosecdef{GlsXtrDefaultResourceOptions} |
| 8085 |
This command will be inserted at the start of the options list for |
| 8086 |
all resource commands (and will expand as it's written to |
| 8087 |
the \ext{aux} file). For example: |
| 8088 |
\begin{codeenv} |
| 8089 |
\cs{renewcommand}\marg{\gls{GlsXtrDefaultResourceOptions}}\marg{\comment{} |
| 8090 |
\csopt[all]{selection},\csopt[entries]{src}} |
| 8091 |
\gls{GlsXtrLoadResources}\oarg{ |
| 8092 |
\csopt[symbols]{type}, |
| 8093 |
\csopt[entrytype=symbol]{match}} |
| 8094 |
\gls{GlsXtrLoadResources}\oarg{ |
| 8095 |
\csopt[abbreviations]{type}, |
| 8096 |
\csopt[entrytype=abbreviation]{match}} |
| 8097 |
\end{codeenv} |
| 8098 |
This acts like: |
| 8099 |
\begin{codeenv} |
| 8100 |
\gls{GlsXtrLoadResources}\oarg{ |
| 8101 |
\csopt[all]{selection},\csopt[entries]{src}, |
| 8102 |
\csopt[symbols]{type}, |
| 8103 |
\csopt[entrytype=symbol]{match}} |
| 8104 |
\gls{GlsXtrLoadResources}\oarg{ |
| 8105 |
\csopt[all]{selection},\csopt[entries]{src}, |
| 8106 |
\csopt[abbreviations]{type}, |
| 8107 |
\csopt[entrytype=abbreviation]{match}} |
| 8108 |
\end{codeenv} |
| 8109 |
|
| 8110 |
If you have multiple \ext{bib} files you can either select them all |
| 8111 |
using \csopt[\meta{bib list}]{src} in a single |
| 8112 |
\gls{GlsXtrLoadResources} call, if they all require the same settings, |
| 8113 |
or you can load them separately with different settings applied. |
| 8114 |
|
| 8115 |
For example, if the files \filefmt{entries-terms.bib} and |
| 8116 |
\filefmt{entries-symbols.bib} have the same settings: |
| 8117 |
\begin{codeenv} |
| 8118 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries-terms,entries-symbols]{src}} |
| 8119 |
\end{codeenv} |
| 8120 |
Alternatively, if they have different settings: |
| 8121 |
\begin{codeenv} |
| 8122 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries-terms]{src},\csopt[main]{type}} |
| 8123 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries-symbols]{src},\csopt[use]{sort},\csopt[symbols]{type}} |
| 8124 |
\end{codeenv} |
| 8125 |
|
| 8126 |
Note that the sorting is applied to each \igls{resourceset} independently |
| 8127 |
of other \iglspl{resourceset}. This means that if you have multiple instances |
| 8128 |
of \gls{GlsXtrLoadResources} but only one glossary type, the glossary |
| 8129 |
will effectively contain blocks of sorted entries. For example, if |
| 8130 |
\filefmt{file1.bib} contains: |
| 8131 |
\begin{codeenv} |
| 8132 |
\atentry{index}\marg{duck} |
| 8133 |
\atentry{index}\marg{zebra} |
| 8134 |
\atentry{index}\marg{aardvark} |
| 8135 |
\end{codeenv} |
| 8136 |
and \filefmt{file2.bib} contains: |
| 8137 |
\begin{codeenv} |
| 8138 |
\atentry{index}\marg{caterpillar} |
| 8139 |
\atentry{index}\marg{bee} |
| 8140 |
\atentry{index}\marg{wombat} |
| 8141 |
\end{codeenv} |
| 8142 |
then |
| 8143 |
\begin{codeenv} |
| 8144 |
\gls{GlsXtrLoadResources}\oarg{\csopt[file1,file2]{src}} |
| 8145 |
\end{codeenv} |
| 8146 |
will result in the list: aardvark, bee, caterpillar, duck, wombat, |
| 8147 |
zebra. These six entries are all defined when |
| 8148 |
\csfmt{jobname}\filefmt{.glstex} is read. |
| 8149 |
Whereas |
| 8150 |
\begin{codeenv} |
| 8151 |
\gls{GlsXtrLoadResources}\oarg{\csopt[file1]{src}} |
| 8152 |
\gls{GlsXtrLoadResources}\oarg{\csopt[file2]{src}} |
| 8153 |
\end{codeenv} |
| 8154 |
will result in the list: aardvark, duck, zebra, bee, caterpillar, |
| 8155 |
wombat. The first three (aardvark, duck, zebra) are defined when |
| 8156 |
\csfmt{jobname}\filefmt{.glstex} is read. The second three (bee, |
| 8157 |
caterpillar, wombat) are defined when \csfmt{jobname}\filefmt{-1.glstex} |
| 8158 |
is read. Since \ics{printunsrtglossary} simply iterates over all |
| 8159 |
defined entries, this is the ordering used. |
| 8160 |
|
| 8161 |
Abbreviation styles must be set (using \ics{setabbreviationstyle}) |
| 8162 |
before the resource command that selects the abbreviations from the |
| 8163 |
appropriate \ext{bib} file, since the entries are defined (through |
| 8164 |
\gls{newabbreviation} or \gls{newacronym}) when |
| 8165 |
\gls{GlsXtrLoadResources} inputs the \ext{glstex} file. (Similarly for any |
| 8166 |
associated abbreviation style commands that must be set before |
| 8167 |
abbreviations are defined, such as \cs{glsxtrlongshortdescname}.) |
| 8168 |
|
| 8169 |
Note \bibgls\ allows \iext{bib} files that don't provide any entries. |
| 8170 |
This can be used to provide commands in \atentry{preamble}. |
| 8171 |
For example, suppose I have \filefmt{defs.bib} that just contains: |
| 8172 |
\begin{codeenv} |
| 8173 |
\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{strong}}[1]\marg{\cs{textbf}\marg{\ics{cs.color}\marg{red}\idx{param}1}} |
| 8174 |
\cs{providecommand}\marg{\cmd{parenswap}}[2]\marg{\idx{param}2 (\idx{param}1)}}} |
| 8175 |
\end{codeenv} |
| 8176 |
This provides two commands: |
| 8177 |
\nosecdef{strong} |
| 8178 |
(which sets the font weight and colour) and |
| 8179 |
\nosecdef{parenswap} |
| 8180 |
(which just displays its second argument followed by the first in parentheses). |
| 8181 |
|
| 8182 |
Suppose I also have \filefmt{entries.bib} that contains: |
| 8183 |
\begin{codeenv} |
| 8184 |
\atentry{index}\marg{example, |
| 8185 |
\field{name}=\marg{\gls{strong}\marg{\gls{parenswap}\marg{stuff}\marg{example}}} |
| 8186 |
} |
| 8187 |
\atentry{index}\marg{sample} |
| 8188 |
\atentry{index}\marg{test} |
| 8189 |
\atentry{index}\marg{foo} |
| 8190 |
\atentry{index}\marg{bar} |
| 8191 |
\end{codeenv} |
| 8192 |
This contains an entry that requires the commands provided in |
| 8193 |
\filefmt{defs.bib}, so to ensure those commands are defined, I can |
| 8194 |
do: |
| 8195 |
\begin{codeenv} |
| 8196 |
\gls{GlsXtrLoadResources}\oarg{\csopt[defs,entries]{src}} |
| 8197 |
\end{codeenv} |
| 8198 |
Unfortunately this results in the sort value for \code{example} being |
| 8199 |
set to \code{redexample (stuff)} because the interpreter has |
| 8200 |
detected the provided commands and expanded: |
| 8201 |
\begin{codeenv} |
| 8202 |
\gls{strong}\marg{\gls{parenswap}\marg{stuff}\marg{example}} |
| 8203 |
\end{codeenv} |
| 8204 |
to: |
| 8205 |
\begin{codeenv} |
| 8206 |
\cs{textbf}\marg{\cs{cs.color}\marg{red}example (stuff)} |
| 8207 |
\end{codeenv} |
| 8208 |
It discards font changes, so \cs{textbf} is ignored, but it doesn't |
| 8209 |
recognise \cs{cs.color} and so doesn't know that the first argument is |
| 8210 |
just the colour specifier and therefore doesn't discard it. |
| 8211 |
This means that \qt{\textbf{\color{red}example (stuff)}} is placed |
| 8212 |
between \qt{foo} and \qt{sample} instead of between \qt{bar} and |
| 8213 |
\qt{foo}. |
| 8214 |
|
| 8215 |
I can prevent the interpreter from parsing \atentry{preamble}: |
| 8216 |
\begin{codeenv} |
| 8217 |
\gls{GlsXtrLoadResources}\oarg{\csopt[defs,entries]{src},\csopt[false]{interpret-preamble}} |
| 8218 |
\end{codeenv} |
| 8219 |
Now when the sort value for \code{example} is obtained from: |
| 8220 |
\begin{codeenv} |
| 8221 |
\gls{strong}\marg{\gls{parenswap}\marg{stuff}\marg{example}} |
| 8222 |
\end{codeenv} |
| 8223 |
no expansion occurs (since \gls{strong} and \gls{parenswap} are now |
| 8224 |
unrecognised) so the sort value ends up as: |
| 8225 |
\code{stuffexample} |
| 8226 |
which places \qt{\textbf{\color{red}example (stuff)}} between |
| 8227 |
\qt{sample} and \qt{test}, which is again incorrect. |
| 8228 |
|
| 8229 |
The best thing to do in this situation is to split the provided |
| 8230 |
commands into two \iext{bib} files: one that shouldn't be interpreted |
| 8231 |
and one that should. |
| 8232 |
|
| 8233 |
For example, \filefmt{defs-nointerpret.bib}: |
| 8234 |
\begin{codeenv} |
| 8235 |
\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\gls{strong}}[1]\marg{\cs{textbf}\marg{\cs{cs.color}\marg{red}\idx{param}1}}}} |
| 8236 |
\end{codeenv} |
| 8237 |
and \filefmt{defs-interpret.bib}: |
| 8238 |
\begin{codeenv} |
| 8239 |
\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\gls{parenswap}}[2]\marg{\idx{param}2 (\idx{param}1)}}} |
| 8240 |
\end{codeenv} |
| 8241 |
Now the first one can be loaded with \csopt[false]{interpret-preamble}: |
| 8242 |
\begin{codeenv} |
| 8243 |
\gls{GlsXtrLoadResources}\oarg{\csopt[defs-nointerpret]{src},\csopt[false]{interpret-preamble}} |
| 8244 |
\end{codeenv} |
| 8245 |
This creates a \iext{glstex} file that provides \gls{strong} but |
| 8246 |
doesn't define any entries. The other file \filefmt{defs-interpret.bib} can |
| 8247 |
then be loaded with the default \csopt[true]{interpret-preamble}: |
| 8248 |
\begin{codeenv} |
| 8249 |
\gls{GlsXtrLoadResources}\oarg{\csopt[defs-interpret,entries]{src}} |
| 8250 |
\end{codeenv} |
| 8251 |
The provided commands are remembered by the interpreter, so you can |
| 8252 |
also do: |
| 8253 |
\begin{codeenv} |
| 8254 |
\gls{GlsXtrLoadResources}\oarg{\csopt[defs-interpret]{src}} |
| 8255 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}} |
| 8256 |
\end{codeenv} |
| 8257 |
The \emph{contents} of \atentry{preamble} are only written to the |
| 8258 |
associated \iext{glstex} file, but the definitions contained within |
| 8259 |
the \atentry{preamble} are retained by the interpreter for subsequent |
| 8260 |
\iglspl{resourceset}. |
| 8261 |
|
| 8262 |
\section{String Concatenation} |
| 8263 |
\label{sec:optstringconcat} |
| 8264 |
|
| 8265 |
Some resource options allow string \gls{concatenation} in their |
| 8266 |
syntax. This is where fragments or substrings can be joined together |
| 8267 |
to form a value. This is similar to the way \gls{concatenation} |
| 8268 |
occurs in \ext{bib} files, but a different operator is used. In |
| 8269 |
\ext{bib} files, the concatenation operator is \idx{stringconcat} (hash) |
| 8270 |
but, since this is a problematic character to use in the optional |
| 8271 |
argument of \gls{GlsXtrLoadResources}, the operator for string |
| 8272 |
\gls{concatenation} in resource options is \idx{concat-plus} (plus). |
| 8273 |
|
| 8274 |
A string \gls{concatenation} \meta{element-list} in a resource option |
| 8275 |
has the following syntax: |
| 8276 |
\begin{codeenv} |
| 8277 |
\meta{element-list} ::= \meta{element-value} | \meta{element-value} \idx{concat-plus} \meta{element-list} |
| 8278 |
\meta{element-value} ::= \meta{string} | \meta{field-ref} | \meta{element-quark}\margm{element-list} | \meta{match-ref} |
| 8279 |
\meta{match-ref} ::= \gls{MGP}\margm{group-ref} |
| 8280 |
\meta{group-ref} ::= \meta{index} | \meta{name} |
| 8281 |
\meta{string} ::= \qtdelim{\meta{tokens}} | \margm{tokens} |
| 8282 |
\end{codeenv} |
| 8283 |
The \meta{field-ref} syntax is described below in \sectionref{sec:fieldref}, and is used to |
| 8284 |
reference a field value. |
| 8285 |
The element quarks (\meta{element-quark}, described below in |
| 8286 |
\sectionref{sec:elementquarks}) take an |
| 8287 |
\meta{element-list} argument. If the \meta{element-list} argument evaluates |
| 8288 |
to null, they will return null. |
| 8289 |
|
| 8290 |
\begin{important} |
| 8291 |
Remember that the argument of \gls{GlsXtrLoadResources} is expanded |
| 8292 |
as it's written to the \ext{aux} file. This means that care must be |
| 8293 |
taken to prevent premature expansion of \idxpl{quark} or any |
| 8294 |
commands that need to be present in a string. |
| 8295 |
\end{important} |
| 8296 |
|
| 8297 |
As from \styfmt{glossaries-extra} v1.51, the |
| 8298 |
\sty{glossaries-extra-bib2gls} package (which is automatically |
| 8299 |
loaded with the \styopt{record} option) provides the command |
| 8300 |
\ics{GlsXtrResourceInitEscSequences} which will locally redefine |
| 8301 |
these \idx{quark} commands to expand to their detokenized form. |
| 8302 |
So you can do: |
| 8303 |
\begin{codeenv} |
| 8304 |
\cs{renewcommand}*\marg{\cs{glsxtrresourceinit}}\marg{\comment{} |
| 8305 |
\ics{GlsXtrResourceInitEscSequences} |
| 8306 |
} |
| 8307 |
\end{codeenv} |
| 8308 |
This means that you can simply write the \idx{quark} in the resource |
| 8309 |
option without needing to use \ics{protect} or \idx{cs.string}. |
| 8310 |
The remainder of this section assumes that \ics{glsxtrresourceinit} |
| 8311 |
has been redefined to use \ics{GlsXtrResourceInitEscSequences}, as |
| 8312 |
in the above example. |
| 8313 |
|
| 8314 |
As with the \ext{bib} format, strings (\meta{string}) can be delimited by braces |
| 8315 |
\code{\margm{text}} or double-quotes \code{\qtdelim{\meta{text}}}. If you |
| 8316 |
need a literal double-quote (\idx{doublequotechar}) then either use |
| 8317 |
brace delimiters or use \gls{quark.doublequote}. If you need the |
| 8318 |
actual \LaTeX\ accent command \ics{umlaut} then use brace |
| 8319 |
delimiters. If you need braces that start and end in different |
| 8320 |
strings then use double-quote delimiters. For example: |
| 8321 |
\begin{codeenv} |
| 8322 |
\csopt[ |
| 8323 |
\field{first} = "\gls{cs}\marg{emph}\idx{bgroupchar}" \idx{concat-plus} \field{name} \idx{concat-plus} "\idx{egroupchar}" |
| 8324 |
]{assign-fields} |
| 8325 |
\end{codeenv} |
| 8326 |
|
| 8327 |
The \meta{element-list} may just contain a single element, such as a |
| 8328 |
field reference or a constant string, but it must still conform to |
| 8329 |
the element syntax. For example, if you want to use |
| 8330 |
\csopt{copy-to-glossary} to copy all entries to a specific glossary, |
| 8331 |
such as \code{index}, then you will need to markup \code{index} as a |
| 8332 |
string. For example: |
| 8333 |
\begin{codeenv} |
| 8334 |
\csopt[\qtdelim{index}]{copy-to-glossary} |
| 8335 |
\end{codeenv} |
| 8336 |
or |
| 8337 |
\begin{codeenv} |
| 8338 |
\csopt[\marg{index}]{copy-to-glossary} |
| 8339 |
\end{codeenv} |
| 8340 |
Note that the outer braces are stripped by the resource option |
| 8341 |
parser before the content is parsed as an \meta{element-list}. |
| 8342 |
If only a single set of braces was used, those braces would be |
| 8343 |
stripped leaving a bare \code{index}, which would be parsed as a |
| 8344 |
field reference. |
| 8345 |
|
| 8346 |
\subsection{Element Quarks} |
| 8347 |
\label{sec:elementquarks} |
| 8348 |
|
| 8349 |
The element \idxpl{quark} are uppercase tokens that start with a leading |
| 8350 |
backslash. They have no meaning to \bibgls's interpreter nor are |
| 8351 |
they defined in the \LaTeX\ document outside of the scope of |
| 8352 |
the resource command (unless they happen to coincidentally be |
| 8353 |
defined by another package or are a custom command). \Idxpl{quark} |
| 8354 |
occur outside of strings. Any escape sequences occurring within a |
| 8355 |
string are considered to be \LaTeX\ commands. |
| 8356 |
|
| 8357 |
\nosecdef{CS} |
| 8358 |
Returns a control sequence with the control sequence |
| 8359 |
name obtained from concatenating \meta{element-list}. |
| 8360 |
Note that this is different from |
| 8361 |
\gls{cs} which expands to the detokenized control sequence name as |
| 8362 |
the resource options are written to the \ext{aux} file. |
| 8363 |
|
| 8364 |
For example, if the \LaTeX\ file has: |
| 8365 |
\begin{codeenv} |
| 8366 |
\gls{GlsXtrLoadResources}\oarg{ |
| 8367 |
\csopt[ |
| 8368 |
\field{name} = "\gls{cs}\marg{foo}\marg{" \idx{concat-plus} \field{user1} \idx{concat-plus} "}" |
| 8369 |
]{assign-fields} |
| 8370 |
} |
| 8371 |
\end{codeenv} |
| 8372 |
then this will expand the options to the \ext{aux} file as |
| 8373 |
\begin{codeenv} |
| 8374 |
\csopt[ |
| 8375 |
\field{name} = "\csfmt{foo}\marg{" \idx{concat-plus} \field{user1} \idx{concat-plus} "}" |
| 8376 |
]{assign-fields} |
| 8377 |
\end{codeenv} |
| 8378 |
Compare this with: |
| 8379 |
\begin{codeenv} |
| 8380 |
\gls{GlsXtrLoadResources}\oarg{ |
| 8381 |
\csopt[ |
| 8382 |
\field{name} = \gls{CS} \marg{ \field{user1} } |
| 8383 |
]{assign-fields} |
| 8384 |
} |
| 8385 |
\end{codeenv} |
| 8386 |
which will set the \field{name} value to \csfmt{\meta{csname}} (no |
| 8387 |
arguments) where \meta{csname} is the value obtained from the |
| 8388 |
\field{user1} field for that entry. Note that \csfmt{\meta{csname}} |
| 8389 |
will need to be defined in the document to ensure that the document |
| 8390 |
compiles without error but will also need to be recognised by |
| 8391 |
\bibgls\ if the field value needs to be interpreted (such as when |
| 8392 |
obtaining the \field{sort} value). |
| 8393 |
|
| 8394 |
\nosecdef{MGP} |
| 8395 |
The \meta{match-ref} element should only be used with a |
| 8396 |
\gls{regular-expression} from an associated conditional (see |
| 8397 |
\sectionref{sec:conditionals}). |
| 8398 |
For example, the \meta{condition} part of an assignment rule in |
| 8399 |
\csopt{assign-fields}. |
| 8400 |
|
| 8401 |
If a match was found, \gls{MGP} can be used to reference a group within the match. |
| 8402 |
The \meta{group-ref} argument may be either an integer (the group |
| 8403 |
index) or the group name. For example, suppose a custom field called |
| 8404 |
\fieldfmt{ordinal} may contain content such as \code{1st} or |
| 8405 |
\code{10th} and I want to encapsulate the suffix part without |
| 8406 |
altering the \ext{bib} file. This can be done as follows: |
| 8407 |
\begin{codeenv} |
| 8408 |
\csopt[ |
| 8409 |
\fieldfmt{ordinal} =\oarg{o} \gls{MGP}\marg{1} + " \gls{cs}\marg{ord}\marg{" + \gls{MGP}\marg{2} + "}" |
| 8410 |
\oarg{ ordinal=/(\gls{cs}\marg{d}+)(st|nd|rd|th)/ } |
| 8411 |
]{assign-fields} |
| 8412 |
\end{codeenv} |
| 8413 |
Alternatively, using named groups: |
| 8414 |
\begin{codeenv*} |
| 8415 |
\csopt[ |
| 8416 |
ordinal =\oarg{o} \gls{MGP}\marg{num} + " \gls{cs}\marg{ord}\marg{" + \gls{MGP}\marg{suffix} + "}" |
| 8417 |
\oarg{ ordinal=/(\idx{regex.question}\idx{regex.lt}num\idx{regex.gt}\gls{cs}\marg{d}+)(\idx{regex.question}\idx{regex.lt}suffix\idx{regex.gt}st|nd|rd|th)/ } |
| 8418 |
]{assign-fields} |
| 8419 |
\end{codeenv*} |
| 8420 |
Note that the group name shouldn't be delimited with double-quotes. |
| 8421 |
|
| 8422 |
\begin{important} |
| 8423 |
The \gls{MGP} quark (which expands to the \gls{MGP} identifier for |
| 8424 |
\csopt{assign-fields}) isn't the same as \ics{glscapturedgroup} |
| 8425 |
(which expands to \cs{cs.string}\idx{dollarchar}, allowing a dollar |
| 8426 |
character to be written to the \ext{aux} file within |
| 8427 |
the replacement part of \csopt{labelify-replace}). |
| 8428 |
\end{important} |
| 8429 |
|
| 8430 |
\nosecdef{TRIM} |
| 8431 |
Returns its argument with any leading and trailing spaces removed. |
| 8432 |
|
| 8433 |
\nosecdef{INTERPRET} |
| 8434 |
Interprets the contents of \meta{element-list} using \bibgls's |
| 8435 |
interpreter and returns the result, which may be an empty string if |
| 8436 |
the content only contains unknown commands. Note that the result is |
| 8437 |
a string with any special characters replaced by detokenized commands, such as |
| 8438 |
\ics{glsbackslash}. This ensures that the value is suitable to be written |
| 8439 |
in the entry definition in the \ext{glstex} file. |
| 8440 |
|
| 8441 |
It's important to remember that the result of \gls{INTERPRET} is a detokenized string. |
| 8442 |
In general, it's therefore best to have \gls{INTERPRET} as the outermost quark. |
| 8443 |
|
| 8444 |
Suppose I have a \ext{bib} file that contains: |
| 8445 |
\begin{codeenv} |
| 8446 |
\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{csfmt}}[1]\marg{\cs{glsbackslash} \idx{param}1}}} |
| 8447 |
\atentry{index}\marg{relax,\field{name}=\marg{\cmd{csfmt}\marg{relax}}} |
| 8448 |
\atentry{index}\marg{comment,\field{name}=\marg{\cs{cs.percent} comment}} |
| 8449 |
\end{codeenv} |
| 8450 |
If the resource options include: |
| 8451 |
\begin{codeenv} |
| 8452 |
\csopt[ |
| 8453 |
\field{user1} = \gls{INTERPRET} \marg{ \field{name} } , |
| 8454 |
]{assign-fields} |
| 8455 |
\end{codeenv} |
| 8456 |
Then the definitions in the \ext{glstex} file will be: |
| 8457 |
\begin{codeenv} |
| 8458 |
\gls{bibglsnewindex}\marg{comment}\comment{} |
| 8459 |
\marg{\field{user1}=\marg{\cs{glspercentchar} \cs{space} comment}, |
| 8460 |
\field{name}=\marg{\cs{cs.percent} comment}, |
| 8461 |
\field{sort}=\marg{comment|}} |
| 8462 |
\strut |
| 8463 |
\gls{bibglsnewindex}\marg{relax}\comment{} |
| 8464 |
\marg{\field{user1}=\marg{\cs{glsbackslash} relax}, |
| 8465 |
\field{name}=\marg{\cmd{csfmt}\marg{relax}}, |
| 8466 |
\field{sort}=\marg{relax|}} |
| 8467 |
\end{codeenv} |
| 8468 |
This ensures that the \LaTeX\ syntax in the \ext{glstex} definitions is valid and |
| 8469 |
the \field{user1} field can expand to a literal string. (Remember that the document |
| 8470 |
definition of the custom \csfmt{csfmt} command may be different from the one provided |
| 8471 |
in the \atentry{preamble} content.) |
| 8472 |
|
| 8473 |
The \gls{INTERPRET} quark converts \code{\cs{cs.percent} comment} to |
| 8474 |
\qtt{\% comment} since the interpreter recognises \ics{cs.percent}. However, |
| 8475 |
if this value is written to the \ext{glstex} file: |
| 8476 |
\begin{codeenv} |
| 8477 |
\field{user1}=\marg{\% comment}, |
| 8478 |
\end{codeenv} |
| 8479 |
then this is invalid. When the \ext{glstex} file is input by \gls{GlsXtrLoadResources}, |
| 8480 |
\LaTeX\ will interpret the percent symbol \code{\%} as a comment and the rest of the |
| 8481 |
line, including the closing brace, will be ignored. This leads to a missing closing brace error. |
| 8482 |
|
| 8483 |
In the case of the \qt{relax} entry, since a definition of the custom \csfmt{csfmt} |
| 8484 |
is provided in \atentry{preamble}, the interpreter will convert \code{\csfmt{csfmt}\marg{relax}} |
| 8485 |
to the string \qtt{\csfmt{relax}}. If this value is written to the \ext{glstex} file: |
| 8486 |
\begin{codeenv} |
| 8487 |
\field{user1}=\marg{\csfmt{relax}}, |
| 8488 |
\end{codeenv} |
| 8489 |
then this would be parsed as the command \csfmt{relax} when the file is input |
| 8490 |
by \gls{GlsXtrLoadResources}. |
| 8491 |
|
| 8492 |
Therefore, \gls{INTERPRET} automatically replaces all the \TeX\ special characters |
| 8493 |
in the resulting string to ensure that they expand to their literal meanings |
| 8494 |
in the \LaTeX\ document. |
| 8495 |
|
| 8496 |
Now suppose instead that the resource options include: |
| 8497 |
\begin{codeenv} |
| 8498 |
\csopt[ |
| 8499 |
\field{user1} = \gls{FIRSTUC} \marg{ \gls{INTERPRET} \marg{ \field{name} } }, |
| 8500 |
]{assign-fields} |
| 8501 |
\end{codeenv} |
| 8502 |
This first interprets the value of the \field{name} field and substitutes the special |
| 8503 |
characters (so \code{\csfmt{relax}} becomes the string \qtt{\csfmt{glsbackslash} relax}). |
| 8504 |
The resulting string is then converted to \idx{sentencecase}, which results in |
| 8505 |
\qtt{\csfmt{Glsbackslash} relax} because the initial backslash is now a literal character, |
| 8506 |
and since it's a non-letter character it's skipped by the case-conversion. |
| 8507 |
So now the code written to the \ext{glstex} file is: |
| 8508 |
\begin{codeenv} |
| 8509 |
\gls{bibglsnewindex}\marg{comment}\comment{} |
| 8510 |
\marg{\field{user1}=\marg{\csfmt{Glspercentchar} \cs{space} comment}, |
| 8511 |
\field{name}=\marg{\cs{cs.percent} comment}, |
| 8512 |
\field{sort}=\marg{comment|}} |
| 8513 |
\strut |
| 8514 |
\gls{bibglsnewindex}\marg{relax}\comment{} |
| 8515 |
\marg{\field{user1}=\marg{\csfmt{Glsbackslash} relax}, |
| 8516 |
\field{name}=\marg{\cmd{csfmt}\marg{relax}}, |
| 8517 |
\field{sort}=\marg{relax|}} |
| 8518 |
\end{codeenv} |
| 8519 |
This is invalid because \csfmt{Glspercentchar} and \csfmt{Glsbackslash} are not defined. |
| 8520 |
|
| 8521 |
Suppose the order of the quarks is swapped: |
| 8522 |
\begin{codeenv} |
| 8523 |
\csopt[ |
| 8524 |
\field{user1} = \gls{INTERPRET} \marg{ \gls{FIRSTUC} \marg{ \field{name} } }, |
| 8525 |
]{assign-fields} |
| 8526 |
\end{codeenv} |
| 8527 |
This results in valid \LaTeX\ code: |
| 8528 |
\begin{codeenv} |
| 8529 |
\gls{bibglsnewindex}\marg{comment}\comment{} |
| 8530 |
\marg{\field{user1}=\marg{\cs{glspercentchar} \cs{space} comment}, |
| 8531 |
\field{name}=\marg{\cs{cs.percent} comment}, |
| 8532 |
\field{sort}=\marg{comment|}} |
| 8533 |
\strut |
| 8534 |
\gls{bibglsnewindex}\marg{relax}\comment{} |
| 8535 |
\marg{\field{user1}=\marg{\cs{glsbackslash} Relax}, |
| 8536 |
\field{name}=\marg{\cmd{csfmt}\marg{relax}}, |
| 8537 |
\field{sort}=\marg{relax|}} |
| 8538 |
\end{codeenv} |
| 8539 |
If you don't want the argument of a command to be affected by case-changing |
| 8540 |
commands, you can use \ics{MFUblocker} or \ics{MFUexcl}. The |
| 8541 |
\sty{glossaries-extra} package writes this information in the \ext{aux} |
| 8542 |
file for the benefit of \bibgls. See the \sty{mfirstuc} |
| 8543 |
manual for further details of those commands. |
| 8544 |
|
| 8545 |
\nosecdef{INTERPRETNOREPL} |
| 8546 |
As \gls{INTERPRET} but doesn't replace special characters. |
| 8547 |
Consider an adjustment to the previous example: |
| 8548 |
\begin{codeenv} |
| 8549 |
\csopt[ |
| 8550 |
\field{user1} = \gls{FIRSTUC} \marg{ \gls{INTERPRETNOREPL} \marg{ \field{name} } }, |
| 8551 |
]{assign-fields} |
| 8552 |
\end{codeenv} |
| 8553 |
Now \code{\csfmt{csfmt}\marg{relax}} is converted into the literal string |
| 8554 |
\qtt{\csfmt{relax}} and then the case-conversion is performed, |
| 8555 |
which results in the literal string \qtt{\csfmt{Relax}} but this will become |
| 8556 |
an undefined command in the \ext{glstex} file: |
| 8557 |
\begin{codeenv} |
| 8558 |
\field{user1}=\marg{\csfmt{Relax}}, |
| 8559 |
\end{codeenv} |
| 8560 |
In the case of the \qt{comment} entry, \code{\cs{cs.percent} comment} will |
| 8561 |
be converted to the literal string \qtt{\% comment}, which will then have the case-conversion |
| 8562 |
applied, but the \ext{glstex} file will be invalid: |
| 8563 |
\begin{codeenv} |
| 8564 |
\field{user1}=\marg{\% Comment}, |
| 8565 |
\end{codeenv} |
| 8566 |
|
| 8567 |
\nosecdef{REPLACESPCHARS} |
| 8568 |
Detokenises and replaces special characters with commands like \ics{glsbackslash}. |
| 8569 |
For example: |
| 8570 |
\begin{codeenv} |
| 8571 |
\csopt[ |
| 8572 |
\field{user1} = \gls{REPLACESPCHARS} \marg{ |
| 8573 |
\gls{FIRSTUC} \marg{ \gls{INTERPRETNOREPL} \marg{ \field{name} } } }, |
| 8574 |
]{assign-fields} |
| 8575 |
\end{codeenv} |
| 8576 |
This rather long-winded assignment produces the same result as: |
| 8577 |
\begin{codeenv} |
| 8578 |
\csopt[ |
| 8579 |
\field{user1} = \gls{INTERPRET} \marg{ \gls{FIRSTUC} \marg{ \field{name} } }, |
| 8580 |
]{assign-fields} |
| 8581 |
\end{codeenv} |
| 8582 |
A difference can be observed if the custom command is made a blocker or exclusion |
| 8583 |
using \ics{MFUblocker} or \ics{MFUexcl}. |
| 8584 |
|
| 8585 |
\nosecdef{LABELIFY} |
| 8586 |
Converts the contents of \meta{element-list} into a label string, |
| 8587 |
according to the \csopt{labelify} criteria. |
| 8588 |
|
| 8589 |
\nosecdef{LABELIFYLIST} |
| 8590 |
Converts the contents of \meta{element-list} into a label-list string, |
| 8591 |
according to the \csopt{labelify-list} criteria. |
| 8592 |
|
| 8593 |
\nosecdef{LEN} |
| 8594 |
When used within an element list, \gls{LEN} returns the length of |
| 8595 |
its \meta{element-list} argument as a string or null if \meta{element-list} |
| 8596 |
evaluates to null. Note that this is different from using \gls{LEN} |
| 8597 |
in a numerical condition where the result is always an integer (see |
| 8598 |
\sectionref{sec:conditionals}). |
| 8599 |
This means that \code{\gls{LEN}\margm{list1} \idx{concat-plus} |
| 8600 |
\gls{LEN}\margm{list2}} performs string \gls{concatenation} not numerical |
| 8601 |
addition. Instead, use \code{\gls{LEN}\marg{\meta{list1} |
| 8602 |
\idx{concat-plus} \meta{list2}}} for the combined length. |
| 8603 |
|
| 8604 |
The length is the detokenised length, for example, |
| 8605 |
if the \field{name} field has the value \code{\cs{emph}\marg{x}} |
| 8606 |
then \code{\gls{LEN}\marg{\field{name}}} will evaluate to the string |
| 8607 |
\qtdelim{8}. You can use |
| 8608 |
\begin{codeenv} |
| 8609 |
\gls{LEN}\marg{\gls{INTERPRET}\margm{element-list}} |
| 8610 |
\end{codeenv} |
| 8611 |
to find the length without \LaTeX\ commands. |
| 8612 |
|
| 8613 |
The \idxpl{quark} below identify case-changing functions. The |
| 8614 |
\meta{element-list} argument will be converted using the appropriate |
| 8615 |
function and the result will be returned. If \meta{element-list} |
| 8616 |
evaluates to null then null will be returned. |
| 8617 |
|
| 8618 |
The case-changing functions will use the \gls{resource-locale}, but |
| 8619 |
whether or not \bibgls\ recognises the correct rules for the locale |
| 8620 |
depends on whether or not the locale is correctly supported by the |
| 8621 |
Java locale provider. The \langxml\ may provide assistance with |
| 8622 |
case-conversion (see \sectionref{sec:lang.xml}). Note that the |
| 8623 |
case-change is performed by \bibgls\ not by inserting \LaTeX\ |
| 8624 |
case-changing commands into the code. |
| 8625 |
|
| 8626 |
\begin{itemize} |
| 8627 |
\item \inlinedef{LC} converts \meta{element-list} to \idx{lowercase}; |
| 8628 |
\item \inlinedef{UC} converts \meta{element-list} to \idx{uppercase}; |
| 8629 |
\item \inlinedef{FIRSTLC} converts the first letter of |
| 8630 |
\meta{element-list} to \idx{lowercase}; |
| 8631 |
\item \inlinedef{FIRSTUC} converts the first letter of |
| 8632 |
\meta{element-list} to \idx{uppercase} (\idx{sentencecase}); |
| 8633 |
\item \inlinedef{TITLE} converts \meta{element-list} to \idx{titlecase}. |
| 8634 |
\end{itemize} |
| 8635 |
|
| 8636 |
There is an additional token \inlinedef{NOCHANGE} which simply |
| 8637 |
evaluates \meta{element-list} and returns it |
| 8638 |
unchanged.\footnote{The \gls{NOCHANGE} support wasn't |
| 8639 |
intentional, but was simply a by-product of the original |
| 8640 |
implementation of the case-changing commands.} This isn't |
| 8641 |
like \cs{NoCaseChange} but is more like \cs{@firstofone}. There is |
| 8642 |
little need for it so it's not defined by |
| 8643 |
\ics{GlsXtrResourceInitEscSequences}. The only plausible use for it |
| 8644 |
is if you have a class or package that contains something like: |
| 8645 |
\begin{codeenv} |
| 8646 |
\csfmt{newcommand}\marg{\csfmt{mycase}}\marg{NOCHANGE} |
| 8647 |
\comment{later as the result of some condition:} |
| 8648 |
\csfmt{renewcommand}\marg{\csfmt{mycase}}\marg{FIRSTUC} |
| 8649 |
\comment{later on:} |
| 8650 |
\gls{GlsXtrLoadResources}\oarg{ |
| 8651 |
\csopt[ |
| 8652 |
\field{name}=\oarg{o} \gls{cs}\marg{\csfmt{mycase}}\marg{\field{name}}, |
| 8653 |
\comment{other assignments \ldots} |
| 8654 |
]{assign-fields} |
| 8655 |
} |
| 8656 |
\end{codeenv} |
| 8657 |
In most cases, it should be possible to achieve the same result with a |
| 8658 |
conditional associated with the resource option or by adjusting the |
| 8659 |
content passed to the resource command. For example: |
| 8660 |
\begin{codeenv} |
| 8661 |
\csfmt{newcommand}\marg{\csfmt{nameassign}}\marg{} |
| 8662 |
\comment{later as the result of some condition:} |
| 8663 |
\csfmt{renewcommand}\marg{\csfmt{nameassign}}\marg{name=\oarg{o}\gls{FIRSTUC}\marg{name},} |
| 8664 |
\comment{later on:} |
| 8665 |
\gls{GlsXtrLoadResources}\oarg{ |
| 8666 |
\csopt[ |
| 8667 |
\csfmt{nameassign} |
| 8668 |
\comment{other assignments \ldots} |
| 8669 |
]{assign-fields} |
| 8670 |
} |
| 8671 |
\end{codeenv} |
| 8672 |
|
| 8673 |
\subsection{Field Reference} |
| 8674 |
\label{sec:fieldref} |
| 8675 |
|
| 8676 |
The \idx{field-reference} (\meta{field-ref}) syntax is more complicated: |
| 8677 |
\begin{codeenv} |
| 8678 |
\meta{field-ref} ::= \meta{value-ref} | \meta{entry-ref} \idx{follow} \meta{field-ref} |
| 8679 |
\meta{entry-ref} ::= self | parent | root |
| 8680 |
\meta{value-ref} ::= \meta{field-name} | \meta{label-ref} |
| 8681 |
\meta{label-ref} ::= \meta{label-type} \idx{follow} \meta{label-delineator} |
| 8682 |
\meta{label-type} ::= entrytype | entrylabel | entrybib |
| 8683 |
\meta{label-delineator} ::= original | actual |
| 8684 |
\end{codeenv} |
| 8685 |
where \meta{field-name} is the required field name. Note that field |
| 8686 |
names (which need to be used in a string \gls{concatenation}) can't include |
| 8687 |
any of the \gls{concatenation} or conditional markup special characters: |
| 8688 |
\idx{concat-plus} \idx{startoptional} \idx{endoptional} |
| 8689 |
\idx{equalsassign} \idx{commasep} \idx{ltcmp} \idx{gtcmp} or |
| 8690 |
\idx{doublequotechardelim}. |
| 8691 |
|
| 8692 |
The \meta{entry-ref} part indicates which entry the referenced field |
| 8693 |
belongs to. The keywords are: \code{self} (the entry itself), |
| 8694 |
\code{parent} (the entry's \parent), and \code{root} (the entry's |
| 8695 |
\glsdisp{hierarchicalglossary}{hierarchical root}, not including the |
| 8696 |
entry itself). Note that with options such as |
| 8697 |
\csopt{assign-fields} the entry's \glspl{ancestor} must be |
| 8698 |
defined before the entry in the \ext{bib} file because their fields |
| 8699 |
can only be referenced after they have been processed. A |
| 8700 |
grandparent entry can be referenced with \code{parent \idx{follow} |
| 8701 |
parent \idx{follow}}. Since \qt{parent} is also a field name, if |
| 8702 |
the keyword \code{parent} is followed by \idx{follow} then the |
| 8703 |
keyword refers to the \gls{parententry} otherwise it refers to the |
| 8704 |
\field{parent} field. For example, |
| 8705 |
\code{self \idx{follow} parent} refers to the value of the entry's |
| 8706 |
\field{parent} field, which is the \gls{parententry}['s] label, whereas |
| 8707 |
\code{parent \idx{follow} name} refers to the value of the entry's parent's |
| 8708 |
\field{name} field. |
| 8709 |
|
| 8710 |
|
| 8711 |
The special keywords identify values that aren't normally stored in |
| 8712 |
a field. The keyword must be followed by the \meta{delineator}, |
| 8713 |
which may be \code{original} or \code{actual}. Available keywords: |
| 8714 |
|
| 8715 |
\begin{description} |
| 8716 |
|
| 8717 |
\item[\code{entrytype}] the \gls{entrytype}, without the leading |
| 8718 |
\code{@}, where \code{original} refers to the original |
| 8719 |
\gls{entrytype} used in the \ext{bib} file and \code{actual} refers |
| 8720 |
to the actual \gls{entrytype}, which may have changed as a result of |
| 8721 |
\csopt{entry-type-aliases} (but remember that you can't match the |
| 8722 |
special entry types described in \sectionref{sec:specialentrytypes}); |
| 8723 |
|
| 8724 |
\item[\code{entrylabel}] the entry label, where \code{original} |
| 8725 |
refers to the original label used in the \ext{bib} file and |
| 8726 |
\code{actual} refers to the actual label, which may have been |
| 8727 |
altered by options such as \csopt{label-prefix}; |
| 8728 |
|
| 8729 |
\item[\code{entrybib}] the \ext{bib} file the entry was defined in, |
| 8730 |
where \code{original} refers to the basename (without the |
| 8731 |
\code{.bib} extension, regardless of whether or not it was included |
| 8732 |
in \csopt{src}) and \code{actual} refers to the file name |
| 8733 |
(including the extension and path). |
| 8734 |
|
| 8735 |
\end{description} |
| 8736 |
|
| 8737 |
If a syntax error occurs, the error message will show how \bibgls\ |
| 8738 |
has scanned the information so far. For example, in the case of |
| 8739 |
\code{\csopt[parent \field{name}]{assign-fields}} the message will be: |
| 8740 |
\begin{quote}\ttfamily |
| 8741 |
Error: Invalid syntax for option '\csopt{assign-fields}': Expected |
| 8742 |
one of \idx{follow} \idx{concat-plus} \idx{startoptional} after |
| 8743 |
' self \idx{follow} parent', found 'n' |
| 8744 |
\end{quote} |
| 8745 |
This indicates that it has read \qt{parent} as meaning the |
| 8746 |
\field{parent} field of the current entry since it isn't followed by |
| 8747 |
\qt{\idx{follow}}. |
| 8748 |
|
| 8749 |
\section{Complex Conditionals} |
| 8750 |
\label{sec:conditionals} |
| 8751 |
|
| 8752 |
Some options may have a conditional in their value. In certain |
| 8753 |
cases, such as \csopt{match}, the condition is provided as a |
| 8754 |
\gls{regular-expression}, but other conditionals (such as in |
| 8755 |
\csopt{assign-fields}) are complex. This section describes that |
| 8756 |
complex conditional syntax. |
| 8757 |
|
| 8758 |
For example, suppose you want to use \csopt{post-description-dot} |
| 8759 |
to automatically append a dot to descriptions but not to entries |
| 8760 |
that have been defined with \atentry{symbol} or \atentry{number}: |
| 8761 |
\begin{codeenv} |
| 8762 |
\csopt[check]{post-description-dot}, |
| 8763 |
\csopt[ |
| 8764 |
entrytype \idx{follow} original = \qtdelim{symbol} |
| 8765 |
\idx{pipeor} entrytype \idx{follow} original = \qtdelim{number} |
| 8766 |
]{post-description-dot-exclude} |
| 8767 |
\end{codeenv} |
| 8768 |
|
| 8769 |
The tokens \idx{ampand} and \idx{pipeor} indicate logical |
| 8770 |
\qt{AND} and \qt{OR}, respectively, and \idx{exclamnot} indicates |
| 8771 |
negation. Parentheses \idx{openparenchar} and \idx{closeparenchar} |
| 8772 |
may be used to control the order of precedence. For example, |
| 8773 |
\begin{codeenv} |
| 8774 |
\meta{boolean1} \idx{pipeor} (\meta{boolean2} \idx{ampand} \idx{exclamnot} \meta{boolean3}) |
| 8775 |
\end{codeenv} |
| 8776 |
|
| 8777 |
Available boolean functions are in the form: |
| 8778 |
\begin{codeenv} |
| 8779 |
\meta{value1} \meta{cmp} \meta{value2} |
| 8780 |
\end{codeenv} |
| 8781 |
where \meta{value1} is the left-hand value and \meta{value2} is the |
| 8782 |
right-hand value. The middle \meta{cmp} operator identifies the comparison |
| 8783 |
function. |
| 8784 |
|
| 8785 |
The left-hand \meta{value1} may be a field reference \meta{field-ref} or |
| 8786 |
the integer \idx{quark} \code{\gls{LEN}\margm{element-list}} or |
| 8787 |
the concatenate \idx{quark} \code{\gls{CAT}\margm{element-list}}, |
| 8788 |
where \meta{field-ref} references a field value and |
| 8789 |
\meta{element-list} is an element list, using the same |
| 8790 |
syntax described in \sectionref{sec:optstringconcat}. |
| 8791 |
|
| 8792 |
The right-hand \meta{value2} may be a field reference |
| 8793 |
\meta{field-ref} or \code{\gls{CAT}\margm{element-list}} or |
| 8794 |
\gls{NULL} or a constant string (\qtdelim{\meta{string}} or |
| 8795 |
\margm{string}) or a number or a \gls{regular-expression}. You can't |
| 8796 |
use \gls{LEN} on the right-hand as a numeric value (but it may occur |
| 8797 |
inside the argument \gls{CAT}). You can't use \gls{NULL} or a |
| 8798 |
\gls{regular-expression} on the left-hand side. |
| 8799 |
|
| 8800 |
Where \meta{value1} is \code{\gls{LEN}\margm{element-list}}, the length |
| 8801 |
evaluates to an integer and may only be used in the numerical |
| 8802 |
comparisons. If \meta{element-list} is null, then the length will be~0. |
| 8803 |
The \gls{LEN} \idx{quark} can't be used in the right hand |
| 8804 |
\meta{value2} part of a numerical comparison. Note that if \gls{LEN} |
| 8805 |
occurs inside the argument of \gls{CAT} then it becomes a string not |
| 8806 |
a number. |
| 8807 |
|
| 8808 |
\nosecdef{CAT} |
| 8809 |
Where \meta{value1} or \meta{value2} is \code{\gls{CAT}\margm{element-list}}, the |
| 8810 |
\meta{element-list} will be evaluated and treated as a string, which |
| 8811 |
will be null if \meta{element-list} evaluates to null. |
| 8812 |
|
| 8813 |
\nosecdef{NULL} |
| 8814 |
The null \idx{quark} may only be used as \meta{value2} for the |
| 8815 |
equality and inequality comparisons. It can't be used in any other |
| 8816 |
context. Note that the numeric \gls{LEN} doesn't return null. |
| 8817 |
|
| 8818 |
Where a field value is referenced (\meta{field-ref}), if the field |
| 8819 |
value is undefined (either the field isn't set or the referenced |
| 8820 |
ancestor entry hasn't been defined) then, if the designated action |
| 8821 |
is \qt{fallback} (for example, |
| 8822 |
\csopt[fallback]{assign-missing-field-action}), the fallback value |
| 8823 |
is obtained (see \sectionref{sec:fallbacks}). If the value is still |
| 8824 |
undefined it will be considered a null value for the purposes of the |
| 8825 |
comparison. Note that if the designated action is \qt{empty} (for |
| 8826 |
example, \csopt[empty]{assign-missing-field-action}) there will be |
| 8827 |
no null values. |
| 8828 |
|
| 8829 |
\begin{codeenv*} |
| 8830 |
\meta{value1}\idx{equalscmp}\gls{NULL} |
| 8831 |
\end{codeenv*} |
| 8832 |
Evaluates to true if \meta{value1} is null. |
| 8833 |
|
| 8834 |
\begin{codeenv*} |
| 8835 |
\meta{value1}\idx{notequalscmp}\gls{NULL} |
| 8836 |
\end{codeenv*} |
| 8837 |
Evaluates to true if \meta{value1} is not null. |
| 8838 |
|
| 8839 |
For the remaining comparisons, null values will be treated as an |
| 8840 |
empty string. Once the \meta{field-ref} or \gls{CAT} references have |
| 8841 |
been evaluated, their returned value will be turned into a |
| 8842 |
detokenized string for the purposes of the comparison. |
| 8843 |
|
| 8844 |
The detokenized values from a field reference may contain any TAB or |
| 8845 |
newline characters or additional spacing that are present in the |
| 8846 |
\ext{bib} file (unless they have already been stripped by other |
| 8847 |
resource options or field assignments). However, redundant spacing |
| 8848 |
in any literal strings (\qtdelim{\meta{string}} or \code{\margm{string}}) |
| 8849 |
are likely to be lost when the resource options are written to the |
| 8850 |
\ext{aux} file. |
| 8851 |
|
| 8852 |
\begin{codeenv} |
| 8853 |
\meta{value1}=\idx{slashchar}\meta{regex}\idx{slashchar} |
| 8854 |
\meta{value1}=\idx{slashchar}\meta{regex}\idx{slashchar}i |
| 8855 |
\end{codeenv} |
| 8856 |
Evaluates to true if the value matches the given \gls{anchored} |
| 8857 |
\gls{regular-expression} \meta{regex}. If \qtt{i} follows the terminating |
| 8858 |
\idx{slashchar} then the match is case-insensitive. No other modifiers |
| 8859 |
are recognised, but you can use embedded flag expressions, such as |
| 8860 |
\code{?s} for \qt{single-line} mode. |
| 8861 |
|
| 8862 |
In the following string comparisons, the right-hand \meta{string} is |
| 8863 |
a constant string that must be delimited with double-quotes or braces. The |
| 8864 |
comparisons are according to the Unicode code points (not |
| 8865 |
locale-sensitive), but if the string is followed by \qtt{i}, a |
| 8866 |
case-insensitive comparison is used. |
| 8867 |
|
| 8868 |
\begin{codeenv*} |
| 8869 |
\meta{value1}\idx{equalscmp}\meta{string} |
| 8870 |
\meta{value1}\idx{equalscmp}\meta{string}i |
| 8871 |
\end{codeenv*} |
| 8872 |
Evaluates to true if the value is equal to the string. |
| 8873 |
For example: |
| 8874 |
\begin{codeenv} |
| 8875 |
\field{category}\idx{equalscmp}\qtdelim{abbreviation} |
| 8876 |
\end{codeenv} |
| 8877 |
|
| 8878 |
\begin{codeenv*} |
| 8879 |
\meta{value1}\idx{notequalscmp}\meta{string} |
| 8880 |
\meta{value1}\idx{notequalscmp}\meta{string}i |
| 8881 |
\end{codeenv*} |
| 8882 |
Evaluates to true if the value is not equal to the string. |
| 8883 |
|
| 8884 |
\begin{codeenv*} |
| 8885 |
\meta{value1}\idx{ltcmp}\meta{string} |
| 8886 |
\meta{value1}\idx{ltcmp}\meta{string}i |
| 8887 |
\end{codeenv*} |
| 8888 |
Evaluates to true if the value is lexicographically less than the string. |
| 8889 |
|
| 8890 |
\begin{codeenv*} |
| 8891 |
\meta{value1}\idx{lecmp}\meta{string} |
| 8892 |
\meta{value1}\idx{lecmp}\meta{string}i |
| 8893 |
\end{codeenv*} |
| 8894 |
Evaluates to true if the value is lexicographically less than or |
| 8895 |
equal to the string. |
| 8896 |
|
| 8897 |
\begin{codeenv*} |
| 8898 |
\meta{value1}\idx{gtcmp}\meta{string} |
| 8899 |
\meta{value1}\idx{gtcmp}\meta{string}i |
| 8900 |
\end{codeenv*} |
| 8901 |
Evaluates to true if the value is lexicographically greater than the string. |
| 8902 |
|
| 8903 |
\begin{codeenv*} |
| 8904 |
\meta{value1}\idx{gecmp}\meta{string} |
| 8905 |
\meta{value1}\idx{gecmp}\meta{string}i |
| 8906 |
\end{codeenv*} |
| 8907 |
Evaluates to true if the value is lexicographically greater than or |
| 8908 |
equal to the string. |
| 8909 |
|
| 8910 |
In the following numerical comparisons, the given \meta{number} |
| 8911 |
should use \qtt{.} for the decimal point and no number group |
| 8912 |
separators. If the \meta{number} doesn't contain a decimal point or |
| 8913 |
if \meta{value1} is the \code{\gls{LEN}\margm{element-list}} quark |
| 8914 |
then an integer comparison is assumed. If \meta{value1} is |
| 8915 |
empty or isn't numeric it will be treated as 0. The number |
| 8916 |
shouldn't be delimited by quotes or braces. |
| 8917 |
|
| 8918 |
\begin{codeenv*} |
| 8919 |
\meta{value1}\idx{equalscmp}\meta{number} |
| 8920 |
\end{codeenv*} |
| 8921 |
Evaluates to true if the value is equal to \meta{number}. |
| 8922 |
For example: |
| 8923 |
\begin{codeenv} |
| 8924 |
\gls{LEN}\marg{\field{user1}}\idx{equalscmp}0.9 |
| 8925 |
\end{codeenv} |
| 8926 |
This will return true if the \field{user1} field length is 0 and |
| 8927 |
false otherwise. This is because \gls{LEN} enforces an integer |
| 8928 |
comparison which means that 0.9 is converted to 0. |
| 8929 |
Similarly: |
| 8930 |
\begin{codeenv} |
| 8931 |
\gls{CAT}\marg{\qtdelim{0.9}}\idx{equalscmp}0 |
| 8932 |
\end{codeenv} |
| 8933 |
This will return true because the \meta{number} 0 is an integer |
| 8934 |
which enforces an integer comparison so the string \qtdelim{0.9} |
| 8935 |
will be converted to the number~0. |
| 8936 |
Compare this with: |
| 8937 |
\begin{codeenv} |
| 8938 |
\gls{CAT}\marg{\qtdelim{0.9}}\idx{equalscmp}0.0 |
| 8939 |
\end{codeenv} |
| 8940 |
This will return false because the \meta{number} 0.0 is a decimal, |
| 8941 |
so a decimal comparison will be used. |
| 8942 |
|
| 8943 |
\begin{codeenv*} |
| 8944 |
\meta{value1}\idx{notequalscmp}\meta{number} |
| 8945 |
\end{codeenv*} |
| 8946 |
Evaluates to true if the value is not equal to \meta{number}. |
| 8947 |
|
| 8948 |
\begin{codeenv*} |
| 8949 |
\meta{value1}\idx{ltcmp}\meta{number} |
| 8950 |
\end{codeenv*} |
| 8951 |
Evaluates to true if the value is less than \meta{number}. |
| 8952 |
|
| 8953 |
\begin{codeenv*} |
| 8954 |
\meta{value1}\idx{lecmp}\meta{number} |
| 8955 |
\end{codeenv*} |
| 8956 |
Evaluates to true if the value is less than or equal to \meta{number}. |
| 8957 |
|
| 8958 |
\begin{codeenv*} |
| 8959 |
\meta{value1}\idx{gtcmp}\meta{number} |
| 8960 |
\end{codeenv*} |
| 8961 |
Evaluates to true if the value is greater than \meta{number}. |
| 8962 |
|
| 8963 |
\begin{codeenv*} |
| 8964 |
\meta{value1}\idx{gecmp}\meta{number} |
| 8965 |
\end{codeenv*} |
| 8966 |
Evaluates to true if the value is greater than or equal to \meta{number}. |
| 8967 |
|
| 8968 |
Finally, the following are string comparisons made after |
| 8969 |
evaluating and detokenizing both \meta{value1} and \meta{value2}. The |
| 8970 |
comparisons are case-sensitive and according to the Unicode code |
| 8971 |
points (not locale-sensitive). |
| 8972 |
|
| 8973 |
\begin{codeenv*} |
| 8974 |
\meta{value1}\idx{equalscmp}\meta{value2} |
| 8975 |
\end{codeenv*} |
| 8976 |
Evaluates to true if \meta{value1} is equal to \meta{value2}. |
| 8977 |
For example: |
| 8978 |
\begin{codeenv} |
| 8979 |
\field{name} \idx{equalscmp} parent \idx{follow} \field{name} |
| 8980 |
\end{codeenv} |
| 8981 |
|
| 8982 |
\begin{codeenv*} |
| 8983 |
\meta{value1}\idx{notequalscmp}\meta{value2} |
| 8984 |
\end{codeenv*} |
| 8985 |
Evaluates to true if \meta{value1} is not equal to \meta{value2}. |
| 8986 |
|
| 8987 |
\begin{codeenv*} |
| 8988 |
\meta{value1}\idx{ltcmp}\meta{value2} |
| 8989 |
\end{codeenv*} |
| 8990 |
Evaluates to true if \meta{value1} is lexicographically less than |
| 8991 |
\meta{value2}. |
| 8992 |
|
| 8993 |
\begin{codeenv*} |
| 8994 |
\meta{value1}\idx{lecmp}\meta{value2} |
| 8995 |
\end{codeenv*} |
| 8996 |
Evaluates to true if \meta{value1} is lexicographically less than or |
| 8997 |
equal to \meta{value2}. |
| 8998 |
|
| 8999 |
\begin{codeenv*} |
| 9000 |
\meta{value1}\idx{gtcmp}\meta{value2} |
| 9001 |
\end{codeenv*} |
| 9002 |
Evaluates to true if \meta{value1} is lexicographically greater than |
| 9003 |
\meta{value2}. |
| 9004 |
|
| 9005 |
\begin{codeenv*} |
| 9006 |
\meta{value1}\idx{gecmp}\meta{value2} |
| 9007 |
\end{codeenv*} |
| 9008 |
Evaluates to true if \meta{value} is lexicographically greater than or |
| 9009 |
equal to \meta{value2}. |
| 9010 |
|
| 9011 |
\begin{codeenv*} |
| 9012 |
\meta{value1} \inlinedef{IN} \meta{value2} |
| 9013 |
\end{codeenv*} |
| 9014 |
Evaluates to true if \meta{value1} is a substring of \meta{value2}. |
| 9015 |
If \meta{value1} is empty or null it's considered |
| 9016 |
not a substring regardless of the value of \meta{value2}. |
| 9017 |
|
| 9018 |
\begin{codeenv*} |
| 9019 |
\meta{value1} \inlinedef{NIN} \meta{value2} |
| 9020 |
\end{codeenv*} |
| 9021 |
The negation of the \gls{IN} test. Evaluates to true if \meta{value1} is |
| 9022 |
not a substring of \meta{value2}. This is equivalent to: |
| 9023 |
\begin{codeenv} |
| 9024 |
\idx{exclamnot} \meta{value1} \gls{IN} \meta{value2} |
| 9025 |
\end{codeenv} |
| 9026 |
|
| 9027 |
\begin{codeenv*} |
| 9028 |
\meta{value1} \inlinedef{PREFIXOF} \meta{value2} |
| 9029 |
\end{codeenv*} |
| 9030 |
Evaluates to true if \meta{value1} is a prefix of \meta{value2} |
| 9031 |
(that is, \meta{value2} starts with \meta{value1}). |
| 9032 |
If \meta{value1} is empty or null it's considered |
| 9033 |
not a prefix regardless of \meta{value2}. |
| 9034 |
|
| 9035 |
\begin{codeenv*} |
| 9036 |
\meta{value1} \inlinedef{NOTPREFIXOF} \meta{value2} |
| 9037 |
\end{codeenv*} |
| 9038 |
Evaluates to true if \meta{value1} is not a prefix of \meta{value2}. |
| 9039 |
This is equivalent to: |
| 9040 |
\begin{codeenv} |
| 9041 |
\idx{exclamnot} \meta{value1} \gls{PREFIXOF} \meta{value2} |
| 9042 |
\end{codeenv} |
| 9043 |
|
| 9044 |
\begin{codeenv*} |
| 9045 |
\meta{value1} \inlinedef{SUFFIXOF} \meta{value2} |
| 9046 |
\end{codeenv*} |
| 9047 |
Evaluates to true if \meta{value1} is a suffix of \meta{value2} |
| 9048 |
(that is, \meta{value2} ends with \meta{value1}). |
| 9049 |
If \meta{value1} is empty or null it's considered |
| 9050 |
not a suffix regardless of \meta{value2}. |
| 9051 |
|
| 9052 |
\begin{codeenv*} |
| 9053 |
\meta{value1} \inlinedef{NOTSUFFIXOF} \meta{value2} |
| 9054 |
\end{codeenv*} |
| 9055 |
Evaluates to true if \meta{value1} is not a suffix of \meta{value2}. |
| 9056 |
This is equivalent to: |
| 9057 |
\begin{codeenv} |
| 9058 |
\idx{exclamnot} \meta{value1} \gls{SUFFIXOF} \meta{value2} |
| 9059 |
\end{codeenv} |
| 9060 |
|
| 9061 |
|
| 9062 |
\section{General Options} |
| 9063 |
\label{sec:generalopts} |
| 9064 |
|
| 9065 |
\optsection{charset} |
| 9066 |
|
| 9067 |
If the character \igls{encoding} hasn't been supplied in the \iext{bib} file |
| 9068 |
with the \gls{encoding} comment |
| 9069 |
\begin{alltt} |
| 9070 |
\idx{commentchar} Encoding: \meta{encoding-name} |
| 9071 |
\end{alltt} |
| 9072 |
then you can supply the correct \gls{encoding} using |
| 9073 |
\csopt[encoding-name]{charset}. In general, it's better to include |
| 9074 |
the \gls{encoding} in the \ext{bib} file where it can also be read by |
| 9075 |
a \ext{bib} managing systems, such as JabRef. |
| 9076 |
|
| 9077 |
See \longarg{tex-encoding} for the \gls{encoding} used to write the \ext{glstex} |
| 9078 |
file, and see \sectionref{sec:defencoding} for information about the |
| 9079 |
default encoding. |
| 9080 |
|
| 9081 |
\optsection{locale} |
| 9082 |
|
| 9083 |
Sets the default \glsdisp{resource-locale}{locale} for the current |
| 9084 |
\gls{resourceset}. In general, it's best to set this at the start of |
| 9085 |
the resource option list, if required. If not set, the default |
| 9086 |
will be the \gls{document-locale}, if supplied, otherwise the |
| 9087 |
\gls{Java-locale} will be used. |
| 9088 |
|
| 9089 |
\optsection{wordify-math-greek} |
| 9090 |
|
| 9091 |
Instructs the interpreter to replace known math Greek commands with |
| 9092 |
words instead of the applicable symbol. For example, if an entry has |
| 9093 |
been defined as: |
| 9094 |
\begin{codeenv} |
| 9095 |
\atentry{index}\marg{a-Fe, |
| 9096 |
\field{name}=\marg{\cs{ensuremath}\marg{\ics{alpha}}-iron} |
| 9097 |
} |
| 9098 |
\end{codeenv} |
| 9099 |
Then with \csopt[true]{wordify-math-greek} the interpreter will obtain |
| 9100 |
the sort value \qt{alpha-iron}. This only works for commands |
| 9101 |
recognised by the \texparserlib\ as Math Greek commands. |
| 9102 |
|
| 9103 |
With the default \csopt[false]{wordify-math-greek}, the interpreter |
| 9104 |
will convert \cs{alpha} into the nearest appropriate Unicode |
| 9105 |
character. |
| 9106 |
|
| 9107 |
The textual replacement depends on whether or not a corresponding |
| 9108 |
entry is available in the language file \metafilefmt{bib2gls-extra-}{lang}{.xml} |
| 9109 |
for the current resource locale. If no entry is found, the control |
| 9110 |
sequence name (or substring) will typically be used. |
| 9111 |
|
| 9112 |
\optsection{wordify-math-symbol} |
| 9113 |
|
| 9114 |
Similar to \csopt{wordify-math-greek}, this option will apply to |
| 9115 |
other known math symbol commands. Again, this only works for a |
| 9116 |
limited set of commands recognised by the \texparserlib. An |
| 9117 |
alternative is to provide alternative definitions for \bibgls\ that |
| 9118 |
aren't picked up by \LaTeX, or use \ics{IfNotBibGls}, or use a more |
| 9119 |
appropriate field for sorting. |
| 9120 |
|
| 9121 |
\optsection{interpret-preamble} |
| 9122 |
|
| 9123 |
This is a boolean option that determines whether or not the |
| 9124 |
interpreter should parse the contents of \atentry{preamble}. |
| 9125 |
The default is \optfmt{true}. If \optfmt{false}, the preamble |
| 9126 |
contents will still be written to the \iext{glstex} file, but any |
| 9127 |
commands provided in the preamble won't be recognised by the |
| 9128 |
interpreter (see \sectionref{sec:texparserlib}). |
| 9129 |
|
| 9130 |
Related options are: \csopt{set-widest} (which uses the interpreter to determine |
| 9131 |
the widest name for the \glostyle{alttree} style or the |
| 9132 |
\isty{glossary-longextra} styles), \csopt{interpret-label-fields} (which governs |
| 9133 |
whether or not fields that must only contain a label should be interpreted), |
| 9134 |
\csopt{labelify} (which converts a field into a string suitable for use as a |
| 9135 |
label), and \csopt{labelify-list} (which converts a field into a string suitable |
| 9136 |
for use as a comma-separated list of labels). |
| 9137 |
|
| 9138 |
\optsection{write-preamble} |
| 9139 |
|
| 9140 |
This is a boolean option that determines whether or not the |
| 9141 |
preamble should be written to the \ext{glstex} file. The default |
| 9142 |
is \optfmt{true}. Note that the preamble will |
| 9143 |
still be parsed if \csopt[true]{interpret-preamble} even if |
| 9144 |
\csopt[false]{write-preamble}. This means it's possible to |
| 9145 |
provide \bibgls\ command definitions in \atentry{preamble} |
| 9146 |
that don't get seen by \LaTeX. |
| 9147 |
|
| 9148 |
\optsection{set-widest} |
| 9149 |
|
| 9150 |
The \glostyle{alttree} glossary style needs to know the widest |
| 9151 |
\field{name} (for each level, if \hierarchical). This can be set |
| 9152 |
using \ics{glssetwidest} provided by the \isty{glossary-tree} |
| 9153 |
package (or similar commands like \ics{glsupdatewidest} provided by |
| 9154 |
\isty{glossaries-extra-stylemods}), but this requires knowing |
| 9155 |
which name is the widest. Alternatively, one of the iterative commands |
| 9156 |
such as \ics{glsFindWidestTopLevelName} can be used, which slows the |
| 9157 |
document build as it has to iterate over all defined entries. |
| 9158 |
|
| 9159 |
The \isty{glossary-longextra} package, provided with |
| 9160 |
\sty{glossaries-extra} v1.37+, also needs to know the widest name, |
| 9161 |
but in this case only the \gls{top-levelentry}{top-level} is needed. |
| 9162 |
If this has already been found through the commands provided with |
| 9163 |
the \glostyle{alttree} style then that value will be used as the |
| 9164 |
default, but you can set another value that's only used for the |
| 9165 |
\sty{glossary-longextra} styles with \ics{glslongextraSetWidest}. |
| 9166 |
|
| 9167 |
The \sty{glossaries-extra-bib2gls} package provides \ics{glsxtrSetWidest}, |
| 9168 |
which sets the widest name for those styles that need it. As from version |
| 9169 |
1.8, \bibgls\ now checks for the existence of this command and will use it with |
| 9170 |
\csopt{set-widest} to allow for the new styles provided by the |
| 9171 |
\sty{glossary-longextra} package. |
| 9172 |
|
| 9173 |
The boolean option \csopt[true]{set-widest} will try to calculate |
| 9174 |
the widest names for each \hierarchicallevel\ to help remove the need |
| 9175 |
to determine the correct value within the document. |
| 9176 |
Since \bibgls\ doesn't know the fonts that will be used |
| 9177 |
in the document or if there are any non-standard commands that |
| 9178 |
aren't provided in the \ext{bib} files preamble, \emph{this option may not |
| 9179 |
work}. For example, if one entry has the \field{name} defined as: |
| 9180 |
\begin{codeenv} |
| 9181 |
\field{name}=\marg{some \marg{\cmd{Huge} huge} text} |
| 9182 |
\end{codeenv} |
| 9183 |
and another entry has the \field{name} defined as: |
| 9184 |
\begin{codeenv} |
| 9185 |
\field{name}=\marg{some \marg{\cmd{small} small} text} |
| 9186 |
\end{codeenv} |
| 9187 |
then \bibgls\ will determine that the second name is the widest |
| 9188 |
although the first will actually be wider when it's rendered in the |
| 9189 |
document. |
| 9190 |
|
| 9191 |
When using this option, the transcript file will include the message: |
| 9192 |
\begin{alltt} |
| 9193 |
Calculated width of '\meta{text}': \meta{number} |
| 9194 |
\end{alltt} |
| 9195 |
where \meta{text} is \bibgls's interpretation of the contents of the |
| 9196 |
\field{name} field and \meta{number} is a rough guide to the width |
| 9197 |
of \meta{text} assuming the operating system's default serif font. |
| 9198 |
The entry that has the largest \meta{number} is the one that will be |
| 9199 |
selected. This will then be implemented as follows: |
| 9200 |
\begin{itemize} |
| 9201 |
\item If the \field{type} is unknown then: |
| 9202 |
\begin{itemize} |
| 9203 |
\item if the interpreter resolves all \field{name} fields to the |
| 9204 |
empty string (that is the \field{name} fields all consist of |
| 9205 |
unknown commands) then |
| 9206 |
\begin{itemize} |
| 9207 |
\item if there are \glspl{childentry} \gls{bibglssetwidestfallback} |
| 9208 |
is used, |
| 9209 |
\item otherwise \gls{bibglssetwidesttoplevelfallback} is used; |
| 9210 |
\end{itemize} |
| 9211 |
\item otherwise \gls{bibglssetwidest} is used. |
| 9212 |
\end{itemize} |
| 9213 |
\item If the \field{type} is known then: |
| 9214 |
\begin{itemize} |
| 9215 |
\item if the interpreter resolves all \field{name} fields for that |
| 9216 |
type to the empty string (that is the \field{name} fields all consist of |
| 9217 |
unknown commands) then |
| 9218 |
\begin{itemize} |
| 9219 |
\item if there are \glspl{childentry} \gls{bibglssetwidestfortypefallback} |
| 9220 |
is used, |
| 9221 |
\item otherwise |
| 9222 |
\gls{bibglssetwidesttoplevelfortypefallback} is used; |
| 9223 |
\end{itemize} |
| 9224 |
\item otherwise \gls{bibglssetwidestfortype} is used. |
| 9225 |
\end{itemize} |
| 9226 |
\end{itemize} |
| 9227 |
This leaves \TeX\ to compute the width according to the document |
| 9228 |
fonts. If \bibgls\ can't correctly determine the widest entry then |
| 9229 |
you will need to use one of the commands provided by |
| 9230 |
\sty{glossary-tree}, \sty{glossary-longextra} or |
| 9231 |
\sty{glossaries-extra-stylemods} to set it. |
| 9232 |
|
| 9233 |
In general, if you have more than one glossary it's best to |
| 9234 |
set the \field{type} using options like \csopt{type} and |
| 9235 |
\csopt{dual-type} if you use \csopt{set-widest}. |
| 9236 |
|
| 9237 |
\optsection{entry-type-aliases} |
| 9238 |
|
| 9239 |
In the \ext{bib} file, the data is identified by |
| 9240 |
\code{@\meta{entry-type}}, such as \atentry[noindex]{abbreviation}. |
| 9241 |
It may be that you want to replace all instances of |
| 9242 |
\code{@\meta{entry-type}} with a different |
| 9243 |
type of entry. For example, suppose my \ext{bib} file |
| 9244 |
contains abbreviations defined in the form: |
| 9245 |
\begin{codeenv} |
| 9246 |
\atentry{abbreviation}\marg{html, |
| 9247 |
\field{short} = \marg{html}, |
| 9248 |
\field{long} = \marg{hypertext markup language}, |
| 9249 |
\field{description} = \marg{a markup language for creating web pages} |
| 9250 |
} |
| 9251 |
\end{codeenv} |
| 9252 |
but suppose in one of my documents I actually want all these |
| 9253 |
abbreviations defined with \atentry[noindex]{dualabbreviationentry} |
| 9254 |
instead of \atentry[noindex]{abbreviation}. Instead of editing |
| 9255 |
the \ext{bib} file I can just supply a mapping: |
| 9256 |
\begin{codeenv} |
| 9257 |
\gls{GlsXtrLoadResources}\oarg{ |
| 9258 |
\csopt[entries]{src},\comment{data in entries.bib} |
| 9259 |
\csopt[abbreviation=dualabbreviationentry]{entry-type-aliases} |
| 9260 |
} |
| 9261 |
\end{codeenv} |
| 9262 |
This makes all instances of \atentry[noindex]{abbreviation} |
| 9263 |
behave as \atentry[noindex]{dualabbreviationentry}. You can have more than |
| 9264 |
one mapping. For example: |
| 9265 |
\begin{codeenv} |
| 9266 |
\gls{GlsXtrLoadResources}\oarg{ |
| 9267 |
\csopt[entries]{src},\comment{data in entries.bib} |
| 9268 |
\csopt[ |
| 9269 |
\comment{\atentry{abbreviation} -> \atentry{dualabbreviationentry}:} |
| 9270 |
abbreviation=dualabbreviationentry, |
| 9271 |
\comment{\atentry{entry} -> \atentry{index}:} |
| 9272 |
entry=index |
| 9273 |
]{entry-type-aliases} |
| 9274 |
} |
| 9275 |
\end{codeenv} |
| 9276 |
This option isn't cumulative. Multiple instances of |
| 9277 |
\csopt{entry-type-aliases} override previous instances. |
| 9278 |
If \meta{\keyvallist} is empty there will be no mappings. |
| 9279 |
You can save the original \gls{entrytype} in the |
| 9280 |
\field{originalentrytype} field with |
| 9281 |
\csopt{save-original-entrytype}. |
| 9282 |
|
| 9283 |
Here's another example entry in a \ext{bib} file: |
| 9284 |
\begin{codeenv} |
| 9285 |
@foo\marg{html, |
| 9286 |
\field{name} = \marg{HTML}, |
| 9287 |
\field{short} = \marg{HTML}, |
| 9288 |
\field{long} = \marg{hypertext markup language}, |
| 9289 |
\field{description} = \marg{hypertext markup language} |
| 9290 |
} |
| 9291 |
\end{codeenv} |
| 9292 |
Ordinarily this entry would be ignored since \code{@foo} |
| 9293 |
isn't recognised, but it can be mapped like this: |
| 9294 |
\begin{codeenv} |
| 9295 |
\gls{GlsXtrLoadResources}\oarg{ |
| 9296 |
\csopt[entries]{src},\comment{data in entries.bib} |
| 9297 |
\csopt[short,long]{ignore-fields}, |
| 9298 |
\csopt[foo=entry]{entry-type-aliases} |
| 9299 |
} |
| 9300 |
\end{codeenv} |
| 9301 |
This treats the entry as though it had been defined as: |
| 9302 |
\begin{codeenv} |
| 9303 |
\atentry{entry}\marg{html, |
| 9304 |
\field{name} = \marg{HTML}, |
| 9305 |
\field{description} = \marg{hypertext markup language} |
| 9306 |
} |
| 9307 |
\end{codeenv} |
| 9308 |
whereas: |
| 9309 |
\begin{codeenv} |
| 9310 |
\gls{GlsXtrLoadResources}\oarg{ |
| 9311 |
\csopt[entries]{src},\comment{data in entries.bib} |
| 9312 |
\csopt[name,description]{ignore-fields}, |
| 9313 |
\csopt[foo=abbreviation]{entry-type-aliases} |
| 9314 |
} |
| 9315 |
\end{codeenv} |
| 9316 |
treats the entry as though it had been defined as: |
| 9317 |
\begin{codeenv} |
| 9318 |
\atentry{abbreviation}\marg{html, |
| 9319 |
\field{short} = \marg{HTML}, |
| 9320 |
\field{long} = \marg{hypertext markup language} |
| 9321 |
} |
| 9322 |
\end{codeenv} |
| 9323 |
|
| 9324 |
\optsection{unknown-entry-alias} |
| 9325 |
|
| 9326 |
If this option is set, the \meta{value} is used as the alias for any |
| 9327 |
unknown \glspl{entrytype} (after any aliases provided with |
| 9328 |
\csopt{entry-type-aliases} have been applied). If the value is |
| 9329 |
missing or empty, unknown \glspl{entrytype} will be ignored with a |
| 9330 |
warning. |
| 9331 |
|
| 9332 |
\optsection{action} |
| 9333 |
|
| 9334 |
This governs how the entries are written in the \iext{glstex} file. |
| 9335 |
The \meta{value} may be one of: |
| 9336 |
\begin{itemize} |
| 9337 |
\item\code{define}: define the entries; |
| 9338 |
\item\code{provide}: provide the entries; |
| 9339 |
\item\code{copy}: copy the entries; |
| 9340 |
\item\code{define or copy}: copy existing entries and define |
| 9341 |
non-existing entries. |
| 9342 |
\end{itemize} |
| 9343 |
The default setting is \csopt[define]{action}, which writes the entry |
| 9344 |
definition to the \ext{glstex} file using one of the commands |
| 9345 |
described in \sectionref{sec:newentrydefs}. Since the \styopt{record} |
| 9346 |
package option automatically switches on the \styopt[warn]{undefaction} |
| 9347 |
option, any attempt at defining an entry that's already been defined |
| 9348 |
will generate a warning rather than an error. The duplicate |
| 9349 |
definition will be ignored. (The warnings can be found in the |
| 9350 |
\ext{log} file since they are warnings produce by |
| 9351 |
\sty{glossaries-extra} not by \bibgls.) |
| 9352 |
|
| 9353 |
If you have multiple \iglspl{resourceset} to help group different types of |
| 9354 |
entry for the same glossary, the \csopt[provide]{action} setting can |
| 9355 |
be used to suppress any warnings if the selection criteria is too |
| 9356 |
complex to filter out entries that were selected by a previous |
| 9357 |
\gls{resourceset}. If, however, you want duplicate entries so that |
| 9358 |
you can have the same entry listed in multiple glossary, you need a |
| 9359 |
different approach. |
| 9360 |
|
| 9361 |
For example, if you try: |
| 9362 |
\begin{codeenv} |
| 9363 |
\cs{newglossary*}\marg{copies}\marg{Copies} |
| 9364 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}} |
| 9365 |
\gls{GlsXtrLoadResources}\oarg{\csopt[use]{sort},\csopt[copies]{type},\csopt[entries]{src}} |
| 9366 |
\end{codeenv} |
| 9367 |
you'll find that the \code{copies} glossary is empty and there will |
| 9368 |
be warnings in the \ext{log} file when the second resource file is |
| 9369 |
loaded. |
| 9370 |
|
| 9371 |
There are various ways of having the same entries in multiple |
| 9372 |
glossaries. The simplest method is to use \csopt{secondary}, but |
| 9373 |
another method is to use \csopt[copy]{action} which simply writes |
| 9374 |
\nosecformatdef{glsxtrcopytoglossary} |
| 9375 |
instead of using one of the commands listed in |
| 9376 |
\sectionref{sec:newentrydefs}. This copies the entries rather than |
| 9377 |
defining them, which means the entries must already have been |
| 9378 |
defined. You can select entries that were selected in earlier |
| 9379 |
\iglspl{resourceset} with \csopt[selected before]{selection}. |
| 9380 |
|
| 9381 |
The \meta{type} is determined as follows: |
| 9382 |
\begin{itemize} |
| 9383 |
\item if the entry has the \field{type} field set, that's used; |
| 9384 |
\item if the entry is a tertiary and \csopt{tertiary-type} is set, that's |
| 9385 |
used; |
| 9386 |
\item if the entry is a dual and \csopt{dual-type} is set, that's |
| 9387 |
used; |
| 9388 |
\item otherwise the value of the \csopt{type} option is used. |
| 9389 |
\end{itemize} |
| 9390 |
If you're not sure whether the entries may already be defined, you |
| 9391 |
can use \csopt[define or copy]{action} which will use |
| 9392 |
\ics{ifglsentryexists} in the resource file to determine whether to |
| 9393 |
define or copy the entry. |
| 9394 |
|
| 9395 |
Options that set or modify fields, such as \csopt{category}, |
| 9396 |
\csopt{group}, \csopt{save-locations}, \csopt{flatten} or |
| 9397 |
\csopt{name-case-change}, will be ignored if entries are copied. |
| 9398 |
However the \csopt{copy-action-group-field} may be used to copy |
| 9399 |
the \field{group} field (which may have been locally set by the |
| 9400 |
\csopt{sort} method) to another field. This ensures that the |
| 9401 |
original \field{group} value from the entry definition in an earlier |
| 9402 |
resource set won't be overwritten (unless you set |
| 9403 |
\csopt[group]{copy-action-group-field}). |
| 9404 |
|
| 9405 |
Remember that \gls{glsxtrcopytoglossary} simply copies the entry's |
| 9406 |
label to the glossary's internal list. The only checks that \bibgls\ |
| 9407 |
performs if \csopt{action} is not \code{define} is to ensure that |
| 9408 |
the \csopt{master} or \csopt{secondary} options have not been used, |
| 9409 |
since they're incompatible, and that the \csopt{type} option is set, |
| 9410 |
since it's required as a fallback for any entries that don't have |
| 9411 |
the \field{type} field set. (There are too many options that alter |
| 9412 |
field values to check them all and some may be used to alter the |
| 9413 |
sorting.) The purpose of the copy action is simply to provide a |
| 9414 |
duplicate list in a different order. |
| 9415 |
|
| 9416 |
Remember that if you are using \sty{hyperref}, you need to use |
| 9417 |
\code{\printglossopt[false]{target}} in the optional argument of |
| 9418 |
\ics{printunsrtglossary} for the glossary containing the copies to |
| 9419 |
prevent duplicate hypertargets. Commands like \cs{gls} will link to |
| 9420 |
the original entries. For example, in the preamble: |
| 9421 |
\begin{codeenv} |
| 9422 |
\cs{newignoredglossary}\marg{copies} |
| 9423 |
\strut |
| 9424 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}} |
| 9425 |
\strut |
| 9426 |
\gls{GlsXtrLoadResources}\oarg{ |
| 9427 |
\csopt[use]{sort}, |
| 9428 |
\csopt[copy]{action}, |
| 9429 |
\csopt[copies]{type}, |
| 9430 |
\csopt[entries]{src} |
| 9431 |
} |
| 9432 |
\end{codeenv} |
| 9433 |
and later in the document: |
| 9434 |
\begin{codeenv} |
| 9435 |
\cs{printunsrtglossary}\oarg{\printglossopt[Glossary (Alphabetical)]{title},\printglossopt[\glostyle{indexgroup}]{style}} |
| 9436 |
\cs{printunsrtglossary}\oarg{\printglossopt[copies]{type},\printglossopt[Glossary (Order of Use)]{title}, |
| 9437 |
\printglossopt[index]{style},\printglossopt{nogroupskip},\comment{no grouping} |
| 9438 |
\printglossopt[false]{target}} |
| 9439 |
\end{codeenv} |
| 9440 |
Note also the need to use \code{nogroupskip} and a non-group style |
| 9441 |
for the duplicates since the \field{group} field will have been |
| 9442 |
assigned in the first resource set if \bibgls\ was invoked with |
| 9443 |
\longarg{group}. The grouping is appropriate for alphabetical |
| 9444 |
ordering but not for order of use. |
| 9445 |
|
| 9446 |
If you want different grouping for the duplicates, you can specify |
| 9447 |
the field name to use in which to store the group information using |
| 9448 |
\csopt{copy-action-group-field}. Unlike \csopt{secondary}, you |
| 9449 |
will need to redefine \ics{glsxtrgroupfield} to the relevant field |
| 9450 |
before you display the glossary. The simplest way to do this is with |
| 9451 |
the starred form of \cs{printunsrtglossary}. |
| 9452 |
For example, if \csopt[dupgroup]{copy-action-group-field} is added to |
| 9453 |
the options for the second resource set: |
| 9454 |
\begin{codeenv} |
| 9455 |
\ics{printunsrtglossary*}\oarg{\printglossopt[copies]{type},\printglossopt[Duplicates]{title},\printglossopt[\glostyle{indexgroup}]{style}} |
| 9456 |
\marg{\cs{renewcommand}\marg{\cs{glsxtrgroupfield}}\marg{dupgroup}} |
| 9457 |
\end{codeenv} |
| 9458 |
This just does: |
| 9459 |
\begin{codeenv} |
| 9460 |
\cmd{begingroup} |
| 9461 |
\cs{renewcommand}\marg{\ics{glsxtrgroupfield}}\marg{dupgroup}\comment{} |
| 9462 |
\cs{printunsrtglossary}\oarg{\printglossopt[copies]{type},\printglossopt[Duplicates]{title}, |
| 9463 |
\printglossopt[indexgroup]{style}} |
| 9464 |
\cmd{endgroup} |
| 9465 |
\end{codeenv} |
| 9466 |
|
| 9467 |
\optsection{copy-to-glossary} |
| 9468 |
|
| 9469 |
This option can selectively copy an entry to a glossary after it has |
| 9470 |
been defined. If the supplied value \meta{list} is empty, no copying is |
| 9471 |
performed (except as a result of other options, such as |
| 9472 |
\csopt{action} or \csopt{secondary}). If set, the \meta{list} |
| 9473 |
argument is a list of string \glspl{concatenation} with optional |
| 9474 |
conditionals. Take care that constant strings are correctly |
| 9475 |
delimited, as described below, to ensure that they are not mistaken |
| 9476 |
for field labels. |
| 9477 |
|
| 9478 |
The evaluation of the target glossary label for each entry is |
| 9479 |
performed while the \ext{glstex} file is being written (after |
| 9480 |
sorting) so all field values should be available in any field reference. |
| 9481 |
The \csopt{action} option is implemented first, so the |
| 9482 |
selected entry will first either be defined or copied according to |
| 9483 |
\csopt{action}. If the \csopt{copy-to-glossary} instruction is |
| 9484 |
successful, the entry will then be copied to the target glossary using |
| 9485 |
\gls{bibglscopytoglossary}. |
| 9486 |
|
| 9487 |
The \csopt{copy-to-glossary} value should be a comma-separated list, |
| 9488 |
where the syntax for each item in the list is in the form: |
| 9489 |
\begin{codeenv} |
| 9490 |
\meta{element-list} \oargm{condition} |
| 9491 |
\end{codeenv} |
| 9492 |
where \meta{element-list} is a string \gls{concatenation} (see |
| 9493 |
\sectionref{sec:optstringconcat}) and \meta{condition} is a complex |
| 9494 |
conditional (see \sectionref{sec:conditionals}). For each |
| 9495 |
\meta{element-list} \oargm{condition} specification, if the |
| 9496 |
condition evaluates to false or if the \meta{element-list} evaluates |
| 9497 |
to null then the copy instruction won't be added. |
| 9498 |
|
| 9499 |
For example, the following first sets the \field{type} to |
| 9500 |
\qt{ignored} for any entries that only have \glspl{ignoredrecord} |
| 9501 |
and then copies all entries that don't have the \field{type} field |
| 9502 |
set to \qt{ignored} to the glossary labelled \qt{index}: |
| 9503 |
\begin{codeenv} |
| 9504 |
\gls{GlsXtrLoadResources}\oarg{ |
| 9505 |
\csopt[ignored]{ignored-type}, |
| 9506 |
\csopt[\qtdelim{index} \oarg{ \field{type} \idx{notequalscmp} \qtdelim{ignored}} ]{copy-to-glossary} |
| 9507 |
} |
| 9508 |
\end{codeenv} |
| 9509 |
|
| 9510 |
The fallback action for a missing field value is governed by the |
| 9511 |
\csopt{copy-to-glossary-missing-field-action} setting. The result of |
| 9512 |
the string concatenation (if not null) is the label of the target |
| 9513 |
glossary. |
| 9514 |
|
| 9515 |
You can have multiple copy instructions to copy an entry to multiple |
| 9516 |
glossaries. The definition of \gls{bibglscopytoglossary} will ensure |
| 9517 |
that an entry will only be copied to the designated glossary if it |
| 9518 |
isn't already in the glossary's internal list and will silently do |
| 9519 |
nothing if the glossary doesn't exist. |
| 9520 |
|
| 9521 |
Remember that constant strings need to be marked with braces or |
| 9522 |
double-quote delimiters. For example, if you want to copy \emph{all} |
| 9523 |
entries to the \code{index} glossary then either do: |
| 9524 |
\begin{codeenv} |
| 9525 |
\csopt[\qtdelim{index}]{copy-to-glossary} |
| 9526 |
\end{codeenv} |
| 9527 |
or |
| 9528 |
\begin{codeenv} |
| 9529 |
\csopt[\marg{index}]{copy-to-glossary} |
| 9530 |
\end{codeenv} |
| 9531 |
Note that the outer braces are stripped by the resource option |
| 9532 |
parser, which first splits the \code{\meta{option}\dequals\margm{value}} list supplied via |
| 9533 |
\gls{GlsXtrLoadResources} into \meta{option} and \meta{value} pairs, and then |
| 9534 |
parses each \meta{option}. So by the time that the |
| 9535 |
\csopt{copy-to-glossary} option has its value parsed, the value has |
| 9536 |
become \code{\qtdelim{index}} or \code{\marg{index}}, respectively, |
| 9537 |
in the above two examples. |
| 9538 |
|
| 9539 |
Remember that the \meta{value} itself may be a comma-separated list. |
| 9540 |
The outer grouping hides the inner list comma from the initial |
| 9541 |
\code{\meta{option}\dequals\margm{value}} split. For example, to copy all entries |
| 9542 |
to the \code{index} and \code{symbols} glossaries: |
| 9543 |
\begin{codeenv} |
| 9544 |
\csopt[\qtdelim{index}, \qtdelim{symbols}]{copy-to-glossary} |
| 9545 |
\end{codeenv} |
| 9546 |
or |
| 9547 |
\begin{codeenv} |
| 9548 |
\csopt[\marg{index}, \marg{symbols}]{copy-to-glossary} |
| 9549 |
\end{codeenv} |
| 9550 |
|
| 9551 |
The following example will only copy entries to the \code{index} |
| 9552 |
glossary if their actual entry type is \code{index}: |
| 9553 |
\begin{codeenv} |
| 9554 |
\csopt[\qtdelim{index} \oarg{ entrytype \idx{follow} actual \idx{equalscmp} \qtdelim{index} }]{copy-to-glossary} |
| 9555 |
\end{codeenv} |
| 9556 |
Alternatively, to copy aliased custom entry types |
| 9557 |
\atentryfmt{person} entries to a custom glossary \code{person} and |
| 9558 |
\atentryfmt{place} to a custom glossary \code{place}: |
| 9559 |
\begin{codeenv} |
| 9560 |
\csopt[ |
| 9561 |
entrytype \idx{follow} original |
| 9562 |
\oarg{ entrytype \idx{follow} original =\idx{slashchar}person\idx{regexpor}place\idx{slashchar} } |
| 9563 |
]{copy-to-glossary} |
| 9564 |
\end{codeenv} |
| 9565 |
|
| 9566 |
If the glossary types don't conveniently match the entry type, |
| 9567 |
the instructions can be split into a list. |
| 9568 |
For example: |
| 9569 |
\begin{codeenv} |
| 9570 |
\csopt[ |
| 9571 |
\qtdelim{abbreviations} \oarg{ entrytype \idx{follow} actual = \qtdelim{abbreviation} }, |
| 9572 |
\qtdelim{symbols} \oarg{ entrytype \idx{follow} actual = \qtdelim{symbol} }, |
| 9573 |
\qtdelim{numbers} \oarg{ entrytype \idx{follow} actual = \qtdelim{number} }, |
| 9574 |
]{copy-to-glossary} |
| 9575 |
\end{codeenv} |
| 9576 |
Each instruction in the list will be tried and the copy instruction |
| 9577 |
will only be written if the condition evaluates to true and a |
| 9578 |
non-null value is successfully returned. |
| 9579 |
|
| 9580 |
\optsection{copy-to-glossary-missing-field-action} |
| 9581 |
|
| 9582 |
This option indicates what to do if a source field identified in |
| 9583 |
\csopt{copy-to-glossary} is missing. The value may be one of: |
| 9584 |
\begin{itemize} |
| 9585 |
\item \optfmt{skip}: return null; |
| 9586 |
\item \optfmt{fallback}: use the fallback for the missing field |
| 9587 |
(see \sectionref{sec:fallbacks}), if |
| 9588 |
one is available, otherwise return null (default); |
| 9589 |
\item \optfmt{empty}: treat the missing value as empty. |
| 9590 |
\end{itemize} |
| 9591 |
Returning null will result in the copy instruction being omitted. |
| 9592 |
|
| 9593 |
\section{Selection Options} |
| 9594 |
\label{sec:selectionopts} |
| 9595 |
|
| 9596 |
\optsection{src} |
| 9597 |
|
| 9598 |
This identifies the \iext{bib} files containing the entry |
| 9599 |
definitions. The value should be a comma-separated list of the |
| 9600 |
required \ext{bib} files. These may either be in the current working |
| 9601 |
directory or in the directory given by the \longarg{dir} switch or on |
| 9602 |
\TeX's path (in which case \idx{kpsewhich} will be used to find |
| 9603 |
them). The \ext{bib} extension may be omitted. Remember that if |
| 9604 |
\meta{list} contains multiple files it must be grouped to protect |
| 9605 |
the comma from the \meta{options} list. |
| 9606 |
|
| 9607 |
For example: |
| 9608 |
\begin{codeenv} |
| 9609 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries-terms,entries-symbols]{src}} |
| 9610 |
\end{codeenv} |
| 9611 |
indicates that \bibgls\ must read the files |
| 9612 |
\filefmt{entries-terms.bib} and \filefmt{entries-symbols.bib}. |
| 9613 |
|
| 9614 |
If \csopt{src} is omitted or if the value is empty, it's assumed to |
| 9615 |
be the same as the basename of the \ext{glstex} file. This is |
| 9616 |
\ics{jobname} for the first instance of \gls{GlsXtrLoadResources}. |
| 9617 |
Remember that subsequent uses of \gls{GlsXtrLoadResources} append a |
| 9618 |
suffix \code{\cs{jobname}-\meta{n}}, so in general it's best to |
| 9619 |
always supply \csopt{src} (or use \gls{glsbibdata}), except for |
| 9620 |
small test cases with a single \gls{resourcecommand}. |
| 9621 |
|
| 9622 |
With old \LaTeX\ kernels, if you have non-ASCII characters in the |
| 9623 |
\ext{bib} filename but aren't using \XeLaTeX\ or \LuaLaTeX, then you |
| 9624 |
will need to use \ics{detokenize} to prevent expansion when the |
| 9625 |
information is written to the \ext{aux} file. Newer \LaTeX\ kernels |
| 9626 |
have better support for UTF-8. Similarly for any special characters |
| 9627 |
that need protecting (although it's better not to use special |
| 9628 |
characters in filenames). For example: |
| 9629 |
\begin{codeenv} |
| 9630 |
\cmd{documentclass}\marg{article} |
| 9631 |
\strut |
| 9632 |
\cmd{usepackage}\oarg{T2A}\marg{fontenc} |
| 9633 |
\cmd{usepackage}\oarg{utf8}\marg{inputenc} |
| 9634 |
\cmd{usepackage}\oarg{russian}\marg{babel} |
| 9635 |
\cmd{usepackage}\oarg{record}\marg{glossaries-extra} |
| 9636 |
\strut |
| 9637 |
\gls{GlsXtrLoadResources}\oarg{ |
| 9638 |
\csopt[\cs{detokenize}\marg{\textcyrillicmono{кириллица}}]{src},\comment{data in \textcyrillicmono{кириллица.bib}} |
| 9639 |
\csopt[all]{selection} |
| 9640 |
} |
| 9641 |
\strut |
| 9642 |
\cmd{begin}\marg{document} |
| 9643 |
\cs{printunsrtglossary} |
| 9644 |
\cmd{end}\marg{document} |
| 9645 |
\end{codeenv} |
| 9646 |
|
| 9647 |
\optsection{selection} |
| 9648 |
|
| 9649 |
By default all entries that have records in the \iext{aux} file will |
| 9650 |
be selected as well as all their dependent entries. The dependent |
| 9651 |
entries that don't have corresponding records on the first \LaTeX\ |
| 9652 |
run, may need an additional build to ensure their \glspl{locationlist} |
| 9653 |
are updated. |
| 9654 |
|
| 9655 |
Remember that on the first \LaTeX\ run the \iext{glstex} files don't |
| 9656 |
exist. This means that the entries aren't defined at that point. The |
| 9657 |
\styopt{record} package option additionally switches on the |
| 9658 |
\styopt[warn]{undefaction} option, which means that you'll only get |
| 9659 |
warnings rather than errors when you reference entries in the |
| 9660 |
document. You can't use \ics{glsaddall} with |
| 9661 |
\bibgls\ because the glossary lists are empty on the first run, so |
| 9662 |
there's nothing for \ics{glsaddall} to iterate over. |
| 9663 |
Instead, if you want to add all defined entries, you need to |
| 9664 |
instruct \bibgls\ to do this with the \csopt{selection} option. The |
| 9665 |
following values are allowed: |
| 9666 |
\begin{itemize} |
| 9667 |
\item \optfmt{recorded and deps}: add all recorded entries and |
| 9668 |
their dependencies (default). |
| 9669 |
|
| 9670 |
\item \optfmt{recorded and deps and see}: as above but will also |
| 9671 |
add unrecorded entries whose \field{see}, \field{seealso} or |
| 9672 |
\field{alias} field refers to a recorded entry. |
| 9673 |
|
| 9674 |
\item \optfmt{recorded and deps and see not also}: as above but will |
| 9675 |
add unrecorded entries whose \field{see} or \field{alias} (but not |
| 9676 |
\field{seealso}) field refers to a recorded entry. |
| 9677 |
|
| 9678 |
\item \optfmt{recorded no deps}: add all recorded entries but not |
| 9679 |
their dependencies. The dependencies include those referenced in the |
| 9680 |
\field{see} or \field{seealso} field or fields identified by |
| 9681 |
\csopt{dependency-fields}, \field{parent} entries and those found |
| 9682 |
referenced with commands like \ics{gls} in the field values that are |
| 9683 |
parsed by \bibgls. With this setting, \glsdisp{parententry}{parents} |
| 9684 |
will be omitted unless they've been referenced in the document |
| 9685 |
through commands like \ics{gls}. This setting won't add any |
| 9686 |
\field{see} or \field{seealso} lists to the \igls{locationlist}. The |
| 9687 |
given field will be set, so you can access the information, but |
| 9688 |
there's no guarantee that the cross-referenced entry will have been |
| 9689 |
selected. The \field{alias} cross-reference will be added to the |
| 9690 |
\igls{locationlist} but you will need to ensure that the target is |
| 9691 |
also selected (or use \csopt[omit]{alias} to suppress it). |
| 9692 |
|
| 9693 |
\item \optfmt{recorded and ancestors}: this is like the previous |
| 9694 |
setting but \glsdisp{parententry}{parents} are added even if they |
| 9695 |
haven't been referenced in the document. The other dependent entries |
| 9696 |
are omitted if they haven't been referenced in the document. The |
| 9697 |
above notes regarding the cross-reference lists also applies. |
| 9698 |
|
| 9699 |
\item \optfmt{deps but not recorded}: this first selects entries as |
| 9700 |
though \optfmt{recorded and deps} had been used, but after all |
| 9701 |
\glspl{ancestor} and dependencies have been added it then removes all |
| 9702 |
entries that have records. This means that you end up with only the |
| 9703 |
unrecorded dependencies. (Recorded entries will need to be selected |
| 9704 |
in a different resource set.) |
| 9705 |
|
| 9706 |
\item \optfmt{ancestors but not recorded}: this first selects |
| 9707 |
entries as though \optfmt{recorded and ancestors} had been used, but |
| 9708 |
after all \glspl{ancestor} have been added it then removes all entries that |
| 9709 |
have records. This means that you end up with only the unrecorded |
| 9710 |
\glspl{ancestor}. (Recorded entries will need to be selected |
| 9711 |
in a different resource set.) See the \exfile{sample-nested.tex} |
| 9712 |
example document. |
| 9713 |
|
| 9714 |
\item \optfmt{selected before}: select any entries that have been |
| 9715 |
selected in a previous \igls{resourceset}. This is intended |
| 9716 |
for use with \csopt[copy]{action} to copy entries to another |
| 9717 |
glossary as an alternative to (or in addition to) the |
| 9718 |
\csopt{secondary} option. Note that if you make any modifications to |
| 9719 |
the fields (such as case-changing) the modification won't be saved |
| 9720 |
to the \ext{glstex} file. This option can't be used in the first |
| 9721 |
\igls{resourceset}. |
| 9722 |
|
| 9723 |
\item \optfmt{all}: add all entries found in the \ext{bib} files |
| 9724 |
supplied in the \csopt{src} option. |
| 9725 |
\end{itemize} |
| 9726 |
The \meta{value} must be supplied. |
| 9727 |
|
| 9728 |
For example, suppose the file \filefmt{entries.bib} contains: |
| 9729 |
\begin{codeenv} |
| 9730 |
\atentry{index}\marg{run} |
| 9731 |
\atentry{index}\marg{sprint,\field{see}=\marg{run}} |
| 9732 |
\atentry{index}\marg{dash,\field{see}=\marg{sprint}} |
| 9733 |
\end{codeenv} |
| 9734 |
If the document only references the \qt{run} entry (for example, |
| 9735 |
using \code{\cs{gls}\marg{run}}) then: |
| 9736 |
\begin{itemize} |
| 9737 |
\item If \csopt[recorded and deps]{selection}, only the \qt{run} |
| 9738 |
entry is selected. The \qt{run} entry has a record, so it's |
| 9739 |
selected, but it has no dependencies. Neither \qt{sprint} nor |
| 9740 |
\qt{dash} have records, so they're not selected. |
| 9741 |
\item If \csopt[recorded and deps and see]{selection}, the \qt{run} |
| 9742 |
and \qt{sprint} entries are selected, but not the \qt{dash} entry. |
| 9743 |
The \qt{run} entry is selected because it has a record. The |
| 9744 |
\qt{sprint} entry doesn't have a record but its \field{see} field |
| 9745 |
includes \qt{run}, which does have a record, so \qt{sprint} is also |
| 9746 |
selected. The \qt{dash} entry doesn't have a record. Its |
| 9747 |
\field{see} field references \qt{sprint}. Although \qt{sprint} has |
| 9748 |
been selected, it doesn't have any records, so \qt{dash} isn't |
| 9749 |
selected. |
| 9750 |
\end{itemize} |
| 9751 |
The above is just an example. The circuitous redirection of |
| 9752 |
\qt{dash} to \qt{sprint} to \qt{run} is unhelpful to the reader and |
| 9753 |
is best avoided (especially for an index where there are no accompanying |
| 9754 |
descriptions and no \igls{locationlist} for the intermediate \qt{sprint}). |
| 9755 |
A better method would be: |
| 9756 |
\begin{codeenv} |
| 9757 |
\atentry{index}\marg{run} |
| 9758 |
\atentry{index}\marg{sprint,\field{see}=\marg{run}} |
| 9759 |
\atentry{index}\marg{dash,\field{see}=\marg{run}} |
| 9760 |
\end{codeenv} |
| 9761 |
The \csopt[recorded and deps and see]{selection} in this case will |
| 9762 |
select all three entries, and the document won't send the reader on a |
| 9763 |
long-winded detour. |
| 9764 |
|
| 9765 |
Now suppose that the file \filefmt{entries.bib} contains: |
| 9766 |
\begin{codeenv} |
| 9767 |
\atentry{entry}\marg{run, |
| 9768 |
\field{name} = \marg{run}, |
| 9769 |
\field{description}=\marg{move fast using legs} |
| 9770 |
} |
| 9771 |
\strut |
| 9772 |
\atentry{entry}\marg{sprint, |
| 9773 |
\field{name} = \marg{sprint}, |
| 9774 |
\field{description}=\marg{run at full speed over short distance}, |
| 9775 |
\field{seealso}=\marg{run} |
| 9776 |
} |
| 9777 |
\strut |
| 9778 |
\atentry{entry}\marg{dash, |
| 9779 |
\field{name} = \marg{dash}, |
| 9780 |
\field{description}=\marg{run in a great hurry}, |
| 9781 |
\field{seealso}=\marg{sprint} |
| 9782 |
} |
| 9783 |
\end{codeenv} |
| 9784 |
and suppose the document only references \qt{dash} (for example, with |
| 9785 |
\code{\cs{gls}\marg{dash}}), then with the default \csopt[recorded and deps]{selection} |
| 9786 |
\qt{dash} will be selected because it has a record, and \qt{sprint} |
| 9787 |
will be selected because \qt{dash} requires it (for the cross-reference), |
| 9788 |
and \qt{run} will be selected because \qt{sprint} requires it |
| 9789 |
(for the cross-reference). In this case, neither \qt{sprint} nor \qt{run} |
| 9790 |
have a \igls{locationlist} but they do both provide additional information |
| 9791 |
for the reader in their descriptions. |
| 9792 |
|
| 9793 |
A better method here would be for each entry to have a cross-reference |
| 9794 |
list that includes all related terms: |
| 9795 |
\begin{codeenv} |
| 9796 |
\atentry{entry}\marg{run, |
| 9797 |
\field{name} = \marg{run}, |
| 9798 |
\field{description}=\marg{move fast using legs}, |
| 9799 |
\field{seealso}=\marg{sprint,dash} |
| 9800 |
} |
| 9801 |
\strut |
| 9802 |
\atentry{entry}\marg{sprint, |
| 9803 |
\field{name} = \marg{sprint}, |
| 9804 |
\field{description}=\marg{run at full speed over short distance}, |
| 9805 |
\field{seealso}=\marg{run,dash} |
| 9806 |
} |
| 9807 |
\strut |
| 9808 |
\atentry{entry}\marg{dash, |
| 9809 |
\field{name} = \marg{dash}, |
| 9810 |
\field{description}=\marg{run in a great hurry}, |
| 9811 |
\field{seealso}=\marg{sprint,run} |
| 9812 |
} |
| 9813 |
\end{codeenv} |
| 9814 |
Now, whichever one is indexed in the document, the other two will automatically |
| 9815 |
be selected. |
| 9816 |
|
| 9817 |
\optsection{match} |
| 9818 |
|
| 9819 |
It's possible to filter the selection by matching field values. |
| 9820 |
The value is required for this key but may be empty, which indicates |
| 9821 |
that the setting is switched off, otherwise |
| 9822 |
\meta{\keyvallist} should be a \meta{key}=\meta{regexp} list, where |
| 9823 |
\meta{key} is the name of a field or \optfmt{id} for the entry's |
| 9824 |
label or \optfmt{entrytype} for the \bibgls\ \gls{entrytype} (as in |
| 9825 |
the part after \verb|@| identifying the entry not the \field{type} |
| 9826 |
field identifying the glossary label). If you've used |
| 9827 |
\csopt{entry-type-aliases}, this refers to the target \gls{entrytype} not |
| 9828 |
the original \gls{entrytype} specified in the \ext{bib} file. |
| 9829 |
|
| 9830 |
\begin{important} |
| 9831 |
Filtering options don't apply directly to \atentry{compoundset} |
| 9832 |
entries (or any of the other special entry types described in |
| 9833 |
\sectionref{sec:specialentrytypes}), so you can't |
| 9834 |
match the entry type to \atentry{compoundset}. |
| 9835 |
However, if any elements within a \gls{compoundentry} are filtered |
| 9836 |
then the \gls{compoundentry} won't be written to the \ext{glstex} |
| 9837 |
file. Use the \csopt{compound-write-def} option to determine whether |
| 9838 |
or not to write the \gls{compoundentry} to the resource file. |
| 9839 |
\end{important} |
| 9840 |
|
| 9841 |
The \meta{regexp} part should be a \gls{regular-expression} conforming |
| 9842 |
to |
| 9843 |
\href{http://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html}{Java's |
| 9844 |
Pattern class}~\cite{pattern}. The pattern is \gls{anchored} |
| 9845 |
(\code{oo}\idx{matchanydot}\idx{zeroormore} matches |
| 9846 |
\code{oops} but not \code{loops}) and \meta{regexp} can't be |
| 9847 |
empty. Remember that \TeX\ will expand the option list as |
| 9848 |
it writes the information to the \ext{aux} file so take |
| 9849 |
care with special characters. For example, to match a literal |
| 9850 |
period use \cs{cs.string}\idx{cs.period} not \idx{cs.period} (backslash dot). |
| 9851 |
|
| 9852 |
If the field is missing its value it is assumed to be empty for |
| 9853 |
the purposes of the pattern match even if it will be assigned a |
| 9854 |
non-empty default value when the entry is defined. If the field is |
| 9855 |
unrecognised by \bibgls\ any reference to it in \meta{\keyvallist} will |
| 9856 |
be ignored. |
| 9857 |
|
| 9858 |
If a field is listed multiple times, the pattern for that |
| 9859 |
field is concatenated using: |
| 9860 |
\begin{alltt} |
| 9861 |
(?:\meta{pattern-1})|(?:\meta{pattern-2}) |
| 9862 |
\end{alltt} |
| 9863 |
where \meta{pattern-1} is the current pattern for that field |
| 9864 |
and \meta{pattern-2} is the new pattern. This means it performs a |
| 9865 |
logical OR\@. For the non-duplicate |
| 9866 |
fields the logical operator is given by \csopt{match-op}. |
| 9867 |
For example: |
| 9868 |
\begin{codeenv} |
| 9869 |
\csopt[and]{match-op}, |
| 9870 |
\csopt[ |
| 9871 |
\field{category}=animals, |
| 9872 |
\fieldfmt{topic}=biology, |
| 9873 |
\field{category}=vegetables |
| 9874 |
]{match} |
| 9875 |
\end{codeenv} |
| 9876 |
This will keep all the selected entries that satisfy: |
| 9877 |
\begin{itemize} |
| 9878 |
\item \field{category} matches \verb"(?:animals)|(?:vegetables)" |
| 9879 |
|
| 9880 |
(the \field{category} is either \optfmt{animals} or |
| 9881 |
\optfmt{vegetables}) |
| 9882 |
|
| 9883 |
\item[AND] |
| 9884 |
|
| 9885 |
\item \fieldfmt{topic} (custom key provided by user) is \code{biology}. |
| 9886 |
\end{itemize} |
| 9887 |
and will discard any entries that don't satisfy this condition. |
| 9888 |
A message will be written to the log file for each entry |
| 9889 |
that's discarded. |
| 9890 |
|
| 9891 |
Patterns for unknown fields will be ignored. If the entire |
| 9892 |
list consists of patterns for unknown fields it will be |
| 9893 |
treated as \csopt[\empty]{match}. That is, no filtering will be |
| 9894 |
applied. In the above example, the custom \fieldfmt{topic} key must |
| 9895 |
be provided before the first \gls{GlsXtrLoadResources} with |
| 9896 |
\ics{glsaddkey} or \ics{glsaddstoragekey}. |
| 9897 |
|
| 9898 |
\optsection{match-op} |
| 9899 |
|
| 9900 |
If the value of \csopt{match} contains more than one |
| 9901 |
\meta{key}=\meta{pattern} element, the \csopt{match-op} |
| 9902 |
determines whether to apply a logical AND or a logical OR. |
| 9903 |
The \meta{value} may be either \optfmt{and} or \optfmt{or}. |
| 9904 |
The default is \csopt[and]{match-op}. |
| 9905 |
|
| 9906 |
\optsection{not-match} |
| 9907 |
|
| 9908 |
If \csopt[\meta{\keyvallist}]{match} would cause an entry to be |
| 9909 |
selected then \csopt[\meta{\keyvallist}]{not-match} would cause that |
| 9910 |
entry to be ignored. The value is required for this key but may be |
| 9911 |
empty, which indicates that the setting is switched off. If you |
| 9912 |
have both \csopt{match} and \csopt{not-match} in the same resource |
| 9913 |
set, the last one listed takes precedence. |
| 9914 |
|
| 9915 |
\begin{important} |
| 9916 |
Filtering options don't apply directly to \atentry{compoundset} |
| 9917 |
entries (or any of the other special entry types described in |
| 9918 |
\sectionref{sec:specialentrytypes}), so you can't match the entry type to \atentry{compoundset}. |
| 9919 |
However, if any elements within a \gls{compoundentry} are filtered |
| 9920 |
then the \gls{compoundentry} won't be written to the \ext{glstex} |
| 9921 |
file. Use the \csopt{compound-write-def} option to determine whether |
| 9922 |
or not to write the \gls{compoundentry} to the resource file. |
| 9923 |
\end{important} |
| 9924 |
|
| 9925 |
\optsection{match-action} |
| 9926 |
|
| 9927 |
The default behaviour with \csopt{match} or \csopt{not-match} |
| 9928 |
is to filter the selection. This may be changed to append to the |
| 9929 |
selection instead. The \meta{value} may be one of: |
| 9930 |
\begin{itemize} |
| 9931 |
\item\optfmt{filter}: (default) filter selection; |
| 9932 |
\item\optfmt{add}: append any matches (with \csopt{match}) or |
| 9933 |
non-matches (with \csopt{not-match}) to the selection. |
| 9934 |
This setting can't be used with \csopt[use]{sort}. |
| 9935 |
\end{itemize} |
| 9936 |
For example, if I want to select all record entries and their |
| 9937 |
dependencies, but I also want to make sure that any entries with |
| 9938 |
the category set to \code{important} are always selected regardless |
| 9939 |
of whether or not they have any records: |
| 9940 |
\begin{codeenv} |
| 9941 |
\gls{GlsXtrLoadResources}\oarg{ |
| 9942 |
\csopt[entries]{src},\comment{data in entries.bib} |
| 9943 |
\csopt[add]{match-action}, |
| 9944 |
\csopt[\field{category}=important]{match} |
| 9945 |
} |
| 9946 |
\end{codeenv} |
| 9947 |
|
| 9948 |
\optsection{limit} |
| 9949 |
|
| 9950 |
If \meta{number} is greater than 0 then this will truncate the |
| 9951 |
list of selected entries after sorting to \meta{number} (if the list |
| 9952 |
size is greater than that value). The transcript will show the |
| 9953 |
message: |
| 9954 |
\begin{alltt} |
| 9955 |
Truncating according to limit=\meta{number} |
| 9956 |
\end{alltt} |
| 9957 |
When used with \csopt{shuffle}, this provides a means of randomly |
| 9958 |
selecting at most \meta{number} entries. The default setting is |
| 9959 |
\csopt[0]{limit} (no truncation). A negative value of \meta{number} is not |
| 9960 |
permitted. |
| 9961 |
|
| 9962 |
If you have any \glspl{dualentry}, then the truncation will be |
| 9963 |
applied to the combined list of \primary\ and |
| 9964 |
\glsdisp{dualentry}{duals} if \csopt[combine]{dual-sort} otherwise |
| 9965 |
each list will be truncated separately by \meta{number}, which |
| 9966 |
results in a maximum of $2 \times \meta{number}$. Remember that |
| 9967 |
\glspl{tertiaryentry} are created when \glspl{dualentry} are defined |
| 9968 |
in the \ext{glstex} file, so this will increase the total number of |
| 9969 |
entries. |
| 9970 |
|
| 9971 |
\section{Hierarchical Options} |
| 9972 |
\label{sec:hierarchicalopts} |
| 9973 |
|
| 9974 |
Hierarchy is established by setting the \field{parent} field to the |
| 9975 |
label of the parent entry. The parent and child entries are |
| 9976 |
sorted together, but hierarchical comparators will place child |
| 9977 |
entries after their corresponding parent. |
| 9978 |
|
| 9979 |
The \sty{glossaries} package provides \ics{ifglshasparent} to |
| 9980 |
determine whether or not an entry has the \field{parent} field set. |
| 9981 |
If also provides \ics{ifglshaschildren}, but this command is |
| 9982 |
inefficient as it has to iterate over all entries to find an entry |
| 9983 |
with the \field{parent} field set to the relevant label. It's also |
| 9984 |
non-trivial to determine which child entries have been included in |
| 9985 |
the glossary with \idx!{makeindex} or \idx!{xindy}. \bibgls\ can |
| 9986 |
provide this information with some of the options described in this |
| 9987 |
section. |
| 9988 |
|
| 9989 |
It's also possible to \glsdisp{flatglossary}{flatten entries} (that is, remove the |
| 9990 |
hierarchical information) or just flatten \glspl{lonelychildentry}. |
| 9991 |
|
| 9992 |
\optsection{save-child-count} |
| 9993 |
|
| 9994 |
This is a boolean option. The default setting is |
| 9995 |
\csopt[false]{save-child-count}. |
| 9996 |
If \csopt[true]{save-child-count}, each entry will be assigned a |
| 9997 |
field called \field{childcount} with the value equal to the number |
| 9998 |
of \glspl{childentry} that have been selected. As from version 1.5, |
| 9999 |
this option also creates the \field{childlist} field for entries |
| 10000 |
that have \glsdisp{childentry}{children} selected. This field is in |
| 10001 |
\sty{etoolbox}'s internal list format and can be iterated over using |
| 10002 |
\glsadd{idx.loop}\ics{glsxtrfieldforlistloop}. |
| 10003 |
|
| 10004 |
The assignment is done using \ics{GlsXtrSetField} so there's |
| 10005 |
no associated key. You can test if the field is set and non-zero |
| 10006 |
using: |
| 10007 |
\nosecformatdef{GlsXtrIfHasNonZeroChildCount} |
| 10008 |
which is provided with \sty{glossaries-extra-bib2gls} v1.31+. |
| 10009 |
Within \meta{true}, you can access the actual value with |
| 10010 |
\ics{glscurrentfieldvalue}. If \csopt[false]{save-child-count}, |
| 10011 |
this command will do \meta{false} as the \field{childcount} field |
| 10012 |
won't be set. |
| 10013 |
|
| 10014 |
For example, suppose \filefmt{entries.bib} contains: |
| 10015 |
\begin{codeenv} |
| 10016 |
\atentry{index}\marg{birds} |
| 10017 |
\atentry{index}\marg{duck,\field{parent}=\marg{birds}} |
| 10018 |
\atentry{index}\marg{goose,\field{plural}=\marg{geese},\field{parent}=\marg{birds}} |
| 10019 |
\atentry{index}\marg{swan,\field{parent}=\marg{birds}} |
| 10020 |
\strut |
| 10021 |
\atentry{index}\marg{minerals} |
| 10022 |
\atentry{index}\marg{quartz,\field{parent}=\marg{minerals}} |
| 10023 |
\atentry{index}\marg{corundum,\field{parent}=\marg{minerals}} |
| 10024 |
\atentry{index}\marg{amethyst,\field{parent}=\marg{minerals}} |
| 10025 |
\atentry{index}\marg{gypsum,\field{parent}=\marg{minerals}} |
| 10026 |
\atentry{index}\marg{gold,\field{parent}=\marg{minerals}} |
| 10027 |
\end{codeenv} |
| 10028 |
and the document contains: |
| 10029 |
\begin{codeenv} |
| 10030 |
\cmd{documentclass}\marg{article} |
| 10031 |
\strut |
| 10032 |
\cmd{usepackage}[\styopt{record},\styopt[indexgroup]{style}]\marg{glossaries-extra} |
| 10033 |
\strut |
| 10034 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt{save-child-count}} |
| 10035 |
\strut |
| 10036 |
\cmd{begin}\marg{document} |
| 10037 |
\cs{gls}\marg{duck} and \cs{gls}\marg{goose}. |
| 10038 |
\cs{gls}\marg{quartz}, \cs{gls}\marg{corundum}, \cs{gls}\marg{amethyst}. |
| 10039 |
\strut |
| 10040 |
\cs{printunsrtglossaries} |
| 10041 |
\cmd{end}\marg{document} |
| 10042 |
\end{codeenv} |
| 10043 |
Then the \ext{glstex} file will contain: |
| 10044 |
\begin{codeenv} |
| 10045 |
\cs{GlsXtrSetField}\marg{birds}\marg{childcount}\marg{2} |
| 10046 |
\cs{GlsXtrSetField}\marg{duck}\marg{childcount}\marg{0} |
| 10047 |
\gls{glsxtrfieldlistadd}\marg{birds}\marg{childlist}\marg{duck} |
| 10048 |
\cs{GlsXtrSetField}\marg{goose}\marg{childcount}\marg{0} |
| 10049 |
\gls{glsxtrfieldlistadd}\marg{birds}\marg{childlist}\marg{goose} |
| 10050 |
\cs{GlsXtrSetField}\marg{minerals}\marg{childcount}\marg{3} |
| 10051 |
\cs{GlsXtrSetField}\marg{amethyst}\marg{childcount}\marg{0} |
| 10052 |
\gls{glsxtrfieldlistadd}\marg{minerals}\marg{childlist}\marg{amethyst} |
| 10053 |
\cs{GlsXtrSetField}\marg{corundum}\marg{childcount}\marg{0} |
| 10054 |
\gls{glsxtrfieldlistadd}\marg{minerals}\marg{childlist}\marg{corundum} |
| 10055 |
\cs{GlsXtrSetField}\marg{quartz}\marg{childcount}\marg{0} |
| 10056 |
\gls{glsxtrfieldlistadd}\marg{minerals}\marg{childlist}\marg{quartz} |
| 10057 |
\end{codeenv} |
| 10058 |
Note that although \code{birds} has three \children\ defined in the |
| 10059 |
\ext{bib} file, only two have been selected, so the \child\ count is |
| 10060 |
set to~2. Similarly the \code{minerals} entry has five \children\ |
| 10061 |
defined in the \ext{bib} file, but only three have been selected, so |
| 10062 |
the \child\ count is~3. |
| 10063 |
|
| 10064 |
The following uses the post-description hook to show the \child\ count |
| 10065 |
in parentheses: |
| 10066 |
\begin{codeenv} |
| 10067 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[general]{category},\csopt{save-child-count}} |
| 10068 |
\strut |
| 10069 |
\cs{glsdefpostdesc}\marg{general}\marg{\comment{} |
| 10070 |
\cs{glsxtrifhasfield}\marg{childcount}\marg{\cs{glscurrententrylabel}}\comment{} |
| 10071 |
\marg{ (child count: \cs{glscurrentfieldvalue}.)}\comment{} |
| 10072 |
\marg{}\comment{} |
| 10073 |
} |
| 10074 |
\end{codeenv} |
| 10075 |
\ics{glsxtrifhasfield} requires at least \sty{glossaries-extra} v1.19. |
| 10076 |
It's slightly more efficient than \ics{ifglshasfield} provided by |
| 10077 |
the base \styfmt{glossaries} package, and it doesn't complain if the |
| 10078 |
entry or field don't exist, but note that \ics{glsxtrifhasfield} |
| 10079 |
implicitly scopes its content. Use the starred version to omit the |
| 10080 |
grouping. With \sty{glossaries-extra} v1.31+ you can perform a |
| 10081 |
numerical test with \ics{GlsXtrIfFieldNonZero} or |
| 10082 |
\ics{GlsXtrIfFieldEqNum}. |
| 10083 |
|
| 10084 |
\optsection{save-sibling-count} |
| 10085 |
|
| 10086 |
This is a boolean option. The default setting is |
| 10087 |
\csopt[false]{save-sibling-count}. This is like |
| 10088 |
\csopt{save-child-count} but saves the \gls{sibling} count in |
| 10089 |
\field{siblingcount} and the \gls{sibling} list in |
| 10090 |
\field{siblinglist}. As with the \child list, the \gls{sibling} |
| 10091 |
list is in \sty{etoolbox}['s] internal list format. The |
| 10092 |
\gls{sibling} information is only saved for entries that have a |
| 10093 |
\parent. |
| 10094 |
|
| 10095 |
The advantage with \field{siblinglist} over accessing the |
| 10096 |
\glsdisp{parententry}{parent's} \field{childlist} is that the entry |
| 10097 |
itself is excluded from the list. |
| 10098 |
|
| 10099 |
\optsection{save-root-ancestor} |
| 10100 |
|
| 10101 |
This is a boolean option. The default setting is |
| 10102 |
\csopt[false]{save-root-ancestor}. If true, the entry's top-most |
| 10103 |
\gls{ancestor} will be saved in the entry's \field{rootancestor} internal |
| 10104 |
field. If the entry doesn't have a \parent\ (that it, the entry itself |
| 10105 |
is the root) then the \field{rootancestor} field won't be set. |
| 10106 |
|
| 10107 |
\optsection{flatten} |
| 10108 |
|
| 10109 |
This is a boolean option. The default value is \csopt[false]{flatten}. |
| 10110 |
If \csopt[true]{flatten}, the sorting will ignore \hierarchy\ and |
| 10111 |
the \field{parent} field will be omitted when writing |
| 10112 |
the definitions to the \ext{glstex} file, but the \glspl{parententry} |
| 10113 |
will still be considered a dependent \gls{ancestor} from the |
| 10114 |
\csopt{selection} point of view. |
| 10115 |
|
| 10116 |
Note the difference between this option and using |
| 10117 |
\csopt[parent]{ignore-fields} which will remove the dependency |
| 10118 |
(unless a dependency is established through another field). |
| 10119 |
|
| 10120 |
\optsection{flatten-lonely} |
| 10121 |
|
| 10122 |
This may take one of three values: \optfmt{false} (default), |
| 10123 |
\optfmt{presort} and \optfmt{postsort}. The value must be supplied. |
| 10124 |
|
| 10125 |
Unlike the \csopt{flatten} option, which completely |
| 10126 |
removes the \hierarchy, the \csopt{flatten-lonely} option can be used |
| 10127 |
to selectively alter the \hierarchy. In this case only those entries |
| 10128 |
that have a \parent\ but have no \glspl{sibling} are considered. This option |
| 10129 |
is affected by the \csopt{flatten-lonely-rule} setting. The conditions for |
| 10130 |
moving a \child\ up one \hierarchicallevel\ are as follows: |
| 10131 |
\begin{itemize} |
| 10132 |
\item The \child\ must have a \parent, and |
| 10133 |
\item the \child\ can't have any selected \glspl{sibling}, and |
| 10134 |
\item if \csopt[only unrecorded parents]{flatten-lonely-rule} |
| 10135 |
then the \parent\ can't have a \gls{locationlist}, where the |
| 10136 |
\gls{locationlist} includes \glspl{record} and \field{see} or \field{seealso} |
| 10137 |
cross-references (for the other rules the \parent\ |
| 10138 |
may have a \gls{locationlist} as long as it only has the one \child\ selected). |
| 10139 |
\end{itemize} |
| 10140 |
If the \child\ is selected for \hierarchical\ adjustment, |
| 10141 |
the \parent\ will be removed if: |
| 10142 |
\begin{itemize} |
| 10143 |
\item The \parent\ has no \gls{locationlist}, and |
| 10144 |
\item \csopt{flatten-lonely-rule} isn't set to \optfmt{no discard}. |
| 10145 |
\end{itemize} |
| 10146 |
|
| 10147 |
The value of \csopt{flatten-lonely} determines whether the |
| 10148 |
adjustment should be made before sorting (\optfmt{presort}) |
| 10149 |
or after sorting (\optfmt{postsort}). To disable this function |
| 10150 |
use \csopt[false]{flatten-lonely}. |
| 10151 |
|
| 10152 |
For example, suppose the file \filefmt{entries.bib} contains: |
| 10153 |
\begin{codeenv} |
| 10154 |
\atentry{index}\marg{birds} |
| 10155 |
\atentry{index}\marg{duck,\field{parent}=\marg{birds}} |
| 10156 |
\atentry{index}\marg{goose,\field{plural}=\marg{geese},\field{parent}=\marg{birds}} |
| 10157 |
\atentry{index}\marg{swan,\field{parent}=\marg{birds}} |
| 10158 |
\atentry{index}\marg{chicken,\field{parent}=\marg{birds}} |
| 10159 |
\strut |
| 10160 |
\atentry{index}\marg{vegetable} |
| 10161 |
\atentry{index}\marg{cabbage,\field{parent}=\marg{vegetable}} |
| 10162 |
\strut |
| 10163 |
\atentry{index}\marg{minerals} |
| 10164 |
\atentry{index}\marg{quartz,\field{parent}=\marg{minerals}} |
| 10165 |
\atentry{index}\marg{corundum,\field{parent}=\marg{minerals}} |
| 10166 |
\atentry{index}\marg{amethyst,\field{parent}=\marg{minerals}} |
| 10167 |
\atentry{index}\marg{gypsum,\field{parent}=\marg{minerals}} |
| 10168 |
\strut |
| 10169 |
\atentry{index}\marg{aardvark} |
| 10170 |
\atentry{index}\marg{bard} |
| 10171 |
\atentry{index}\marg{buzz} |
| 10172 |
\strut |
| 10173 |
\atentry{index}\marg{item} |
| 10174 |
\atentry{index}\marg{subitem,\field{parent}=\marg{item}} |
| 10175 |
\atentry{index}\marg{subsubitem,\field{parent}=\marg{subitem}} |
| 10176 |
\end{codeenv} |
| 10177 |
and suppose the document contains: |
| 10178 |
\begin{codeenv} |
| 10179 |
\cmd{documentclass}\marg{article} |
| 10180 |
\strut |
| 10181 |
\cmd{usepackage}[\styopt{record},\styopt[indexgroup]{style}]\marg{glossaries-extra} |
| 10182 |
\strut |
| 10183 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries.bib]{src}} |
| 10184 |
\strut |
| 10185 |
\cmd{begin}\marg{document} |
| 10186 |
\cs{gls}\marg{duck}. |
| 10187 |
\cs{gls}\marg{quartz}, \cs{gls}\marg{corundum}, \cs{gls}\marg{amethyst}. |
| 10188 |
\cs{gls}\marg{aardvark}, \cs{gls}\marg{bard}, \cs{gls}\marg{buzz}. |
| 10189 |
\cs{gls}\marg{vegetable}, \cs{gls}\marg{cabbage}. |
| 10190 |
\cs{gls}\marg{subsubitem}. |
| 10191 |
\strut |
| 10192 |
\cs{printunsrtglossaries} |
| 10193 |
\cmd{end}\marg{document} |
| 10194 |
\end{codeenv} |
| 10195 |
Although the \code{duck} entry has \glspl{sibling} in the |
| 10196 |
\filefmt{entries.bib} file, none of them have been |
| 10197 |
\glsdisp{recordedentry}{recorded} in the document, nor has the |
| 10198 |
\parent\ \code{birds} entry. |
| 10199 |
|
| 10200 |
This document hasn't used \csopt{flatten-lonely}, so the default |
| 10201 |
\csopt[false]{flatten-lonely} is assumed. This results in the |
| 10202 |
\hierarchical\ structure: |
| 10203 |
\begin{description}\setlength\itemsep{0pt}% |
| 10204 |
\item[A] \null |
| 10205 |
\item[aardvark] 1 |
| 10206 |
\item[B] \null |
| 10207 |
\item[bard] 1 |
| 10208 |
\item[birds] \mbox{} |
| 10209 |
\begin{description}\setlength\itemsep{0pt}% |
| 10210 |
\item[duck] 1 |
| 10211 |
\end{description} |
| 10212 |
\item[buzz] 1 |
| 10213 |
\item[I] \null |
| 10214 |
\item[item] \mbox{} |
| 10215 |
\begin{description}\setlength\itemsep{0pt}% |
| 10216 |
\item[subitem] \mbox{} |
| 10217 |
\begin{description}\setlength\itemsep{0pt}% |
| 10218 |
\item[subsubitem] 1 |
| 10219 |
\end{description} |
| 10220 |
\end{description} |
| 10221 |
\item[M] \null |
| 10222 |
\item[minerals] \mbox{} |
| 10223 |
\begin{description}\setlength\itemsep{0pt}% |
| 10224 |
\item[amethyst] 1 |
| 10225 |
\item[corundum] 1 |
| 10226 |
\item[quartz] 1 |
| 10227 |
\end{description} |
| 10228 |
\item[V] \null |
| 10229 |
\item[vegetable] 1 |
| 10230 |
\begin{description}\setlength\itemsep{0pt}% |
| 10231 |
\item[cabbage] 1 |
| 10232 |
\end{description} |
| 10233 |
\end{description} |
| 10234 |
(The \qt{1} in the above indicates the page number.) |
| 10235 |
There are some entries here that look a little odd: \code{duck}, |
| 10236 |
\code{cabbage} and \code{subsubitem}. In each case they are a |
| 10237 |
\glsdisp{lonelychildentry}{lone child entry}. It would look better |
| 10238 |
if they could be compressed, but I don't want to use the |
| 10239 |
\csopt{flatten} option, as I still want to keep the mineral |
| 10240 |
\hierarchy. |
| 10241 |
|
| 10242 |
If I now add \csopt[postsort]{flatten-lonely}: |
| 10243 |
\begin{codeenv} |
| 10244 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries.bib]{src},\csopt[postsort]{flatten-lonely}} |
| 10245 |
\end{codeenv} |
| 10246 |
the \hierarchy\ becomes: |
| 10247 |
\begin{description}\setlength\itemsep{0pt}% |
| 10248 |
\item[A] \null |
| 10249 |
\item[aardvark] 1 |
| 10250 |
\item[B] \null |
| 10251 |
\item[bard] 1 |
| 10252 |
\item[birds, duck] 1 |
| 10253 |
\item[buzz] 1 |
| 10254 |
\item[I] \null |
| 10255 |
\item[item, subitem, subsubitem] 1 |
| 10256 |
\item[M] \null |
| 10257 |
\item[minerals] \mbox{} |
| 10258 |
\begin{description}\setlength\itemsep{0pt}% |
| 10259 |
\item[amethyst] 1 |
| 10260 |
\item[corundum] 1 |
| 10261 |
\item[quartz] 1 |
| 10262 |
\end{description} |
| 10263 |
\item[V] \null |
| 10264 |
\item[vegetable] 1 |
| 10265 |
\begin{description}\setlength\itemsep{0pt}% |
| 10266 |
\item[cabbage] 1 |
| 10267 |
\end{description} |
| 10268 |
\end{description} |
| 10269 |
The \field{name} field of the \code{duck} entry has been |
| 10270 |
set to: |
| 10271 |
\begin{codeenv} |
| 10272 |
\field{name}=\marg{\gls{bibglsflattenedchildpostsort}\marg{birds}\marg{duck}} |
| 10273 |
\end{codeenv} |
| 10274 |
the \field{text} field has been set to: |
| 10275 |
\begin{codeenv} |
| 10276 |
\field{text}=\marg{duck} |
| 10277 |
\end{codeenv} |
| 10278 |
the \field{group} field is copied over from the \gls{parententry} (\qt{B}), |
| 10279 |
and the \field{parent} field has been adjusted, moving \code{duck} |
| 10280 |
up one \hierarchicallevel. |
| 10281 |
Finally, the former \parent\ \code{birds} entry has been removed (the default |
| 10282 |
\csopt[only unrecorded parents]{flatten-lonely-rule} is in effect). |
| 10283 |
|
| 10284 |
The default definition of \gls!{bibglsflattenedchildpostsort} |
| 10285 |
formats its arguments so that they are separated by a comma and |
| 10286 |
space (\qt{birds, duck}). If the \field{text} field had been set |
| 10287 |
in the original \atentry{index} definition of \text{duck}, it |
| 10288 |
wouldn't have been altered. This adjustment ensures that in the |
| 10289 |
document \code{\cs{gls}\marg{duck}} still produces \qt{duck} rather than |
| 10290 |
\qt{birds, duck}. |
| 10291 |
(If the \child\ and \parent\ \field{name} fields are identical, |
| 10292 |
the terms are considered \glspl{homograph}. See below for further details.) |
| 10293 |
|
| 10294 |
The \code{subsubitem} entry has also been adjusted. This was done |
| 10295 |
in a multi-stage process, starting with sub-items and then moving down |
| 10296 |
the \hierarchical\ levels: |
| 10297 |
\begin{itemize} |
| 10298 |
\item The \code{subitem} entry was adjusted, moving it from a |
| 10299 |
\gls{sub-entry} to a \gls{top-levelentry}. The \field{name} field was then |
| 10300 |
modified to: |
| 10301 |
\begin{codeenv} |
| 10302 |
\field{name}=\marg{\gls{bibglsflattenedchildpostsort}\marg{item}\marg{subitem}} |
| 10303 |
\end{codeenv} |
| 10304 |
This now means that the \code{subsubitem} entry is now a \gls{sub-entry} |
| 10305 |
(rather than a sub-sub-entry). The \code{subitem} entry now has no |
| 10306 |
\parent, but at this stage the \code{subsubitem} entry still has |
| 10307 |
\code{subitem} as its \parent. |
| 10308 |
\item The \code{subsubitem} entry is then adjusted moving from a |
| 10309 |
\gls{sub-entry} to a \gls{top-levelentry}. The \field{name} field was then |
| 10310 |
modified to: |
| 10311 |
\begin{codeenv} |
| 10312 |
\field{name}= |
| 10313 |
\marg{\comment{} |
| 10314 |
\gls{bibglsflattenedchildpostsort} |
| 10315 |
\marg{\comment{} |
| 10316 |
\comment{name from former parent} |
| 10317 |
\gls{bibglsflattenedchildpostsort}\marg{item}\marg{subitem}\comment{} |
| 10318 |
}\comment{} |
| 10319 |
\marg{subsubitem}\comment{original name} |
| 10320 |
} |
| 10321 |
\end{codeenv} |
| 10322 |
The first argument of \gls!{bibglsflattenedchildpostsort} is |
| 10323 |
obtained from the \field{name} field of the entry's former \parent\ |
| 10324 |
(which is removed from the \glsdisp{childentry}{child's} set of |
| 10325 |
\glspl{ancestor}). This field value was changed in the previous |
| 10326 |
step, and the change is reflected here. |
| 10327 |
|
| 10328 |
This means that the name for \code{subitem} will be displayed as |
| 10329 |
\qt{item, subitem} and the name for \code{subsubitem} will be |
| 10330 |
displayed as \qt{item, subitem, subsubitem}. |
| 10331 |
|
| 10332 |
\item The \glspl{parententry} \code{item} and \code{subitem} |
| 10333 |
are removed from the selection as they have no \glspl{locationlist}. |
| 10334 |
\end{itemize} |
| 10335 |
|
| 10336 |
Note that the \code{cabbage} \gls{sub-entry} hasn't been adjusted. It |
| 10337 |
doesn't have any \glspl{sibling} but its \gls{parententry} (\code{vegetable}) |
| 10338 |
has a \gls{locationlist} so it can't be discarded. |
| 10339 |
If I change the rule: |
| 10340 |
\begin{codeenv} |
| 10341 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries.bib]{src}, |
| 10342 |
\csopt[discard unrecorded]{flatten-lonely-rule}, |
| 10343 |
\csopt[postsort]{flatten-lonely} |
| 10344 |
} |
| 10345 |
\end{codeenv} |
| 10346 |
then this will move the \code{cabbage} entry up a level but the |
| 10347 |
original \gls{parententry} \code{vegetable} will remain: |
| 10348 |
\begin{description}\setlength\itemsep{0pt}% |
| 10349 |
\item[A] \null |
| 10350 |
\item[aardvark] 1 |
| 10351 |
\item[B] \null |
| 10352 |
\item[bard] 1 |
| 10353 |
\item[birds, duck] 1 |
| 10354 |
\item[buzz] 1 |
| 10355 |
\item[I] \null |
| 10356 |
\item[item, subitem, subsubitem] 1 |
| 10357 |
\item[M] \null |
| 10358 |
\item[minerals] \mbox{} |
| 10359 |
\begin{description}\setlength\itemsep{0pt}% |
| 10360 |
\item[amethyst] 1 |
| 10361 |
\item[corundum] 1 |
| 10362 |
\item[quartz] 1 |
| 10363 |
\end{description} |
| 10364 |
\item[V] \null |
| 10365 |
\item[vegetable] 1 |
| 10366 |
\item[vegetable, cabbage] 1 |
| 10367 |
\end{description} |
| 10368 |
|
| 10369 |
Remember that \csopt[postsort]{flatten-lonely} performs the |
| 10370 |
adjustment after sorting. This means that the entries are still in |
| 10371 |
the same relative location that they were in with the original |
| 10372 |
\csopt[false]{flatten-lonely} setting. For example, \code{duck} |
| 10373 |
remains in the B letter group before \qt{buzz}. |
| 10374 |
|
| 10375 |
With \csopt[presort]{flatten-lonely} the adjustments are made before |
| 10376 |
the sorting is performed. For example, using: |
| 10377 |
\begin{codeenv} |
| 10378 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries.bib]{src}, |
| 10379 |
\csopt[discard unrecorded]{flatten-lonely-rule}, |
| 10380 |
\csopt[presort]{flatten-lonely} |
| 10381 |
} |
| 10382 |
\end{codeenv} |
| 10383 |
the \hierarchical\ order is now: |
| 10384 |
\begin{description}\setlength\itemsep{0pt}% |
| 10385 |
\item[A] \null |
| 10386 |
\item[aardvark] 1 |
| 10387 |
\item[B] \null |
| 10388 |
\item[bard] 1 |
| 10389 |
\item[buzz] 1 |
| 10390 |
\item[C] \null |
| 10391 |
\item[cabbage] 1 |
| 10392 |
\item[D] \null |
| 10393 |
\item[duck] 1 |
| 10394 |
\item[M] \null |
| 10395 |
\item[minerals] \mbox{} |
| 10396 |
\begin{description}\setlength\itemsep{0pt}% |
| 10397 |
\item[amethyst] 1 |
| 10398 |
\item[corundum] 1 |
| 10399 |
\item[quartz] 1 |
| 10400 |
\end{description} |
| 10401 |
\item[S] \null |
| 10402 |
\item[subsubitem] 1 |
| 10403 |
\item[V] \null |
| 10404 |
\item[vegetable] 1 |
| 10405 |
\end{description} |
| 10406 |
This method uses a different format for the modified \field{name} |
| 10407 |
field. For example, the \code{duck} entry now has: |
| 10408 |
\begin{codeenv} |
| 10409 |
\field{name}=\marg{\gls{bibglsflattenedchildpresort}\marg{duck}\marg{birds}} |
| 10410 |
\end{codeenv} |
| 10411 |
The default definition of \gls{bibglsflattenedchildpresort} simply |
| 10412 |
does the first argument and ignores the second. The sorting is then |
| 10413 |
performed, but the interpreter recognises this command and can |
| 10414 |
deduce that the sort value for this entry should be \code{duck}, |
| 10415 |
so \qt{duck} now ends up in the D letter group. |
| 10416 |
|
| 10417 |
If you provide a definition of \gls{bibglsflattenedchildpresort} in |
| 10418 |
the \atentry{preamble}, it will be picked up by the interpreter. |
| 10419 |
For example: |
| 10420 |
\begin{codeenv} |
| 10421 |
\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\gls{bibglsflattenedchildpresort}}[2]\marg{\idx{param}1 (\idx{param}2)}}} |
| 10422 |
\end{codeenv} |
| 10423 |
|
| 10424 |
Note that the \field{text} field is only changed if not already set. |
| 10425 |
This option may have unpredictable results for abbreviations as the |
| 10426 |
\field{name} field (and sometimes the \field{text} field) is |
| 10427 |
typically set by the abbreviation style. Remember that |
| 10428 |
if the \gls{parententry} doesn't have a \igls{locationlist} and the rule isn't |
| 10429 |
set to \optfmt{no discard} then the \gls{parententry} will be discarded |
| 10430 |
after all relevant entries and their dependencies have been |
| 10431 |
selected, so any cross-references within the \gls{parententry} (such as |
| 10432 |
\ics{gls} occurring in the description) may end up being selected |
| 10433 |
even if they wouldn't be selected if the \gls{parententry} didn't exist. |
| 10434 |
|
| 10435 |
With both \optfmt{presort} and \optfmt{postsort}, if the \parent\ \field{name} |
| 10436 |
is the same as the \glsdisp{childentry}{child's} \field{name} |
| 10437 |
then the \child\ is considered a \igls{homograph} and |
| 10438 |
the \glsdisp{childentry}{child's} name is set to: |
| 10439 |
\begin{codeenv*} |
| 10440 |
\format{bibglsflattenedhomograph} |
| 10441 |
\end{codeenv*} |
| 10442 |
instead of the corresponding \csfmt{bibglsflattenedchild\ldots sort}. |
| 10443 |
This defaults to just \meta{name}. |
| 10444 |
|
| 10445 |
|
| 10446 |
\optsection{flatten-lonely-rule} |
| 10447 |
|
| 10448 |
This option governs the rule used by \csopt{flatten-lonely} to |
| 10449 |
determine which \glspl{sub-entry} (that have no \glspl{sibling}) to adjust and |
| 10450 |
which \glsdisp{parententry}{parents} to remove. The value may be one |
| 10451 |
of the following, where \meta{condition} is the condition provided |
| 10452 |
by \csopt{flatten-lonely-condition}: |
| 10453 |
\begin{description} |
| 10454 |
\item[\optfmt{only unrecorded parents}] Only the \glspl{sub-entry} |
| 10455 |
that have a \parent\ without a \igls{locationlist} (and have |
| 10456 |
\meta{condition} evaluate to true) will be altered. |
| 10457 |
The \gls{parententry} will be removed from the selection |
| 10458 |
if the child entry is adjusted. |
| 10459 |
This value is the default setting. |
| 10460 |
|
| 10461 |
\item[\optfmt{discard unrecorded}] This setting will adjust all |
| 10462 |
\glspl{sub-entry} that have no \glspl{sibling} (and have |
| 10463 |
\meta{condition} evaluate to true) regardless of whether or not the |
| 10464 |
\parent\ has a \igls{locationlist}. |
| 10465 |
Only the \glspl{parententry} that don't have a \gls{locationlist} will be |
| 10466 |
removed from the selection if the child entry is adjusted. |
| 10467 |
|
| 10468 |
\item[\optfmt{no discard}] This setting will adjust all |
| 10469 |
\glspl{sub-entry} that don't have \glspl{sibling} (and have |
| 10470 |
\meta{condition} evaluate to true) regardless of whether or not the |
| 10471 |
\parent\ has a \igls{locationlist}. No entries will be discarded, so |
| 10472 |
\glspl{parententry} that don't have a \igls{locationlist} will still appear in the |
| 10473 |
glossary. |
| 10474 |
\end{description} |
| 10475 |
In the above, the \igls{locationlist} includes \glspl{record} and |
| 10476 |
cross-references obtained from the \field{see} or \field{seealso} |
| 10477 |
fields. See \csopt{flatten-lonely} for further details. |
| 10478 |
|
| 10479 |
\optsection{flatten-lonely-condition} |
| 10480 |
|
| 10481 |
The value may either be empty, to indicate true (the default), or a |
| 10482 |
complex condition using syntax described in |
| 10483 |
\sectionref{sec:conditionals}. After taking into account |
| 10484 |
\csopt{flatten-lonely} and \csopt{flatten-lonely-rule}, this option |
| 10485 |
determines whether or not the child entry will be adjusted. If the |
| 10486 |
condition evaluates to false, the child entry won't be adjusted. |
| 10487 |
|
| 10488 |
For example, if both the parent entry and the child entry have long |
| 10489 |
names, it may be better to keep their hierarchy. The following |
| 10490 |
will only flatten lonely entries where both the child name and the |
| 10491 |
parent name have less then 25 characters: |
| 10492 |
\begin{codeenv*} |
| 10493 |
\csopt[postsort]{flatten-lonely}, |
| 10494 |
\csopt[\gls{LEN}\marg{parent \idx{follow} \field{name}} \idx{ltcmp} 25 \idx{ampand} \gls{LEN}\marg{\field{name}} \idx{ltcmp} 25]{flatten-lonely-condition} |
| 10495 |
\end{codeenv*} |
| 10496 |
Alternatively, for a combined length of less than 50 characters: |
| 10497 |
\begin{codeenv*} |
| 10498 |
\csopt[postsort]{flatten-lonely}, |
| 10499 |
\csopt[\gls{LEN}\marg{parent \idx{follow} \field{name} \idx{concat-plus} \field{name}} \idx{ltcmp} 50]{flatten-lonely-condition} |
| 10500 |
\end{codeenv*} |
| 10501 |
This doesn't include the number of characters taken up by the |
| 10502 |
separator but the maximum value can be adjusted to allow for that, |
| 10503 |
given a constant string separator. |
| 10504 |
|
| 10505 |
\optsection{flatten-lonely-missing-field-action} |
| 10506 |
|
| 10507 |
This option indicates what to do if a source field identified in |
| 10508 |
\csopt{flatten-lonely-condition} is missing. The value may be one of: |
| 10509 |
\begin{itemize} |
| 10510 |
\item \optfmt{skip}: return null; |
| 10511 |
\item \optfmt{fallback}: use the fallback for the missing field |
| 10512 |
(see \sectionref{sec:fallbacks}), if |
| 10513 |
one is available, otherwise return null (default); |
| 10514 |
\item \optfmt{empty}: treat the missing value as empty. |
| 10515 |
\end{itemize} |
| 10516 |
Returning null will result in the flatten lonely instruction being omitted. |
| 10517 |
|
| 10518 |
\optsection{strip-missing-parents} |
| 10519 |
|
| 10520 |
The \sty{glossaries} package requires that all \glspl{childentry} must be |
| 10521 |
defined after the \gls{parententry}. An error occurs otherwise, so |
| 10522 |
\bibgls\ will omit the \field{parent} field if it can't be found in |
| 10523 |
the given \igls{resourceset}. However, when the default |
| 10524 |
\csopt[false]{strip-missing-parents} is on, this omission only occurs |
| 10525 |
while writing the definitions in the \ext{glstex} file (after |
| 10526 |
selection and sorting). |
| 10527 |
|
| 10528 |
Sorting is performed \hierarchically\ and the \field{group} field is |
| 10529 |
set accordingly for the \glspl{top-levelentry} (but not for |
| 10530 |
\glspl{childentry}), which means that an entry with a \field{parent} |
| 10531 |
field will be treated by the sort method as a \gls{childentry}. This can |
| 10532 |
lead to a strange result, which \bibgls\ warns about: |
| 10533 |
\begin{alltt} |
| 10534 |
Parent '\meta{parent id}' not found for entry \meta{child-id} |
| 10535 |
\end{alltt} |
| 10536 |
|
| 10537 |
This is the default behaviour as it may simply be a result of a |
| 10538 |
typing mistake in the \field{parent} field. If you actually want |
| 10539 |
missing \glsdisp{parententry}{parents} to be stripped before sorting (but after the |
| 10540 |
selection process) then use \csopt[true]{strip-missing-parents}. If |
| 10541 |
you want all \glsdisp{parententry}{parents} stripped then use \csopt{flatten} or |
| 10542 |
\csopt[parent]{ignore-fields} instead. As from version 1.4, if you |
| 10543 |
want \bibgls\ to create the missing \glsdisp{parententry}{parents}, then you can use |
| 10544 |
\csopt[create]{missing-parents}. |
| 10545 |
|
| 10546 |
\optsection{missing-parents} |
| 10547 |
|
| 10548 |
As an alternative to \csopt{strip-missing-parents}, as from version |
| 10549 |
1.4 you can now use \csopt[\meta{value}]{missing-parents} where |
| 10550 |
\meta{value} may be one of: |
| 10551 |
\begin{itemize} |
| 10552 |
\item \optfmt{strip}: this is equivalent to |
| 10553 |
\csopt[true]{strip-missing-parents}; |
| 10554 |
|
| 10555 |
\item \optfmt{warn}: this is equivalent to the default |
| 10556 |
\csopt[false]{strip-missing-parents}; |
| 10557 |
|
| 10558 |
\item \optfmt{create}: this will create a new \atentry{index} entry |
| 10559 |
with the missing \glsdisp{parententry}{parent's} label (after it's |
| 10560 |
been processed by options such as \csopt{labelify}) with the |
| 10561 |
\field{name} obtained from the \emph{original} value of the |
| 10562 |
\field{parent} field (before being processed by options like |
| 10563 |
\csopt{labelify}). If the \gls{childentry} has the \field{type} field |
| 10564 |
set, then the new \gls{parententry} will be given the same value. The |
| 10565 |
\field{category} for the new \gls{parententry} can be assigned with |
| 10566 |
\csopt{missing-parent-category}. |
| 10567 |
\end{itemize} |
| 10568 |
|
| 10569 |
For example, consider the \exfile!{books.bib} file which contains |
| 10570 |
entries like: |
| 10571 |
\begin{codeenv} |
| 10572 |
\atentry{entry}\marg{ubik, |
| 10573 |
\field{name}=\marg{Ubik}, |
| 10574 |
\field{description}=\marg{novel by Philip K. Dick}, |
| 10575 |
\fieldfmt{identifier}=\marg{book}, |
| 10576 |
\fieldfmt{author}=\marg{\gls{sortmediacreator}\marg{Philip K.}\marg{Dick}}, |
| 10577 |
\fieldfmt{year}=\marg{1969} |
| 10578 |
} |
| 10579 |
\end{codeenv} |
| 10580 |
then the field alias: |
| 10581 |
\begin{codeenv} |
| 10582 |
\csopt[\fieldfmt{author}=\field{parent}]{field-aliases} |
| 10583 |
\end{codeenv} |
| 10584 |
will treat: |
| 10585 |
\begin{codeenv} |
| 10586 |
\fieldfmt{author}=\marg{\gls{sortmediacreator}\marg{Philip K.}\marg{Dick}}, |
| 10587 |
\end{codeenv} |
| 10588 |
as though it had been defined as: |
| 10589 |
\begin{codeenv} |
| 10590 |
\field{parent}=\marg{\gls{sortmediacreator}\marg{Philip K.}\marg{Dick}}, |
| 10591 |
\end{codeenv} |
| 10592 |
This can be converted into a label with the options: |
| 10593 |
\begin{codeenv} |
| 10594 |
\csopt[parent]{labelify}, |
| 10595 |
\csopt[ |
| 10596 |
\marg{[ \cs{cs.string}\csfmt{.}]}\marg{} |
| 10597 |
]{labelify-replace} |
| 10598 |
\end{codeenv} |
| 10599 |
If the interpreter has been provided with the definition: |
| 10600 |
\begin{codeenv} |
| 10601 |
\cs{providecommand}*\marg{\gls{sortmediacreator}}[2]\marg{\idx{param}2 \idx{param}1} |
| 10602 |
\end{codeenv} |
| 10603 |
then the \field{parent} field for the \code{ubik} entry |
| 10604 |
will become \code{DickPhilipK} but the original value is stored |
| 10605 |
internally when \csopt[create]{missing-parents} is set so that it |
| 10606 |
can be used as the \field{name} if the \parent\ needs to be created. |
| 10607 |
Once all the entries have been processed, if \code{ubik} has been |
| 10608 |
selected but no entry can be found with the label \code{DickPhilipK} |
| 10609 |
then a new entry will be added as though it had been defined with: |
| 10610 |
\begin{codeenv} |
| 10611 |
\atentry{index}\marg{DickPhilipK, |
| 10612 |
\field{name}=\marg{\gls{sortmediacreator}\marg{Philip K.}\marg{Dick}} |
| 10613 |
} |
| 10614 |
\end{codeenv} |
| 10615 |
This is an alternative approach to the \exfile{sample-authors.tex} |
| 10616 |
document from the \hyperref[sec:examples]{examples chapter}. |
| 10617 |
|
| 10618 |
\optsection{missing-parent-category} |
| 10619 |
|
| 10620 |
If a missing \gls{parententry} is created through the use of |
| 10621 |
\csopt[create]{missing-parents} then the \field{category} field can |
| 10622 |
be assigned to the new \gls{parententry} with this option. The |
| 10623 |
\meta{value} may be one of: |
| 10624 |
\begin{itemize} |
| 10625 |
\item \code{same as child}: the \gls{parententry}['s] \field{category} |
| 10626 |
field is set to the same value as the \glsdisp{childentry}{child's} (if set); |
| 10627 |
\item \code{same as base}: the \gls{parententry}['s] \field{category} is |
| 10628 |
set to the base name of the \ext{bib} file that provided the |
| 10629 |
\gls{childentry}['s] definition; |
| 10630 |
\item \code{no value} or \code{false}: don't set the \field{category} field; |
| 10631 |
\item \meta{label}: the \gls{parententry}['s] \field{category} field is set to |
| 10632 |
\meta{label} (which shouldn't contain any special characters). |
| 10633 |
\end{itemize} |
| 10634 |
The default setting is \csopt[no value]{missing-parent-category}. |
| 10635 |
|
| 10636 |
\optsection{group-level} |
| 10637 |
|
| 10638 |
If letter \idx{group} formation is enabled (see \csopt{group}, |
| 10639 |
\csopt{group-formation} and \longarg{group}) then the default |
| 10640 |
behaviour is to only assign the group label for \glspl{top-levelentry}. |
| 10641 |
This option allows the group label to be assigned to \glspl{sub-entry} |
| 10642 |
if \idxpl{sub-group} are required. |
| 10643 |
The value may be one of the following: |
| 10644 |
\begin{itemize} |
| 10645 |
\item \meta{n}: only assign the group for level~\meta{n} entries; |
| 10646 |
\item \code{>}\meta{n}: only assign the group for entries with a |
| 10647 |
level greater than \meta{n}; |
| 10648 |
\item \code{>=}\meta{n}: only assign the group for entries with a |
| 10649 |
level greater than or equal to \meta{n}; |
| 10650 |
\item \code{<}\meta{n}: only assign the group for entries with a |
| 10651 |
level less than \meta{n}; |
| 10652 |
\item \code{<=}\meta{n}: only assign the group for entries with a |
| 10653 |
level less than or equal to \meta{n}; |
| 10654 |
\item \code{all}: equivalent to \csopt[>=0]{group-level}. |
| 10655 |
\end{itemize} |
| 10656 |
The default setting is \csopt[0]{group-level}. |
| 10657 |
If no value is provided, \csopt[all]{group-level} is assumed. The |
| 10658 |
hierarchical levels start at 0 (\gls{top-levelentry}). For any value |
| 10659 |
other than \csopt[0]{group-level}, the parent entry label will be |
| 10660 |
included in the group label. |
| 10661 |
|
| 10662 |
The \idx{hiergroup} titles are formatted according to |
| 10663 |
\gls{bibglshiersubgrouptitle}. If the group title would |
| 10664 |
usually be set with the command \csfmt{bibglsset\ldots group} |
| 10665 |
for \glspl{top-levelentry} then the \idx{hiergroup} title would |
| 10666 |
be set with the analogous \csfmt{bibglsset\ldots group} command. |
| 10667 |
For example, letter groups are normally set with |
| 10668 |
\gls{bibglssetlettergrouptitle} but hierarchical letter groups are set |
| 10669 |
with \gls{bibglssetlettergrouptitlehier}. |
| 10670 |
|
| 10671 |
If the \longarg{no-group} setting is on then this option has no effect. |
| 10672 |
|
| 10673 |
\begin{important} |
| 10674 |
Any value other than the default \csopt[0]{group-level} requires |
| 10675 |
\sty{glossaries-extra} v1.49+, which provides \cs{glssubgroupheading}. |
| 10676 |
\end{important} |
| 10677 |
|
| 10678 |
\Idxpl{sub-group} are implemented by the glossary style command: |
| 10679 |
\nosecformatdef{glssubgroupheading} |
| 10680 |
The \sty{glossaries-extra} package automatically implements: |
| 10681 |
\begin{codeenv} |
| 10682 |
\cmd{renewcommand}*\marg{\cs{glssubgroupheading}}[4]\marg{\cs{glsgroupheading}\marg{\idx{param}4}} |
| 10683 |
\end{codeenv} |
| 10684 |
whenever a style is set, so that if the style doesn't provide a |
| 10685 |
definition for this command, it will behave like \cs{glsgroupheading}. |
| 10686 |
|
| 10687 |
\optsection{merge-small-groups} |
| 10688 |
|
| 10689 |
Merges consecutive \idxpl{smallgroup} that have less than \meta{n} entries. The |
| 10690 |
default is \csopt[0]{merge-small-groups}, which switches off this |
| 10691 |
action. If \meta{n} is omitted, \csopt[1]{merge-small-groups} is |
| 10692 |
assumed. |
| 10693 |
|
| 10694 |
This setting only has an effect if group formation is enabled. |
| 10695 |
If hierarchical \idxpl{sub-group} are enabled (\csopt{group-level}) then |
| 10696 |
merging is only performed on consecutive small groups within the |
| 10697 |
same hierarchical level. Any \glspl{childentry} that aren't in their |
| 10698 |
own \idx{sub-group} are included in the higher level group count. |
| 10699 |
|
| 10700 |
For example, suppose you have a large number of entries in most of |
| 10701 |
the letter groups: |
| 10702 |
\begin{codeenv} |
| 10703 |
\atentry{index}\marg{aardvark} |
| 10704 |
\atentry{index}\marg{ant} |
| 10705 |
\atentry{index}\marg{alligator} |
| 10706 |
\atentry{index}\marg{ape} |
| 10707 |
\comment{etc} |
| 10708 |
\end{codeenv} |
| 10709 |
but you only have one entry in each of the \qt{X}, \qt{Y} and \qt{Z} |
| 10710 |
groups: |
| 10711 |
\begin{codeenv} |
| 10712 |
\atentry{index}\marg{xylem} |
| 10713 |
\atentry{index}\marg{yak} |
| 10714 |
\atentry{index}\marg{zebra} |
| 10715 |
\end{codeenv} |
| 10716 |
then you may prefer to merge these entries into a single group: |
| 10717 |
\begin{codeenv} |
| 10718 |
\gls{GlsXtrLoadResources}\oarg{merge-small-groups} |
| 10719 |
\end{codeenv} |
| 10720 |
The title of this merged group is obtained from |
| 10721 |
\gls{bibglsmergedgrouptitle} (or \gls{bibglsmergedgrouptitle} if |
| 10722 |
hierarchical groups have been enabled with \csopt{group-level}). |
| 10723 |
For the above example, the merged letter group would have the title |
| 10724 |
\qt{X, Y, Z}. If there are more than three groups then the middle |
| 10725 |
group titles are replace with an ellipsis. For example, if there is |
| 10726 |
also only one entry in the \qt{W} letter group, then the merged |
| 10727 |
title would be \qt{W,\ldots, Z}. |
| 10728 |
|
| 10729 |
The small groups must be consecutive (there is no group between |
| 10730 |
them) and on the same hierarchical level in order to be merged. |
| 10731 |
In the above example, if the yak entry isn't selected so that there |
| 10732 |
is no \qt{Y} letter group, then the \qt{X} and \qt{Z} groups can be |
| 10733 |
merged (with the merged title \qt{X, Z}). If, on the other hand, |
| 10734 |
extra entries occur in the \qt{Y} letter group, so that it is larger |
| 10735 |
than the value of \csopt{merge-small-groups}, then \qt{X} and |
| 10736 |
\qt{Z} can no longer be merged. |
| 10737 |
|
| 10738 |
\section{Master Documents} |
| 10739 |
\label{sec:master} |
| 10740 |
|
| 10741 |
Suppose you have two documents \filefmt{mybook.tex} and |
| 10742 |
\filefmt{myarticle.tex} that share a common glossary that's shown |
| 10743 |
in \filefmt{mybook.pdf} but not in \filefmt{myarticle.pdf}. |
| 10744 |
Furthermore, you'd like to use \isty{hyperref} and be able to click |
| 10745 |
on a term in \filefmt{myarticle.pdf} and be taken to the relevant |
| 10746 |
page in \filefmt{mybook.pdf} where the term is listed in the |
| 10747 |
glossary. |
| 10748 |
|
| 10749 |
This can be achieved with the \catattr{targeturl} and |
| 10750 |
\catattr{targetname} category attributes. For example, without |
| 10751 |
\bibgls\ the file \filefmt{mybook.tex} might look like: |
| 10752 |
\begin{codeenv} |
| 10753 |
\cmd{documentclass}\marg{book} |
| 10754 |
\cmd{usepackage}[colorlinks]\marg{hyperref} |
| 10755 |
\cmd{usepackage}\marg{glossaries-extra} |
| 10756 |
\strut |
| 10757 |
\cs{cs.makeglossaries} |
| 10758 |
\strut |
| 10759 |
\gls{newglossaryentry}\marg{sample}\marg{\field{name}=\marg{sample},\field{description}=\marg{an example}} |
| 10760 |
\strut |
| 10761 |
\cmd{begin}\marg{document} |
| 10762 |
\cs{chapter}\marg{Example} |
| 10763 |
\cs{gls}\marg{sample}. |
| 10764 |
\strut |
| 10765 |
\cs{printglossaries} |
| 10766 |
\cmd{end}\marg{document} |
| 10767 |
\end{codeenv} |
| 10768 |
The other document \filefmt{myarticle.tex} might look like: |
| 10769 |
\begin{codeenv} |
| 10770 |
\cmd{documentclass}\marg{article} |
| 10771 |
\cmd{usepackage}[colorlinks]\marg{hyperref} |
| 10772 |
\cmd{usepackage}\marg{glossaries-extra} |
| 10773 |
\strut |
| 10774 |
\cs{newignoredglossary*}\marg{external} |
| 10775 |
\ics{glssetcategoryattribute}\marg{external}\marg{targeturl}\marg{mybook.pdf} |
| 10776 |
\cs{glssetcategoryattribute}\marg{external}\marg{targetname}\marg{\cs{glolinkprefix}\cs{glslabel}} |
| 10777 |
\strut |
| 10778 |
\gls{newglossaryentry}\marg{sample}\marg{\field{type}=external,\field{category}=external, |
| 10779 |
\field{name}=\marg{sample},\field{description}=\marg{an example}} |
| 10780 |
\strut |
| 10781 |
\cmd{begin}\marg{document} |
| 10782 |
\cs{gls}\marg{sample}. |
| 10783 |
\cmd{end}\marg{document} |
| 10784 |
\end{codeenv} |
| 10785 |
In this case the \mainglossary\ isn't used, but the category |
| 10786 |
attributes allow a mixture of internal and external references, so |
| 10787 |
the \mainglossary\ could be used for the internal |
| 10788 |
references. (In which case, \csfmt{makeglossaries} and |
| 10789 |
\csfmt{printglossaries} would need to be added back to |
| 10790 |
\filefmt{myarticle.tex}.) |
| 10791 |
|
| 10792 |
Note that both documents had to define the common terms. The above |
| 10793 |
documents can be rewritten to work with \bibgls. First a \ext{bib} |
| 10794 |
file needs to be created: |
| 10795 |
\begin{codeenv} |
| 10796 |
\atentry{entry}\marg{sample, |
| 10797 |
\field{name}=\marg{sample}, |
| 10798 |
\field{description}=\marg{an example} |
| 10799 |
} |
| 10800 |
\end{codeenv} |
| 10801 |
Assuming this file is called \filefmt{myentries.bib}, then |
| 10802 |
\filefmt{mybook.tex} can be changed to: |
| 10803 |
\begin{codeenv} |
| 10804 |
\cmd{documentclass}\marg{book} |
| 10805 |
\cmd{usepackage}[colorlinks]\marg{hyperref} |
| 10806 |
\cmd{usepackage}[record]\marg{glossaries-extra} |
| 10807 |
\strut |
| 10808 |
\gls{GlsXtrLoadResources}\oarg{\csopt[myentries]{src}} |
| 10809 |
\strut |
| 10810 |
\cmd{begin}\marg{document} |
| 10811 |
\cs{chapter}\marg{Example} |
| 10812 |
\cs{gls}\marg{sample}. |
| 10813 |
\strut |
| 10814 |
\cs{printunsrtglossaries} |
| 10815 |
\cmd{end}\marg{document} |
| 10816 |
\end{codeenv} |
| 10817 |
and \filefmt{myarticle.tex} can be changed to: |
| 10818 |
\begin{codeenv} |
| 10819 |
\cmd{documentclass}\marg{article} |
| 10820 |
\cmd{usepackage}[colorlinks]\marg{hyperref} |
| 10821 |
\cmd{usepackage}[record]\marg{glossaries-extra} |
| 10822 |
\strut |
| 10823 |
\cs{newignoredglossary*}\marg{external} |
| 10824 |
\cs{glssetcategoryattribute}\marg{external}\marg{targeturl}\marg{mybook.pdf} |
| 10825 |
\cs{glssetcategoryattribute}\marg{external}\marg{targetname}\marg{\cs{glolinkprefix}\cs{glslabel}} |
| 10826 |
\strut |
| 10827 |
\gls{GlsXtrLoadResources}\oarg{ |
| 10828 |
\csopt[myentries]{src}, |
| 10829 |
\csopt[none]{sort}, |
| 10830 |
\csopt[external]{type}, |
| 10831 |
\csopt[external]{category} |
| 10832 |
} |
| 10833 |
\strut |
| 10834 |
\cmd{begin}\marg{document} |
| 10835 |
\cs{gls}\marg{sample}. |
| 10836 |
\cmd{end}\marg{document} |
| 10837 |
\end{codeenv} |
| 10838 |
Most of the options related to sorting and the glossary format are |
| 10839 |
unneeded here since the glossary isn't being displayed. This may be |
| 10840 |
sufficient for your needs, but it may be that the book has changed |
| 10841 |
various settings that have been written to \filefmt{mybook.glstex} |
| 10842 |
but aren't present in the \iext{bib} file (such as |
| 10843 |
\csopt[uc]{short-case-change}). In this case, you could just remember to copy |
| 10844 |
over the settings from \filefmt{mybook.tex} to |
| 10845 |
\filefmt{myarticle.tex}, but |
| 10846 |
another possibility is to simply make \filefmt{myarticle.tex} input |
| 10847 |
\filefmt{mybook.glstex} instead of using \gls{GlsXtrLoadResources}. This |
| 10848 |
can work but it's not so convenient to set the label prefix, the |
| 10849 |
type and the category. The \optfmt{master} option allows this, but |
| 10850 |
it has limitations (see below), so in complex cases (in particular |
| 10851 |
different label prefixes combined with \hierarchical\ entries or cross-references) you'll have to use |
| 10852 |
the method shown in the example code above. |
| 10853 |
|
| 10854 |
\optsection{master} |
| 10855 |
|
| 10856 |
This option will disable most of the options that relate to |
| 10857 |
parsing and processing data contained in \iext{bib} files |
| 10858 |
(since this option doesn't actually read any \ext{bib} files). |
| 10859 |
It also can't be used with \csopt[copy]{action} or \csopt[define |
| 10860 |
or copy]{action}. A value of \code{false} will switch off this |
| 10861 |
setting (the default). |
| 10862 |
|
| 10863 |
The use of \optfmt{master} isn't always suitable. In particular |
| 10864 |
if any of the terms cross-reference each other, such as through |
| 10865 |
the \field{see} or \field{seealso} field or the \field{parent} field or |
| 10866 |
using commands like \ics{gls} in any of the other fields when |
| 10867 |
the labels have been assigned prefixes. In this |
| 10868 |
case you will need to use the method described in the example above. |
| 10869 |
|
| 10870 |
The \meta{name} is the name of the \iext{aux} file for the |
| 10871 |
\gls{masterdocument} without the extension (in this case, \filefmt{mybook}). It |
| 10872 |
needs to be relative to the document referencing it or an absolute |
| 10873 |
path using forward slashes as the directory divider. Remember that |
| 10874 |
if it's a relative path, the PDF files (\filefmt{mybook.pdf} and |
| 10875 |
\filefmt{myarticle.pdf}) will also need to be located in the same |
| 10876 |
relative position. |
| 10877 |
|
| 10878 |
When \bibgls\ detects the \csopt{master} option, it won't search for |
| 10879 |
entries in any \ext{bib} files (for that particular resource set) |
| 10880 |
but will create a \iext{glstex} file that inputs the |
| 10881 |
\gls{masterdocument}['s] \ext{glstex} files, but it will |
| 10882 |
additionally temporarily adjust the internal commands used to define |
| 10883 |
entries so that the prefix given by \csopt{label-prefix}, the |
| 10884 |
glossary type and the category type are all automatically inserted. |
| 10885 |
If the \csopt{type} or \csopt{category} options haven't been used, |
| 10886 |
the corresponding value will default to \optfmt{master}. The |
| 10887 |
\catattr{targeturl} and \catattr{targetname} category attributes |
| 10888 |
will automatically be set, and the glossary type will be provided |
| 10889 |
using \code{\ics{provideignoredglossary*}\margm{type}} (even if |
| 10890 |
\longarg{no-provide-glossaries} is set). |
| 10891 |
|
| 10892 |
The above \filefmt{myarticle.tex} can be changed to: |
| 10893 |
\begin{codeenv} |
| 10894 |
\cmd{documentclass}\marg{article} |
| 10895 |
\cmd{usepackage}[colorlinks]\marg{hyperref} |
| 10896 |
\cmd{usepackage}[record]\marg{glossaries-extra} |
| 10897 |
\strut |
| 10898 |
\gls{GlsXtrLoadResources}\oarg{\csopt[book.]{label-prefix},\csopt[mybook]{master}} |
| 10899 |
\strut |
| 10900 |
\cmd{begin}\marg{document} |
| 10901 |
\cs{gls}\marg{book.sample}. |
| 10902 |
\cmd{end}\marg{document} |
| 10903 |
\end{codeenv} |
| 10904 |
|
| 10905 |
There are some settings from the \gls{masterdocument} that you |
| 10906 |
still need to repeat in the other document. These include |
| 10907 |
the label prefixes set when the \gls{masterdocument} loaded |
| 10908 |
the resource files, and any settings in the \gls{masterdocument} |
| 10909 |
that relate to the \gls{masterdocument}['s] entries. |
| 10910 |
|
| 10911 |
For example, if the \gls{masterdocument} loaded a resource file |
| 10912 |
with \csopt[term.]{label-prefix} then you also need this |
| 10913 |
prefix when you reference the entries in the dependent document |
| 10914 |
in addition to the \optfmt{label-prefix} for the dependent document. |
| 10915 |
Suppose \filefmt{mybook.tex} loads the resources using: |
| 10916 |
\begin{codeenv} |
| 10917 |
\gls{GlsXtrLoadResources}\oarg{\csopt[myentries]{src},\csopt[term.]{label-prefix}} |
| 10918 |
\end{codeenv} |
| 10919 |
and \filefmt{myarticle.tex} loads the resources using: |
| 10920 |
\begin{codeenv} |
| 10921 |
\gls{GlsXtrLoadResources}\oarg{\csopt[book.]{label-prefix},\csopt[mybook]{master}} |
| 10922 |
\end{codeenv} |
| 10923 |
Then the entries referenced in \filefmt{myarticle.tex} need |
| 10924 |
to use the prefix \optfmt{book.term.}\ as in: |
| 10925 |
\begin{codeenv} |
| 10926 |
This is a \cs{gls}\marg{book.term.sample} term. |
| 10927 |
\end{codeenv} |
| 10928 |
|
| 10929 |
Remember that the category labels will need adjusting to reflect the |
| 10930 |
change in category label in the dependent document. |
| 10931 |
|
| 10932 |
For example, if \filefmt{mybook.tex} included: |
| 10933 |
\begin{codeenv} |
| 10934 |
\cs{setabbreviationstyle}\marg{long-short-sc} |
| 10935 |
\end{codeenv} |
| 10936 |
then \filefmt{myarticle.tex} will need: |
| 10937 |
\begin{codeenv} |
| 10938 |
\cs{setabbreviationstyle}\oarg{master}\marg{long-short-sc} |
| 10939 |
\end{codeenv} |
| 10940 |
(change \optfmt{master} to \meta{value} if you have used |
| 10941 |
\csopt[\meta{value}]{category}). You can, of course, choose |
| 10942 |
a different abbreviation style for the dependent document, |
| 10943 |
but the category in the optional argument needs to be correct. |
| 10944 |
|
| 10945 |
\optsection{master-resources} |
| 10946 |
|
| 10947 |
If the \gls{masterdocument} has multiple resource files |
| 10948 |
then by default all the \gls{masterdocument}['s] |
| 10949 |
\iext{glstex} files will be input. If you don't want them all |
| 10950 |
you can use \optfmt{master-resources} to specify |
| 10951 |
only those files that should be included. The value \meta{list} is |
| 10952 |
a comma-separated list of names, where each name corresponds |
| 10953 |
to the basename of the applicable \gls{resourceset}. |
| 10954 |
The file \primaryresourcefmt\ is considered the primary resource |
| 10955 |
file and the files \suppresourcefmt{\meta{n}} (starting with |
| 10956 |
\meta{n} equal to 1) are considered the supplementary resource |
| 10957 |
files. |
| 10958 |
|
| 10959 |
For example, to just select the first and third of the |
| 10960 |
supplementary resource files (omitting the primary |
| 10961 |
\filefmt{mybook.glstex}): |
| 10962 |
\begin{codeenv} |
| 10963 |
\gls{GlsXtrLoadResources}\oarg{ |
| 10964 |
\csopt[mybook]{master}, |
| 10965 |
\csopt[mybook-1,mybook-3]{master-resources} |
| 10966 |
} |
| 10967 |
\end{codeenv} |
| 10968 |
|
| 10969 |
\section{Field and Label Options} |
| 10970 |
\label{sec:fieldlabelopts} |
| 10971 |
|
| 10972 |
The options in this section may be used to set or adjust field |
| 10973 |
values or labels. Some field values are expected to be labels (such |
| 10974 |
as \field{group}). These labels must not contain special |
| 10975 |
characters or commands, but it's possible to convert a field value |
| 10976 |
into a valid label using options such as \csopt{labelify}. |
| 10977 |
|
| 10978 |
\subsection{Entry Labels} |
| 10979 |
\label{sec:labelopts} |
| 10980 |
|
| 10981 |
\optsection[\subsubsection]{interpret-label-fields} |
| 10982 |
|
| 10983 |
This is a boolean option that determines whether or not the fields |
| 10984 |
that may only contain labels should have their values interpreted |
| 10985 |
(\field{parent}, \field{category}, \field{type}, \field{group}, |
| 10986 |
\field{seealso} and \field{alias}). Although this option interprets |
| 10987 |
commands within those fields, it doesn't strip any characters that |
| 10988 |
can't be used within a label. The \field{see} field isn't included |
| 10989 |
as it may optionally start with \code{\oargm{tag}} where \meta{tag} |
| 10990 |
may legitimately contain \LaTeX\ code that shouldn't be interpreted. |
| 10991 |
|
| 10992 |
The default setting is \csopt[false]{interpret-label-fields}. |
| 10993 |
Note that if this setting is on, \iglspl{crossresourceref} aren't |
| 10994 |
permitted. This setting has no effect if the interpreter has been |
| 10995 |
disabled. |
| 10996 |
|
| 10997 |
Related settings are \csopt{labelify} and |
| 10998 |
\csopt{labelify-list} which can be used to strip content that |
| 10999 |
can't be used in labels and may be used more generally for other |
| 11000 |
fields. The \csopt{labelify} and \csopt{labelify-list} options |
| 11001 |
are performed before \csopt{interpret-label-fields}. |
| 11002 |
|
| 11003 |
\optsection[\subsubsection]{labelify} |
| 11004 |
|
| 11005 |
This option should take a comma-separated list of recognised field names as the |
| 11006 |
value. (If a field is present in both \csopt{labelify} and |
| 11007 |
\csopt{labelify-list}, then \csopt{labelify-list} takes precedence.) |
| 11008 |
Note that if this setting is on, \iglspl{crossresourceref} aren't |
| 11009 |
permitted. The value is required for this key but may be empty, |
| 11010 |
which indicates an empty set of fields (that is, the setting is |
| 11011 |
switched off). |
| 11012 |
|
| 11013 |
Each listed field will be converted into a string suitable |
| 11014 |
for use as a label. (Not necessarily a glossary entry label, but |
| 11015 |
any label that may be used in the construction of a control sequence |
| 11016 |
name.) |
| 11017 |
|
| 11018 |
The conversion is performed in the following order: |
| 11019 |
\begin{enumerate} |
| 11020 |
\item If the interpreter is on and the field value contains |
| 11021 |
any of the characters \idx{escchar}~(backslash), |
| 11022 |
\idx{bgroupchar}~(begin group), \idx{egroupchar}~(end group), |
| 11023 |
\idx{nbspchar}~(non-breakable space) or \idx{mshiftchar}~(maths shift), |
| 11024 |
then the value is interpreted. |
| 11025 |
|
| 11026 |
\item Any substitutions that have been specified with |
| 11027 |
\csopt{labelify-replace} are performed. |
| 11028 |
|
| 11029 |
\item All characters that aren't alphanumeric or the space character |
| 11030 |
or any of the following punctuation |
| 11031 |
characters \code{.}~(full stop), \code{-}~(hyphen), \code{+}~(plus), |
| 11032 |
\code{:}~(colon), \code{;}~(semi-colon), \code{\string|}~(pipe), |
| 11033 |
\code{/}~(forward slash), \code{!}~(exclamation mark), |
| 11034 |
\code{?}~(question mark), \code{*}~(asterisk), \code{<}~(less than), |
| 11035 |
\code{>}~(greater than), \code{\textasciigrave}~(backtick), |
| 11036 |
\code{'}~(apostrophe) or \code{@}~(at-sign) are stripped. If you want to |
| 11037 |
retain commas, use \csopt{labelify-list} instead. If you want to |
| 11038 |
strip any of the allowed punctuation, use \csopt{labelify-replace} to |
| 11039 |
remove the unwanted characters. (Remember that \isty{babel} can make |
| 11040 |
some of these punctuation characters active, in which case they need |
| 11041 |
to be stripped.) |
| 11042 |
|
| 11043 |
\item If \bibgls\ doesn't allow non-ASCII characters in labels, the |
| 11044 |
value is then decomposed and all non-ASCII characters are removed. |
| 11045 |
UTF-8 support is automatic if \bibgls\ detects \sty{fontspec} in the document's |
| 11046 |
transcript file, otherwise UTF-8 in labels will only be supported if |
| 11047 |
\bibgls\ detects that the versions of \sty{glossaries} and \sty{glossaries-extra} |
| 11048 |
are new enough to support it. |
| 11049 |
To ensure better support for UTF-8 with \pdfLaTeX, make sure you |
| 11050 |
have a recent \TeX\ distribution and up-to-date versions of |
| 11051 |
\sty{glossaries} and \sty{glossaries-extra}. |
| 11052 |
\end{enumerate} |
| 11053 |
|
| 11054 |
For example, suppose the \ext{bib} file contains: |
| 11055 |
\begin{codeenv} |
| 11056 |
\atentry{index}\marg{sample, |
| 11057 |
\field{name}=\marg{\ics{AA} ngstr\ics{umlaut}om, \ics{O} stergaard, d'Arcy, and Fotheringay-Smythe} |
| 11058 |
} |
| 11059 |
\end{codeenv} |
| 11060 |
Then: |
| 11061 |
\begin{codeenv} |
| 11062 |
\gls{GlsXtrLoadResources}\oarg{ |
| 11063 |
\csopt[entries]{src},\comment{data in entries.bib} |
| 11064 |
\csopt[name]{labelify} |
| 11065 |
} |
| 11066 |
\end{codeenv} |
| 11067 |
will convert the \field{name} field into: |
| 11068 |
\begin{verbatim} |
| 11069 |
Angstrom stergaard d'Arcy and Fotheringay-Smythe |
| 11070 |
\end{verbatim} |
| 11071 |
if \bibgls\ doesn't support non-ASCII characters in labels otherwise it will be: |
| 11072 |
\begin{verbatim} |
| 11073 |
Ångström Østergaard d'Arcy and Fotheringay-Smythe |
| 11074 |
\end{verbatim} |
| 11075 |
Note that \O\ is considered an unmodified letter and so can't |
| 11076 |
be decomposed into a basic Latin letter with a combining diacritic. |
| 11077 |
It's therefore removed completely from the ASCII label |
| 11078 |
version. Whereas \AA\ can be decomposed into \qt{A} followed by the |
| 11079 |
\qt{combining ring above} character and \"o can be decomposed into \qt{o} |
| 11080 |
followed by the \qt{combining diaresis} character. You can use |
| 11081 |
\csopt{labelify-replace} to replace non-ASCII characters into |
| 11082 |
the closest match. Alternatively, switch to using \XeLaTeX\ or |
| 11083 |
\LuaLaTeX. |
| 11084 |
|
| 11085 |
You can use this option with \csopt{replicate-fields} if you need |
| 11086 |
to retain the original: |
| 11087 |
\begin{codeenv} |
| 11088 |
\gls{GlsXtrLoadResources}\oarg{ |
| 11089 |
\csopt[entries]{src},\comment{data in entries.bib} |
| 11090 |
\csopt[\field{name}=\marg{\field{user1}}]{replicate-fields}, |
| 11091 |
\csopt[\field{user1}]{labelify} |
| 11092 |
} |
| 11093 |
\end{codeenv} |
| 11094 |
|
| 11095 |
\optsection[\subsubsection]{labelify-list} |
| 11096 |
|
| 11097 |
This option is like \csopt{labelify} but it retains commas, as it's |
| 11098 |
designed for fields that should be converted into a comma-separated |
| 11099 |
list of labels. Any empty elements are removed. For example, with |
| 11100 |
the \ext{bib} entry from above: |
| 11101 |
\begin{codeenv} |
| 11102 |
\gls{GlsXtrLoadResources}\oarg{ |
| 11103 |
\csopt[entries]{src},\comment{data in entries.bib} |
| 11104 |
\csopt[\field{name}=\marg{\field{user1}}]{replicate-fields}, |
| 11105 |
\csopt[\field{user1}]{labelify-list} |
| 11106 |
} |
| 11107 |
\end{codeenv} |
| 11108 |
will convert the \field{user1} field into: |
| 11109 |
\begin{verbatim} |
| 11110 |
Angstrom, stergaard, d'Arcy, and Fotheringay-Smythe |
| 11111 |
\end{verbatim} |
| 11112 |
or: |
| 11113 |
\begin{verbatim} |
| 11114 |
Ångström, Østergaard, d'Arcy, and Fotheringay-Smythe |
| 11115 |
\end{verbatim} |
| 11116 |
depending on whether or not UTF-8 labels are supported. |
| 11117 |
|
| 11118 |
\optsection[\subsubsection]{labelify-replace} |
| 11119 |
|
| 11120 |
This option takes a comma-separated list as a value with each |
| 11121 |
element in the list in the form \code{\margm{regex}\margm{replacement}} |
| 11122 |
where \meta{regex} is a \gls{regular-expression} (that conforms to \href{http://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html}{Java's |
| 11123 |
Pattern class}~\cite{pattern}) and \meta{replacement} |
| 11124 |
is the replacement text. The value is required for this key but |
| 11125 |
may be empty, which indicates that the |
| 11126 |
setting is switched off. |
| 11127 |
|
| 11128 |
Remember that the argument of |
| 11129 |
\gls{GlsXtrLoadResources} is expanded when written to the \ext{aux} |
| 11130 |
file so take care to protect any special characters. For example, to |
| 11131 |
match a literal \idx{full-stop} use \cs{cs.string}\idx{cs.period} |
| 11132 |
rather than just \idx{cs.period} (backslash dot). |
| 11133 |
|
| 11134 |
In the \meta{replacement} part, you can use |
| 11135 |
\ics{glscapturedgroup}\meta{n} to reference a captured sub-sequence. |
| 11136 |
For example: |
| 11137 |
\begin{codeenv} |
| 11138 |
\csopt[\marg{([A-Z])\ics{cs.string}\idx{cs.period}}\marg{\cs{glscapturedgroup}1}]{labelify-replace} |
| 11139 |
\end{codeenv} |
| 11140 |
This removes any \idx{full-stop} that follows any of the characters |
| 11141 |
A,\ldots,Z. Alternatively, you can just use \verb|\string\$| |
| 11142 |
instead of \cs{glscapturedgroup}. If you want a literal dollar |
| 11143 |
character, you need to use \cs{glshex}\code{24} (or |
| 11144 |
\verb|\string\u24|). This isn't recommended for labels (since special |
| 11145 |
characters are automatically stripped), but |
| 11146 |
\csopt{sort-replace} follows the same rules as |
| 11147 |
\csopt{labelify-replace}, and it may be needed |
| 11148 |
for that. |
| 11149 |
|
| 11150 |
\begin{important} |
| 11151 |
You can't use the \gls{MGP} quark (which expands to the \gls{MGP} |
| 11152 |
identifier in a string \gls{concatenation}) to identify the captured group in this |
| 11153 |
context, as the replacement text needs to use the correct |
| 11154 |
\gls{regular-expression} syntax. |
| 11155 |
\end{important} |
| 11156 |
|
| 11157 |
|
| 11158 |
Both \csopt{labelify} and \csopt{labelify-list} use the |
| 11159 |
\csopt{labelify-replace} setting to |
| 11160 |
perform substitutions. For example, to replace the sub-string \qt{ and } |
| 11161 |
(including spaces) with a comma: |
| 11162 |
\begin{codeenv} |
| 11163 |
\gls{GlsXtrLoadResources}\oarg{ |
| 11164 |
\csopt[entries]{src},\comment{data in entries.bib} |
| 11165 |
\csopt[\field{name}=\marg{\field{user1}}]{replicate-fields}, |
| 11166 |
\csopt[\marg{ and }\marg{,}]{labelify-replace}, |
| 11167 |
\csopt[\field{user1}]{labelify-list} |
| 11168 |
} |
| 11169 |
\end{codeenv} |
| 11170 |
The earlier example will now end up as: |
| 11171 |
\begin{verbatim} |
| 11172 |
Angstrom, stergaard, d'Arcy,Fotheringay-Smythe |
| 11173 |
\end{verbatim} |
| 11174 |
or: |
| 11175 |
\begin{verbatim} |
| 11176 |
Ångström, Østergaard, d'Arcy,Fotheringay-Smythe |
| 11177 |
\end{verbatim} |
| 11178 |
depending on whether or not UTF-8 labels are supported. |
| 11179 |
|
| 11180 |
Note that this produces the same result regardless of whether or not |
| 11181 |
the Oxford comma is present as \verb*|, and | would first be |
| 11182 |
converted to \verb|,,| and then the empty element is removed |
| 11183 |
resulting in a single comma. |
| 11184 |
|
| 11185 |
You can have more than one replacement: |
| 11186 |
\begin{codeenv} |
| 11187 |
\gls{GlsXtrLoadResources}\oarg{ |
| 11188 |
\csopt[entries]{src},\comment{data in entries.bib} |
| 11189 |
\csopt[\field{name}=\marg{\field{user1}}]{replicate-fields}, |
| 11190 |
\csopt[ |
| 11191 |
\marg{ and }\marg{,},\comment{first substitution} |
| 11192 |
\marg{[ '\cs{cs.string}\cmd{-}]}\marg{},\comment{second substitution} |
| 11193 |
\marg{\ics{glshex}00D8}\marg{O}\comment{third substitution} |
| 11194 |
]{labelify-replace}, |
| 11195 |
\csopt[\field{user1}]{labelify-list} |
| 11196 |
} |
| 11197 |
\end{codeenv} |
| 11198 |
This additionally removes the space, apostrophe and hyphen |
| 11199 |
characters (second substitution) and replaces \qt{\O} (\hex{00D8}) |
| 11200 |
with \qt{O} (third substitution) so the string now ends up as: |
| 11201 |
\begin{verbatim} |
| 11202 |
Angstrom,Ostergaard,dArcy,FotheringaySmythe |
| 11203 |
\end{verbatim} |
| 11204 |
or: |
| 11205 |
\begin{verbatim} |
| 11206 |
Ångström,Ostergaard,dArcy,FotheringaySmythe |
| 11207 |
\end{verbatim} |
| 11208 |
depending on whether or not UTF-8 labels are supported. |
| 11209 |
|
| 11210 |
\optsection[\subsubsection]{label-prefix} |
| 11211 |
|
| 11212 |
The \csopt{label-prefix} option prepends \meta{tag} to each entry's label. This |
| 11213 |
\meta{tag} will also be inserted in front of any cross-references, unless they |
| 11214 |
start with \idprefix{dual} or \idprefix{tertiary} or \idprefix{extn} (where |
| 11215 |
\meta{n} is an integer). Use \csopt{dual-prefix} to change the dual label |
| 11216 |
prefixes and \csopt{ext-prefixes} to change the external label prefixes. |
| 11217 |
|
| 11218 |
If you set \csopt{label-prefix} and you define commands with |
| 11219 |
\gls{glsxtrnewglslike}, then any of those commands found in entry |
| 11220 |
fields won't have the \csopt{label-prefix} inserted if the prefix provided with |
| 11221 |
the command starts with the prefix given in \csopt{label-prefix}. |
| 11222 |
(This doesn't apply to other prefix options, such as |
| 11223 |
\csopt{dual-prefix}, so take care if you have a mixture of prefix |
| 11224 |
options and prefixes identified with \gls{glsxtrnewglslike}.) |
| 11225 |
|
| 11226 |
As from version 1.8, the \primary\ label prefix is identified |
| 11227 |
in the \ext{glstex} file with: |
| 11228 |
\begin{codeenv} |
| 11229 |
\format{bibglsprimaryprefixlabel} |
| 11230 |
\end{codeenv} |
| 11231 |
|
| 11232 |
For example, if the \ext{bib} file contains: |
| 11233 |
\begin{codeenv} |
| 11234 |
\atentry{entry}\marg{bird, |
| 11235 |
\field{name}=\marg{bird}, |
| 11236 |
\field{description} = \marg{feathered animal, such as a \cs{gls}\marg{duck} or \cs{gls}\marg{goose}} |
| 11237 |
} |
| 11238 |
\strut |
| 11239 |
\atentry{entry}\marg{waterfowl, |
| 11240 |
\field{name}=\marg{waterfowl}, |
| 11241 |
\field{description}=\marg{Any \cs{gls}\marg{bird} that lives in or about water}, |
| 11242 |
\field{see}=\marg{[see also]\marg{duck,goose}} |
| 11243 |
} |
| 11244 |
\strut |
| 11245 |
\atentry{index}\marg{duck} |
| 11246 |
\strut |
| 11247 |
\atentry{index}\marg{goose,\field{plural}=\qtdelim{geese}} |
| 11248 |
\end{codeenv} |
| 11249 |
Then if this \ext{bib} file is loaded with \csopt[gls.]{label-prefix} |
| 11250 |
it's as though the entries had been defined as: |
| 11251 |
\begin{codeenv} |
| 11252 |
\atentry{entry}\marg{gls.bird, |
| 11253 |
\field{name}=\marg{bird}, |
| 11254 |
\field{description} = \marg{feathered animal, such as a \cs{gls}\marg{gls.duck} or \cs{gls}\marg{gls.goose}} |
| 11255 |
} |
| 11256 |
\strut |
| 11257 |
\atentry{entry}\marg{gls.waterfowl, |
| 11258 |
\field{name}=\marg{waterfowl}, |
| 11259 |
\field{description}=\marg{Any \cs{gls}\marg{gls.bird} that lives in or about water}, |
| 11260 |
\field{see}=\marg{[see also]\marg{gls.duck,gls.goose}} |
| 11261 |
} |
| 11262 |
\strut |
| 11263 |
\atentry{index}\marg{gls.duck,\field{name}=\marg{duck}} |
| 11264 |
\strut |
| 11265 |
\atentry{index}\marg{gls.goose,\field{name}=\marg{goose},\field{plural}=\qtdelim{geese}} |
| 11266 |
\end{codeenv} |
| 11267 |
|
| 11268 |
Remember to use this prefix when you reference the terms in the |
| 11269 |
document with commands like \ics{gls}. |
| 11270 |
|
| 11271 |
\optsection[\subsubsection]{duplicate-label-suffix} |
| 11272 |
|
| 11273 |
The \sty{glossaries} package doesn't permit entries with duplicate |
| 11274 |
labels (even if they're in different glossaries). If you |
| 11275 |
have multiple \iglspl{resourceset} and an entry that's selected |
| 11276 |
in one \igls{resourceset} is also selected in another, by |
| 11277 |
default, \bibgls\ will issue a warning, but it will still write the |
| 11278 |
entry definition to the \ext{glstex} file, which means you'll also |
| 11279 |
get a warning from \sty{glossaries-extra} and the duplicate |
| 11280 |
definition will be ignored, but associated internal fields |
| 11281 |
set with commands like \cs{GlsXtrSetField} may still be set. |
| 11282 |
|
| 11283 |
If you actually want the duplicate, you need to specify a |
| 11284 |
suffix with \csopt{duplicate-label-suffix}. This suffix is only |
| 11285 |
set just before writing the entry definition to the \ext{glstex} |
| 11286 |
file, so it doesn't affect selection criteria nor can label |
| 11287 |
substitutions be performed in any cross-references. Options such as |
| 11288 |
\csopt{set-widest} that reference entry labels are incompatible |
| 11289 |
as they will use the unsuffixed label. |
| 11290 |
|
| 11291 |
The actual suffix is formed from \meta{value}\meta{n} where \meta{n} |
| 11292 |
is an integer that's incremented in the event of multiple |
| 11293 |
duplicates. For example, \csopt[.copy]{duplicate-label-suffix} will |
| 11294 |
change the label to \meta{id}\code{.copy1} for the first duplicate |
| 11295 |
of the entry whose label is \meta{id}, and \meta{id}\code{.copy2} for |
| 11296 |
the second duplicate, etc. |
| 11297 |
|
| 11298 |
\optsection[\subsubsection]{record-label-prefix} |
| 11299 |
|
| 11300 |
If set, this option will cause \bibgls\ to pretend that each record |
| 11301 |
label starts with \meta{tag}, if it doesn't already. For example, suppose |
| 11302 |
the records in the \ext{aux} file are: |
| 11303 |
\begin{codeenv} |
| 11304 |
\gls{glsxtr@record}\marg{bird}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1} |
| 11305 |
\gls{glsxtr@record}\marg{waterfowl}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1} |
| 11306 |
\gls{glsxtr@record}\marg{idx.duck}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1} |
| 11307 |
\gls{glsxtr@record}\marg{idx.goose}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1} |
| 11308 |
\end{codeenv} |
| 11309 |
The use of \csopt[idx.]{record-label-prefix} makes \bibgls\ act as |
| 11310 |
though the records were given as: |
| 11311 |
\begin{codeenv} |
| 11312 |
\gls{glsxtr@record}\marg{idx.bird}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1} |
| 11313 |
\gls{glsxtr@record}\marg{idx.waterfowl}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1} |
| 11314 |
\gls{glsxtr@record}\marg{idx.duck}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1} |
| 11315 |
\gls{glsxtr@record}\marg{idx.goose}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1} |
| 11316 |
\end{codeenv} |
| 11317 |
|
| 11318 |
|
| 11319 |
\optsection[\subsubsection]{cs-label-prefix} |
| 11320 |
|
| 11321 |
If you have commands such as \code{\ics{gls}\margm{label}} or |
| 11322 |
\code{\ics{glstext}\margm{label}} in field |
| 11323 |
values (in situations where nested link text won't cause a problem) |
| 11324 |
the \meta{label} will be converted as follows: |
| 11325 |
\begin{itemize} |
| 11326 |
\item if \meta{label} starts with \idprefix{dual} then |
| 11327 |
\idprefix{dual} will be replaced by the \csopt{dual-prefix} value; |
| 11328 |
\item if \meta{label} starts with \idprefix{tertiary} then |
| 11329 |
\idprefix{tertiary} will be replaced by the \csopt{tertiary-prefix} value; |
| 11330 |
\item if \meta{label} starts with \idprefix{extn} then |
| 11331 |
\idprefix{extn} will be replaced by the corresponding |
| 11332 |
\csopt{ext-prefixes} setting (if \igls{crossresourceref} mode is |
| 11333 |
enabled, see \sectionref{sec:resourcesets}); |
| 11334 |
\item if \meta{label} doesn't start with one of the above recognised |
| 11335 |
prefixes then, if \csopt{cs-label-prefix} has been used the supplied |
| 11336 |
value will be inserted otherwise the \csopt{label-prefix} setting |
| 11337 |
will be inserted. |
| 11338 |
\end{itemize} |
| 11339 |
For example, given: |
| 11340 |
\begin{codeenv} |
| 11341 |
\atentry{entry}\marg{bird, |
| 11342 |
\field{name}=\marg{bird}, |
| 11343 |
\field{description} = \marg{feathered animal, such as a \cs{gls}\marg{duck} or \cs{gls}\marg{goose}} |
| 11344 |
} |
| 11345 |
\end{codeenv} |
| 11346 |
then if \csopt[idx.]{label-prefix} is set but \csopt{cs-label-prefix} |
| 11347 |
isn't included in the resource option list this will convert the |
| 11348 |
\field{description} field to: |
| 11349 |
\begin{codeenv} |
| 11350 |
\field{description} = \marg{feathered animal, such as a \cs{gls}\marg{idx.duck} or |
| 11351 |
\cs{gls}\marg{idx.goose}} |
| 11352 |
\end{codeenv} |
| 11353 |
However with \csopt[gls.]{cs-label-prefix} the \field{description} |
| 11354 |
field will be converted to: |
| 11355 |
\begin{codeenv} |
| 11356 |
\field{description} = \marg{feathered animal, such as a \cs{gls}\marg{gls.duck} or |
| 11357 |
\cs{gls}\marg{gls.goose}} |
| 11358 |
\end{codeenv} |
| 11359 |
regardless of the \csopt{label-prefix} setting. Whereas if the |
| 11360 |
original entry definition is: |
| 11361 |
\begin{codeenv} |
| 11362 |
\atentry{entry}\marg{bird, |
| 11363 |
\field{name}=\marg{bird}, |
| 11364 |
\field{description} = \marg{feathered animal, such as a \cs{gls}\marg{dual.duck} or |
| 11365 |
\cs{gls}\marg{dual.goose}} |
| 11366 |
} |
| 11367 |
\end{codeenv} |
| 11368 |
then \idprefix{dual} will be replaced by the value of the |
| 11369 |
\csopt{dual-prefix} option regardless of the \csopt{cs-label-prefix} |
| 11370 |
setting. |
| 11371 |
|
| 11372 |
The \csopt{cs-label-prefix} setting doesn't affect labels in the |
| 11373 |
fields that have an entry label or label list as the value |
| 11374 |
(\field{parent}, \field{alias}, \field{see} and \field{seealso}). |
| 11375 |
|
| 11376 |
\optsection[\subsubsection]{ext-prefixes} |
| 11377 |
|
| 11378 |
Any cross-references in the \iext{bib} file that start with |
| 11379 |
\idprefix{extn} (where \meta{n} is a positive integer) will be |
| 11380 |
substituted with the \meta{n}th tag listed in the comma-separated |
| 11381 |
\meta{list}. If there aren't that many items in the list, the |
| 11382 |
\idprefix{extn} will simply be removed. The default setting is |
| 11383 |
an empty list, which will strip all \idprefix{extn} prefixes. |
| 11384 |
Remember that \igls{crossresourceref} mode needs to be enabled for |
| 11385 |
this option to work (see \sectionref{sec:resourcesets}). |
| 11386 |
|
| 11387 |
As from version 1.8, the external label prefixes are identified |
| 11388 |
in the \ext{glstex} file with: |
| 11389 |
\begin{codeenv} |
| 11390 |
\format{bibglsexternalprefixlabel} |
| 11391 |
\end{codeenv} |
| 11392 |
|
| 11393 |
For example, suppose the file \filefmt{entries-terms.bib} contains: |
| 11394 |
\begin{codeenv} |
| 11395 |
\atentry{entry}\marg{set, |
| 11396 |
\field{name}=\marg{set}, |
| 11397 |
\field{description}=\marg{collection of values, denoted \cs{gls}\marg{ext1.set}} |
| 11398 |
} |
| 11399 |
\end{codeenv} |
| 11400 |
and the file \filefmt{entries-symbols.bib} contains: |
| 11401 |
\begin{codeenv} |
| 11402 |
\atentry{symbol}\marg{set, |
| 11403 |
\field{name}=\marg{\cs{ensuremath}\marg{\cs{mathcal}\marg{S}}}, |
| 11404 |
\field{description}=\marg{a \cs{gls}\marg{ext1.set}} |
| 11405 |
} |
| 11406 |
\end{codeenv} |
| 11407 |
|
| 11408 |
These files both contain an entry with the label \code{set} |
| 11409 |
but the \field{description} field includes \code{\cs{gls}\marg{ext1.set}} |
| 11410 |
which is referencing the entry from the other file. These |
| 11411 |
two files can be loaded without conflict using: |
| 11412 |
\begin{codeenv} |
| 11413 |
\cmd{usepackage}[\styopt{record},\styopt{symbols}]\marg{glossaries-extra} |
| 11414 |
\strut |
| 11415 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries-terms]{src}, |
| 11416 |
\csopt[gls.]{label-prefix}, |
| 11417 |
\csopt[sym.]{ext-prefixes} |
| 11418 |
} |
| 11419 |
\strut |
| 11420 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries-symbols]{src}, |
| 11421 |
\csopt[symbols]{type}, |
| 11422 |
\csopt[sym.]{label-prefix}, |
| 11423 |
\csopt[gls.]{ext-prefixes} |
| 11424 |
} |
| 11425 |
\end{codeenv} |
| 11426 |
|
| 11427 |
Now the \code{set} entry from \filefmt{entries-terms.bib} |
| 11428 |
will be defined with the label \code{gls.set} and the |
| 11429 |
description will be: |
| 11430 |
\begin{codeenv} |
| 11431 |
collection of values, denoted \cs{gls}\marg{sym.set} |
| 11432 |
\end{codeenv} |
| 11433 |
The \code{set} entry |
| 11434 |
from \filefmt{entries-symbols.bib} will be defined with the label |
| 11435 |
\code{sym.set} and the description will be: |
| 11436 |
\begin{codeenv} |
| 11437 |
a \cs{gls}\marg{gls.set} |
| 11438 |
\end{codeenv} |
| 11439 |
|
| 11440 |
Note that in this case the \ext{bib} files have to be loaded |
| 11441 |
as two separate resources. They can't be combined into a |
| 11442 |
single \csopt{src} list as the labels aren't unique. |
| 11443 |
|
| 11444 |
If you want to allow the flexibility to choose between |
| 11445 |
loading them together or separately, you'll have to give them |
| 11446 |
unique labels. For example, \filefmt{entries-terms.bib} could |
| 11447 |
contain: |
| 11448 |
\begin{codeenv} |
| 11449 |
\atentry{entry}\marg{set, |
| 11450 |
\field{name}=\marg{set}, |
| 11451 |
\field{description}=\marg{collection of values, denoted \cs{gls}\marg{ext1.S}} |
| 11452 |
} |
| 11453 |
\end{codeenv} |
| 11454 |
and \filefmt{entries-symbols.bib} could contain: |
| 11455 |
\begin{codeenv} |
| 11456 |
\atentry{symbol}\marg{S, |
| 11457 |
\field{name}=\marg{\cs{ensuremath}\marg{\cs{mathcal}\marg{S}}}, |
| 11458 |
\field{description}=\marg{a \cs{gls}\marg{ext1.set}} |
| 11459 |
} |
| 11460 |
\end{codeenv} |
| 11461 |
Now they can be combined with: |
| 11462 |
\begin{codeenv} |
| 11463 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries-terms,entries-symbols]{src}} |
| 11464 |
\end{codeenv} |
| 11465 |
which will simply strip the \glsdisp{idx.idprefix.extn}{\idprefixfmt{ext1}} |
| 11466 |
prefix from the cross-references. Alternatively: |
| 11467 |
\begin{codeenv} |
| 11468 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries-terms,entries-symbols]{src}, |
| 11469 |
\csopt[gls.]{label-prefix}, |
| 11470 |
\csopt[gls.]{ext-prefixes} |
| 11471 |
} |
| 11472 |
\end{codeenv} |
| 11473 |
which will insert the supplied \csopt{label-prefix} at the |
| 11474 |
start of the labels in the entry definitions and will replace |
| 11475 |
the \idprefixfmt{ext1} prefix with \idprefixfmt{gls} in the |
| 11476 |
cross-references. |
| 11477 |
|
| 11478 |
\optsection[\subsubsection]{prefix-only-existing} |
| 11479 |
|
| 11480 |
This is a boolean option. It's possible that a prefix can end up being |
| 11481 |
inserted when there's no entry in the current \igls{resourceset} that |
| 11482 |
matches the prefixed label. If this option is set then the prefix |
| 11483 |
won't be added if there's no matching entry. The default setting is |
| 11484 |
\csopt[false]{prefix-only-existing}. |
| 11485 |
|
| 11486 |
\optsection[\subsubsection]{dependency-fields} |
| 11487 |
|
| 11488 |
The \meta{list} should be a comma-separated list of fields that |
| 11489 |
have values in the form \code{\oargm{tag}\meta{id-list}} where |
| 11490 |
\meta{id-list} is a comma-separated list of entry labels. The value |
| 11491 |
is required for this key but may be empty, which indicates an empty |
| 11492 |
set of fields (that is, the setting is switched off). |
| 11493 |
Note that the listed fields must be recognised as known fields, for |
| 11494 |
example, custom fields defined with \cs{glsaddstoragekey}. |
| 11495 |
|
| 11496 |
This setting makes those fields act like the \field{see} field by |
| 11497 |
identifying the listed entries as dependencies, but the information |
| 11498 |
isn't added to the cross-reference part of the \gls{locationlist}. This |
| 11499 |
action is performed after \csopt{labelify-list}, if that's also set. |
| 11500 |
|
| 11501 |
For example, suppose the file \filefmt{entries-en.bib} contains: |
| 11502 |
\begin{codeenv} |
| 11503 |
\atentry{index}\marg{cat, |
| 11504 |
\fieldfmt{translations-pt}=\marg{gato,gatinho}, |
| 11505 |
\field{seealso}=\marg{kitten} |
| 11506 |
} |
| 11507 |
\strut |
| 11508 |
\atentry{index}\marg{kitten, |
| 11509 |
\fieldfmt{translations-pt}=\marg{gato,gatinho} |
| 11510 |
} |
| 11511 |
\strut |
| 11512 |
\atentry{index}\marg{staple} |
| 11513 |
\atentry{index}\marg{rivet} |
| 11514 |
\atentry{index}\marg{mat} |
| 11515 |
\atentry{index}\marg{carpet} |
| 11516 |
\atentry{index}\marg{rug} |
| 11517 |
\atentry{index}\marg{tapestry} |
| 11518 |
\atentry{index}\marg{doormat} |
| 11519 |
\atentry{index}\marg{matting} |
| 11520 |
\atentry{index}\marg{coconut-matting, |
| 11521 |
\field{name}=\marg{coconut matting} |
| 11522 |
} |
| 11523 |
\atentry{index}\marg{track} |
| 11524 |
\atentry{index}\marg{furrow} |
| 11525 |
\end{codeenv} |
| 11526 |
and suppose the file \filefmt{entries-pt.bib} contains: |
| 11527 |
\begin{codeenv} |
| 11528 |
\atentry{index}\marg{gato, |
| 11529 |
\field{prefix}=\marg{o}, |
| 11530 |
\fieldfmt{translations-en}=\marg{cat,staple,rivet}, |
| 11531 |
\field{seealso}=\marg{gatinho} |
| 11532 |
} |
| 11533 |
\strut |
| 11534 |
\atentry{index}\marg{gatinho, |
| 11535 |
\fieldfmt{translations-en}=\marg{kitten} |
| 11536 |
} |
| 11537 |
\strut |
| 11538 |
\atentry{index}\marg{tapete, |
| 11539 |
\fieldfmt{translations-en}=\marg{carpet,rug,mat,tapestry} |
| 11540 |
} |
| 11541 |
\strut |
| 11542 |
\atentry{index}\marg{esteira, |
| 11543 |
\field{prefix}=\marg{a}, |
| 11544 |
\fieldfmt{translations-en}=\marg{mat,track,matting,furrow} |
| 11545 |
} |
| 11546 |
\strut |
| 11547 |
\atentry{index}\marg{capacho, |
| 11548 |
\field{prefix}=\marg{o}, |
| 11549 |
\fieldfmt{translations-en}=\marg{doormat,matting,mat,coconut-matting} |
| 11550 |
} |
| 11551 |
\end{codeenv} |
| 11552 |
The aim here is to have a document containing an |
| 11553 |
English-to-Portuguese and a Portuguese-to-English dictionary. The |
| 11554 |
custom \fieldfmt{translations-pt} and \fieldfmt{translations-pt} |
| 11555 |
fields contain comma-separated lists of possible translations. In |
| 11556 |
this case I don't want to use the \field{see} field (and, in fact, |
| 11557 |
can't for the entries that have the \field{seealso} field set), but |
| 11558 |
I can identify the values of those fields as dependent entries to |
| 11559 |
ensure that they are selected even if they're not referenced in the |
| 11560 |
document. |
| 11561 |
|
| 11562 |
For convenience I've aliased the custom fields to \field{user1}: |
| 11563 |
\begin{codeenv} |
| 11564 |
\cmd{documentclass}\marg{article} |
| 11565 |
\strut |
| 11566 |
\cmd{usepackage}[T1]\marg{fontenc} |
| 11567 |
\cmd{usepackage}[utf8]\marg{inputenc} |
| 11568 |
\cmd{usepackage}[british,brazilian]\marg{babel} |
| 11569 |
\cmd{usepackage}[colorlinks]\marg{hyperref} |
| 11570 |
\cmd{usepackage}\oarg{\styopt{record}, |
| 11571 |
\styopt{nomain}, |
| 11572 |
\styopt{nostyles}, |
| 11573 |
\styopt[bookindex]{stylemods}, |
| 11574 |
\styopt[\glostyle{bookindex}]{style} |
| 11575 |
}\marg{glossaries-extra} |
| 11576 |
\cmd{usepackage}\marg{\isty{glossaries-prefix}} |
| 11577 |
\strut |
| 11578 |
\cs{newglossary*}\marg{en}\marg{English Terms} |
| 11579 |
\cs{newglossary*}\marg{pt}\marg{Portuguese Terms} |
| 11580 |
\strut |
| 11581 |
\gls{GlsXtrLoadResources}\oarg{ |
| 11582 |
\csopt[en]{type}, |
| 11583 |
\csopt[entries-en]{src}, |
| 11584 |
\csopt[en-GB]{sort}, |
| 11585 |
\csopt[en]{category}, |
| 11586 |
\csopt[\fieldfmt{translations-pt}=\field{user1}]{field-aliases}, |
| 11587 |
\csopt[\field{user1}]{dependency-fields}, |
| 11588 |
\csopt[\field{user1}:pt-BR:\encap{glsentryname}]{sort-label-list} |
| 11589 |
} |
| 11590 |
\gls{GlsXtrLoadResources}\oarg{ |
| 11591 |
\csopt[pt]{type}, |
| 11592 |
\csopt[entries-pt]{src}, |
| 11593 |
\csopt[pt-BR]{sort}, |
| 11594 |
\csopt[pt]{category}, |
| 11595 |
\csopt[\fieldfmt{translations-en}=\field{user1}]{field-aliases}, |
| 11596 |
\csopt[\field{user1}]{dependency-fields}, |
| 11597 |
\csopt[\field{user1}:en-GB:\encap{glsentryname}]{sort-label-list} |
| 11598 |
} |
| 11599 |
\strut |
| 11600 |
\cs{apptoglossarypreamble}\oarg{en}\marg{\cs{selectlanguage}\marg{british}} |
| 11601 |
\cs{apptoglossarypreamble}\oarg{pt}\marg{\cs{selectlanguage}\marg{brazilian}} |
| 11602 |
\strut |
| 11603 |
\cmd{begin}\marg{document} |
| 11604 |
\cs{selectlanguage}\marg{british} |
| 11605 |
The \cs{gls}\marg{cat} sat on the \cs{gls}\marg{mat}. |
| 11606 |
\strut |
| 11607 |
\cs{selectlanguage}\marg{brazilian} |
| 11608 |
O \cs{gls}\marg{gato} sentou-se no \cs{gls}\marg{tapete}. |
| 11609 |
\strut |
| 11610 |
\cs{renewcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\comment{} |
| 11611 |
\cs{glsxtrifhasfield}\marg{\field{prefix}}\marg{\idx{param}1}\marg{\ics{xmakefirstuc}\cs{glscurrentfieldvalue}\cs{cs.space}}\marg{}\comment{} |
| 11612 |
\cs{glossentryname}\marg{\idx{param}1}\comment{} |
| 11613 |
\cs{glsxtrifhasfield}\marg{\field{useri}}\marg{\idx{param}1} |
| 11614 |
\marg{; translations: \cs{glsxtrseelist}\cs{glscurrentfieldvalue}}\marg{}\comment{} |
| 11615 |
} |
| 11616 |
\cs{printunsrtglossaries} |
| 11617 |
\cmd{end}\marg{document} |
| 11618 |
\end{codeenv} |
| 11619 |
|
| 11620 |
\subsection{Special Fields} |
| 11621 |
\label{sec:specialfieldopts} |
| 11622 |
|
| 11623 |
\optsection[\subsubsection]{save-original-id} |
| 11624 |
|
| 11625 |
The \meta{value} may be the keywords \code{false} or \code{true} or |
| 11626 |
the name of a field in which to store the entry's original |
| 11627 |
label (as given in the \ext{bib} file). The default setting is |
| 11628 |
\csopt[false]{save-original-id}. If \meta{value} is omitted or is the |
| 11629 |
keyword \code{true}, then \field{originalid} is assumed. |
| 11630 |
|
| 11631 |
If \meta{value} has an associated key in \gls!{newglossaryentry} |
| 11632 |
(for example, one provided with \cs{glsaddstoragekey}) it will be |
| 11633 |
set after the field aliases, otherwise (for example, |
| 11634 |
\field{originalid}) it will simply be added to the \ext{glstex} file |
| 11635 |
using \ics{GlsXtrSetField} after the entry definition (which means |
| 11636 |
the field can't be referenced in other resource options). This |
| 11637 |
setting is governed by \csopt{save-original-id-action}. |
| 11638 |
|
| 11639 |
\optsection[\subsubsection]{save-original-id-action} |
| 11640 |
|
| 11641 |
This option determines whether or not \csopt{save-original-id} |
| 11642 |
should save the original entry label. No action is performed when |
| 11643 |
\csopt[false]{save-original-id} otherwise the action is determined |
| 11644 |
by \meta{value} which may be one of the following keywords: |
| 11645 |
\begin{itemize} |
| 11646 |
\item \code{always}: always save the original label (default); |
| 11647 |
\item \code{no override}: don't override a field that's already been |
| 11648 |
set; |
| 11649 |
\item \code{changed override} or \code{changed} or \code{diff}: |
| 11650 |
only save the original label if it's different from the final label; |
| 11651 |
\item \code{changed no override}: |
| 11652 |
only save the original label if it's different from the final label |
| 11653 |
and the specified field hasn't been set. |
| 11654 |
\end{itemize} |
| 11655 |
The \qt{no override} options make no difference if the given field |
| 11656 |
has no associated key in \gls!{newglossaryentry} (such as |
| 11657 |
\field{originalid}). For known fields, bear in mind that the field |
| 11658 |
will be set after field aliasing but before other options, such as |
| 11659 |
\csopt{ignore-fields}. |
| 11660 |
|
| 11661 |
\optsection[\subsubsection]{save-definition-index} |
| 11662 |
|
| 11663 |
This is a boolean option. If the value is omitted \code{true} is |
| 11664 |
assumed. The default setting is \csopt[false]{save-definition-index}. |
| 11665 |
|
| 11666 |
This setting will save the \gls{definitionindex} that's used by |
| 11667 |
\csopt[def]{identical-sort-action} to determine the order of |
| 11668 |
definition in the special internal field \field{definitionindex}. |
| 11669 |
This field is assigned when the entry is first created |
| 11670 |
and can be referenced with \gls{bibglsdefinitionindex}. |
| 11671 |
You can reference this field with certain resource options, such as |
| 11672 |
\csopt{format-integer-fields}, but you must place the |
| 11673 |
\csopt{save-definition-index} resource option first. |
| 11674 |
|
| 11675 |
Note that (unless you need to maintain \hierarchy) if you want to |
| 11676 |
order all entries by definition, it's better to use |
| 11677 |
\csopt[none]{sort}, which doesn't perform any sorting, so the order |
| 11678 |
will be by definition. |
| 11679 |
|
| 11680 |
\optsection[\subsubsection]{save-use-index} |
| 11681 |
|
| 11682 |
This is a boolean option. If the value is omitted \code{true} is |
| 11683 |
assumed. The default setting is \csopt[false]{save-use-index}. |
| 11684 |
|
| 11685 |
This setting will save the \gls{orderofuseindex} that's used by |
| 11686 |
\csopt[use]{identical-sort-action} in the special internal field |
| 11687 |
\field{useindex}. This field is assigned when the entry picks up |
| 11688 |
its first record and can be referenced with \gls{bibglsuseindex}. |
| 11689 |
You can't reference this field in resource options such as |
| 11690 |
\csopt{format-integer-fields}. |
| 11691 |
|
| 11692 |
Entries that don't have records won't have this field set. The order |
| 11693 |
of use corresponds to the first time the entry is recorded in the document. |
| 11694 |
|
| 11695 |
Note that (unless you need to maintain \hierarchy) if you want to |
| 11696 |
order all entries by use, it's better to use \csopt[use]{sort}, |
| 11697 |
which doesn't perform any sorting. |
| 11698 |
|
| 11699 |
\optsection[\subsubsection]{save-from-see} |
| 11700 |
|
| 11701 |
This option allows you to save a comma-separated list of entry |
| 11702 |
labels in a designated internal field of the target entry identified |
| 11703 |
by their \field{see} field. If the \meta{value} is omitted, |
| 11704 |
\csopt[from-see]{save-from-see} is assumed. The value may be the |
| 11705 |
keyword \code{false}, which switches off this setting, otherwise the |
| 11706 |
value should be the desired name of the internal field. |
| 11707 |
The default setting is \csopt[false]{save-from-see}. |
| 11708 |
|
| 11709 |
For example, if the \ext{bib} file contains: |
| 11710 |
\begin{codeenv} |
| 11711 |
\atentry{index}\marg{gourd} |
| 11712 |
\atentry{index}\marg{cucumber,\field{see}=\marg{gourd}} |
| 11713 |
\atentry{index}\marg{pumpkin,\field{see}=\marg{gourd}} |
| 11714 |
\end{codeenv} |
| 11715 |
then the resource option \csopt[from-see]{save-from-see} will create |
| 11716 |
an internal field called \fieldfmt{from-see} for the \code{gourd} entry |
| 11717 |
that contains the comma-separated list \code{cucumber,pumpkin}. |
| 11718 |
|
| 11719 |
Note that the given internal field isn't actually assigned within \bibgls, so it |
| 11720 |
can't be accessed via any resource options. Each item in this list is added using |
| 11721 |
\ics{glsxtrapptocsvfield} after the source entry (that is, the entry |
| 11722 |
containing the \field{see} field) is defined in the \ext{glstex} |
| 11723 |
file. This means that the list will be in the same order as the |
| 11724 |
entries. You can then pass the field value to \ics{glsseelist}. |
| 11725 |
For example: |
| 11726 |
\begin{codeenv} |
| 11727 |
\cs{glsdefpostdesc}\marg{\comment{} |
| 11728 |
\cs{glsxtrifhasfield}\marg{from-see}\marg{\cs{glscurrententrylabel}} |
| 11729 |
\marg{, related: \cs{glsseelist}\marg{\cs{glscurrentfieldvalue}}}\marg{}\% |
| 11730 |
} |
| 11731 |
\end{codeenv} |
| 11732 |
|
| 11733 |
This option has no effect with the \qt{no dependency} selection |
| 11734 |
criteria (such as \csopt[recorded no deps]{selection}). |
| 11735 |
|
| 11736 |
\optsection[\subsubsection]{save-from-seealso} |
| 11737 |
|
| 11738 |
As \csopt{save-from-see} but for the \field{seealso} field. If the |
| 11739 |
value is omitted, \csopt[from-seealso]{save-from-seealso} is assumed. |
| 11740 |
|
| 11741 |
\optsection[\subsubsection]{save-from-alias} |
| 11742 |
|
| 11743 |
As \csopt{save-from-see} but for the \field{alias} field. If the |
| 11744 |
value is omitted, \csopt[from-alias]{save-from-alias} is assumed. |
| 11745 |
|
| 11746 |
\optsection[\subsubsection]{save-crossref-tail} |
| 11747 |
|
| 11748 |
If you have a cross-reference trail where one entry references |
| 11749 |
another entry using \field{see}, \field{seealso} or \field{alias} |
| 11750 |
and the referenced entry also references another, and so on, then |
| 11751 |
you can save the tail end of the trail with this option. Note that |
| 11752 |
the trail only follows single-label lists (in \field{see} or |
| 11753 |
\field{seealso}). The trail is terminated if an entry doesn't have |
| 11754 |
one of those three fields set or if it cross-references multiple |
| 11755 |
entries or if the trail loops back on itself. |
| 11756 |
|
| 11757 |
If you have a loop, the tail for some entries may end prematurely |
| 11758 |
since the algorithm to obtain the tail saves the tail for each |
| 11759 |
sub-trail to avoid recalculating it. It's best to avoid |
| 11760 |
this setting if you have cross-reference loops. (Aside from two-way |
| 11761 |
cross-references, it's best to avoid loops in general.) |
| 11762 |
|
| 11763 |
The tail label is stored in the field identified by |
| 11764 |
the \meta{value} of this option. If the value is omitted, |
| 11765 |
\csopt[crossref-tail]{save-crossref-tail} is assumed. |
| 11766 |
The field won't be set if there's no tail. The tails are calculated |
| 11767 |
when writing the entry definitions to the \ext{glstex} file so the |
| 11768 |
value can't be referenced or otherwise accessed by \bibgls. |
| 11769 |
|
| 11770 |
Example: |
| 11771 |
\begin{codeenv} |
| 11772 |
\atentry{index}\marg{sample1,\field{see}=\marg{sample2}} |
| 11773 |
\atentry{index}\marg{sample2,\field{see}=\marg{sample3}} |
| 11774 |
\atentry{index}\marg{sample3,\field{see}=\marg{sample4}} |
| 11775 |
\atentry{index}\marg{sample4} |
| 11776 |
\end{codeenv} |
| 11777 |
The tail for \code{sample1} is \code{sample4}. As a by-product of |
| 11778 |
the recursion used in calculating the tail for \code{sample1}, the |
| 11779 |
tail for each element in the trail (\code{sample2} and |
| 11780 |
\code{sample3}) is also calculated. The tail is the same for each |
| 11781 |
entry in the trail. The final entry \code{sample4} doesn't have a |
| 11782 |
tail. |
| 11783 |
|
| 11784 |
If \code{sample4} is modified to cross-reference \code{sample1}: |
| 11785 |
\begin{codeenv} |
| 11786 |
\atentry{index}\marg{sample4,\field{see}=\marg{sample1}} |
| 11787 |
\end{codeenv} |
| 11788 |
then when the tail for \code{sample4} is calculated the tail for its |
| 11789 |
cross-reference (\code{sample1}) is consulted. This has already been |
| 11790 |
set to \code{sample4}. An entry can't have itself as a tail so the |
| 11791 |
tail for \code{sample4} is set to \code{sample3}. All the other |
| 11792 |
entries still have \code{sample4} as their tail because their tail |
| 11793 |
was determined while traversing the trail for \code{sample1}, which |
| 11794 |
had to stop when it wrapped round to its starting point. |
| 11795 |
|
| 11796 |
\optsection[\subsubsection]{save-original-entrytype} |
| 11797 |
|
| 11798 |
The \meta{value} may be the keywords \code{false} or \code{true} or |
| 11799 |
the name of a field in which to store the original \gls{entrytype} (as |
| 11800 |
given in the \ext{bib} file but without the leading \idx{atchar} and |
| 11801 |
converted to \idx!{lowercase}). The setting is |
| 11802 |
\csopt[false]{save-original-entrytype}. If \meta{value} is omitted or the |
| 11803 |
keyword \code{true}, then \csopt[originalentrytype]{save-original-entrytype} |
| 11804 |
If \meta{value} has an associated key in \gls!{newglossaryentry} |
| 11805 |
(for example, one provided with \cs{glsaddstoragekey}) it will be |
| 11806 |
set after the field aliases, otherwise (for example, |
| 11807 |
\field{originalentrytype}) it will simply be added to the \ext{glstex} file |
| 11808 |
using \ics{GlsXtrSetField} after the entry definition (which means |
| 11809 |
the field can't be referenced in other resource options). This |
| 11810 |
setting is governed by \csopt{save-original-entrytype-action}. |
| 11811 |
|
| 11812 |
\optsection[\subsubsection]{save-original-entrytype-action} |
| 11813 |
|
| 11814 |
This option determines whether or not \csopt{save-original-entrytype} |
| 11815 |
should save the original \gls{entrytype}. No action is performed when |
| 11816 |
\csopt[false]{save-original-entrytype} otherwise the action is determined |
| 11817 |
by \meta{value} which may be one of the following keywords: |
| 11818 |
\begin{itemize} |
| 11819 |
\item \code{always}: always save the original \gls{entrytype} (default); |
| 11820 |
\item \code{no override}: don't override a field that's already been |
| 11821 |
set; |
| 11822 |
\item \code{changed override} or \code{changed} or \code{diff}: |
| 11823 |
only save the original \gls{entrytype} if it's different from the final |
| 11824 |
\gls{entrytype}; |
| 11825 |
\item \code{changed no override}: |
| 11826 |
only save the original \gls{entrytype} if it's different from the final |
| 11827 |
\gls{entrytype} and the specified field hasn't been set. |
| 11828 |
\end{itemize} |
| 11829 |
The \qt{no override} options make no difference if the given field |
| 11830 |
is unknown (such as \field{originalentrytype}). For known fields, bear in |
| 11831 |
mind that the field will be set after field aliasing but before |
| 11832 |
other options, such as \csopt{ignore-fields}. |
| 11833 |
|
| 11834 |
The \qt{changed} options ignore case. For example, if the \ext{bib} |
| 11835 |
file defined an entry with \atentryfmt{INDEX} then both the original |
| 11836 |
and final \gls{entrytype} will be \code{index}. |
| 11837 |
|
| 11838 |
\optsection[\subsubsection]{gather-parsed-dependencies} |
| 11839 |
|
| 11840 |
Dependencies that are found by parsing field values may be gathered into a |
| 11841 |
comma-separated list saved in a field for later use. |
| 11842 |
The \meta{value} is the name of the desired field. If the \meta{value} is omitted |
| 11843 |
\csopt[seealso]{gather-parsed-dependencies} is assumed. |
| 11844 |
If the designated field is already set, the list will be appended to the existing value. |
| 11845 |
|
| 11846 |
Note that other dependencies, such as those obtained by examining the |
| 11847 |
cross-reference fields (\field{see}, \field{seealso} or \field{alias}) |
| 11848 |
or ancestors or dual entries, are not automatically added. |
| 11849 |
The \meta{value} may be the keyword \code{false} to switch off this option (which is the default). |
| 11850 |
|
| 11851 |
\subsection{Assignments} |
| 11852 |
\label{sec:fieldassignments} |
| 11853 |
|
| 11854 |
\optsection[\subsubsection]{group} |
| 11855 |
|
| 11856 |
The \csopt{group} option will set the \field{group} field to \meta{label} |
| 11857 |
unless \meta{label} is \optfmt{auto}. If \csopt[auto]{group} then if |
| 11858 |
the \longarg{group} switch is used the value of the \field{group} |
| 11859 |
field is set automatically during the sorting (see also |
| 11860 |
\csopt{group-formation}, \csopt{group-level} |
| 11861 |
and \sectionref{sec:logicaldivisions}). If the \longarg{no-group} |
| 11862 |
setting is on then \csopt[auto]{group} does nothing. |
| 11863 |
|
| 11864 |
The corresponding group title can be set with |
| 11865 |
\gls{glsxtrsetgrouptitle} in the document if the title is different |
| 11866 |
from the label. The default behaviour is \csopt[auto]{group}. |
| 11867 |
|
| 11868 |
For example: |
| 11869 |
\begin{codeenv} |
| 11870 |
\gls{GlsXtrLoadResources}\oarg{\csopt[integer]{sort},\csopt[Constants]{group}, |
| 11871 |
\csopt[entries-constants]{src}\comment{data in entries-constants.bib} |
| 11872 |
} |
| 11873 |
\gls{GlsXtrLoadResources}\oarg{\csopt[letter-case]{sort},\csopt[Variables]{group}, |
| 11874 |
\csopt[entries-variables]{src}\comment{data in entries-variables.bib} |
| 11875 |
} |
| 11876 |
\end{codeenv} |
| 11877 |
In this case, if the \field{type} field hasn't been set in the \ext{bib} files, |
| 11878 |
these entries will be added to the same glossary, but will |
| 11879 |
be grouped according to each instance of \gls{GlsXtrLoadResources}, |
| 11880 |
with the provided group label. |
| 11881 |
|
| 11882 |
|
| 11883 |
\optsection[\subsubsection]{category} |
| 11884 |
|
| 11885 |
The selected entries may all have their \field{category} field |
| 11886 |
changed before writing their definitions to the \ext{glstex} file. |
| 11887 |
The \meta{value} may be: |
| 11888 |
\begin{itemize} |
| 11889 |
\item \optfmt{false}: switch off this setting (default); |
| 11890 |
\item \optfmt{same as entry}: set the |
| 11891 |
\field{category} to the \ext{bib} \gls{entrytype} used to define it |
| 11892 |
(\idx!{lowercase} and without the initial \code{@}) after any aliasing, |
| 11893 |
if applicable; |
| 11894 |
|
| 11895 |
\item \optfmt{same as original entry}: (new to v1.4) set the \field{category} |
| 11896 |
to the original \gls{entrytype} (\idx!{lowercase} and without |
| 11897 |
the initial \code{@}) before it was aliased (behaves like |
| 11898 |
\optfmt{same as entry} if the \gls{entrytype} wasn't aliased); |
| 11899 |
|
| 11900 |
\item \optfmt{same as base}: (new to v1.1) set the \field{category} |
| 11901 |
to the base name of the \ext{bib} file (without the extension) |
| 11902 |
that provided the entry definition; |
| 11903 |
|
| 11904 |
\item \optfmt{same as type}: set the \field{category} to the same |
| 11905 |
value as the \field{type} field (if that field has been provided |
| 11906 |
either in the \ext{bib} file or through the \csopt{type} option); |
| 11907 |
|
| 11908 |
\item \meta{label}: the \field{category} is set to |
| 11909 |
\meta{label} (which mustn't contain any special characters). |
| 11910 |
\end{itemize} |
| 11911 |
This will override any |
| 11912 |
\field{category} fields supplied in the \ext{bib} file. |
| 11913 |
|
| 11914 |
When used with \csopt{entry-type-aliases}, the option \csopt[same as |
| 11915 |
entry]{category} refers to the \emph{target} \gls{entrytype} whereas |
| 11916 |
\csopt[same as original entry]{category} refers to the |
| 11917 |
\emph{original} \gls{entrytype} given in the \ext{bib} file. In both |
| 11918 |
cases, the value is converted to \idx!{lowercase} to ensure consistency. |
| 11919 |
An alternative is to use \csopt[category]{save-original-entrytype}. |
| 11920 |
When combined with \csopt[changed]{save-original-entrytype-action} |
| 11921 |
it's then possible to only set the \field{category} to the original |
| 11922 |
\gls{entrytype} for aliased entries and leave it unmodified for unaliased |
| 11923 |
entries. |
| 11924 |
|
| 11925 |
For example, if the \ext{bib} file contains: |
| 11926 |
\begin{codeenv} |
| 11927 |
\atentry{entry}\marg{bird, |
| 11928 |
\field{name}=\marg{bird}, |
| 11929 |
\field{description} = \marg{feathered animal} |
| 11930 |
} |
| 11931 |
\strut |
| 11932 |
\atentry{index}\marg{duck} |
| 11933 |
\strut |
| 11934 |
\atentry{index}\marg{goose,\field{plural}=\qtdelim{geese}} |
| 11935 |
\strut |
| 11936 |
\atentry{dualentry}\marg{dog, |
| 11937 |
\field{name}=\marg{dog}, |
| 11938 |
\field{description}=\marg{chien} |
| 11939 |
} |
| 11940 |
\end{codeenv} |
| 11941 |
then if the document contains: |
| 11942 |
\begin{codeenv} |
| 11943 |
\gls{GlsXtrLoadResources}\oarg{\csopt[same as entry]{category},\csopt[entries]{src}} |
| 11944 |
\end{codeenv} |
| 11945 |
this will set the \field{category} of the \code{bird} term to \optfmt{entry} |
| 11946 |
(since it was defined with \atentry{entry}), the \field{category} of the |
| 11947 |
\code{duck} and \code{goose} terms to \optfmt{index} (since they were defined |
| 11948 |
with \atentry{index}), and the \field{category} of the \code{dog} term to |
| 11949 |
\optfmt{dualentry} (since it was defined with \atentry{dualentry}). Note that |
| 11950 |
the dual entry \code{dual.dog} doesn't have the category set, since that's |
| 11951 |
governed by \csopt{dual-category} instead. |
| 11952 |
|
| 11953 |
If, instead, the document contains: |
| 11954 |
\begin{codeenv} |
| 11955 |
\gls{GlsXtrLoadResources}\oarg{\csopt[animals]{category},\csopt[entries]{src}} |
| 11956 |
\end{codeenv} |
| 11957 |
then the \field{category} of all the \primary\ selected entries will |
| 11958 |
be set to \optfmt{animals}. Again the \gls{dualentry} \code{dual.dog} |
| 11959 |
doesn't have the \field{category} set. |
| 11960 |
|
| 11961 |
Note that the categories may be overridden by the commands that are used to |
| 11962 |
actually define the entries (such as \gls!{bibglsnewindex}). |
| 11963 |
|
| 11964 |
For example, if the document contains: |
| 11965 |
\begin{codeenv} |
| 11966 |
\cs{newcommand}\marg{\gls{bibglsnewdualentry}}[4]\marg{\comment{} |
| 11967 |
\cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2,\field{category}=\marg{dual}}\marg{\idx{param}4}\comment{} |
| 11968 |
} |
| 11969 |
\strut |
| 11970 |
\gls{GlsXtrLoadResources}\oarg{\csopt[animals]{category},\csopt[entries]{src}} |
| 11971 |
\end{codeenv} |
| 11972 |
then both the \code{dog} and \code{dual.dog} entries will |
| 11973 |
have their \field{category} field set to \optfmt{dual} since the |
| 11974 |
new definition of \gls{bibglsnewdualentry} has overridden |
| 11975 |
the \csopt[animals]{category} option. |
| 11976 |
|
| 11977 |
\optsection[\subsubsection]{type} |
| 11978 |
|
| 11979 |
The \meta{value} may be one of: |
| 11980 |
\begin{itemize} |
| 11981 |
\item \optfmt{false}: switches off this setting (default); |
| 11982 |
|
| 11983 |
\item \optfmt{same as entry}: set the \field{type} field |
| 11984 |
to the \gls{entrytype} (\idx!{lowercase} and without the initial \code{@}); |
| 11985 |
|
| 11986 |
\item \optfmt{same as original entry}: set the \field{type} |
| 11987 |
to the original \gls{entrytype} (\idx!{lowercase} and without |
| 11988 |
the initial \code{@}) before it was aliased (behaves like |
| 11989 |
\optfmt{same as entry} if the \gls{entrytype} wasn't aliased); |
| 11990 |
|
| 11991 |
\optfmt{same as base}: set the \field{type} field |
| 11992 |
to the base name of the corresponding \ext{bib} file |
| 11993 |
(without the extension); |
| 11994 |
|
| 11995 |
\item \optfmt{same as category}: set the \field{type} field |
| 11996 |
to the same value as the \field{category} field |
| 11997 |
(\field{type} unchanged if \field{category} not set); |
| 11998 |
|
| 11999 |
\item \optfmt{same as parent}: sets the \field{type} to the same as |
| 12000 |
the entry's \parent\ (new to v1.9). If the entry doesn't have a |
| 12001 |
\parent\ or if the \parent\ doesn't have the \field{type} field set, then |
| 12002 |
no change is made. Entries should always have the same type |
| 12003 |
as their \parent, but it's possible for spawned entries to |
| 12004 |
pick up the \field{type} field from their \igls{progenitor} entry |
| 12005 |
(if it was explicitly set in the \ext{bib} file), |
| 12006 |
which may be inappropriate. |
| 12007 |
|
| 12008 |
\item\meta{label}: sets the \field{type} field to the glossary |
| 12009 |
identified by \meta{label}. |
| 12010 |
\end{itemize} |
| 12011 |
When used with \csopt{entry-type-aliases}, the option \csopt[same as |
| 12012 |
entry]{type} refers to the \emph{target} \gls{entrytype} and \csopt[same |
| 12013 |
as original entry]{type} refers to the \emph{original} \gls{entrytype} |
| 12014 |
given in the \ext{bib} file. |
| 12015 |
An alternative is to use \csopt[type]{save-original-entrytype}. |
| 12016 |
When combined with \csopt[changed]{save-original-entrytype-action} |
| 12017 |
it's then possible to only set the \field{type} to the original |
| 12018 |
\gls{entrytype} for aliased entries and leave it unmodified for unaliased |
| 12019 |
entries. |
| 12020 |
|
| 12021 |
\begin{important} |
| 12022 |
It's not possible to have both |
| 12023 |
\csopt[same as type]{category} and \csopt[same as category]{type}. |
| 12024 |
\end{important} |
| 12025 |
|
| 12026 |
Note that this setting only changes the \field{type} field for |
| 12027 |
\glspl{primaryentry}. Use \csopt{dual-type} for \glspl{dualentry}. |
| 12028 |
|
| 12029 |
For example: |
| 12030 |
\begin{codeenv} |
| 12031 |
\cmd{usepackage}[\styopt{record},\styopt{symbols}]\marg{glossaries-extra} |
| 12032 |
\strut |
| 12033 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries-symbols]{src},\csopt[symbols]{type}} |
| 12034 |
\end{codeenv} |
| 12035 |
|
| 12036 |
Make sure that the glossary type has already been defined |
| 12037 |
(see \sectionref{sec:newglossary}). In the above, the |
| 12038 |
\styopt{symbols} option defines the \code{symbols} glossary. |
| 12039 |
If you want to use a custom glossary, you need to provide it. For |
| 12040 |
example: |
| 12041 |
\begin{codeenv} |
| 12042 |
\cmd{usepackage}[\styopt{record},\styopt{nomain}]\marg{glossaries-extra} |
| 12043 |
\strut |
| 12044 |
\cs{newglossary*}\marg{dictionary}\marg{Dictionary} |
| 12045 |
\strut |
| 12046 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries-symbols]{src},\csopt[dictionary]{type}} |
| 12047 |
\end{codeenv} |
| 12048 |
(The \styopt{nomain} option was added to suppress the |
| 12049 |
creation of the default \mainglossary.) |
| 12050 |
|
| 12051 |
\optsection[\subsubsection]{ignored-type} |
| 12052 |
|
| 12053 |
Any entry that only has \iglspl{ignoredrecord} will still be |
| 12054 |
identified as having a record for selection purposes, which is |
| 12055 |
necessary for the entry to be defined in the document, but it may be |
| 12056 |
preferable to move such entries to a special \igls{ignoredglossary}. |
| 12057 |
This can be done with \csopt[\meta{type}]{ignored-type}, where |
| 12058 |
\meta{type} is the label of the \igls{ignoredglossary}. |
| 12059 |
|
| 12060 |
The glossary will be provided with |
| 12061 |
\ics{provideignoredglossary} to ensure that it's |
| 12062 |
defined even if \longarg{no-provide-glossaries} is set |
| 12063 |
(see \sectionref{sec:newglossary}). |
| 12064 |
Note that it uses the unstarred \ics{provideignoredglossary} |
| 12065 |
since it's assumed that it won't be needed in a list and |
| 12066 |
therefore won't have a target. This is different to all the other |
| 12067 |
settings that provide an \gls{ignoredglossary}, which use the |
| 12068 |
starred version instead. |
| 12069 |
|
| 12070 |
This option is not implemented for entries that have \emph{no} records |
| 12071 |
(those entries may have been selected because they are dependent on |
| 12072 |
another entry, such as a parent of a recorded child entry). The entry |
| 12073 |
must have at least one \gls{ignoredrecord} and |
| 12074 |
no other type of record and not be dependent on other entries or be |
| 12075 |
cross-referenced by other entries. |
| 12076 |
|
| 12077 |
Note that the \csopt{trigger-type} option, if set, overrides the |
| 12078 |
\csopt{ignored-type} option for entries that have records with the |
| 12079 |
special format \ics{glstriggerrecordformat} (which is also |
| 12080 |
considered an \gls{ignoredrecord}). However, \csopt{ignored-type} |
| 12081 |
will override the \csopt{type}, \csopt{dual-type}, |
| 12082 |
\csopt{tertiary-type} and the type specification in |
| 12083 |
\csopt{secondary}. |
| 12084 |
|
| 12085 |
Ignored entries may be copied to another glossary |
| 12086 |
with \csopt{copy-to-glossary}. If this is undesirable, a condition |
| 12087 |
may be applied to prevent it. For example, to copy all selected |
| 12088 |
entries to the glossary labelled \qt{index} except for ignored |
| 12089 |
entries: |
| 12090 |
\begin{codeenv} |
| 12091 |
\gls{GlsXtrLoadResources}\oarg{ |
| 12092 |
\csopt[\marg{terms,abbreviations}]{src} |
| 12093 |
\csopt[ignored]{ignored-type}, |
| 12094 |
\csopt[\qtdelim{index} \oarg{ \field{type} \idx{notequalscmp} \qtdelim{ignored} }]{copy-to-glossary} |
| 12095 |
} |
| 12096 |
\end{codeenv} |
| 12097 |
|
| 12098 |
\optsection[\subsubsection]{trigger-type} |
| 12099 |
|
| 12100 |
The record counting commands, such as \gls{rgls}, use the special |
| 12101 |
format \ics{glstriggerrecordformat}, which \bibgls\ also treats |
| 12102 |
as an \igls{ignoredrecord}. This means the entry will still be |
| 12103 |
identified as having a record for selection purposes, which is |
| 12104 |
necessary for the entry to be defined for use in the document, but |
| 12105 |
in order to prevent it from appearing in the glossary you need to |
| 12106 |
transfer the entry with \csopt[\meta{type}]{trigger-type}. |
| 12107 |
This will override the \csopt{type}, \csopt{dual-type}, |
| 12108 |
\csopt{tertiary-type} and the type specification in |
| 12109 |
\csopt{secondary}. |
| 12110 |
|
| 12111 |
The provided value \meta{type} must be a glossary label (not one of |
| 12112 |
the keywords allowed by \csopt{type}) or \code{false} to switch |
| 12113 |
off this setting. |
| 12114 |
You can define the glossary before loading the resource, but |
| 12115 |
it's not required as \bibgls\ will write |
| 12116 |
\code{\ics{provideignoredglossary*}\margm{type}} to the \ext{glstex} file |
| 12117 |
even if \longarg{no-provide-glossaries} is set |
| 12118 |
(see \sectionref{sec:newglossary}). |
| 12119 |
|
| 12120 |
\optsection[\subsubsection]{progenitor-type} |
| 12121 |
|
| 12122 |
This sets the default \field{type} field for the |
| 12123 |
\glsdisp{mainentry}{main term} defined by |
| 12124 |
\atentry{progenitor}-like entries. The \meta{value} is as for |
| 12125 |
\csopt{type}. This doesn't change the \field{type} for the spawned |
| 12126 |
\gls{progeny}. |
| 12127 |
|
| 12128 |
\optsection[\subsubsection]{progeny-type} |
| 12129 |
|
| 12130 |
This sets the default \field{type} field for the \gls{progeny} term |
| 12131 |
spawned by \atentry{progenitor}-like entries. The \meta{value} is as |
| 12132 |
for \csopt{type}. This doesn't change the \field{type} for the |
| 12133 |
\glsdisp{mainentry}{main} \gls{progenitor}. Remember that with the |
| 12134 |
default \csopt[parent]{adopted-parent-field} setting, the given type |
| 12135 |
should match the type of the \gls{parententry}. |
| 12136 |
|
| 12137 |
\optsection[\subsubsection]{adopted-parent-field} |
| 12138 |
|
| 12139 |
This identifies the target field to be set to the corresponding |
| 12140 |
value of the \field{adoptparents} list by the \gls{progeny} |
| 12141 |
entries spawned by the \atentry{progenitor} type of entry. |
| 12142 |
The default is \field{parent}. |
| 12143 |
|
| 12144 |
\optsection[\subsubsection]{ignore-fields} |
| 12145 |
|
| 12146 |
\begin{important} |
| 12147 |
Take care not to confuse \csopt{ignore-fields} with \csopt{omit-fields}. |
| 12148 |
The argument of \csopt{ignore-fields} is a simple list of field names. |
| 12149 |
\end{important} |
| 12150 |
|
| 12151 |
The \csopt{ignore-fields} key indicates that you want \bibgls\ to |
| 12152 |
skip the fields listed in the supplied comma-separated \meta{list} of field |
| 12153 |
labels. Remember that unrecognised fields will always be skipped. |
| 12154 |
However, an unrecognised field can still be referenced with some |
| 12155 |
options (such as \csopt{replicate-fields}) whereas any field |
| 12156 |
excluded with \csopt{ignore-fields} will be discarded and can't be |
| 12157 |
referenced. |
| 12158 |
|
| 12159 |
This setting is always implemented after \csopt{field-aliases} (see |
| 12160 |
\sectionref{sec:resourcesets}). If a field has been aliased then the |
| 12161 |
original field name is no longer present and so ignoring it will |
| 12162 |
have no effect. |
| 12163 |
|
| 12164 |
For example, suppose my \ext{bib} file contains: |
| 12165 |
\begin{codeenv} |
| 12166 |
\atentry{abbreviation}\marg{html, |
| 12167 |
\field{short} =\qtdelim{html}, |
| 12168 |
\field{long} = \marg{hypertext markup language}, |
| 12169 |
\field{description}=\marg{a markup language for creating web pages}, |
| 12170 |
\field{seealso}=\marg{xml} |
| 12171 |
} |
| 12172 |
\end{codeenv} |
| 12173 |
but I want to use the \abbrstyle{short-long} style and I don't want |
| 12174 |
the cross-referenced term, then I can use |
| 12175 |
\csopt[seealso,description]{ignore-fields}. |
| 12176 |
|
| 12177 |
Note that \csopt[parent]{ignore-fields} removes the \field{parent} |
| 12178 |
before determining the dependency lists. This means that |
| 12179 |
\csopt[recorded and deps]{selection} and |
| 12180 |
\csopt[recorded and ancestors]{selection} won't pick up the |
| 12181 |
label in the \field{parent} field. |
| 12182 |
|
| 12183 |
If you want to maintain the dependency and \gls{ancestor} relationship but |
| 12184 |
omit the \field{parent} field when writing the entries to the |
| 12185 |
\ext{glstex} file, you need to use \csopt{flatten} instead. |
| 12186 |
Alternatively, you can use \csopt{omit-fields}, however the hierarchical structure |
| 12187 |
will continue to be maintained. |
| 12188 |
|
| 12189 |
The \csopt{ignore-fields} instruction removes the unwanted fields |
| 12190 |
early in the Stage~3 process (see \sectionref{sec:resourcesets}). |
| 12191 |
This means that those field values won't be available if they are referenced |
| 12192 |
nor can they be used to establish dependencies. |
| 12193 |
If fields should be omitted from the \ext{glstex} file but the field values should |
| 12194 |
still be available to \bibgls, then use \csopt{omit-fields} instead. |
| 12195 |
|
| 12196 |
\optsection[\subsubsection]{omit-fields} |
| 12197 |
|
| 12198 |
\begin{important} |
| 12199 |
Take care not to confuse \csopt{omit-fields} with \csopt{ignore-fields}. |
| 12200 |
The argument of \csopt{omit-fields} is a complex list of string \glspl{concatenation}. |
| 12201 |
\end{important} |
| 12202 |
|
| 12203 |
The \csopt{omit-fields} action takes place in the final stage, at the point where |
| 12204 |
each entry is written to the \ext{glstex} file. Unlike \csopt{ignore-fields}, |
| 12205 |
the fields aren't removed from \bibgls's own internal data structure. This means that the fields |
| 12206 |
can be referenced in other options and will be parsed as usual for dependencies. |
| 12207 |
|
| 12208 |
If set, the \meta{list} argument is a list of string \glspl{concatenation} with |
| 12209 |
optional conditionals. Take care that constant strings are correctly delimited |
| 12210 |
to ensure that they are not mistaken for references to field values. |
| 12211 |
Note that this is different from \csopt{ignore-fields}, which simply requires |
| 12212 |
a list of field names. |
| 12213 |
For example, to omit the \field{description} field for all entries: |
| 12214 |
\begin{codeenv} |
| 12215 |
\csopt[\qtdelim{description}]{omit-fields} |
| 12216 |
\end{codeenv} |
| 12217 |
|
| 12218 |
Each identified field is simply omitted when writing the field list in the \ext{glstex} file. |
| 12219 |
However, this may trigger a fallback if the field is required. This option only |
| 12220 |
applies to fields that have a corresponding key that may be used in commands such |
| 12221 |
as \gls{newglossaryentry}. The option does not apply to special internal fields. |
| 12222 |
Any fields identified in the given list that are not recognised will be ignored. |
| 12223 |
|
| 12224 |
When each entry definition is being written to the \ext{glstex} file, the supplied |
| 12225 |
\meta{list} is evaluated for the current entry. Each non-empty non-null result |
| 12226 |
will be added to a temporary set of exclusion field names. Then each \keyval\ for the current |
| 12227 |
entry will be written to the \ext{glstex} for each known \meta{key} that has the |
| 12228 |
corresponding field set where the \meta{key} is not included in the exclusion set. |
| 12229 |
|
| 12230 |
Suppose the file \filefmt{abbrv.bib} contains: |
| 12231 |
\begin{codeenv} |
| 12232 |
\atentry{abbreviation}\marg{ssi, |
| 12233 |
\field{short}=\marg{SSI}, |
| 12234 |
\field{long}=\marg{server-side includes}, |
| 12235 |
\field{description}=\marg{a simple interpreted server-side |
| 12236 |
scripting language} |
| 12237 |
} |
| 12238 |
\atentry{abbreviation}\marg{html, |
| 12239 |
\field{short}=\marg{HTML}, |
| 12240 |
\field{long}=\marg{hypertext markup language}, |
| 12241 |
\field{description}=\marg{a markup language for creating web |
| 12242 |
pages} |
| 12243 |
} |
| 12244 |
\atentry{abbreviation}\marg{shtml, |
| 12245 |
\field{short}=\marg{SHTML}, |
| 12246 |
\field{long}=\marg{server-side includes enabled hypertext markup language}, |
| 12247 |
\field{description}=\marg{a combination of \cs{gls}\marg{html} and |
| 12248 |
\cs{gls}\marg{ssi}} |
| 12249 |
} |
| 12250 |
\end{codeenv} |
| 12251 |
With \csopt[description]{ignore-fields}, the \field{description} field will |
| 12252 |
be removed when the entry is first processed. This means that the |
| 12253 |
dependencies in the SHTML description field won't be detected. |
| 12254 |
Whereas with \csopt[\qtdelim{description}]{omit-fields}, the \field{description} |
| 12255 |
field won't be removed, so it will still be parsed and the dependent entries will |
| 12256 |
be detected, however the \field{description} field won't be written in the |
| 12257 |
\ext{glstex} file. In this case, you may want to also use |
| 12258 |
\csopt{gather-parsed-dependencies} to save a list of the dependent entries. |
| 12259 |
|
| 12260 |
Remember that literal strings must be quoted with string \glspl{concatenation}. |
| 12261 |
For example, suppose an entry has been defined as: |
| 12262 |
\begin{codeenv} |
| 12263 |
\atentry{index}\marg{nom-fr, |
| 12264 |
\field{name}=\marg{nom}, |
| 12265 |
\field{description}=\marg{name} |
| 12266 |
} |
| 12267 |
\end{codeenv} |
| 12268 |
In the case of \csopt[\qtdelim{description}]{omit-fields} then this will become: |
| 12269 |
\begin{codeenv} |
| 12270 |
\gls{newglossaryentry}\marg{name-fr}\marg{ |
| 12271 |
\field{name}=\marg{nom} |
| 12272 |
} |
| 12273 |
\end{codeenv} |
| 12274 |
Whereas \csopt[description]{omit-fields} returns \emph{the value of} the |
| 12275 |
\field{description} field. For the above example entry, the value of |
| 12276 |
the \field{description} field is \qt{name}, so \field{name} is added to the exclusion set |
| 12277 |
and so won't be written whilst \bibgls\ iterates over the \qt{name-fr} list of fields. |
| 12278 |
|
| 12279 |
This means that the \field{name} field will be flagged |
| 12280 |
as not written to the \ext{glstex} file. In the case of \atentry{index}, this |
| 12281 |
means that the fallback for the \field{name} field will be used, which is |
| 12282 |
the entry label. The result will therefore end up as: |
| 12283 |
\begin{codeenv} |
| 12284 |
\gls{newglossaryentry}\marg{name-fr}\marg{ |
| 12285 |
\field{description}=\marg{name}, |
| 12286 |
\field{name}=\marg{name-fr} |
| 12287 |
} |
| 12288 |
\end{codeenv} |
| 12289 |
In this case, the \field{description} field value just happens to be the name of |
| 12290 |
another recognised field. Mostly, this type of error would likely result |
| 12291 |
in a string that doesn't match any known field, which will trigger a warning. |
| 12292 |
|
| 12293 |
Conditions may also be applied. For example, to omit the \field{description} |
| 12294 |
field for any entries defined with \atentry{abbreviation}: |
| 12295 |
\begin{codeenv} |
| 12296 |
\csopt[ |
| 12297 |
\qtdelim{description} \oarg{entrytype \idx{follow} actual = \qtdelim{abbreviation}} |
| 12298 |
]{omit-fields} |
| 12299 |
\end{codeenv} |
| 12300 |
|
| 12301 |
\optsection[\subsubsection]{omit-fields-missing-field-action} |
| 12302 |
|
| 12303 |
This option indicates what to do if a source field identified in |
| 12304 |
\csopt{omit-fields} is missing. The value may be one of: |
| 12305 |
\begin{itemize} |
| 12306 |
\item \optfmt{skip}: return null; |
| 12307 |
\item \optfmt{fallback}: use the fallback for the missing field |
| 12308 |
(see \sectionref{sec:fallbacks}), if |
| 12309 |
one is available, otherwise return null (default); |
| 12310 |
\item \optfmt{empty}: treat the missing value as empty. |
| 12311 |
\end{itemize} |
| 12312 |
Returning null or empty skips the string \gls{concatenation} element from the |
| 12313 |
omision list. |
| 12314 |
|
| 12315 |
\optsection[\subsubsection]{field-aliases} |
| 12316 |
|
| 12317 |
You can instruct \bibgls\ to treat one field as though it |
| 12318 |
was another using this option. The value should be a comma-separated |
| 12319 |
list of \meta{field1}\dequals\meta{field2} pairs, where |
| 12320 |
\meta{field1} and \meta{field2} are field names. Identical |
| 12321 |
mappings and trails aren't permitted. (That is, \meta{field1} |
| 12322 |
and \meta{field2} can't be the same nor can you have both |
| 12323 |
\meta{field1}\dequals\meta{field2} and |
| 12324 |
\meta{field2}\dequals\meta{field3}.) If you want to swap |
| 12325 |
fields you need to use one of the dual \glspl{entrytype} instead. |
| 12326 |
Field aliases are performed before \csopt{ignore-fields}, |
| 12327 |
so if \meta{field1} is listed in \csopt{ignore-fields} it won't |
| 12328 |
be ignored (unless \meta{field2} is in \csopt{ignore-fields}). |
| 12329 |
|
| 12330 |
For example, suppose \filefmt{people.bib} contains: |
| 12331 |
\begin{codeenv} |
| 12332 |
\atentry{entry}\marg{alexander, |
| 12333 |
\field{name}=\marg{Alexander III of Macedon}, |
| 12334 |
\field{description}=\marg{Ancient Greek king of Macedon}, |
| 12335 |
\fieldfmt{born}=\marg{20 July 356 BC}, |
| 12336 |
\fieldfmt{died}=\marg{10 June 323 BC}, |
| 12337 |
\fieldfmt{othername}=\marg{Alexander the Great} |
| 12338 |
} |
| 12339 |
\end{codeenv} |
| 12340 |
This contains three non-standard fields: \fieldfmt{born}, |
| 12341 |
\fieldfmt{died} and \fieldfmt{othername}. I could define |
| 12342 |
these fields using \ics{glsaddkey}, but another possibility |
| 12343 |
is to map these onto the user keys \field{user1}, \field{user2} |
| 12344 |
and \field{user3}, which saves the overhead of providing new |
| 12345 |
keys: |
| 12346 |
\begin{codeenv} |
| 12347 |
\gls{GlsXtrLoadResources}\oarg{ |
| 12348 |
\csopt[people]{src},\comment{data in people.bib} |
| 12349 |
\csopt[\fieldfmt{born}=\field{user1},\fieldfmt{died}=\field{user2},\fieldfmt{othername}=\field{user3}]{field-aliases} |
| 12350 |
} |
| 12351 |
\end{codeenv} |
| 12352 |
|
| 12353 |
\optsection[\subsubsection]{replicate-fields} |
| 12354 |
|
| 12355 |
\begin{important} |
| 12356 |
Note the difference in syntax between \csopt{replicate-fields} and |
| 12357 |
\csopt{assign-fields}. Both have a \keyvallist\ as the option |
| 12358 |
argument, but the \keyval\ syntax is different. In the case of |
| 12359 |
\csopt{replicate-fields}, the left hand side (\meta{key}) is the |
| 12360 |
\emph{source} field. The right hand side (\meta{value}) is a |
| 12361 |
comma-separated list of \emph{destination} fields. The value of the |
| 12362 |
source field will be copied into each of the destination fields. |
| 12363 |
In the case of \csopt{assign-fields}, the left hand side |
| 12364 |
(\meta{key}) is the \emph{destination} field and the right hand side |
| 12365 |
\emph{value} is an assignment expression with an optional |
| 12366 |
conditional. |
| 12367 |
\end{important} |
| 12368 |
|
| 12369 |
The value of one field can be copied to other fields using |
| 12370 |
this option where each \keyval\ pair is in the form |
| 12371 |
\code{\meta{field1}\dequals\marg{\meta{field2},\meta{field3},\ldots}} |
| 12372 |
where all values are field names. The value is required for this key |
| 12373 |
but may be empty, which indicates that the setting is switched off. |
| 12374 |
|
| 12375 |
This option copies the contents |
| 12376 |
of \meta{field1} to \meta{field2}, \meta{field3}, \ldots\ |
| 12377 |
(but only if the target field isn't already set with |
| 12378 |
\csopt[false]{replicate-override}). This action is |
| 12379 |
performed after \csopt{ignore-fields} (see |
| 12380 |
\sectionref{sec:resourcesets}). If the source field is missing, the |
| 12381 |
\csopt{replicate-missing-field-action} setting determines the |
| 12382 |
action. |
| 12383 |
|
| 12384 |
If the target field doesn't have an associated key recognised by |
| 12385 |
\gls{newglossaryentry} then the value will be saved using |
| 12386 |
\cs{GlsXtrSetField}. Special internal fields aren't permitted as |
| 12387 |
either source or target fields. |
| 12388 |
|
| 12389 |
For example, suppose \filefmt{people.bib} contains: |
| 12390 |
\begin{codeenv} |
| 12391 |
\atentry{entry}\marg{alexander, |
| 12392 |
\field{name}=\marg{Alexander III of Macedon (Alexander the Great)}, |
| 12393 |
\field{text}=\marg{Alexander}, |
| 12394 |
\field{description}=\marg{Ancient Greek king of Macedon} |
| 12395 |
} |
| 12396 |
\end{codeenv} |
| 12397 |
Since the \field{first} field hasn't been supplied, it |
| 12398 |
will default to the value of the \field{text} field, but |
| 12399 |
perhaps for one of my documents I'd like the \field{first} |
| 12400 |
field to be the same as the \field{name} field. Rather than |
| 12401 |
editing the \ext{bib} file, I can just do: |
| 12402 |
\begin{codeenv} |
| 12403 |
\gls{GlsXtrLoadResources}\oarg{ |
| 12404 |
\csopt[people]{src},\comment{data in people.bib} |
| 12405 |
\csopt[\field{name}=\field{first}]{replicate-fields} |
| 12406 |
} |
| 12407 |
\end{codeenv} |
| 12408 |
This copies the contents of the \field{name} field into the |
| 12409 |
\field{first} field. If you have more than one field |
| 12410 |
in the list take care to brace the lists to avoid confusion. |
| 12411 |
For example, if for some reason I want to copy the value |
| 12412 |
of the \field{name} field to both \field{first} and |
| 12413 |
\field{firstplural} and copy the value of the \field{text} |
| 12414 |
field to the \field{plural} field, then this requires braces |
| 12415 |
for the inner list: |
| 12416 |
\begin{codeenv} |
| 12417 |
\gls{GlsXtrLoadResources}\oarg{ |
| 12418 |
\csopt[people]{src},\comment{data in people.bib} |
| 12419 |
\csopt[\field{name}=\marg{\field{first},\field{firstplural}},\field{text}=\field{plural}]{replicate-fields} |
| 12420 |
} |
| 12421 |
\end{codeenv} |
| 12422 |
|
| 12423 |
If my \filefmt{people.bib} file instead contained: |
| 12424 |
\begin{codeenv} |
| 12425 |
\atentry{entry}\marg{alexander, |
| 12426 |
\field{name}=\marg{Alexander III of Macedon (Alexander the Great)}, |
| 12427 |
\field{first}=\marg{Alexander the Great}, |
| 12428 |
\field{text}=\marg{Alexander}, |
| 12429 |
\field{description}=\marg{Ancient Greek king of Macedon} |
| 12430 |
} |
| 12431 |
\end{codeenv} |
| 12432 |
then: |
| 12433 |
\begin{codeenv} |
| 12434 |
\gls{GlsXtrLoadResources}\oarg{ |
| 12435 |
\csopt[people]{src},\comment{data in people.bib} |
| 12436 |
\csopt[\field{name}=\field{first}]{replicate-fields} |
| 12437 |
} |
| 12438 |
\end{codeenv} |
| 12439 |
won't alter the \field{first} field since \csopt{replicate-fields} |
| 12440 |
doesn't override existing values by default. You can use |
| 12441 |
\csopt{replicate-override} to change this. Alternatively, since |
| 12442 |
\csopt{replicate-fields} is always performed after \csopt{ignore-fields} |
| 12443 |
it's possible to ignore the \field{first} field which means that the |
| 12444 |
\field{name} value can then be copied into it: |
| 12445 |
\begin{codeenv} |
| 12446 |
\gls{GlsXtrLoadResources}\oarg{ |
| 12447 |
\csopt[people]{src},\comment{data in people.bib} |
| 12448 |
\csopt[\field{first}]{ignore-fields}, |
| 12449 |
\csopt[\field{name}=\field{first}]{replicate-fields} |
| 12450 |
} |
| 12451 |
\end{codeenv} |
| 12452 |
Note that the ordering within the resource options doesn't |
| 12453 |
make a difference. The same result occurs with: |
| 12454 |
\begin{codeenv} |
| 12455 |
\gls{GlsXtrLoadResources}\oarg{ |
| 12456 |
\csopt[people]{src},\comment{data in people.bib} |
| 12457 |
\csopt[\field{name}=\field{first}]{replicate-fields}, |
| 12458 |
\csopt[\field{first}]{ignore-fields} |
| 12459 |
} |
| 12460 |
\end{codeenv} |
| 12461 |
|
| 12462 |
\optsection[\subsubsection]{replicate-override} |
| 12463 |
|
| 12464 |
This is a boolean option. The default setting is |
| 12465 |
\csopt[false]{replicate-override}. If \optfmt{true}, |
| 12466 |
\csopt{replicate-fields} will override the existing value if the |
| 12467 |
target field is already set. |
| 12468 |
|
| 12469 |
\optsection[\subsubsection]{replicate-missing-field-action} |
| 12470 |
|
| 12471 |
This option indicates what to do if a source field identified in |
| 12472 |
\csopt{replicate-fields} is missing. The value may be one of: |
| 12473 |
\begin{itemize} |
| 12474 |
\item \optfmt{skip}: skip the replication of the missing field |
| 12475 |
(default); |
| 12476 |
\item \optfmt{fallback}: use the fallback for the missing field |
| 12477 |
(see \sectionref{sec:fallbacks}), if |
| 12478 |
one is available (otherwise skip); |
| 12479 |
\item \optfmt{empty}: make the target field empty. |
| 12480 |
\end{itemize} |
| 12481 |
|
| 12482 |
\optsection[\subsubsection]{assign-fields} |
| 12483 |
|
| 12484 |
\begin{important} |
| 12485 |
Note the difference in syntax between \csopt{replicate-fields} and |
| 12486 |
\csopt{assign-fields}, as highlighted in the |
| 12487 |
\csopt{replicate-fields} section, above. The \csopt{assign-fields} |
| 12488 |
option is implemented after the \csopt{replicate-fields} option (see |
| 12489 |
\sectionref{sec:resourcesets}). |
| 12490 |
\end{important} |
| 12491 |
|
| 12492 |
The \csopt{assign-fields} option is a more complicated way of setting a |
| 12493 |
field than \csopt{replicate-fields}. Each \keyval\ element of the |
| 12494 |
\keyvallist\ argument has the syntax: |
| 12495 |
\begin{codeenv} |
| 12496 |
\meta{dest-field} \dequals\oargm{override} \meta{element-list} \oargm{condition} |
| 12497 |
\end{codeenv} |
| 12498 |
If the destination field (\meta{dest-field}) is already set, it will |
| 12499 |
only be overwritten if \csopt[true]{assign-override} or if |
| 12500 |
\oarg{override} is \qtt{o}. The \meta{dest-field} is simply the name |
| 12501 |
of the field for the entry under consideration and doesn't use the |
| 12502 |
more complex \meta{field-ref} syntax used in \meta{element-list}, |
| 12503 |
which is described in \sectionref{sec:optstringconcat}. |
| 12504 |
You can, however, use the \cs{uhex} quark on either side of the |
| 12505 |
\keyval\ element to indicate a Unicode character. |
| 12506 |
|
| 12507 |
The \oargm{override} following the equal sign is optional and may be |
| 12508 |
used to counteract the \csopt{assign-override} setting for the given |
| 12509 |
assignment. The \meta{override} value may be either \qtt{o} |
| 12510 |
(override) or \qtt{n} (no override). If not present, the |
| 12511 |
\csopt{assign-override} setting will be used. |
| 12512 |
|
| 12513 |
The \meta{element-list} is a string \gls{concatenation}, as |
| 12514 |
described in \sectionref{sec:optstringconcat}. If any individual |
| 12515 |
element in the list evaluates to null, the entire string is deemed |
| 12516 |
to be null, in which case the assignment won't be made. |
| 12517 |
|
| 12518 |
The \oargm{condition} part is optional. If present, the assignment |
| 12519 |
is only made if the condition evaluates to true. The condition |
| 12520 |
should be placed in square brackets after the \meta{element-list} |
| 12521 |
part. This is a complex conditional, as described in |
| 12522 |
\sectionref{sec:conditionals}. |
| 12523 |
|
| 12524 |
Note that, unlike most \keyval\ options, the value part |
| 12525 |
(\meta{element-list} \oargm{condition}) should not be grouped. The |
| 12526 |
\csopt{assign-fields} option is parsed in a different way to the |
| 12527 |
other \keyvallist\ options. However, it's best to group the \emph{entire} |
| 12528 |
\meta{value} argument of \csopt{assign-fields}. For example: |
| 12529 |
\begin{codeenv} |
| 12530 |
\csopt[ |
| 12531 |
\field{name} \idx{equalsassign} \field{text} \idx{concat-plus} \qtdelim{, } \idx{concat-plus} \field{symbol} |
| 12532 |
]{assign-fields} |
| 12533 |
\end{codeenv} |
| 12534 |
Don't do \code{\field{name} \idx{equalsassign} \marg{\field{text} |
| 12535 |
\idx{concat-plus} \qtdelim{, } \idx{concat-plus} \field{symbol}}}. |
| 12536 |
|
| 12537 |
\begin{important} |
| 12538 |
Remember that field values may be altered before or after |
| 12539 |
\csopt{assign-fields} by other resource options (see |
| 12540 |
\sectionref{sec:resourcesets}). The assignment will use the value |
| 12541 |
current at the time it is referenced during the processing of |
| 12542 |
\csopt{assign-fields}. If you need to reference the destination |
| 12543 |
field in the assignment, make sure that the override setting is on |
| 12544 |
if the field needs to be updated. |
| 12545 |
\end{important} |
| 12546 |
|
| 12547 |
For example, suppose I have defined the custom fields |
| 12548 |
\fieldfmt{surname} and \fieldfmt{forename}, and I have the following |
| 12549 |
in my \ext{bib} file: |
| 12550 |
\begin{codeenv} |
| 12551 |
\atentry{index}\marg{Smith} |
| 12552 |
\atentry{index}\marg{Jane-Smith, |
| 12553 |
\fieldfmt{forename}=\marg{Jane}, |
| 12554 |
\field{parent}=\marg{Smith} |
| 12555 |
} |
| 12556 |
\end{codeenv} |
| 12557 |
Suppose that what I actually want is: |
| 12558 |
\begin{codeenv} |
| 12559 |
\atentry{index}\marg{Smith} |
| 12560 |
\atentry{index}\marg{Jane-Smith, |
| 12561 |
\fieldfmt{forename}=\marg{Jane}, |
| 12562 |
\fieldfmt{surname}=\marg{Smith}, |
| 12563 |
\field{parent}=\marg{Smith}, |
| 12564 |
\field{name}=\marg{Jane}, |
| 12565 |
\field{text}=\marg{Jane Smith} |
| 12566 |
} |
| 12567 |
\end{codeenv} |
| 12568 |
This is quite repetitive to type out for every person you need to |
| 12569 |
index. The \csopt{replicate-fields} option can reduce some of this. |
| 12570 |
For example: |
| 12571 |
\begin{codeenv} |
| 12572 |
\csopt{replicate-fields}=\marg{ |
| 12573 |
\fieldfmt{forename}=\marg{name}, |
| 12574 |
\fieldfmt{surname}=\marg{parent} |
| 12575 |
} |
| 12576 |
\end{codeenv} |
| 12577 |
This doesn't deal with the \field{text} field and also has a problem |
| 12578 |
if the \field{parent} field (which should contain a label) doesn't |
| 12579 |
match the surname. For example, I might also have: |
| 12580 |
\begin{codeenv} |
| 12581 |
\atentry{index}\marg{de-la-Fontaine, |
| 12582 |
\field{name}=\marg{de la Fontaine} |
| 12583 |
} |
| 12584 |
\atentry{index}\marg{Margaret-de-la-Fontaine, |
| 12585 |
\fieldfmt{forename}=\marg{Margaret}, |
| 12586 |
\field{parent}=\marg{de-la-Fontaine} |
| 12587 |
} |
| 12588 |
\end{codeenv} |
| 12589 |
In this case the custom \fieldfmt{surname} field needs to match the |
| 12590 |
parent's \field{name} field, not the parent's label. |
| 12591 |
|
| 12592 |
The desired result can instead be obtained with: |
| 12593 |
\begin{codeenv} |
| 12594 |
\csopt{assign-fields}=\marg{ |
| 12595 |
\fieldfmt{surname} = parent \idx{follow} \field{name}, |
| 12596 |
\field{name} = self \idx{follow} \fieldfmt{forename}, |
| 12597 |
\field{text} = self \idx{follow} \fieldfmt{forename} |
| 12598 |
\idx{concat-plus} \qtdelim{ } \idx{concat-plus} self \idx{follow} \fieldfmt{surname} |
| 12599 |
} |
| 12600 |
\end{codeenv} |
| 12601 |
The \code{self \idx{follow}} part is optional so this can be written |
| 12602 |
more compactly as: |
| 12603 |
\begin{codeenv} |
| 12604 |
\csopt{assign-fields}=\marg{ |
| 12605 |
\fieldfmt{surname} = parent \idx{follow} \field{name}, |
| 12606 |
\field{name} = \fieldfmt{forename}, |
| 12607 |
\field{text} = \fieldfmt{forename} \idx{concat-plus} \qtdelim{ } \idx{concat-plus} \fieldfmt{surname} |
| 12608 |
} |
| 12609 |
\end{codeenv} |
| 12610 |
The last assignment in the above can also be written as: |
| 12611 |
\begin{codeenv} |
| 12612 |
\field{text} = \fieldfmt{forename} \idx{concat-plus} \marg{ } \idx{concat-plus} \fieldfmt{surname} |
| 12613 |
\end{codeenv} |
| 12614 |
Suppose, for some reason, I want the first use to show the surname |
| 12615 |
in bold. This means I need to add |
| 12616 |
\code{\cs{textbf}\idx{bgroupchar}} before the value of the |
| 12617 |
surname field and the closing \idx{egroupchar} needs to go after. |
| 12618 |
This can be achieved with: |
| 12619 |
\begin{codeenv} |
| 12620 |
\field{first} = \fieldfmt{forename} \idx{concat-plus} \qtdelim{ \cs{textbf}\idx{bgroupchar}} \idx{concat-plus} \fieldfmt{surname} \qtdelim{\idx{egroupchar}} |
| 12621 |
\end{codeenv} |
| 12622 |
Note that because there are unbalanced braces in the string |
| 12623 |
fragments, it's necessary to use quote delimiters. Since \cs{textbf} |
| 12624 |
is robust, there's no need to protect it from expansion. |
| 12625 |
|
| 12626 |
Suppose, instead, I want the surname in \idx{uppercase} on first |
| 12627 |
use. I could simply replace \cs{textbf} with \cs{MakeUppercase}, but |
| 12628 |
I can get \bibgls\ to do the case-conversion instead: |
| 12629 |
\begin{codeenv} |
| 12630 |
\field{first} = \fieldfmt{forename} \idx{concat-plus} \qtdelim{ } \idx{concat-plus} \gls{UC}\marg{ \fieldfmt{surname} } |
| 12631 |
\end{codeenv} |
| 12632 |
This assumes that \ics{GlsXtrResourceInitEscSequences} has been |
| 12633 |
added to the definition of \cs{glsxtrresourceinit}, as described in |
| 12634 |
\sectionref{sec:quarks}. Otherwise you would need to protect \gls{UC}. |
| 12635 |
|
| 12636 |
In the above example, the \fieldfmt{surname} field is obtained from |
| 12637 |
the value of the parent's \field{name} according to the assignment: |
| 12638 |
\begin{codeenv} |
| 12639 |
\fieldfmt{surname} = parent \idx{follow} \field{name}, |
| 12640 |
\end{codeenv} |
| 12641 |
In the case of the Smith entry, the \field{name} field hasn't been |
| 12642 |
set. |
| 12643 |
|
| 12644 |
If a referenced field hasn't been set then the behaviour depends on |
| 12645 |
the \csopt{assign-missing-field-action} setting. The default |
| 12646 |
behaviour is to use the fallback, if provided (see |
| 12647 |
\sectionref{sec:fallbacks}). In the case of \atentry{index}, the |
| 12648 |
fallback for the \field{name} field is the entry's label. This means |
| 12649 |
that the Jane-Smith entry will have the \fieldfmt{surname} field set |
| 12650 |
to \qt{Smith}. |
| 12651 |
|
| 12652 |
If the fallback isn't set or if there is no fallback then the |
| 12653 |
assignment instruction will be skipped. Similarly, if an ancestor is |
| 12654 |
referenced but doesn't exist then assignment will again be skipped. |
| 12655 |
|
| 12656 |
\begin{important} |
| 12657 |
The ancestor entries must be defined first to ensure that they have |
| 12658 |
been processed and have had their fields set before they can be |
| 12659 |
referenced in an assignment. |
| 12660 |
\end{important} |
| 12661 |
|
| 12662 |
Since I haven't imposed any conditions on the assignments, the |
| 12663 |
instructions will be attempted on all entries. This includes the |
| 12664 |
parent entries. |
| 12665 |
|
| 12666 |
The first instruction attempts to set the \fieldfmt{surname} field |
| 12667 |
to the parent's \field{name}. Neither the Smith nor the |
| 12668 |
de-la-Fontaine entries have a parent entry, so this instruction is |
| 12669 |
skipped for both of them. |
| 12670 |
|
| 12671 |
The second instruction attempts to set the \field{name} field to the |
| 12672 |
entry's \fieldfmt{forename} field. The de-la-Fontaine entry already |
| 12673 |
has the \field{name} field set so the instruction is automatically |
| 12674 |
skipped (because of the default \csopt[false]{assign-override}). |
| 12675 |
The Smith entry doesn't have the \field{name} field set so the |
| 12676 |
assignment will be attempted but will fail because the |
| 12677 |
\fieldfmt{forename} field isn't set and doesn't have a fallback. |
| 12678 |
|
| 12679 |
The \field{text} (and \field{first}) instruction similarly |
| 12680 |
references the \fieldfmt{forename} field, which isn't set, so the |
| 12681 |
instruction is skipped. The instruction also contains a reference to |
| 12682 |
the \fieldfmt{surname} field, but that part of the assignment isn't |
| 12683 |
reached as the attempt stops at the first unset reference. |
| 12684 |
|
| 12685 |
This means that neither the Smith not the de-la-Fontaine entries |
| 12686 |
will be affected by the above \csopt{assign-fields} setting. |
| 12687 |
|
| 12688 |
Each instruction will be attempted, in turn, unless the \csopt{assign-override} |
| 12689 |
setting prevents it. This means it's possible to have multiple |
| 12690 |
assignments for a particular field. The first one that succeeds will |
| 12691 |
be the one that has effect (with \csopt[false]{assign-override}). |
| 12692 |
For example: |
| 12693 |
\begin{codeenv} |
| 12694 |
\csopt{assign-fields}=\marg{ |
| 12695 |
\fieldfmt{surname} = parent \idx{follow} \field{name}, |
| 12696 |
\fieldfmt{surname} = \field{name}, |
| 12697 |
\field{name} = \fieldfmt{forename}, |
| 12698 |
\field{text} = \fieldfmt{forename} \idx{concat-plus} \qtdelim{ } \idx{concat-plus} \fieldfmt{surname} |
| 12699 |
} |
| 12700 |
\end{codeenv} |
| 12701 |
This has two instructions for the \fieldfmt{surname}. The first one |
| 12702 |
will be applied to entries that have a parent and the second one |
| 12703 |
will be applied to the other entries (that don't already have the |
| 12704 |
\fieldfmt{surname} set). |
| 12705 |
|
| 12706 |
Suppose I also have some monarchs, who are more typically only |
| 12707 |
referred to by their forename (with no surname), possibly prefixed by their rank and |
| 12708 |
suffixed by their ordinal. Let's further suppose that in my document |
| 12709 |
I have also defined the custom fields \fieldfmt{rank} and |
| 12710 |
\fieldfmt{ordinal}, and in my \ext{bib} file I have: |
| 12711 |
\begin{codeenv} |
| 12712 |
\atentry{indexplural}\marg{king} |
| 12713 |
\atentry{indexplural}\marg{queen} |
| 12714 |
\atentry{indexplural}\marg{empress,\field{plural}=\marg{empresses}} |
| 12715 |
\strut |
| 12716 |
\atentry{index}\marg{King-Stephen, |
| 12717 |
\field{parent}=\marg{king}, |
| 12718 |
\fieldfmt{forename}=\marg{Stephen} |
| 12719 |
} |
| 12720 |
\atentry{index}\marg{Empress-Matilda, |
| 12721 |
\field{parent}=\marg{empress}, |
| 12722 |
\fieldfmt{forename}=\marg{Matilda}, |
| 12723 |
} |
| 12724 |
\atentry{index}\marg{Elizabeth-I, |
| 12725 |
\field{parent}=\marg{queen}, |
| 12726 |
\fieldfmt{forename}={Elizabeth}, |
| 12727 |
\fieldfmt{ordinal}={I} |
| 12728 |
} |
| 12729 |
\end{codeenv} |
| 12730 |
The earlier assignment rules won't be appropriate for these cases, |
| 12731 |
as they would result in the \field{text} fields: \qt{Stephen kings}, |
| 12732 |
\qt{Matilda empresses} and \qt{Elizabeth queens}. |
| 12733 |
|
| 12734 |
In this case, the assignment rules need to depend on the type of |
| 12735 |
entry. I could test if the parent label is \qt{king} or \qt{empress} |
| 12736 |
or \qt{queen}, but a more reliable approach is to have custom entry |
| 12737 |
types which can be aliased: |
| 12738 |
|
| 12739 |
\begin{codeenv} |
| 12740 |
\atentry{index}\marg{Smith} |
| 12741 |
\atentryfmt{person}\marg{Jane-Smith, |
| 12742 |
\fieldfmt{forename}=\marg{Jane}, |
| 12743 |
\field{parent}=\marg{Smith} |
| 12744 |
} |
| 12745 |
\atentry{index}\marg{de-la-Fontaine, |
| 12746 |
\field{name}=\marg{de la Fontaine} |
| 12747 |
} |
| 12748 |
\atentryfmt{person}\marg{Margaret-de-la-Fontaine, |
| 12749 |
\fieldfmt{forename}=\marg{Margaret}, |
| 12750 |
\field{parent}=\marg{de-la-Fontaine} |
| 12751 |
} |
| 12752 |
\strut |
| 12753 |
\atentry{indexplural}\marg{king} |
| 12754 |
\atentry{indexplural}\marg{queen} |
| 12755 |
\atentry{indexplural}\marg{empress,\field{plural}=\marg{empresses}} |
| 12756 |
\strut |
| 12757 |
\atentryfmt{monarch}\marg{King-Stephen, |
| 12758 |
\field{parent}=\marg{king}, |
| 12759 |
\fieldfmt{forename}=\marg{Stephen} |
| 12760 |
} |
| 12761 |
\atentryfmt{monarch}\marg{Empress-Matilda, |
| 12762 |
\field{parent}=\marg{empress}, |
| 12763 |
\fieldfmt{forename}=\marg{Matilda}, |
| 12764 |
} |
| 12765 |
\atentryfmt{monarch}\marg{Elizabeth-I, |
| 12766 |
\field{parent}=\marg{queen}, |
| 12767 |
\fieldfmt{forename}={Elizabeth}, |
| 12768 |
\fieldfmt{ordinal}={I} |
| 12769 |
} |
| 12770 |
\end{codeenv} |
| 12771 |
The resource options are now: |
| 12772 |
\begin{codeenv} |
| 12773 |
\csopt[person=index,monarch=index]{entry-type-aliases}, |
| 12774 |
\csopt[ |
| 12775 |
\field{name} = \fieldfmt{forename} \idx{concat-plus} \qt{\idx{nbspchar}} \fieldfmt{ordinal}, |
| 12776 |
\field{name} = \fieldfmt{forename}, |
| 12777 |
\fieldfmt{surname} = parent \idx{follow} \field{name} |
| 12778 |
\oarg{ entrytype \idx{follow} original \idx{equalscmp} \qtdelim{person} }, |
| 12779 |
\field{text} = \fieldfmt{forename} \idx{concat-plus} \qtdelim{ } \idx{concat-plus} \fieldfmt{surname} |
| 12780 |
\oarg{ entrytype \idx{follow} original \idx{equalscmp} \qtdelim{person} }, |
| 12781 |
\field{first} = \gls{FIRSTUC} \marg{ parent \idx{follow} \field{text} } \idx{concat-plus} \qtdelim{ } \idx{concat-plus} \fieldfmt{name} |
| 12782 |
\oarg{ entrytype \idx{follow} original \idx{equalscmp} \qtdelim{monarch} }, |
| 12783 |
\field{text} = \fieldfmt{name} |
| 12784 |
\oarg{ entrytype \idx{follow} original \idx{equalscmp} \qtdelim{monarch} } |
| 12785 |
]{assign-fields} |
| 12786 |
\end{codeenv} |
| 12787 |
|
| 12788 |
Additional fields can be added to accommodate nicknames or other |
| 12789 |
forms of address, which will add to the complexity of the assignment |
| 12790 |
specification. |
| 12791 |
|
| 12792 |
\optsection[\subsubsection]{assign-override} |
| 12793 |
|
| 12794 |
This is a boolean option. The default setting is |
| 12795 |
\csopt[false]{assign-override}. If \optfmt{true}, |
| 12796 |
\csopt{assign-fields} will override the existing value if the |
| 12797 |
target field is already set. |
| 12798 |
|
| 12799 |
\optsection[\subsubsection]{assign-missing-field-action} |
| 12800 |
|
| 12801 |
This option indicates what to do if a source field identified in |
| 12802 |
\csopt{assign-fields} is missing. The value may be one of: |
| 12803 |
\begin{itemize} |
| 12804 |
\item \optfmt{skip}: skip the assignment; |
| 12805 |
\item \optfmt{fallback}: use the fallback for the missing field |
| 12806 |
(see \sectionref{sec:fallbacks}), if |
| 12807 |
one is available, otherwise skip the assignment (default); |
| 12808 |
\item \optfmt{empty}: treat the missing value as empty. |
| 12809 |
\end{itemize} |
| 12810 |
Return null will result in the assignment instruction being omitted. |
| 12811 |
|
| 12812 |
\optsection[\subsubsection]{counter} |
| 12813 |
|
| 12814 |
The \csopt{counter} option assigns the default counter to use |
| 12815 |
for the selected entries. (This can be overridden with the |
| 12816 |
\glsopt{counter} key when using commands like \cs{gls}.) |
| 12817 |
The value must be the name of a counter. Since \bibgls\ doesn't know |
| 12818 |
which counters are defined within the document, there's no check to |
| 12819 |
determine if the value is valid (except for ensuring that |
| 12820 |
\meta{value} is non-empty). |
| 12821 |
A value of \code{false} will switch off this setting (the default). |
| 12822 |
|
| 12823 |
Note that this will require an extra \LaTeX\ and \bibgls\ call since |
| 12824 |
the counter can't be used for the indexing until the entry has been |
| 12825 |
defined. |
| 12826 |
|
| 12827 |
\optsection[\subsubsection]{copy-action-group-field} |
| 12828 |
|
| 12829 |
This option may only be used when invoking \bibgls\ with the |
| 12830 |
\longarg{group} (or \shortargfmt{g}) switch. If an action |
| 12831 |
other than the default \csopt[define]{action} is set, |
| 12832 |
this option can be used to identify a field in which to save |
| 12833 |
the letter group information |
| 12834 |
where \meta{value} is the name of the field. This just uses |
| 12835 |
\cs{GlsXtrSetField}. You will need to redefine |
| 12836 |
\ics{glsxtrgroupfield} to \meta{value} before displaying the glossary. |
| 12837 |
For example, if \csopt[dupgroup]{copy-action-group-field}, |
| 12838 |
\csopt[copy]{action} and \csopt[copies]{type} are set in |
| 12839 |
the resource options and \code{copies} identifies a custom |
| 12840 |
glossary: |
| 12841 |
\begin{codeenv} |
| 12842 |
\ics{printunsrtglossary*}\oarg{\printglossopt[copies]{type},\printglossopt[\glostyle{indexgroup}]{style}} |
| 12843 |
\marg{\cs{renewcommand}\marg{\cs{glsxtrgroupfield}}\marg{dupgroup}} |
| 12844 |
\end{codeenv} |
| 12845 |
|
| 12846 |
This option is ignored when used with \csopt[define]{action}. |
| 12847 |
This option is not used by \csopt{secondary} which will |
| 12848 |
always save the group information in the \field{secondarygroup} |
| 12849 |
field. When used with \csopt[define or copy]{action}, entries |
| 12850 |
that are defined will have both \field{group} and |
| 12851 |
the field given by \csopt{copy-action-group-field} set. |
| 12852 |
|
| 12853 |
Note that you may do \csopt[group]{copy-action-group-field} which |
| 12854 |
will override the \field{group} field from the original definition. |
| 12855 |
This may be useful if you don't use grouping in the |
| 12856 |
\gls{primaryglossary}. That is, you use \code{nogroupskip} and a non-group |
| 12857 |
style. For example: |
| 12858 |
\begin{codeenv} |
| 12859 |
\cs{printunsrtglossary}\oarg{\printglossopt{nogroupskip},\printglossopt[\glostyle{index}]{style}} |
| 12860 |
\cs{printunsrtglossary}\oarg{\printglossopt[copies]{type},\printglossopt[indexgroup]{style}} |
| 12861 |
\end{codeenv} |
| 12862 |
|
| 12863 |
\optsection[\subsubsection]{copy-alias-to-see} |
| 12864 |
|
| 12865 |
If set, the value of the \field{alias} field is copied to |
| 12866 |
the \field{see} field. The default setting is \csopt[false]{copy-alias-to-see}. |
| 12867 |
|
| 12868 |
\subsection{Field Adjustments} |
| 12869 |
\label{sec:fieldmods} |
| 12870 |
|
| 12871 |
\optsection[\subsubsection]{post-description-dot} |
| 12872 |
|
| 12873 |
The \styopt{postdot} package option (or \styopt[false]{nopostdot}) |
| 12874 |
can be used to append a \idx{full-stop} (\idx{periodchar})\ to the |
| 12875 |
end of all the descriptions. This can be awkward if some of the |
| 12876 |
descriptions end with punctuation characters. This resource option |
| 12877 |
can be used instead. The \meta{value} may be one of: |
| 12878 |
\begin{itemize} |
| 12879 |
\item\optfmt{none}: don't append a \idx{full-stop} (default); |
| 12880 |
\item\optfmt{all}: append a \idx{full-stop} to all \field{description} |
| 12881 |
fields in this resource set; |
| 12882 |
\item\optfmt{check}: selectively append a \idx{full-stop} (see below). |
| 12883 |
\end{itemize} |
| 12884 |
Note that if you have dual entries and you use this option to |
| 12885 |
append a \idx{full-stop}, then it will be copied over to the mapped field. |
| 12886 |
This is different to the \styopt{postdot} option which doesn't |
| 12887 |
add the dot to the field but incorporates it in the |
| 12888 |
\idx{postdescriptionhook}. This means that a dot inserted with |
| 12889 |
\csopt{post-description-dot} will come before the |
| 12890 |
\idx{postdescriptionhook} whereas with \styopt{postdot} the |
| 12891 |
punctuation comes after any category-specific hook. |
| 12892 |
|
| 12893 |
The \csopt[check]{post-description-dot} setting determines whether |
| 12894 |
to append the dot as follows: |
| 12895 |
\begin{itemize} |
| 12896 |
\item If the \csopt{post-description-dot-exclude} condition |
| 12897 |
evaluates to true, then a dot isn't appended. |
| 12898 |
\item If the \field{description} field ends with |
| 12899 |
\ics{nopostdesc} or \ics{glsxtrnopostpunc}, then a dot isn't appended. |
| 12900 |
\item If the \field{description} field doesn't end with a regular |
| 12901 |
(ungrouped letter or other) character, then a dot is appended. |
| 12902 |
(For example, if the description ends with a control sequence |
| 12903 |
or an end group token.) |
| 12904 |
\item If the \field{description} field ends with a character |
| 12905 |
that belongs to the Unicode category \idx{punctuationclose} |
| 12906 |
or \idx{punctuationfinalquote} then the token preceding |
| 12907 |
that character is checked. |
| 12908 |
\item If the \field{description} field doesn't end with |
| 12909 |
a character that belongs to the Unicode category |
| 12910 |
\idx{punctuationother} then the dot is added. |
| 12911 |
\end{itemize} |
| 12912 |
Note that the interpreter isn't used during the check. |
| 12913 |
If the \field{description} ends with a command then a dot will be |
| 12914 |
appended (unless it's \cs{glsxtrnopostpunc} or \cs{nopostdesc}) even if |
| 12915 |
that command expands in such a way that it ends with a terminating |
| 12916 |
punctuation character. This option only applies to the |
| 12917 |
\field{description} field. |
| 12918 |
|
| 12919 |
\optsection{post-description-dot-exclude} |
| 12920 |
|
| 12921 |
The value may either be empty, to indicate false (the default), or a |
| 12922 |
complex condition using syntax described in |
| 12923 |
\sectionref{sec:conditionals}. This option is only applicable with |
| 12924 |
\csopt[check]{post-description-dot}. |
| 12925 |
|
| 12926 |
|
| 12927 |
\optsection[\subsubsection]{strip-trailing-nopost} |
| 12928 |
|
| 12929 |
This option is always performed before \csopt{post-description-dot}. |
| 12930 |
The default setting is \csopt[false]{strip-trailing-nopost}. If \optfmt{true} |
| 12931 |
any trailing ungrouped \ics{nopostdesc} or \ics{glsxtrnopostpunc} found in the |
| 12932 |
\field{description} field will be removed. Note that the command (possibly |
| 12933 |
followed by ignored space) must be at the very end of the description for it to |
| 12934 |
be removed. A description should not contain both commands. This option only |
| 12935 |
applies to the \field{description} field. |
| 12936 |
|
| 12937 |
For example, \cs{nopostdesc} will be stripped from: |
| 12938 |
\begin{codeenv} |
| 12939 |
\field{description}=\marg{sample\cs{nopostdesc}} |
| 12940 |
\end{codeenv} |
| 12941 |
since it's at the end. It will also be stripped from: |
| 12942 |
\begin{codeenv} |
| 12943 |
\field{description}=\marg{sample\cs{nopostdesc} } |
| 12944 |
\end{codeenv} |
| 12945 |
since the trailing space is ignored as it follows a control |
| 12946 |
word. It won't be stripped from: |
| 12947 |
\begin{codeenv} |
| 12948 |
\field{description}=\marg{sample\cs{nopostdesc}\marg{} } |
| 12949 |
\end{codeenv} |
| 12950 |
because the final space is now significant, but even without the |
| 12951 |
space it still won't be stripped as the field ends with |
| 12952 |
an empty group not with \cs{nopostdesc}. Similarly it won't be |
| 12953 |
stripped from: |
| 12954 |
\begin{codeenv} |
| 12955 |
\field{description}=\marg{sample\cs{nopostdesc}\cmd{relax}} |
| 12956 |
\end{codeenv} |
| 12957 |
because again it's not at the end. |
| 12958 |
|
| 12959 |
\optsection[\subsubsection]{check-end-punctuation} |
| 12960 |
|
| 12961 |
This options checks the end of all the fields given in \meta{list} for |
| 12962 |
end of sentence punctuation. This is determined as follows, for each |
| 12963 |
\meta{field} in the comma-separated \meta{list}: |
| 12964 |
\begin{itemize} |
| 12965 |
\item if the last character is of type \idx{punctuationclose} |
| 12966 |
or \idx{punctuationfinalquote}, check the character that comes |
| 12967 |
before it; |
| 12968 |
\item if the character is of type \idx{punctuationother}, then check |
| 12969 |
if it's listed in the entry given by \idx{sentence.terminators} |
| 12970 |
in \bibgls's \langxml. |
| 12971 |
\end{itemize} |
| 12972 |
If a sentence terminator is found, an internal field is created |
| 12973 |
called \field{fieldendpunc} that contains the punctuation |
| 12974 |
character. Fields whose values must be labels (such as |
| 12975 |
\field{parent}, \field{category} and \field{type}) aren't checked, |
| 12976 |
even if they're included in \meta{list}. |
| 12977 |
|
| 12978 |
The default \idx{sentence.terminators} is defined in \file{bib2gls-en.xml} |
| 12979 |
as: |
| 12980 |
\begin{verbatim} |
| 12981 |
<entry key="sentence.terminators">.?!</entry> |
| 12982 |
\end{verbatim} |
| 12983 |
Any character that isn't of type \idx{punctuationother} won't |
| 12984 |
match. |
| 12985 |
|
| 12986 |
For example, the sample \exfile!{books.bib} file contains: |
| 12987 |
\begin{codeenv} |
| 12988 |
\atentry{entry}\marg{whydidnttheyaskevans, |
| 12989 |
\field{name}=\marg{Why Didn't They Ask Evans?}, |
| 12990 |
\field{description}=\marg{novel by Agatha Christie}, |
| 12991 |
\fieldfmt{identifier}=\marg{book}, |
| 12992 |
\fieldfmt{author}=\marg{\gls{sortmediacreator}\marg{Agatha}\marg{Christie}}, |
| 12993 |
\fieldfmt{year}=\marg{1934} |
| 12994 |
} |
| 12995 |
\end{codeenv} |
| 12996 |
With \csopt[name]{check-end-punctuation}, this entry will be |
| 12997 |
assigned an internal field called |
| 12998 |
\fielddisp{fieldendpunc}{nameendpunc} set to \code{?}\ |
| 12999 |
as that's included in \idx{sentence.terminators} and is found |
| 13000 |
at the end of the \field{name} field: |
| 13001 |
\begin{codeenv} |
| 13002 |
\cs{GlsXtrSetField}\marg{whydidnttheyaskevans}\marg{nameendpunc}\marg{?} |
| 13003 |
\end{codeenv} |
| 13004 |
(Note that \csopt[first,text]{check-end-punctuation} won't match |
| 13005 |
as there's no \field{first} or \field{text} field supplied.) |
| 13006 |
|
| 13007 |
If you have a field that ends with an abbreviation followed by a |
| 13008 |
\idx{full-stop}, this will be considered an end of sentence terminator, but |
| 13009 |
the main purpose of this option is to provide a way to deal with |
| 13010 |
cases like: |
| 13011 |
\begin{codeenv} |
| 13012 |
Agatha Christie wrote \cs{gls}\marg{whydidnttheyaskevans}. |
| 13013 |
\end{codeenv} |
| 13014 |
where the end of sentence punctuation following \cs{gls} needs to be |
| 13015 |
discarded. This is needed regardless of whether or not |
| 13016 |
the link text ends with an abbreviation or is a complete sentence. |
| 13017 |
|
| 13018 |
It's then possible to hook into the \idx{postlinkhook} \qt{discard |
| 13019 |
period} check. By default this just checks the category attributes |
| 13020 |
that govern whether or not to discard a following period, but |
| 13021 |
(with \styfmt{glossaries-extra} v1.23+) it's possible to provide |
| 13022 |
an additional check by redefining: |
| 13023 |
\nosecdef{glsxtrifcustomdiscardperiod} |
| 13024 |
This should expand to \meta{true} if the check should be performed |
| 13025 |
otherwise it should expand to \meta{false}. You can reference the |
| 13026 |
label using \cs{glslabel}. For example: |
| 13027 |
\begin{codeenv} |
| 13028 |
\cs{renewcommand}*\marg{\gls{glsxtrifcustomdiscardperiod}}[2]\marg{\comment{} |
| 13029 |
\cs{GlsXtrIfFieldUndef}\marg{nameendpunc}\marg{\cs{glslabel}}\marg{\idx{param}2}\marg{\idx{param}1}\comment{} |
| 13030 |
} |
| 13031 |
\end{codeenv} |
| 13032 |
This uses \ics{GlsXtrIfFieldUndef} rather than |
| 13033 |
\ics{glsxtrifhasfield*} since there's no need to access the field's |
| 13034 |
value. (The unstarred form \ics{glsxtrifhasfield} can't be used |
| 13035 |
as it introduces implicit scoping, which would interfere with the |
| 13036 |
punctuation lookahead.) The other difference between |
| 13037 |
\ics{GlsXtrIfFieldUndef} and the other \csfmt{\ldots hasfield} tests |
| 13038 |
is the case where the field is set to an empty value. In this case |
| 13039 |
the field is defined (so \ics{GlsXtrIfFieldUndef} does the |
| 13040 |
\meta{false} argument) but it's considered unset (so commands like |
| 13041 |
\ics{ifglshasfield} do the \meta{false} argument). |
| 13042 |
|
| 13043 |
\optsection[\subsubsection]{sort-label-list} |
| 13044 |
|
| 13045 |
This option takes a list as the value with each element in the list |
| 13046 |
in the form: |
| 13047 |
\begin{codeenv} |
| 13048 |
\code{\meta{field-list}:\meta{sort}:\meta{csname}} |
| 13049 |
\end{codeenv} |
| 13050 |
or: |
| 13051 |
\begin{codeenv} |
| 13052 |
\code{\meta{field-list}:\meta{sort}} |
| 13053 |
\end{codeenv} |
| 13054 |
where: |
| 13055 |
\begin{itemize} |
| 13056 |
\item \meta{field-list} is a comma-separated list of valid fields; |
| 13057 |
\item \meta{sort} is a valid sort method as per the \csopt{sort} |
| 13058 |
option, but not including \optfmt{none} or \optfmt{unsrt}; |
| 13059 |
\item \meta{csname} is the name (without a leading backslash) of a |
| 13060 |
command that takes a label as its sole mandatory argument that's |
| 13061 |
recognised by \bibgls' interpreter (such as those listed in |
| 13062 |
\tableref{tab:bibglsdefs}). |
| 13063 |
\end{itemize} |
| 13064 |
The final \code{:\meta{csname}} part may be omitted if no command |
| 13065 |
need be applied. (That is, sort by label.) The \meta{list} value |
| 13066 |
is required for this option but may be empty, which indicates the setting is |
| 13067 |
switched off. |
| 13068 |
|
| 13069 |
The sorting options are as those for the \gls{mainlist}. For |
| 13070 |
example, for entries in the \glsdisp{mainlist}{primary list} the |
| 13071 |
break point is obtained from the \csopt{break-at} setting and for |
| 13072 |
entries in the \gls{duallist} the break point is obtained from |
| 13073 |
\csopt{dual-break-at}. (Remember that if \csopt[combine]{dual-sort} |
| 13074 |
then there is only one list that contains both the \primary\ and |
| 13075 |
\dual\ entries, which is governed by the \primary\ options only.) |
| 13076 |
|
| 13077 |
If the \meta{field-list} has more than one element |
| 13078 |
take care to use braces \code{\marg{}} to avoid confusion for the |
| 13079 |
list-parser. For example: |
| 13080 |
\begin{codeenv} |
| 13081 |
\gls{GlsXtrLoadResources}\oarg{ |
| 13082 |
\csopt[\marg{see,seealso}:en:glsentryname]{sort-label-list} |
| 13083 |
} |
| 13084 |
\end{codeenv} |
| 13085 |
|
| 13086 |
Note that strange results may occur if this setting is used on any |
| 13087 |
fields that don't simply contain a list of entry labels or if any of |
| 13088 |
the referenced entries are processed in different |
| 13089 |
\iglspl{resourceset} (see \sectionref{sec:resourcesets}). |
| 13090 |
|
| 13091 |
After the main sorting of each set of selected entries is performed |
| 13092 |
(as per \csopt{sort} or \csopt{dual-sort}), if this |
| 13093 |
option is set, then for each |
| 13094 |
\code{\margm{field-list}:\meta{sort}:\meta{csname}} the following |
| 13095 |
steps are performed: |
| 13096 |
\begin{enumerate} |
| 13097 |
\item For each entry \meta{id}: |
| 13098 |
\begin{enumerate} |
| 13099 |
\item For each \meta{field} in \meta{field-list}, if the field is |
| 13100 |
set for entry \meta{id} then: |
| 13101 |
|
| 13102 |
\begin{enumerate} |
| 13103 |
\item The field value must be in the form |
| 13104 |
\code{\oargm{tag}\meta{label-list}} where |
| 13105 |
\code{\oargm{tag}} is optional and |
| 13106 |
\meta{label-list} is a comma-separated list of entry labels |
| 13107 |
\meta{label$_1$}, \ldots, \meta{label$_n$}; |
| 13108 |
\item A new list is constructed where the $i$th element is: |
| 13109 |
\code{\marg{\csfmt{}\meta{csname}\margm{label$_i$}}} |
| 13110 |
unless \meta{csname} hasn't been set, in which case the |
| 13111 |
$i$th element is just \margm{label$_i$} (the optional |
| 13112 |
\oargm{tag} part is omitted); |
| 13113 |
\item This new list is sorted according to the interpreter's |
| 13114 |
definition of the command given by \meta{csname} (if provided) |
| 13115 |
and the designated \meta{sort} method; |
| 13116 |
\item The field value is reconstructed with the labels in the |
| 13117 |
corresponding order (prefixed with \code{\oargm{tag}} if it was |
| 13118 |
present in the original). |
| 13119 |
\end{enumerate} |
| 13120 |
\end{enumerate} |
| 13121 |
\end{enumerate} |
| 13122 |
Note that there is no \hierarchical\ structure in the sorting of the field list |
| 13123 |
even if any of the referenced entries has a \parent. |
| 13124 |
|
| 13125 |
For example, suppose the file \filefmt{entries.bib} contains: |
| 13126 |
\begin{codeenv} |
| 13127 |
\atentry{index}\marg{bird} |
| 13128 |
\strut |
| 13129 |
\atentry{index}\marg{waterfowl, \field{parent}=\marg{bird} } |
| 13130 |
\strut |
| 13131 |
\atentry{index}\marg{duck, |
| 13132 |
\field{parent}=\marg{waterfowl}, |
| 13133 |
\field{seealso}=\marg{swan,duckling,parrot,goose} |
| 13134 |
} |
| 13135 |
\strut |
| 13136 |
\atentry{index}\marg{swan, |
| 13137 |
\field{parent}=\marg{waterfowl}, |
| 13138 |
\field{seealso}=\marg{goose,duck} |
| 13139 |
} |
| 13140 |
\strut |
| 13141 |
\atentry{index}\marg{goose, |
| 13142 |
\field{parent}=\marg{waterfowl}, |
| 13143 |
\field{seealso}=\marg{duck} |
| 13144 |
} |
| 13145 |
\strut |
| 13146 |
\atentry{index}\marg{parrot, \field{parent}=\marg{bird} } |
| 13147 |
\strut |
| 13148 |
\atentry{index}\marg{duckling, |
| 13149 |
\field{see}=\marg{[related terms]fluffy,velociraptor,duck,tardigrade} |
| 13150 |
} |
| 13151 |
\strut |
| 13152 |
\atentry{index}\marg{fluffy} |
| 13153 |
\strut |
| 13154 |
\atentry{index}\marg{tardigrade, \field{name}=\marg{water bear} } |
| 13155 |
\strut |
| 13156 |
\atentry{index}\marg{velociraptor} |
| 13157 |
\end{codeenv} |
| 13158 |
And suppose the document contains: |
| 13159 |
\begin{codeenv} |
| 13160 |
\cmd{documentclass}\marg{article} |
| 13161 |
\strut |
| 13162 |
\cmd{usepackage}[\styopt{record},\styopt[tree]{style}]\marg{glossaries-extra} |
| 13163 |
\strut |
| 13164 |
\gls{GlsXtrLoadResources}\oarg{ |
| 13165 |
\csopt[entries]{src}, |
| 13166 |
\csopt[en]{sort}, |
| 13167 |
\csopt[\marg{seealso,see}:en:glsentryname]{sort-label-list} |
| 13168 |
} |
| 13169 |
\strut |
| 13170 |
\cmd{begin}\marg{document} |
| 13171 |
\cs{Gls}\marg{parrot}, \cs{gls}\marg{tardigrade}, \cs{gls}\marg{swan}, \cs{gls}\marg{duck}, |
| 13172 |
\cs{gls}\marg{goose}, \cs{gls}\marg{fluffy} \cs{gls}\marg{duckling}, \cs{gls}\marg{velociraptor}. |
| 13173 |
\strut |
| 13174 |
\cs{printunsrtglossaries} |
| 13175 |
\cmd{end}\marg{document} |
| 13176 |
\end{codeenv} |
| 13177 |
Then this reorders the \field{see} and \field{seealso} fields according to |
| 13178 |
the referenced entry's name (obtained with \ics{glsentryname}). |
| 13179 |
|
| 13180 |
For example, the \field{see} field for the \code{duckling} entry was |
| 13181 |
originally: |
| 13182 |
\begin{codeenv} |
| 13183 |
\field{see}=\marg{[related terms]fluffy,velociraptor,duck,tardigrade} |
| 13184 |
\end{codeenv} |
| 13185 |
but in the \ext{glstex} file it's written as: |
| 13186 |
\begin{codeenv} |
| 13187 |
\field{see}=\marg{[related terms]duck,fluffy,velociraptor,tardigrade} |
| 13188 |
\end{codeenv} |
| 13189 |
The reason for \code{tardigrade} being placed after |
| 13190 |
\code{velociraptor} is because |
| 13191 |
\code{\ics{glsentryname}\marg{tardigrade}} is expanded to \qt{water |
| 13192 |
bear} (and \qt{W} comes after \qt{V}). If no encapsulating command |
| 13193 |
was specified: |
| 13194 |
\begin{codeenv} |
| 13195 |
\csopt[\marg{seealso,see}:en]{sort-label-list} |
| 13196 |
\end{codeenv} |
| 13197 |
then the list would have been sorted according to the labels |
| 13198 |
instead (and so \code{tardigrade} would come before |
| 13199 |
\code{velociraptor}). Note that the optional tag is kept at the start of the |
| 13200 |
list. |
| 13201 |
|
| 13202 |
The \field{seealso} fields have also been changed. For example, |
| 13203 |
the \code{duck} entry originally had: |
| 13204 |
\begin{codeenv} |
| 13205 |
\field{seealso}=\marg{swan,duckling,parrot,goose} |
| 13206 |
\end{codeenv} |
| 13207 |
but in the \ext{glstex} file it's written as: |
| 13208 |
\begin{codeenv} |
| 13209 |
\field{seealso}=\marg{duckling,goose,parrot,swan} |
| 13210 |
\end{codeenv} |
| 13211 |
Note that the \hierarchical\ structure hasn't been maintained. The glossary |
| 13212 |
lists \qt{duckling} (a \gls{top-levelentry}) after \qt{swan} (a level~2 entry) |
| 13213 |
but the \field{seealso} field has \code{duckling} first. |
| 13214 |
|
| 13215 |
If you want to maintain the \hierarchy\ you can use \ics{glsxtrhiername} instead |
| 13216 |
of \ics{glsentryname}: |
| 13217 |
\begin{codeenv} |
| 13218 |
\gls{GlsXtrLoadResources}\oarg{ |
| 13219 |
\csopt[entries]{src}, |
| 13220 |
\csopt[en]{sort}, |
| 13221 |
\csopt[\marg{seealso,see}:en:glsxtrhiername]{sort-label-list} |
| 13222 |
} |
| 13223 |
\end{codeenv} |
| 13224 |
The separator between the levels is |
| 13225 |
given by \ics{glsxtrhiernamesep} which is defined by |
| 13226 |
\sty{glossaries-extra} to produce \qt{\glsxtrhiernamesep}. |
| 13227 |
The \bibgls\ interpreter's definition of this command is different |
| 13228 |
to assist sorting and simply expands to a \idx{full-stop} to prevent |
| 13229 |
it from being replaced by the default word break marker. |
| 13230 |
|
| 13231 |
In this case \code{\ics{glsxtrhiername}\marg{swan}} would be |
| 13232 |
displayed as \qt{bird\glsxtrhiernamesep waterfowl\glsxtrhiernamesep |
| 13233 |
swan} if used in the document, but the interpreter converts it to |
| 13234 |
\qt{bird.waterfowl.swan}, so with the default \csopt{break-at} |
| 13235 |
setting the actual sort value becomes \code{bird.waterfowl.swan|} |
| 13236 |
(instead of \code{bird|waterfowl|swan|} which would be the result if |
| 13237 |
the interpreter used the same definition as \sty{glossaries-extra}). |
| 13238 |
|
| 13239 |
Therefore the \field{seealso} field for the \code{duck} entry ends up as: |
| 13240 |
\begin{codeenv} |
| 13241 |
\field{seealso}=\marg{parrot,goose,swan,duckling} |
| 13242 |
\end{codeenv} |
| 13243 |
Now \code{swan} comes before \code{duckling} because the actual sort |
| 13244 |
value started with a \qt{B} not \qt{S}. |
| 13245 |
|
| 13246 |
This \hierarchical\ information isn't shown in the cross-reference by |
| 13247 |
default, so the \code{duck} cross-reference list appears in the |
| 13248 |
document as: parrot, goose, swan \& duckling. |
| 13249 |
|
| 13250 |
If you want the \hierarchical\ information to appear to help assist |
| 13251 |
the reader, you can redefine \ics{glsseeitemformat} in the document |
| 13252 |
to use \ics{glsxtrhiername}: |
| 13253 |
\begin{codeenv} |
| 13254 |
\cmd{renewcommand}*\marg{\cs{glsseeitemformat}}[1]\marg{\cs{glsxtrhiername}\marg{\idx{param}1}} |
| 13255 |
\end{codeenv} |
| 13256 |
This means that the \code{duck} cross-reference now appears in the |
| 13257 |
document as: bird\glsxtrhiernamesep parrot, bird\glsxtrhiernamesep |
| 13258 |
waterfowl\glsxtrhiernamesep goose, bird\glsxtrhiernamesep waterfowl |
| 13259 |
\glsxtrhiernamesep swan \& duckling. |
| 13260 |
|
| 13261 |
This next example document has two languages, English and |
| 13262 |
Portuguese. The file \filefmt{entries-en.bib} contains the English |
| 13263 |
terms, such as: |
| 13264 |
\begin{codeenv} |
| 13265 |
\atentry{index}\marg{cat, \fieldfmt{translations}=\marg{gato,gatinho} } |
| 13266 |
\atentry{index}\marg{kitten, \fieldfmt{translations}=\marg{gatinho} } |
| 13267 |
\atentry{index}\marg{staple, \fieldfmt{translations}=\marg{grampo}} |
| 13268 |
\atentry{index}\marg{rivet, \fieldfmt{translations}=\marg{rebite}} |
| 13269 |
\end{codeenv} |
| 13270 |
The file \filefmt{entries-pt.bib} contains the Portuguese |
| 13271 |
terms, such as: |
| 13272 |
\begin{codeenv} |
| 13273 |
\atentry{index}\marg{gato, \fieldfmt{translations}=\marg{cat,staple,rivet} } |
| 13274 |
\atentry{index}\marg{gatinho, \fieldfmt{translations}=\marg{kitten} } |
| 13275 |
\end{codeenv} |
| 13276 |
|
| 13277 |
Both files have a custom field called \fieldfmt{translations} that |
| 13278 |
will need to be either defined or aliased. This field contains a |
| 13279 |
comma-separated list of labels for the corresponding entries in the |
| 13280 |
other language file that provide a possible translation. Where a |
| 13281 |
word has multiple possible translations, I'd like the list sorted |
| 13282 |
alphabetically. (In practice, it would make more sense to sort them |
| 13283 |
according to how likely the translation is, but this is for |
| 13284 |
illustrative purposes.) For convenience, the |
| 13285 |
custom field is simply aliased to the \field{user1} field. |
| 13286 |
|
| 13287 |
The document has two glossaries for each set of terms. The English |
| 13288 |
terms are sorted according to \csopt[en-GB]{sort} in one |
| 13289 |
\igls{resourceset} and the Portuguese terms are sorted according to |
| 13290 |
\csopt[pt-BR]{sort} in another \igls{resourceset}. This means that there |
| 13291 |
are cross-resource references, but since there are no instances of |
| 13292 |
\atentry{preamble} it should be possible to resolve the references. |
| 13293 |
|
| 13294 |
The document code is: |
| 13295 |
\begin{codeenv} |
| 13296 |
\cmd{documentclass}\marg{article} |
| 13297 |
\strut |
| 13298 |
\cmd{usepackage}[T1]\marg{fontenc} |
| 13299 |
\cmd{usepackage}[utf8]\marg{inputenc} |
| 13300 |
\cmd{usepackage}[british,brazilian]\marg{babel} |
| 13301 |
\cmd{usepackage}\oarg{\styopt{record}, |
| 13302 |
\styopt{nomain}, |
| 13303 |
\styopt{nostyles}, |
| 13304 |
\styopt[bookindex]{stylemods}, |
| 13305 |
\styopt[bookindex]{style} |
| 13306 |
}\marg{glossaries-extra} |
| 13307 |
\cmd{usepackage}\marg{glossaries-prefix} |
| 13308 |
\strut |
| 13309 |
\cs{newglossary*}\marg{en}\marg{English Terms} |
| 13310 |
\cs{newglossary*}\marg{pt}\marg{Portuguese Terms} |
| 13311 |
\strut |
| 13312 |
\gls{GlsXtrLoadResources}\oarg{ |
| 13313 |
\csopt[all]{selection}, |
| 13314 |
\csopt[en]{type}, |
| 13315 |
\csopt[entries-en]{src}, |
| 13316 |
\csopt[en-GB]{sort}, |
| 13317 |
\csopt[\fieldfmt{translations}=\field{user1}]{field-aliases}, |
| 13318 |
\csopt[\field{user1}:pt-BR:\encap{glsentryname}]{sort-label-list} |
| 13319 |
} |
| 13320 |
\gls{GlsXtrLoadResources}\oarg{ |
| 13321 |
\csopt[all]{selection}, |
| 13322 |
\csopt[pt]{type}, |
| 13323 |
\csopt[entries-pt]{src}, |
| 13324 |
\csopt[pt-BR]{sort}, |
| 13325 |
\csopt[\fieldfmt{translations}=\field{user1}]{field-aliases}, |
| 13326 |
\csopt[\field{user1}:en-GB:\encap{glsentryname}]{sort-label-list} |
| 13327 |
} |
| 13328 |
\strut |
| 13329 |
\cs{apptoglossarypreamble}\oarg{en}\marg{\ics{selectlanguage}\marg{british}} |
| 13330 |
\cs{apptoglossarypreamble}\oarg{pt}\marg{\cs{selectlanguage}\marg{brazilian}} |
| 13331 |
\strut |
| 13332 |
\cmd{begin}\marg{document} |
| 13333 |
\cs{renewcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\comment{} |
| 13334 |
\cs{glossentryname}\marg{\idx{param}1}\comment{} |
| 13335 |
\cs{glsxtrifhasfield}\marg{useri}\marg{\idx{param}1}\marg{: \ics{glsxtrseelist}\cs{glscurrentfieldvalue}}\marg{}\comment{} |
| 13336 |
} |
| 13337 |
\cs{printunsrtglossaries} |
| 13338 |
\cmd{end}\marg{document} |
| 13339 |
\end{codeenv} |
| 13340 |
In verbose mode, the transcript file indicates that it's performing |
| 13341 |
the label list sorting. For example, when sorting according to |
| 13342 |
\csopt[user1:pt-BR:glsentryname]{sort-label-list}, the transcript |
| 13343 |
file contains: |
| 13344 |
\begin{verbatim} |
| 13345 |
Label list sort method 'pt-BR' on field: user1 |
| 13346 |
\end{verbatim} |
| 13347 |
The \code{cat} entry has a list of two elements in this field: |
| 13348 |
\code{gato,gatinho}. This is converted into a new list where the |
| 13349 |
first element is: |
| 13350 |
\begin{codeenv} |
| 13351 |
\marg{\cs{glsentryname}\marg{gato}} |
| 13352 |
\end{codeenv} |
| 13353 |
and the second element is: |
| 13354 |
\begin{codeenv} |
| 13355 |
\marg{\cs{glsentryname}\marg{gatinho}} |
| 13356 |
\end{codeenv} |
| 13357 |
Regardless of the level of verbosity, the transcript file will |
| 13358 |
contain the conversions obtained by the interpreter: |
| 13359 |
\begin{verbatim} |
| 13360 |
texparserlib: {\glsentryname{gato}} -> gato |
| 13361 |
texparserlib: {\glsentryname{gatinho}} -> gatinho |
| 13362 |
\end{verbatim} |
| 13363 |
The \code{kitten} entry has the same list, and the same process is |
| 13364 |
repeated for that entry. The \commonlongarg{verbose} mode will provide additional |
| 13365 |
information. The \commonlongarg{debug} mode will indicate whether the |
| 13366 |
referenced label was found in the current \igls{resourceset} or if it had |
| 13367 |
to be fetched from another \igls{resourceset}. So if the resulting |
| 13368 |
order isn't what you expect, check the transcript file for messages. |
| 13369 |
|
| 13370 |
\optsection[\subsubsection]{prune-xr} |
| 13371 |
|
| 13372 |
If true, this is a shortcut for: |
| 13373 |
\begin{codeenv} |
| 13374 |
\csopt[entrytype=\marg{index(plural)?},see=\marg{},seealso=\marg{},alias=\marg{}]{prune-see-match}, |
| 13375 |
\csopt[entrytype=\marg{index(plural)?},see=\marg{},seealso=\marg{},alias=\marg{}]{prune-seealso-match}, |
| 13376 |
\end{codeenv} |
| 13377 |
|
| 13378 |
This will remove any labels in an entry's \field{see} or |
| 13379 |
\field{seealso} field where the referenced label doesn't have any |
| 13380 |
records and hasn't been selected as another form of dependency and |
| 13381 |
whose \gls{entrytype} is either \atentry{index} or \atentry{indexplural} |
| 13382 |
and doesn't have the \field{see}, \field{seealso} or \field{alias} |
| 13383 |
fields set. |
| 13384 |
|
| 13385 |
Both \csopt{prune-see-match} and \csopt{prune-seealso-match} can be |
| 13386 |
switched off at the same time with \csopt[false]{prune-xr}. |
| 13387 |
|
| 13388 |
\optsection[\subsubsection]{prune-see-match} |
| 13389 |
|
| 13390 |
The value has the same syntax as \csopt{match}. Omitting the value |
| 13391 |
switches off the setting. This option is not cumulative. |
| 13392 |
|
| 13393 |
If a value is supplied, this setting will attempt to prune unnecessary |
| 13394 |
labels from \field{see} fields. Note that pruning may fail if there |
| 13395 |
are cross-reference trails. |
| 13396 |
|
| 13397 |
A label will be stripped from a \field{see} field if the label |
| 13398 |
references an entry that has no records, isn't dependent on another |
| 13399 |
entry, hasn't previously been selected, and matches the given |
| 13400 |
criteria. If more that one pattern match is supplied, |
| 13401 |
\csopt{prune-see-op} determines whether to apply a logical AND or a |
| 13402 |
logical OR. |
| 13403 |
|
| 13404 |
For example, suppose the file \filefmt{entries.bib} contains the |
| 13405 |
following: |
| 13406 |
\begin{codeenv} |
| 13407 |
\atentry{index}\marg{pumpkin} |
| 13408 |
\atentry{index}\marg{cucumber} |
| 13409 |
\atentry{index}\marg{melon} |
| 13410 |
\atentry{index}\marg{cucurbit,\field{see}=\marg{gourd}} |
| 13411 |
\atentry{index}\marg{gourd,\field{see}=\marg{pumpkin,cucumber,melon}} |
| 13412 |
\atentry{index}\marg{courgette} |
| 13413 |
\atentry{index}\marg{marrow,\field{seealso}=\marg{courgette}} |
| 13414 |
\atentry{index}\marg{broccoli} |
| 13415 |
\atentry{index}\marg{cauliflower,\field{seealso}=\marg{broccoli}} |
| 13416 |
\end{codeenv} |
| 13417 |
Suppose the document contains: |
| 13418 |
\begin{codeenv} |
| 13419 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}} |
| 13420 |
\cmd{begin}\marg{document} |
| 13421 |
\cs{gls}\marg{cucurbit}, \cs{gls}\marg{pumpkin}, \cs{gls}\marg{melon}, \cs{gls}\marg{broccoli}, |
| 13422 |
\cs{gls}\marg{marrow}, \cs{gls}\marg{cauliflower}. |
| 13423 |
\cs{printunsrtglossary}\oarg{title=Index} |
| 13424 |
\cmd{end}\marg{document} |
| 13425 |
\end{codeenv} |
| 13426 |
This uses the default \csopt[recorded and deps]{selection} setting, |
| 13427 |
which selects recorded entries (cucurbit, pumpkin, melon, broccoli, |
| 13428 |
marrow and cauliflower) and their dependencies. In this case, the |
| 13429 |
dependencies are: courgette (because it's listed in the marrow's |
| 13430 |
\field{seealso} field), gourd (because it's listed in the cucurbit's |
| 13431 |
\field{see} field), and cucumber (because it's listed in the |
| 13432 |
gourd's \field{see} field). |
| 13433 |
The resulting list is: |
| 13434 |
\begin{quote} |
| 13435 |
\setlength{\parindent}{0pt}% |
| 13436 |
\setlength{\parskip}{0pt plus 0.3pt}% |
| 13437 |
\glstreeitem broccoli 1\par |
| 13438 |
\glstreeitem cauliflower 1, \emph{see also} broccoli\par |
| 13439 |
\glstreeitem courgette\par |
| 13440 |
\glstreeitem cucumber\par |
| 13441 |
\glstreeitem cucurbit 1, \emph{see} gourd\par |
| 13442 |
\glstreeitem gourd \emph{see} pumpkin, cucumber \& melon\par |
| 13443 |
\glstreeitem marrow 1, \emph{see also} courgette\par |
| 13444 |
\glstreeitem melon 1\par |
| 13445 |
\glstreeitem pumpkin 1\par |
| 13446 |
\end{quote} |
| 13447 |
|
| 13448 |
This means that courgette and cucumber appear in the glossary |
| 13449 |
without a \igls{locationlist}. If this was an actual glossary with |
| 13450 |
descriptions, this may not be a problem, but it looks strange for an |
| 13451 |
index since the cross-reference essentially leads the reader to a dead end. |
| 13452 |
|
| 13453 |
Switching to \csopt[recorded no deps]{selection} will remove |
| 13454 |
courgette, gourd and cucumber but the \field{see} and |
| 13455 |
\field{seealso} fields will be lost. Since gourd references both |
| 13456 |
pumpkin and melon (which are used in the document), it might be |
| 13457 |
useful to keep the gourd entry. The aim of pruning is to remove the |
| 13458 |
unwanted cucumber entry from the gourd's \field{see} list but retain |
| 13459 |
pumpkin and melon. |
| 13460 |
|
| 13461 |
An appropriate filter is needed to switch on pruning. (This is in |
| 13462 |
addition to the criteria that the pruned entry has no records, isn't |
| 13463 |
dependent on another entry, and hasn't previously been selected.) |
| 13464 |
This type of pruning is usually only necessary for indexes so a |
| 13465 |
useful filter may be simply on the \gls{entrytype} (either |
| 13466 |
\atentry{index} or \atentry{indexplural}): |
| 13467 |
\begin{codeenv} |
| 13468 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}, |
| 13469 |
\csopt[entrytype=\marg{index(plural)?}]{prune-see-match}} |
| 13470 |
\end{codeenv} |
| 13471 |
Another possibility is to filter on an empty \field{description}: |
| 13472 |
\begin{codeenv} |
| 13473 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[description=\marg{}]{prune-see-match}} |
| 13474 |
\end{codeenv} |
| 13475 |
|
| 13476 |
The result is that the cauliflower and marrow entries keep their |
| 13477 |
\field{seealso} lists (since this option only applies to \field{see} |
| 13478 |
lists) and the courgette entry has been added (because it's |
| 13479 |
in the marrow entry's \field{seealso} list). The gourd entry is |
| 13480 |
removed from the cucurbit's \field{see} list (because it matches the |
| 13481 |
criteria) and is not selected (because it's no longer a dependency). |
| 13482 |
|
| 13483 |
In this case, I'd like to include the gourd entry because it has the |
| 13484 |
\field{see} field set. This means adjusting the criteria so that |
| 13485 |
only entries without the \field{see} field can be pruned: |
| 13486 |
\begin{codeenv} |
| 13487 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}, |
| 13488 |
\csopt[entrytype=\marg{index(plural)?},see=\marg{}]{prune-see-match}} |
| 13489 |
\end{codeenv} |
| 13490 |
This means that gourd is now selected (and retained in the |
| 13491 |
cucurbit's \field{see} field) but cucumber is removed from the |
| 13492 |
gourd's \field{see} field. |
| 13493 |
|
| 13494 |
A similar method can be applied for the \field{seealso} fields using |
| 13495 |
\csopt{prune-seealso-match}. There's no applicable setting for the |
| 13496 |
\field{alias} field (since it's expected that the alias be present |
| 13497 |
due to the nature of the way the \field{alias} field works). |
| 13498 |
|
| 13499 |
For convenience, the \csopt{prune-xr} option is provided as a |
| 13500 |
shortcut. If the resource command in the above example is modified |
| 13501 |
to: |
| 13502 |
\begin{codeenv} |
| 13503 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt{prune-xr}} |
| 13504 |
\end{codeenv} |
| 13505 |
then the resulting list will be: |
| 13506 |
\begin{quote} |
| 13507 |
\setlength{\parindent}{0pt}% |
| 13508 |
\setlength{\parskip}{0pt plus 0.3pt}% |
| 13509 |
\glstreeitem broccoli 1\par |
| 13510 |
\glstreeitem cauliflower 1, \emph{see also} broccoli\par |
| 13511 |
\glstreeitem cucurbit 1, \emph{see} gourd\par |
| 13512 |
\glstreeitem gourd \emph{see} pumpkin \& melon\par |
| 13513 |
\glstreeitem marrow 1\par |
| 13514 |
\glstreeitem melon 1\par |
| 13515 |
\glstreeitem pumpkin 1\par |
| 13516 |
\end{quote} |
| 13517 |
|
| 13518 |
Note that if the pumpkin and melon references are removed from the |
| 13519 |
document, then gourd will still be selected but will have no |
| 13520 |
cross-reference. This is because the cucurbit entry is checked for |
| 13521 |
pruning while the gourd entry still has a non-empty \field{see} |
| 13522 |
field so it's not removed from the cucurbit entry. |
| 13523 |
|
| 13524 |
There are two ways around this problem: either switch the |
| 13525 |
definitions of cucurbit and gourd around in the \ext{bib} file |
| 13526 |
or use \csopt{prune-iterations} to reprune (in this case, |
| 13527 |
\csopt[2]{prune-iterations} is sufficient). |
| 13528 |
|
| 13529 |
\begin{important} |
| 13530 |
This setting is only compatible with the \qt{recorded and dep} |
| 13531 |
selection criteria: \csopt[recorded and |
| 13532 |
deps]{selection}, \csopt[recorded and deps and see]{selection} |
| 13533 |
and \csopt[recorded and deps and see not also]{selection}. |
| 13534 |
\end{important} |
| 13535 |
|
| 13536 |
\optsection[\subsubsection]{prune-see-op} |
| 13537 |
|
| 13538 |
If the value of \csopt{prune-see-match} contains more than one |
| 13539 |
\meta{key}=\meta{pattern} element, the \csopt{prune-see-op} |
| 13540 |
determines whether to apply a logical AND or a logical OR. |
| 13541 |
The \meta{value} may be either \optfmt{and} or \optfmt{or}. |
| 13542 |
The default is \csopt[and]{prune-see-op}. |
| 13543 |
|
| 13544 |
\optsection[\subsubsection]{prune-seealso-match} |
| 13545 |
|
| 13546 |
As \csopt{prune-see-match} but for \field{seealso} fields. If more |
| 13547 |
that one pattern match is supplied, \csopt{prune-seealso-op} |
| 13548 |
determines whether to apply a logical AND or a logical OR. |
| 13549 |
|
| 13550 |
\begin{important} |
| 13551 |
This setting is only compatible with the \qt{recorded and dep} |
| 13552 |
selection criteria: \csopt[recorded and |
| 13553 |
deps]{selection}, \csopt[recorded and deps and see]{selection} |
| 13554 |
and \csopt[recorded and deps and see not also]{selection}. |
| 13555 |
\end{important} |
| 13556 |
|
| 13557 |
\optsection[\subsubsection]{prune-seealso-op} |
| 13558 |
|
| 13559 |
If the value of \csopt{prune-seealso-match} contains more than one |
| 13560 |
\meta{key}=\meta{pattern} element, the \csopt{prune-seealso-op} |
| 13561 |
determines whether to apply a logical AND or a logical OR. |
| 13562 |
The \meta{value} may be either \optfmt{and} or \optfmt{or}. |
| 13563 |
The default is \csopt[and]{prune-seealso-op}. |
| 13564 |
|
| 13565 |
\optsection[\subsubsection]{prune-iterations} |
| 13566 |
|
| 13567 |
If you have cross-reference trails, you may need to reprune. The |
| 13568 |
value of this options indicates the number of pruning iterations. |
| 13569 |
The default is 1. The higher the number, the longer \bibgls\ will |
| 13570 |
take to complete. The value can't be less that 1. |
| 13571 |
|
| 13572 |
The maximum number of iterations is capped at 20. A cross-reference |
| 13573 |
trail that long is excessive for an index. |
| 13574 |
|
| 13575 |
\optsection[\subsubsection]{bibtex-contributor-fields} |
| 13576 |
|
| 13577 |
This option indicates that the listed fields all use \BibTeX's name |
| 13578 |
syntax (as used in \BibTeX's \code{author} and \code{editor} fields). |
| 13579 |
The \meta{list} value is required for this key but |
| 13580 |
may be empty, which indicates an empty set of fields (that is, the |
| 13581 |
setting is switched off). |
| 13582 |
|
| 13583 |
The values of these fields will be converted into the form: |
| 13584 |
\begin{codeenv} |
| 13585 |
\gls{bibglscontributorlist}\margm{contributor list}\margm{n} |
| 13586 |
\end{codeenv} |
| 13587 |
where \meta{n} is the number of names in the list and |
| 13588 |
\meta{contributor-list} is a comma-separated list of names in the |
| 13589 |
form: |
| 13590 |
\begin{codeenv} |
| 13591 |
\gls{bibglscontributor}\margm{forenames}\margm{von-part}\margm{surname}\margm{suffix} |
| 13592 |
\end{codeenv} |
| 13593 |
|
| 13594 |
The \gls{bibglscontributorlist} command is initially defined in |
| 13595 |
\bibgls's interpreter to just do the first argument and ignore the |
| 13596 |
second. This means that if you're sorting on this field, the \qt{and} |
| 13597 |
part between the final names doesn't appear in the sort value. |
| 13598 |
The actual definition of \gls{bibglscontributorlist} provided in the |
| 13599 |
\ext{glstex} file depends on whether or not \ics{DTLformatlist} is defined. |
| 13600 |
(Note that \styfmt{glossaries} automatically loads \sty{datatool-base} |
| 13601 |
so this command will be defined if you have at least v2.28 of |
| 13602 |
\sty{datatool-base}.) |
| 13603 |
|
| 13604 |
For example, if the \field{name} field is specified as: |
| 13605 |
\begin{codeenv} |
| 13606 |
\field{name}=\marg{John Smith and Jane Doe and Dickie von Duck} |
| 13607 |
\end{codeenv} |
| 13608 |
then \csopt[name]{bibtex-contributor-fields} will convert the |
| 13609 |
\field{name} field value to: |
| 13610 |
\begin{codeenv} |
| 13611 |
\gls{bibglscontributorlist}\marg{\comment{} |
| 13612 |
\gls{bibglscontributor}\marg{John}\marg{}\marg{Smith}\marg{},\comment{} |
| 13613 |
\gls{bibglscontributor}\marg{Jane}\marg{}\marg{Doe}\marg{},\comment{} |
| 13614 |
\gls{bibglscontributor}\marg{Dickie}\marg{von}\marg{Duck}\marg{}}\marg{3} |
| 13615 |
\end{codeenv} |
| 13616 |
With \csopt[von]{contributor-order} the sort value obtained from |
| 13617 |
this field will be: |
| 13618 |
\begin{verbatim} |
| 13619 |
Smith, John,Doe, Jane,von Duck, Dickie |
| 13620 |
\end{verbatim} |
| 13621 |
With one of the locale sort methods and with the default |
| 13622 |
\csopt[word]{break-at}, this will end up as: |
| 13623 |
\begin{verbatim} |
| 13624 |
Smith|John|Doe|Jane|von|Duck|Dickie |
| 13625 |
\end{verbatim} |
| 13626 |
|
| 13627 |
\optsection[\subsubsection]{contributor-order} |
| 13628 |
|
| 13629 |
The \gls{bibglscontributor} command is defined in |
| 13630 |
\bibgls's interpreter and its definition is dependent on this |
| 13631 |
setting. The \meta{value} may be one of (where the parts in square |
| 13632 |
brackets are omitted if that argument is empty): |
| 13633 |
\begin{itemize} |
| 13634 |
\item \optfmt{surname}: \gls{bibglscontributor} expands to |
| 13635 |
\meta{surname}\oarg{, \meta{suffix}}\oarg{, \meta{forenames}}\oarg{, |
| 13636 |
\meta{von-part}}; |
| 13637 |
\item \optfmt{von}: \gls{bibglscontributor} expands to |
| 13638 |
\oarg{\meta{von-part} }\meta{surname}\oarg{, \meta{suffix}}\oarg{, \meta{forenames}}; |
| 13639 |
\item \optfmt{forenames}: \gls{bibglscontributor} expands to |
| 13640 |
\oarg{\meta{forenames} }\oarg{\meta{von-part} }\meta{surname}\oarg{, |
| 13641 |
\meta{suffix}}. |
| 13642 |
\end{itemize} |
| 13643 |
The default value is \optfmt{von}. Note that if you have multiple |
| 13644 |
resource sets, this option governs the way \bibgls's version of |
| 13645 |
\gls{bibglscontributor} behaves. The actual definition is written to |
| 13646 |
the \ext{glstex} using \cs{providecommand}, which means that \LaTeX\ |
| 13647 |
will only pick up the first definition. |
| 13648 |
|
| 13649 |
For example: |
| 13650 |
\begin{codeenv} |
| 13651 |
\cs{newcommand}*\marg{\gls{bibglscontributor}}[4]\marg{\comment{} |
| 13652 |
\idx{param}1\ics{ifstrempty}\marg{\idx{param}2}\marg{}\marg{ \idx{param}2} \idx{param}3\cs{ifstrempty}\marg{\idx{param}4}\marg{}\marg{, \idx{param}4}\comment{} |
| 13653 |
} |
| 13654 |
\strut |
| 13655 |
\gls{GlsXtrLoadResources}\oarg{ |
| 13656 |
\csopt[entries]{src},\comment{data in entries.bib} |
| 13657 |
\csopt[name]{bibtex-contributor-fields} |
| 13658 |
} |
| 13659 |
\end{codeenv} |
| 13660 |
This will display the names in the glossary with the forenames |
| 13661 |
first, but \bibgls\ will sort according to surname. |
| 13662 |
|
| 13663 |
An alternative approach, if you need an initial resource set |
| 13664 |
such as with the \exfile{no-interpret-preamble.bib} file: |
| 13665 |
\begin{codeenv} |
| 13666 |
\gls{GlsXtrLoadResources}\oarg{ |
| 13667 |
\csopt[no-interpret-preamble]{src}, |
| 13668 |
\csopt[false]{interpret-preamble}, |
| 13669 |
\csopt[name]{bibtex-contributor-fields}, |
| 13670 |
\csopt[forenames]{contributor-order} |
| 13671 |
} |
| 13672 |
\strut |
| 13673 |
\gls{GlsXtrLoadResources}\oarg{ |
| 13674 |
\csopt[entries]{src},\comment{data in entries.bib} |
| 13675 |
\csopt[name]{bibtex-contributor-fields} |
| 13676 |
} |
| 13677 |
\end{codeenv} |
| 13678 |
Note the need to use \csopt[name]{bibtex-contributor-fields} |
| 13679 |
in the first resource set even though there are no entries in |
| 13680 |
the \ext{bib} file. This is because the definition of |
| 13681 |
\gls{bibglscontributor} is only written to the \ext{glstex} file if |
| 13682 |
\csopt{bibtex-contributor-fields} has been set to a non-empty list. |
| 13683 |
The second resource set will use the default |
| 13684 |
\csopt[von]{bibtex-contributor-fields} setting when obtaining the |
| 13685 |
sort value. |
| 13686 |
|
| 13687 |
\optsection[\subsubsection]{encapsulate-fields} |
| 13688 |
|
| 13689 |
This option should take a comma-separated list of |
| 13690 |
\optfmt{\meta{field}\dequals\meta{cs-name-1arg}} values, where |
| 13691 |
\meta{cs-name-1arg} is the name of a control sequence that takes |
| 13692 |
one argument. The value is required for this key but |
| 13693 |
may be empty, which indicates an empty set (that is, the |
| 13694 |
setting is switched off). |
| 13695 |
|
| 13696 |
During the processing stage, each field identified in |
| 13697 |
the list (if defined) will have its value replaced with: |
| 13698 |
\begin{codeenv} |
| 13699 |
\cmd{\meta{cs-name-1arg}}\margm{value} |
| 13700 |
\end{codeenv} |
| 13701 |
where \meta{value} was its previous value. An |
| 13702 |
empty list switches off encapsulation (the default). |
| 13703 |
|
| 13704 |
This action overrides any previous use of \csopt{encapsulate-fields} |
| 13705 |
within the same \igls{resourceset} and is always performed before |
| 13706 |
\csopt{encapsulate-fields*}, regardless of the order in the |
| 13707 |
\igls{resourceset}['s] list of options. |
| 13708 |
|
| 13709 |
\optsection[\subsubsection]{encapsulate-fields*} |
| 13710 |
|
| 13711 |
This option should take a comma-separated list of |
| 13712 |
\optfmt{\meta{field}\dequals\meta{cs-name-2arg}} values, where |
| 13713 |
\meta{cs-name-2arg} is the name of a control sequence that takes two |
| 13714 |
arguments. The value is required for this key but |
| 13715 |
may be empty, which indicates an empty set (that is, the |
| 13716 |
setting is switched off). |
| 13717 |
|
| 13718 |
During the processing stage, each field identified in the |
| 13719 |
list (if defined) will have its value replaced with: |
| 13720 |
\begin{codeenv} |
| 13721 |
\cmd{\meta{cs-name-2arg}}\margm{value}\margm{label} |
| 13722 |
\end{codeenv} |
| 13723 |
where \meta{value} was its previous value and \meta{label} is the |
| 13724 |
entry's label (including prefix, if appropriate). An |
| 13725 |
empty list switches off encapsulation (the default). |
| 13726 |
|
| 13727 |
This action overrides any previous use of |
| 13728 |
\csopt{encapsulate-fields*} within the same \igls{resourceset}, and |
| 13729 |
is always performed after \csopt{encapsulate-fields}, regardless of |
| 13730 |
the order in the \igls{resourceset}['s] list of options, so if the |
| 13731 |
same field is listed in both settings, its value will end up as: |
| 13732 |
\begin{codeenv} |
| 13733 |
\cmd{\meta{cs-name-2arg}}\marg{\cmd{\meta{cs-name-1arg}}\margm{value}}\margm{label} |
| 13734 |
\end{codeenv} |
| 13735 |
An alternative is to use the more complex \csopt{assign-fields} option. |
| 13736 |
|
| 13737 |
\optsection[\subsubsection]{format-integer-fields} |
| 13738 |
|
| 13739 |
This option should take a comma-separated list of |
| 13740 |
\optfmt{\meta{field}\dequals\meta{format}} values, where |
| 13741 |
\meta{format} is a |
| 13742 |
\href{https://docs.oracle.com/javase/8/docs/api/java/util/Formatter.html#syntax}{string |
| 13743 |
format pattern} that contains a single numeric specifier. |
| 13744 |
This will convert the value stored in the identified field to the |
| 13745 |
given format. If the field doesn't contain an integer value it won't |
| 13746 |
be changed. If the field contains a decimal value use |
| 13747 |
\csopt{format-decimal-fields} instead. This setting is performed |
| 13748 |
before field encapsulation. |
| 13749 |
|
| 13750 |
Since format patterns uses \idx{percentchar} as a placeholder, which |
| 13751 |
can be problematic in the resource command, you will need to use |
| 13752 |
\ics{cs.percent} instead. You may also use \ics{cs.hash}, |
| 13753 |
\ics{cs.dollar}, \ics{cs.amp}, \ics{cs.openbrace}, |
| 13754 |
\ics{cs.closebrace}, \ics{cs.underscore} and \ics{cs.backslash} to |
| 13755 |
indicate the corresponding literal character. You can use \cs{u}\meta{XXXX} to |
| 13756 |
indicate a character by its hexadecimal value, but remember that the |
| 13757 |
resource options will be expanded when they are written to the |
| 13758 |
resource file so use \cs{glshex} or \cs{cs.string}\cs{u}. |
| 13759 |
|
| 13760 |
If you want to format the \field{definitionindex} field you must use |
| 13761 |
\csopt{save-definition-index} first. For example, to save this field |
| 13762 |
and then zero-pad it to four digits: |
| 13763 |
\begin{codeenv} |
| 13764 |
\csopt{save-definition-index}, |
| 13765 |
\csopt[definitionindex=\ics{cs.percent}04d]{format-integer-fields} |
| 13766 |
\end{codeenv} |
| 13767 |
This option can't be used for the \field{useindex} field |
| 13768 |
created with \csopt{save-use-index} as that field isn't set until |
| 13769 |
after the field modifications are made. |
| 13770 |
|
| 13771 |
\optsection[\subsubsection]{format-decimal-fields} |
| 13772 |
|
| 13773 |
As \csopt{format-integer-fields} but for decimal values. If a field |
| 13774 |
contains an integer then: |
| 13775 |
\begin{itemize} |
| 13776 |
\item if \csopt{format-integer-fields} has also been used to set a |
| 13777 |
format for the given field, the integer format will take precedence; |
| 13778 |
\item otherwise the integer value will be treated as a decimal |
| 13779 |
number. |
| 13780 |
\end{itemize} |
| 13781 |
If you get an error like: |
| 13782 |
\begin{verbatim} |
| 13783 |
Error: d != java.lang.Double |
| 13784 |
\end{verbatim} |
| 13785 |
then it means you have used an invalid specifier. (The above error |
| 13786 |
results from using \verb|%d| instead of \verb|%f| or \verb|%g|.) |
| 13787 |
|
| 13788 |
\optsection[\subsubsection]{interpret-fields} |
| 13789 |
|
| 13790 |
This option indicates that the listed fields should be replaced by |
| 13791 |
their interpreted values. The value is required for this key but |
| 13792 |
may be empty, which indicates an empty set of fields (that is, the |
| 13793 |
setting is switched off). Other fields not listed may still be |
| 13794 |
interpreted depending on other settings. As with the \field{sort} |
| 13795 |
field, any special characters are replaced with commands like |
| 13796 |
\ics{glsbackslash} and \ics{bibglsdollarchar}. This option is |
| 13797 |
applied after \csopt{field-case-change} (if set). |
| 13798 |
|
| 13799 |
For example, suppose I have a file \filefmt{entries.bib} that |
| 13800 |
contains definitions like: |
| 13801 |
\begin{codeenv} |
| 13802 |
\atentry{symbol}\marg{pi, |
| 13803 |
\field{name}=\marg{\cs{ensuremath}\marg{\ics{pi}}}, |
| 13804 |
\field{description}=\marg{the ratio of a circle's circumference to its diameter}, |
| 13805 |
} |
| 13806 |
\strut |
| 13807 |
\atentry{symbol}\marg{sigma, |
| 13808 |
\field{name} = \marg{\cs{ensuremath}\marg{\ics{sigma}}}, |
| 13809 |
\field{description} = \marg{standard deviation} |
| 13810 |
} |
| 13811 |
\end{codeenv} |
| 13812 |
Instead of having a list of terms (glossary), suppose I want to have |
| 13813 |
stand-alone definitions, where the term appears in a section heading. |
| 13814 |
I could define a command like this: |
| 13815 |
\begin{codeenv} |
| 13816 |
\cs{newcommand}\marg{\cmd{definition}}[1]\marg{\comment{} |
| 13817 |
\cs{ifglsentryexists}\marg{\idx{param}1}\comment{} |
| 13818 |
\marg{\comment{} |
| 13819 |
\cs{section}\oarg{\cs{glsentryname}\marg{\idx{param}}}\marg{\cs{glsadd}\marg{\idx{param}1}\ics{glsxtrglossentry}\marg{\idx{param}1}}\comment{} |
| 13820 |
\ics{Glossentrydesc}\marg{\idx{param}1}\cs{glspostdescription} |
| 13821 |
}\comment{} |
| 13822 |
\marg{\cs{section}\oarg{Missing `\idx{param}1'}\marg{\cs{glsadd}\marg{\idx{param}1}}}\comment{} |
| 13823 |
} |
| 13824 |
\end{codeenv} |
| 13825 |
which can be used in the document: |
| 13826 |
\begin{codeenv} |
| 13827 |
\ics{tableofcontents} |
| 13828 |
\cmd{definition}\marg{pi} |
| 13829 |
\cmd{definition}\marg{sigma} |
| 13830 |
\end{codeenv} |
| 13831 |
A problem with this definition of my custom command occurs if I add |
| 13832 |
\sty{hyperref} to the document, because this tries to write \cs{pi} |
| 13833 |
and \cs{sigma} to the PDF bookmarks, which doesn't work because |
| 13834 |
those commands can't be automatically converted to characters |
| 13835 |
permitted in a PDF string. This leads to a warning from |
| 13836 |
\sty{hyperref}: |
| 13837 |
\begin{alltt} |
| 13838 |
Token not allowed in a PDF string (Unicode) |
| 13839 |
\end{alltt} |
| 13840 |
Ideally I'd like to be able to convert these symbols to Unicode so |
| 13841 |
that they can appear in the bookmarks. Since \bibgls' interpreter |
| 13842 |
recognises these commands, I can get it to make the conversion |
| 13843 |
instead of trying to implement a method within \TeX: |
| 13844 |
\begin{codeenv} |
| 13845 |
\cs{glsaddstoragekey}\marg{pdfname}\marg{}\marg{\cmd{pdfname}} |
| 13846 |
\gls{GlsXtrLoadResources}\oarg{ |
| 13847 |
\csopt[entries]{src}, |
| 13848 |
\csopt[\field{name}=\fieldfmt{pdfname}]{replicate-fields}, |
| 13849 |
\csopt[fallback]{replicate-missing-field-action}, |
| 13850 |
\csopt[\fieldfmt{pdfname}]{interpret-fields} |
| 13851 |
} |
| 13852 |
\end{codeenv} |
| 13853 |
This first copies the \field{name} field to the custom |
| 13854 |
\fieldfmt{pdfname} and then interprets the copy. This leaves |
| 13855 |
the \field{name} field with the \LaTeX\ code to produce the symbol |
| 13856 |
in the document, but the \fieldfmt{pdfname} field ends up with all markup |
| 13857 |
stripped by the interpreter and the \cs{pi} and \cs{sigma} are |
| 13858 |
converted to the Unicode characters \hex{1D70B} (mathematical italic |
| 13859 |
small pi) and \hex{1D70E} (mathematical italic small sigma). With |
| 13860 |
\XeLaTeX\ or \LuaLaTeX\ these characters can be written to the PDF |
| 13861 |
bookmarks by adjusting the definition of the custom command: |
| 13862 |
\begin{codeenv} |
| 13863 |
\cs{newcommand}\marg{\cmd{definition}}[1]\marg{\comment{} |
| 13864 |
\cs{ifglsentryexists}\marg{\idx{param}1}\comment{} |
| 13865 |
\marg{\comment{} |
| 13866 |
\cs{section} |
| 13867 |
\oarg{\ics{texorpdfstring}\marg{\cs{glsentryname}\marg{\idx{param}1}}\marg{\cmd{pdfname}\marg{\idx{param}1}}} |
| 13868 |
\marg{\cs{glsadd}\marg{\idx{param}1}\cs{glsxtrglossentry}\marg{\idx{param}1}}\comment{} |
| 13869 |
\cs{Glossentrydesc}\marg{\idx{param}1}\cs{glspostdescription} |
| 13870 |
}\comment{} |
| 13871 |
\marg{\cs{section}\oarg{Missing `\idx{param}1'}\marg{\cs{glsadd}\marg{\idx{param}1}}}% |
| 13872 |
} |
| 13873 |
\end{codeenv} |
| 13874 |
With \pdfLaTeX\ and \sty{fontenc}, you will need |
| 13875 |
\sty{hyperref}'s \styoptfmt{unicode} option: |
| 13876 |
\begin{codeenv} |
| 13877 |
\cs{usepackage}\oarg{\styoptfmt{unicode}}\marg{hyperref} |
| 13878 |
\end{codeenv} |
| 13879 |
If you still encounter problems with the Unicode characters not |
| 13880 |
appearing in the PDF bookmarks, then try the |
| 13881 |
\csopt{hex-unicode-fields} option. For example: |
| 13882 |
\begin{codeenv} |
| 13883 |
\csopt[pdfname]{hex-unicode-fields} |
| 13884 |
\end{codeenv} |
| 13885 |
This still requires \sty{hyperref}'s \styoptfmt{unicode} option. |
| 13886 |
|
| 13887 |
\optsection[\subsubsection]{interpret-fields-action} |
| 13888 |
|
| 13889 |
This option governs the behaviour of \csopt{interpret-fields}. |
| 13890 |
Available values are: |
| 13891 |
\begin{itemize} |
| 13892 |
\item\code{replace}: replace the field content with its interpreted |
| 13893 |
value (default); |
| 13894 |
\item\code{replace non empty}: only replace the field content with |
| 13895 |
its interpreted value if the interpreted value isn't an empty |
| 13896 |
string. |
| 13897 |
\end{itemize} |
| 13898 |
If a field value consists solely of commands that are unknown to the |
| 13899 |
interpreter, then the resulting value will end up empty. In this |
| 13900 |
case, it may be more appropriate to leave the field unchanged. |
| 13901 |
|
| 13902 |
\optsection[\subsubsection]{hex-unicode-fields} |
| 13903 |
|
| 13904 |
This option will convert any Unicode characters (outside of the |
| 13905 |
Basic Latin set) that are found in the listed fields into |
| 13906 |
\code{\gls{bibglshexunicodechar}\margm{hex-code}} where |
| 13907 |
\meta{hex-code} is the hexadecimal character code. |
| 13908 |
|
| 13909 |
The \meta{list} should be a comma-separated list of field names. |
| 13910 |
This action is performed after \csopt{interpret-fields}. |
| 13911 |
|
| 13912 |
If the field contents need to be added to the PDF bookmarks (as in |
| 13913 |
the earlier example) then you need to make sure you use |
| 13914 |
\sty{hyperref}'s \styoptfmt{unicode} option |
| 13915 |
otherwise you'll get the warning: |
| 13916 |
\begin{verbatim} |
| 13917 |
Token not allowed in a PDF string (PDFDocEncoding): |
| 13918 |
removing `\char' |
| 13919 |
\end{verbatim} |
| 13920 |
and the bookmarks will show \idx{doublequotecharhex}\meta{hex-code} |
| 13921 |
instead of the Unicode character. |
| 13922 |
|
| 13923 |
\optsection[\subsubsection]{date-time-fields} |
| 13924 |
|
| 13925 |
This option indicates that the listed fields all contain |
| 13926 |
date and time information. Primary entries will have these fields |
| 13927 |
parsed according to \csopt{date-time-field-format} and |
| 13928 |
\csopt{date-time-field-locale} and dual entries will have these |
| 13929 |
fields parsed according to \csopt{dual-date-time-field-format} and |
| 13930 |
\csopt{dual-date-time-field-locale}. If the field value is missing |
| 13931 |
or doesn't match the given pattern it remains unchanged, otherwise |
| 13932 |
it's converted into the form: |
| 13933 |
\formatdef{bibglsdatetime} |
| 13934 |
where \meta{original} is the value of the field before conversion. |
| 13935 |
If the interpreter is on, the value will be interpreted before |
| 13936 |
being parsed if it contains \idx{escchar}, \idx{mshiftchar}, |
| 13937 |
\idx{bgroupchar}, \idx{egroupchar} or \idx{nbspchar}. (Remember that |
| 13938 |
\idx{nbspchar} is converted to the non-breaking space character |
| 13939 |
\hex{A0} unless \longarg{break-space} is used.) |
| 13940 |
|
| 13941 |
\optsection[\subsubsection]{date-fields} |
| 13942 |
|
| 13943 |
As \csopt{date-time-fields} but for fields that only contain date |
| 13944 |
(not time) information. If parsed correctly, the field is converted |
| 13945 |
to: |
| 13946 |
\formatdef{bibglsdate} |
| 13947 |
The fields are parsed according to |
| 13948 |
\csopt{date-field-format} and |
| 13949 |
\csopt{date-field-locale} for \glspl{primaryentry} and according to |
| 13950 |
\csopt{dual-date-field-format} and |
| 13951 |
\csopt{dual-date-field-locale} for \glspl{dualentry}. |
| 13952 |
|
| 13953 |
\optsection[\subsubsection]{time-fields} |
| 13954 |
|
| 13955 |
As \csopt{date-time-fields} but for fields that only contain time |
| 13956 |
(not date) information. If parsed correctly, the field is converted |
| 13957 |
to: |
| 13958 |
\formatdef{bibglstime} |
| 13959 |
The fields are parsed according to |
| 13960 |
\csopt{time-field-format} and |
| 13961 |
\csopt{time-field-locale} for \glspl{primaryentry} and according to |
| 13962 |
\csopt{dual-time-field-format} and |
| 13963 |
\csopt{dual-time-field-locale} for \glspl{dualentry}. |
| 13964 |
|
| 13965 |
\optsection[\subsubsection]{date-time-field-format} |
| 13966 |
|
| 13967 |
This option also sets |
| 13968 |
\csopt[\meta{value}]{dual-date-time-field-format}. |
| 13969 |
The value is the format pattern used when parsing fields identified |
| 13970 |
by \csopt{date-time-fields}. The \meta{value} is as for |
| 13971 |
\csopt{date-sort-format}. |
| 13972 |
|
| 13973 |
\optsection[\subsubsection]{date-field-format} |
| 13974 |
|
| 13975 |
This option also sets |
| 13976 |
\csopt[\meta{value}]{dual-date-field-format}. |
| 13977 |
The value is the format pattern used when parsing fields identified |
| 13978 |
by \csopt{date-fields}. The \meta{value} is as for |
| 13979 |
\csopt{date-sort-format}. |
| 13980 |
|
| 13981 |
\optsection[\subsubsection]{time-field-format} |
| 13982 |
|
| 13983 |
This option also sets |
| 13984 |
\csopt[\meta{value}]{dual-time-field-format}. |
| 13985 |
The value is the format pattern used when parsing fields identified |
| 13986 |
by \csopt{time-fields}. The \meta{value} is as for |
| 13987 |
\csopt{date-sort-format}. |
| 13988 |
|
| 13989 |
\optsection[\subsubsection]{date-time-field-locale} |
| 13990 |
|
| 13991 |
This option also sets |
| 13992 |
\csopt[\meta{value}]{dual-date-time-field-locale}. |
| 13993 |
The value is the locale used when parsing fields identified |
| 13994 |
by \csopt{date-time-fields}. The \meta{value} is as for |
| 13995 |
\csopt{date-sort-locale}. |
| 13996 |
|
| 13997 |
\optsection[\subsubsection]{date-field-locale} |
| 13998 |
|
| 13999 |
This option also sets |
| 14000 |
\csopt[\meta{value}]{dual-date-field-locale}. |
| 14001 |
The value is the locale used when parsing fields identified |
| 14002 |
by \csopt{date-fields}. The \meta{value} is as for |
| 14003 |
\csopt{date-sort-locale}. |
| 14004 |
|
| 14005 |
\optsection[\subsubsection]{time-field-locale} |
| 14006 |
|
| 14007 |
This option also sets |
| 14008 |
\csopt[\meta{value}]{dual-time-field-locale}. |
| 14009 |
The value is the locale used when parsing fields identified |
| 14010 |
by \csopt{time-fields}. The \meta{value} is as for |
| 14011 |
\csopt{date-sort-locale}. |
| 14012 |
|
| 14013 |
\subsection{Prefix Fields} |
| 14014 |
\label{sec:prefixfields} |
| 14015 |
|
| 14016 |
If you use the \isty{glossaries-prefix} package, the prefix |
| 14017 |
set of fields become available (\field{prefix}, |
| 14018 |
\field{prefixplural}, \field{prefixfirst} and |
| 14019 |
\field{prefixfirstplural}). The default behaviour of \ics{pgls} is for no |
| 14020 |
separator between the prefix and the text produced with \cs{gls}. |
| 14021 |
This is because there are situations where there shouldn't be a |
| 14022 |
space, although a space is more commonly required. |
| 14023 |
|
| 14024 |
This means that a space needs to be appended to the required prefix |
| 14025 |
fields, but an actual space character can't be used because |
| 14026 |
\sty{xkeyval} trims leading and trailing spaces. The \ics{space} |
| 14027 |
command needs to be used instead, but there are also situations |
| 14028 |
where an non-breakable space should be used (for example, where the |
| 14029 |
prefix is a single character). It's a bit tiresome having to |
| 14030 |
remember to put \ics{space} or \idx{nbspchar} at the end of the |
| 14031 |
field value. |
| 14032 |
|
| 14033 |
The \csopt{append-prefix-field} option allows the automatic insertion of a |
| 14034 |
space, but it may be used without the \sty{glossaries-prefix} |
| 14035 |
package. The fields that contain prefixes are identified by |
| 14036 |
\csopt{prefix-fields}. |
| 14037 |
|
| 14038 |
If you have any dual entries, then \bibgls\ will also recognise the |
| 14039 |
special internal fields \field{dualprefix}, |
| 14040 |
\field{dualprefixplural}, \field{dualprefixfirst} and |
| 14041 |
\field{dualprefixfirstplural}. |
| 14042 |
|
| 14043 |
\optsection[\subsubsection]{prefix-fields} |
| 14044 |
|
| 14045 |
Identifies the fields that are used to store prefixes. The default |
| 14046 |
set is: \field{prefix}, \field{prefixfirst}, \field{prefixplural}, |
| 14047 |
\field{prefixfirstplural}, and their dual counterparts |
| 14048 |
\field{dualprefix}, \field{dualprefixfirst}, \field{dualprefixplural} |
| 14049 |
and \field{dualprefixfirstplural}. |
| 14050 |
|
| 14051 |
\optsection[\subsubsection]{append-prefix-field} |
| 14052 |
|
| 14053 |
Allowed values are: |
| 14054 |
\begin{itemize} |
| 14055 |
\item \optfmt{none}: don't append a space to the prefix fields (default); |
| 14056 |
|
| 14057 |
\item \optfmt{space}: append the command identified by |
| 14058 |
\csopt{append-prefix-field-cs} (\ics{space} by default) to the |
| 14059 |
prefix field unless the field value ends with a character identified |
| 14060 |
by \csopt{append-prefix-field-exceptions} or a command identified by |
| 14061 |
\csopt{append-prefix-field-cs-exceptions}. Note that if the field |
| 14062 |
value ends with anything else (such as an empty group) then these |
| 14063 |
exceptions won't apply. |
| 14064 |
|
| 14065 |
\item \optfmt{space or nbsp}: as above but uses \idx{nbspchar} |
| 14066 |
instead of \ics{space} if the field value matches the pattern given |
| 14067 |
by \csopt{append-prefix-field-nbsp-match}. |
| 14068 |
|
| 14069 |
\end{itemize} |
| 14070 |
|
| 14071 |
\optsection[\subsubsection]{append-prefix-field-cs} |
| 14072 |
|
| 14073 |
Identifies the command \meta{cs} that should be used to append to |
| 14074 |
the prefix fields. The default value is \ics{space}. Remember to use |
| 14075 |
\cs{cs.string} or \cs{protect} to prevent the command from being |
| 14076 |
expanded as it's written to the \ext{aux} file. |
| 14077 |
|
| 14078 |
\optsection[\subsubsection]{append-prefix-field-exceptions} |
| 14079 |
|
| 14080 |
This setting identifies the set of characters that, if found at the |
| 14081 |
end of a prefix field, prevent \csopt{append-prefix-field} from |
| 14082 |
appending a space (either \ics{space} or \idx{nbspchar}). |
| 14083 |
|
| 14084 |
The value should be a sequence of characters. You may use |
| 14085 |
\stringu\meta{hex} to identify a character by its hexadecimal code. |
| 14086 |
Spaces are ignored, so \csopt[ ' - ]{append-prefix-field-exceptions} |
| 14087 |
is equivalent to \csopt['-]{append-prefix-field-exceptions}. |
| 14088 |
|
| 14089 |
The default set is the straight apostrophe character (\hex{0027}), |
| 14090 |
the hyphen-minus character (\hex{002D}), the tilde character |
| 14091 |
(\idx{nbspchar}), the hyphen character (\hex{2010}), the |
| 14092 |
non-breaking hyphen (\hex{2011}), and the right single quotation |
| 14093 |
mark (\hex{2019}). |
| 14094 |
|
| 14095 |
\optsection[\subsubsection]{append-prefix-field-cs-exceptions} |
| 14096 |
|
| 14097 |
This setting identifies the set of commands that, if found at the |
| 14098 |
end of a prefix field, prevent \csopt{append-prefix-field} from |
| 14099 |
appending a space (either \ics{space} or \idx{nbspchar}). Any spaces |
| 14100 |
found in \meta{sequence} are ignored. The default setting is the |
| 14101 |
set: \cs{space}, \ics{nobreakspace} and \cs{cs.space}. |
| 14102 |
|
| 14103 |
Remember that you will need to use \cs{cs.string} or \cs{protect} to |
| 14104 |
prevent the command from being expanded while the resource options |
| 14105 |
are written to the \ext{aux} file. |
| 14106 |
|
| 14107 |
\optsection[\subsubsection]{append-prefix-field-nbsp-match} |
| 14108 |
|
| 14109 |
The value is the \gls{regular-expression} that identifies prefixes that should be |
| 14110 |
followed by \idx{nbspchar} instead of \ics{space}. The default |
| 14111 |
is \csopt[\idx{matchanydot}]{append-prefix-field-nbsp-match} which indicates a |
| 14112 |
single character. |
| 14113 |
|
| 14114 |
\subsection{Case-Changing} |
| 14115 |
\label{sec:fieldcase} |
| 14116 |
|
| 14117 |
The \sty{glossaries-extra} package comes with the category |
| 14118 |
attributes \catattr{glossdesc} and \catattr{glossname}, which may |
| 14119 |
take the values \optfmt{firstuc} or \optfmt{title}. These don't |
| 14120 |
change the actual \field{name} or \field{description} fields, but |
| 14121 |
instead \ics{glossentryname} and \ics{glossentrydesc} (which are |
| 14122 |
used by the default glossary styles) check for the corresponding |
| 14123 |
attribute and apply the appropriate \idx{case-change} to the field value. |
| 14124 |
|
| 14125 |
So \ics{glossentryname} will use \ics{Glsentryname} if the |
| 14126 |
\catattr{glossname} attribute for the given entry is set to \optfmt{firstuc} |
| 14127 |
and \ics{glossentrydesc} will use \ics{Glsentrydesc} if the |
| 14128 |
\catattr{glossdesc} attribute is set to \optfmt{firstuc}. |
| 14129 |
The \optfmt{title} setting will instead use \ics{capitalisewords} |
| 14130 |
applied to the field value. |
| 14131 |
|
| 14132 |
The resource options described in this section provide an |
| 14133 |
alternative to those attributes that actually modify the relevant |
| 14134 |
field (rather than just adjusting the style code used to display it). |
| 14135 |
There are two forms of modification: the field is adjusted so that |
| 14136 |
the original value is encapsulated by a command or \bibgls\ will |
| 14137 |
perform the actual \idx{case-change} according to its own algorithm. |
| 14138 |
The results can vary according to the field content. |
| 14139 |
|
| 14140 |
Where \bibgls\ itself performs the case change, its case-changing |
| 14141 |
functions will use the \gls{resource-locale}, but whether or not |
| 14142 |
\bibgls\ recognises the correct rules for the locale depends on |
| 14143 |
whether or not the locale is correctly supported by the Java locale |
| 14144 |
provider. The \langxml\ may provide assistance with case-conversion. |
| 14145 |
|
| 14146 |
\begin{important} |
| 14147 |
Note the difference between \ics{NoCaseChange} (which prevents case-changing |
| 14148 |
for both \bibgls\ and in the \LaTeX\ document) and \ics{BibGlsNoCaseChange} |
| 14149 |
(which only prevents case-changing in \bibgls). The options that defer |
| 14150 |
the case-change action to \LaTeX, such as \optfmt{uc-cs}, will treat |
| 14151 |
\ics{NoCaseChange} as an exclusion but not \ics{BibGlsNoCaseChange}. |
| 14152 |
\end{important} |
| 14153 |
|
| 14154 |
Each of the case-changing resource options may take one of the |
| 14155 |
following values: |
| 14156 |
\begin{itemize} |
| 14157 |
\item \optfmt{none}: don't apply any case-changing (default); |
| 14158 |
|
| 14159 |
\item \optfmt{lc-cs}: make \bibgls\ behave as though the field |
| 14160 |
assignment: |
| 14161 |
\begin{codeenv} |
| 14162 |
\meta{field} = \margm{text} |
| 14163 |
\end{codeenv} |
| 14164 |
had actually been specified as: |
| 14165 |
\begin{codeenv*} |
| 14166 |
\meta{field} = \marg{\gls{bibglslowercase}\margm{text}} |
| 14167 |
\end{codeenv*} |
| 14168 |
which uses \TeX\ to convert the field to \idx{lowercase}; |
| 14169 |
|
| 14170 |
\item \optfmt{uc-cs}: make \bibgls\ behave as though the field |
| 14171 |
assignment: |
| 14172 |
\begin{codeenv} |
| 14173 |
\meta{field} = \margm{text} |
| 14174 |
\end{codeenv} |
| 14175 |
had actually been specified as: |
| 14176 |
\begin{codeenv*} |
| 14177 |
\meta{field} = \marg{\gls{bibglsuppercase}\margm{text}} |
| 14178 |
\end{codeenv*} |
| 14179 |
which uses \TeX\ to convert the field to \idx{uppercase}; |
| 14180 |
|
| 14181 |
\item \optfmt{firstuc-cs}: make \bibgls\ behave as though the field |
| 14182 |
assignment: |
| 14183 |
\begin{codeenv} |
| 14184 |
\meta{field} = \margm{text} |
| 14185 |
\end{codeenv} |
| 14186 |
had actually been specified as: |
| 14187 |
\begin{codeenv*} |
| 14188 |
\meta{field} = \marg{\gls{bibglsfirstuc}\margm{text}} |
| 14189 |
\end{codeenv*} |
| 14190 |
which uses \TeX\ to convert the field to first-letter \idx{uppercase}; |
| 14191 |
|
| 14192 |
\item \optfmt{title-cs}: make \bibgls\ behave as though the field |
| 14193 |
assignment: |
| 14194 |
\begin{codeenv} |
| 14195 |
\meta{field} = \margm{text} |
| 14196 |
\end{codeenv} |
| 14197 |
had actually been specified as: |
| 14198 |
\begin{codeenv*} |
| 14199 |
\meta{field} = \marg{\gls{bibglstitlecase}\margm{text}} |
| 14200 |
\end{codeenv*} |
| 14201 |
which uses \TeX\ to convert the field to \idx{titlecase}; |
| 14202 |
|
| 14203 |
\item \optfmt{lc}: convert to \idx{lowercase} by making the |
| 14204 |
appropriate modifications to tokens in the field value that have |
| 14205 |
a known \idx{lowercase} alternative (see below); |
| 14206 |
|
| 14207 |
\item \optfmt{uc}: convert to \idx{uppercase} by making the |
| 14208 |
appropriate modifications to tokens in the field value that have |
| 14209 |
a known \idx{uppercase} alternative (see below); |
| 14210 |
|
| 14211 |
\item \optfmt{firstuc}: convert to first letter \idx{uppercase} |
| 14212 |
by making the appropriate modification, if it has |
| 14213 |
a known \idx{uppercase} alternative (see below); |
| 14214 |
|
| 14215 |
\item \optfmt{title}: convert to \idx{titlecase} by making the |
| 14216 |
appropriate modifications to the first letter of each identified |
| 14217 |
word in the field value that has a known \idx{uppercase} |
| 14218 |
alternative (see below). |
| 14219 |
|
| 14220 |
A word-boundary is identified according to the |
| 14221 |
\csopt{word-boundaries} setting. Words to be excluded from the |
| 14222 |
case-changing (unless they occur at the start) can be identified |
| 14223 |
with \ics{MFUnocap} in the \atentry{preamble} or you can use |
| 14224 |
\code{\longarg{packages} mfirstuc-english} for the exclusion list |
| 14225 |
provided by the \isty{mfirstuc-english} package. Alternatively, you |
| 14226 |
can use \longarg{custom-packages} to load a simple package that |
| 14227 |
contains the required \cs{MFUnocap} commands (in a similar style to |
| 14228 |
\sty{mfirstuc-english}). |
| 14229 |
|
| 14230 |
The \bibgls\ word-boundary implementation is slightly different with |
| 14231 |
this setting than with the \cs{capitalisewords} command (implemented |
| 14232 |
in \TeX\ or by the \texparserlib\ when interpreting field |
| 14233 |
values). Only words in the exclusion list that start with an |
| 14234 |
alphabetical character can be matched. Punctuation following a |
| 14235 |
word-boundary is not considered part of the next word. |
| 14236 |
If you want to identify that a particular character forms a word |
| 14237 |
break, you can use \code{\ics{MFUwordbreak}\margm{char}}. For |
| 14238 |
example: |
| 14239 |
\begin{codeenv} |
| 14240 |
\field{name}=\marg{some word\cs{MFUwordbreak}\marg{/}phrase} |
| 14241 |
\end{codeenv} |
| 14242 |
|
| 14243 |
\end{itemize} |
| 14244 |
|
| 14245 |
If you need to selectively change the case, based on some condition |
| 14246 |
(such as the \gls{entrytype}) then you can use the |
| 14247 |
\csopt{assign-fields} option instead, but remember that you will |
| 14248 |
need the override setting on. For example: |
| 14249 |
\begin{codeenv} |
| 14250 |
\csopt[ |
| 14251 |
\field{name} =\oarg{o} \gls{TITLE}\marg{ \field{name} } |
| 14252 |
\oarg{ entrytype \idx{follow} original = \qtdelim{entry} } |
| 14253 |
]{assign-fields} |
| 14254 |
\end{codeenv} |
| 14255 |
This will convert the \field{name} field to \idx{titlecase} for |
| 14256 |
entries that were defined in the \ext{bib} file with |
| 14257 |
\atentry{entry}. Note that if you also use a case-changing option, |
| 14258 |
for example, \csopt{name-case-change}, then all entries will have |
| 14259 |
the change applied, according to the option's designated behaviour, |
| 14260 |
regardless of whether or not the applicable field has already been |
| 14261 |
altered by \csopt{assign-fields}. |
| 14262 |
|
| 14263 |
\begin{important} |
| 14264 |
Major changes have been introduced to \sty{mfirstuc} v2.08. Some of |
| 14265 |
the information below refers to older versions and is not |
| 14266 |
applicable with \sty{mfirstuc} v2.08+. See the \sty{mfirstuc} manual |
| 14267 |
for further details. |
| 14268 |
\end{important} |
| 14269 |
|
| 14270 |
The \optfmt{firstuc-cs} and \optfmt{firstuc} options are essentially |
| 14271 |
a \idx{sentencecase} change, but there's no check for |
| 14272 |
sentence-breaks within the value, so even if the value contains |
| 14273 |
multiple sentences, only the first is changed. If the text to be |
| 14274 |
changed starts with a punctuation character it should be |
| 14275 |
encapsulated with \ics{MFUskippunc} to apply the case-change to the |
| 14276 |
following object. For example: |
| 14277 |
\begin{codeenv} |
| 14278 |
\field{name}=\marg{\cs{MFUskippunc}\marg{'}tis} |
| 14279 |
\end{codeenv} |
| 14280 |
If the \optfmt{firstuc} option is applied to the \field{name} field |
| 14281 |
this will be converted to: |
| 14282 |
\begin{codeenv} |
| 14283 |
\field{name}=\marg{\cs{MFUskippunc}\marg{'}Tis} |
| 14284 |
\end{codeenv} |
| 14285 |
Using \ics{NoCaseChange} (provided by \sty{textcase}) instead will have the |
| 14286 |
same effect, but this isn't consistent with the behaviour of |
| 14287 |
\ics{makefirstuc} so it's best to use \cs{MFUskippunc} instead. |
| 14288 |
|
| 14289 |
The \optfmt{\meta{option}-cs} settings defer the actual case-changing |
| 14290 |
to \TeX, which means that the case-changing has to be applied every |
| 14291 |
time the field is typeset (and it introduces non-expandable content |
| 14292 |
to the field value). Be aware of the limitations of using any of the |
| 14293 |
case-changing commands. See the \isty{textcase} and \isty{mfirstuc} |
| 14294 |
package documentation for further details~\cite{textcase,mfirstuc}. |
| 14295 |
|
| 14296 |
For the settings where \bibgls\ itself performs the \idx{case-change}, then |
| 14297 |
\bibgls\ will iterate over each token of the field value and apply |
| 14298 |
the rules listed below. Note that the case-change implemented by |
| 14299 |
\bibgls\ recognises the \gls{resource-locale}, but whether or not it |
| 14300 |
recognises the correct rules for the locale depends on whether or |
| 14301 |
not the locale is correctly supported by the Java locale provider. |
| 14302 |
|
| 14303 |
\begin{enumerate} |
| 14304 |
|
| 14305 |
\item If the token is a normal Unicode alphabetic character, it will |
| 14306 |
be replaced with the corresponding upper or lower case character, as |
| 14307 |
appropriate. In some cases, a single character, such as \ss, is |
| 14308 |
replaced by multiple characters, such as SS. |
| 14309 |
|
| 14310 |
For \optfmt{title} and \optfmt{firstuc}, the \idx{titlecase} character is |
| 14311 |
used as the replacement, for \optfmt{uc} the \idx{uppercase} character is |
| 14312 |
used as the replacement, and for \optfmt{lc} the \idx{lowercase} character |
| 14313 |
is used as the replacement. Many characters have the same upper and |
| 14314 |
title case alternative (for example, \qt{a} will be converted to \qt{A} |
| 14315 |
for the \optfmt{title}, \optfmt{firstuc} and \optfmt{uc} settings), but |
| 14316 |
some characters have different title and upper versions (for example, |
| 14317 |
the digraph \qt{\char"01F3} has the title version \qt{\char"01F2} |
| 14318 |
and \idx{uppercase} version \qt{\char"01F1}). |
| 14319 |
|
| 14320 |
If the option is \optfmt{firstuc} then all the remaining tokens are |
| 14321 |
skipped. If the option is \optfmt{title} then the subsequent tokens |
| 14322 |
are skipped until a word-boundary is found. |
| 14323 |
|
| 14324 |
\item If the token is a normal Unicode character that isn't alphabetical, |
| 14325 |
then this token will be skipped for all options. |
| 14326 |
|
| 14327 |
\item If \code{\idx{mshiftchar}\meta{maths}\idx{mshiftchar}} is |
| 14328 |
encountered, it will be skipped. If the option is \optfmt{firstuc} |
| 14329 |
then all remaining tokens are skipped, so no \idx{case-change} will be |
| 14330 |
performed. |
| 14331 |
|
| 14332 |
\item\label{case-change-group} If a group \code{\margm{content}} is |
| 14333 |
found, then the \idx{case-change} is applied to the entire \meta{content} |
| 14334 |
(which may be empty). This corresponds to the way \ics{makefirstuc} |
| 14335 |
and \ics{capitalisewords} work if a~word starts with a group. Note |
| 14336 |
that with \optfmt{firstuc} and \optfmt{title} the group content will |
| 14337 |
be converted according to \optfmt{uc}, so the normal \idx{uppercase} |
| 14338 |
character is used rather than the title case character (if they are |
| 14339 |
different). |
| 14340 |
|
| 14341 |
If the option is \optfmt{firstuc} then all the remaining tokens are |
| 14342 |
skipped. If the option is \optfmt{title} then the subsequent tokens |
| 14343 |
are skipped until a word-boundary is found. A word-boundary can be |
| 14344 |
marked up with \ics{MFUwordbreak}. |
| 14345 |
|
| 14346 |
\item If a control sequence \csfmt{}\meta{csname} is found, then: |
| 14347 |
|
| 14348 |
\begin{enumerate} |
| 14349 |
\item If the control sequence is \cs{protect}, this token is skipped |
| 14350 |
for all options. |
| 14351 |
|
| 14352 |
\item With \optfmt{firstuc} and \optfmt{title}, if |
| 14353 |
\code{\ics{MFUskippunc}\margm{text}} or \code{\ics{NoCaseChange}\margm{text}} |
| 14354 |
occurs at the start of a word, then \bibgls\ will act as though |
| 14355 |
the word hasn't started yet (so the next token will be considered |
| 14356 |
for a \idx{case-change}). |
| 14357 |
|
| 14358 |
\item If the control sequence is one of: \ics{o}, \ics{O}, \ics{l}, |
| 14359 |
\ics{L}, \ics{ae}, \ics{AE}, \ics{oe}, \ics{OE}, \ics{aa}, \ics{AA}, |
| 14360 |
\ics{ss}, \ics{SS}, \ics{ng}, \ics{NG}, \ics{th}, \ics{TH}, |
| 14361 |
\ics{dh}, \ics{DH}, \ics{dj} or \ics{DJ}, then |
| 14362 |
it's replaced with its \idx{case-change} counterpart (if not already the |
| 14363 |
correct case). |
| 14364 |
|
| 14365 |
If the option is \optfmt{firstuc} then all the remaining tokens are |
| 14366 |
skipped. If the option is \optfmt{title} then the subsequent tokens |
| 14367 |
are skipped until a word-boundary is found. |
| 14368 |
|
| 14369 |
\item If the control sequence is in the \csopt{no-case-change-cs} |
| 14370 |
list or is \ics{ensuremath}, \ics{si} or if |
| 14371 |
\meta{csname} ends with \qtt{ref} (for example, \ics{ref} or |
| 14372 |
\ics{pageref}) then the control sequence and its argument is |
| 14373 |
ignored. In the case where \meta{csname} ends with \qtt{ref}, a |
| 14374 |
following star (\code{*}) or optional argument before the mandatory |
| 14375 |
argument will also be skipped. This allows for some common |
| 14376 |
cross-referencing commands, such as \sty{hyperref}['s] |
| 14377 |
\ics{autoref}, which may have a starred form, but does not allow for |
| 14378 |
more complicated commands with multiple arguments. |
| 14379 |
|
| 14380 |
If the option is \optfmt{firstuc} then all the remaining tokens are |
| 14381 |
skipped (so no \idx{case-change} will be performed). If the option is |
| 14382 |
\optfmt{title} then the subsequent tokens |
| 14383 |
are skipped until a word-boundary is found (so no \idx{case-change} is |
| 14384 |
performed for this word). |
| 14385 |
|
| 14386 |
\item If the control sequence is \ics{glsentrytitlecase} then: |
| 14387 |
\begin{description} |
| 14388 |
\item[\optfmt{lc}] the control sequence is converted to |
| 14389 |
\ics{glsxtrusefield}; |
| 14390 |
\item[\optfmt{uc}] the control sequence is converted to |
| 14391 |
\ics{GLSxtrusefield}; |
| 14392 |
\item[\optfmt{firstuc}] the control sequence is converted to |
| 14393 |
\ics{Glsxtrusefield} and the remaining tokens are skipped; |
| 14394 |
\item[\optfmt{title}] the control sequence is left unchanged |
| 14395 |
and subsequent tokens are skipped until a word-boundary is found. |
| 14396 |
\end{description} |
| 14397 |
The field and entry label arguments are skipped. |
| 14398 |
|
| 14399 |
\item If the control sequence is \ics{glshyperlink} then the |
| 14400 |
\idx{case-change} is applied to its optional argument. (If there was no |
| 14401 |
optional argument in the original field value, one will be inserted.) |
| 14402 |
The label argument is skipped. |
| 14403 |
|
| 14404 |
If the option is \optfmt{firstuc} then all the remaining tokens are |
| 14405 |
skipped. If the option is \optfmt{title} then the subsequent tokens |
| 14406 |
are skipped until a word-boundary is found. |
| 14407 |
|
| 14408 |
\item If the control sequence is \ics{glsdisp}, \ics{glslink}, |
| 14409 |
\ics{dglsdisp} or \ics{dglslink} then the \idx{case-change} will be |
| 14410 |
applied to the appropriate argument. The optional argument (if |
| 14411 |
present) and the label are skipped. |
| 14412 |
|
| 14413 |
If the option is \optfmt{firstuc} then all the remaining tokens are |
| 14414 |
skipped. If the option is \optfmt{title} then the subsequent tokens |
| 14415 |
are skipped until a word-boundary is found. |
| 14416 |
|
| 14417 |
\item If the control sequence has a known case variant, it will be |
| 14418 |
substituted. For example, \ics{gls} will be changed to \ics{Gls} |
| 14419 |
or \ics{GLS}. In some cases there isn't an appropriate variant. |
| 14420 |
For example, \ics{glsentrytext} has a first-letter upper case |
| 14421 |
version \ics{Glsentrytext}, but not an all-caps version. |
| 14422 |
|
| 14423 |
If the option is \optfmt{firstuc} then all the remaining tokens are |
| 14424 |
skipped. If the option is \optfmt{title} then the subsequent tokens |
| 14425 |
are skipped until a word-boundary is found. |
| 14426 |
|
| 14427 |
\item If the control sequence is followed by a group, then the |
| 14428 |
appropriate \idx{case-change} is applied to the group contents. |
| 14429 |
Unlike step~\ref{case-change-group}, the \idx{case-change} isn't |
| 14430 |
applied to the entire group content with \optfmt{firstuc} and |
| 14431 |
\optfmt{title}. (Again, this follows the way that |
| 14432 |
\ics{makefirstuc} and \ics{capitalisewords} work.) |
| 14433 |
|
| 14434 |
If there are subsequent groups, they won't be considered arguments, |
| 14435 |
but will be treated as groups, as per step~\ref{case-change-group}. |
| 14436 |
(This will only affect the \optfmt{title} setting as they will be |
| 14437 |
skipped by the \optfmt{firstuc} setting.) For complex cases, |
| 14438 |
consider using a semantic command that hides non-textual context |
| 14439 |
such as the \csfmt{strong} example described on page~\glsxtrpageref{strong}. |
| 14440 |
|
| 14441 |
\item Otherwise the control sequence is skipped. |
| 14442 |
\end{enumerate} |
| 14443 |
|
| 14444 |
\item Anything else is skipped. |
| 14445 |
|
| 14446 |
\end{enumerate} |
| 14447 |
|
| 14448 |
For example, if an entry is defined as: |
| 14449 |
\begin{codeenv} |
| 14450 |
\atentry{abbreviation}\marg{html, |
| 14451 |
\field{short} = \marg{HTML}, |
| 14452 |
\field{long} = \marg{hypertext markup language}, |
| 14453 |
\field{description}=\marg{a markup language for creating web pages} |
| 14454 |
} |
| 14455 |
\end{codeenv} |
| 14456 |
then: |
| 14457 |
\begin{codeenv} |
| 14458 |
\gls{GlsXtrLoadResources}\oarg{ |
| 14459 |
\csopt[lc]{short-case-change}, |
| 14460 |
\csopt[title]{long-case-change}, |
| 14461 |
\csopt[firstuc]{description-case-change} |
| 14462 |
} |
| 14463 |
\end{codeenv} |
| 14464 |
will make the entry behave as if it had been defined as: |
| 14465 |
\begin{codeenv} |
| 14466 |
\atentry{abbreviation}\marg{html, |
| 14467 |
\field{short} = \marg{html}, |
| 14468 |
\field{long} = \marg{Hypertext Markup Language}, |
| 14469 |
\field{description}=\marg{A markup language for creating web pages} |
| 14470 |
} |
| 14471 |
\end{codeenv} |
| 14472 |
whereas: |
| 14473 |
\begin{codeenv} |
| 14474 |
\gls{GlsXtrLoadResources}\oarg{ |
| 14475 |
\csopt[lc-cs]{short-case-change}, |
| 14476 |
\csopt[title-cs]{long-case-change}, |
| 14477 |
\csopt[firstuc-cs]{description-case-change} |
| 14478 |
} |
| 14479 |
\end{codeenv} |
| 14480 |
will make the entry behave as if it had been defined as: |
| 14481 |
\begin{codeenv} |
| 14482 |
\atentry{abbreviation}\marg{html, |
| 14483 |
\field{short} = \marg{\gls{bibglslowercase}\marg{HTML}}, |
| 14484 |
\field{long} = \marg{\gls{bibglstitlecase}\marg{hypertext markup language}}, |
| 14485 |
\field{description}=\marg{\gls{bibglsfirstuc}\marg{a markup language for creating web pages}} |
| 14486 |
} |
| 14487 |
\end{codeenv} |
| 14488 |
If the given field is missing, no change is made, except under |
| 14489 |
certain circumstances (see the relevant resource option for details). |
| 14490 |
For example, if an abbreviation is simply defined as: |
| 14491 |
\begin{codeenv} |
| 14492 |
\atentry{abbreviation}\marg{html, |
| 14493 |
\field{short} = \marg{html}, |
| 14494 |
\field{long} = \marg{hypertext markup language} |
| 14495 |
} |
| 14496 |
\end{codeenv} |
| 14497 |
then: |
| 14498 |
\begin{codeenv} |
| 14499 |
\gls{GlsXtrLoadResources}\oarg{ |
| 14500 |
\csopt[uc]{name-case-change}, |
| 14501 |
\csopt[title]{description-case-change} |
| 14502 |
} |
| 14503 |
\end{codeenv} |
| 14504 |
won't have an effect. Although the default \abbrstyle{long-short} abbreviation |
| 14505 |
style sets the \field{name} and \field{description} fields, \bibgls\ doesn't |
| 14506 |
have access to this information. |
| 14507 |
|
| 14508 |
Remember that you can create missing fields by copying the value |
| 14509 |
from another field. So if the resource options are changed to: |
| 14510 |
\begin{codeenv} |
| 14511 |
\gls{GlsXtrLoadResources}\oarg{ |
| 14512 |
\csopt[uc]{name-case-change}, |
| 14513 |
\csopt[title]{description-case-change}, |
| 14514 |
\csopt[\field{short}=\field{name},\field{long}=\field{description}]{replicate-fields} |
| 14515 |
} |
| 14516 |
\end{codeenv} |
| 14517 |
then \bibgls\ will act as though the entry had been defined as: |
| 14518 |
\begin{codeenv} |
| 14519 |
\atentry{abbreviation}\marg{html, |
| 14520 |
\field{short} = \marg{html}, |
| 14521 |
\field{long} = \marg{hypertext markup language}, |
| 14522 |
\field{name} = \marg{HTML}, |
| 14523 |
\field{description} = \marg{Hypertext Markup Language} |
| 14524 |
} |
| 14525 |
\end{codeenv} |
| 14526 |
If the \abbrstyle{long-short-sc} abbreviation style is set (before |
| 14527 |
\gls{GlsXtrLoadResources}) then this will override the default style |
| 14528 |
for the \field{name} and \field{description}, so |
| 14529 |
\code{\cs{gls}\marg{html}} will display the short form using |
| 14530 |
\code{\ics{textsc}\marg{html}} but the \field{name} in the glossary |
| 14531 |
will be displayed using just \code{HTML}. |
| 14532 |
|
| 14533 |
Note that with \atentry{index} the \field{name} and \field{text} |
| 14534 |
fields will automatically be created if they are missing and |
| 14535 |
\csopt{name-case-change} is used. For example, if an entry is |
| 14536 |
defined as: |
| 14537 |
\begin{codeenv} |
| 14538 |
\atentry{index}\marg{duck} |
| 14539 |
\end{codeenv} |
| 14540 |
then \csopt[firstuc]{name-case-change} will make this entry behave |
| 14541 |
as though it was defined as: |
| 14542 |
\begin{codeenv} |
| 14543 |
\atentry{index}\marg{duck, |
| 14544 |
\field{name} = \marg{Duck}, |
| 14545 |
\field{text} = \marg{duck} |
| 14546 |
} |
| 14547 |
\end{codeenv} |
| 14548 |
|
| 14549 |
Suppose I have a slightly eccentric abbreviation definition: |
| 14550 |
\begin{codeenv} |
| 14551 |
\atentry{abbreviation}\marg{html, |
| 14552 |
\field{short} = \qtdelim{ht\cs{emph}\marg{ml}}, |
| 14553 |
\field{long} = \qtdelim{hypertext markup language} |
| 14554 |
} |
| 14555 |
\end{codeenv} |
| 14556 |
then \csopt[uc]{short-case-change} would convert the value of the |
| 14557 |
\field{short} field into: |
| 14558 |
\begin{codeenv} |
| 14559 |
HT\cs{emph}{ML} |
| 14560 |
\end{codeenv} |
| 14561 |
Note that \csfmt{emph} isn't modified as it's recognised as a |
| 14562 |
command. There's a difference between a group that follows a control |
| 14563 |
sequence and one that doesn't. For example: |
| 14564 |
\begin{codeenv} |
| 14565 |
\atentry{abbreviation}\marg{html, |
| 14566 |
\field{short} = \qtdelim{\marg{ht}ml}, |
| 14567 |
\field{long} = \qtdelim{hypertext markup language} |
| 14568 |
} |
| 14569 |
\end{codeenv} |
| 14570 |
In this case \csopt[firstuc]{short-case-change} will convert the |
| 14571 |
\field{short} field value to: |
| 14572 |
\begin{codeenv} |
| 14573 |
\marg{HT}ml |
| 14574 |
\end{codeenv} |
| 14575 |
(The entire contents of the group \code{\marg{ht}} has been |
| 14576 |
converted.) Whereas with: |
| 14577 |
\begin{codeenv} |
| 14578 |
\atentry{abbreviation}\marg{html, |
| 14579 |
\field{short} = \qtdelim{\cs{emph}\marg{ht}ml}, |
| 14580 |
\field{long} = \qtdelim{hypertext markup language} |
| 14581 |
} |
| 14582 |
\end{codeenv} |
| 14583 |
then \csopt[firstuc]{short-case-change} will convert the |
| 14584 |
\field{short} field value to: |
| 14585 |
\begin{codeenv} |
| 14586 |
\cs{emph}\marg{Ht}ml |
| 14587 |
\end{codeenv} |
| 14588 |
(Only the first letter of the argument \code{\marg{ht}} has been |
| 14589 |
converted.) |
| 14590 |
|
| 14591 |
There's no attempt at interpreting the field contents at this point (but |
| 14592 |
the value may later be interpreted during sorting). |
| 14593 |
For example, suppose a \field{name} field is defined using: |
| 14594 |
\begin{codeenv} |
| 14595 |
\field{name} = \qtdelim{z\ics{ae}\ics{oe}}, |
| 14596 |
\end{codeenv} |
| 14597 |
then with \csopt[uc]{name-case-change}, the value would be converted to |
| 14598 |
\begin{codeenv} |
| 14599 |
Z\ics{AE}\ics{OE} |
| 14600 |
\end{codeenv} |
| 14601 |
because \cs{ae} and \cs{oe} have known \idx{uppercase} versions. |
| 14602 |
|
| 14603 |
With \csopt[uc-cs]{name-case-change}, the \field{name} |
| 14604 |
value would be converted to: |
| 14605 |
\begin{codeenv} |
| 14606 |
\gls{bibglsuppercase}\marg{z\cs{ae}\cs{oe}} |
| 14607 |
\end{codeenv} |
| 14608 |
If the interpreter is used during sorting, the sort value will be set to |
| 14609 |
\code{Z\AE\OE} because the interpreter recognises all three commands. |
| 14610 |
|
| 14611 |
You can use \code{\ics{NoCaseChange}\margm{text}} to prevent the given |
| 14612 |
\meta{text} from having the case changed. For example, if the \field{short} |
| 14613 |
field is defined as: |
| 14614 |
\begin{codeenv} |
| 14615 |
\field{short} = \marg{a\cs{NoCaseChange}\marg{bc}d} |
| 14616 |
\end{codeenv} |
| 14617 |
then with \csopt[uc]{short-case-change}, this would be converted to |
| 14618 |
\begin{codeenv} |
| 14619 |
A\cs{NoCaseChange}\marg{bc}D |
| 14620 |
\end{codeenv} |
| 14621 |
|
| 14622 |
Note that with \optfmt{firstuc} and \optfmt{title}, if |
| 14623 |
\code{\ics{MFUskippunc}\margm{text}} occurs at the start of a word |
| 14624 |
then it's skipped, and the case change is |
| 14625 |
applied to the material following its argument. For example, |
| 14626 |
suppose the \field{short} field is defined as: |
| 14627 |
\begin{codeenv} |
| 14628 |
\field{short}=\marg{\cs{MFUskippunc}\marg{h}tml} |
| 14629 |
\end{codeenv} |
| 14630 |
then the result is: |
| 14631 |
\begin{codeenv} |
| 14632 |
\cs{MFUskippunc}\marg{h}Tml |
| 14633 |
\end{codeenv} |
| 14634 |
whereas with: |
| 14635 |
\begin{codeenv} |
| 14636 |
\field{short}=\marg{\marg{}html} |
| 14637 |
\end{codeenv} |
| 14638 |
then the result is just \code{\marg{}html} (since the case change is |
| 14639 |
applied to the empty group, which has no effect). |
| 14640 |
|
| 14641 |
If you have a command that takes a label or identifier as an argument then it's |
| 14642 |
best to hide the label in a custom command. For example, if the |
| 14643 |
\field{short} field in the \ext{bib} definition is defined as: |
| 14644 |
\begin{codeenv} |
| 14645 |
\field{short} = \qtdelim{ht\ics{textcolor}\marg{red}\marg{ml}}, |
| 14646 |
\end{codeenv} |
| 14647 |
then with \csopt[uc]{short-case-change} this would end up as: |
| 14648 |
\begin{codeenv} |
| 14649 |
HT\cs{textcolor}\marg{RED}\marg{ML} |
| 14650 |
\end{codeenv} |
| 14651 |
which is incorrect. Instead, provide a command that hides the label |
| 14652 |
(such as the \csfmt{strong} example described on page~\glsxtrpageref{strong}). |
| 14653 |
|
| 14654 |
\optsection[\subsubsection]{no-case-change-cs} |
| 14655 |
|
| 14656 |
Instructs the non-\TeX\ case-changing options (where \bibgls, not |
| 14657 |
\TeX, performs the modification) to treat the commands whose control |
| 14658 |
sequence names are given in the comma-separated \meta{list} in the |
| 14659 |
same way as it treats \cs{ensuremath} etc. That is, the case-change |
| 14660 |
is omitted for the argument that follows any of those commands. |
| 14661 |
|
| 14662 |
For example, this manual defines some semantic commands such as |
| 14663 |
\csfmt{fieldfmt} (to format field names), \csfmt{abbrstylefmt} |
| 14664 |
(to format abbreviation style names) and \csfmt{glostylefmt} (to format |
| 14665 |
glossary style names). If any these occur in section |
| 14666 |
and subsection headings (which are converted to \idx{titlecase}) |
| 14667 |
then the case-change would produce an inappropriate result. |
| 14668 |
These formatting commands shouldn't have their argument changed so they |
| 14669 |
are identified with: |
| 14670 |
\begin{codeenv} |
| 14671 |
\csopt[fieldfmt,abbrstylefmt,glostylefmt]{no-case-change-cs} |
| 14672 |
\end{codeenv} |
| 14673 |
|
| 14674 |
\optsection[\subsubsection]{word-boundaries} |
| 14675 |
|
| 14676 |
Governs how the \optfmt{title} \idx{case-change} option |
| 14677 |
determines word boundaries. The \meta{list} must contain one or |
| 14678 |
more of the following keywords: |
| 14679 |
\begin{description} |
| 14680 |
\item[\optfmt{white space}] any white space Unicode character |
| 14681 |
that is not a non-breakable space indicates a word-boundary; |
| 14682 |
\item[\optfmt{cs space}] the control sequences |
| 14683 |
\ics{space} or \ics{cs.space} indicate a word-boundary; |
| 14684 |
\item[\optfmt{dash}] a Unicode character that belongs to the |
| 14685 |
\idx{punctuationdash} block indicates a word-boundary; |
| 14686 |
\item[\optfmt{nbsp}] the \idx{nbspchar} active character or the Unicode |
| 14687 |
non-breakable characters \hex{00A0}, \hex{2007} and \hex{202F} |
| 14688 |
indicate a word-boundary. |
| 14689 |
\end{description} |
| 14690 |
Any keyword that is not listed indicates that particular setting is off. This |
| 14691 |
option is not cumulative. Any subsequent use of |
| 14692 |
\csopt{word-boundaries} within the same set of resource options will |
| 14693 |
override previous settings. |
| 14694 |
|
| 14695 |
The default setting is \csopt[white space,cs |
| 14696 |
space]{word-boundaries}, which excludes non-breakable |
| 14697 |
spaces and dashes. |
| 14698 |
|
| 14699 |
Note that you can explicitly markup word-boundary punctuation using |
| 14700 |
\ics{MFUwordbreak}. For example: |
| 14701 |
\begin{codeenv*} |
| 14702 |
\field{name} = \marg{a book of rhyme\cs{MFUwordbreak}\marg{/}verse} |
| 14703 |
\end{codeenv*} |
| 14704 |
|
| 14705 |
\optsection[\subsubsection]{short-case-change} |
| 14706 |
|
| 14707 |
Applies a case-change to the \field{short} field (if present). |
| 14708 |
This option may take one of the values described above. |
| 14709 |
|
| 14710 |
See \csopt{dual-short-case-change} to adjust the \field{dualshort} |
| 14711 |
field. |
| 14712 |
|
| 14713 |
\optsection[\subsubsection]{long-case-change} |
| 14714 |
|
| 14715 |
Applies a case-change to the \field{long} field (if present). |
| 14716 |
This option may take one of the values described above. |
| 14717 |
|
| 14718 |
See \csopt{dual-long-case-change} to adjust the \field{duallong} |
| 14719 |
field. |
| 14720 |
|
| 14721 |
\optsection[\subsubsection]{name-case-change} |
| 14722 |
|
| 14723 |
Applies a case-change to the \field{name} field. |
| 14724 |
This option may take one of the values described above. |
| 14725 |
|
| 14726 |
If the \field{text} field hasn't been set, the \field{name} value is |
| 14727 |
first copied to the \field{text} field. If the \field{name} field |
| 14728 |
hasn't been set (for example, with the \atentry{index} |
| 14729 |
\gls{entrytype}), it's copied from the fallback value (which depends |
| 14730 |
on the \gls{entrytype}, see \sectionref{sec:fallbacks}) unless the |
| 14731 |
\gls{entrytype} is \atentry{abbreviation} or \atentry{acronym}, in |
| 14732 |
which case if the \field{name} field is missing no action is |
| 14733 |
performed. |
| 14734 |
|
| 14735 |
\optsection[\subsubsection]{description-case-change} |
| 14736 |
|
| 14737 |
Applies a case-change to the \field{description} field (if present). |
| 14738 |
This option may take one of the values described above. |
| 14739 |
|
| 14740 |
\optsection[\subsubsection]{field-case-change} |
| 14741 |
|
| 14742 |
A general case-change instruction. The value should be a |
| 14743 |
comma-separated list of \code{\meta{field}\dequals\meta{setting}} for each |
| 14744 |
field that needs a case-change applied. The value is required for this key but |
| 14745 |
may be empty, which indicates this option is switched off. |
| 14746 |
|
| 14747 |
The \meta{setting} should be |
| 14748 |
the same as the permitted values for the above options. This |
| 14749 |
option is applied after all fields have been parsed but before |
| 14750 |
\csopt{interpret-fields}. If the |
| 14751 |
specified field is missing, the fallback for that field (if known, |
| 14752 |
see \sectionref{sec:fallbacks}) is copied |
| 14753 |
into the field. For example: |
| 14754 |
\begin{codeenv} |
| 14755 |
\csopt[\field{user1}=uc,\field{user2}={firstuc}]{field-case-change} |
| 14756 |
\end{codeenv} |
| 14757 |
This manual provides a custom storage key called |
| 14758 |
\fieldfmt{nametitle}: |
| 14759 |
\begin{codeenv} |
| 14760 |
\cs{glsxtrprovidestoragekey}\marg{\fieldfmt{nametitle}}\marg{}\marg{} |
| 14761 |
\end{codeenv} |
| 14762 |
The resource options copy the \field{name} value to this custom |
| 14763 |
field and convert \fieldfmt{nametitle} to \idx{titlecase}: |
| 14764 |
\begin{codeenv} |
| 14765 |
\csopt[\field{name}=\fieldfmt{nametitle}]{replicate-fields}, |
| 14766 |
\csopt[\fieldfmt{nametitle}=title]{field-case-change}, |
| 14767 |
\end{codeenv} |
| 14768 |
This means that it's possible to fetch the value of |
| 14769 |
\fieldfmt{nametitle} instead of \field{name}, which provides an |
| 14770 |
expandable \idx{titlecase} form that's suitable for the PDF |
| 14771 |
bookmarks. (Note that \LaTeX3 now provides some expandable |
| 14772 |
case-changing commands.) |
| 14773 |
|
| 14774 |
This option isn't cumulative. If used multiple times in the same |
| 14775 |
\igls{resourceset}, the last instance will be the one used. If |
| 14776 |
the \keyvallist\ is missing, no general case-changing is applied |
| 14777 |
(the default). |
| 14778 |
|
| 14779 |
\section{Field Fallbacks} |
| 14780 |
\label{sec:fallbacks} |
| 14781 |
|
| 14782 |
The options in this section don't modify any field values but |
| 14783 |
provide instructions on what to do if \bibgls\ wants to know the |
| 14784 |
value of a field where the field hasn't been explicitly set. The most common |
| 14785 |
case is querying the \field{sort} field value with the default |
| 14786 |
\csopt[\field{sort}]{sort-field} setting. Being able to vary the |
| 14787 |
fallback used according to the \gls{entrytype} allows a more flexible |
| 14788 |
approach than explicitly setting the \field{sort} field in the |
| 14789 |
\ext{bib} file. |
| 14790 |
|
| 14791 |
Note that if you specify a different field to use for the sort value |
| 14792 |
with \csopt{sort-field} then the fallback for that field will be used |
| 14793 |
if that field is missing. The \field{sort} fallbacks will be |
| 14794 |
irrelevant if the \field{sort} field isn't being queried. If the |
| 14795 |
fallback system fails to provide a value for the field identified by |
| 14796 |
\csopt{sort-field} then \bibgls\ will follow the rule given by the |
| 14797 |
\csopt{missing-sort-fallback} setting. |
| 14798 |
|
| 14799 |
If you require a complex sort value that can't be implemented by the |
| 14800 |
fallback system, you can use \csopt{assign-fields} to explicitly set |
| 14801 |
the \field{sort} field to a string expression |
| 14802 |
(\sectionref{sec:optstringconcat}). Bear in mind that if the |
| 14803 |
\field{sort} field is actually set to a value, either in the |
| 14804 |
\ext{bib} file or through resource options, then \emph{the |
| 14805 |
\field{sort} fallback won't be used} and the sort fallback options |
| 14806 |
describe in this section won't have any effect. |
| 14807 |
|
| 14808 |
There are other fields that \bibgls\ may want to query that won't |
| 14809 |
necessarily be set in the \ext{bib} file but may be inferred from |
| 14810 |
another field. For example, if the \field{sort} field fallback |
| 14811 |
references the \field{name} field then the \field{name} field will |
| 14812 |
also need a fallback if it hasn't been set. |
| 14813 |
|
| 14814 |
Another possibility is that the interpreter encounters content that |
| 14815 |
includes commands such as \ics{gls}. Since the interpreter can't |
| 14816 |
tell at what point in the document the first use flag is changed, |
| 14817 |
\ics{gls} is treated as \ics{glstext} (and similarly \ics{glspl} is |
| 14818 |
treated as \ics{glsplural}) so the \field{text} (or \field{plural}) |
| 14819 |
field will be queried by the interpreter. |
| 14820 |
|
| 14821 |
The commands \ics{newglossaryentry} and \ics{longnewglossaryentry} |
| 14822 |
are the foundation for all commands that define glossary entries. |
| 14823 |
These commands both require that either the \field{name} or the |
| 14824 |
\field{parent} field are set. If the \field{name} is omitted, then |
| 14825 |
its value is obtained from the \gls{parententry}['s] name. The |
| 14826 |
\field{description} must also be provided but may be set to empty. |
| 14827 |
(Some entry types, such as \atentry{index}, will set |
| 14828 |
\field{description} to empty if that field is missing, but for other |
| 14829 |
entry types, such as \atentry{entry}, the \field{description} is |
| 14830 |
required and will trigger a warning if omitted.) |
| 14831 |
|
| 14832 |
All other entry definition commands, such as \ics{newabbreviation} and |
| 14833 |
\ics{glsxtrnewsymbol}, internally use one of those foundation |
| 14834 |
commands.\footnote{Or the internal command that both |
| 14835 |
\cs{newglossaryentry} and \cs{longnewglossaryentry} use.} In the |
| 14836 |
case of \ics{newabbreviation} (and \ics{newacronym}), the |
| 14837 |
\field{name} field is set by the style using values obtained from |
| 14838 |
the \field{short} and\slash or \field{long} fields. This is |
| 14839 |
information that \bibgls\ is unaware of and may guess incorrectly |
| 14840 |
when trying to determine an appropriate value for the \field{name} |
| 14841 |
field if it is omitted (which is typically the case) from |
| 14842 |
abbreviation entry types, such as \atentry{abbreviation} or |
| 14843 |
\atentry{acronym}. |
| 14844 |
|
| 14845 |
The general \atentry{entry} entry type, uses the same rules as |
| 14846 |
\ics{newglossaryentry}: |
| 14847 |
\begin{description} |
| 14848 |
\item[\field{name}] If the \field{parent} field has been set, then |
| 14849 |
the parent's \field{name} field is used. If the parent's |
| 14850 |
\field{name} field isn't set, then the fallback for the parent's |
| 14851 |
\field{name} field is used (which will depend on the parent's |
| 14852 |
\gls{entrytype}). If neither the \field{name} nor the \field{parent} |
| 14853 |
field is set, then a warning is issued since at least one of those |
| 14854 |
fields must be set for \atentry{entry}. |
| 14855 |
|
| 14856 |
\item[\field{text}] If the \field{text} field is missing, it's |
| 14857 |
obtained from the \field{name} field or the fallback for the |
| 14858 |
\field{name} field, if that hasn't been set. |
| 14859 |
|
| 14860 |
\item[\field{plural}] If the \field{name} field has been set then |
| 14861 |
the \field{plural} value is obtained by appending \ics{glspluralsuffix} |
| 14862 |
to the value of the \field{text} field (or the fallback for the |
| 14863 |
\field{text} field, if that hasn't been set). |
| 14864 |
|
| 14865 |
If the \field{name} field hasn't been set but the \field{parent} |
| 14866 |
field has been set, then the \field{plural} is obtained from the |
| 14867 |
parent's \field{plural} field. If the parent's \field{plural} field |
| 14868 |
hasn't been set then the fallback for that value will be used, |
| 14869 |
according to the parent's \gls{entrytype}. |
| 14870 |
|
| 14871 |
\item[\field{first}] The fallback for the \field{first} field is |
| 14872 |
obtained from the \field{text} field (or the fallback for the |
| 14873 |
\field{text} field, if that hasn't been set). |
| 14874 |
|
| 14875 |
\item[\field{firstplural}] The fallback for the \field{firstplural} |
| 14876 |
field is obtained by appending \ics{glspluralsuffix} to the value of |
| 14877 |
the \field{first} field, if that field has been set, otherwise it's |
| 14878 |
obtained from the \field{plural} field (or the fallback for the |
| 14879 |
\field{plural} field if that isn't set). |
| 14880 |
|
| 14881 |
\end{description} |
| 14882 |
|
| 14883 |
Note that although \bibgls\ follows the \ics{newglossaryentry} rules |
| 14884 |
in order to obtain the fallback, it doesn't explicitly set those |
| 14885 |
fields in the \ext{glstex} file if they weren't provided in the |
| 14886 |
\ext{bib} file or set using options such as \csopt{replicate-fields} |
| 14887 |
or \csopt{assign-fields}. |
| 14888 |
|
| 14889 |
The exception to this is the \field{sort} field, which will be |
| 14890 |
obtained from the \field{name} field for most \glspl{entrytype} unless |
| 14891 |
overridden by one of the applicable sort fallback options, such as |
| 14892 |
\csopt{entry-sort-fallback}. If the designated fallback (such as |
| 14893 |
\field{name}) is missing, then the fallback value for that field |
| 14894 |
will be used. |
| 14895 |
|
| 14896 |
The \atentry{index} and \atentry{indexplural} entry types are |
| 14897 |
slightly different. They have their own rules for obtaining the |
| 14898 |
value of the \field{name} field, and will explicitly set it in the |
| 14899 |
\ext{glstex} file via the helper commands \gls{bibglsnewindex} |
| 14900 |
and \gls{bibglsnewindexplural}. |
| 14901 |
|
| 14902 |
In the case of \atentry{index}, if the \field{name} field is |
| 14903 |
missing, its value will be obtained from the entry's original label. |
| 14904 |
If the \field{sort} field is missing, its value is obtained from the |
| 14905 |
\field{name} field unless a different fallback is specified with |
| 14906 |
\csopt{custom-sort-fallbacks}. The remaining fallbacks are as for |
| 14907 |
\atentry{entry}. |
| 14908 |
|
| 14909 |
It's more complicated for \atentry{indexplural}, which has the following |
| 14910 |
fallback rules: |
| 14911 |
\begin{description} |
| 14912 |
\item[\field{name}] If the \field{name} field is missing, its value |
| 14913 |
is obtained from the entry's \field{plural} field (or the fallback |
| 14914 |
for the \field{plural} field, if that field is missing). |
| 14915 |
|
| 14916 |
\item[\field{plural}] If the \field{plural} field is missing, its |
| 14917 |
value is obtained by appending \ics{glspluralsuffix} to the value |
| 14918 |
of the \field{text} field (or the fallback for the \field{text} |
| 14919 |
field, if that field is missing). |
| 14920 |
|
| 14921 |
\item[\field{text}] If the \field{text} field is missing, its value |
| 14922 |
is obtained from the entry's original label. |
| 14923 |
|
| 14924 |
\item[\field{sort}] If the \field{sort} field is missing, its value |
| 14925 |
is obtained from the \field{name} field unless a different fallback |
| 14926 |
is specified with \csopt{custom-sort-fallbacks}. |
| 14927 |
\end{description} |
| 14928 |
The remaining fallbacks are as for \atentry{entry}. |
| 14929 |
|
| 14930 |
The most awkward of all the \glspl{entrytype} are, as indicated earlier, |
| 14931 |
the abbreviations where the field values such as \field{name} and |
| 14932 |
\field{text} are set by the abbreviation style. Therefore, there are resource |
| 14933 |
options specifically to identify the most appropriate fallback |
| 14934 |
values for abbreviations. The default is to use the value of the |
| 14935 |
\field{short} field as the fallback for the \field{name}, |
| 14936 |
\field{sort} and \field{text} fields. If this is inappropriate for |
| 14937 |
your abbreviation style then you will need to use the options listed below to |
| 14938 |
provide more appropriate fallbacks. These options don't actually set |
| 14939 |
the \field{name} and \field{text} fields in the \ext{glstex} file |
| 14940 |
and don't include any style formatting (such as font changing |
| 14941 |
commands), which are irrelevant to \bibgls.\footnote{The \field{sort} field |
| 14942 |
will be set in the \ext{glstex} file as it's useful for debugging, |
| 14943 |
but it's typically irrelevant.} |
| 14944 |
|
| 14945 |
For other entry types, see their description in \sectionref{sec:bib}. |
| 14946 |
|
| 14947 |
\optsection{abbreviation-name-fallback} |
| 14948 |
|
| 14949 |
The \glspl{entrytype} that define abbreviations (such as |
| 14950 |
\atentry{abbreviation} and \atentry{acronym}) will, by default, |
| 14951 |
fallback on the \field{short} field if the \field{name} field is |
| 14952 |
missing and it's required for some reason (for example, with |
| 14953 |
\csopt[name]{sort-field}). If you prefer to |
| 14954 |
fallback on a different field, then you can use this option to |
| 14955 |
specify the field. For example, |
| 14956 |
\csopt[long]{abbreviation-name-fallback}. |
| 14957 |
The \meta{field} value must be a known field (not an internal field) |
| 14958 |
but can't be the \field{sort} field. |
| 14959 |
|
| 14960 |
Note that the default fallback for the \field{sort} field for |
| 14961 |
abbreviations is given by \csopt{abbreviation-sort-fallback} which |
| 14962 |
is set to \field{short} not \field{name} by default. So changing the |
| 14963 |
fallback for the \field{name} field won't have an effect unless the |
| 14964 |
\field{sort} fallback is changed to \field{name} or |
| 14965 |
\csopt[\field{name}]{sort-field} is used or the \field{name} field |
| 14966 |
is referenced in an option such as \csopt{assign-fields}. |
| 14967 |
|
| 14968 |
Field concatenation isn't available for this option. |
| 14969 |
|
| 14970 |
\optsection{abbreviation-text-fallback} |
| 14971 |
|
| 14972 |
Similar to \csopt{abbreviation-name-fallback} but for the |
| 14973 |
\field{text} field. The default fallback is the \field{short} field. |
| 14974 |
Field concatenation isn't available for this option. |
| 14975 |
|
| 14976 |
Note that you can't have both |
| 14977 |
\csopt[\field{text}]{abbreviation-name-fallback} and |
| 14978 |
\csopt[\field{name}]{abbreviation-text-fallback} as it would cause |
| 14979 |
an infinite loop. |
| 14980 |
|
| 14981 |
\optsection{abbreviation-sort-fallback} |
| 14982 |
|
| 14983 |
The \glspl{entrytype} that define abbreviations (such as |
| 14984 |
\atentry{abbreviation} and \atentry{acronym}) will, by default, |
| 14985 |
fallback on the \field{short} field if the \field{sort} field is |
| 14986 |
missing (assuming \csopt[sort]{sort-field}). If you prefer to |
| 14987 |
fallback on a different field, then you can use this option to |
| 14988 |
specify the field. For example, |
| 14989 |
\csopt[long]{abbreviation-sort-fallback}. Note that if you use |
| 14990 |
\csopt[name]{sort-field}, then the fallback field will be given by |
| 14991 |
\csopt{abbreviation-name-fallback} if the \field{name} field is |
| 14992 |
omitted. |
| 14993 |
|
| 14994 |
The \meta{field} may be a known field but not an internal |
| 14995 |
field. It can't be the \field{sort} field. It may also be |
| 14996 |
one of the keywords: \optfmt{id} (for the entry's label) or |
| 14997 |
\optfmt{original id} (for the entry's original label). The |
| 14998 |
\meta{field} may also be a composite in the form |
| 14999 |
\optfmt{\meta{field1}+\meta{field2}+\ldots} which indicates that the |
| 15000 |
sort value should be obtained by concatenating the values of given fields, |
| 15001 |
where the separator is given by \csopt{field-concat-sep}. |
| 15002 |
|
| 15003 |
Note that \csopt{missing-sort-fallback} and |
| 15004 |
\csopt{custom-sort-fallbacks} override this setting. |
| 15005 |
|
| 15006 |
\begin{important} |
| 15007 |
The \csopt{abbreviation-sort-fallback} setting is only used when \bibgls\ |
| 15008 |
tries to access the \field{sort} field for an abbreviation and finds |
| 15009 |
that the field hasn't been set. This means that this setting has no effect |
| 15010 |
if you explicitly set the \field{sort} field or if you change the field used |
| 15011 |
for sorting (\csopt{sort-field}). |
| 15012 |
\end{important} |
| 15013 |
|
| 15014 |
\optsection{entry-sort-fallback} |
| 15015 |
|
| 15016 |
The regular \glspl{entrytype} (such as \atentry{entry} and |
| 15017 |
\atentry{dualentry}) will, by default, fallback on the \field{name} |
| 15018 |
field if the \field{sort} field is missing (assuming |
| 15019 |
\csopt[sort]{sort-field}). If you prefer to |
| 15020 |
fallback on a different field, then you can use this option to |
| 15021 |
specify the field. |
| 15022 |
Note that \csopt{missing-sort-fallback} and |
| 15023 |
\csopt{custom-sort-fallbacks} override this setting. |
| 15024 |
|
| 15025 |
The \meta{field} may be a known field but not an internal |
| 15026 |
field. It can't be the \field{sort} field. It may also be |
| 15027 |
one of the keywords: \optfmt{id} (for the entry's label) or |
| 15028 |
\optfmt{original id} (for the entry's original label). The |
| 15029 |
\meta{field} may also be a composite in the form |
| 15030 |
\optfmt{\meta{field1}+\meta{field2}+\ldots} which indicates that the |
| 15031 |
sort value should be obtained by concatenating the values of given fields, |
| 15032 |
where the separator is given by \csopt{field-concat-sep}. |
| 15033 |
|
| 15034 |
This setting doesn't affect the index type of entries, such as |
| 15035 |
\atentry{index} or \atentry{indexplural}. This is useful if your |
| 15036 |
glossary contains \iglspl{homograph} (terms with the same spelling) which |
| 15037 |
can't be distinguished by the sort comparators. For example, suppose |
| 15038 |
my file \filefmt{entries.bib} contains: |
| 15039 |
\begin{codeenv} |
| 15040 |
\atentry{index}\marg{pagelist, |
| 15041 |
\field{name}=\marg{page list}, |
| 15042 |
\field{description}=\marg{a list of individual pages or page ranges} |
| 15043 |
} |
| 15044 |
\strut |
| 15045 |
\atentry{index}\marg{glossary} |
| 15046 |
\strut |
| 15047 |
\atentry{entry}\marg{glossarylist, |
| 15048 |
\field{parent}=\marg{glossary}, |
| 15049 |
\field{description}=\marg{list of technical words} |
| 15050 |
} |
| 15051 |
\strut |
| 15052 |
\atentry{entry}\marg{glosscol, |
| 15053 |
\field{parent}=\marg{glossary}, |
| 15054 |
\field{description}=\marg{collection of glosses} |
| 15055 |
} |
| 15056 |
\end{codeenv} |
| 15057 |
Now first consider a document that uses the default settings: |
| 15058 |
\begin{codeenv} |
| 15059 |
\cmd{documentclass}\marg{article} |
| 15060 |
\strut |
| 15061 |
\cmd{usepackage}\oarg{\styopt{record},\styopt{subentrycounter},\styopt[\glostyle{treenoname}]{style}}\marg{glossaries-extra} |
| 15062 |
\strut |
| 15063 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}} |
| 15064 |
\strut |
| 15065 |
\cmd{begin}\marg{document} |
| 15066 |
A test document describing \cs{glspl}\marg{pagelist} and |
| 15067 |
\cs{gls}\marg{glosscol} (collection) vs \cs{gls}\marg{glossarylist} (list). |
| 15068 |
\strut |
| 15069 |
\cs{printunsrtglossary} |
| 15070 |
\cmd{end}\marg{document} |
| 15071 |
\end{codeenv} |
| 15072 |
The default behaviour for \atentry{entry} if the \field{sort} field |
| 15073 |
is missing is to fallback on the \field{name} field. If the |
| 15074 |
\field{name} field is missing (as with \code{glossarylist} and |
| 15075 |
\code{glosscol}), then the value is obtained from the |
| 15076 |
\field{name} field from the \gls{parententry}. The \gls{parententry} for these |
| 15077 |
\glspl{homograph} is the \code{glossary} entry, which was defined with |
| 15078 |
\atentry{index} and doesn't have the \field{name} field. For the |
| 15079 |
\atentry{index} entries, if \field{name} is missing the value is |
| 15080 |
obtained from the label. |
| 15081 |
|
| 15082 |
Therefore both \code{glossarylist} and \code{glosscol} end |
| 15083 |
up with the same sort value: \code{glossary}. This triggers a |
| 15084 |
message in verbose mode (\commonlongarg{verbose}) which can be found |
| 15085 |
in the transcript file: |
| 15086 |
\begin{verbatim} |
| 15087 |
Identical sort values for 'glossarylist' and 'glosscol' |
| 15088 |
Falling back on ID |
| 15089 |
\end{verbatim} |
| 15090 |
So the actual sort values used are \qt{glossarylist} and |
| 15091 |
\qt{glosscol}. This puts the \code{glossarylist} entry |
| 15092 |
before the \code{glosscol} entry. |
| 15093 |
|
| 15094 |
Now suppose a minor modification is made to the document: |
| 15095 |
\begin{codeenv} |
| 15096 |
\gls{GlsXtrLoadResources} |
| 15097 |
\oarg{ |
| 15098 |
\csopt[entries]{src}, |
| 15099 |
\csopt[description]{entry-sort-fallback} |
| 15100 |
} |
| 15101 |
\end{codeenv} |
| 15102 |
This means that when the sort function fails to find the |
| 15103 |
\field{sort} field for the terms defined with \atentry{entry}, it |
| 15104 |
will fallback on the \field{description} field. This doesn't affect |
| 15105 |
the terms defined with \atentry{index}, which still fallback on the |
| 15106 |
\field{name} field. This time there's no message in the transcript |
| 15107 |
file and the \code{glosscol} entry now comes before the |
| 15108 |
\code{glossarylist} entry. |
| 15109 |
|
| 15110 |
\begin{important} |
| 15111 |
The \csopt{entry-sort-fallback} setting is only used when \bibgls\ |
| 15112 |
tries to access the \field{sort} field for a term defined with |
| 15113 |
\atentry{entry} and finds that the field hasn't been set. This means |
| 15114 |
that this setting has no effect if you explicitly set the \field{sort} |
| 15115 |
field or if you change the field used for sorting |
| 15116 |
(\csopt{sort-field}). |
| 15117 |
\end{important} |
| 15118 |
|
| 15119 |
\optsection{symbol-sort-fallback} |
| 15120 |
|
| 15121 |
The \glspl{entrytype} that define symbols (such as \atentry{symbol} and |
| 15122 |
\atentry{number}) will, by default, fallback on the entry's original label if the |
| 15123 |
\field{sort} field is missing (assuming the default |
| 15124 |
\csopt[sort]{sort-field}). If you prefer to fallback on a different |
| 15125 |
field, then you can use this option to specify the field. For |
| 15126 |
example, \csopt[name]{symbol-sort-fallback}. |
| 15127 |
|
| 15128 |
The \meta{field} may be a known field but not an internal |
| 15129 |
field. It can't be the \field{sort} field. It may also be |
| 15130 |
one of the keywords: \optfmt{id} (for the entry's label) or |
| 15131 |
\optfmt{original id} (for the entry's original label). The |
| 15132 |
\meta{field} may also be a composite in the form |
| 15133 |
\optfmt{\meta{field1}+\meta{field2}+\ldots} which indicates that the |
| 15134 |
sort value should be obtained by concatenating the values of given fields, |
| 15135 |
where the separator is given by \csopt{field-concat-sep}. |
| 15136 |
|
| 15137 |
Note that \csopt{missing-sort-fallback} and |
| 15138 |
\csopt{custom-sort-fallbacks} override this setting. |
| 15139 |
|
| 15140 |
\begin{important} |
| 15141 |
The \csopt{symbol-sort-fallback} setting is only used when \bibgls\ |
| 15142 |
tries to access the \field{sort} field for a symbol and finds |
| 15143 |
that the field hasn't been set. This means that this setting has no effect |
| 15144 |
if you explicitly set the \field{sort} field or if you change the field used |
| 15145 |
for sorting (\csopt{sort-field}). |
| 15146 |
\end{important} |
| 15147 |
|
| 15148 |
\optsection{bibtexentry-sort-fallback} |
| 15149 |
|
| 15150 |
The \glsdisp{mainentry}{main} \atentry{bibtexentry} |
| 15151 |
\glspl{entrytype} will, by default, |
| 15152 |
fallback on the \field{name} if the |
| 15153 |
\field{sort} field is missing (assuming the default |
| 15154 |
\csopt[sort]{sort-field}). If you prefer to fallback on a different |
| 15155 |
field, then you can use this option to specify the field. |
| 15156 |
|
| 15157 |
The \meta{field} may be a known field but not an internal |
| 15158 |
field. It can't be the \field{sort} field. It may also be |
| 15159 |
one of the keywords: \optfmt{id} (for the entry's label) or |
| 15160 |
\optfmt{original id} (for the entry's original label). The |
| 15161 |
\meta{field} may also be a composite in the form |
| 15162 |
\optfmt{\meta{field1}+\meta{field2}+\ldots} which indicates that the |
| 15163 |
sort value should be obtained by concatenating the values of given fields, |
| 15164 |
where the separator is given by \csopt{field-concat-sep}. |
| 15165 |
|
| 15166 |
Note that \csopt{missing-sort-fallback} and |
| 15167 |
\csopt{custom-sort-fallbacks} override this setting. |
| 15168 |
|
| 15169 |
\begin{important} |
| 15170 |
The \csopt{bibtexentry-sort-fallback} setting is only used when |
| 15171 |
\bibgls\ tries to access the \field{sort} field for a \gls{mainentry} |
| 15172 |
defined with \atentry{bibtexentry} and finds that the field hasn't |
| 15173 |
been set. This means that this setting has no effect if you |
| 15174 |
explicitly set the \field{sort} field or if you change the field used for |
| 15175 |
sorting (\csopt{sort-field}). |
| 15176 |
\end{important} |
| 15177 |
|
| 15178 |
\optsection{custom-sort-fallbacks} |
| 15179 |
|
| 15180 |
The value should be a \keyvallist\ in the form |
| 15181 |
\meta{entrytype}\dequals\meta{field} where \meta{entrytype} is the |
| 15182 |
\emph{original} \gls{entrytype} (before being aliased with |
| 15183 |
\csopt{entry-type-aliases}). This will override any of the sort fallback |
| 15184 |
options listed below for entries whose original \gls{entrytype} matches |
| 15185 |
\meta{entrytype}. |
| 15186 |
|
| 15187 |
The \meta{field} may be a known field but not an internal field. For |
| 15188 |
obvious reasons, it can't be the \field{sort} field (since |
| 15189 |
\meta{field} is the fallback a missing \field{sort} field). It may also be one of the |
| 15190 |
keywords: \optfmt{id} (for the entry's label) or \optfmt{original id} |
| 15191 |
(for the entry's original label). The \meta{field} may also be a |
| 15192 |
composite in the form \optfmt{\meta{field1}+\meta{field2}+\ldots} |
| 15193 |
which indicates that the sort value should be obtained by |
| 15194 |
concatenating the values of the given fields, where the separator is |
| 15195 |
given by \csopt{field-concat-sep}. |
| 15196 |
|
| 15197 |
For example, if the \ext{bib} file contains: |
| 15198 |
\begin{codeenv} |
| 15199 |
\atentryfmt{unit}\marg{ohm, |
| 15200 |
\field{name}=\marg{\cs{si}\marg{\csfmt{ohm}}}, |
| 15201 |
\field{description}=\marg{electrical resistance} |
| 15202 |
} |
| 15203 |
\strut |
| 15204 |
\atentryfmt{constant}\marg{pi, |
| 15205 |
\field{name}=\marg{\cs{ensuremath}\marg{\cs{pi}}}, |
| 15206 |
\field{description}=\marg{the ratio of the length of the circumference |
| 15207 |
of a circle to its diameter}, |
| 15208 |
\field{user1}=\marg{3.14159} |
| 15209 |
} |
| 15210 |
\strut |
| 15211 |
\atentry{symbol}\marg{fx, |
| 15212 |
\field{name}=\marg{\cs{ensuremath}\marg{f(x)}}, |
| 15213 |
\field{description}=\marg{a function of \idx{mshiftchar}x\idx{mshiftchar}} |
| 15214 |
} |
| 15215 |
\strut |
| 15216 |
\atentry{number}\marg{zero, |
| 15217 |
\field{name}=\marg{0}, |
| 15218 |
\field{description}=\marg{nothing or no quantity} |
| 15219 |
} |
| 15220 |
\end{codeenv} |
| 15221 |
Then the resource options: |
| 15222 |
\begin{codeenv} |
| 15223 |
\csopt[\entryfmt{unit}=\entryref{symbol},\entryfmt{constant}=\entryref{number}]{entry-type-aliases}, |
| 15224 |
\csopt[\entryfmt{unit}=\field{name},\entryfmt{constant}=\field{user1}]{custom-sort-fallbacks} |
| 15225 |
\end{codeenv} |
| 15226 |
will treat the custom \atentryfmt{unit} and \atentryfmt{constant} |
| 15227 |
entries as though they had been defined with \atentry{symbol} |
| 15228 |
and \atentry{number}, respectively, but the fallback for the |
| 15229 |
\field{sort} field is different: the \code{ohm} entry will use the |
| 15230 |
\field{name} field for the sort fallback (because its original |
| 15231 |
\gls{entrytype} was \entryfmt{unit}), the \code{pi} entry will use the |
| 15232 |
\field{user1} field for the sort fallback (because its original |
| 15233 |
\gls{entrytype} was \entryfmt{constant}) and the \code{fx} and |
| 15234 |
\code{zero} entries will use the label for the sort fallback (since |
| 15235 |
neither \entryfmt{symbol} nor \entryfmt{number} were identified in |
| 15236 |
\csopt{custom-sort-fallbacks} so the \csopt{symbol-sort-fallback} is |
| 15237 |
used). |
| 15238 |
|
| 15239 |
If an entry hasn't had its \gls{entrytype} aliased then \meta{entrytype} |
| 15240 |
is its actual \gls{entrytype}. For example, consider the following |
| 15241 |
definitions: |
| 15242 |
\begin{codeenv} |
| 15243 |
\atentry{abbreviation}\marg{svm, |
| 15244 |
\field{short}=\marg{SVM}, |
| 15245 |
\field{long}=\marg{support vector machine} |
| 15246 |
} |
| 15247 |
\atentry{acronym}\marg{laser, |
| 15248 |
\field{short}=\marg{laser}, |
| 15249 |
\field{long}=\marg{light amplification by stimulated emission of radiation} |
| 15250 |
} |
| 15251 |
\end{codeenv} |
| 15252 |
Then \csopt[short]{abbreviation-sort-fallback} will make both |
| 15253 |
entries fallback on the \field{short} field (since |
| 15254 |
\csopt{abbreviation-sort-fallback} applies to both \atentry{acronym} |
| 15255 |
and \atentry{abbreviation}), but the option: |
| 15256 |
\begin{codeenv} |
| 15257 |
\csopt[\entryref{abbreviation}=\field{long},\entryref{acronym}=\field{short}]{custom-sort-fallbacks} |
| 15258 |
\end{codeenv} |
| 15259 |
will make the entry defined with \atentry{abbreviation} fallback on |
| 15260 |
the \field{long} field and the entry defined with \atentry{acronym} |
| 15261 |
will fallback on the \field{short} field. |
| 15262 |
|
| 15263 |
Since the default setting is \csopt[short]{abbreviation-sort-fallback} |
| 15264 |
this only needs to be: |
| 15265 |
\begin{codeenv} |
| 15266 |
\csopt[\entryref{abbreviation}=\field{long}]{custom-sort-fallbacks} |
| 15267 |
\end{codeenv} |
| 15268 |
In this case, the entry defined with \atentry{abbreviation} (\qt{SVM}) will use |
| 15269 |
the setting given in \csopt{custom-sort-fallbacks}, but the entry |
| 15270 |
defined with \atentry{acronym} (\qt{laser}) will use the setting given by |
| 15271 |
\csopt{abbreviation-sort-fallback} since \atentry{acronym} hasn't |
| 15272 |
been identified in \csopt{custom-sort-fallbacks}. |
| 15273 |
|
| 15274 |
This option also covers \glspl{dualentry}. For example: |
| 15275 |
\begin{codeenv} |
| 15276 |
\csopt[ |
| 15277 |
\entryref{dualindexnumber}=\field{description}, |
| 15278 |
\entryfmt{dualindexnumbersecondary}=\field{user1} |
| 15279 |
]{custom-sort-fallbacks} |
| 15280 |
\end{codeenv} |
| 15281 |
Note that the \gls{entrytype} for the \dual\ is in the form |
| 15282 |
\code{\meta{primary entry type}secondary}. |
| 15283 |
|
| 15284 |
\begin{important} |
| 15285 |
The \csopt{custom-sort-fallbacks} setting is only used when \bibgls\ |
| 15286 |
tries to access the \field{sort} field for an entry (whose original |
| 15287 |
\gls{entrytype} has been identified in this setting) and finds that the field |
| 15288 |
hasn't been set. This means that this setting has no effect if you |
| 15289 |
explicitly set the \field{sort} field or if you change the field |
| 15290 |
used for sorting (\csopt{sort-field}). |
| 15291 |
\end{important} |
| 15292 |
|
| 15293 |
\optsection{field-concat-sep} |
| 15294 |
|
| 15295 |
This option sets the field concatenation separator to \meta{value} |
| 15296 |
used by the \field{sort} fallback options. The default is a space. |
| 15297 |
An empty value indicates no separator. You may use |
| 15298 |
\gls{uhex}\meta{hex} to indicate a character by its hexadecimal code |
| 15299 |
(see \sectionref{sec:quarks}). Note that the more complex field |
| 15300 |
concatenation specification described in |
| 15301 |
\sectionref{sec:optstringconcat} isn't available for this option. |
| 15302 |
|
| 15303 |
For example, suppose the \ext{bib} file contains: |
| 15304 |
\begin{codeenv} |
| 15305 |
\atentry{abbreviation}\marg{ac, |
| 15306 |
\field{short}=\marg{AC}, |
| 15307 |
\field{long}=\marg{alternating current} |
| 15308 |
} |
| 15309 |
\atentry{index}\marg{acacia} |
| 15310 |
\end{codeenv} |
| 15311 |
Then the resource option: |
| 15312 |
\begin{codeenv} |
| 15313 |
\gls{GlsXtrLoadResources}\oarg{ |
| 15314 |
\csopt[letter-nocase]{sort}, |
| 15315 |
\csopt[\field{short}+\field{long}]{abbreviation-sort-fallback} |
| 15316 |
} |
| 15317 |
\end{codeenv} |
| 15318 |
will set the \code{ac} sort value to \qt{AC alternating current}. |
| 15319 |
That is, the \field{short} value concatenated with the \field{long} |
| 15320 |
value using the default space separator. With the |
| 15321 |
\optfmt{letter-nocase} sort method, this will put the \code{ac} |
| 15322 |
entry before the \code{acacia} entry (because the space character |
| 15323 |
comes before \qt{a}). |
| 15324 |
|
| 15325 |
If the resource options are changed to: |
| 15326 |
\begin{codeenv} |
| 15327 |
\gls{GlsXtrLoadResources}\oarg{ |
| 15328 |
\csopt[letter-nocase]{sort}, |
| 15329 |
\csopt[\empty]{field-concat-sep}, |
| 15330 |
\csopt[\field{short}+\field{long}]{abbreviation-sort-fallback} |
| 15331 |
} |
| 15332 |
\end{codeenv} |
| 15333 |
This will obtain the sort value for abbreviations from a |
| 15334 |
concatenation of the \meta{short} and \meta{long} values without a |
| 15335 |
separator. This means that the \code{ac} sort value will be |
| 15336 |
\qt{ACalternating current} and so the \code{ac} entry will |
| 15337 |
come after the \code{acacia} entry (since \qt{l} comes after \qt{c}). |
| 15338 |
|
| 15339 |
This setting is only used for the sort fallback options that allow |
| 15340 |
field concatenation (such as \csopt{entry-sort-fallback} but not |
| 15341 |
\csopt{missing-sort-fallback}). |
| 15342 |
|
| 15343 |
Note that due to the way that the \keyvallist\ parser trims leading and |
| 15344 |
trailing spaces, you can't simply do \csopt[~]{field-concat-sep} |
| 15345 |
to indicate a space character as the value will end up as an empty |
| 15346 |
string. You can instead do \csopt[\stringu20]{field-concat-sep} but |
| 15347 |
since this is the default value there shouldn't be much need for it. |
| 15348 |
|
| 15349 |
Remember that the separator may be replaced with a break point |
| 15350 |
marker depending on the sort method and \csopt{break-at} setting. |
| 15351 |
|
| 15352 |
\section{Plurals} |
| 15353 |
\label{sec:plurals} |
| 15354 |
|
| 15355 |
Some languages, such as English, have a general rule that plurals |
| 15356 |
are formed from the singular with a suffix appended. This isn't |
| 15357 |
an absolute rule. There are plenty of exceptions (for example, |
| 15358 |
geese, children, churches, elves, fairies, sheep, mice), so a |
| 15359 |
simplistic approach of just doing \code{\ics{gls}\margm{label}[s]} |
| 15360 |
will sometimes produce inappropriate results, so the \styfmt{glossaries} |
| 15361 |
package provides a \field{plural} key with the corresponding command |
| 15362 |
\ics{glspl}. |
| 15363 |
|
| 15364 |
In some cases a plural may not make any sense (for example, if the |
| 15365 |
term is a verb or symbol), so the \field{plural} key is optional, but to |
| 15366 |
make life easier for languages where the majority of plurals can |
| 15367 |
simply be formed by appending a suffix to the singular, the |
| 15368 |
\styfmt{glossaries} package lets the \field{plural} field default |
| 15369 |
to the value of the \field{text} field with \ics{glspluralsuffix} |
| 15370 |
appended. This command is defined to be just the letter \qt{s}. |
| 15371 |
This means that the majority of terms in such languages don't need to have the |
| 15372 |
\field{plural} supplied as well, and you only need to use it for the |
| 15373 |
exceptions. |
| 15374 |
|
| 15375 |
For languages that don't have this general rule, the \field{plural} |
| 15376 |
field will always need to be supplied for nouns. |
| 15377 |
|
| 15378 |
There are other plural fields, such as \field{firstplural}, |
| 15379 |
\field{longplural} and \field{shortplural}. Again, if you are using |
| 15380 |
a language that doesn't have a simple suffix rule, you'll have to |
| 15381 |
supply the plural forms if you need them (and if a plural makes |
| 15382 |
sense in the context). |
| 15383 |
|
| 15384 |
If these fields are omitted, the \styfmt{glossaries} package follows |
| 15385 |
these rules: |
| 15386 |
\begin{itemize} |
| 15387 |
\item If \field{firstplural} is missing, then \ics{glspluralsuffix} |
| 15388 |
is appended to the \field{first} field, if that field has been |
| 15389 |
supplied. If the \field{first} field hasn't been supplied but the |
| 15390 |
\field{plural} field has been supplied, then the \field{firstplural} |
| 15391 |
field defaults to the \field{plural} field. If the \field{plural} |
| 15392 |
field hasn't been supplied, then both the \field{plural} and |
| 15393 |
\field{firstplural} fields default to the \field{text} field (or |
| 15394 |
\field{name}, if no \field{text} field) with \ics{glspluralsuffix} |
| 15395 |
appended. |
| 15396 |
|
| 15397 |
\item If the \field{longplural} field is missing, then |
| 15398 |
\ics{glspluralsuffix} is appended to the \field{long} field, if the |
| 15399 |
\field{long} field has been supplied. |
| 15400 |
|
| 15401 |
\item If the \field{shortplural} field is missing then, \emph{with |
| 15402 |
the base \styfmt{glossaries} acronym mechanism}, \ics{acrpluralsuffix} |
| 15403 |
is appended to the \field{short} field. |
| 15404 |
|
| 15405 |
\end{itemize} |
| 15406 |
|
| 15407 |
The last case is different with the \isty{glossaries-extra} extension |
| 15408 |
package. The \field{shortplural} field defaults to the \field{short} |
| 15409 |
field with \ics{abbrvpluralsuffix} appended \emph{unless overridden |
| 15410 |
by category attributes}. This suffix command is set by the |
| 15411 |
abbreviation styles. This means that every time an abbreviation |
| 15412 |
style is implemented, \ics{abbrvpluralsuffix} is redefined. Most |
| 15413 |
styles simply define this command as: |
| 15414 |
\begin{codeenv} |
| 15415 |
\cs{renewcommand}*\marg{\cs{abbrvpluralsuffix}}\marg{\cs{glsxtrabbrvpluralsuffix}} |
| 15416 |
\end{codeenv} |
| 15417 |
where \ics{glsxtrabbrvpluralsuffix} expands to \ics{glspluralsuffix}. |
| 15418 |
The \qt{sc} styles (such as \abbrstyle{long-short-sc}) use a different |
| 15419 |
definition: |
| 15420 |
\begin{codeenv} |
| 15421 |
\cs{renewcommand}*\marg{\cs{abbrvpluralsuffix}}\marg{\cs{protect}\ics{glsxtrscsuffix}} |
| 15422 |
\end{codeenv} |
| 15423 |
This allows the suffix to be reverted back to the upright font, |
| 15424 |
counteracting the affect of the small-caps font. |
| 15425 |
|
| 15426 |
This means that if you want to change or strip the suffix used for |
| 15427 |
the plural short form, it's usually not sufficient to redefine |
| 15428 |
\ics{abbrvpluralsuffix}, as the change will be undone the next time |
| 15429 |
the style is applied. Instead, for a document-wide solution, you |
| 15430 |
need to redefine \ics{glsxtrabbrvpluralsuffix}. Alternatively you can |
| 15431 |
use the category attributes. |
| 15432 |
|
| 15433 |
There are two attributes that affect the short plural suffix |
| 15434 |
formation. The first is \catattr{aposplural} which uses the suffix |
| 15435 |
\begin{codeenv*} |
| 15436 |
\idx{aposchar}\cs{abbrvpluralsuffix} |
| 15437 |
\end{codeenv*} |
| 15438 |
That is, an \idx{apostrophe} followed by \ics{abbrvpluralsuffix} is |
| 15439 |
appended. The second attribute is \catattr{noshortplural} which |
| 15440 |
suppresses the suffix and simply sets \field{shortplural} to the |
| 15441 |
same as \field{short}. |
| 15442 |
|
| 15443 |
With \bibgls, if you have some abbreviations where the plural should |
| 15444 |
have a suffix and some where the plural shouldn't have a suffix |
| 15445 |
(for example, the document has both English and French abbreviations) |
| 15446 |
then there are two approaches. |
| 15447 |
|
| 15448 |
The first approach is to use the category attributes. For example: |
| 15449 |
\begin{codeenv} |
| 15450 |
\cs{glssetcategoryattribute}\marg{french}\marg{\catattr{noshortplural}} |
| 15451 |
\end{codeenv} |
| 15452 |
Now just make sure all the French abbreviations are have their |
| 15453 |
\field{category} field set to \optfmt{french}: |
| 15454 |
\begin{codeenv} |
| 15455 |
\gls{GlsXtrLoadResources}\oarg{\csopt[fr-abbrvs]{src},\csopt[french]{category}} |
| 15456 |
\end{codeenv} |
| 15457 |
|
| 15458 |
The other approach is to use the options listed below for the given |
| 15459 |
\igls{resourceset}. For example: |
| 15460 |
\begin{codeenv} |
| 15461 |
\gls{GlsXtrLoadResources}\oarg{\csopt[fr-abbrvs]{src},\csopt[\empty]{short-plural-suffix}} |
| 15462 |
\end{codeenv} |
| 15463 |
|
| 15464 |
\optsection{short-plural-suffix} |
| 15465 |
|
| 15466 |
Sets the plural suffix for the default \field{shortplural} to |
| 15467 |
\meta{value}. The \meta{value} may be one of: |
| 15468 |
\begin{itemize} |
| 15469 |
\item \meta{suffix}: add the |
| 15470 |
\field{shortplural} field, if missing, with the given \meta{suffix}. |
| 15471 |
\item \meta{empty}: add the |
| 15472 |
\field{shortplural} field, if missing, with no suffix. |
| 15473 |
\item \optfmt{use-default}: leave |
| 15474 |
it to \styfmt{glossaries-extra} to determine the appropriate default. |
| 15475 |
\end{itemize} |
| 15476 |
The default setting is \csopt[use-default]{short-plural-suffix}. |
| 15477 |
If the \code{=\meta{value}} part is omitted, then |
| 15478 |
\csopt[\empty]{short-plural-suffix} is assumed. |
| 15479 |
|
| 15480 |
\optsection{dual-short-plural-suffix} |
| 15481 |
|
| 15482 |
Sets the plural suffix for the default \field{dualshortplural} field to |
| 15483 |
\meta{value}. As with \csopt{short-plural-suffix}, the default |
| 15484 |
setting is \csopt[use-default]{dual-short-plural-suffix}. If the |
| 15485 |
\meta{value} is omitted or empty, the suffix is set to empty. |
| 15486 |
|
| 15487 |
\section{Location List Options} |
| 15488 |
\label{sec:locationopts} |
| 15489 |
|
| 15490 |
The \styopt{record} package option automatically adds two new keys: |
| 15491 |
\field{loclist} and \field{location}. These two fields are set by |
| 15492 |
\bibgls\ from the information supplied in the \iext{aux} file (unless |
| 15493 |
the option \csopt[false]{save-locations} is used). The |
| 15494 |
\field{location} field contains the code to typeset the formatted |
| 15495 |
\igls{locationlist}. |
| 15496 |
|
| 15497 |
Note that the cross-referencing information provided with the |
| 15498 |
\field{see}, \field{seealso} and \field{alias} fields is put in the |
| 15499 |
location list. If you only want the cross-reference and not any of |
| 15500 |
the locations, use \csopt[see]{save-locations} (or similar). |
| 15501 |
|
| 15502 |
The \field{loclist} field has the syntax of an \isty{etoolbox} |
| 15503 |
internal list and includes every \gls{location} (except for the |
| 15504 |
\glsdisp{discardedrecord}{discarded duplicates} and |
| 15505 |
\iglspl{ignoredrecord}) with no \idx{range} formations. Any \idx{explicit-range} |
| 15506 |
markup is stripped from the \glsopt{format} information to leave |
| 15507 |
just the \idx{encap} name, so you just get the start and end |
| 15508 |
\glspl{location} added as individual elements but they are still |
| 15509 |
encapsulated with the associated formatting command. Each item in |
| 15510 |
the list is provided in one of the following forms: |
| 15511 |
\begin{codeenv} |
| 15512 |
\ics{glsseeformat}\oargm{tag}\margm{label list}\marg{} |
| 15513 |
\end{codeenv} |
| 15514 |
for the cross-reference supplied by the \field{see} field, |
| 15515 |
\begin{codeenv} |
| 15516 |
\ics{glsxtruseseealsoformat}\margm{xr list} |
| 15517 |
\end{codeenv} |
| 15518 |
for the cross-reference supplied by the \field{seealso} field, |
| 15519 |
\nosecdef{glsnoidxdisplayloc} |
| 15520 |
for standard the internal \glspl{location}, |
| 15521 |
\begin{codeenv} |
| 15522 |
\format{glsxtrdisplaysupploc} |
| 15523 |
\end{codeenv} |
| 15524 |
for \glsdisp{supplementalrecord}{supplemental (external) locations} and |
| 15525 |
\begin{codeenv} |
| 15526 |
\format{glsxtrdisplaylocnameref} |
| 15527 |
\end{codeenv} |
| 15528 |
for \code{nameref} \glspl{record}. (See \sectionref{sec:supplementalopts} |
| 15529 |
for more information about \glsdisp{supplementalrecord}{supplemental locations} and |
| 15530 |
\longarg{merge-nameref-on} for more information about \code{nameref} |
| 15531 |
records.) |
| 15532 |
|
| 15533 |
You can iterate through the \field{loclist} value |
| 15534 |
using one of \sty{etoolbox}'s internal list \idxpl{loop} (either |
| 15535 |
by first fetching the list using \ics{glsfieldfetch} |
| 15536 |
or through \styfmt{glossaries-extra}'s \ics{glsxtrfielddolistloop} |
| 15537 |
or \ics{glsxtrfieldforlistloop} shortcuts). |
| 15538 |
|
| 15539 |
The \meta{format} is that supplied by the \glsopt{format} key |
| 15540 |
when using commands like \ics{gls} or \ics{glsadd} (the encapsulator or |
| 15541 |
\idx{encap} in \idx!{makeindex} parlance). If omitted, the default |
| 15542 |
\glsopt[glsnumberformat]{format} is assumed (unless this |
| 15543 |
default value is changed with \ics{GlsXtrSetDefaultNumberFormat}. |
| 15544 |
The value of the \glsopt{format} key must be the name of |
| 15545 |
a text-block command without the leading backslash that takes |
| 15546 |
a single argument (the \gls{location}). The \gls{location} |
| 15547 |
is encapsulated by that command. For example, |
| 15548 |
\begin{codeenv} |
| 15549 |
\cs{gls}\oarg{\glsopt[\encap{textbf}]{format}}\marg{sample} |
| 15550 |
\end{codeenv} |
| 15551 |
will display the corresponding \gls{location} in bold, but note that this |
| 15552 |
will no longer have a hyperlink if you've used \sty{hyperref}. |
| 15553 |
If you want to retain the hyperlink you need the \gls{location} |
| 15554 |
encapsulated with \cs{hyperbf} instead of \cs{textbf}: |
| 15555 |
\begin{codeenv} |
| 15556 |
\cs{gls}\oarg{\glsopt[\encap{hyperbf}]{format}}\marg{sample} |
| 15557 |
\end{codeenv} |
| 15558 |
The \csfmt{hyper}\meta{xx} set of commands all internally use |
| 15559 |
\cs{glshypernumber} which adds the appropriate hyperlink to the |
| 15560 |
\gls{location}. See Table~6.1 in the \styfmt{glossaries}~\cite{glossaries} |
| 15561 |
user manual for a list of all the \csfmt{hyper}\meta{xx} commands. |
| 15562 |
|
| 15563 |
\Idxpl{range} can be explicitly formed using the parenthetical |
| 15564 |
syntax \glsopt[\idx{openrange}]{format} and |
| 15565 |
\glsopt[\idx{openrange}]{format} or \glsopt[\idx{openrange}\meta{csname}]{format} and |
| 15566 |
\glsopt[\idx{closerange}\meta{csname}]{format} (where \meta{csname} is again the name of |
| 15567 |
a text-block command without the initial backslash) in the optional |
| 15568 |
argument of commands like \ics{gls} or \ics{glsadd}. With |
| 15569 |
\sty{glossaries-extra} v1.50+, you can also use \ics{glsstartrange} |
| 15570 |
and \ics{glsendrange} (which is useful if the unbalanced parentheses |
| 15571 |
upset syntax highlighting). |
| 15572 |
|
| 15573 |
These \idxpl{explicit-range} will always form a \idx{range}, |
| 15574 |
regardless of \csopt{min-loc-range}, unless the start and end |
| 15575 |
coincide and \longarg{collapse-same-location-range} is in effect. |
| 15576 |
The \idx{explicit-range} will be encapsulated with \gls!{bibglsrange} |
| 15577 |
(unless \csopt[true]{merge-ranges}). (This command is not used with |
| 15578 |
\idxpl{implicit-range} that are formed by collating consecutive \glspl{location}.) |
| 15579 |
The initial marker is stripped from the \meta{format} argument of |
| 15580 |
the \gls{location} formatting commands, such as |
| 15581 |
\gls{glsnoidxdisplayloc}, to allow for easy conversion to the |
| 15582 |
corresponding text-block command. |
| 15583 |
|
| 15584 |
\Idxpl{explicit-range} don't merge with neighbouring |
| 15585 |
\glspl{location} (unless \csopt[true]{merge-ranges}), but will |
| 15586 |
absorb any individual \glspl{location} within the \idx{range} that doesn't |
| 15587 |
conflict. (Conflicts, denoted \idxpl{interloper}, will be moved to the start of the |
| 15588 |
\idx{explicit-range}, regardless of \csopt{merge-ranges}.) |
| 15589 |
For example, if \code{\cs{gls}\marg{sample}} is used on page~1, |
| 15590 |
\code{\cs{gls}\oarg{\glsopt[\idx{openrange}]{format}}\marg{sample}} |
| 15591 |
is used on page~2, \code{\cs{gls}\marg{sample}} is used on page~3, and |
| 15592 |
\code{\cs{gls}\oarg{\glsopt[\idx{closerange}]{format}}\marg{sample}} |
| 15593 |
is used on page~4, then the \gls{locationlist} will be 1, 2--4. The |
| 15594 |
entry on page~3 is absorbed into the \idx{explicit-range}, but, with |
| 15595 |
the default \csopt[false]{merge-ranges}, the |
| 15596 |
\idx{range} can't be expanded to include page~1. If the entry on page~3 had a |
| 15597 |
different format to the \idx{explicit-range}, for example |
| 15598 |
\code{\cs{gls}\oarg{\glsopt[\encap{textbf}]{format}}\marg{sample}} |
| 15599 |
then this will cause a warning and the \idx{interloper} will be |
| 15600 |
moved before the start of the \idx{range} so that the |
| 15601 |
\gls{locationlist} would then be 1, \textbf{3}, 2--4. |
| 15602 |
|
| 15603 |
The \csopt[true]{merge-ranges} option will make \idxpl{explicit-range} |
| 15604 |
behave like \idxpl{implicit-range}, which allows them to merge with |
| 15605 |
neighbouring \idxpl{range}. The \gls{bibglsrange} command won't be used in |
| 15606 |
this case (regardless of whether or not the \idx{range} was merged with |
| 15607 |
neighbouring \glspl{location}). Options such as |
| 15608 |
\csopt{min-loc-range} won't have an effect on the merged \idx{range}, but |
| 15609 |
will still effect \idxpl{implicit-range} that haven't been merged with an |
| 15610 |
\idx{explicit-range}. |
| 15611 |
|
| 15612 |
An \igls{ignoredrecord} identifies a term that needs to be treated as |
| 15613 |
though it has a \gls{record} for selection purposes, but the |
| 15614 |
\gls{record} should not be included in the \gls{locationlist}. |
| 15615 |
The special format \glsaddopt[\encap{glsignore}]{format} is provided |
| 15616 |
by the \styfmt{glossaries} package for cases where the \gls{location} |
| 15617 |
should be ignored. (The command \ics{glsignore} simply ignores its |
| 15618 |
argument.) This works reasonably well if an entry only has the one |
| 15619 |
\gls{location}, but if the entry happens to be indexed again, it can lead |
| 15620 |
to an odd empty gap in the \gls{locationlist} with a spurious comma. If |
| 15621 |
\bibgls\ encounters a \gls{record} with this special format, the entry |
| 15622 |
will be selected but the \gls{record} will be discarded. |
| 15623 |
|
| 15624 |
This means that the \gls{locationlist} will be empty if the entry was |
| 15625 |
only indexed with the special ignored format, but if the entry was also |
| 15626 |
indexed with another format then the \gls{locationlist} won't include the |
| 15627 |
\iglspl{ignoredrecord}. (This format is used by \ics{glsaddallunused} but |
| 15628 |
remember that iterative commands like this don't work with \bibgls. |
| 15629 |
Instead, just use \csopt[all]{selection} to select all entries. |
| 15630 |
Those that don't have \glspl{record} won't have a \gls{locationlist}.) |
| 15631 |
|
| 15632 |
For example, suppose you only want main matter \glspl{location} in the |
| 15633 |
number list, but you want entries that only appear in the back matter |
| 15634 |
to still appear in the glossary (without a \gls{locationlist}), then you could do: |
| 15635 |
\begin{codeenv} |
| 15636 |
\ics{backmatter} |
| 15637 |
\ics{GlsXtrSetDefaultNumberFormat}\marg{\encap{glsignore}} |
| 15638 |
\end{codeenv} |
| 15639 |
If you also want to drop front matter \glspl{location} as well: |
| 15640 |
\begin{codeenv} |
| 15641 |
\ics{frontmatter} |
| 15642 |
\cs{GlsXtrSetDefaultNumberFormat}\marg{\encap{glsignore}} |
| 15643 |
\ldots |
| 15644 |
\ics{mainmatter} |
| 15645 |
\cs{GlsXtrSetDefaultNumberFormat}\marg{\encap{glsnumberformat}} |
| 15646 |
\ldots |
| 15647 |
\cs{backmatter} |
| 15648 |
\cs{GlsXtrSetDefaultNumberFormat}\marg{\encap{glsignore}} |
| 15649 |
\end{codeenv} |
| 15650 |
|
| 15651 |
Note that \idx{explicit-range} formations aren't discarded, so if |
| 15652 |
\encap{glsignore} is used in a \idx{range}, such as: |
| 15653 |
\begin{codeenv} |
| 15654 |
\ics{glsadd}\oarg{\glsopt[\idx{openrange}\encap{glsignore}]{format}}\marg{sample} |
| 15655 |
\ldots |
| 15656 |
\cs{glsadd}\oarg{\glsopt[\idx{closerange}\encap{glsignore}]{format}}\marg{sample} |
| 15657 |
\end{codeenv} |
| 15658 |
then the \idx{range} will be included in the \gls{locationlist} (encapsulated |
| 15659 |
with \ics{glsignore}), but this case would be a rather odd use of |
| 15660 |
this special format and is not recommended. |
| 15661 |
|
| 15662 |
The \gls{record} counting commands, such as \gls{rgls}, use the special |
| 15663 |
format \encap{glstriggerrecordformat}, which \bibgls\ also treats |
| 15664 |
as an \igls{ignoredrecord} and the same rules as for \encap{glsignore} apply. |
| 15665 |
|
| 15666 |
The \glspl{location} are always listed in the order in which they were indexed, |
| 15667 |
(except for the cross-reference which may be placed at the start or |
| 15668 |
end of the list or omitted). |
| 15669 |
This is different to \idx!{xindy} and \idx!{makeindex} where you can |
| 15670 |
specify the ordering (such as \idx!{lowercase} Roman first, then digits, |
| 15671 |
etc), but unlike those applications, \bibgls\ allows any \gls{location}, |
| 15672 |
although it may not be able to work out an integer representation. |
| 15673 |
(With \idx!{xindy}, you can define new \gls{location} formats, but you need |
| 15674 |
to remember to add the appropriate code to the custom module.) |
| 15675 |
|
| 15676 |
It's possible to define a custom glossary style where |
| 15677 |
\ics{glossentry} (and the \child\ form \ics{subglossentry}) ignore the |
| 15678 |
final argument (which will be the \field{location} field) |
| 15679 |
and instead parse the \field{loclist} field and re-order the |
| 15680 |
\glspl{location} or process them in some other way. Remember that you can |
| 15681 |
also use \ics{glsnoidxloclist} |
| 15682 |
provided by \styfmt{glossaries}. For example: |
| 15683 |
\begin{codeenv} |
| 15684 |
\cs{glsfieldfetch}\marg{gls.sample}\marg{loclist}\marg{\cmd{loclist}}\comment{fetch location list} |
| 15685 |
\cs{glsnoidxloclist}\marg{\cmd{loclist}}\comment{iterate over locations} |
| 15686 |
\end{codeenv} |
| 15687 |
This uses \ics{glsnoidxloclisthandler} as the list's \idx{handler} |
| 15688 |
macro, which simply displays each \gls{location} separated by \ics{delimN}. |
| 15689 |
(See also |
| 15690 |
\href{http://www.dickimaw-books.com/latex/admin/html/foreachtips.shtml}{Iteration |
| 15691 |
Tips and Tricks}~\cite{iterationtips}.) |
| 15692 |
|
| 15693 |
Each regular \gls{location} is listed in the \iext{aux} file in the form: |
| 15694 |
\nosecdef{glsxtr@record} |
| 15695 |
(See \longarg{merge-nameref-on} for \code{nameref} records.) |
| 15696 |
Exact duplicates are discarded. For example, if \code{cat} |
| 15697 |
is indexed twice on page 1: |
| 15698 |
\begin{codeenv} |
| 15699 |
\gls{glsxtr@record}\marg{cat}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1} |
| 15700 |
\gls{glsxtr@record}\marg{cat}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1} |
| 15701 |
\end{codeenv} |
| 15702 |
then the second \gls{record} is discarded. Only the first |
| 15703 |
\gls{record} is added to the \gls{locationlist}. |
| 15704 |
|
| 15705 |
Partial duplicates, where all arguments match except for |
| 15706 |
\meta{format}, may be discarded depending on the value |
| 15707 |
of \meta{format}. For example, if page~1 of the document |
| 15708 |
uses \code{\cs{gls}\marg{cat}} and |
| 15709 |
\code{\cs{gls}\oarg{\glsopt[\encap{hyperbf}]{format}}\marg{cat}} |
| 15710 |
then the \ext{aux} file will contain: |
| 15711 |
\begin{codeenv} |
| 15712 |
\gls{glsxtr@record}\marg{cat}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1} |
| 15713 |
\gls{glsxtr@record}\marg{cat}\marg{}\marg{\counter{page}}\marg{\encap{hyperbf}}\marg{1} |
| 15714 |
\end{codeenv} |
| 15715 |
This is a partial \gls{record} match. In this case, \bibgls\ |
| 15716 |
makes the following tests: |
| 15717 |
\begin{itemize} |
| 15718 |
\item If one of the formats includes an \idx{explicit-range} formation marker, the |
| 15719 |
\idx{range} takes precedence. |
| 15720 |
|
| 15721 |
\item If one of the formats is \encap{glsnumberformat} (as in the |
| 15722 |
above example) or an \igls{ignoredrecord} format such as |
| 15723 |
\encap{glsignore}, that format will be skipped. So in the above |
| 15724 |
example, the second \gls{record} will be added to the \gls{locationlist}, but |
| 15725 |
not the first. (A message will only be written to the transcript if |
| 15726 |
the \commonlongarg{debug} switch is used.) The default |
| 15727 |
\encap{glsnumberformat} will take precedence over the |
| 15728 |
\igls{ignoredrecord} formats (\encap{glsignore} and |
| 15729 |
\encap{glstriggerrecordformat}). |
| 15730 |
|
| 15731 |
\item If a mapping has been set with the \longarg{map-format} |
| 15732 |
switch that mapping will be checked. |
| 15733 |
\item Otherwise the duplicate \gls{record} will be discarded with a |
| 15734 |
warning. |
| 15735 |
\end{itemize} |
| 15736 |
|
| 15737 |
The \field{location} field is used to store the formatted |
| 15738 |
\gls{locationlist}. The code for this list is generated by \bibgls\ based on the |
| 15739 |
information provided in the \iext{aux} file, the presence of the |
| 15740 |
\field{see} or \field{seealso} field and the various settings described in this |
| 15741 |
chapter. When you display the glossary using \ics{printunsrtglossary}, |
| 15742 |
if the \field{location} field is present it will be displayed |
| 15743 |
according to the glossary style (and other factors, such as whether the |
| 15744 |
\styopt{nonumberlist} option has been used, either as a package |
| 15745 |
option or supplied in the optional argument of \ics{printunsrtglossary}). |
| 15746 |
For more information on adjusting the formatting see the |
| 15747 |
\styfmt{glossaries}~\cite{glossaries} and |
| 15748 |
\styfmt{glossaries-extra}~\cite{glossaries-extra} user manuals. |
| 15749 |
|
| 15750 |
\optsection{save-locations} |
| 15751 |
|
| 15752 |
This was originally a boolean setting, but as from v3.0 there are |
| 15753 |
additional values. |
| 15754 |
\begin{itemize} |
| 15755 |
\item \optfmt{false}: don't save anything in the \field{location} |
| 15756 |
field; |
| 15757 |
|
| 15758 |
\item \optfmt{true}: save cross-references and all non-ignored |
| 15759 |
locations in the \field{location} field; |
| 15760 |
|
| 15761 |
\item \optfmt{see}: only save cross-references (\field{see}, |
| 15762 |
\field{seealso} and \field{alias}) in the \field{location} field; |
| 15763 |
|
| 15764 |
\item \optfmt{see not also}: only save the \field{see} and |
| 15765 |
\field{alias} cross-references (not \field{seealso}) in the |
| 15766 |
\field{location} field; |
| 15767 |
|
| 15768 |
\item \optfmt{alias only}: only save the \field{alias} |
| 15769 |
cross-references (not \field{see} or \field{seealso}) in the |
| 15770 |
\field{location} field. |
| 15771 |
|
| 15772 |
\end{itemize} |
| 15773 |
|
| 15774 |
By default, the \glspl{location} will be processed and stored in the |
| 15775 |
\field{location} and \field{loclist} fields. However, if you don't |
| 15776 |
want the \glspl{locationlist} (for example, you are using the |
| 15777 |
\styopt{nonumberlist} option or you are using \idx!{xindy} with a |
| 15778 |
custom \gls{location} rule), then there's no need for \bibgls\ to process |
| 15779 |
the \glspl{location}. To switch this function off, just use |
| 15780 |
\csopt[false]{save-locations}. Note that with this setting, if |
| 15781 |
you're not additionally using \idx!{makeindex} or \idx!{xindy}, then |
| 15782 |
the \glspl{location} won't be available even if you don't have the |
| 15783 |
\styopt{nonumberlist} option set. |
| 15784 |
|
| 15785 |
The boolean \field{nonumberlist} key that may be used in |
| 15786 |
\gls{newglossaryentry} can also be used in a \ext{bib} file, but in |
| 15787 |
this case it can't have an empty value. The value must be either |
| 15788 |
\code{true} or \code{false}. If \code{true} then \bibgls\ won't |
| 15789 |
save the \field{location} or \field{loclist} fields, regardless of |
| 15790 |
the \csopt{save-locations} resource option. |
| 15791 |
|
| 15792 |
The \field{nonumberlist} key provided by the base \sty{glossaries} |
| 15793 |
package doesn't represent a real field. The value isn't saved but, |
| 15794 |
if used, it will alter the indexing information that's written to |
| 15795 |
the \idx!{makeindex} or \idx!{xindy} file. It's a little hack to |
| 15796 |
ensure that the \gls{location} is hidden for a specific entry when used |
| 15797 |
with \idx!{makeindex} and \idx!{xindy}. |
| 15798 |
|
| 15799 |
\bibgls\ will look for this key to determine if the \gls{location} should |
| 15800 |
be omitted for the given entry, but it won't write the key to the |
| 15801 |
\ext{glstex} file. |
| 15802 |
|
| 15803 |
\optsection{save-loclist} |
| 15804 |
|
| 15805 |
If you want the \field{location} field but don't need |
| 15806 |
\field{loclist}, you can use \csopt[false]{save-loclist}. |
| 15807 |
This can help to save resources and build time. |
| 15808 |
|
| 15809 |
\optsection{save-primary-locations} |
| 15810 |
|
| 15811 |
A synonym for \csopt{save-principal-locations}. |
| 15812 |
|
| 15813 |
\optsection{save-principal-locations} |
| 15814 |
|
| 15815 |
It's sometimes useful to identify a \igls{principallocation} with a different |
| 15816 |
format, such as bold or italic. This helps the reader select which |
| 15817 |
\gls{location} to try first in the event of a long \gls{locationlist}. However, |
| 15818 |
you may prefer to store the \glspl{principallocation} in a different field to |
| 15819 |
give it a more prominent position. In order to do this you |
| 15820 |
need to specify the format (or formats) used to identify |
| 15821 |
\glspl{principallocation} with \csopt{principal-location-formats} and |
| 15822 |
use \csopt{save-principal-locations} to determine how to deal with |
| 15823 |
these \glspl{location}. |
| 15824 |
|
| 15825 |
This option may take one of the following values: |
| 15826 |
\begin{itemize} |
| 15827 |
\item \optfmt{false}: don't save \glspl{principallocation} (default); |
| 15828 |
|
| 15829 |
\item \optfmt{retain}: save \glspl{principallocation} in the |
| 15830 |
\field{primarylocations} field but don't remove from the usual |
| 15831 |
\igls{locationlist}; |
| 15832 |
|
| 15833 |
\item \optfmt{default format}: similar to \optfmt{retain} but the |
| 15834 |
format for the \glsdisp{principallocation}{principal records} in the |
| 15835 |
\field{location} field is converted to the default |
| 15836 |
\encap{glsnumberformat} \idx{encap} (the \glspl{record} in the |
| 15837 |
\field{primarylocations} field retain their given format); |
| 15838 |
|
| 15839 |
\item \optfmt{start}: save \glspl{principallocation} in the |
| 15840 |
\field{primarylocations} field and also move to the start of the |
| 15841 |
usual \igls{locationlist}; |
| 15842 |
|
| 15843 |
\item \optfmt{remove}: save \glspl{principallocation} in the |
| 15844 |
\field{primarylocations} field and remove from the usual |
| 15845 |
\igls{locationlist}. You may want to consider using the |
| 15846 |
\longarg{retain-formats} switch with this setting if you don't |
| 15847 |
want to lose a partial \gls{location} match (for example, if the |
| 15848 |
\gls{principallocation} coincides with the start of an |
| 15849 |
\idx{explicit-range}). |
| 15850 |
|
| 15851 |
\end{itemize} |
| 15852 |
|
| 15853 |
The \glspl{principallocation} are copied to the \field{primarylocations} |
| 15854 |
field and are either encapsulated with \gls!{bibglsprimary} or can |
| 15855 |
be split into groups, according to \csopt{principal-loc-counters}. |
| 15856 |
|
| 15857 |
If you use \csopt[remove]{save-principal-locations}, the |
| 15858 |
\field{location} field will end up empty if the \glspl{location} for the |
| 15859 |
associated entry were all identified as principal. If you use |
| 15860 |
\csopt[start]{save-principal-locations}, all |
| 15861 |
\glspl{principallocation} will be |
| 15862 |
moved to the start of the \igls{locationlist} stored in the |
| 15863 |
\field{location} field, but there will be no additional markup |
| 15864 |
(other than the given format) to identify them. If you need |
| 15865 |
additional markup, then use \csopt[remove]{save-principal-locations} |
| 15866 |
and adjust the \igls{locationlist} format to insert the |
| 15867 |
\glspl{principallocation} at the start. This can be done by modifying the glossary |
| 15868 |
style. |
| 15869 |
|
| 15870 |
For example, the \glostyle{bookindex} style inserts |
| 15871 |
\ics{glsxtrbookindexprelocation} before the \gls{location}, so you could |
| 15872 |
redefine this: |
| 15873 |
\begin{codeenv} |
| 15874 |
\cs{renewcommand}*\marg{\cs{glsxtrbookindexprelocation}}[1]\marg{\comment{} |
| 15875 |
\cs{glsxtrifhasfield}\marg{primarylocations}\marg{\idx{param}1}\comment{} |
| 15876 |
\marg{\comment{} |
| 15877 |
\ics{glsxtrprelocation} |
| 15878 |
\cs{glscurrentfieldvalue} |
| 15879 |
\cs{glsxtrifhasfield}\marg{location}\marg{\idx{param}1}\marg{;}\marg{}\comment{} |
| 15880 |
}\comment{} |
| 15881 |
\marg{}\comment{} |
| 15882 |
\cs{glsxtrprelocation} |
| 15883 |
} |
| 15884 |
\end{codeenv} |
| 15885 |
(Note that if \csopt{loc-prefix} is used, the prefix will be |
| 15886 |
in the \field{location} field and so will come after the |
| 15887 |
\glspl{principallocation} in the above example. Similarly for cross-references |
| 15888 |
unless they've been omitted.) |
| 15889 |
|
| 15890 |
You can switch from using the \field{location} field to the |
| 15891 |
\field{primarylocations} field by locally changing |
| 15892 |
\ics{GlsXtrLocationField}: |
| 15893 |
\begin{codeenv} |
| 15894 |
\cs{printunsrtglossary*}\marg{\comment{} |
| 15895 |
\cs{renewcommand}\marg{\cs{GlsXtrLocationField}}\marg{primarylocations}\comment{} |
| 15896 |
} |
| 15897 |
\end{codeenv} |
| 15898 |
Remember that the \idx{handler} used by \cs{printunsrtglossary} will |
| 15899 |
fallback on the \field{loclist} field if the field identified |
| 15900 |
by \cs{GlsXtrLocationField} is missing or empty. You may want to |
| 15901 |
consider using \csopt[false]{save-loclist} to prevent this. |
| 15902 |
|
| 15903 |
\optsection{primary-location-formats} |
| 15904 |
|
| 15905 |
A synonym for \csopt{principal-location-formats}. |
| 15906 |
|
| 15907 |
\optsection{principal-location-formats} |
| 15908 |
|
| 15909 |
This option will automatically set |
| 15910 |
\csopt[retain]{save-principal-locations} unless it has already been |
| 15911 |
changed from the default \csopt[false]{save-principal-locations} |
| 15912 |
setting. The argument should be a comma-separated list of |
| 15913 |
formats. If a record's format is contained in this list then it will |
| 15914 |
be considered a \igls{principallocation} and it will be included in the |
| 15915 |
associated entry's \field{primarylocations} field. |
| 15916 |
|
| 15917 |
For example, suppose the file \filefmt{entries.bib} contains: |
| 15918 |
\begin{codeenv} |
| 15919 |
\atentry{entry}\marg{bird, |
| 15920 |
\field{name}=\marg{bird}, |
| 15921 |
\field{description}=\marg{feathered animal} |
| 15922 |
} |
| 15923 |
\atentry{entry}\marg{waterfowl, |
| 15924 |
\field{name}=\marg{waterfowl}, |
| 15925 |
\field{description}=\marg{any bird that lives in or about water} |
| 15926 |
} |
| 15927 |
\atentry{entry}\marg{zebra, |
| 15928 |
\field{name}=\marg{zebra}, |
| 15929 |
\field{description}=\marg{striped African horse} |
| 15930 |
} |
| 15931 |
\atentry{entry}\marg{parrot, |
| 15932 |
\field{name}=\marg{parrot}, |
| 15933 |
\field{description}=\marg{mainly tropical bird with bright plumage} |
| 15934 |
} |
| 15935 |
\end{codeenv} |
| 15936 |
and the document \filefmt{test.tex} contains: |
| 15937 |
\begin{codeenv} |
| 15938 |
\cmd{documentclass}\marg{report} |
| 15939 |
\strut |
| 15940 |
\cmd{usepackage}\oarg{colorlinks}\marg{hyperref} |
| 15941 |
\cmd{usepackage}\oarg{\styopt{record}, |
| 15942 |
\styopt[dot]{postpunc}, |
| 15943 |
\styopt{nostyles}, |
| 15944 |
\styopt[tree,bookindex]{stylemods}, |
| 15945 |
\styopt[bookindex]{style}}\marg{glossaries-extra} |
| 15946 |
\strut |
| 15947 |
\gls{GlsXtrLoadResources}\oarg{ |
| 15948 |
\csopt[entries]{src}, |
| 15949 |
\csopt[hyperbf,hyperemph]{principal-location-formats}, |
| 15950 |
\csopt[remove]{save-principal-locations} |
| 15951 |
} |
| 15952 |
\strut |
| 15953 |
\cmd{renewcommand}*\marg{\cs{glsxtrbookindexprelocation}}[1]\marg{\comment{} |
| 15954 |
\cs{glsxtrifhasfield}\marg{\field{primarylocations}}\marg{\idx{param}1}\comment{} |
| 15955 |
\marg{\comment{} |
| 15956 |
\ics{glsxtrprelocation} |
| 15957 |
\cs{glscurrentfieldvalue} |
| 15958 |
\cs{glsxtrifhasfield}\marg{\field{location}}\marg{\idx{param}1}\marg{;}\marg{}\comment{} |
| 15959 |
}\comment{} |
| 15960 |
\marg{}\comment{} |
| 15961 |
\cs{glsxtrprelocation} |
| 15962 |
} |
| 15963 |
\strut |
| 15964 |
\gls{glsxtrnewglslike}\oarg{\glsopt[\encap{hyperbf}]{format}}\marg{}\marg{\cmd{primary}}\marg{\cmd{primarypl}}\marg{\cmd{Primary}}\marg{\cmd{Primarypl}} |
| 15965 |
\strut |
| 15966 |
\cmd{begin}\marg{document} |
| 15967 |
\cmd{chapter}\marg{Sample} |
| 15968 |
\cmd{Primary}\marg{waterfowl}, \cs{gls}\marg{bird} and \cs{gls}\marg{zebra}. |
| 15969 |
\strut |
| 15970 |
\cmd{chapter}\marg{Another Sample} |
| 15971 |
\cs{Gls}\marg{waterfowl}, \cmd{primary}\marg{bird} and \cs{gls}\marg{zebra}. |
| 15972 |
\strut |
| 15973 |
\cmd{chapter}\marg{Yet Another Sample} |
| 15974 |
\cs{Gls}\marg{waterfowl}, \cs{gls}\marg{bird} and \cmd{primary}\marg{zebra}. |
| 15975 |
\strut |
| 15976 |
\cmd{chapter}\marg{Yet Another Sample Again} |
| 15977 |
\cs{Gls}\marg{waterfowl}, \cs{gls}\marg{bird}, \cmd{primarypl}\marg{parrot} and \cs{gls}\marg{zebra}. |
| 15978 |
\strut |
| 15979 |
\ics{printunsrtglossary*}\oarg{\printglossopt[\iglostyle{tree}]{style},\printglossopt{nonumberlist}}\marg{\comment{} |
| 15980 |
\cmd{renewcommand}*\marg{\ics{glsextrapostnamehook}}[1]\marg{\ics{glsadd}\oarg{\glsopt[\encap{hyperemph}]{format}}\marg{\idx{param}1}}\comment{} |
| 15981 |
} |
| 15982 |
\strut |
| 15983 |
\cs{printunsrtglossary}\oarg{\printglossopt[Index]{title},\printglossopt[false]{target}} |
| 15984 |
\cmd{end}\marg{document} |
| 15985 |
\end{codeenv} |
| 15986 |
|
| 15987 |
The \csopt[\encap{hyperbf},\encap{hyperemph}]{principal-location-formats} |
| 15988 |
setting in the above indicates that \glspl{location} encapsulated with |
| 15989 |
\ics{hyperbf} and \ics{hyperemph} are |
| 15990 |
\glsdisp{principallocation}{principal records}. In this case, the |
| 15991 |
bold format is used to indicate the \gls{principallocation} in the |
| 15992 |
main document text and the emphasized format is used to indicate the |
| 15993 |
\gls{location} in the \gls{mainglossary}. |
| 15994 |
|
| 15995 |
The \glsdisp{principallocation}{principal records} are removed from |
| 15996 |
the \field{location} field due to the |
| 15997 |
\csopt[remove]{save-principal-locations} setting. This can lead to a |
| 15998 |
ragged \gls{locationlist}. The option \csopt[default |
| 15999 |
format]{save-principal-locations} can allow the |
| 16000 |
\gls{principallocation} to be absorbed into a \idx{range}. |
| 16001 |
|
| 16002 |
The \gls{mainglossary} records are added through the category-independent post-name |
| 16003 |
hook with \cs{glsadd}. This won't be implemented until the entries are actually |
| 16004 |
defined as the page number can't be determined until the glossary can be |
| 16005 |
displayed. This means that the document build requires an extra \bibgls\ and |
| 16006 |
\LaTeX\ run: |
| 16007 |
\begin{verbatim} |
| 16008 |
pdflatex test |
| 16009 |
bib2gls --group test |
| 16010 |
pdflatex test |
| 16011 |
bib2gls --group test |
| 16012 |
pdflatex test |
| 16013 |
\end{verbatim} |
| 16014 |
|
| 16015 |
For consistency, I've used \gls{glsxtrnewglslike} to provide commands |
| 16016 |
used to indicate a principal reference in the text. This means that if |
| 16017 |
I decide to change the optional arguments used for principal |
| 16018 |
references I only need to edit one line. For example, I might want to |
| 16019 |
change the default counter: |
| 16020 |
\begin{codeenv} |
| 16021 |
\gls{glsxtrnewglslike}\oarg{\glsopt[\encap{hyperbf}]{format},\glsopt[\counter{chapter}]{counter}}\marg{}\marg{\cmd{primary}}\marg{\cmd{primarypl}}\marg{\cmd{Primary}}\marg{\cmd{Primarypl}} |
| 16022 |
\end{codeenv} |
| 16023 |
|
| 16024 |
Here's another example that only has one principal format (\encap{hyperrm}) |
| 16025 |
that's indexed through the use of \ics{GlsXtrAutoAddOnFormat}, which sets |
| 16026 |
up a hook that automatically inserts: |
| 16027 |
\begin{codeenv*} |
| 16028 |
\ics{glsadd}\oarg{\glsaddopt[\counter{chapter}]{counter},\glsaddopt[\encap{hyperrm}]{format}}\margm{label} |
| 16029 |
\end{codeenv*} |
| 16030 |
on each instance of \code{\cs{gls}\oarg{\glsopt[primaryfmt]{format}}\margm{label}} (or |
| 16031 |
similar). This means that the entry is indexed twice when this particular |
| 16032 |
format is used: first with the \encap{hyperrm} format and \counter{chapter} |
| 16033 |
counter (from the \cs{glsadd} command in the hook), and then with the |
| 16034 |
\code{primaryfmt} format and the default counter (as per normal behaviour): |
| 16035 |
\begin{codeenv} |
| 16036 |
\cmd{documentclass}\marg{report} |
| 16037 |
\strut |
| 16038 |
\cmd{usepackage}\oarg{colorlinks}\marg{hyperref} |
| 16039 |
\cmd{usepackage}\oarg{ |
| 16040 |
\styopt[nameref]{record}, |
| 16041 |
\styopt[dot]{postpunc}, |
| 16042 |
\styopt{nostyles}, |
| 16043 |
\styopt[tree,bookindex]{stylemods}, |
| 16044 |
\styopt[bookindex]{style}}\marg{glossaries-extra} |
| 16045 |
\strut |
| 16046 |
\gls{GlsXtrLoadResources}\oarg{ |
| 16047 |
\csopt[topics]{src}, |
| 16048 |
\csopt[hyperrm]{principal-location-formats}, |
| 16049 |
\csopt[remove]{save-principal-locations}, |
| 16050 |
\csopt[false]{save-loclist} |
| 16051 |
} |
| 16052 |
\strut |
| 16053 |
\cmd{newcommand}\marg{\cmd{primaryfmt}}\oarg{1}\marg{\cs{hyperbf}\marg{\idx{param}1}} |
| 16054 |
\strut |
| 16055 |
\ics{GlsXtrAutoAddOnFormat}\marg{primaryfmt}\marg{\glsaddopt[\counter{chapter}]{counter},\glsaddopt[\encap{hyperrm}]{format}} |
| 16056 |
\strut |
| 16057 |
\gls{glsxtrnewglslike}\oarg{\glsaddopt[primaryfmt]{format}}\marg{}\marg{\cmd{primary}}\marg{\cmd{primarypl}}\marg{\cmd{Primary}}\marg{\cmd{Primarypl}} |
| 16058 |
\strut |
| 16059 |
\cmd{begin}\marg{document} |
| 16060 |
\cmd{chapter}\marg{Sample} |
| 16061 |
\cmd{Primary}\marg{waterfowl}, \cs{gls}\marg{bird} and \cs{gls}\marg{zebra}. |
| 16062 |
\strut |
| 16063 |
\cmd{chapter}\marg{Another Sample} |
| 16064 |
\cs{Gls}\marg{waterfowl}, \cmd{primary}\marg{bird} and \cs{gls}\marg{zebra}. |
| 16065 |
\strut |
| 16066 |
\cmd{chapter}\marg{Yet Another Sample} |
| 16067 |
\cs{Gls}\marg{waterfowl}, \cs{gls}\marg{bird} and \cmd{primary}\marg{zebra}. |
| 16068 |
\strut |
| 16069 |
\cmd{chapter}\marg{Yet Another Sample Again} |
| 16070 |
\cs{Gls}\marg{waterfowl}, \cs{gls}\marg{bird}, \cmd{primarypl}\marg{parrot} and \cs{gls}\marg{zebra}. |
| 16071 |
\strut |
| 16072 |
\ics{printunsrtglossary*}\oarg{\printglossopt[\glostyle{tree}]{style},\printglossopt[Summary]{title}}\marg{\comment{} |
| 16073 |
\cmd{renewcommand}*\marg{\ics{glsextrapostnamehook}}[1]\marg{\ics{glsadd}\oarg{\glsaddopt[\encap{hyperemph}]{format}}\marg{\idx{param}1}}\comment{} |
| 16074 |
\cmd{renewcommand}\marg{\ics{GlsXtrLocationField}}\marg{\field{primarylocations}}\comment{} |
| 16075 |
} |
| 16076 |
\strut |
| 16077 |
\cs{printunsrtglossary}\oarg{\printglossopt[Index]{title},\printglossopt[false]{target}} |
| 16078 |
\cmd{end}\marg{document} |
| 16079 |
\end{codeenv} |
| 16080 |
|
| 16081 |
Note that in this case, from \bibgls' point of view, the principal |
| 16082 |
format is \encap{hyperrm} not \code{primaryfmt}. This picks out the |
| 16083 |
records created with the automated \ics{glsadd}, which have the |
| 16084 |
counter set to \counter{chapter}. The first glossary (with the |
| 16085 |
title \qt{Summary}) switches the location field to |
| 16086 |
\field{primarylocations} so that only the |
| 16087 |
\glsdisp{principallocation}{principal records} are listed. Since |
| 16088 |
\styopt[nameref]{record} has been used this means that the chapter |
| 16089 |
title is shown rather than the chapter number. |
| 16090 |
|
| 16091 |
The second glossary (\qt{Index}) shows the \glspl{locationlist} that |
| 16092 |
only have the \counter{page} counter (because the automated |
| 16093 |
\cs{glsadd} records with the \counter{chapter} counter have been |
| 16094 |
removed because they were identified as |
| 16095 |
\glsdisp{principallocation}{principal records}). These just show the |
| 16096 |
page number as that's the default display with |
| 16097 |
\styopt[nameref]{record} for records with the \counter{page} |
| 16098 |
counter. |
| 16099 |
|
| 16100 |
An alternative to \ics{GlsXtrAutoAddOnFormat} would be to simply |
| 16101 |
define the custom commands as follows: |
| 16102 |
\begin{codeenv} |
| 16103 |
\cmd{newcommand}\marg{\cmd{primary}}[2][]\marg{\comment{} |
| 16104 |
\cs{glsadd}\oarg{\glsaddopt[\counter{chapter}]{counter},\glsaddopt[\encap{hyperrm}]{format}}\marg{\idx{param}2}\comment{} |
| 16105 |
\cs{gls}\oarg{\glsopt[primaryfmt]{format},\idx{param}1}\marg{\idx{param}2}\comment{} |
| 16106 |
} |
| 16107 |
\cmd{newcommand}\marg{\cmd{primarypl}}[2][]\marg{\comment{} |
| 16108 |
\cs{glsadd}\oarg{\glsaddopt[\counter{chapter}]{counter},\glsaddopt[\encap{hyperrm}]{format}}\marg{\idx{param}2}\comment{} |
| 16109 |
\cs{glspl}\oarg{\glsopt[primaryfmt]{format},\idx{param}1}\marg{\idx{param}2}\comment{} |
| 16110 |
} |
| 16111 |
\cmd{newcommand}\marg{\cmd{Primary}}[2][]\marg{\comment{} |
| 16112 |
\cs{glsadd}\oarg{\glsaddopt[\counter{chapter}]{counter},\glsaddopt[\encap{hyperrm}]{format}}\marg{\idx{param}2}\comment{} |
| 16113 |
\cs{Gls}\oarg{\glsopt[primaryfmt]{format},\idx{param}1}\marg{\idx{param}2}\comment{} |
| 16114 |
} |
| 16115 |
\cmd{newcommand}\marg{\cmd{Primarypl}}[2][]\marg{\comment{} |
| 16116 |
\cs{glsadd}\oarg{\glsaddopt[\counter{chapter}]{counter},\glsaddopt[\encap{hyperrm}]{format}}\marg{\idx{param}2}\comment{} |
| 16117 |
\cs{Glspl}\oarg{\glsopt[primaryfmt]{format},\idx{param}1}\marg{\idx{param}2}\comment{} |
| 16118 |
} |
| 16119 |
\end{codeenv} |
| 16120 |
This is more useful if you want to simply omit the |
| 16121 |
\code{\glsopt[primaryfmt]{format}} option (just remove it from the above four |
| 16122 |
definitions), which makes it easier to merge the \glspl{location} into |
| 16123 |
\idxpl{range} in the index. |
| 16124 |
|
| 16125 |
\optsection{primary-loc-counters} |
| 16126 |
|
| 16127 |
A synonym for \csopt{principal-loc-counters}. |
| 16128 |
|
| 16129 |
\optsection{principal-loc-counters} |
| 16130 |
|
| 16131 |
This option determines whether the \glspl{principallocation} should |
| 16132 |
be split into groups according to the location counter. The value |
| 16133 |
may be one or: |
| 16134 |
\begin{itemize} |
| 16135 |
\item \optfmt{combine}: don't split into groups (default); |
| 16136 |
\item \optfmt{match}: match the \csopt{loc-counters} setting; |
| 16137 |
\item \optfmt{split}: split into groups regardless of the |
| 16138 |
\csopt{loc-counters} setting. |
| 16139 |
\end{itemize} |
| 16140 |
|
| 16141 |
With \csopt[combine]{principal-loc-counters} or with |
| 16142 |
\csopt[match]{principal-loc-counters} and the default \csopt[as |
| 16143 |
use]{loc-counters} settings, no groups will be formed and the |
| 16144 |
\glspl{principallocation} will be encapsulated with |
| 16145 |
\gls{bibglsprimary}. Otherwise, the locations will be split into |
| 16146 |
groups according to the counter and each group will be encapsulated |
| 16147 |
with \gls{bibglsprimarylocationgroup} and separated with |
| 16148 |
\gls{bibglsprimarylocationgroupsep}. |
| 16149 |
|
| 16150 |
For example, suppose the file \filefmt{topics.bib} contains the |
| 16151 |
following entry: |
| 16152 |
\begin{codeenv} |
| 16153 |
\atentry{entry}\marg{zebra, |
| 16154 |
\field{name}=\marg{zebra}, |
| 16155 |
\field{description}=\marg{striped African horse} |
| 16156 |
} |
| 16157 |
\end{codeenv} |
| 16158 |
The document sets up a \gls{principallocation} format identified by |
| 16159 |
the custom command \csfmt{primaryfmt}: |
| 16160 |
\begin{codeenv} |
| 16161 |
\cs{newcommand}\marg{\cmd{primaryfmt}}[1]\marg{\cs{hyperbf}\marg{\idx{param}1}} |
| 16162 |
\end{codeenv} |
| 16163 |
The \ics{GlsXtrAutoAddOnFormat} command is used to automatically |
| 16164 |
record an entry with the \counter{chapter} counter (using |
| 16165 |
\ics{glsadd}) every time the entry is |
| 16166 |
recorded with the \gls{principallocation} format: |
| 16167 |
\begin{codeenv} |
| 16168 |
\cs{GlsXtrAutoAddOnFormat}\marg{primaryfmt}\marg{\glsopt{counter}=\counter{chapter},\glsopt{format}=primaryfmt} |
| 16169 |
\end{codeenv} |
| 16170 |
This means that, for example, |
| 16171 |
\begin{codeenv} |
| 16172 |
\cs{gls}\oarg{\glsopt{format}=primaryfmt}\margm{zebra} |
| 16173 |
\end{codeenv} |
| 16174 |
will also first do: |
| 16175 |
\begin{codeenv} |
| 16176 |
\cs{glsadd}\oarg{\glsopt{counter}=\counter{chapter},\glsopt{format}=primaryfmt}\margm{zebra} |
| 16177 |
\end{codeenv} |
| 16178 |
|
| 16179 |
If \idx{resourceset} is loaded with: |
| 16180 |
\begin{codeenv} |
| 16181 |
\gls{GlsXtrLoadResources}\oarg{\csopt[topics]{src}, |
| 16182 |
\csopt[primaryfmt]{primary-location-formats}, |
| 16183 |
\csopt[retain]{save-primary-locations} |
| 16184 |
} |
| 16185 |
\end{codeenv} |
| 16186 |
then both the \field{location} field and the |
| 16187 |
\field{primarylocations} field will include both the \counter{page} |
| 16188 |
and \counter{chapter} records mixed together. The |
| 16189 |
\field{primarylocations} field will have the locations encapsulated |
| 16190 |
with \gls{bibglsprimary}. |
| 16191 |
|
| 16192 |
With |
| 16193 |
\begin{codeenv} |
| 16194 |
\gls{GlsXtrLoadResources}\oarg{\csopt[topics]{src}, |
| 16195 |
\csopt[primaryfmt]{primary-location-formats}, |
| 16196 |
\csopt[retain]{save-primary-locations}, |
| 16197 |
\csopt[split]{primary-loc-counters} |
| 16198 |
} |
| 16199 |
\end{codeenv} |
| 16200 |
the \field{primarylocations} field will have the locations split into |
| 16201 |
two groups, each encapsulated with \gls{bibglsprimarylocationgroup}. |
| 16202 |
The \field{location} field will have the \counter{chapter} and |
| 16203 |
\counter{page} locations intermingled. |
| 16204 |
|
| 16205 |
With |
| 16206 |
\begin{codeenv} |
| 16207 |
\gls{GlsXtrLoadResources}\oarg{\csopt[topics]{src}, |
| 16208 |
\csopt[primaryfmt]{primary-location-formats}, |
| 16209 |
\csopt[retain]{save-primary-locations}, |
| 16210 |
\csopt[split]{primary-loc-counters}, |
| 16211 |
\csopt[page]{loc-counters} |
| 16212 |
} |
| 16213 |
\end{codeenv} |
| 16214 |
The \field{primarylocations} field will be the same as before, but |
| 16215 |
the \field{location} field will only have the \counter{page} |
| 16216 |
locations. |
| 16217 |
|
| 16218 |
Whereas with |
| 16219 |
\begin{codeenv} |
| 16220 |
\gls{GlsXtrLoadResources}\oarg{\csopt[topics]{src}, |
| 16221 |
\csopt[primaryfmt]{primary-location-formats}, |
| 16222 |
\csopt[retain]{save-primary-locations}, |
| 16223 |
\csopt[match]{primary-loc-counters}, |
| 16224 |
\csopt[page]{loc-counters} |
| 16225 |
} |
| 16226 |
\end{codeenv} |
| 16227 |
Both the \field{primarylocations} field and the \field{location} |
| 16228 |
field will only have the \counter{page} locations. |
| 16229 |
|
| 16230 |
The order of the groups depends on whether \optfmt{split} or |
| 16231 |
\optfmt{match} is used. With \csopt[match]{primary-loc-counters} the |
| 16232 |
counter group order will match \csopt{loc-counters}. Whereas with |
| 16233 |
\csopt[split]{primary-loc-counters} the counter group order will be determined by |
| 16234 |
the order of records. |
| 16235 |
|
| 16236 |
So in the case of the above document where the \counter{chapter} |
| 16237 |
record is automatically added before the \counter{page} record |
| 16238 |
(where the \glsopt{format} is \code{primaryfmt}) then with: |
| 16239 |
\begin{codeenv} |
| 16240 |
\gls{GlsXtrLoadResources}\oarg{\csopt[topics]{src}, |
| 16241 |
\csopt[primaryfmt]{primary-location-formats}, |
| 16242 |
\csopt[retain]{save-primary-locations}, |
| 16243 |
\csopt[match]{primary-loc-counters}, |
| 16244 |
\csopt[page,chapter]{loc-counters} |
| 16245 |
} |
| 16246 |
\end{codeenv} |
| 16247 |
then both the \field{location} field and the |
| 16248 |
\field{primarylocations} field will have the \counter{page} group |
| 16249 |
first, followed by the \counter{chapter} group. Whereas with: |
| 16250 |
\begin{codeenv} |
| 16251 |
\gls{GlsXtrLoadResources}\oarg{\csopt[topics]{src}, |
| 16252 |
\csopt[primaryfmt]{primary-location-formats}, |
| 16253 |
\csopt[retain]{save-primary-locations}, |
| 16254 |
\csopt[skip]{primary-loc-counters}, |
| 16255 |
\csopt[page,chapter]{loc-counters} |
| 16256 |
} |
| 16257 |
\end{codeenv} |
| 16258 |
then the \field{primarylocations} field will have the |
| 16259 |
\counter{chapter} group first, followed by the \counter{page} group. |
| 16260 |
|
| 16261 |
\optsection{merge-ranges} |
| 16262 |
|
| 16263 |
This boolean option determines whether or not \idxpl{explicit-range} should |
| 16264 |
merge with neighbouring \glspl{location} on either side of the |
| 16265 |
\idx{range}. The default setting is \csopt[false]{merge-ranges}. |
| 16266 |
|
| 16267 |
Note that \gls{bibglsrange} won't be used with |
| 16268 |
\csopt[true]{merge-ranges}, regardless of whether or not the \idx{range} |
| 16269 |
was merged with neighbouring \glspl{location}. Options such as |
| 16270 |
\csopt{min-loc-range}, \csopt{suffixF} and \csopt{suffixFF} |
| 16271 |
won't have an effect on the merged range, but |
| 16272 |
will still effect \idxpl{implicit-range} that haven't been merged with an |
| 16273 |
\idx{explicit-range}. |
| 16274 |
|
| 16275 |
Regardless of the value of this option, \idxpl{interloper} will still be |
| 16276 |
moved to the start of the \idx{range} and encapsulated with |
| 16277 |
\gls{bibglsinterloper}. |
| 16278 |
|
| 16279 |
\optsection{min-loc-range} |
| 16280 |
|
| 16281 |
By default, three or more consecutive \glspl{location} \meta{loc-1}, |
| 16282 |
\meta{loc-2}, \ldots, \meta{loc-n} are compressed into |
| 16283 |
the \idx{range} \code{\meta{loc-1}\ics{delimR} \meta{loc-n}} |
| 16284 |
(an \idx{implicit-range}). Otherwise |
| 16285 |
the \glspl{location} are separated by \gls!{bibglsdelimN} or \gls!{bibglslastDelimN}. |
| 16286 |
As mentioned above, these aren't merged with \idx{explicit-range} |
| 16287 |
formations unless \csopt[true]{merge-ranges}. |
| 16288 |
|
| 16289 |
You can change how many consecutive \glspl{location} are need to |
| 16290 |
form an \idx{implicit-range} with the \csopt{min-loc-range} setting where |
| 16291 |
\meta{value} is either \optfmt{none} (don't form ranges) or an |
| 16292 |
integer greater than one indicating how many consecutive |
| 16293 |
\glspl{location} should be converted into a \idx{range}. |
| 16294 |
|
| 16295 |
\bibgls\ determines if one \gls{location} |
| 16296 |
\code{\margm{prefix-2}\margm{counter-2}\margm{format-2}\margm{location-2}} |
| 16297 |
is one unit more than another \gls{location} |
| 16298 |
\code{\margm{prefix-1}\margm{counter-1}\margm{format-1}\margm{location-1} } |
| 16299 |
according to the following: |
| 16300 |
\begin{enumerate} |
| 16301 |
\item\label{itm:pre} If \meta{prefix-1} is not equal to \meta{prefix-2} or |
| 16302 |
\meta{counter-1} is not equal to \meta{counter-2} or \meta{format-1} |
| 16303 |
is not equal to \meta{format-2}, then the \glspl{location} aren't |
| 16304 |
considered consecutive. |
| 16305 |
\item\label{itm:emptyloc} If either \meta{location-1} or \meta{location-2} are empty, |
| 16306 |
then the \glspl{location} aren't considered consecutive. |
| 16307 |
\item\label{itm.csmatch} If both \meta{location-1} and \meta{location-2} match the |
| 16308 |
pattern (line break for clarity only)\footnote{The Java class \code{\csfmt{p}\marg{javaDigit}} |
| 16309 |
used in the \gls{regular-expression} will match any digits in the |
| 16310 |
Unicode \idx{numberdecimaldigit} category not just the digits in the Basic Latin set. Similarly \code{\csfmt{p}\marg{javaAlphabetic}} will also match alphabetic |
| 16311 |
characters outside the Basic Latin set.} |
| 16312 |
\begin{verbatim} |
| 16313 |
(.*?)(?:\\protect\s*)?(\\[\p{javaAlphabetic}@]+)\s*\{([\p{javaDigit} |
| 16314 |
\p{javaAlphabetic}]+)\} |
| 16315 |
\end{verbatim} |
| 16316 |
then: |
| 16317 |
\begin{itemize} |
| 16318 |
\item if the control sequence matched by group 2 isn't the same for |
| 16319 |
both \glspl{location}, the \glspl{location} aren't considered consecutive; |
| 16320 |
\item if the argument of the control sequence (group 3) is the same for |
| 16321 |
both \glspl{location}, then the test is retried with \meta{location-1} |
| 16322 |
set to group 1 of the first pattern match and \meta{location-2} |
| 16323 |
set to group 1 of the second pattern match; |
| 16324 |
\item otherwise the test is retried with \meta{location-1} set to |
| 16325 |
group 3 of the first pattern match and \meta{location-2} set to |
| 16326 |
group 3 of the second pattern match. |
| 16327 |
\end{itemize} |
| 16328 |
\item\label{itm:decmatch} If both \meta{location-1} and \meta{location-2} match the |
| 16329 |
pattern |
| 16330 |
\begin{verbatim} |
| 16331 |
(.*?)([^\p{javaDigit}]?)(\p{javaDigit}+) |
| 16332 |
\end{verbatim} |
| 16333 |
then: |
| 16334 |
\begin{enumerate} |
| 16335 |
\item\label{itm:decgrp3eq} if group 3 of both pattern matches are |
| 16336 |
equal then: |
| 16337 |
\begin{enumerate} |
| 16338 |
\item\label{itm:decgrp3nz} if group 3 isn't zero, the \glspl{location} |
| 16339 |
aren't considered consecutive; |
| 16340 |
\item if the separators (group 2) are different the test is |
| 16341 |
retried with \meta{location-1} set to the concatenation of the first |
| 16342 |
two groups \meta{group-1}\meta{group-2} of the first pattern match |
| 16343 |
and \meta{location-2} set to the concatenation of the first two groups |
| 16344 |
\meta{group-1}\meta{group-2} of the second pattern |
| 16345 |
match; |
| 16346 |
\item\label{itm:decgrp3eqsepeq} if the separators (group 2) are the same the test is |
| 16347 |
retried with \meta{location-1} set to the first |
| 16348 |
group \meta{group-1} of the first pattern match |
| 16349 |
and \meta{location-2} set to the first group |
| 16350 |
\meta{group-1} of the second pattern match. |
| 16351 |
\end{enumerate} |
| 16352 |
\item If \meta{group-1} of the first pattern match (of |
| 16353 |
\meta{location-1}) doesn't equal |
| 16354 |
\meta{group-1} of the second pattern match (of \meta{location-2}) |
| 16355 |
or \meta{group-2} of the first pattern match (of |
| 16356 |
\meta{location-1}) doesn't equal |
| 16357 |
\meta{group-2} of the second pattern match (of \meta{location-2}) |
| 16358 |
then the \glspl{location} aren't considered consecutive; |
| 16359 |
\item\label{itm:decgrp3} If $0 < l_2 - l_1 \leq d $ |
| 16360 |
where $l_2$ is \meta{group 3} of the second pattern match, |
| 16361 |
$l_1$ is \meta{group 3} of the first pattern match and |
| 16362 |
$d$ is the value of \optfmt{max-loc-diff} then the \glspl{location} |
| 16363 |
are consecutive otherwise they're not consecutive. |
| 16364 |
\end{enumerate} |
| 16365 |
\item\label{itm:rommatch} The next pattern matches for \meta{prefix}\meta{sep}\meta{n} |
| 16366 |
where \meta{n} is a \idx!{lowercase} Roman numeral, which is converted to |
| 16367 |
a decimal value and the test is performed in the same way as the |
| 16368 |
above \hyperref[itm:decmatch]{decimal test}. |
| 16369 |
\item\label{itm:Rommatch} The next pattern matches for \meta{prefix}\meta{sep}\meta{n} |
| 16370 |
where \meta{n} is an \idx!{uppercase} Roman numeral, which is converted to |
| 16371 |
a decimal value and the test is performed |
| 16372 |
in the same way as the above \hyperref[itm:decmatch]{decimal test}. |
| 16373 |
\item\label{itm:alphmatch} The next pattern matches for \meta{prefix}\meta{sep}\meta{c} |
| 16374 |
where \meta{c} is either a \idx!{lowercase} letter from \code{a} to |
| 16375 |
\code{z} or an \idx!{uppercase} letter from \code{A} to \code{Z}. |
| 16376 |
The character is converted to its code point and the test is |
| 16377 |
performed in the same way as the \hyperref[itm:decmatch]{decimal pattern} above. |
| 16378 |
\item\label{itm:nomatch} If none of the above, the \gls{location} aren't considered |
| 16379 |
consecutive. |
| 16380 |
\end{enumerate} |
| 16381 |
|
| 16382 |
Examples: |
| 16383 |
\begin{enumerate} |
| 16384 |
\item |
| 16385 |
\begin{codeenv} |
| 16386 |
\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1} |
| 16387 |
\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{2} |
| 16388 |
\end{codeenv} |
| 16389 |
These records are consecutive. The prefix, counter and format are |
| 16390 |
identical (so the test passes step~\ref{itm:pre}), the \glspl{location} match |
| 16391 |
the \hyperref[itm:decmatch]{decimal pattern} and the test in |
| 16392 |
step~\ref{itm:decgrp3} passes. |
| 16393 |
|
| 16394 |
\item |
| 16395 |
\begin{codeenv} |
| 16396 |
\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1} |
| 16397 |
\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{textbf}}\marg{2} |
| 16398 |
\end{codeenv} |
| 16399 |
These records aren't consecutive since the formats are different. |
| 16400 |
|
| 16401 |
\item |
| 16402 |
\begin{codeenv} |
| 16403 |
\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{A.i} |
| 16404 |
\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{A.ii} |
| 16405 |
\end{codeenv} |
| 16406 |
These records are consecutive. The prefix, counter and format are |
| 16407 |
identical (so it passes step~\ref{itm:pre}). The \glspl{location} match |
| 16408 |
the \hyperref[itm:rommatch]{lower case Roman numeral pattern}, where |
| 16409 |
\code{A} is considered a prefix and the dot is consider a |
| 16410 |
separator. The Roman numerals i and ii are converted to decimal and |
| 16411 |
the test is retried with the \glspl{location} set to 1 and 2, respectively. |
| 16412 |
This now passes the decimal pattern test (step~\ref{itm:decgrp3}). |
| 16413 |
|
| 16414 |
\item |
| 16415 |
\begin{codeenv} |
| 16416 |
\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{i.A} |
| 16417 |
\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{ii.A} |
| 16418 |
\end{codeenv} |
| 16419 |
These records aren't consecutive. They match the |
| 16420 |
\hyperref[itm:alphmatch]{alpha pattern}. The first \gls{location} is |
| 16421 |
considered to consist of the prefix \code{i}, the separator |
| 16422 |
\code{.}\ (dot) and the number given by the character code of A. |
| 16423 |
The second \gls{location} is considered to consist of the prefix |
| 16424 |
\code{ii}, the separator \code{.}\ (dot) and the number |
| 16425 |
given by the character code of A. |
| 16426 |
|
| 16427 |
The test fails because the numbers are equal and the prefixes are |
| 16428 |
different. |
| 16429 |
|
| 16430 |
\item |
| 16431 |
\begin{codeenv} |
| 16432 |
\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1.0} |
| 16433 |
\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{2.0} |
| 16434 |
\end{codeenv} |
| 16435 |
These records are consecutive. They match the \hyperref[itm:decmatch]{decimal |
| 16436 |
pattern}, and then step~\ref{itm:decgrp3eq} followed by |
| 16437 |
step~\ref{itm:decgrp3eqsepeq}. The \code{.0} part is discarded and |
| 16438 |
the test is retried with the first \gls{location} set to 1 and the second |
| 16439 |
\gls{location} set to 2. |
| 16440 |
|
| 16441 |
\item |
| 16442 |
\begin{codeenv} |
| 16443 |
\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1.1} |
| 16444 |
\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{2.1} |
| 16445 |
\end{codeenv} |
| 16446 |
These records aren't consecutive as the test branches off into |
| 16447 |
step~\ref{itm:decgrp3nz}. |
| 16448 |
|
| 16449 |
\item |
| 16450 |
\begin{codeenv} |
| 16451 |
\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{\cmd{@alph}\marg{1}} |
| 16452 |
\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{\cmd{@alph}\marg{2}} |
| 16453 |
\end{codeenv} |
| 16454 |
These records are consecutive. The \glspl{location} match the |
| 16455 |
\hyperref[itm.csmatch]{control sequence pattern}. The control |
| 16456 |
sequences are the same, so the test is retried with the first |
| 16457 |
\gls{location} set to 1 and the second \gls{location} set to 2. |
| 16458 |
|
| 16459 |
In this example, the \gls{location} has been written to the file as |
| 16460 |
\code{\csfmt{@alph}\margm{number}} instead of fully expanding according to the |
| 16461 |
normal behaviour of \code{\ics{alph}\margm{counter}}. (Note that |
| 16462 |
\gls!{GlsXtrLoadResources} changes the category code of \code{@} to allow for |
| 16463 |
internal commands in \glspl{location}.) This unusual case is for illustrative purposes. |
| 16464 |
\end{enumerate} |
| 16465 |
|
| 16466 |
\optsection{max-loc-diff} |
| 16467 |
|
| 16468 |
This setting is used to determine whether two \glspl{location} are |
| 16469 |
considered consecutive. |
| 16470 |
The value must be an integer greater than or equal to 1. |
| 16471 |
(The default is \optfmt{1}.) |
| 16472 |
|
| 16473 |
For two \glspl{location}, \meta{location-1} and \meta{location-2}, |
| 16474 |
that have numeric values $n_1$ and $n_2$ (and identical prefix, |
| 16475 |
counter and format), then the sequence \meta{location-1}, |
| 16476 |
\meta{location-2} is considered consecutive if |
| 16477 |
\[ |
| 16478 |
0 < n_2 - n_1 \leq \text{\meta{max-loc-diff}} |
| 16479 |
\] |
| 16480 |
The default value of 1 means that \meta{location-2} immediately |
| 16481 |
follows \meta{location-1} if $n_2 = n_1+1$. |
| 16482 |
|
| 16483 |
For example, if \meta{location-1} is \qt{B} and \meta{location-2} |
| 16484 |
is \qt{C}, then $n_1 = 66$ and $n_2 = 67$. Since $n_2 = 67 = 66+1= |
| 16485 |
n_1+1$ then \meta{location-2} immediately follows \meta{location-1}. |
| 16486 |
|
| 16487 |
This is used in the \idx{implicit-range} formations within |
| 16488 |
the \glspl{locationlist} (as described |
| 16489 |
in the above section). |
| 16490 |
So, for example, the list \qt{1, 2, 3, 5, 7, 8, 10, 11, 12, 58, 59, |
| 16491 |
61} becomes |
| 16492 |
\qt{1--3, 5, 7, 8, 10--12, 58, 59, 61}. |
| 16493 |
|
| 16494 |
The automatically indexing of commands like \ics{gls} means that |
| 16495 |
the \glspl{locationlist} can become long and ragged. You could |
| 16496 |
deal with this by switching off the automatic indexing and |
| 16497 |
only explicitly index pertinent use or you can adjust |
| 16498 |
the value of \optfmt{max-loc-diff} so that a \idx{range} can be formed even |
| 16499 |
if there are one or two gaps in it. |
| 16500 |
By default, any \idxpl{range} that have skipped gaps in this |
| 16501 |
manner will be followed by \gls!{bibglspassim}. The default |
| 16502 |
definition of this command is obtained from the resource file. |
| 16503 |
For English, this is \verb*| passim| (space followed by \qt{passim}). |
| 16504 |
|
| 16505 |
So with the above set of \glspl{location}, if \csopt[2]{max-loc-diff} then |
| 16506 |
the list becomes \qt{1--12 passim, 58--61 passim} which now highlights that |
| 16507 |
there are two blocks within the document related to that |
| 16508 |
term. |
| 16509 |
|
| 16510 |
\optsection{suffixF} |
| 16511 |
|
| 16512 |
If set, an \idx{implicit-range} consisting of two consecutive |
| 16513 |
\glspl{location} \meta{loc-1} and \meta{loc-2} will be displayed in |
| 16514 |
the \gls{locationlist} as \meta{loc-1}\meta{value}. This option |
| 16515 |
doesn't affect \idxpl{explicit-range}, even with |
| 16516 |
\csopt[true]{merge-ranges}. |
| 16517 |
|
| 16518 |
Note that \csopt[\empty]{suffixF} sets the suffix to the |
| 16519 |
empty string. To remove the suffix formation use |
| 16520 |
\csopt[none]{suffixF}. |
| 16521 |
|
| 16522 |
The default is \csopt[none]{suffixF}. |
| 16523 |
|
| 16524 |
\optsection{suffixFF} |
| 16525 |
|
| 16526 |
If set, an \idx{implicit-range} consisting of three or more |
| 16527 |
consecutive \glspl{location} \meta{loc-1} and \meta{loc-2} will be |
| 16528 |
displayed in the \gls{locationlist} as \meta{loc-1}\meta{value}. |
| 16529 |
This option doesn't affect \idxpl{explicit-range}, even with |
| 16530 |
\csopt[true]{merge-ranges}. |
| 16531 |
|
| 16532 |
Note that \csopt[\empty]{suffixFF} sets the suffix to the |
| 16533 |
empty string. To remove the suffix formation use |
| 16534 |
\csopt[none]{suffixFF}. |
| 16535 |
|
| 16536 |
The default is \csopt[none]{suffixFF}. |
| 16537 |
|
| 16538 |
\optsection{compact-ranges} |
| 16539 |
|
| 16540 |
The \meta{value} may be an integer \meta{n} or \optfmt{false} (equivalent to |
| 16541 |
\csopt[0]{compact-ranges}) or \optfmt{true} (equivalent to |
| 16542 |
\csopt[3]{compact-ranges}). If no \meta{value} is specified, |
| 16543 |
\optfmt{true} is assumed. |
| 16544 |
|
| 16545 |
This setting allows location \idxpl{range} such as 184--189 to appear |
| 16546 |
more compactly as 184--9. The end \gls{location} is encapsulated |
| 16547 |
in the command \gls{bibglscompact}, so the \idx{range} would actually |
| 16548 |
become: |
| 16549 |
\begin{codeenv} |
| 16550 |
184\ics{delimR}\gls{bibglscompact}\marg{digit}\marg{18}\marg{9} |
| 16551 |
\end{codeenv} |
| 16552 |
If the \gls{location} is in the form \code{\meta{cs}\margm{loc}} |
| 16553 |
(where \meta{cs} is a command) |
| 16554 |
then \gls{bibglscompact} will be inside the argument. |
| 16555 |
For example, if the \idx{range} would normally be: |
| 16556 |
\begin{codeenv} |
| 16557 |
\cmd{custom}\marg{184}\ics{delimR}\cmd{custom}\marg{189} |
| 16558 |
\end{codeenv} |
| 16559 |
then it would become: |
| 16560 |
\begin{codeenv} |
| 16561 |
\cmd{custom}\marg{184}\ics{delimR}\cmd{custom}\marg{\gls{bibglscompact}\marg{digit}\marg{18}\marg{9}} |
| 16562 |
\end{codeenv} |
| 16563 |
The numerical value given in \csopt[\meta{n}]{compact-ranges} |
| 16564 |
indicates that compaction should only occur if the actual \gls{location} |
| 16565 |
consists of at least \meta{n} characters, for $\meta{n} \geq 2$. |
| 16566 |
Any value of \meta{n} less than 2 will switch off compaction. |
| 16567 |
|
| 16568 |
For example, \code{189} consists of 3 characters, so it will be |
| 16569 |
compacted with \csopt[3]{compact-ranges} but not with |
| 16570 |
\csopt[4]{compact-ranges}. Whereas \code{\csfmt{custom}\marg{89}} |
| 16571 |
would only be compacted with \csopt[2]{compact-ranges} |
| 16572 |
because \code{89} only consists of 2 characters. |
| 16573 |
|
| 16574 |
The compaction isn't limited to decimal digits but it will only |
| 16575 |
occur if both the start and end \gls{location} have the same number of |
| 16576 |
characters. For example, xvi--xviii can't be compacted because |
| 16577 |
the start consists of three characters and the end consists |
| 16578 |
of five characters, whereas xxv--xxx can be compacted to xxv--x, |
| 16579 |
which may look a little strange. In this case, you may want to |
| 16580 |
consider changing the definition of \cs{bibglscompact} so that |
| 16581 |
it only performs the compaction for digits. |
| 16582 |
|
| 16583 |
\optsection{see} |
| 16584 |
|
| 16585 |
If an entry has a \field{see} field, this can be placed before or |
| 16586 |
after the \gls{locationlist}, or completely omitted (but the value will |
| 16587 |
still be available in the \field{see} field for use with |
| 16588 |
\ics{glsxtrusesee}). The required \meta{value} must be one of: |
| 16589 |
\begin{itemize} |
| 16590 |
\item \optfmt{omit}: omit the see reference from the |
| 16591 |
\gls{locationlist}. |
| 16592 |
|
| 16593 |
\item \optfmt{before}: place the see reference before the |
| 16594 |
\gls{locationlist}. |
| 16595 |
|
| 16596 |
\item \optfmt{after}: place the see reference after the |
| 16597 |
\gls{locationlist} (default). |
| 16598 |
\end{itemize} |
| 16599 |
|
| 16600 |
The separator between the \gls{locationlist} and the cross-reference is |
| 16601 |
provided by \gls!{bibglsseesep}. This separator is omitted if the |
| 16602 |
\gls{locationlist} is empty. The cross-reference is written to the |
| 16603 |
\field{location} field using \code{\gls{bibglsusesee}\margm{label}}. |
| 16604 |
|
| 16605 |
\optsection{seealso} |
| 16606 |
|
| 16607 |
This is like \csopt{see} but governs the location of the cross-references |
| 16608 |
provided by the \field{seealso} field. You need at least v1.16 |
| 16609 |
of \sty{glossaries-extra} for this option. The values are the |
| 16610 |
same as for \csopt{see} but the separator is given by |
| 16611 |
\gls!{bibglsseealsosep}. The cross-reference is written to the |
| 16612 |
\field{location} field using \code{\gls{bibglsuseseealso}\margm{label}}. |
| 16613 |
|
| 16614 |
\optsection{alias} |
| 16615 |
|
| 16616 |
This is like \csopt{see} but governs the location of the cross-references |
| 16617 |
provided by the \field{alias} field. The separator is given by |
| 16618 |
\gls!{bibglsaliassep}. The cross-reference is written to the |
| 16619 |
\field{location} field using \code{\gls{bibglsusealias}\margm{label}}. |
| 16620 |
|
| 16621 |
\optsection{alias-loc} |
| 16622 |
|
| 16623 |
If an entry has an \field{alias} field, the \gls{locationlist} |
| 16624 |
may be retained or omitted or transferred to the target entry. |
| 16625 |
The required \meta{value} must be one of: |
| 16626 |
\begin{itemize} |
| 16627 |
\item\optfmt{keep}: keep the \gls{locationlist}; |
| 16628 |
\item\optfmt{transfer}: transfer the \gls{locationlist}; |
| 16629 |
\item\optfmt{omit}: omit the \gls{locationlist}. |
| 16630 |
\end{itemize} |
| 16631 |
The default setting is \csopt[transfer]{alias-loc}. |
| 16632 |
In all cases, the target entry will be added to the \field{see} |
| 16633 |
field of the entry with the \field{alias} field, unless it |
| 16634 |
already has a \field{see} field (in which case the \field{see} value |
| 16635 |
is left unchanged). |
| 16636 |
|
| 16637 |
Note that with \csopt[transfer]{alias-loc}, both the aliased |
| 16638 |
entry and the target entry must be in the same resource set. |
| 16639 |
(That is, both entries have been selected by the same instance of |
| 16640 |
\gls!{GlsXtrLoadResources}.) If you have \sty{glossaries-extra} version~1.12, |
| 16641 |
you may need to redefine \ics{glsxtrsetaliasnoindex} to do |
| 16642 |
nothing if the \glspl{locationlist} aren't showing correctly |
| 16643 |
with aliased entries. (This was corrected in version~1.13.) |
| 16644 |
|
| 16645 |
\optsection{loc-prefix} |
| 16646 |
|
| 16647 |
The \csopt{loc-prefix} setting indicates that the \glspl{locationlist} |
| 16648 |
should begin with \code{\gls!{bibglslocprefix}\margm{n}}. The \meta{value} may |
| 16649 |
be one of the following: |
| 16650 |
\begin{itemize} |
| 16651 |
\item \optfmt{false}: don't insert \code{\gls{bibglslocprefix}\margm{n}} at the |
| 16652 |
start of the \glspl{locationlist} (default). |
| 16653 |
|
| 16654 |
\item \optfmt{\margm{prefix-1},\margm{prefix-2},\ldots,\margm{prefix-n}}: |
| 16655 |
insert \code{\gls{bibglslocprefix}\margm{n}} (where \meta{n} is the number of |
| 16656 |
\glspl{location} in the list) at the start of each \gls{locationlist} and the |
| 16657 |
definition of \gls{bibglslocprefix} will have an \ics{ifcase} condition: |
| 16658 |
\begin{codeenv} |
| 16659 |
\cmd{providecommand}\marg{\gls{bibglslocprefix}}[1]\marg{\comment{} |
| 16660 |
\ics{ifcase}\idx{param}1 |
| 16661 |
\cmd{or} \meta{prefix-1}\gls{bibglspostlocprefix} |
| 16662 |
\cmd{or} \meta{prefix-2}\gls{bibglspostlocprefix} |
| 16663 |
\ldots |
| 16664 |
\cmd{else} \meta{prefix-n}\gls{bibglspostlocprefix} |
| 16665 |
\cmd{fi} |
| 16666 |
} |
| 16667 |
\end{codeenv} |
| 16668 |
|
| 16669 |
\item \optfmt{comma}: equivalent to \csopt[\marg{,~}]{loc-prefix} |
| 16670 |
but avoids confusion with the list syntax. That is, the prefix is a comma |
| 16671 |
followed by a space for non-empty \glspl{locationlist}. |
| 16672 |
|
| 16673 |
\item \optfmt{list}: equivalent to \csopt[\ics{pagelistname} ]{loc-prefix}. |
| 16674 |
|
| 16675 |
\item \optfmt{true}: equivalent to |
| 16676 |
\csopt[\gls{bibglspagename},\gls{bibglspagesname}]{loc-prefix}, |
| 16677 |
where the definitions of \gls{bibglspagename} and |
| 16678 |
\gls{bibglspagesname} are obtained from the \idx{tag.page} and |
| 16679 |
\idx{tag.pages} entries in \bibgls's \langxml. |
| 16680 |
This setting works best if the document's language matches the |
| 16681 |
language file. However, you can redefine these commands within |
| 16682 |
the document's language hooks or in the glossary preamble. |
| 16683 |
|
| 16684 |
\end{itemize} |
| 16685 |
|
| 16686 |
If \meta{value} is omitted, \optfmt{true} is assumed. The definition |
| 16687 |
will be placed in the \ext{glstex} file according to |
| 16688 |
\csopt{loc-prefix-def}. |
| 16689 |
|
| 16690 |
For example: |
| 16691 |
\begin{codeenv} |
| 16692 |
\gls{GlsXtrLoadResources}\oarg{\csopt[main]{type},\csopt[individual]{loc-prefix-def},\csopt[entries1]{src},\csopt[false]{loc-prefix}} |
| 16693 |
\gls{GlsXtrLoadResources}\oarg{\csopt[main]{type},\csopt[individual]{loc-prefix-def},\csopt[entries2]{src},\csopt{loc-prefix}} |
| 16694 |
\gls{GlsXtrLoadResources}\oarg{\csopt[symbols]{type},\csopt[entries3]{src},\csopt[p.,pp.]{loc-prefix}} |
| 16695 |
\end{codeenv} |
| 16696 |
This works since the conflicting \csopt[p.,pp.]{loc-prefix} and |
| 16697 |
\csopt[true]{loc-prefix} are in different glossaries (assigned through the |
| 16698 |
\csopt{type} key). The entries fetched from \filefmt{entries1.bib} |
| 16699 |
won't have a location prefix. The entries fetched from |
| 16700 |
\filefmt{entries2.bib} will have the location prefix obtained from |
| 16701 |
the language resource file. The entries fetched from |
| 16702 |
\filefmt{entries3.bib} will have the location prefix \qt{p.}\ or |
| 16703 |
\qt{pp.} (Note that using the \csopt{type} option isn't the same as |
| 16704 |
setting the \field{type} field for each entry in the \ext{bib} |
| 16705 |
file.) |
| 16706 |
|
| 16707 |
If the \csopt{type} option isn't used: |
| 16708 |
\begin{codeenv} |
| 16709 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries1]{src},\csopt[false]{loc-prefix}} |
| 16710 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries2]{src},\csopt{loc-prefix}} |
| 16711 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries3]{src},\csopt[p.,pp.]{loc-prefix}} |
| 16712 |
\end{codeenv} |
| 16713 |
then \csopt[true]{loc-prefix} takes precedence over |
| 16714 |
\csopt[p.,pp.]{loc-prefix} (since it was used first). The entries fetched from |
| 16715 |
\filefmt{entries1.bib} still won't have a location prefix, but the entries |
| 16716 |
fetched from both \filefmt{entries2.bib} and \filefmt{entries3.bib} |
| 16717 |
have the location prefixes obtained from the language resource file. |
| 16718 |
|
| 16719 |
Note that if you identify some glossaries but not others (for |
| 16720 |
example, you have dual entries in separate glossaries but only |
| 16721 |
use \csopt{type} and not \csopt{dual-type}), then you will need to |
| 16722 |
use \csopt[global]{loc-prefix-def} or \csopt[local]{loc-prefix-def}. |
| 16723 |
|
| 16724 |
\optsection{loc-prefix-def} |
| 16725 |
|
| 16726 |
This determines how the location prefix identified by |
| 16727 |
\csopt{loc-prefix} is written to the \ext{glstex} file. The value |
| 16728 |
may be one of: |
| 16729 |
\begin{itemize} |
| 16730 |
\item\optfmt{global} the definition is globally defined using |
| 16731 |
\cs{providecommand}; |
| 16732 |
\item\optfmt{local} the definition is locally defined using |
| 16733 |
\cs{providecommand} in the general glossary preamble |
| 16734 |
(\cs{glossarypreamble}); |
| 16735 |
\item\optfmt{individual} the definition is locally defined using |
| 16736 |
\cs{providecommand} in the glossary preamble of each type that has |
| 16737 |
been identified in the current \gls{resourceset}, using options like |
| 16738 |
\csopt{type} and \csopt{dual-type} |
| 16739 |
(\ics{apptoglossarypreamble}). |
| 16740 |
\end{itemize} |
| 16741 |
The default is \csopt[individual]{loc-prefix-def}. Note that this |
| 16742 |
can lead to an undefined control sequence error if locations appear |
| 16743 |
in a glossary that hasn't been detected by the \gls{resourceset}. |
| 16744 |
|
| 16745 |
\optsection{loc-suffix} |
| 16746 |
|
| 16747 |
This is similar to \csopt{loc-prefix} but there are some subtle |
| 16748 |
differences. In this case \meta{value} may either be the keyword |
| 16749 |
\optfmt{false} (in which case the location suffix is omitted) or a |
| 16750 |
comma-separated list |
| 16751 |
\optfmt{\meta{suffix-0}\dcomma\meta{suffix-1}\dcomma\ldots\dcomma\meta{suffix-n}} |
| 16752 |
where \meta{suffix-0} is the suffix to use when the |
| 16753 |
\gls{locationlist} only has a cross-reference with no |
| 16754 |
\glspl{location}, \meta{suffix-1} is the suffix to use when the |
| 16755 |
\gls{locationlist} has one \gls{location} (optionally with a |
| 16756 |
cross-reference), and so on. The final \meta{suffix-n} in the list |
| 16757 |
is the suffix when the \gls{locationlist} has \meta{n} or more |
| 16758 |
\glspl{location} (optionally with a cross-reference). |
| 16759 |
|
| 16760 |
This option will append \code{\gls!{bibglslocsuffix}\margm{n}} to |
| 16761 |
\glspl{locationlist} that either have a cross-reference or have at |
| 16762 |
least one \gls{location}. Unlike \gls{bibglslocprefix}, this |
| 16763 |
command isn't used when the \gls{locationlist} is completely empty. |
| 16764 |
Also, unlike \gls{bibglslocprefix}, this suffix command doesn't have |
| 16765 |
an equivalent to \gls{bibglspostlocprefix}. |
| 16766 |
|
| 16767 |
If \meta{value} omitted, \csopt[\ics{at}\idx{periodchar}]{loc-suffix} |
| 16768 |
is assumed. The default is \csopt[false]{loc-suffix}. |
| 16769 |
|
| 16770 |
The way the definition is written to the \ext{glstex} file is determined |
| 16771 |
by \csopt{loc-suffix-def}. |
| 16772 |
Note that if you identify some glossaries but not others (for |
| 16773 |
example, you have dual entries in separate glossaries but only |
| 16774 |
use \csopt{type} and not \csopt{dual-type}), then you will need to |
| 16775 |
use \csopt[global]{loc-suffix-def} or \csopt[local]{loc-suffix-def}. |
| 16776 |
|
| 16777 |
\optsection{loc-suffix-def} |
| 16778 |
|
| 16779 |
This determines how the location suffix identified by |
| 16780 |
\csopt{loc-suffix} is written to the \ext{glstex} file. The value |
| 16781 |
may be one of: |
| 16782 |
\begin{itemize} |
| 16783 |
\item\optfmt{global} the definition is globally defined using |
| 16784 |
\cs{providecommand}; |
| 16785 |
\item\optfmt{local} the definition is locally defined using |
| 16786 |
\cs{providecommand} in the general glossary preamble |
| 16787 |
(\cs{glossarypreamble}); |
| 16788 |
\item\optfmt{individual} the definition is locally defined using |
| 16789 |
\cs{providecommand} in the glossary preamble of each type that has |
| 16790 |
been identified in the current \gls{resourceset}, using options like |
| 16791 |
\csopt{type} and \csopt{dual-type} |
| 16792 |
(\ics{apptoglossarypreamble}). |
| 16793 |
\end{itemize} |
| 16794 |
The default is \csopt[individual]{loc-suffix-def}. Note that this |
| 16795 |
can lead to an undefined control sequence error if locations appear |
| 16796 |
in a glossary that hasn't been detected by the \gls{resourceset}. |
| 16797 |
|
| 16798 |
\optsection{loc-counters} |
| 16799 |
|
| 16800 |
Commands like \ics{gls} allow you to select a different |
| 16801 |
counter to use for the \gls{location} for that specific instance |
| 16802 |
(overriding the default counter for the entry's glossary type). |
| 16803 |
This is done with the \glsopt{counter} option. For example, |
| 16804 |
consider the following document: |
| 16805 |
\begin{codeenv} |
| 16806 |
\cmd{documentclass}\marg{article} |
| 16807 |
\strut |
| 16808 |
\cmd{usepackage}\oarg{colorlinks}\marg{hyperref} |
| 16809 |
\cmd{usepackage}\oarg{\styopt{record},\styopt[tree]{style}}\marg{glossaries-extra} |
| 16810 |
\strut |
| 16811 |
\gls{GlsXtrLoadResources}\oarg{ |
| 16812 |
\csopt[entries]{src}\comment{data in entries.bib} |
| 16813 |
} |
| 16814 |
\strut |
| 16815 |
\cmd{begin}\marg{document} |
| 16816 |
\strut |
| 16817 |
\cs{gls}\marg{pi}. |
| 16818 |
\cmd{begin}\marg{equation} |
| 16819 |
\cs{gls}\oarg{\glsopt[\counter{equation}]{counter}}\marg{pi} |
| 16820 |
\cmd{end}\marg{equation} |
| 16821 |
\cmd{begin}\marg{equation} |
| 16822 |
\cs{gls}\oarg{\glsopt[\counter{equation}]{counter}}\marg{pi} |
| 16823 |
\cmd{end}\marg{equation} |
| 16824 |
\strut |
| 16825 |
\cmd{newpage} |
| 16826 |
\cmd{begin}\marg{equation} |
| 16827 |
\cs{gls}\oarg{\glsopt[\counter{equation}]{counter}}\marg{pi} |
| 16828 |
\cmd{end}\marg{equation} |
| 16829 |
\strut |
| 16830 |
\cmd{newpage} |
| 16831 |
\cs{gls}\marg{pi}. |
| 16832 |
\strut |
| 16833 |
\cmd{newpage} |
| 16834 |
\cs{gls}\marg{pi}. |
| 16835 |
\strut |
| 16836 |
\cmd{newpage} |
| 16837 |
\cs{gls}\marg{pi}. |
| 16838 |
\strut |
| 16839 |
\cmd{newpage} |
| 16840 |
\cs{printunsrtglossaries} |
| 16841 |
\cmd{end}\marg{document} |
| 16842 |
\end{codeenv} |
| 16843 |
This results in the \gls{locationlist} \qt{1, 1--3, 3--5}. This |
| 16844 |
looks a little odd and it may seem as though the \idx{implicit-range} formation |
| 16845 |
hasn't worked, but the \glspl{location} are actually: page~1, equation~1, |
| 16846 |
equation~2, equation~3, page~3, page~4 and page~5. \Idxpl{range} can't |
| 16847 |
be formed across different counters. |
| 16848 |
|
| 16849 |
The \csopt[\meta{list}]{loc-counters} option instructs \bibgls\ |
| 16850 |
to group the \glspl{location} according to the counters given in |
| 16851 |
the comma-separated \meta{list}. If a \gls{location} has a counter |
| 16852 |
that's not listed in \meta{list}, then the \gls{location} is discarded. |
| 16853 |
|
| 16854 |
For example: |
| 16855 |
\begin{codeenv} |
| 16856 |
\gls{GlsXtrLoadResources}\oarg{ |
| 16857 |
\csopt[\counter{equation},\counter{page}]{loc-counters},\comment{group locations by counter} |
| 16858 |
\csopt[entries]{src}\comment{data in entries.bib} |
| 16859 |
} |
| 16860 |
\end{codeenv} |
| 16861 |
This will first list the \glspl{location} for the \counter{equation} |
| 16862 |
counter and then the \glspl{location} for the \counter{page} counter. |
| 16863 |
Each group of \glspl{location} is encapsulated within the command |
| 16864 |
\gls!{bibglslocationgroup}\margm{n}\margm{counter}\margm{locations}. |
| 16865 |
The groups are separated by \gls!{bibglslocationgroupsep}. |
| 16866 |
|
| 16867 |
The \meta{list} value must be non-empty. Use |
| 16868 |
\csopt[as-use]{loc-counters} to restore the default behaviour, where |
| 16869 |
the \glspl{location} are listed in the document order of use, or |
| 16870 |
\csopt[false]{save-locations} to omit the \glspl{locationlist}. Note that |
| 16871 |
you can't form counter groups from |
| 16872 |
\hyperref[sec:supplementalopts]{supplemental location lists}. |
| 16873 |
|
| 16874 |
\optsection{save-index-counter} |
| 16875 |
|
| 16876 |
\emph{This option requires at least version 1.29 of |
| 16877 |
\isty{glossaries-extra}.} The \meta{value} may be one of: |
| 16878 |
\begin{itemize} |
| 16879 |
\item \optfmt{false}: don't create the \field{indexcounter} field |
| 16880 |
(default); |
| 16881 |
\item \optfmt{true}: create the \field{indexcounter} field with the |
| 16882 |
value set to the first \counter{wrglossary} \gls{location}; |
| 16883 |
\item \meta{encap}: create the \field{indexcounter} field with the |
| 16884 |
value set to the first \counter{wrglossary} \gls{location} |
| 16885 |
where the \glsopt{format} is \meta{encap}. |
| 16886 |
\end{itemize} |
| 16887 |
This setting will have no effect if the \styopt{indexcounter} |
| 16888 |
package option hasn't been used. In the case where the \meta{value} |
| 16889 |
is \meta{encap}, make sure that this format takes priority in the |
| 16890 |
\gls{location} precedence rules (\longarg{map-format}). If the |
| 16891 |
\gls{location} with that \meta{encap} format value is discarded then |
| 16892 |
it can't be saved. |
| 16893 |
|
| 16894 |
The \styopt{indexcounter} package option |
| 16895 |
(\sty{glossaries-extra} v1.29+) creates a new counter called |
| 16896 |
\counter{wrglossary} that's incremented every time a term is |
| 16897 |
indexed (recorded), except for cross-references such as \cs{glssee}. |
| 16898 |
The increment is performed using \ics{refstepcounter} and is |
| 16899 |
followed by \code{\ics{label}\marg{wrglossary.\meta{n}}} where |
| 16900 |
\meta{n} is the value of the \counter{wrglossary} counter. |
| 16901 |
This option is intended for use with the \sty{hyperref} package to |
| 16902 |
allow \glspl{location} to link back to the particular part of the page where |
| 16903 |
the term was referenced rather than to the top of the page. |
| 16904 |
|
| 16905 |
\begin{important} |
| 16906 |
Take care not to confuse this with the \field{indexed} special internal field |
| 16907 |
introduced in \sty{glossaries-extra} v1.49+. This is incremented on a per-entry basis |
| 16908 |
and does not have an associated counter. |
| 16909 |
\end{important} |
| 16910 |
|
| 16911 |
The \styopt{indexcounter} package option also automatically |
| 16912 |
implements the option \styopt[wrglossary]{counter}, which means that |
| 16913 |
each instance of \code{\ics{gls}\margm{id}} writes the label |
| 16914 |
information to the \iext{aux} file: |
| 16915 |
\begin{codeenv} |
| 16916 |
\cmd{newlabel}\marg{wrglossary.\meta{n}}\marg{\margm{n}\margm{page}\marg{}\marg{wrglossary.\meta{n}}\marg{}} |
| 16917 |
\end{codeenv} |
| 16918 |
(where \meta{page} is the page number) followed by the record: |
| 16919 |
\begin{codeenv} |
| 16920 |
\gls{glsxtr@record}\margm{id}\marg{}\marg{wrglossary}\marg{\encap{glsnumberformat}}\margm{n} |
| 16921 |
\end{codeenv} |
| 16922 |
The \gls{location} here is actually the value of the \counter{wrglossary} |
| 16923 |
counter not the page number, but \bibgls\ can pick up the |
| 16924 |
corresponding \meta{page} from the \csfmt{newlabel} command. It then |
| 16925 |
replaces the \gls{record}['s] location \meta{n} with: |
| 16926 |
\nosecdef{glsxtr@wrglossarylocation} |
| 16927 |
(but it only does this for \glspl{record} that have the \counter{wrglossary} |
| 16928 |
counter). |
| 16929 |
|
| 16930 |
The \sty{glossaries-extra} package (v1.29+) adjusts the definition |
| 16931 |
of \ics{glshypernumber} (which is internally used by |
| 16932 |
\cs{glsnumberformat}, \cs{hyperbf} etc when \sty{hyperref} has been |
| 16933 |
loaded) so that if the counter is \counter{wrglossary} then |
| 16934 |
\ics{pageref} is used instead of \ics{hyperlink}. This means that the |
| 16935 |
page number is displayed in the \gls{locationlist} but it links back to |
| 16936 |
the place where the corresponding \cs{label} occurred. |
| 16937 |
|
| 16938 |
This method works partially with \idx!{makeindex} and \idx!{xindy} |
| 16939 |
but from their point of view the \gls{location} is the value of the |
| 16940 |
\counter{wrglossary} counter, which interferes with their ability to |
| 16941 |
merge duplicate page numbers and form \idxpl{range}. Since \bibgls\ is |
| 16942 |
designed specifically to work with \sty{glossaries-extra}, it's |
| 16943 |
aware of this special counter and will merge and collate the |
| 16944 |
\glspl{location} according to the corresponding page number instead. |
| 16945 |
|
| 16946 |
With the default \longarg{merge-wrglossary-records} switch, if a |
| 16947 |
term has multiple \counter{wrglossary} records for a given page they |
| 16948 |
will be merged. The reference link will be the dominant record for |
| 16949 |
that page. |
| 16950 |
|
| 16951 |
The \csopt{save-index-counter} option allows you to save the first |
| 16952 |
of the \counter{wrglossary} \glspl{location} for a given entry or the first |
| 16953 |
instance of a specific format of the \counter{wrglossary} \glspl{location} |
| 16954 |
for a given entry. This \gls{location} is stored in the |
| 16955 |
\field{indexcounter} internal field using: |
| 16956 |
\begin{codeenv} |
| 16957 |
\ics{GlsXtrSetField}\margm{id}\marg{\field{indexcounter}}\marg{\gls{glsxtr@wrglossarylocation}\margm{n}\margm{page}} |
| 16958 |
\end{codeenv} |
| 16959 |
Since \gls{glsxtr@wrglossarylocation} simply expands to its first |
| 16960 |
argument, the corresponding label can be obtained with: |
| 16961 |
\begin{codeenv} |
| 16962 |
wrglossary.\gls{glsxtr@wrglossarylocation}\margm{n}\margm{page} |
| 16963 |
\end{codeenv} |
| 16964 |
For convenience, \sty{glossaries-extra-bib2gls} provides: |
| 16965 |
\nosecdef{GlsXtrIndexCounterLink} |
| 16966 |
which will do: |
| 16967 |
\begin{codeenv*} |
| 16968 |
\ics{cs.hyperref.int}\oarg{wrglossary.\meta{value}}\margm{text} |
| 16969 |
\end{codeenv*} |
| 16970 |
where \meta{value} is the value of the \field{indexcounter} field if |
| 16971 |
it has been set. If the \field{indexcounter} field hasn't been set |
| 16972 |
(or if \sty{hyperref} hasn't been loaded) then just \meta{text} is |
| 16973 |
done. |
| 16974 |
|
| 16975 |
This provides a convenient way of encapsulating the \field{name} in |
| 16976 |
the glossary so that it links back to the first \counter{wrglossary} |
| 16977 |
entry or the first \glsopt[\meta{encap}]{format} \counter{wrglossary} |
| 16978 |
entry. This encapsulation can be done by providing a new glossary |
| 16979 |
style or more simply by redefining \ics{glsnamefont}: |
| 16980 |
\begin{codeenv} |
| 16981 |
\cmd{renewcommand}\marg{\cs{glsnamefont}}[1]\marg{\comment{} |
| 16982 |
\gls{GlsXtrIndexCounterLink}\marg{\idx{param}1}\marg{\cs{glscurrententrylabel}}} |
| 16983 |
\end{codeenv} |
| 16984 |
Here's a complete example: |
| 16985 |
\begin{codeenv} |
| 16986 |
\cmd{documentclass}\marg{article} |
| 16987 |
\strut |
| 16988 |
\cmd{usepackage}\marg{lipsum}\comment{dummy filler text} |
| 16989 |
\cmd{usepackage}\oarg{colorlinks}\marg{hyperref} |
| 16990 |
\cmd{usepackage}\oarg{\styopt{record},\styopt{indexcounter}}\marg{glossaries-extra} |
| 16991 |
\strut |
| 16992 |
\cmd{newcommand}\marg{\cmd{primary}}[1]\marg{\cs{hyperbf}\marg{\idx{param}1}} |
| 16993 |
\strut |
| 16994 |
\gls{GlsXtrLoadResources}\oarg{ |
| 16995 |
\csopt[entries]{src},\comment{terms defined in entries.bib} |
| 16996 |
\csopt[primary]{save-index-counter} |
| 16997 |
} |
| 16998 |
\strut |
| 16999 |
\cmd{renewcommand}\marg{\cs{glsnamefont}}[1]\marg{\comment{} |
| 17000 |
\gls{GlsXtrIndexCounterLink}\marg{\idx{param}1}\marg{\cs{glscurrententrylabel}}} |
| 17001 |
\strut |
| 17002 |
\cmd{begin}\marg{document} |
| 17003 |
\strut |
| 17004 |
A \cs{gls}\marg{sample}. \cmd{lipsum}*[1] A \cs{gls}\marg{duck}. |
| 17005 |
\strut |
| 17006 |
An equation: |
| 17007 |
\cmd{begin}\marg{equation} |
| 17008 |
\cs{gls}\oarg{\glsopt[\counter{equation}]{counter}}\marg{pi} |
| 17009 |
\cmd{end}\marg{equation} |
| 17010 |
\strut |
| 17011 |
\cmd{lipsum}[2] |
| 17012 |
\strut |
| 17013 |
Another \cs{gls}\oarg{\glsopt[primary]{format}}\marg{sample}. \cmd{lipsum}*[3] Another |
| 17014 |
\cs{gls}\marg{duck}. |
| 17015 |
\strut |
| 17016 |
\cs{gls}\marg{pi}. \cmd{lipsum}[4] |
| 17017 |
\strut |
| 17018 |
A \cs{gls}\marg{sample}. \cmd{lipsum}*[5] A \cs{gls}\marg{duck} and |
| 17019 |
\cs{gls}\oarg{\glsopt[primary]{format}}\marg{pi}. |
| 17020 |
\strut |
| 17021 |
\cmd{lipsum}*[6] A \cs{gls}\oarg{\glsopt[primary]{format}}\marg{duck}. |
| 17022 |
\strut |
| 17023 |
\cs{printunsrtglossaries} |
| 17024 |
\cmd{end}\marg{document} |
| 17025 |
\end{codeenv} |
| 17026 |
Note that the \glsopt[\counter{equation}]{counter} entry will have its own |
| 17027 |
independent \gls{location}. In this example, it's difficult to tell the |
| 17028 |
difference between 1 (the equation reference) and 1 (the page |
| 17029 |
reference) in the \gls{locationlist} for the \code{pi} entry. |
| 17030 |
|
| 17031 |
The \glsopt[primary]{format} instances indicate |
| 17032 |
\glsdisp{principallocation}{principal} references. |
| 17033 |
They're displayed in bold (since \csfmt{primary} is defined to use |
| 17034 |
\csfmt{hyperbf}) and these are the \glspl{location} saved in the |
| 17035 |
\field{indexcounter} field because that's the \meta{encap} |
| 17036 |
identified by the \csopt[primary]{save-index-counter} setting. |
| 17037 |
|
| 17038 |
\section{Supplemental Locations} |
| 17039 |
\label{sec:supplementalopts} |
| 17040 |
|
| 17041 |
\emph{These options require at least version 1.14 of |
| 17042 |
\isty{glossaries-extra}.} If you require \glspl{location} from multiple |
| 17043 |
external sources, then you need at least version 1.36 of |
| 17044 |
\isty{glossaries-extra} (or, more specifically, |
| 17045 |
\isty{glossaries-extra-bib2gls}, which is automatically loaded |
| 17046 |
by the \styopt[only]{record} package option). |
| 17047 |
|
| 17048 |
The \sty{glossaries-extra} package (from v1.14) provides a way of |
| 17049 |
manually adding \glspl{location} in \glspl{supplementaldocument} through the use |
| 17050 |
of the \glsaddopt{thevalue} option in the optional argument of |
| 17051 |
\ics{glsadd}. Setting values manually is inconvenient and can result |
| 17052 |
in errors, so \bibgls\ provides a way of doing this automatically. |
| 17053 |
Both the \gls{maindocument} and the \supplementarydocument\ need to use |
| 17054 |
the \styopt{record} option. The entries provided in the \csopt{src} |
| 17055 |
set must have the same labels as those used in the |
| 17056 |
\supplementarydocument. (The simplest way to achieve this is to ensure that both |
| 17057 |
documents use the same \ext{bib} files and the same prefixes.) |
| 17058 |
|
| 17059 |
For example, suppose the file \filefmt{entries.bib} contains: |
| 17060 |
\begin{codeenv} |
| 17061 |
\atentry{entry}\marg{sample, |
| 17062 |
\field{name}=\marg{sample}, |
| 17063 |
\field{description}=\qtdelim{an example entry} |
| 17064 |
} |
| 17065 |
\strut |
| 17066 |
\atentry{abbreviation}\marg{html, |
| 17067 |
\field{short}=\qtdelim{html}, |
| 17068 |
\field{long}=\marg{hypertext markup language} |
| 17069 |
} |
| 17070 |
\strut |
| 17071 |
\atentry{abbreviation}\marg{ssi, |
| 17072 |
\field{short}=\qtdelim{ssi}, |
| 17073 |
\field{long}=\qtdelim{server-side includes} |
| 17074 |
} |
| 17075 |
\strut |
| 17076 |
\atentry{index}\marg{goose,\field{plural}=\qtdelim{geese}} |
| 17077 |
\end{codeenv} |
| 17078 |
Now suppose the supplementary document is contained in the file |
| 17079 |
\filefmt{suppl.tex}: |
| 17080 |
\begin{codeenv} |
| 17081 |
\cmd{documentclass}\marg{article} |
| 17082 |
\strut |
| 17083 |
\cmd{usepackage}\oarg{colorlinks}\marg{hyperref} |
| 17084 |
\cmd{usepackage}\oarg{\styopt{record},\styopt[section]{counter}}\marg{glossaries-extra} |
| 17085 |
\strut |
| 17086 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}} |
| 17087 |
\strut |
| 17088 |
\cmd{renewcommand}\marg{\cmd{thesection}}\marg{S\cmd{arabic}\marg{section}} |
| 17089 |
\cmd{renewcommand}\marg{\cmd{theHsection}}\marg{\cmd{thepart}.\cmd{thesection}} |
| 17090 |
\strut |
| 17091 |
\cmd{begin}\marg{document} |
| 17092 |
\cmd{part}\marg{Sample Part} |
| 17093 |
\cmd{section}\marg{Sample Section} |
| 17094 |
\cs{gls}\marg{goose}. \cs{gls}\marg{sample}. |
| 17095 |
\strut |
| 17096 |
\cmd{part}\marg{Another Part} |
| 17097 |
\cmd{section}\marg{Another Section} |
| 17098 |
\cs{gls}\marg{html}. |
| 17099 |
\cs{gls}\marg{ssi}. |
| 17100 |
\strut |
| 17101 |
\cs{printunsrtglossaries} |
| 17102 |
\cmd{end}\marg{document} |
| 17103 |
\end{codeenv} |
| 17104 |
This uses the \counter{section} counter for the \glspl{location} and has a |
| 17105 |
prefix (\code{\csfmt{thepart}.})\ for the section hyperlinks. |
| 17106 |
|
| 17107 |
Now let's suppose I have another document called \filefmt{main.tex} |
| 17108 |
that uses the \code{sample} entry, but also needs to include the |
| 17109 |
\gls{location} (S1) from the \supplementarydocument. The manual approached |
| 17110 |
offered by \styfmt{glossaries-extra} is quite cumbersome and requires |
| 17111 |
setting the \catattr{externallocation} attribute and using |
| 17112 |
\ics{glsadd} with \glsaddopt[S1]{thevalue}, \glsaddopt[I.S1]{theHvalue} |
| 17113 |
and \glsaddopt[\encap{glsxtrsupphypernumber}]{format}. |
| 17114 |
|
| 17115 |
This can be simplified with \bibgls\ by using the |
| 17116 |
\optfmt{supplemental-locations} option, described below. |
| 17117 |
|
| 17118 |
Version 1.36 of \isty{glossaries-extra-bib2gls} introduces some |
| 17119 |
special \gls{location} formatting commands that don't use the |
| 17120 |
\catattr{externallocation} attribute, but instead have an extra |
| 17121 |
argument that indicates the external reference. The additional |
| 17122 |
argument means that it can't be used by the \glsaddopt{format} |
| 17123 |
key, but with \bibgls\ you don't use \cs{glsadd} to record |
| 17124 |
the external \glspl{location}. Instead it obtains the \glspl{record} from |
| 17125 |
the corresponding \supplementary\ \ext{aux} file, and adjusts the |
| 17126 |
\gls{location} encapsulator as appropriate. |
| 17127 |
|
| 17128 |
If \bibgls\ detects an older version of \sty{glossaries-extra}, |
| 17129 |
it will only allow one external \supplemental\ source, and |
| 17130 |
will set the \catattr{externallocation} attribute and use |
| 17131 |
the \encap{glsxtrsupphypernumber} format. Otherwise \bibgls\ |
| 17132 |
will allow multiple sources and use the newer method. |
| 17133 |
|
| 17134 |
\optsection{supplemental-locations} |
| 17135 |
|
| 17136 |
The value should be the base name (without the extension) of the |
| 17137 |
\supplementarydocument\ (\optfmt{suppl} in the above example). |
| 17138 |
If you have at least version 1.36 of \sty{glossaries-extra}, |
| 17139 |
the value may be a comma-separated list of base names (without the |
| 17140 |
extensions) of the \supplementarydocuments. If an older version is |
| 17141 |
detected, \bibgls\ will issue a warning and only accept the first |
| 17142 |
element of the list. |
| 17143 |
|
| 17144 |
For example: |
| 17145 |
\begin{codeenv} |
| 17146 |
\cmd{documentclass}\marg{article} |
| 17147 |
\strut |
| 17148 |
\cmd{usepackage}\oarg{colorlinks}\marg{hyperref} |
| 17149 |
\cmd{usepackage}\oarg{\styopt{record}}\marg{glossaries-extra} |
| 17150 |
\strut |
| 17151 |
\gls{GlsXtrLoadResources}\oarg{ |
| 17152 |
\csopt[suppl]{supplemental-locations},\comment{fetch records from suppl.aux} |
| 17153 |
\csopt[entries]{src}} |
| 17154 |
\strut |
| 17155 |
\cmd{begin}\marg{document} |
| 17156 |
\cs{Gls}\marg{sample} document. |
| 17157 |
\strut |
| 17158 |
\cs{printunsrtglossaries} |
| 17159 |
\cmd{end}\marg{document} |
| 17160 |
\end{codeenv} |
| 17161 |
The \gls{locationlist} for \code{sample} will now be \qt{1, S1} (page~1 |
| 17162 |
from the \gls{maindocument} and S1 from the \supplementarydocument). |
| 17163 |
|
| 17164 |
With \sty{glossaries-extra} v1.36+, a regular \gls{location} from the |
| 17165 |
\supplementarydocument\ will be encapsulated with: |
| 17166 |
\nosecdef{glsxtrdisplaysupploc} |
| 17167 |
By default, this simply creates an external hyperlink to the |
| 17168 |
\supplementarydocument\ with the \gls{location} as the hyperlink text. |
| 17169 |
The hyperlink is created using \meta{src} as the target path |
| 17170 |
with the fragment part (anchor) formed from the prefix and |
| 17171 |
\gls{location}. The \catattr{externallocation} attribute is not set in |
| 17172 |
this case. The actual formatting is done via: |
| 17173 |
\nosecdef{glsxtrmultisupplocation} |
| 17174 |
which ignores the \meta{format} argument by default. Its |
| 17175 |
definition is simply: |
| 17176 |
\begin{codeenv} |
| 17177 |
\cmd{newcommand}*\marg{\gls{glsxtrmultisupplocation}}[3]\marg{\comment{} |
| 17178 |
\marg{\comment{scope required to localise changes} |
| 17179 |
\cmd{def}\cs{glsxtrsupplocationurl}\marg{\idx{param}2}\comment{} |
| 17180 |
\cs{glshypernumber}\marg{\idx{param}1}\comment{} |
| 17181 |
}\comment{} |
| 17182 |
} |
| 17183 |
\end{codeenv} |
| 17184 |
This locally sets the command \ics{glsxtrsupplocationurl}, which is checked |
| 17185 |
by \ics{glshypernumber} to establish an external rather than internal link. |
| 17186 |
You can redefine the \supplementallocation\ command to retain the original |
| 17187 |
\idx{encap} used in the target document: |
| 17188 |
\begin{codeenv} |
| 17189 |
\cmd{renewcommand}*\marg{\gls{glsxtrmultisupplocation}}[3]\marg{\comment{} |
| 17190 |
\marg{\comment{scope required to localise changes} |
| 17191 |
\cmd{def}\cs{glsxtrsupplocationurl}\marg{\idx{param}2}\comment{} |
| 17192 |
\ics{csuse}\marg{\idx{param}3}\marg{\idx{param}1}\comment{} |
| 17193 |
}\comment{} |
| 17194 |
} |
| 17195 |
\end{codeenv} |
| 17196 |
but remember that if a hyperlink is required, the identified |
| 17197 |
control sequence name must correspond to a command that |
| 17198 |
uses \cs{glshyperlink} (such as \cs{hyperbf}), otherwise you |
| 17199 |
will lose the hyperlink. |
| 17200 |
|
| 17201 |
With older versions of \sty{glossaries-extra}, |
| 17202 |
the original \gls{location} format from the \supplementarydocument\ |
| 17203 |
will be replaced by \encap{glsxtrsupphypernumber}, which |
| 17204 |
again produces an external hyperlink. The \catattr{externallocation} |
| 17205 |
attribute also needs to be set (this can be done automatically with |
| 17206 |
\csopt{supplemental-category}) to identify the external document. |
| 17207 |
The original format can't be accessed. |
| 17208 |
|
| 17209 |
In both cases, if the document hasn't loaded the \isty{hyperref} package, the |
| 17210 |
\gls{location} will simply be displayed without a hyperlink. Even if both the main |
| 17211 |
and the \supplementarydocuments\ have loaded \sty{hyperref}, note that not all |
| 17212 |
PDF viewers can handle external hyperlinks, and some that can open the external |
| 17213 |
PDF file may not recognise the destination within that file. |
| 17214 |
|
| 17215 |
The special \code{nameref} \glspl{location} (see |
| 17216 |
\longarg{merge-nameref-on}) are still identified with |
| 17217 |
\gls!{glsxtrdisplaylocnameref} but the \meta{file} argument will now |
| 17218 |
be set. |
| 17219 |
|
| 17220 |
As from \bibgls\ v1.7, any awkward characters in the file path are |
| 17221 |
replaced with \gls{bibglshrefchar} or (for \idx{non-ASCII} |
| 17222 |
characters, when supported) \gls{bibglshrefunicode}. Both commands |
| 17223 |
take two arguments: the hexadecimal character code and the actual |
| 17224 |
character. In the case of \gls{bibglshrefchar}, the second |
| 17225 |
argument is ignored, and the first is preceded by a literal percent |
| 17226 |
character, so \filefmt{file name.pdf} will be converted to: |
| 17227 |
\begin{codeenv} |
| 17228 |
file\gls{bibglshrefchar}\marg{20}\marg{ }name.pdf |
| 17229 |
\end{codeenv} |
| 17230 |
which will expand to \verb|file%20name.pdf|. |
| 17231 |
In the case of \gls{bibglshrefunicode}, the first argument is |
| 17232 |
ignored, so \filefmt{skr\'aarnafn.pdf} will be converted to: |
| 17233 |
\begin{codeenv} |
| 17234 |
skr\gls{bibglshrefunicode}\marg{E1}\marg{\'a}arnafn.pdf |
| 17235 |
\end{codeenv} |
| 17236 |
which will expand to \code{skr\'aarnafn.pdf}. |
| 17237 |
|
| 17238 |
|
| 17239 |
The \supplementarylocation\ lists are encapsulated within |
| 17240 |
\gls{bibglssupplemental}. With \sty{glossaries-extra} v1.36+, |
| 17241 |
this command will encapsulate the sub-lists with |
| 17242 |
\gls{bibglssupplementalsublist}. |
| 17243 |
|
| 17244 |
So the above example with an old version of \sty{glossaries-extra} |
| 17245 |
(pre 1.36) will set the \supplementallocation\ list (which only consists |
| 17246 |
of one \gls{location}) to: |
| 17247 |
\begin{codeenv} |
| 17248 |
\gls{bibglssupplemental} |
| 17249 |
\marg{1}\marg{\ics{setentrycounter}\oarg{I}\marg{\counter{section}}\cs{glsxtrsupphypernumber}\marg{S1}} |
| 17250 |
\end{codeenv} |
| 17251 |
and the external target must be supplied through the |
| 17252 |
\catattr{externallocation} attribute, which can be set |
| 17253 |
with the \csopt{supplemental-category} option. |
| 17254 |
|
| 17255 |
Whereas with at least version 1.36, the list will be: |
| 17256 |
\begin{codeenv} |
| 17257 |
\gls{bibglssupplemental}\marg{1}\marg{\gls{bibglssupplementalsublist}\marg{1}\marg{suppl.pdf} |
| 17258 |
\marg{\gls{glsxtrdisplaysupploc}\marg{I}\marg{\counter{section}}\marg{\encap{glsnumberformat}}\marg{suppl.pdf}\marg{S1}}} |
| 17259 |
\end{codeenv} |
| 17260 |
|
| 17261 |
If an entry has both a main \gls{locationlist} and a |
| 17262 |
\supplementarylocation\ list (such as the \code{sample} entry above), the lists |
| 17263 |
will be separated by \gls!{bibglssupplementalsep}. The sub-lists |
| 17264 |
(when supported) are separated by \gls{bibglssupplementalsubsep}. |
| 17265 |
|
| 17266 |
\optsection{supplemental-selection} |
| 17267 |
|
| 17268 |
In the above example, only the \code{sample} entry is listed in the |
| 17269 |
\gls{maindocument}, even though the \supplementarydocument\ also |
| 17270 |
references the \code{goose}, \code{html} and \code{ssi} entries. By |
| 17271 |
default, only those entries that are referenced in the \gls{maindocument} |
| 17272 |
will have \supplementarylocations\ added (if found in the |
| 17273 |
\glsdisp{supplementaldocument}{supplementary document's} \iext{aux} |
| 17274 |
file). You can additionally include other entries that are |
| 17275 |
referenced in the \supplementarydocument\ but not in the main |
| 17276 |
document using \optfmt{supplemental-selection}. The \meta{value} may |
| 17277 |
be one of the following: |
| 17278 |
\begin{itemize} |
| 17279 |
\item \optfmt{all}: add all the entries in the |
| 17280 |
\supplementarydocument\ that have been defined in the \ext{bib} files listed in |
| 17281 |
\csopt{src} for this resource set in the \gls{maindocument}. |
| 17282 |
\item \optfmt{selected}: only add \supplementallocations\ for entries |
| 17283 |
that have already been selected by this \gls{resourceset}. |
| 17284 |
\item \meta{label-1},\ldots,\meta{label-2}: in addition to all those |
| 17285 |
entries that have already been selected by this resource set, also |
| 17286 |
add the entries identified in the comma-separated list. If a label |
| 17287 |
in this list doesn't have a record in the |
| 17288 |
\glsdisp{supplementaldocument}{supplementary document's} |
| 17289 |
\ext{aux} file, it will be ignored. |
| 17290 |
\end{itemize} |
| 17291 |
Any records in the \supplementary\ \ext{aux} file that aren't defined |
| 17292 |
by the current resource set (through the \ext{bib} files listed in |
| 17293 |
\csopt{src}) will be ignored. Entry aliases aren't taken into |
| 17294 |
account when including \supplementarylocations. |
| 17295 |
|
| 17296 |
For example: |
| 17297 |
\begin{codeenv} |
| 17298 |
\cmd{documentclass}\marg{article} |
| 17299 |
\strut |
| 17300 |
\cmd{usepackage}\oarg{colorlinks}\marg{hyperref} |
| 17301 |
\cmd{usepackage}\oarg{\styopt{record}}\marg{glossaries-extra} |
| 17302 |
\strut |
| 17303 |
\gls{GlsXtrLoadResources}\oarg{ |
| 17304 |
\csopt[suppl]{supplemental-locations}, |
| 17305 |
\csopt[html,ssi]{supplemental-selection}, |
| 17306 |
\csopt[entries]{src}} |
| 17307 |
\strut |
| 17308 |
\cmd{begin}\marg{document} |
| 17309 |
\cs{Gls}\marg{sample} document. |
| 17310 |
\strut |
| 17311 |
\cs{printunsrtglossaries} |
| 17312 |
\cmd{end}\marg{document} |
| 17313 |
\end{codeenv} |
| 17314 |
This will additionally add the \code{html} and \code{ssi} entries |
| 17315 |
even though they haven't been used in this document. The |
| 17316 |
\code{goose} entry used in the \supplementarydocument\ won't be |
| 17317 |
included. |
| 17318 |
|
| 17319 |
\optsection{supplemental-category} |
| 17320 |
|
| 17321 |
The \field{category} field for entries containing \supplementallocation\ |
| 17322 |
lists may be set using this option. If unset, |
| 17323 |
\meta{value} defaults to the same as that given by the |
| 17324 |
\csopt{category} option. The \meta{value} may either be a known |
| 17325 |
identifier (as per \csopt{category}) or the category label. For example: |
| 17326 |
\begin{codeenv} |
| 17327 |
\cmd{documentclass}\marg{article} |
| 17328 |
\strut |
| 17329 |
\cmd{usepackage}\oarg{colorlinks}\marg{hyperref} |
| 17330 |
\cmd{usepackage}\oarg{\styopt{record}}\marg{glossaries-extra} |
| 17331 |
\strut |
| 17332 |
\gls{GlsXtrLoadResources}\oarg{ |
| 17333 |
\csopt[suppl]{supplemental-locations}, |
| 17334 |
\csopt[html,ssi]{supplemental-selection}, |
| 17335 |
\csopt[supplemental]{supplemental-category}, |
| 17336 |
\csopt[entries]{src}} |
| 17337 |
\strut |
| 17338 |
\cmd{begin}\marg{document} |
| 17339 |
\cs{Gls}\marg{sample} document. |
| 17340 |
\strut |
| 17341 |
\cs{printunsrtglossaries} |
| 17342 |
\cmd{end}\marg{document} |
| 17343 |
\end{codeenv} |
| 17344 |
|
| 17345 |
A value of \code{false} will switch off this setting (the default). |
| 17346 |
|
| 17347 |
\section{Sorting} |
| 17348 |
\label{sec:sortingopts} |
| 17349 |
|
| 17350 |
Entries are typically displayed in an ordered list, but the |
| 17351 |
\styfmt{glossaries-extra} package is versatile enough to be used in |
| 17352 |
wider contexts than simple terms, symbols or abbreviations. For |
| 17353 |
example, entries could contain theorems or problems where the |
| 17354 |
\field{name} supplies the title and the \field{description} provides |
| 17355 |
a description of the theorem or problem. Another field might then |
| 17356 |
contain the proof or solution. Therefore, somewhat unusually for an |
| 17357 |
indexing application, \bibgls\ also provides the option to shuffle |
| 17358 |
the entries instead of sorting them. |
| 17359 |
|
| 17360 |
This section covers the resource options for sorting |
| 17361 |
\glspl{primaryentry}. See \sectionref{sec:dualoptssort} for sorting |
| 17362 |
\glspl{dualentry} and also \csopt{sort-label-list} for sorting field |
| 17363 |
values that contain a comma-separated list of entry labels (such as |
| 17364 |
the \field{see} or \field{seealso} fields). |
| 17365 |
|
| 17366 |
The sort methods that use a comparison function (that is, all the |
| 17367 |
sort methods except those listed in \tableref{tab:sortoptionsnosort}) |
| 17368 |
require a sort value for each entry. The function compares these |
| 17369 |
values to determine the order. By default, this sort value is |
| 17370 |
obtained from the \field{sort} field but for greater flexibility |
| 17371 |
it's best to not actually set this field. \bibgls\ has a set of fallbacks |
| 17372 |
that it uses if a field it needs to access is missing. These |
| 17373 |
fallbacks depend on the \gls{entrytype} and resource settings (see |
| 17374 |
\sectionref{sec:fallbacks}). |
| 17375 |
|
| 17376 |
For example, if a term defined with \atentry{index} doesn't have the |
| 17377 |
\field{sort} field set then \bibgls\ will use the value given by the |
| 17378 |
\field{name} field because \field{name} is the fallback field for |
| 17379 |
\field{sort} for \atentry{index} entries. If the \field{name} field |
| 17380 |
isn't set either then \bibgls\ will use the fallback for that field. |
| 17381 |
In the case of \atentry{index} that's the entry's label. If the |
| 17382 |
\field{sort} field is explicitly set then there's no need to use the |
| 17383 |
fallback. |
| 17384 |
|
| 17385 |
If, on the other hand, a term defined with \atentry{symbol} doesn't |
| 17386 |
have the \field{sort} field set then \bibgls\ will use the value |
| 17387 |
from the field identified by \csopt{symbol-sort-fallback}, which is |
| 17388 |
the entry's label by default (not the \field{name} field). |
| 17389 |
|
| 17390 |
This means that if I don't explicitly set the \field{sort} field for |
| 17391 |
any entries then I can, for example, sort terms defined with |
| 17392 |
\atentry{index} by \field{name} and those defined with |
| 17393 |
\atentry{symbol} by \field{description} with the setting: |
| 17394 |
\begin{codeenv} |
| 17395 |
\csopt[description]{symbol-sort-fallback} |
| 17396 |
\end{codeenv} |
| 17397 |
|
| 17398 |
If the field used to obtain the sort value is changed |
| 17399 |
(with \csopt{sort-field}) then the \field{sort} field won't be |
| 17400 |
queried. This reduces the flexibility of selecting the most |
| 17401 |
appropriate field for given \glspl{entrytype}. For example, |
| 17402 |
\csopt[name]{sort-field} will force all entries to be sorted by the |
| 17403 |
\field{name} field, which may not be appropriate for symbols. |
| 17404 |
|
| 17405 |
\begin{important} |
| 17406 |
If you choose a field whose value must be a label (such as |
| 17407 |
\field{parent} or \field{group}) then the sort value will be that label. |
| 17408 |
\end{important} |
| 17409 |
|
| 17410 |
You can have \atentry{preamble} definitions that |
| 17411 |
can be hidden from \bibgls's interpreter. For example, |
| 17412 |
\exfile{no-interpret-preamble.bib} might contain: |
| 17413 |
\begin{codeenv} |
| 17414 |
\atentry{preamble}\marg{\qtdelim{\cmd{providecommand}\marg{\gls{sortop}}[2]\marg{\idx{param}1 \idx{param}2}}} |
| 17415 |
\end{codeenv} |
| 17416 |
which is loaded using: |
| 17417 |
\begin{codeenv} |
| 17418 |
\gls{GlsXtrLoadResources}\oarg{\csopt[no-interpret-preamble]{src}, |
| 17419 |
\csopt[false]{interpret-preamble}} |
| 17420 |
\end{codeenv} |
| 17421 |
This provides a custom command: |
| 17422 |
\nosecdef{sortop} |
| 17423 |
for internal use in the document. (Remember it won't be defined on |
| 17424 |
the first \LaTeX\ run before the \iext{glstex} file has been |
| 17425 |
created and so is only used within entry fields.) |
| 17426 |
|
| 17427 |
Another file, say, \filefmt{interpret-preamble.bib} may provide |
| 17428 |
a definition for \bibgls: |
| 17429 |
\begin{codeenv} |
| 17430 |
\atentry{preamble}\marg{\qtdelim{\cmd{providecommand}\marg{\gls{sortop}}[2]\marg{\idx{param}2, \idx{param}1}}} |
| 17431 |
\end{codeenv} |
| 17432 |
which can be processed with: |
| 17433 |
\begin{codeenv} |
| 17434 |
\gls{GlsXtrLoadResources}\oarg{\csopt[interpret-preamble]{src}} |
| 17435 |
\end{codeenv} |
| 17436 |
to provide \bibgls\ with this definition. |
| 17437 |
The \filefmt{entries.bib} file could contain: |
| 17438 |
\begin{codeenv} |
| 17439 |
\atentry{entry}\marg{caesar, |
| 17440 |
\field{name}=\marg{\gls{sortop}\marg{Gaius Julius}\marg{Caesar}}, |
| 17441 |
\field{first}=\marg{Julius Caesar}, |
| 17442 |
\field{text}=\marg{Caesar}, |
| 17443 |
\field{description}=\marg{Roman politician and general} |
| 17444 |
} |
| 17445 |
\end{codeenv} |
| 17446 |
and then be processed with: |
| 17447 |
\begin{codeenv} |
| 17448 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}} |
| 17449 |
\end{codeenv} |
| 17450 |
|
| 17451 |
The definition provided in \filefmt{interpret-preamble.bib}, which |
| 17452 |
swaps the two arguments around, is now picked up by \bibgls, so the |
| 17453 |
sort value becomes \code{Caesar, Gaius Julius}, but this new |
| 17454 |
definition doesn't affect the document since \LaTeX\ has already |
| 17455 |
defined \gls{sortop} from the first resource set, so the name will |
| 17456 |
appear as \qt{Gaius Julius Caesar} in the glossary. (If you have |
| 17457 |
\cs{renewcommand} rather than \cs{providecommand}, you can prevent |
| 17458 |
the redefinition occurring in the document with |
| 17459 |
\csopt[false]{write-preamble}.) |
| 17460 |
|
| 17461 |
Alternatively both of these \ext{bib} files can be loaded in one |
| 17462 |
\igls{resourceset}: |
| 17463 |
\begin{codeenv} |
| 17464 |
\gls{GlsXtrLoadResources}\oarg{\csopt[interpret-preamble,entries]{src}} |
| 17465 |
\end{codeenv} |
| 17466 |
Another possibility is to provide a custom package that contains the |
| 17467 |
command definitions for the \bibgls\ interpreter and load it with |
| 17468 |
\longarg{custom-packages} instead of having the |
| 17469 |
\filefmt{interpret-preamble.bib} file. |
| 17470 |
|
| 17471 |
\optsection{sort} |
| 17472 |
|
| 17473 |
The \csopt{sort} key indicates how \glspl{primaryentry} should be sorted. |
| 17474 |
If the \meta{value} is omitted, \csopt[resource]{sort} is assumed. |
| 17475 |
Note the differences between the keywords \optfmt{resource}, |
| 17476 |
\optfmt{doc} and \optfmt{locale}: |
| 17477 |
\begin{description} |
| 17478 |
\item[\optfmt{resource}] The default \gls{resource-locale}, which |
| 17479 |
can be specified with the \csopt{locale} option. If that option |
| 17480 |
hasn't been set, then \optfmt{resource} will be equivalent to |
| 17481 |
\optfmt{doc}. This option is new to \bibgls\ v3.3. Previous versions |
| 17482 |
had \csopt[doc]{sort} as the default. |
| 17483 |
|
| 17484 |
\item[\optfmt{doc}] The \gls{document-locale} if it has been detected by |
| 17485 |
\sty{tracklang}. If no document language has been detected (or |
| 17486 |
identified with \commonlongarg{locale}), then |
| 17487 |
\optfmt{doc} will be equivalent to \optfmt{locale}. |
| 17488 |
|
| 17489 |
\item[\optfmt{locale}] The default \gls{Java-locale}. |
| 17490 |
|
| 17491 |
\end{description} |
| 17492 |
|
| 17493 |
The \optfmt{\meta{method}\dhyphen reverse} options reverse the |
| 17494 |
result returned by the corresponding \meta{method} comparator. |
| 17495 |
However \optfmt{\meta{method}\dhyphen reverse} may not produce a |
| 17496 |
list that's the exact reverse of the underlying non-reversed |
| 17497 |
\meta{method} as the \hierarchical\ structure or associated settings |
| 17498 |
can affect the order. |
| 17499 |
|
| 17500 |
\begin{table}[p] |
| 17501 |
\caption{Summary of Available Sort Options: No Sort Field} |
| 17502 |
\label{tab:sortoptionsnosort} |
| 17503 |
\centering |
| 17504 |
\begin{tabular}{ll} |
| 17505 |
\optfmt{none} or \optfmt{unsrt} & don't sort\tabularnewline |
| 17506 |
\optfmt{random} & shuffle entries\tabularnewline |
| 17507 |
\optfmt{use} & order of use\tabularnewline |
| 17508 |
\optfmt{use-reverse} & reverse order of use\tabularnewline |
| 17509 |
\optfmt{recordcount}\textsuperscript\textdagger & order of record count\tabularnewline |
| 17510 |
\optfmt{recordcount-reverse}\textsuperscript\textdagger & reverse order of record count |
| 17511 |
\end{tabular} |
| 17512 |
\par |
| 17513 |
\medskip |
| 17514 |
\textsuperscript\textdagger Requires \longarg{record-count} switch. |
| 17515 |
\end{table} |
| 17516 |
|
| 17517 |
\begin{table}[p] |
| 17518 |
\caption{Summary of Available Sort Options: Alphabet} |
| 17519 |
\label{tab:sortoptionsrule} |
| 17520 |
\centering |
| 17521 |
\begin{tabular}{ll} |
| 17522 |
\meta{lang tag} & sort according to this language tag\tabularnewline |
| 17523 |
\meta{lang tag}\optfmt{-reverse} & reverse sort according to this language tag\tabularnewline |
| 17524 |
\optfmt{resource} & sort according to the default |
| 17525 |
\gls{resource-locale}\tabularnewline |
| 17526 |
\optfmt{resource-reverse} & reverse sort according to the default |
| 17527 |
\gls{resource-locale}\tabularnewline |
| 17528 |
\optfmt{doc} & sort according to the \gls{document-locale}\tabularnewline |
| 17529 |
\optfmt{doc-reverse} & reverse sort according to the |
| 17530 |
\gls{document-locale}\tabularnewline |
| 17531 |
\optfmt{locale} & sort according to the default |
| 17532 |
\gls{Java-locale}\tabularnewline |
| 17533 |
\optfmt{locale-reverse} & reverse sort according to the default |
| 17534 |
\gls{Java-locale}\tabularnewline |
| 17535 |
\optfmt{custom} & sort according to \csopt[\meta{custom |
| 17536 |
rule}]{sort-rule}\tabularnewline |
| 17537 |
\optfmt{custom-reverse} & reverse sort according to \csopt[\meta{custom rule}]{sort-rule} |
| 17538 |
\end{tabular} |
| 17539 |
\end{table} |
| 17540 |
|
| 17541 |
\begin{table}[p] |
| 17542 |
\caption{Summary of Available Sort Options: Letter (Non-Locale)} |
| 17543 |
\label{tab:sortoptionsletter} |
| 17544 |
\centering |
| 17545 |
\begin{tabular}{ll} |
| 17546 |
\optfmt{letter-case} & case-sensitive letter sort\tabularnewline |
| 17547 |
\optfmt{letter-case-reverse} & reverse case-sensitive letter |
| 17548 |
sort\tabularnewline |
| 17549 |
\optfmt{letter-nocase} & case-insensitive letter sort\tabularnewline |
| 17550 |
\optfmt{letter-nocase-reverse} & reverse case-insensitive letter |
| 17551 |
sort\tabularnewline |
| 17552 |
\optfmt{letter-upperlower} & upper-lower letter sort\tabularnewline |
| 17553 |
\optfmt{letter-upperlower-reverse} & reverse upper-lower letter |
| 17554 |
sort\tabularnewline |
| 17555 |
\optfmt{letter-lowerupper} & lower-upper letter sort\tabularnewline |
| 17556 |
\optfmt{letter-lowerupper-reverse} & reverse lower-upper letter sort |
| 17557 |
\end{tabular} |
| 17558 |
\end{table} |
| 17559 |
|
| 17560 |
\begin{table}[p] |
| 17561 |
\caption{Summary of Available Sort Options: Letter-Number} |
| 17562 |
\label{tab:sortoptionsletternumber} |
| 17563 |
\centering |
| 17564 |
\begin{tabular}{ll} |
| 17565 |
\optfmt{letternumber-case} & case-sensitive letter-number |
| 17566 |
sort\tabularnewline |
| 17567 |
\optfmt{letternumber-case-reverse} & reverse case-sensitive |
| 17568 |
letter-number sort\tabularnewline |
| 17569 |
\optfmt{letternumber-nocase} & case-insensitive letter-number |
| 17570 |
sort\tabularnewline |
| 17571 |
\optfmt{letternumber-nocase-reverse} & reverse case-insensitive |
| 17572 |
letter-number sort\tabularnewline |
| 17573 |
\optfmt{letternumber-upperlower} & upper-lower letter-number |
| 17574 |
sort\tabularnewline |
| 17575 |
\optfmt{letternumber-upperlower-reverse} & reverse upper-lower |
| 17576 |
letter-number sort\tabularnewline |
| 17577 |
\optfmt{letternumber-lowerupper} & lower-upper letter-number |
| 17578 |
sort\tabularnewline |
| 17579 |
\optfmt{letternumber-lowerupper-reverse} & reverse lower-upper letter-number sort |
| 17580 |
\end{tabular} |
| 17581 |
\end{table} |
| 17582 |
|
| 17583 |
\begin{table}[p] |
| 17584 |
\caption{Summary of Available Sort Options: Numerical} |
| 17585 |
\label{tab:sortoptionsnumerical} |
| 17586 |
\centering |
| 17587 |
\begin{tabular}{ll} |
| 17588 |
\optfmt{integer} & integer sort\tabularnewline |
| 17589 |
\optfmt{integer-reverse} & reverse integer sort\tabularnewline |
| 17590 |
\optfmt{hex} & hexadecimal sort\tabularnewline |
| 17591 |
\optfmt{hex-reverse} & reverse hexadecimal sort\tabularnewline |
| 17592 |
\optfmt{octal} & octal sort\tabularnewline |
| 17593 |
\optfmt{octal-reverse} & reverse octal sort\tabularnewline |
| 17594 |
\optfmt{binary} & binary sort\tabularnewline |
| 17595 |
\optfmt{binary-reverse} & reverse binary sort\tabularnewline |
| 17596 |
\optfmt{float} & float sort\tabularnewline |
| 17597 |
\optfmt{float-reverse} & reverse float sort\tabularnewline |
| 17598 |
\optfmt{double} & double sort\tabularnewline |
| 17599 |
\optfmt{double-reverse} & reverse double sort\tabularnewline |
| 17600 |
\optfmt{numeric} & locale-sensitive numeric sort\tabularnewline |
| 17601 |
\optfmt{numeric-reverse} & reverse locale-sensitive numeric |
| 17602 |
sort\tabularnewline |
| 17603 |
\optfmt{currency} & locale-sensitive currency sort\tabularnewline |
| 17604 |
\optfmt{currency-reverse} & reverse locale-sensitive currency |
| 17605 |
sort\tabularnewline |
| 17606 |
\optfmt{percent} & locale-sensitive percent sort\tabularnewline |
| 17607 |
\optfmt{percent-reverse} & reverse locale-sensitive percent |
| 17608 |
sort\tabularnewline |
| 17609 |
\optfmt{numberformat} & locale-sensitive custom numeric |
| 17610 |
sort\tabularnewline |
| 17611 |
\optfmt{numberformat-reverse} & reverse locale-sensitive custom numeric sort |
| 17612 |
\end{tabular} |
| 17613 |
\end{table} |
| 17614 |
|
| 17615 |
\begin{table}[p] |
| 17616 |
\caption{Summary of Available Sort Options: Date-Time} |
| 17617 |
\label{tab:sortoptionsdatetime} |
| 17618 |
\centering |
| 17619 |
\begin{tabular}{ll} |
| 17620 |
\optfmt{date} & locale-sensitive date sort\tabularnewline |
| 17621 |
\optfmt{date-reverse} & reverse locale-sensitive date |
| 17622 |
sort\tabularnewline |
| 17623 |
\optfmt{datetime} & locale-sensitive date-time sort\tabularnewline |
| 17624 |
\optfmt{datetime-reverse} & reverse locale-sensitive date-time |
| 17625 |
sort\tabularnewline |
| 17626 |
\optfmt{time} & locale-sensitive time sort\tabularnewline |
| 17627 |
\optfmt{time-reverse} & reverse locale-sensitive time sort |
| 17628 |
\end{tabular} |
| 17629 |
\end{table} |
| 17630 |
|
| 17631 |
\subsubsection{No Sort Field} |
| 17632 |
|
| 17633 |
Most of the sort methods listed in \tableref{tab:sortoptionsnosort} |
| 17634 |
don't actually perform any sorting. This may cause a problem for |
| 17635 |
\hierarchical\ entries. In some cases this can lead to detached |
| 17636 |
\glspl{childentry} or an attempt to define a \gls{childentry} before its \parent. |
| 17637 |
The methods listed in this section all ignore the \csopt{sort-field} |
| 17638 |
setting and all the various sort fallback settings, except where |
| 17639 |
noted below. |
| 17640 |
\begin{itemize} |
| 17641 |
|
| 17642 |
\item \optfmt{none} (or \optfmt{unsrt}): don't sort the entries. |
| 17643 |
(The entries will be in the order they were processed when parsing |
| 17644 |
the data.) |
| 17645 |
|
| 17646 |
If you need to order by definition but also maintain \hierarchy\ then use: |
| 17647 |
\begin{codeenv} |
| 17648 |
\csopt{save-definition-index}, |
| 17649 |
\csopt[\field{definitionindex}]{sort-field}, |
| 17650 |
\csopt[integer]{sort} |
| 17651 |
\end{codeenv} |
| 17652 |
|
| 17653 |
\item \optfmt{random}: shuffles rather than sorts the entries. |
| 17654 |
This won't work if there are \hierarchical\ entries, so it's best |
| 17655 |
to use this option with \csopt{flatten}. The seed for the |
| 17656 |
random generator can be set using \csopt{shuffle} (which |
| 17657 |
also automatically sets \csopt[random]{sort} and \csopt{flatten}). |
| 17658 |
|
| 17659 |
\item \optfmt{use}: order of use. This order is determined |
| 17660 |
by the \glspl{record} written to the \iext{aux} file by the \styopt{record} |
| 17661 |
package option. Dependencies and cross-references (including those |
| 17662 |
identified with \ics{glssee}) come after entries with \glspl{record}. |
| 17663 |
|
| 17664 |
Note that this is different from using the analogous option with |
| 17665 |
\idx{makeindex} or \idx{xindy}, which does actually sort |
| 17666 |
numerically, where each entry has an associated number set on the |
| 17667 |
first use of that term that's used as the sort value. |
| 17668 |
|
| 17669 |
If you need to order by use but also maintain \hierarchy\ then use: |
| 17670 |
\begin{codeenv} |
| 17671 |
\csopt{save-use-index}, |
| 17672 |
\csopt[\field{useindex}]{sort-field}, |
| 17673 |
\csopt[integer]{sort} |
| 17674 |
\end{codeenv} |
| 17675 |
|
| 17676 |
\item \optfmt{use-reverse}: reverses the order that would be |
| 17677 |
obtained with \csopt[use]{sort} without reference to \hierarchy. |
| 17678 |
|
| 17679 |
\item \optfmt{recordcount}: order of \gls{recordcount} (starting from 0). This order is |
| 17680 |
determined by the total number of records written to the \iext{aux} |
| 17681 |
file for each entry. Unlike the above methods, this performs a \hierarchical\ sort. |
| 17682 |
If letter groups are enabled with \longarg{group}, this method will assign the entries to |
| 17683 |
the \idx{numbergroup}. |
| 17684 |
|
| 17685 |
This option requires the \longarg{record-count} switch. Although |
| 17686 |
that switch makes \bibgls\ write the total \gls{recordcount} to the |
| 17687 |
\ext{glstex} file in the \field{recordcount} internal field (so that it |
| 17688 |
can be accessed in the document), \bibgls\ doesn't actually have a |
| 17689 |
field itself that contains the information. So although this option |
| 17690 |
behaves much like \csopt[integer]{sort} it's not possible to select |
| 17691 |
a field containing the required value. In the event of two or more |
| 17692 |
entries having the same \gls{recordcount}, the |
| 17693 |
\csopt{identical-sort-action} option is used to determine the |
| 17694 |
relative ordering between them. |
| 17695 |
|
| 17696 |
\item \optfmt{recordcount-reverse}: reverse order of \gls{recordcount} |
| 17697 |
(ending with 0). All the above notes applying to |
| 17698 |
\optfmt{recordcount} also apply here. |
| 17699 |
|
| 17700 |
\end{itemize} |
| 17701 |
|
| 17702 |
Suppose the file \filefmt{entries.bib} contains |
| 17703 |
definitions of a set of symbols that don't have any intuitive |
| 17704 |
ordering (for example, they are all pictographs) then there may be |
| 17705 |
no point in trying to order them, in which case you can do: |
| 17706 |
\begin{codeenv} |
| 17707 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[none]{sort}} |
| 17708 |
\end{codeenv} |
| 17709 |
Alternatively, you could list them in order of use: |
| 17710 |
\begin{codeenv} |
| 17711 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[use]{sort}} |
| 17712 |
\end{codeenv} |
| 17713 |
or by frequency of use. For example, starting with entries that |
| 17714 |
don't have any records followed by the least used entries (a rarely-used symbol |
| 17715 |
may be harder to remember and most likely to be looked up in the glossary): |
| 17716 |
\begin{codeenv} |
| 17717 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[recordcount]{sort}} |
| 17718 |
\end{codeenv} |
| 17719 |
Or starting with the most used entries: |
| 17720 |
\begin{codeenv} |
| 17721 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[recordcount-reverse]{sort}} |
| 17722 |
\end{codeenv} |
| 17723 |
It all depends on what's likely to be most useful to the reader. |
| 17724 |
|
| 17725 |
Consider the following: |
| 17726 |
\begin{codeenv} |
| 17727 |
\ics{newglossary*}\marg{frequent}\marg{Most Frequently Used Terms} |
| 17728 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[use]{sort}, |
| 17729 |
\csopt[recordcount-reverse:frequent]{secondary} |
| 17730 |
} |
| 17731 |
\cs{newcommand}\marg{\csfmt{filterhook}}[1]\marg{\comment{} |
| 17732 |
\ics{GlsXtrIfFieldCmpNum}*\marg{\field{recordcount}}\marg{\idx{hashchar}1}\marg{>}\marg{10}\comment{} |
| 17733 |
\marg{}\comment{} |
| 17734 |
\marg{\ics{printunsrtglossaryskipentry}}\comment{} |
| 17735 |
} |
| 17736 |
\csfmt{begin}\marg{document} |
| 17737 |
\cs{printunsrtglossary*}\oarg{\printglossopt[false]{target},\printglossopt[frequent]{type}}\marg{\comment{} |
| 17738 |
\cs{let}\ics{printunsrtglossaryentryprocesshook}\csfmt{filterhook} |
| 17739 |
} |
| 17740 |
\comment{Main body of the document \ldots} |
| 17741 |
\cs{printunsrtglossary} |
| 17742 |
\csfmt{end}\marg{document} |
| 17743 |
\end{codeenv} |
| 17744 |
This has a summary at the start of the document that only contains |
| 17745 |
entries that have at least 10 records and is ordered according to |
| 17746 |
the total number of records (starting with the most frequently used |
| 17747 |
entry). The \gls{mainglossary} at the end of the document is ordered |
| 17748 |
according to use and contains all selected entries. |
| 17749 |
|
| 17750 |
Compare this with the following: |
| 17751 |
\begin{codeenv} |
| 17752 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[use]{sort}} |
| 17753 |
\cs{newcommand}\marg{\csfmt{filterhook}}[1]\marg{\comment{} |
| 17754 |
\ics{GlsXtrIfFieldCmpNum}*\marg{\field{recordcount}}\marg{\idx{hashchar}1}\marg{>}\marg{10}\comment{} |
| 17755 |
\marg{}\comment{} |
| 17756 |
\marg{\ics{printunsrtglossaryskipentry}}\comment{} |
| 17757 |
} |
| 17758 |
\csfmt{begin}\marg{document} |
| 17759 |
\cs{printunsrtglossary*}\oarg{\printglossopt[false]{target}, |
| 17760 |
\printglossopt[Most Frequently Used Terms]{title}}\marg{\comment{} |
| 17761 |
\cs{let}\ics{printunsrtglossaryentryprocesshook}\csfmt{filterhook} |
| 17762 |
} |
| 17763 |
\comment{Main body of the document \ldots} |
| 17764 |
\cs{printunsrtglossary} |
| 17765 |
\csfmt{end}\marg{document} |
| 17766 |
\end{codeenv} |
| 17767 |
This again has a summary at the start of the document that only |
| 17768 |
contains entries that have at least 10 records but is now ordered |
| 17769 |
according to use. |
| 17770 |
|
| 17771 |
Both examples assume there are no \glspl{childentry} as the filtering can |
| 17772 |
cause \glspl{parententry} to be omitted. Both examples require |
| 17773 |
\longarg{record-count} but only the first example sorts according to |
| 17774 |
the \gls{recordcount}. |
| 17775 |
|
| 17776 |
\subsubsection{Alphabet} |
| 17777 |
|
| 17778 |
The sort methods listed in \tableref{tab:sortoptionsrule} are for |
| 17779 |
alphabets that are defined by a rule. These usually ignore most |
| 17780 |
punctuation and may ignore modifiers (such as accents). Use with |
| 17781 |
\csopt{break-at} to determine whether or not to split at word |
| 17782 |
boundaries. The collation rules (except for the custom options) are obtained |
| 17783 |
from the \idx{localeprovider} (see page~\pageref{locale.provider}). |
| 17784 |
|
| 17785 |
\begin{itemize} |
| 17786 |
\item \meta{lang tag}: sort according to the rules of the locale |
| 17787 |
given by the \idx{IETF} language tag \meta{lang tag}. |
| 17788 |
|
| 17789 |
\item \meta{lang tag}\optfmt{-reverse}: reverse sort according to the rules of the locale |
| 17790 |
given by the \idx{IETF} language tag \meta{lang tag}. |
| 17791 |
|
| 17792 |
\item \optfmt{resource}: equivalent to |
| 17793 |
\csopt[\meta{lang tag}]{sort} where \meta{lang tag} is obtained |
| 17794 |
from the default \gls{resource-locale}. |
| 17795 |
|
| 17796 |
\item \optfmt{resource-reverse}: equivalent to |
| 17797 |
\csopt[\meta{lang tag}-reverse]{sort} where \meta{lang tag} is obtained |
| 17798 |
from the default \gls{resource-locale}. |
| 17799 |
|
| 17800 |
\item \optfmt{locale}: equivalent to |
| 17801 |
\csopt[\meta{lang tag}]{sort} where \meta{lang tag} is obtained |
| 17802 |
from the \gls{Java-locale} (which usually matches the |
| 17803 |
operating system's locale). |
| 17804 |
|
| 17805 |
\item \optfmt{locale-reverse}: equivalent to |
| 17806 |
\csopt[\meta{lang tag}-reverse]{sort} where \meta{lang tag} is obtained |
| 17807 |
from the \gls{Java-locale}. |
| 17808 |
|
| 17809 |
\item \optfmt{doc}: sort the entries according to the |
| 17810 |
\gls{document-locale}. This is equivalent to \csopt[\meta{lang tag}]{sort} |
| 17811 |
where \meta{lang tag} is the locale associated with the document |
| 17812 |
language. In the case of a multi-lingual document, \meta{lang tag} |
| 17813 |
is the locale of the last language resource file to be loaded through |
| 17814 |
\isty{tracklang}'s interface. It's best to explicitly set the locale |
| 17815 |
for multi-lingual documents to avoid confusion. If no document |
| 17816 |
language has been set, this option is equivalent to \csopt[locale]{sort}. |
| 17817 |
|
| 17818 |
\item \optfmt{doc-reverse}: as \optfmt{doc} but in reverse order. |
| 17819 |
|
| 17820 |
\item \optfmt{custom}: sort the entries according to the |
| 17821 |
rule provided by \csopt{sort-rule}. |
| 17822 |
|
| 17823 |
\item \optfmt{custom-reverse}: reverse sort the entries according to the |
| 17824 |
rule provided by \csopt{sort-rule}. |
| 17825 |
\end{itemize} |
| 17826 |
|
| 17827 |
Note that \csopt[\meta{lang tag}]{sort} can provide more detail about the |
| 17828 |
given locale than \csopt[doc]{sort}, depending on how the document |
| 17829 |
language has been specified. For example, with: |
| 17830 |
\begin{codeenv} |
| 17831 |
\cmd{documentclass}\marg{article} |
| 17832 |
\cmd{usepackage}\oarg{ngerman}\marg{babel} |
| 17833 |
\cmd{usepackage}\oarg{\styopt{record}}\marg{glossaries} |
| 17834 |
\gls{GlsXtrLoadResources}\oarg{\csopt[german-terms]{src}} |
| 17835 |
\end{codeenv} |
| 17836 |
the language tag will be \code{de-1996}, which doesn't have an |
| 17837 |
associated region, so this is equivalent to using \csopt[de-1996]{sort}. |
| 17838 |
Whereas with: |
| 17839 |
\begin{codeenv} |
| 17840 |
\cmd{documentclass}\oarg{de-DE-1996}\marg{article} |
| 17841 |
\cmd{usepackage}\oarg{ngerman}\marg{babel} |
| 17842 |
\cmd{usepackage}\oarg{\styopt{record}}\marg{glossaries} |
| 17843 |
\gls{GlsXtrLoadResources}\oarg{\csopt[german-terms]{src}} |
| 17844 |
\end{codeenv} |
| 17845 |
the language tag will be \code{de-DE-1996} because \isty{tracklang} |
| 17846 |
has picked up the locale from the document class options, so this is |
| 17847 |
equivalent to using \csopt[de-DE-1996]{sort}. This is |
| 17848 |
only likely to cause a difference if a language has different |
| 17849 |
sorting rules according to the region or if the language may be |
| 17850 |
written in multiple scripts. |
| 17851 |
|
| 17852 |
If no \gls{document-locale} has been set and the |
| 17853 |
\csopt{locale} resource option hasn't been used |
| 17854 |
then the \csopt[resource]{sort} and \csopt[doc]{sort} |
| 17855 |
will be equivalent to \csopt[locale]{sort}. |
| 17856 |
For example, with: |
| 17857 |
\begin{codeenv} |
| 17858 |
\cmd{documentclass}\marg{article} |
| 17859 |
\cmd{usepackage}\oarg{\styopt{record}}\marg{glossaries} |
| 17860 |
\gls{GlsXtrLoadResources}\oarg{\csopt[german-terms]{src}} |
| 17861 |
\end{codeenv} |
| 17862 |
the language tag will be whatever is the default locale for the \idx{JVM}. |
| 17863 |
For a user in Germany, this could be \code{de-DE-1996} and for a user |
| 17864 |
in Austria this could be \code{de-AT-1996}. |
| 17865 |
|
| 17866 |
A multilingual document will need to have the \csopt{sort} specified |
| 17867 |
when loading the \idx{resourceset} to ensure the correct language is chosen. |
| 17868 |
For example: |
| 17869 |
\begin{codeenv} |
| 17870 |
\gls{GlsXtrLoadResources}\oarg{\csopt[english-terms]{src},\csopt[en-GB]{sort}} |
| 17871 |
\gls{GlsXtrLoadResources}\oarg{\csopt[german-terms]{src},\csopt[de-DE-1996]{sort}} |
| 17872 |
\end{codeenv} |
| 17873 |
|
| 17874 |
Alternatively (as from \bibgls\ v3.3), use \csopt{locale}: |
| 17875 |
\begin{codeenv} |
| 17876 |
\gls{GlsXtrLoadResources}\oarg{\csopt[en-GB]{locale},\csopt[english-terms]{src}} |
| 17877 |
\gls{GlsXtrLoadResources}\oarg{\csopt[de-DE-1996]{locale},\csopt[german-terms]{src}} |
| 17878 |
\end{codeenv} |
| 17879 |
|
| 17880 |
\subsubsection{Letter (Non Locale)} |
| 17881 |
|
| 17882 |
The sort methods listed in \tableref{tab:sortoptionsletter} |
| 17883 |
use letter comparators. These simply compare the |
| 17884 |
character codes. The \optfmt{-nocase} options first convert the |
| 17885 |
\field{sort} field to \idx{lowercase} before performing the sort to |
| 17886 |
provide a case-insensitive comparison. |
| 17887 |
|
| 17888 |
Punctuation isn't ignored. |
| 17889 |
Use \csopt[\meta{lang tag}]{sort} with \csopt[none]{break-at} to |
| 17890 |
emulate \idx!{xindy}['s] locale letter ordering. The examples below |
| 17891 |
show the ordering of the list \code{antelope}, \code{bee}, \code{Africa}, |
| 17892 |
\code{aardvark} and \code{Brazil}. |
| 17893 |
\begin{itemize} |
| 17894 |
\item \optfmt{letter-case}: case-sensitive letter sort. |
| 17895 |
\Idx{uppercase} and \idx{lowercase} are in separate letter groups. |
| 17896 |
Example: |
| 17897 |
|
| 17898 |
\code{Africa} (letter group \idx{uppercase} \qt{A}), \code{Brazil} |
| 17899 |
(letter group \idx{uppercase} \qt{B}), \code{aardvark} (letter group |
| 17900 |
\idx{lowercase} \qt{a}), \code{antelope} (letter group |
| 17901 |
\idx{lowercase} \qt{a}), \code{bee} (letter group \idx{lowercase} \qt{b}). |
| 17902 |
|
| 17903 |
\item \optfmt{letter-case-reverse}: reverse case-sensitive letter sort. |
| 17904 |
Example: |
| 17905 |
|
| 17906 |
\code{bee} (letter group \idx{lowercase} \qt{b}), \code{antelope} |
| 17907 |
(letter group \idx{lowercase} \qt{a}), \code{aardvark} (letter group |
| 17908 |
\idx{lowercase} \qt{a}) \code{Brazil} (letter group \idx{uppercase} |
| 17909 |
\qt{B}), \code{Africa} (letter group \idx{uppercase} \qt{A}). |
| 17910 |
|
| 17911 |
\item \optfmt{letter-nocase}: case-insensitive letter sort. (All |
| 17912 |
\idx{uppercase} characters will have first been converted to |
| 17913 |
\idx{lowercase} in the sort value.) |
| 17914 |
Example: |
| 17915 |
|
| 17916 |
\code{aardvark} (letter group \qt{A}), \code{Africa} |
| 17917 |
(letter group \qt{A}), \code{antelope} (letter group \qt{A}), |
| 17918 |
\code{bee} (letter group \qt{B}), |
| 17919 |
\code{Brazil} (letter group \qt{B}). |
| 17920 |
|
| 17921 |
\item \optfmt{letter-nocase-reverse}: reverse case-insensitive letter sort. |
| 17922 |
Example: |
| 17923 |
|
| 17924 |
\code{Brazil} (letter group \qt{B}), \code{bee} (letter group |
| 17925 |
\qt{B}), \code{antelope} (letter group \qt{A}), \code{Africa} |
| 17926 |
(letter group \qt{A}), \code{aardvark} (letter group \qt{A}). |
| 17927 |
|
| 17928 |
\item \optfmt{letter-upperlower}: each character pair is first |
| 17929 |
compared according to their \idx{lowercase} values. If these are equal, |
| 17930 |
then they are compared according to case. This puts upper and lower |
| 17931 |
case in the same letter group but the \idx{uppercase} comes first. |
| 17932 |
Example: |
| 17933 |
|
| 17934 |
\code{Africa} (letter group \qt{A}), \code{aardvark} (letter group |
| 17935 |
\qt{A}), \code{antelope} (letter group \qt{A}), \code{Brazil} |
| 17936 |
(letter group \qt{B}), \code{bee} (letter group \qt{B}). |
| 17937 |
|
| 17938 |
\item \optfmt{letter-upperlower-reverse}: reverse upper-lower letter sort. |
| 17939 |
This now puts the \idx{lowercase} letters first within the letter group. |
| 17940 |
Example: |
| 17941 |
|
| 17942 |
\code{bee} (letter group \qt{B}), \code{Brazil} (letter group |
| 17943 |
\qt{B}), \code{antelope} (letter group \qt{A}), \code{aardvark} |
| 17944 |
(letter group \qt{A}), \code{Africa} (letter group \qt{A}). |
| 17945 |
|
| 17946 |
\item \optfmt{letter-lowerupper}: each character pair is first |
| 17947 |
compared according to their \idx{lowercase} values. If these are equal, |
| 17948 |
then they are compared according to case. This puts |
| 17949 |
\idxlink{uppercase}{upper} and \idx{lowercase} in the same letter group but the \idx{lowercase} comes first. |
| 17950 |
Example: |
| 17951 |
|
| 17952 |
\code{aardvark} (letter group \qt{A}), \code{antelope} (letter group \qt{A}), |
| 17953 |
\code{Africa} (letter group \qt{A}), \code{bee} (letter group |
| 17954 |
\qt{B}), \code{Brazil} (letter group \qt{B}). |
| 17955 |
|
| 17956 |
\item \optfmt{letter-lowerupper-reverse}: reverse lower-upper letter sort. |
| 17957 |
This now puts the \idx{uppercase} letters first within the letter group. |
| 17958 |
Example: |
| 17959 |
|
| 17960 |
\code{Brazil} (letter group \qt{B}), \code{bee} (letter group |
| 17961 |
\qt{B}), \code{Africa} (letter group \qt{A}), \code{antelope} |
| 17962 |
(letter group \qt{A}), \code{aardvark} (letter group \qt{A}). |
| 17963 |
|
| 17964 |
\end{itemize} |
| 17965 |
|
| 17966 |
\subsubsection{Letter-Number} |
| 17967 |
\label{sec:letternumber} |
| 17968 |
|
| 17969 |
The sort methods listed in \tableref{tab:sortoptionsletternumber} |
| 17970 |
use a letter-integer hybrid. They behave in a similar way to the |
| 17971 |
above letter sort methods, but if an integer number pattern is detected in |
| 17972 |
the string then the sub-string containing the number will be compared. |
| 17973 |
This only detects base 10 integers (unlike the numeric methods |
| 17974 |
such as \csopt[hexadecimal]{sort} or \csopt[float]{sort}) but in |
| 17975 |
addition to recognising all the digits in the Unicode \idx{numberdecimaldigit} |
| 17976 |
category it also recognises the subscript and |
| 17977 |
superscript digits, such as \textsuperscript{1} (\hex{00B9}) |
| 17978 |
and \textsuperscript{2} (\hex{00B2}). |
| 17979 |
|
| 17980 |
As with the letter sort methods, letters are compared using a |
| 17981 |
character code comparison not by a locale alphabet. The closest |
| 17982 |
locale-sensitive equivalent is to use \csopt{sort-number-pad} with a |
| 17983 |
locale sort method. Alternatively, use \ics{IfTeXParserLib} or |
| 17984 |
\ics{IfNotBibGls} and |
| 17985 |
\ics{bibglspaddigits} to pad the number for the interpreter but |
| 17986 |
not in the \TeX\ document. |
| 17987 |
|
| 17988 |
\begin{figure} |
| 17989 |
\figcontents |
| 17990 |
{% |
| 17991 |
\begin{tikzpicture}[every node/.style={minimum size=9mm}, |
| 17992 |
ampersand replacement=\&] |
| 17993 |
\matrix[font={\Large\ttfamily}] |
| 17994 |
{ |
| 17995 |
\node[draw]{a\hexsb{61}}; \& \node{$=$}; \& \node[draw]{a\hexsb{61}}; \&[20mm] |
| 17996 |
\node[draw]{a\hexsb{61}}; \& \node{$=$}; \& \node[draw]{a\hexsb{61}}; |
| 17997 |
\\ |
| 17998 |
\node[draw]{b\hexsb{62}}; \& \node{$=$}; \& \node[draw]{b\hexsb{62}}; \& |
| 17999 |
\node[draw]{b\hexsb{62}}; \& \node{$=$}; \& \node[draw]{b\hexsb{62}}; |
| 18000 |
\\ |
| 18001 |
\node[draw]{c\hexsb{63}}; \& \node{$=$}; \& \node[draw]{c\hexsb{63}}; \& |
| 18002 |
\node[draw]{c\hexsb{63}}; \& \node{$=$}; \& \node[draw]{c\hexsb{63}}; |
| 18003 |
\\ |
| 18004 |
\node[draw,ultra thick]{1\hexsb{31}}; \& \node{$<$}; \& |
| 18005 |
\node[draw,ultra thick]{6\hexsb{36}}; \& |
| 18006 |
\node (n1) {1}; \& \node{$>$}; \& \node[draw,ultra thick]{6}; |
| 18007 |
\\ |
| 18008 |
\node[draw]{2\hexsb{32}}; \& \& \node[draw]{b\hexsb{62}}; \& |
| 18009 |
\node (n2) {2}; \& \& \node[draw]{b\hexsb{62}}; |
| 18010 |
\\ |
| 18011 |
\node[draw]{f\hexsb{66}}; \& \& \node[draw]{a\hexsb{61}}; \& |
| 18012 |
\node[draw]{f\hexsb{66}}; \& \& \node[draw]{a\hexsb{61}}; |
| 18013 |
\\ |
| 18014 |
\node[draw]{o\hexsb{6f}}; \& \& \node[draw]{r\hexsb{72}}; \& |
| 18015 |
\node[draw]{o\hexsb{6f}}; \& \& \node[draw]{r\hexsb{72}}; |
| 18016 |
\\ |
| 18017 |
\node[draw]{o\hexsb{6f}}; \& \& \& |
| 18018 |
\node[draw]{o\hexsb{6f}}; \& \& |
| 18019 |
\\[10pt] |
| 18020 |
\& \node[font=\rmfamily]{\subfigfmt{a}}; \& \& |
| 18021 |
\& \node[font=\rmfamily]{\subfigfmt{b}}; \& |
| 18022 |
\\ |
| 18023 |
}; |
| 18024 |
\draw[ultra thick] (n1.north east) rectangle (n2.south west); |
| 18025 |
\end{tikzpicture}% |
| 18026 |
} |
| 18027 |
{% |
| 18028 |
\caption[Regular letter comparison vs letter-number |
| 18029 |
comparison]{Regular letter comparison vs letter-number comparison. |
| 18030 |
Comparing the strings \code{abc12foo} and \code{abc6bar}: |
| 18031 |
\subfigfmt{a} \optfmt{letter-case}; \subfigfmt{b} |
| 18032 |
\optfmt{letternumber-case}.}% |
| 18033 |
} |
| 18034 |
{fig:letternumber} |
| 18035 |
\end{figure} |
| 18036 |
|
| 18037 |
For example, suppose the first string is \code{abc12foo} |
| 18038 |
and the second string is \code{abc6bar}. |
| 18039 |
\Figureref{fig:letternumber}\subfigfmt{a} shows the regular letter |
| 18040 |
comparison using \csopt[letter-case]{sort}, where the subscript |
| 18041 |
indicates the hexadecimal character code. The first three characters |
| 18042 |
from each string are identical (\code{abc}). At this point there's |
| 18043 |
no difference detected, so the comparator moves on to the next |
| 18044 |
character, \code{1\hexsb{31}} for the first string and |
| 18045 |
\code{6\hexsb{36}} for the second string. Since \hex{31} is less than |
| 18046 |
\hex{36}, the first string (\code{abc12foo}) is considered less than the second |
| 18047 |
(\code{abc6bar}). |
| 18048 |
|
| 18049 |
With the letter-number comparison using |
| 18050 |
\csopt[letternumber-case]{sort}, the comparator starts in much the |
| 18051 |
same way. The first three characters from each string are still |
| 18052 |
identical, so the comparator moves on to the next character, |
| 18053 |
\code{1} for the first string and \code{6} for the second. |
| 18054 |
These are now both recognised as digits, so the comparator |
| 18055 |
looks ahead and reads in any following digits (if present). For the |
| 18056 |
first case, this is the sub-string \code{12} and, for the second |
| 18057 |
case, \code{6} (\figureref{fig:letternumber}\subfigfmt{b}). These |
| 18058 |
are both compared according to their integer representation $12 > |
| 18059 |
6$, so \code{abc12bar} is considered greater than \code{abc6foo} |
| 18060 |
(that is, \code{abc12bar} comes after \code{abc6foo}). |
| 18061 |
|
| 18062 |
The same result occurs for other numbering systems, for example if |
| 18063 |
the Basic Latin digits 1, 2 and 6 are replaced with the |
| 18064 |
corresponding Devanagari digits \devone, \devtwo\ and |
| 18065 |
\devsix. (But note that the letter comparisons will still be |
| 18066 |
based on their Unicode values not according to a particular locale. |
| 18067 |
This type of sort method is intended primarily for symbolic values, |
| 18068 |
such as chemical formulae, rather than for words or phrases.) |
| 18069 |
|
| 18070 |
Signed integers are also recognised, so \code{abc-12foo} is less |
| 18071 |
than \code{abc+6bar}, which is again different from the result |
| 18072 |
obtained with a straight letter comparator where the |
| 18073 |
character~\code{+} (\hex{2B}) |
| 18074 |
comes before the character~\code{-} (\hex{2D}). The sign must be followed by at |
| 18075 |
least one digit for it to be recognised as a number otherwise it's |
| 18076 |
treated as a punctuation character. |
| 18077 |
|
| 18078 |
If only one sub-string is numeric |
| 18079 |
then the \csopt{letter-number-rule} is used to determine the |
| 18080 |
result. Where both sub-strings are non-numeric, then the |
| 18081 |
\csopt{letter-number-punc-rule} setting is used to determine the result |
| 18082 |
according to the category of the characters, which may be one of the |
| 18083 |
following: |
| 18084 |
\begin{itemize} |
| 18085 |
\item white space: belongs to the Unicode \idx{separatorspace} |
| 18086 |
category. If both characters are white space, then they are compared |
| 18087 |
according to their Unicode values otherwise they are ordered according to |
| 18088 |
the \csopt{letter-number-punc-rule} setting. |
| 18089 |
|
| 18090 |
\item letter: belongs to one of the Unicode categories \idx{letteruppercase}, |
| 18091 |
\idx{letterlowercase}, \idx{lettertitlecase}, |
| 18092 |
\idx{lettermodifier} or \idx{letterother}. If both characters |
| 18093 |
are letters then, for sort method \optfmt{letternumber-\meta{modifier}}, |
| 18094 |
the characters are compared in the same way as the |
| 18095 |
corresponding \optfmt{letter-\meta{modifier}} sort method otherwise |
| 18096 |
they are ordered according to the |
| 18097 |
\csopt{letter-number-punc-rule} setting. |
| 18098 |
|
| 18099 |
\item punctuation: everything else. If both characters are |
| 18100 |
punctuation, then they are compared according to their Unicode value |
| 18101 |
otherwise they are ordered according to |
| 18102 |
the \csopt{letter-number-punc-rule} setting. |
| 18103 |
\end{itemize} |
| 18104 |
For simplicity, the actual sort value used during sorting isn't a |
| 18105 |
simple string but is converted into a list of objects that represent |
| 18106 |
one of: letter, integer, space or other (punctuation). This reduces |
| 18107 |
the amount of parsing of substrings that needs to be performed. |
| 18108 |
|
| 18109 |
The examples below show the ordering of the list: |
| 18110 |
\code{CH\textsubscript{2}O}, |
| 18111 |
\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}}, |
| 18112 |
\code{C\textsubscript{5}H\textsubscript{4}NCOOH}, |
| 18113 |
\code{CO}, \code{Cl}, |
| 18114 |
\code{Co}, \code{Co\textsubscript{2}O\textsubscript{3}}, |
| 18115 |
\code{Co\textsubscript{2}}, \code{CO\textsubscript{2}}, |
| 18116 |
\code{CoMoO\textsubscript{4}} and \code{CoCl\textsubscript{2}}, |
| 18117 |
for the setting |
| 18118 |
\csopt[between]{letter-number-rule}, where the subscripts are |
| 18119 |
the Unicode subscript characters. |
| 18120 |
|
| 18121 |
\begin{itemize} |
| 18122 |
\item \optfmt{letternumber-case}: case-sensitive |
| 18123 |
letter-number sort. Example: |
| 18124 |
|
| 18125 |
\code{CH\textsubscript{2}O}, |
| 18126 |
\code{CO}, |
| 18127 |
\code{CO\textsubscript{2}}, |
| 18128 |
\code{C\textsubscript{5}H\textsubscript{4}NCOOH}, |
| 18129 |
\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}}, |
| 18130 |
\code{Cl}, |
| 18131 |
\code{Co}, |
| 18132 |
\code{CoCl\textsubscript{2}}, |
| 18133 |
\code{CoMoO\textsubscript{4}}, |
| 18134 |
\code{Co\textsubscript{2}}, |
| 18135 |
\code{Co\textsubscript{2}O\textsubscript{3}}. |
| 18136 |
|
| 18137 |
(Order determined by: $\mathtt{H} < \mathtt{O} < 5 < 10 < \mathtt{l} < \mathtt{o}$.) |
| 18138 |
|
| 18139 |
\item \optfmt{letternumber-case-reverse}: reverse case-sensitive |
| 18140 |
letter-number sort. Example: |
| 18141 |
|
| 18142 |
\code{Co\textsubscript{2}O\textsubscript{3}}, |
| 18143 |
\code{Co\textsubscript{2}}, |
| 18144 |
\code{CoMoO\textsubscript{4}}, |
| 18145 |
\code{CoCl\textsubscript{2}}, |
| 18146 |
\code{Co}, |
| 18147 |
\code{Cl}, |
| 18148 |
\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}}, |
| 18149 |
\code{C\textsubscript{5}H\textsubscript{4}NCOOH}, |
| 18150 |
\code{CO\textsubscript{2}}, |
| 18151 |
\code{CO}, |
| 18152 |
\code{CH\textsubscript{2}O}. |
| 18153 |
|
| 18154 |
\item \optfmt{letternumber-nocase}: case-insensitive |
| 18155 |
letter-number sort. The sort value is first converted to lower |
| 18156 |
case. Note that \csopt[between]{letter-number-rule} doesn't make |
| 18157 |
sense in this context as there won't be any \idx!{uppercase} characters in |
| 18158 |
the sort value, so numbers will always come before letters. Example: |
| 18159 |
|
| 18160 |
\code{C\textsubscript{5}H\textsubscript{4}NCOOH}, |
| 18161 |
\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}}, |
| 18162 |
\code{CH\textsubscript{2}O}, |
| 18163 |
\code{Cl}, |
| 18164 |
\code{CO}, |
| 18165 |
\code{Co}, |
| 18166 |
\code{CO\textsubscript{2}}, |
| 18167 |
\code{Co\textsubscript{2}}, |
| 18168 |
\code{Co\textsubscript{2}O\textsubscript{3}}, |
| 18169 |
\code{CoCl\textsubscript{2}}, |
| 18170 |
\code{CoMoO\textsubscript{4}}. |
| 18171 |
|
| 18172 |
(Order determined by: $5 < 10 < \mathtt{h} < \mathtt{l} < \mathtt{o}$.) |
| 18173 |
|
| 18174 |
\item \optfmt{letternumber-nocase-reverse}: reverse case-insensitive |
| 18175 |
letter-number sort, so numbers will now always come after letters. Example: |
| 18176 |
|
| 18177 |
\code{CoMoO\textsubscript{4}}, |
| 18178 |
\code{CoCl\textsubscript{2}}, |
| 18179 |
\code{Co\textsubscript{2}O\textsubscript{3}}, |
| 18180 |
\code{Co\textsubscript{2}}, |
| 18181 |
\code{CO\textsubscript{2}}, |
| 18182 |
\code{Co}, |
| 18183 |
\code{CO}, |
| 18184 |
\code{Cl}, |
| 18185 |
\code{CH\textsubscript{2}O}, |
| 18186 |
\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}}, |
| 18187 |
\code{C\textsubscript{5}H\textsubscript{4}NCOOH}. |
| 18188 |
|
| 18189 |
\item \optfmt{letternumber-upperlower}: upper-lower |
| 18190 |
letter-number sort. This behaves slightly differently to |
| 18191 |
\optfmt{letter-upperlower} when used with \csopt[between]{letter-number-rule} |
| 18192 |
and has a more complicated rule that's determined by the character |
| 18193 |
following the number and implied numbers inserted between letters. |
| 18194 |
(There was a bug in earlier versions that has been corrected in v1.8 |
| 18195 |
so you may find a slightly different ordering when upgrading.) |
| 18196 |
Example: |
| 18197 |
|
| 18198 |
\code{CH\textsubscript{2}O}, |
| 18199 |
\code{C\textsubscript{5}H\textsubscript{4}NCOOH}, |
| 18200 |
\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}}, |
| 18201 |
\code{Cl}, |
| 18202 |
\code{CO}, |
| 18203 |
\code{CO\textsubscript{2}}, |
| 18204 |
\code{Co}, |
| 18205 |
\code{Co\textsubscript{2}}, |
| 18206 |
\code{CoCl\textsubscript{2}}, |
| 18207 |
\code{CoMoO\textsubscript{4}}, |
| 18208 |
\code{Co\textsubscript{2}O\textsubscript{3}}. |
| 18209 |
|
| 18210 |
(Order determined by: $\mathtt{H} < 5\mathtt{H} < 10\mathtt{H} < |
| 18211 |
\mathtt{l} < \mathtt{O} < \mathtt{o}$, and for the terms starting |
| 18212 |
with \code{CO} or \code{Co}: 2 comes after null and $\mathtt{C} < |
| 18213 |
\mathtt{M} < 2\mathtt{O}$.) |
| 18214 |
|
| 18215 |
Compare this with \csopt[before letter]{letter-number-rule} which |
| 18216 |
results in the order: |
| 18217 |
|
| 18218 |
\code{C\textsubscript{5}H\textsubscript{4}NCOOH}, |
| 18219 |
\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}}, |
| 18220 |
\code{CH\textsubscript{2}O}, |
| 18221 |
\code{Cl}, |
| 18222 |
\code{CO}, |
| 18223 |
\code{CO\textsubscript{2}}, |
| 18224 |
\code{Co}, |
| 18225 |
\code{Co\textsubscript{2}}, |
| 18226 |
\code{Co\textsubscript{2}O\textsubscript{3}}, |
| 18227 |
\code{CoCl\textsubscript{2}}, |
| 18228 |
\code{CoMoO\textsubscript{4}}. |
| 18229 |
|
| 18230 |
\item \optfmt{letternumber-upperlower-reverse}: reverse upper-lower |
| 18231 |
letter-number sort. Example (with \csopt[between]{letter-number-rule}): |
| 18232 |
|
| 18233 |
\code{Co\textsubscript{2}O\textsubscript{3}}, |
| 18234 |
\code{CoMoO\textsubscript{4}}, |
| 18235 |
\code{CoCl\textsubscript{2}}, |
| 18236 |
\code{Co\textsubscript{2}}, |
| 18237 |
\code{Co}, |
| 18238 |
\code{CO\textsubscript{2}}, |
| 18239 |
\code{CO}, |
| 18240 |
\code{Cl}, |
| 18241 |
\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}}, |
| 18242 |
\code{C\textsubscript{5}H\textsubscript{4}NCOOH}, |
| 18243 |
\code{CH\textsubscript{2}O}. |
| 18244 |
|
| 18245 |
Compare this with \csopt[before letter]{letter-number-rule} which |
| 18246 |
results in the order: |
| 18247 |
|
| 18248 |
\code{CoMoO\textsubscript{4}}, |
| 18249 |
\code{CoCl\textsubscript{2}}, |
| 18250 |
\code{Co\textsubscript{2}O\textsubscript{3}}, |
| 18251 |
\code{Co\textsubscript{2}}, |
| 18252 |
\code{Co}, |
| 18253 |
\code{CO\textsubscript{2}}, |
| 18254 |
\code{CO}, |
| 18255 |
\code{Cl}, |
| 18256 |
\code{CH\textsubscript{2}O}, |
| 18257 |
\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}}, |
| 18258 |
\code{C\textsubscript{5}H\textsubscript{4}NCOOH}. |
| 18259 |
|
| 18260 |
Remember that the associated settings are reversed as |
| 18261 |
well. So \csopt[before letter]{letter-number-rule} |
| 18262 |
results in numbers \emph{after} letters. |
| 18263 |
|
| 18264 |
\item \optfmt{letternumber-lowerupper}: lower-upper letter-number |
| 18265 |
sort. As with the upper-lower option, this behaves slightly differently to |
| 18266 |
\optfmt{letter-lowerupper} when used with \csopt[between]{letter-number-rule} |
| 18267 |
and has a more complicated rule. |
| 18268 |
Example: |
| 18269 |
|
| 18270 |
\code{CH\textsubscript{2}O}, |
| 18271 |
\code{C\textsubscript{5}H\textsubscript{4}NCOOH}, |
| 18272 |
\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}}, |
| 18273 |
\code{Cl}, |
| 18274 |
\code{Co}, |
| 18275 |
\code{Co\textsubscript{2}}, |
| 18276 |
\code{CoCl\textsubscript{2}}, |
| 18277 |
\code{CoMoO\textsubscript{4}}, |
| 18278 |
\code{Co\textsubscript{2}O\textsubscript{3}}, |
| 18279 |
\code{CO}, |
| 18280 |
\code{CO\textsubscript{2}}. |
| 18281 |
|
| 18282 |
Compare this with \csopt[before letter]{letter-number-rule} which |
| 18283 |
results in the order: |
| 18284 |
|
| 18285 |
\code{C\textsubscript{5}H\textsubscript{4}NCOOH}, |
| 18286 |
\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}}, |
| 18287 |
\code{CH\textsubscript{2}O}, |
| 18288 |
\code{Cl}, |
| 18289 |
\code{Co}, |
| 18290 |
\code{Co\textsubscript{2}}, |
| 18291 |
\code{Co\textsubscript{2}O\textsubscript{3}}, |
| 18292 |
\code{CoCl\textsubscript{2}}, |
| 18293 |
\code{CoMoO\textsubscript{4}}, |
| 18294 |
\code{CO}, |
| 18295 |
\code{CO\textsubscript{2}}. |
| 18296 |
|
| 18297 |
\item \optfmt{letternumber-lowerupper-reverse}: reverse lower-upper |
| 18298 |
letter-number sort. Example (with \csopt[between]{letter-number-rule}): |
| 18299 |
|
| 18300 |
\code{CO\textsubscript{2}}, |
| 18301 |
\code{CO}, |
| 18302 |
\code{Co\textsubscript{2}O\textsubscript{3}}, |
| 18303 |
\code{CoMoO\textsubscript{4}}, |
| 18304 |
\code{CoCl\textsubscript{2}}, |
| 18305 |
\code{Co\textsubscript{2}}, |
| 18306 |
\code{Co}, |
| 18307 |
\code{Cl}, |
| 18308 |
\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}}, |
| 18309 |
\code{C\textsubscript{5}H\textsubscript{4}NCOOH}, |
| 18310 |
\code{CH\textsubscript{2}O}. |
| 18311 |
|
| 18312 |
\end{itemize} |
| 18313 |
|
| 18314 |
\subsubsection{Numerical} |
| 18315 |
\label{sec:numerical} |
| 18316 |
|
| 18317 |
The sort methods listed in \tableref{tab:sortoptionsnumerical} |
| 18318 |
use numeric comparisons. The sort value is expected to |
| 18319 |
be a numeric value. If it can't be parsed then it's treated as 0 |
| 18320 |
(and a warning will be written to the transcript). |
| 18321 |
These all recognise the digits in the Unicode \qt{Number, |
| 18322 |
Decimal Digit} category but, unlike the hybrid letter-number |
| 18323 |
comparators above, they don't recognise the superscript or subscript |
| 18324 |
digits. The \qt{non-locale} in some of the descriptions below |
| 18325 |
indicates that the method doesn't recognise locale-sensitive |
| 18326 |
formatting, such as group separators. |
| 18327 |
\begin{itemize} |
| 18328 |
\item \optfmt{integer}: integer sort. This is for non-locale integer sort |
| 18329 |
values. |
| 18330 |
|
| 18331 |
\item \optfmt{integer-reverse}: as above but reverses the order. |
| 18332 |
|
| 18333 |
\item \optfmt{hex}: hexadecimal integer sort. This is for non-locale |
| 18334 |
hexadecimal sort values. |
| 18335 |
|
| 18336 |
\item \optfmt{hex-reverse}: as above but reverses the order. |
| 18337 |
|
| 18338 |
\item \optfmt{octal}: octal integer sort. This is for non-locale |
| 18339 |
octal sort values. |
| 18340 |
|
| 18341 |
\item \optfmt{octal-reverse}: as above but reverses the order. |
| 18342 |
|
| 18343 |
\item \optfmt{binary}: binary integer sort. This is for non-locale binary sort |
| 18344 |
values. |
| 18345 |
|
| 18346 |
\item \optfmt{binary-reverse}: as above but reverses the order. |
| 18347 |
|
| 18348 |
\item \optfmt{float}: single-precision sort. This is for non-locale |
| 18349 |
decimal sort values. |
| 18350 |
|
| 18351 |
\item \optfmt{float-reverse}: as above but reverses the order. |
| 18352 |
|
| 18353 |
\item \optfmt{double}: double-precision sort. This is for non-locale |
| 18354 |
decimal sort values. |
| 18355 |
|
| 18356 |
\item \optfmt{double-reverse}: as above but reverses the order. |
| 18357 |
|
| 18358 |
\item \optfmt{numeric}: locale-sensitive numeric sort. Use |
| 18359 |
\csopt{numeric-locale} to set the locale. |
| 18360 |
|
| 18361 |
\item \optfmt{numeric-reverse}: as above but reverses the order. |
| 18362 |
|
| 18363 |
\item \optfmt{currency}: locale-sensitive currency sort. Use |
| 18364 |
\csopt{numeric-locale} to set the locale. |
| 18365 |
|
| 18366 |
\item \optfmt{currency-reverse}: as above but reverses the order. |
| 18367 |
|
| 18368 |
\item \optfmt{percent}: locale-sensitive percent sort. Use |
| 18369 |
\csopt{numeric-locale} to set the locale. |
| 18370 |
|
| 18371 |
\item \optfmt{percent-reverse}: as above but reverses the order. |
| 18372 |
|
| 18373 |
\item \optfmt{numberformat}: locale-sensitive custom numeric sort. Use |
| 18374 |
\csopt{numeric-locale} to set the locale and |
| 18375 |
\csopt{numeric-sort-pattern} to set the number pattern. |
| 18376 |
|
| 18377 |
\item \optfmt{numberformat-reverse}: as above but reverses the order. |
| 18378 |
|
| 18379 |
\end{itemize} |
| 18380 |
|
| 18381 |
In general, it doesn't make much sense to have \hierarchical\ entries |
| 18382 |
that need to be sorted by a number, but it is possible as long as each |
| 18383 |
level uses the same type of numbering. |
| 18384 |
|
| 18385 |
\subsubsection{Date-Time} |
| 18386 |
|
| 18387 |
The sort methods listed in \tableref{tab:sortoptionsdatetime} |
| 18388 |
are for dates and times. Use \csopt{date-sort-format} |
| 18389 |
and \csopt{date-sort-locale} to specify the date format and locale. |
| 18390 |
\begin{itemize} |
| 18391 |
\item \optfmt{date}: sort dates. |
| 18392 |
|
| 18393 |
\item \optfmt{date-reverse}: as above but reverses the order. |
| 18394 |
|
| 18395 |
\item \optfmt{datetime}: sort date and time information. |
| 18396 |
|
| 18397 |
\item \optfmt{datetime-reverse}: as above but reverses the order. |
| 18398 |
|
| 18399 |
\item \optfmt{time}: sort times. |
| 18400 |
|
| 18401 |
\item \optfmt{time-reverse}: as above but reverses the order. |
| 18402 |
|
| 18403 |
\end{itemize} |
| 18404 |
|
| 18405 |
If the field you want to sort by contains a date then the |
| 18406 |
simplest way to sort is to ensure the date is in ISO format |
| 18407 |
and then just use a letter sort. However it may be that |
| 18408 |
the date is in the format particular to your locale or you have a |
| 18409 |
mix of \era{AD} and \era{BC}. In which |
| 18410 |
case you can use one of the date/time sort options (such as |
| 18411 |
\csopt[date]{sort} or \csopt[date-reverse]{sort}). The locale |
| 18412 |
is assumed to be your default locale (as given by the \idx{JVM}) |
| 18413 |
but if you are using a different locale this can |
| 18414 |
be set with \csopt{date-sort-locale}. The pattern is assumed |
| 18415 |
to be the default for that locale but you can change this with |
| 18416 |
\csopt{date-sort-format}. If you provide your |
| 18417 |
own custom pattern you must make sure that it matches the selected |
| 18418 |
\optfmt{sort} option. |
| 18419 |
|
| 18420 |
Take care if you switch from using the \idx{JRE} to the \idx{CLDR} |
| 18421 |
\idx{localeprovider} as you may find the default pattern changes. |
| 18422 |
|
| 18423 |
The locale and pattern information is used by \bibgls\ to parse the |
| 18424 |
field. If the field value can't be parsed then \bibgls\ will issue |
| 18425 |
a warning and assume the current date (or time). |
| 18426 |
|
| 18427 |
The actual sort value that's used by the comparator is numeric. In |
| 18428 |
the case of the time-based \csopt[datetime]{sort} and |
| 18429 |
\csopt[time]{sort} (or their \optfmt{-reverse} versions), this value |
| 18430 |
is the number of milliseconds since 1st~January, 1970. In the case |
| 18431 |
of \csopt[date]{sort} (or \csopt[date-reverse]{sort}), this value is |
| 18432 |
obtained from $a(y\times10000 + m\times100 + d)$ where $y$ is the |
| 18433 |
year, $m$ is the month number, $d$ is the day of month number, and |
| 18434 |
$a$ is an integer representation of the era ($-1$ for \era{BC} and |
| 18435 |
$+1$ for \era{AD}). |
| 18436 |
|
| 18437 |
Unlike the numeric sort methods (such as \csopt[integer]{sort}) |
| 18438 |
the date-time sort methods set the \field{sort} field to a value |
| 18439 |
that can be more easily parsed within the document and that should |
| 18440 |
mostly achieve the same ordering if a letter comparator were to be used |
| 18441 |
with it (except for \era{BC} dates, where the order needs to be |
| 18442 |
reversed). This has the by-product of providing a field that |
| 18443 |
you can access within the document that can be more easily parsed by |
| 18444 |
\LaTeX. |
| 18445 |
|
| 18446 |
In general, it doesn't make much sense to have \hierarchical\ entries |
| 18447 |
that need to be sorted by date, but it is possible as long as each |
| 18448 |
level uses the same date format. |
| 18449 |
|
| 18450 |
For example, suppose my \ext{bib} file contains: |
| 18451 |
\begin{codeenv} |
| 18452 |
\atentry{entry}\marg{journalentry, |
| 18453 |
\field{name}=\marg{10 Jan 2017}, |
| 18454 |
\field{description}=\marg{an interesting journal entry} |
| 18455 |
} |
| 18456 |
\end{codeenv} |
| 18457 |
The \field{name} field uses an abbreviated UK date format. |
| 18458 |
If all my other entries also use this format in the \field{name} |
| 18459 |
then I can sort them chronologically: |
| 18460 |
\begin{codeenv} |
| 18461 |
\gls{GlsXtrLoadResources}\oarg{ |
| 18462 |
\csopt[entries]{src},\comment{data in entries.bib} |
| 18463 |
\csopt[date]{sort}, |
| 18464 |
\csopt[en-GB]{date-sort-locale}, |
| 18465 |
\csopt[medium]{date-sort-format} |
| 18466 |
} |
| 18467 |
\end{codeenv} |
| 18468 |
(The medium format is actually the default for this locale, |
| 18469 |
and the locale matches my system locale, so I could omit |
| 18470 |
both \csopt{date-sort-locale} and \csopt{date-sort-format}.) |
| 18471 |
|
| 18472 |
If \commonlongarg{verbose} mode is on, the transcript will show |
| 18473 |
the label, sort value and numeric value for each entry. |
| 18474 |
In this case, the information is: |
| 18475 |
\begin{verbatim} |
| 18476 |
journalentry -> '+1 2017-01-10' [20170110] |
| 18477 |
\end{verbatim} |
| 18478 |
The first value is the label (\code{journalentry}), the second |
| 18479 |
value is assigned to the \field{sort} field |
| 18480 |
(\code{+1 2017-01-10}) and the number in square brackets |
| 18481 |
is the actual numeric value used by the comparator. The signed |
| 18482 |
number at the start of the sort field \code{+1} is the numeric |
| 18483 |
representation of the era as used for the $a$ variable in the |
| 18484 |
computation of the numeric value (as described earlier). |
| 18485 |
|
| 18486 |
If I change the format to \csopt[short]{date-sort-format}, |
| 18487 |
then the date can't be parsed correctly and \bibgls\ will |
| 18488 |
issue the following warning: |
| 18489 |
\begin{verbatim} |
| 18490 |
Warning: Can't parse sort value '10 Jan 2017' for 'journalentry' |
| 18491 |
(pattern: 'dd/MM/yyyy') |
| 18492 |
\end{verbatim} |
| 18493 |
This shows the value that \bibgls\ is trying to |
| 18494 |
parse (\code{10 Jan 2017}) for the entry identified by |
| 18495 |
the given label (\code{journalentry}). The pattern \bibgls\ |
| 18496 |
expects is also given (\code{dd/MM/yyyy}). |
| 18497 |
|
| 18498 |
\optsection{shuffle} |
| 18499 |
|
| 18500 |
Automatically sets \csopt[random]{sort} and \csopt{flatten}. |
| 18501 |
The value \meta{seed} may be omitted. If present, it should |
| 18502 |
be an integer used as a seed for the random number generator. |
| 18503 |
|
| 18504 |
\optsection{sort-field} |
| 18505 |
|
| 18506 |
The \csopt{sort-field} key indicates which field provides the sort |
| 18507 |
value. The \meta{field} must be a recognised field name or you |
| 18508 |
may use \csopt[id]{sort-field} to sort according to the label. |
| 18509 |
The default value is the \field{sort} field (which is typically |
| 18510 |
inferred rather than explicitly set). |
| 18511 |
|
| 18512 |
Example: |
| 18513 |
\begin{codeenv} |
| 18514 |
\gls{GlsXtrLoadResources}\oarg{ |
| 18515 |
\csopt[entries-terms]{src},\comment{data in entries-terms.bib} |
| 18516 |
\csopt[symbol]{sort-field},\comment{sort by 'symbol' field} |
| 18517 |
\csopt[letter-case]{sort}\comment{case-sensitive letter sort} |
| 18518 |
} |
| 18519 |
\end{codeenv} |
| 18520 |
This sorts the entries according to the \field{symbol} field using |
| 18521 |
a case-sensitive letter comparison. |
| 18522 |
|
| 18523 |
\begin{important} |
| 18524 |
In general it's better to use the default \csopt[sort]{sort-field} |
| 18525 |
and adjust the fallbacks instead (see |
| 18526 |
\sectionref{sec:fallbacks}). The \csopt{sort-field} option is |
| 18527 |
provided if you want to use a specific field regardless of the |
| 18528 |
\gls{entrytype}. |
| 18529 |
\end{important} |
| 18530 |
|
| 18531 |
If an entry is missing a value for \meta{field}, then the value of |
| 18532 |
the fallback field will be used instead. If \csopt{missing-sort-fallback} is |
| 18533 |
set, then that's used as the fallback, otherwise it depends on the |
| 18534 |
\gls{entrytype}. |
| 18535 |
If no fallback field can be found, the entry's label will be used. |
| 18536 |
|
| 18537 |
For the specific case with the default \csopt[sort]{sort-field} |
| 18538 |
setting, the fallback for the \field{sort} field is governed not |
| 18539 |
only by the \gls{entrytype} but also by some associated settings: |
| 18540 |
|
| 18541 |
\begin{itemize} |
| 18542 |
\item If the entry's original type (before being aliased with |
| 18543 |
\csopt{entry-type-aliases}) is identified in |
| 18544 |
\csopt{custom-sort-fallbacks}, then if the \field{sort} field is missing |
| 18545 |
the value is obtained from the supplied custom mapping. |
| 18546 |
|
| 18547 |
\item If the entry is defined using \atentry{entry} (or a dual form |
| 18548 |
that acts like \atentry{entry}), then if the \field{sort} field is |
| 18549 |
missing the value is obtained from the field identified by |
| 18550 |
\csopt{entry-sort-fallback}. If that field is also missing then |
| 18551 |
that field's fallback is used. |
| 18552 |
|
| 18553 |
\item For the index \glspl{entrytype} like \atentry{index} or |
| 18554 |
\atentry{indexplural}, then if the \field{sort} field is missing the |
| 18555 |
value is obtained from the \field{name} field. If that field is also |
| 18556 |
missing, then the value is obtained from the particular \gls{entrytype}['s] |
| 18557 |
fallback for the \field{name} field. (For example, the entry's label |
| 18558 |
for \atentry{index} or the \field{plural} field for |
| 18559 |
\atentry{indexplural}.) |
| 18560 |
|
| 18561 |
\item If the entry is defined with an abbreviation type (for |
| 18562 |
example, \atentry{abbreviation} or \atentry{acronym}) then if the |
| 18563 |
\field{sort} field is missing, \bibgls\ will fallback on the field |
| 18564 |
given by \csopt{abbreviation-sort-fallback}. |
| 18565 |
|
| 18566 |
\item The symbol-like \glspl{entrytype} fallback on the field given by |
| 18567 |
\csopt{symbol-sort-fallback} if the \field{sort} field is missing. |
| 18568 |
|
| 18569 |
\item Entries defined using \atentry{bibtexentry} fallback on the field |
| 18570 |
given by \csopt{bibtexentry-sort-fallback}, which defaults to the |
| 18571 |
\field{name} field. Note that this only applies to the \gls{mainentry}. |
| 18572 |
The \glsdisp{spawnedentry}{spawned} \atentry{contributor} entries behave like |
| 18573 |
\atentry{index}. |
| 18574 |
|
| 18575 |
\end{itemize} |
| 18576 |
Use \csopt{dual-sort-field} when sorting dual entries. |
| 18577 |
|
| 18578 |
\optsection{missing-sort-fallback} |
| 18579 |
|
| 18580 |
With \csopt[\meta{sort-field}]{sort-field}, if the value of the field |
| 18581 |
identified by \meta{sort-field} is missing, then \bibgls\ behaves as |
| 18582 |
follows: |
| 18583 |
\begin{enumerate} |
| 18584 |
\item If \csopt[\meta{fallback-field}]{missing-sort-fallback} is set, then |
| 18585 |
\bibgls\ will fallback on the value provided by the field |
| 18586 |
\meta{fallback-field}. If \meta{fallback-field} is |
| 18587 |
missing, then \bibgls\ will query the \gls{entrytype}['s] fallback for |
| 18588 |
\meta{fallback-field} (not for \meta{sort-field}). |
| 18589 |
|
| 18590 |
The \meta{fallback-field} must be a known field but not an internal |
| 18591 |
field. It can't be the \field{sort} field. (Take care not to cause |
| 18592 |
an infinite loop if \csopt{sort-field} has been changed.) Unlike the |
| 18593 |
other sort fallback options, such as \csopt{entry-sort-fallback}, |
| 18594 |
the \meta{fallback-field} can't be a keyword (to identify the label) |
| 18595 |
and can't be a composite. |
| 18596 |
|
| 18597 |
\item If the \gls{entrytype} has a fallback rule for |
| 18598 |
\meta{sort-field}, then that rule is used (see |
| 18599 |
\sectionref{sec:fallbacks}). When \csopt[sort]{sort-field} this |
| 18600 |
means: |
| 18601 |
\begin{itemize} |
| 18602 |
\item If the entry's original \gls{entrytype} has been identified in |
| 18603 |
\csopt{custom-sort-fallbacks}, then \bibgls\ will fallback on the |
| 18604 |
designated custom setting. |
| 18605 |
|
| 18606 |
\item If the entry was defined using one of the index types (such as |
| 18607 |
\atentry{index}), then \bibgls\ will fallback on the \field{name} |
| 18608 |
field. |
| 18609 |
|
| 18610 |
\item If the entry was defined using the \atentry{entry} type (or a |
| 18611 |
dual form that acts like \atentry{entry}), then \bibgls\ will |
| 18612 |
fallback on the field given by \csopt{entry-sort-fallback}. |
| 18613 |
|
| 18614 |
\item If the entry was defined using |
| 18615 |
one of the symbol types (such as \atentry{symbol}), then \bibgls\ |
| 18616 |
will fallback on the field given by \csopt{symbol-sort-fallback}. |
| 18617 |
|
| 18618 |
\item If the entry was defined using |
| 18619 |
one of the abbreviation types (such as \atentry{abbreviation}), then \bibgls\ |
| 18620 |
will fallback on the field given by |
| 18621 |
\csopt{abbreviation-sort-fallback}. |
| 18622 |
|
| 18623 |
\item If the entry was defined using \atentry{bibtexentry} (but not |
| 18624 |
the spawned \atentry{contributor} entries), then \bibgls\ will |
| 18625 |
fallback on the field given by |
| 18626 |
\csopt{bibtexentry-sort-fallback}. |
| 18627 |
\end{itemize} |
| 18628 |
If \meta{sort-field} is not \field{sort}, then there may not be a |
| 18629 |
fallback, in which case the next condition applies: |
| 18630 |
\item Otherwise the sort value will be set to the entry label and \bibgls\ |
| 18631 |
will issue a warning. |
| 18632 |
\end{enumerate} |
| 18633 |
The default setting is \csopt[\empty]{missing-sort-fallback}, which |
| 18634 |
means that step~1 above is omitted. |
| 18635 |
|
| 18636 |
Use \csopt{dual-missing-sort-fallback} when sorting dual entries |
| 18637 |
separately from primaries, and use |
| 18638 |
\csopt{secondary-missing-sort-fallback} for \csopt{secondary} |
| 18639 |
sorting. |
| 18640 |
|
| 18641 |
\optsection{trim-sort} |
| 18642 |
|
| 18643 |
If the interpreter is used to determine the sort value, this setting |
| 18644 |
governs whether or not the interpreter should trim leading and |
| 18645 |
trailing spaces. The default setting is \csopt[true]{trim-sort}. |
| 18646 |
|
| 18647 |
This option automatically sets \csopt[\meta{boolean}]{dual-trim-sort} |
| 18648 |
and \csopt[\meta{boolean}]{secondary-trim-sort}. |
| 18649 |
|
| 18650 |
\optsection{sort-replace} |
| 18651 |
|
| 18652 |
This option may be used to perform \gls{regular-expression} substitutions |
| 18653 |
on the sort value and has the same syntax as \csopt{labelify-replace}. |
| 18654 |
The value is required for this key but may be empty, which indicates |
| 18655 |
that the setting is switched off. |
| 18656 |
|
| 18657 |
This action is done after the interpreter parses the |
| 18658 |
sort value (if applicable) and before \csopt{sort-number-pad} (if |
| 18659 |
applicable). For example, suppose the sort value is: |
| 18660 |
\begin{codeenv} |
| 18661 |
\cs{ensuremath}\marg{\ics{approx} 3.14} |
| 18662 |
\end{codeenv} |
| 18663 |
then the interpreter will convert this to $\mathtt{\approx}$\texttt{3.14} but: |
| 18664 |
\begin{codeenv} |
| 18665 |
\csopt[\marg{\cs{glshex}2248}\marg{}]{sort-replace} |
| 18666 |
\end{codeenv} |
| 18667 |
can be used to strip the $\approx$ symbol (\hex{2248}) so that the value can |
| 18668 |
now be parsed as a number if \csopt[double]{sort} has been used. |
| 18669 |
|
| 18670 |
Use \csopt{dual-sort-replace} for dual |
| 18671 |
and \csopt{secondary-sort-replace} for secondary sort methods. |
| 18672 |
|
| 18673 |
\optsection{sort-rule} |
| 18674 |
|
| 18675 |
If the \csopt[custom]{sort} option is used, the sort rule must be |
| 18676 |
provided with \optfmt{sort-rule}. If \csopt{sort} is not set to |
| 18677 |
\optfmt{custom}, the \optfmt{sort-rule} setting will be ignored. |
| 18678 |
This setting uses Java's |
| 18679 |
\href{http://docs.oracle.com/javase/8/docs/api/java/text/RuleBasedCollator.html}{RuleBasedCollator} |
| 18680 |
class~\cite{rulebasedcollator}, and the rule syntax needs to conform |
| 18681 |
to that format. |
| 18682 |
|
| 18683 |
Remember that the options will be expanded as they are written to |
| 18684 |
the \iext{aux} file, so be careful of any special characters that |
| 18685 |
occur in the rule. For the special characters \idx{param} |
| 18686 |
\idx{commentchar} \idx{sbchar} \idx{colsep} \idx{bgroupchar} and |
| 18687 |
\idx{egroupchar} you can use \ics{cs.hash}, \ics{cs.percent}, |
| 18688 |
\ics{cs.underscore}, \ics{cs.amp}, \ics{cs.openbrace} and |
| 18689 |
\ics{cs.closebrace}. These will be written to the \ext{aux} file |
| 18690 |
with the leading backslash, but \bibgls\ will remove it for this |
| 18691 |
resource option. Remember that the \styfmt{glossaries} package |
| 18692 |
provides \ics{glsbackslash} and \ics{glstildechar} which can be used |
| 18693 |
to produce a literal backslash (\idx{backslashchar}) and tilde |
| 18694 |
(\idx{tildechar}). |
| 18695 |
|
| 18696 |
You can also |
| 18697 |
use \stringu\meta{hex} (where \meta{hex} is a hexadecimal |
| 18698 |
code) to represent a Unicode character. For example: |
| 18699 |
\begin{codeenv} |
| 18700 |
\gls{GlsXtrLoadResources}\oarg{ |
| 18701 |
\csopt[custom]{sort}, |
| 18702 |
\csopt[< a,A < b,B < c,C < ch,Ch,CH < d,D |
| 18703 |
< dd,Dd,DD < e,E < f,F < ff,Ff,FF |
| 18704 |
< g,G < ng,Ng,NG < h,H < ij,Ij,IJ |
| 18705 |
< i,I < j,J < k,K < l,L < ll,Ll,LL < m,M |
| 18706 |
< n,N < o,O < p,P < ph,Ph,PH < q,Q < r,R < rh,Rh,RH |
| 18707 |
< s,S < t,T < th,Th,TH < u,U < v,V < w,W < x,X < y,Y < z,Z |
| 18708 |
< \stringu00E6,\stringu00C6]{sort-rule} |
| 18709 |
} |
| 18710 |
\end{codeenv} |
| 18711 |
It's best to use \ics{cs.string} rather than \ics{protect} to avoid |
| 18712 |
unwanted spaces interfering with \meta{hex}. Note that |
| 18713 |
\sty{glossaries-extra} v1.21+ provides\footnote{The command |
| 18714 |
definition was moved to \isty{glossaries-extra-bib2gls} from version |
| 18715 |
1.27 since it's only needed with \bibgls.}\ \ics{glshex} |
| 18716 |
which just does \stringu\ so you can do |
| 18717 |
\code{\ics{glshex} 00E6} instead of \code{\stringu00E6}. |
| 18718 |
This is only one character different, but you can redefine |
| 18719 |
\ics{glsxtrresourceinit} to locally set \ics{u} to \ics{glshex} while |
| 18720 |
the protected write is performed. For example: |
| 18721 |
\begin{codeenv} |
| 18722 |
\cs{renewcommand}*\marg{\cs{glsxtrresourceinit}}\marg{\cmd{let}\cmd{u}\cs{glshex}} |
| 18723 |
\end{codeenv} |
| 18724 |
Then you can just do \code{\csfmt{u}00E6} instead of \code{\stringu00E6}. |
| 18725 |
Note that \ics{GlsXtrResourceInitEscSequences} performs a similar |
| 18726 |
assignment, so you can instead do: |
| 18727 |
\begin{codeenv} |
| 18728 |
\cs{renewcommand}*\marg{\cs{glsxtrresourceinit}}\marg{\comment{} |
| 18729 |
\ics{GlsXtrResourceInitEscSequences} |
| 18730 |
} |
| 18731 |
\end{codeenv} |
| 18732 |
|
| 18733 |
The \isty{glossaries-extra-bib2gls} package (which is automatically loaded by |
| 18734 |
the \styopt{record} option) provides some commands for common rule blocks |
| 18735 |
that may be used in the construction of custom rules. For example: |
| 18736 |
\begin{codeenv} |
| 18737 |
\csopt[\ics{glsxtrcontrolrules} |
| 18738 |
;\ics{glsxtrspacerules} |
| 18739 |
;\ics{glsxtrnonprintablerules} |
| 18740 |
;\ics{glsxtrcombiningdiacriticrules} |
| 18741 |
,\ics{glsxtrhyphenrules} |
| 18742 |
<\ics{glsxtrgeneralpuncrules} |
| 18743 |
<\ics{glsxtrdigitrules} |
| 18744 |
<\ics{glsxtrfractionrules} |
| 18745 |
<\ics{glsxtrMathItalicGreekIrules} |
| 18746 |
<\ics{glsxtrGeneralLatinIVrules} |
| 18747 |
<\ics{glsxtrLatinAA} |
| 18748 |
<\ics{glsxtrLatinOslash} |
| 18749 |
]{sort-rule} |
| 18750 |
\end{codeenv} |
| 18751 |
This places the Greek maths symbols (such as \ics{alpha}) before the |
| 18752 |
Latin block. See the \sty{glossaries-extra} documentation for |
| 18753 |
further details of these commands. |
| 18754 |
|
| 18755 |
You might find it convenient to provide similar commands in a |
| 18756 |
package for rules you may often need. For example, suppose I have a |
| 18757 |
package called, say, \styfmt{mapsymbols} for providing map symbols: |
| 18758 |
\begin{codeenv} |
| 18759 |
\cmd{NeedsTeXFormat}\marg{LaTeX2e} |
| 18760 |
\cmd{ProvidesPackage}\marg{mapsymbols} |
| 18761 |
\comment{some package or font loading stuff here to provide} |
| 18762 |
\comment{the appropriate symbols} |
| 18763 |
\cmd{newcommand}\marg{\cmd{Stadium}}\marg{\ldots} |
| 18764 |
\cmd{newcommand}\marg{\cmd{Battlefield}}\marg{\ldots} |
| 18765 |
\cmd{newcommand}\marg{\cmd{Harbour}}\marg{\ldots} |
| 18766 |
\comment{etc} |
| 18767 |
\strut |
| 18768 |
\comment{Provide a rule block:} |
| 18769 |
\cmd{newcommand}\marg{\cmd{MapSymbolOrder}}\marg{\comment{} |
| 18770 |
\cs{glshex} 2694 \comment{crossed-swords 0x2694} |
| 18771 |
< \cs{glshex} 2693 \comment{anchor 0x2693} |
| 18772 |
< \cs{glshex} 26BD \comment{football 0x26BD} |
| 18773 |
} |
| 18774 |
\end{codeenv} |
| 18775 |
In addition to \filefmt{mapsymbols.sty}, I also need to create |
| 18776 |
\filefmt{mapsymbols.bib} to provide the appropriate definitions for |
| 18777 |
\bibgls: |
| 18778 |
\begin{codeenv} |
| 18779 |
\atentry{preamble}\marg{\qtdelim{\cs{glsxtrprovidecommand}\marg{\cmd{Harbour}}\marg{\icharhex{2693}} |
| 18780 |
\cs{glsxtrprovidecommand}\marg{\cmd{Battlefield}}\marg{\charhex{2694}} |
| 18781 |
\cs{glsxtrprovidecommand}\marg{\cmd{Stadium}}\marg{\charhex{26BD}}}} |
| 18782 |
\end{codeenv} |
| 18783 |
The use of \ics{glsxtrprovidecommand} will override any previous |
| 18784 |
definitions of these commands in \bibgls's interpreter but will act |
| 18785 |
like \ics{providecommand} within the document, and so won't |
| 18786 |
interfere with the commands defined in \filefmt{mapsymbols.sty}. |
| 18787 |
Now I can just do: |
| 18788 |
\begin{codeenv} |
| 18789 |
\cmd{usepackage}\marg{mapsymbols}\comment{my custom package} |
| 18790 |
\cmd{usepackage}[\styopt{record}]\marg{glossaries-extra} |
| 18791 |
\strut |
| 18792 |
\gls{GlsXtrLoadResources}\oarg{ |
| 18793 |
\csopt[mapsymbols,\comment{<--- my custom mapsymbols.bib} |
| 18794 |
entries\comment{data in entries.bib} |
| 18795 |
]{src}, |
| 18796 |
\csopt[custom]{sort}, |
| 18797 |
\csopt[\cs{glsxtrcontrolrules} |
| 18798 |
;\cs{glsxtrspacerules} |
| 18799 |
;\cs{glsxtrnonprintablerules} |
| 18800 |
;\cs{glsxtrcombiningdiacriticrules} |
| 18801 |
,\cs{glsxtrhyphenrules} |
| 18802 |
<\cs{glsxtrgeneralpuncrules} |
| 18803 |
<\cs{glsxtrdigitrules} |
| 18804 |
<\cs{glsxtrfractionrules} |
| 18805 |
<\cmd{MapSymbolOrder} \comment{<--- custom map symbols} |
| 18806 |
<\cs{glsxtrMathItalicGreekIrules} |
| 18807 |
<\ics{glsxtrGeneralLatinIrules} |
| 18808 |
]{sort-rule} |
| 18809 |
} |
| 18810 |
\end{codeenv} |
| 18811 |
|
| 18812 |
An alternative to providing \filefmt{mapsymbols.bib} is to provide a |
| 18813 |
custom package just for \bibgls' use. For example, |
| 18814 |
\filefmt{mapsymbols-bib2gls.sty}: |
| 18815 |
\begin{codeenv} |
| 18816 |
\comment{Provided for \bibgls\ only.} |
| 18817 |
\comment{Use \cmd{usepackage}\marg{mapsymbols} in the document.} |
| 18818 |
\cmd{NeedsTeXFormat}\marg{LaTeX2e} |
| 18819 |
\cmd{ProvidesPackage}\marg{mapsymbols-bib2gls} |
| 18820 |
\cs{glsxtrprovidecommand}\marg{\cmd{Harbour}}\marg{\charhex{2693}} |
| 18821 |
\cs{glsxtrprovidecommand}\marg{\cmd{Battlefield}}\marg{\charhex{2694}} |
| 18822 |
\cs{glsxtrprovidecommand}\marg{\cmd{Stadium}}\marg{\charhex{26BD}} |
| 18823 |
\cmd{endinput} |
| 18824 |
\end{codeenv} |
| 18825 |
and instruct \bibgls\ to parse it with |
| 18826 |
\code{\longarg{custom-packages} mapsymbols-bib2gls} (and use |
| 18827 |
\filefmt{mapsymbols.sty} in the document). Remember that \bibgls\ |
| 18828 |
isn't a \TeX\ engine so make sure to only use simple commands in |
| 18829 |
this file. |
| 18830 |
|
| 18831 |
\optsection{break-at} |
| 18832 |
|
| 18833 |
This option automatically implements |
| 18834 |
\csopt[\meta{option}]{dual-break-at} and |
| 18835 |
\csopt[\meta{option}]{secondary-break-at}. |
| 18836 |
|
| 18837 |
The alphabet sort options (\tableref{tab:sortoptionsrule}) typically |
| 18838 |
list non-letter characters before alphabetical characters and spaces |
| 18839 |
are quite often in the ignored set. This means that the alphabet |
| 18840 |
sort options are naturally in a letter order, similar to |
| 18841 |
\idx!{xindy}['s] \code{ord/letorder} module. (This isn't the same as |
| 18842 |
\csopt[letter-nocase]{sort}, which just sorts according to the |
| 18843 |
Unicode value not according to a particular alphabet.) |
| 18844 |
|
| 18845 |
In order to replicate \idx!{makeindex} and \idx!{xindy}['s] default word |
| 18846 |
order, \bibgls\ splits up the sort value at word boundaries and |
| 18847 |
inserts a marker (identified by \csopt{break-marker}). |
| 18848 |
For example, if the sort value is \qt{sea lion} then it's actually |
| 18849 |
converted to \verb"sea|lion|" whereas \qt{sea} becomes \verb"sea|" |
| 18850 |
and \qt{seal} becomes \verb"seal|". The default marker is \verb"|" |
| 18851 |
which is commonly placed in collation rules before digits but |
| 18852 |
after the ignored characters, such as spaces and hyphens. |
| 18853 |
|
| 18854 |
Note that this action removes non-letters, so for example, |
| 18855 |
if the sort value is \verb"# (parameter)" then it will be converted |
| 18856 |
to \verb"parameter|" (hash, space and parentheses removed). |
| 18857 |
If you only want to break at spaces (optionally following a comma) |
| 18858 |
use the following instead: |
| 18859 |
\begin{codeenv} |
| 18860 |
\csopt[none]{break-at}, |
| 18861 |
\csopt[\marg{,? +}\marg{|}]{sort-replace} |
| 18862 |
\end{codeenv} |
| 18863 |
|
| 18864 |
You can change the construction of the break points with |
| 18865 |
\csopt[\meta{option}]{break-at} where \meta{option} may be one of: |
| 18866 |
\begin{itemize} |
| 18867 |
\item \optfmt{word}: break at word boundaries (default). |
| 18868 |
Note that what constitutes a word varies |
| 18869 |
according to the locale but usually anything that's not alphanumeric |
| 18870 |
will designate a word-boundary. The characters between words are |
| 18871 |
discarded. |
| 18872 |
For example, the sort value \qt{Tom, Dick, and Harry} becomes |
| 18873 |
\verb"Tom|Dick|and|Harry", which has discarded the comma and space |
| 18874 |
characters. |
| 18875 |
\item \optfmt{character}: break after each character. |
| 18876 |
\item \optfmt{sentence}: break after each sentence. |
| 18877 |
\item \optfmt{upper-notlower}: break after any \idx{uppercase} character |
| 18878 |
that's not followed by a \idx{lowercase} character. For example, |
| 18879 |
\qt{MathML} becomes \verb"MathM|L|" and \qt{W3C} becomes |
| 18880 |
\verb"W|3C|". |
| 18881 |
\item \optfmt{upper-upper}: break after any \idx{uppercase} character |
| 18882 |
that's followed by an \idx{uppercase} character. |
| 18883 |
\item \optfmt{upper-notlower-word}: first applies break-points |
| 18884 |
according to \optfmt{upper-notlower} and then according to |
| 18885 |
\optfmt{word}. |
| 18886 |
\item \optfmt{upper-upper-word}: first applies break-points |
| 18887 |
according to \optfmt{upper-upper} and then according to |
| 18888 |
\optfmt{word}. |
| 18889 |
\item \optfmt{none}: don't create break points. Use this option to |
| 18890 |
emulate \idx!{makeindex} or \idx!{xindy}'s letter ordering, or combine |
| 18891 |
with \csopt{sort-replace} to insert custom break points. |
| 18892 |
\end{itemize} |
| 18893 |
|
| 18894 |
This option is ignored when used with the non-alphabetic |
| 18895 |
\csopt{sort} options. You can find the break points in the |
| 18896 |
\field{sort} field for the entry's definition in the \ext{glstex} |
| 18897 |
file (which is provided for information rather than for use in the |
| 18898 |
document). Alternatively, use the \commonlongarg{debug} switch to show |
| 18899 |
the break points in the transcript. (This will also show the |
| 18900 |
collation rule.) |
| 18901 |
|
| 18902 |
If you want to selectively apply break points only to certain |
| 18903 |
entries, use \csopt{break-at-match} or \csopt{break-at-not-match}. |
| 18904 |
|
| 18905 |
\optsection{break-marker} |
| 18906 |
|
| 18907 |
This option automatically implements the dual and secondary settings |
| 18908 |
\csopt[\meta{marker}]{dual-break-marker} and |
| 18909 |
\csopt[\meta{marker}]{secondary-break-marker}. |
| 18910 |
|
| 18911 |
The break marker can be changed using |
| 18912 |
\csopt[\meta{marker}]{break-marker}, where \meta{marker} is |
| 18913 |
the character to use. For example, \csopt[-]{break-marker} will use a |
| 18914 |
hyphen. The marker may be empty, which effectively strips the |
| 18915 |
inter-word punctuation. For example, with |
| 18916 |
\csopt[\empty]{break-marker}, \qt{Tom, Dick, and Harry} becomes |
| 18917 |
\code{TomDickandHarry} and \qt{sea lion} simply becomes |
| 18918 |
\code{sealion}. If \meta{marker} is omitted, |
| 18919 |
\csopt[\empty]{break-marker} is assumed. |
| 18920 |
|
| 18921 |
\optsection{break-at-match} |
| 18922 |
|
| 18923 |
This option automatically implements |
| 18924 |
\csopt[\meta{option}]{dual-break-at-match} and |
| 18925 |
\csopt[\meta{option}]{secondary-break-at-match}. |
| 18926 |
|
| 18927 |
If you have \csopt{break-at} set to create break points (for |
| 18928 |
example, with \csopt[word]{break-at}) then you can specify which |
| 18929 |
entries should have break points with this option. The value has the same |
| 18930 |
syntax as \csopt{match}. If an entry matches the criteria, then |
| 18931 |
break points are added, otherwise no break points are added. |
| 18932 |
For example, to only have break points for entries defined with \atentry{index} |
| 18933 |
or \atentry{indexplural}: |
| 18934 |
\begin{codeenv} |
| 18935 |
\csopt[entrytype=index(plural)?]{break-at-match} |
| 18936 |
\end{codeenv} |
| 18937 |
This option has no effect with \csopt[none]{break-at}. |
| 18938 |
|
| 18939 |
\optsection{break-at-match-op} |
| 18940 |
This option automatically implements |
| 18941 |
\csopt[\meta{option}]{dual-break-at-match-op} and |
| 18942 |
\csopt[\meta{option}]{secondary-break-at-match-op}. |
| 18943 |
|
| 18944 |
If the value of \csopt{break-at-match} contains more than one |
| 18945 |
\meta{key}=\meta{pattern} element, the \csopt{break-at-match-op} |
| 18946 |
determines whether to apply a logical AND or a logical OR. |
| 18947 |
The \meta{value} may be either \optfmt{and} or \optfmt{or}. |
| 18948 |
The default is \csopt[and]{break-at-match-op}. |
| 18949 |
|
| 18950 |
\optsection{break-at-not-match} |
| 18951 |
|
| 18952 |
This option automatically implements |
| 18953 |
\csopt[\meta{option}]{dual-break-at-not-match} and |
| 18954 |
\csopt[\meta{option}]{secondary-break-at-not-match}. |
| 18955 |
|
| 18956 |
For example, to prevent entries defined with |
| 18957 |
\atentry{symbol} from having break points: |
| 18958 |
\begin{codeenv} |
| 18959 |
\csopt[entrytype=symbol]{break-at-not-match} |
| 18960 |
\end{codeenv} |
| 18961 |
Like \csopt{break-at-match} but negates the match. |
| 18962 |
This option has no effect with \csopt[none]{break-at}. |
| 18963 |
|
| 18964 |
\optsection{sort-number-pad} |
| 18965 |
|
| 18966 |
This option automatically implements the dual and secondary settings |
| 18967 |
\csopt[\meta{number}]{dual-sort-number-pad}, |
| 18968 |
\csopt[\meta{number}]{secondary-sort-number-pad}. |
| 18969 |
|
| 18970 |
If \meta{number} is greater than 1, any integer sub-strings found |
| 18971 |
in the sort value will be zero-padded up to this value. Since the |
| 18972 |
\code{-} character is often ignored by rule-based sort methods, |
| 18973 |
any signs found will be replaced with the markers given by |
| 18974 |
\csopt{sort-pad-plus} and \csopt{sort-pad-minus}, which should be |
| 18975 |
chosen to ensure that negative numbers are ordered before positive |
| 18976 |
numbers (if this is desired). An unsigned number will have the |
| 18977 |
\csopt{sort-pad-plus} marker inserted before it. The default value |
| 18978 |
is \csopt[0]{sort-number-pad}, which doesn't implement any padding. |
| 18979 |
|
| 18980 |
If you use this with a locale sort method, it's best to also set |
| 18981 |
\csopt[none]{break-at}, as the default word boundary break points |
| 18982 |
will likely be confused by a mix of alphanumerics. |
| 18983 |
|
| 18984 |
\optsection{sort-pad-plus} |
| 18985 |
|
| 18986 |
This option automatically implements the dual and secondary settings |
| 18987 |
\csopt[\meta{marker}]{dual-sort-pad-plus}, |
| 18988 |
\csopt[\meta{marker}]{secondary-sort-pad-plus}. |
| 18989 |
|
| 18990 |
This option only has an effect when used with |
| 18991 |
\csopt[\meta{number}]{sort-number-pad} where \meta{number} is |
| 18992 |
greater than 1. Positive numbers will have their sign replaced with |
| 18993 |
\meta{marker}. The default setting is \csopt[>]{sort-pad-plus}. |
| 18994 |
|
| 18995 |
\optsection{sort-pad-minus} |
| 18996 |
|
| 18997 |
This option automatically implements the dual and secondary settings |
| 18998 |
\csopt[\meta{marker}]{dual-sort-pad-minus}, |
| 18999 |
\csopt[\meta{marker}]{secondary-sort-pad-minus}. |
| 19000 |
|
| 19001 |
This option only has an effect when used with |
| 19002 |
\csopt[\meta{number}]{sort-number-pad} where \meta{number} is |
| 19003 |
greater than 1. Negative numbers will have their sign replaced with |
| 19004 |
\meta{marker}. The default setting is \csopt[<]{sort-pad-plus}. |
| 19005 |
|
| 19006 |
\optsection{identical-sort-action} |
| 19007 |
|
| 19008 |
This option automatically implements the dual and secondary settings |
| 19009 |
\csopt[\meta{value}]{dual-identical-sort-action} and |
| 19010 |
\csopt[\meta{value}]{secondary-identical-sort-action}. |
| 19011 |
|
| 19012 |
This option determines what the comparator should do if |
| 19013 |
two entries at the same \hierarchicallevel\ are considered |
| 19014 |
equal. The \meta{value} may be one of: |
| 19015 |
\begin{itemize} |
| 19016 |
\item\optfmt{none}: don't take any further action if sort values are |
| 19017 |
identical; |
| 19018 |
\item\optfmt{def} if sort values are identical, order them according to definition; |
| 19019 |
\item\optfmt{use}: if sort values are identical, order them |
| 19020 |
according to use in the document (order determine by a normal record); |
| 19021 |
\item\optfmt{id}: if sort values are identical, compare |
| 19022 |
the entry labels; |
| 19023 |
\item\optfmt{original id}: if sort values are identical, compare the |
| 19024 |
original unprefixed entry labels (as given in the \ext{bib} file); |
| 19025 |
\item\meta{field}: if sort values are identical, compare |
| 19026 |
the values from the given \meta{field}. |
| 19027 |
\end{itemize} |
| 19028 |
For the last three cases, a simple case-sensitive string comparison is used. |
| 19029 |
If \meta{value} isn't a recognised keyword or valid field an error will occur. The |
| 19030 |
default setting is \csopt[id]{identical-sort-action}. If you're |
| 19031 |
using one of the sort rules listed in \tableref{tab:sortoptionsrule} |
| 19032 |
and you also want a locale-sensitive sort used on the fallback, then |
| 19033 |
you need to use \csopt{sort-suffix} instead. |
| 19034 |
|
| 19035 |
\bibgls\ allows duplicate sort values, but this can cause a problem |
| 19036 |
for \hierarchical\ entries where \glspl{parententry} with duplicate sort |
| 19037 |
fields are clumped together and their \children\ follow. To prevent |
| 19038 |
this from happening, the \csopt[id]{identical-sort-action} |
| 19039 |
setting will fallback on comparing the labels. Since all labels |
| 19040 |
must be unique, this means comparisons between two different entries |
| 19041 |
are all either strictly higher or strictly lower. |
| 19042 |
|
| 19043 |
This action occurs after any suffixes have been appended through |
| 19044 |
\csopt{sort-suffix}. |
| 19045 |
|
| 19046 |
\optsection{sort-suffix} |
| 19047 |
|
| 19048 |
This option automatically implements the dual and secondary settings |
| 19049 |
\csopt[\meta{value}]{dual-sort-suffix} and |
| 19050 |
\csopt[\meta{value}]{secondary-sort-suffix}. |
| 19051 |
The value may be one of: |
| 19052 |
\begin{itemize} |
| 19053 |
\item\optfmt{none}: don't append a suffix to any \field{sort} value; |
| 19054 |
\item\optfmt{non-unique}: append a numeric suffix to non-unique |
| 19055 |
\field{sort} values; |
| 19056 |
\item\meta{field}: append the value of the given field (if set) to |
| 19057 |
the \field{sort} field. The given field must be defined (has an |
| 19058 |
associated key for use in \gls{newglossaryentry}) but may be unset. |
| 19059 |
If the interpreter is on, the field contents will be interpreted. |
| 19060 |
If the field is just a label (such as the \field{category} field) |
| 19061 |
you may find it simpler to use |
| 19062 |
\csopt[\meta{field}]{identical-sort-action} instead. |
| 19063 |
\end{itemize} |
| 19064 |
The default setting is \csopt[none]{sort-suffix}. |
| 19065 |
|
| 19066 |
This option only affects the alphabetic |
| 19067 |
(\tableref{tab:sortoptionsrule}), letter |
| 19068 |
(\tableref{tab:sortoptionsletter}) and letter-number |
| 19069 |
(\tableref{tab:sortoptionsletternumber}) sort rules. For the other |
| 19070 |
types of sort methods (not including the no-sort options listed in |
| 19071 |
\tableref{tab:sortoptionsnosort}) you'll need to use |
| 19072 |
\csopt{identical-sort-action} to prevent problems occurring with |
| 19073 |
duplicate sort values. |
| 19074 |
|
| 19075 |
In the case of \csopt[non-unique]{sort-suffix}, this will only |
| 19076 |
append a suffix to the duplicate sort values (within the same |
| 19077 |
\hierarchicallevel). The first sort value to be encountered isn't |
| 19078 |
given a suffix. |
| 19079 |
|
| 19080 |
The \csopt[\meta{field}]{sort-suffix} setting will only append a suffix |
| 19081 |
if that field is set, but (if set) it will apply the suffix to all |
| 19082 |
\field{sort} values, even those that are unique. |
| 19083 |
|
| 19084 |
If you use \commonlongarg{verbose}, then \bibgls\ will write information |
| 19085 |
in the transcript when it appends a suffix to the sort value. The |
| 19086 |
message: |
| 19087 |
\begin{alltt} |
| 19088 |
Sort value '\meta{sort}' (entry '\meta{id}') not unique for the entry's |
| 19089 |
\hierarchicallevel. |
| 19090 |
\end{alltt} |
| 19091 |
indicates that an entry with the given \meta{sort} value has already |
| 19092 |
been found within the same \hierarchicallevel\ as the currently |
| 19093 |
processed entry (whose label is given by \meta{id}). The same |
| 19094 |
\hierarchicallevel\ in this context means that either both entries |
| 19095 |
don't have a \parent\ or both entries have the same \parent. (That is, |
| 19096 |
the entries are considered \glspl{sibling}.) |
| 19097 |
|
| 19098 |
This message will then be followed by: |
| 19099 |
\begin{alltt} |
| 19100 |
Appending suffix '\meta{suffix}' to the sort value '\meta{sort}' |
| 19101 |
for entry '\meta{id}'. |
| 19102 |
\end{alltt} |
| 19103 |
which indicates that the entry (identified by the label \meta{id}) |
| 19104 |
has been assigned the sort value given by \meta{sort}\meta{suffix}. |
| 19105 |
If any break markers are applied, this is done after the suffix has |
| 19106 |
been appended. |
| 19107 |
|
| 19108 |
For example, suppose in my document I want to write about \appfmt{makeglossaries} |
| 19109 |
(the application) and \csfmt{makeglossaries} (the command). I might |
| 19110 |
decide to define semantic commands: |
| 19111 |
\begin{codeenv} |
| 19112 |
\cs{newcommand}*\marg{\cmd{application}}[1]\marg{\ics{texttt}\marg{\idx{param}1}} |
| 19113 |
\cs{newcommand}*\marg{\cmd{command}}[1]\marg{\cs{texttt}\marg{\cs{glsbackslash} \idx{param}1}} |
| 19114 |
\end{codeenv} |
| 19115 |
In my \ext{bib} file I might have: |
| 19116 |
\begin{codeenv} |
| 19117 |
\atentry{entry}\marg{cs.makeglossaries, |
| 19118 |
\field{name}=\marg{\cmd{command}\marg{makeglossaries}}, |
| 19119 |
\field{category}=\marg{command}, |
| 19120 |
\field{description}=\marg{opens glossary files} |
| 19121 |
} |
| 19122 |
\strut |
| 19123 |
\atentry{entry}\marg{ap.makeglossaries, |
| 19124 |
\field{name}=\marg{\cmd{application}\marg{makeglossaries}}, |
| 19125 |
\field{category}=\marg{application}, |
| 19126 |
\field{description}=\marg{Perl script} |
| 19127 |
} |
| 19128 |
\end{codeenv} |
| 19129 |
If \bibgls\ is provided with the definitions of \csfmt{application} |
| 19130 |
and \csfmt{command} (by interpreting the \atentry{preamble} or a |
| 19131 |
package provided with \longarg{custom-packages}) then it will |
| 19132 |
determine that the sort value for \code{cs.makeglossaries} is |
| 19133 |
\csfmt{makeglossaries} and the sort value for |
| 19134 |
\code{ap.makeglossaries} is just \code{makeglossaries}. These are |
| 19135 |
two distinct sort values from \bibgls's point of view although the |
| 19136 |
sort rule may consider them identical if the rule ignores the |
| 19137 |
\idx{escchar} character (such as the locale sort methods), in which case, |
| 19138 |
\bibgls\ will then act according to \csopt{identical-sort-action}. |
| 19139 |
|
| 19140 |
If \bibgls\ isn't provided with these custom definitions, then it |
| 19141 |
will ignore those semantic commands and both entries will end up with |
| 19142 |
the sort value \code{makeglossaries}. The second instance will be |
| 19143 |
recognised as a duplicate and the sort value will be converted to |
| 19144 |
\code{makeglossaries1} (where the automated suffix is \code{1} and |
| 19145 |
the suffix marker, see below, is the empty string). Whereas with, |
| 19146 |
say, \csopt[.]{sort-suffix-marker}\ then the sort value would become |
| 19147 |
\code{makeglossaries.1}. |
| 19148 |
|
| 19149 |
For comparison, consider the following document: |
| 19150 |
\begin{codeenv} |
| 19151 |
\cmd{documentclass}\marg{article} |
| 19152 |
\strut |
| 19153 |
\cmd{usepackage}[\styopt[indexgroup]{style}]\marg{glossaries} |
| 19154 |
\strut |
| 19155 |
\ics{cs.makeglossaries} |
| 19156 |
\strut |
| 19157 |
\cs{newcommand}*\marg{\cmd{application}}[1]\marg{\cs{texttt}\marg{\idx{param}1}} |
| 19158 |
\cs{newcommand}*\marg{\cmd{command}}[1]\marg{\cs{texttt}\marg{\cs{glsbackslash} \idx{param}1}} |
| 19159 |
\strut |
| 19160 |
\gls{newglossaryentry}\marg{cs.makeglossaries}\marg{\comment{} |
| 19161 |
\field{name}=\marg{\cmd{command}\marg{makeglossaries}}, |
| 19162 |
\field{description}=\marg{opens glossary files}} |
| 19163 |
\strut |
| 19164 |
\gls{newglossaryentry}\marg{ap.makeglossaries}\marg{\comment{} |
| 19165 |
\field{name}=\marg{\cmd{application}\marg{makeglossaries}}, |
| 19166 |
\field{description}=\marg{Perl script}} |
| 19167 |
\strut |
| 19168 |
\cmd{begin}\marg{document} |
| 19169 |
\cs{gls}\marg{cs.makeglossaries} and \cs{gls}\marg{ap.makeglossaries}. |
| 19170 |
\ics{printglossaries} |
| 19171 |
\cmd{end}\marg{document} |
| 19172 |
\end{codeenv} |
| 19173 |
|
| 19174 |
This uses \idx{makeindex}, which puts both entries in the |
| 19175 |
\qt{Symbols} group (since they both start with \idx{escchar} from the |
| 19176 |
start of \csfmt{command} and \csfmt{application}, respectively). |
| 19177 |
The ordering is \appfmt{makeglossaries}, \csfmt{makeglossaries} |
| 19178 |
because \qt{a} (second character of \csfmt{application}) comes |
| 19179 |
before \qt{c} (second character of \csfmt{command}). |
| 19180 |
|
| 19181 |
The switch to \idx{xindy} just involves adding the \styopt{xindy} |
| 19182 |
package option: |
| 19183 |
\begin{codeenv} |
| 19184 |
\cs{usepackage}[\styopt{xindy},\styopt[indexgroup]{style}]\marg{glossaries} |
| 19185 |
\end{codeenv} |
| 19186 |
This results in a glossary that only contains one entry, |
| 19187 |
\csfmt{makeglossaries}, because \idx{xindy} merges entries with |
| 19188 |
duplicate sort values and the sort values end up as duplicates |
| 19189 |
because \idx{xindy} discards the \csfmt{application} and |
| 19190 |
\csfmt{command} control sequences. Although \bibgls\ also ignores |
| 19191 |
unknown control sequences, it doesn't perform this merger. |
| 19192 |
|
| 19193 |
If I add: |
| 19194 |
\begin{codeenv} |
| 19195 |
\atentry{preamble}\marg{\qtdelim{\cs{providecommand}*\marg{\cmd{application}}[1]\marg{\cs{texttt}\marg{\idx{param}1}} |
| 19196 |
\cs{providecommand}\marg{\cmd{command}}[1]\marg{\cs{texttt}\marg{\cs{glsbackslash} \idx{param}1}}}} |
| 19197 |
\end{codeenv} |
| 19198 |
to the earlier \ext{bib} file (called, say, \filefmt{entries.bib}) |
| 19199 |
then the document can be altered to use \bibgls: |
| 19200 |
\begin{codeenv} |
| 19201 |
\cmd{documentclass}\marg{article} |
| 19202 |
\strut |
| 19203 |
\cmd{usepackage}[\styopt{record},\styopt[indexgroup]{style}]\marg{glossaries-extra} |
| 19204 |
\strut |
| 19205 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries.bib]{src}, |
| 19206 |
\csopt[non-unique]{sort-suffix}, |
| 19207 |
\csopt[none]{identical-sort-action} |
| 19208 |
} |
| 19209 |
\strut |
| 19210 |
\cmd{begin}\marg{document} |
| 19211 |
\cs{gls}\marg{cs.makeglossaries} and \cs{gls}\marg{ap.makeglossaries}. |
| 19212 |
\cs{printunsrtglossaries} |
| 19213 |
\cmd{end}\marg{document} |
| 19214 |
\end{codeenv} |
| 19215 |
This uses the default \csopt[locale]{sort} which considers \idx{escchar} |
| 19216 |
an ignored (punctuation) character, so both \csfmt{makeglossaries} and |
| 19217 |
\appfmt{makeglossaries} are listed in the \qt{M} letter group, even |
| 19218 |
though the interpreter has determined that the sort value for |
| 19219 |
\code{cs.makeglossaries} is the literal string \csfmt{makeglossaries}. |
| 19220 |
Note that in this case \bibgls\ doesn't detect duplicate sort values |
| 19221 |
since it only uses a simple string comparison to detect duplicates |
| 19222 |
rather than using the collator. |
| 19223 |
|
| 19224 |
If I switch to using a letter-based sort rule instead, for example |
| 19225 |
\csopt[letter-nocase]{sort}, then \csfmt{makeglossaries} will be |
| 19226 |
listed in the \qt{Symbols} letter group since the leading \idx{escchar} |
| 19227 |
from the sort value \csfmt{makeglossaries} isn't ignored with this |
| 19228 |
rule. |
| 19229 |
|
| 19230 |
Now let's suppose I use \csopt[false]{interpret-preamble} to prevent |
| 19231 |
\bibgls\ from interpreting the preamble: |
| 19232 |
\begin{codeenv} |
| 19233 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries.bib]{src},\csopt[false]{interpret-preamble}} |
| 19234 |
\end{codeenv} |
| 19235 |
This means that the custom commands won't be recognised and will |
| 19236 |
therefore be ignored, so both entries will have their sort values reduced to |
| 19237 |
\code{makeglosssaries}. |
| 19238 |
|
| 19239 |
The first entry to be processed is \code{cs.makeglossaries} because |
| 19240 |
it's the first to be selected. This is assigned the sort value |
| 19241 |
\code{makeglossaries}. (Note that, unless you use |
| 19242 |
\csopt[unsrt]{sort}, the initial selection order is based on the record |
| 19243 |
order. In this example, \code{cs.makeglossaries} has the first |
| 19244 |
record in the \ext{aux} file.) |
| 19245 |
|
| 19246 |
The next entry to be processed is \code{ap.makeglossaries}. This |
| 19247 |
also ends up with the sort value \code{makeglossaries} so \bibgls\ |
| 19248 |
converts this to \code{makeglossaries1} and (with verbose mode on) |
| 19249 |
the following messages are written to the transcript: |
| 19250 |
\begin{verbatim} |
| 19251 |
Sort value 'makeglossaries' (entry 'ap.makeglossaries') not unique |
| 19252 |
for the entry's hierarchical level. |
| 19253 |
Appending suffix '1' to the sort value 'makeglossaries' for entry |
| 19254 |
'ap.makeglossaries'. |
| 19255 |
\end{verbatim} |
| 19256 |
Both entries are listed in the \qt{M} letter group in the order |
| 19257 |
\csfmt{makeglossaries}, \appfmt{makeglossaries}. |
| 19258 |
|
| 19259 |
If the records are reversed: |
| 19260 |
\begin{codeenv} |
| 19261 |
\cs{gls}\marg{ap.makeglossaries} and \cs{gls}\marg{cs.makeglossaries}. |
| 19262 |
\end{codeenv} |
| 19263 |
then the sort value for \code{cs.makeglossaries} is now considered |
| 19264 |
the duplicate and the order is reversed: \appfmt{makeglossaries}, |
| 19265 |
\csfmt{makeglossaries}. |
| 19266 |
|
| 19267 |
Suppose now I modify the \ext{bib} file so that |
| 19268 |
\code{ap.makeglossaries} is defined as: |
| 19269 |
\begin{codeenv} |
| 19270 |
\atentry{entry}\marg{ap.makeglossaries, |
| 19271 |
\field{name}=\marg{\cmd{application}\marg{makeglossaries}}, |
| 19272 |
\field{category}=\marg{application}, |
| 19273 |
\field{description}=\marg{Perl script (must be used with \cs{gls}\marg{cs.makeglossaries})} |
| 19274 |
} |
| 19275 |
\end{codeenv} |
| 19276 |
and suppose the document only contains an explicit reference to |
| 19277 |
\code{ap.makeglossaries}: |
| 19278 |
\begin{codeenv} |
| 19279 |
\cmd{begin}\marg{document} |
| 19280 |
\cs{gls}\marg{ap.makeglossaries} |
| 19281 |
\cs{printunsrtglossaries} |
| 19282 |
\cmd{end}\marg{document} |
| 19283 |
\end{codeenv} |
| 19284 |
Now \code{ap.makeglossaries} is the first entry to be selected |
| 19285 |
because entries with records are always selected before any |
| 19286 |
(unrecorded) dependencies. In this case \code{cs.makeglossaries} is |
| 19287 |
only selected because it's required by \code{ap.makeglossaries}. Now |
| 19288 |
\code{ap.makeglossaries} is the first to have its sort value |
| 19289 |
assigned, and it's \code{cs.makeglossaries} that has the duplicate. |
| 19290 |
This means that the ordering in the glossary is now: |
| 19291 |
\appfmt{makeglossaries}, \csfmt{makeglossaries}. |
| 19292 |
|
| 19293 |
An oddity occurs if the glossary is moved to the start of the |
| 19294 |
document: |
| 19295 |
\begin{codeenv} |
| 19296 |
\cmd{begin}\marg{document} |
| 19297 |
\cs{printunsrtglossaries} |
| 19298 |
\cs{gls}\marg{ap.makeglossaries} |
| 19299 |
\cmd{end}\marg{document} |
| 19300 |
\end{codeenv} |
| 19301 |
In this case, the first document build: |
| 19302 |
\begin{verbatim} |
| 19303 |
pdflatex myDoc |
| 19304 |
bibgls --group --verbose myDoc |
| 19305 |
pdflatex myDoc |
| 19306 |
\end{verbatim} |
| 19307 |
leads to the ordering described above: |
| 19308 |
\appfmt{makeglossaries}, \csfmt{makeglossaries}. |
| 19309 |
However, the next document build has a new record for |
| 19310 |
\code{cs.makeglossaries} occurring in the glossary (within the |
| 19311 |
description of \code{ap.makeglossaries}) which means it's now the |
| 19312 |
first entry to be selected so the ordering switches to: |
| 19313 |
\csfmt{makeglossaries}, \appfmt{makeglossaries}. |
| 19314 |
In this type of situation you might be better off with the |
| 19315 |
\csopt[id]{identical-sort-action} option instead. |
| 19316 |
|
| 19317 |
Remember that you can temporarily switch off the indexing by locally |
| 19318 |
setting: |
| 19319 |
\begin{codeenv*} |
| 19320 |
\ics{GlsXtrSetDefaultGlsOpts}\marg{\glsopt{noindex}} |
| 19321 |
\end{codeenv*} |
| 19322 |
Since the glossary preamble is scoped, you can simply do |
| 19323 |
\begin{codeenv} |
| 19324 |
\ics{appto}\ics{glossarypreamble}\marg{\cs{GlsXtrSetDefaultGlsOpts}\marg{\glsopt{noindex}}} |
| 19325 |
\end{codeenv} |
| 19326 |
to switch off the indexing within the glossary (or use |
| 19327 |
\ics{apptoglossarypreamble}). Note that this is |
| 19328 |
different to using: |
| 19329 |
\begin{codeenv} |
| 19330 |
\ics{GlsXtrSetDefaultNumberFormat}\marg{\encap{glsignore}} |
| 19331 |
\end{codeenv} |
| 19332 |
which creates an \igls{ignoredrecord}. Even though the record is ignored |
| 19333 |
(and so won't show in the \gls{locationlist}) the record still influences |
| 19334 |
the selection order and the record count. |
| 19335 |
|
| 19336 |
\optsection{sort-suffix-marker} |
| 19337 |
|
| 19338 |
This automatically implements the dual and secondary settings |
| 19339 |
\csopt[\meta{value}]{dual-sort-suffix-marker} and |
| 19340 |
\csopt[\meta{value}]{secondary-sort-suffix-marker}. |
| 19341 |
|
| 19342 |
If a suffix is appended to the sort value (see above) then it will |
| 19343 |
be separated by the suffix marker, which can be set with |
| 19344 |
\csopt[\meta{value}]{sort-suffix-marker} where \meta{value} is the |
| 19345 |
marker. By default the marker is empty. You can use \stringu\meta{hex} |
| 19346 |
or \cs{glshex}\meta{hex} to indicate Unicode characters outside the |
| 19347 |
\idx{ASCII} range. If, for some reason, you want to use a special |
| 19348 |
character, such as \idx{param}, you will need to precede it with |
| 19349 |
\ics{cs.string} (for example \code{\cs{cs.string}\idx{param}}) or |
| 19350 |
use the above hexadecimal markup. If you use \ics{cs.hash} it will |
| 19351 |
be treated as a literal string containing a backslash followed by a |
| 19352 |
hash character. |
| 19353 |
|
| 19354 |
\optsection{encapsulate-sort} |
| 19355 |
|
| 19356 |
This option will encapsulate the sort value (after modifications such |
| 19357 |
as \csopt{sort-suffix} and \csopt{sort-number-pad}) with |
| 19358 |
\csfmt{\meta{csname}}\marg{value}\marg{entry-id} where \meta{value} |
| 19359 |
is the sort value that would otherwise have been used and |
| 19360 |
\meta{entry-id} is the entry's label. It will then be interpreted |
| 19361 |
(if enabled). Note that \meta{value} may already have been |
| 19362 |
interpreted in a previous step. |
| 19363 |
|
| 19364 |
\optsection{strength} |
| 19365 |
|
| 19366 |
This option automatically implements |
| 19367 |
\csopt[\meta{value}]{dual-strength} and |
| 19368 |
\csopt[\meta{value}]{secondary-strength}. |
| 19369 |
|
| 19370 |
The collation strength used by the alphabet sort methods |
| 19371 |
(\tableref{tab:sortoptionsrule}) can be set to the following values: |
| 19372 |
\glsdisp{primarycollatorstrength}{\optfmt{primary}} (default), |
| 19373 |
\glsdisp{secondarycollatorstrength}{\optfmt{secondary}}, |
| 19374 |
\glsdisp{tertiarycollatorstrength}{\optfmt{tertiary}} or |
| 19375 |
\glsdisp{identicalcollatorstrength}{\optfmt{identical}}. These |
| 19376 |
indicate the difference between two characters, but the exact |
| 19377 |
assignment is locale dependent. See the documentation for Java's |
| 19378 |
\href{http://docs.oracle.com/javase/8/docs/api/java/text/Collator.html}{\code{Collator} |
| 19379 |
class}~\cite{collator} for further details. |
| 19380 |
|
| 19381 |
For example, suppose the file \filefmt{entries.bib} contains: |
| 19382 |
\begin{codeenv} |
| 19383 |
\atentry{index}\marg{resume} |
| 19384 |
\atentry{index}\marg{RESUME} |
| 19385 |
\atentry{index}\marg{resumee, \field{name}=\marg{r\ics{acute}esum\cs{acute}e}} |
| 19386 |
\atentry{index}\marg{rat} |
| 19387 |
\atentry{index}\marg{rot} |
| 19388 |
\atentry{index}\marg{aardvark} |
| 19389 |
\atentry{index}\marg{zoo} |
| 19390 |
\end{codeenv} |
| 19391 |
and the document contains: |
| 19392 |
\begin{codeenv} |
| 19393 |
\cmd{documentclass}\marg{article} |
| 19394 |
\strut |
| 19395 |
\cmd{usepackage}[\styopt{record}]\marg{glossaries-extra} |
| 19396 |
\strut |
| 19397 |
\gls{GlsXtrLoadResources}\oarg{\csopt[en]{sort},\csopt[entries]{src}} |
| 19398 |
\strut |
| 19399 |
\cmd{begin}\marg{document} |
| 19400 |
\cs{gls}\marg{resumee}, \cs{gls}\marg{resume}, \cs{gls}\marg{RESUME}, |
| 19401 |
\cs{gls}\marg{aardvark}, \cs{gls}\marg{rat}, \cs{gls}\marg{rot}, \cs{gls}\marg{zoo}. |
| 19402 |
\strut |
| 19403 |
\cs{printunsrtglossaries} |
| 19404 |
\cmd{end}\marg{document} |
| 19405 |
\end{codeenv} |
| 19406 |
then this uses the default \csopt[primary]{strength}, so the entries |
| 19407 |
are listed as aardvark, rat, r\'esum\'e, resume, RESUME, rot, zoo. |
| 19408 |
|
| 19409 |
If the strength is changed to \optfmt{secondary}: |
| 19410 |
\begin{codeenv} |
| 19411 |
\gls{GlsXtrLoadResources}\oarg{\csopt[en]{sort},\csopt[entries]{src},\csopt[secondary]{strength}} |
| 19412 |
\end{codeenv} |
| 19413 |
then the entries are listed as aardvark, rat, resume, RESUME, |
| 19414 |
r\'esum\'e, rot, zoo. |
| 19415 |
|
| 19416 |
If the strength is changed to \optfmt{tertiary} or |
| 19417 |
\optfmt{identical}, there's no difference from |
| 19418 |
\csopt[secondary]{strength} for this particular example. |
| 19419 |
|
| 19420 |
This option is ignored by non-alphabet sorts (such as letter or numeric). |
| 19421 |
|
| 19422 |
\optsection{decomposition} |
| 19423 |
|
| 19424 |
This option automatically implements the dual and secondary settings |
| 19425 |
\csopt[\meta{value}]{dual-decomposition} and |
| 19426 |
\csopt[\meta{value}]{secondary-decomposition}. |
| 19427 |
|
| 19428 |
The collation decomposition used by alphabet sort methods |
| 19429 |
(\tableref{tab:sortoptionsrule}) can be set |
| 19430 |
to the following values: \optfmt{canonical} (default), |
| 19431 |
\optfmt{full} or \optfmt{none}. This determines how Unicode composed |
| 19432 |
characters are handled. The fastest mode is \optfmt{none} but is |
| 19433 |
only appropriate for languages without accents. The slowest mode is |
| 19434 |
\optfmt{full} but is the most complete for languages with \idx{non-ASCII} |
| 19435 |
characters. See the documentation for Java's |
| 19436 |
\href{http://docs.oracle.com/javase/8/docs/api/java/text/Collator.html}{\code{Collator} |
| 19437 |
class}~\cite{collator} for further details. |
| 19438 |
This option is ignored by non-alphabet sorts (such as letter or numeric). |
| 19439 |
|
| 19440 |
\optsection{letter-number-rule} |
| 19441 |
|
| 19442 |
This automatically implements the dual and secondary settings |
| 19443 |
\csopt[\meta{value}]{dual-letter-number-rule} |
| 19444 |
and |
| 19445 |
\csopt[\meta{value}]{secondary-letter-number-rule}. |
| 19446 |
|
| 19447 |
If you use one of the letter-number sort methods |
| 19448 |
(\tableref{tab:sortoptionsletternumber}), then you can determine the |
| 19449 |
comparison between a number and letter. The \meta{value} may be |
| 19450 |
one of: |
| 19451 |
\begin{itemize} |
| 19452 |
\item\optfmt{before letter}: numbers are considered less than any |
| 19453 |
letter. |
| 19454 |
|
| 19455 |
\item\optfmt{after letter}: numbers are considered greater than any |
| 19456 |
letter. |
| 19457 |
|
| 19458 |
\item\optfmt{between}: (default) numbers come between letter cases. |
| 19459 |
With the \optfmt{letternumber\dhyphen case} sort option, this will put |
| 19460 |
numbers after \idx{uppercase} and before \idx{lowercase}. This |
| 19461 |
setting doesn't make much sense with the |
| 19462 |
\optfmt{letternumber\dhyphen nocase} option but, if used, this will put |
| 19463 |
numbers before letters. The \optfmt{letternumber\dhyphen upperlower} and |
| 19464 |
\optfmt{letternumber\dhyphen lowerupper} options are more complicated. See |
| 19465 |
\sectionref{sec:letternumber} for more detail. |
| 19466 |
|
| 19467 |
\item\optfmt{first}: numbers are considered less than all |
| 19468 |
characters (including punctuation and spaces). |
| 19469 |
|
| 19470 |
\item\optfmt{last}: numbers are considered greater than all |
| 19471 |
characters (including punctuation and spaces). |
| 19472 |
\end{itemize} |
| 19473 |
Note that the reverse sort methods will invert this setting. |
| 19474 |
Remember also that the case-insensitive letter-number sort methods always |
| 19475 |
first convert the \field{sort} field to \idx{lowercase}, which means that |
| 19476 |
if you use one of them then there won't be any \idx{uppercase} |
| 19477 |
characters. |
| 19478 |
|
| 19479 |
Use \csopt{letter-number-punc-rule} to determine the relative |
| 19480 |
position of white space and punctuation. |
| 19481 |
|
| 19482 |
\optsection{letter-number-punc-rule} |
| 19483 |
|
| 19484 |
This automatically implements the dual and secondary |
| 19485 |
\csopt[\meta{value}]{dual-letter-number-punc-rule} |
| 19486 |
and |
| 19487 |
\csopt[\meta{value}]{secondary-letter-number-punc-rule}. |
| 19488 |
|
| 19489 |
If you use one of the letter-number sort methods |
| 19490 |
(\tableref{tab:sortoptionsletternumber}), then you can determine the |
| 19491 |
order of white space and punctuation. In this context, punctuation |
| 19492 |
means any character that's not considered a letter, a number |
| 19493 |
or white space. This means that characters such as combining marks |
| 19494 |
are considered punctuation. |
| 19495 |
|
| 19496 |
The \meta{value} may be one of the following: |
| 19497 |
\begin{itemize} |
| 19498 |
\item\optfmt{punc-space-first}: punctuation comes first, followed by |
| 19499 |
white space (then letters and optionally numbers according to the letter-number |
| 19500 |
rule); |
| 19501 |
\item\optfmt{punc-space-last}: punctuation followed by white space |
| 19502 |
come last (after letters and optionally numbers according to the letter-number |
| 19503 |
rule); |
| 19504 |
\item\optfmt{space-punc-first}: white space comes first, followed by |
| 19505 |
punctuation (then letters and optionally numbers according to the letter-number |
| 19506 |
rule); |
| 19507 |
\item\optfmt{space-punc-last}: white space followed by punctuation |
| 19508 |
come last (after letters and optionally numbers according to the letter-number |
| 19509 |
rule); |
| 19510 |
\item\optfmt{space-first-punc-last}: white space comes first |
| 19511 |
(followed by letters and optionally numbers according to the letter-number |
| 19512 |
rule) and punctuation comes last; |
| 19513 |
\item\optfmt{punc-first-space-last}: punctuation comes first |
| 19514 |
(followed by letters and optionally numbers according to the letter-number |
| 19515 |
rule) and white space comes last; |
| 19516 |
\item\optfmt{punc-first-space-zero}: punctuation comes first |
| 19517 |
(although numbers may come before) |
| 19518 |
and white space is replaced by the digit~\code{0} (\hex{30}); |
| 19519 |
\item\optfmt{punc-last-space-zero}: punctuation comes last |
| 19520 |
(although numbers may come after) |
| 19521 |
and white space is replaced by the digit~\code{0} (\hex{30}). |
| 19522 |
\item\optfmt{punc-first-space-zero-match-next}: punctuation comes first |
| 19523 |
(although numbers may come before) |
| 19524 |
and white space is replaced by the appropriate zero character (see below); |
| 19525 |
\item\optfmt{punc-last-space-zero-match-next}: punctuation comes last |
| 19526 |
(although numbers may come after) |
| 19527 |
and white space is replaced by the appropriate zero character (see below). |
| 19528 |
\end{itemize} |
| 19529 |
Remember that the reverse sort methods will invert order governed by this setting. |
| 19530 |
|
| 19531 |
For the \optfmt{space-zero-match-next} settings, the sort value will |
| 19532 |
have all spaces replaced with a digit that represents zero. If the |
| 19533 |
space isn't followed by a digit, the basic Latin \code{0} (\hex{30}) |
| 19534 |
will be used, otherwise \bibgls\ will try to match the zero with the |
| 19535 |
following digit group. For example, if the space is followed by |
| 19536 |
\textsuperscript{1} (\hex{B9}) the space will be replaced by |
| 19537 |
\textsuperscript{0} (\hex{2070}), resulting in the sub-string |
| 19538 |
\code{\textsuperscript{01}} (\hex{B9} \hex{2070}). |
| 19539 |
|
| 19540 |
If just the \optfmt{space-zero} |
| 19541 |
(without the \optfmt{-match-next}) is used then the space will just |
| 19542 |
be replaced with \code{0} resulting in the sub-string |
| 19543 |
\code{0\textsuperscript{1}} (\hex{30} \hex{2070}). In this case, the |
| 19544 |
\code{0} will be distinct from \textsuperscript{1} (rather than |
| 19545 |
being considered a leading zero). However, for |
| 19546 |
other numbering systems the \code{0} will be treated as a leading |
| 19547 |
zero. For example, if the space is followed by the Devanagari digit |
| 19548 |
one (\hex{0967}) then the sub-string will be \hex{30} \hex{0967} but here the |
| 19549 |
mixture is allowed to form a number (with a leading zero) as both |
| 19550 |
characters belong to the Unicode category \idx{numberdecimaldigit}. |
| 19551 |
|
| 19552 |
This means that the \optfmt{-match-next} settings are only really |
| 19553 |
needed if the sort string contains the superscript or subscript |
| 19554 |
digits that don't belong to the \qt{Number, Decimal Digit} category. |
| 19555 |
The plain \optfmt{space-zero} alternatives are more efficient as |
| 19556 |
they just perform a simple substitution. |
| 19557 |
|
| 19558 |
The \texparserlib\ used by \bibgls\ recognises the standard |
| 19559 |
\LaTeX\ text-mode commands \ics{textsuperscript}\margm{text} and |
| 19560 |
\ics{textsubscript}\margm{text} |
| 19561 |
and will use the Unicode superscript or subscript characters if they cover every |
| 19562 |
character in \meta{text}, otherwise HTML markup is used, but that's |
| 19563 |
then stripped by \bibgls. This means that: |
| 19564 |
\begin{codeenv} |
| 19565 |
C\cs{textsubscript}\marg{10}H\cs{textsubscript}\marg{10}O\cs{textsubscript}\marg{4} |
| 19566 |
\end{codeenv} |
| 19567 |
will be converted to: |
| 19568 |
\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}} but: |
| 19569 |
\begin{codeenv} |
| 19570 |
X\cs{textsubscript}\marg{1, 2} |
| 19571 |
\end{codeenv} |
| 19572 |
will be converted to: |
| 19573 |
\begin{verbatim} |
| 19574 |
X<sub>1, 2</sub> |
| 19575 |
\end{verbatim} |
| 19576 |
which ends up as \code{X1, 2}. |
| 19577 |
|
| 19578 |
|
| 19579 |
Note that \csopt[first]{letter-number-rule} and |
| 19580 |
\csopt[last]{letter-number-rule} overrides this option when |
| 19581 |
comparing a number with white space or punctuation. |
| 19582 |
|
| 19583 |
\optsection{numeric-sort-pattern} |
| 19584 |
|
| 19585 |
If you use the custom \csopt[numberformat]{sort} or |
| 19586 |
\csopt[numberformat-reverse]{sort}, you need to |
| 19587 |
specify the format pattern with this option where |
| 19588 |
\meta{value} is a pattern recognised by Java's |
| 19589 |
\href{http://docs.oracle.com/javase/8/docs/api/java/text/DecimalFormat.html}{\code{java.text.DecimalFormat}} |
| 19590 |
class~\cite{decimalformat}. You can use \stringu\meta{hex} or |
| 19591 |
\cs{glshex}\meta{hex} to indicate Unicode characters by their |
| 19592 |
hexadecimal code. You can also use \ics{cs.hash}, \ics{cs.percent}, |
| 19593 |
\ics{cs.underscore}, \ics{cs.amp}, \ics{cs.openbrace} and |
| 19594 |
\ics{cs.closebrace} to indicate \idx{hashchar}, \idx{percentchar}, |
| 19595 |
\idx{underscorechar}, \idx{ampchar}, \idx{openbracechar} and |
| 19596 |
\idx{closebracechar}. |
| 19597 |
|
| 19598 |
Where the dual or secondary sort uses \optfmt{numberformat} |
| 19599 |
or \optfmt{numberformat-reverse}, use \csopt{dual-numeric-sort-pattern} for |
| 19600 |
\csopt{dual-sort} and \csopt{secondary-numeric-sort-pattern} |
| 19601 |
for \csopt{secondary}. |
| 19602 |
|
| 19603 |
\optsection{numeric-locale} |
| 19604 |
|
| 19605 |
If you use any of the locale-sensitive numeric sort methods |
| 19606 |
described in \sectionref{sec:numerical}, |
| 19607 |
such as \csopt[numeric]{sort}, use this option to set |
| 19608 |
the locale if the default \gls{resource-locale} isn't appropriate. The value may be: |
| 19609 |
\begin{itemize} |
| 19610 |
\item\optfmt{resource}: use the default \gls{resource-locale}, if |
| 19611 |
set, otherwise assume \optfmt{doc}; |
| 19612 |
\item\optfmt{doc}: use the \gls{document-locale} or, if not set, assume |
| 19613 |
\csopt[locale]{numeric-locale}; |
| 19614 |
\item\optfmt{locale}: use the \gls{Java-locale} (which is usually |
| 19615 |
the operating system's locale); |
| 19616 |
\item\meta{lang-tag}: set to the locale identified by the given |
| 19617 |
a valid language tag \meta{lang-tag}. |
| 19618 |
\end{itemize} |
| 19619 |
Use \csopt{dual-numeric-locale} for |
| 19620 |
\csopt{dual-sort} and \csopt{secondary-numeric-locale} |
| 19621 |
for \csopt{secondary}. |
| 19622 |
|
| 19623 |
\begin{important} |
| 19624 |
If you use the \csopt{locale} resource option with \csopt[resource]{numeric-locale}, |
| 19625 |
then the \csopt{locale} option must be come before |
| 19626 |
\csopt{numeric-locale}. |
| 19627 |
\end{important} |
| 19628 |
|
| 19629 |
\optsection{date-sort-locale} |
| 19630 |
|
| 19631 |
If you use a date/time sort method (\tableref{tab:sortoptionsdatetime}), |
| 19632 |
then you can set the locale used by Java's date-time parser. |
| 19633 |
The default setting is \csopt[resource]{date-sort-locale}. |
| 19634 |
|
| 19635 |
The value may be \optfmt{resource} (use the \gls{resource-locale}), |
| 19636 |
\optfmt{doc} (use the \gls{document-locale}), |
| 19637 |
\optfmt{locale} (use the \gls{Java-locale}), |
| 19638 |
or a valid language tag \meta{lang-tag} identifying the locale. |
| 19639 |
|
| 19640 |
Use \csopt{dual-date-sort-locale} and \csopt{secondary-date-sort-locale} |
| 19641 |
for the dual and secondary. |
| 19642 |
|
| 19643 |
\begin{important} |
| 19644 |
If you use the \csopt{locale} resource option with \csopt[resource]{date-sort-locale}, |
| 19645 |
then the \csopt{locale} option must be come before |
| 19646 |
\csopt{date-sort-locale}. |
| 19647 |
\end{important} |
| 19648 |
|
| 19649 |
\optsection{date-sort-format} |
| 19650 |
|
| 19651 |
If you use a date/time sort method (\tableref{tab:sortoptionsdatetime}), |
| 19652 |
then you can set the format used by Java's date-time parser. |
| 19653 |
If omitted, \csopt[default]{date-sort-format} is assumed. |
| 19654 |
The \meta{value} may be one of: |
| 19655 |
\begin{itemize} |
| 19656 |
\item\optfmt{default}: use the locale's default format. |
| 19657 |
\item\optfmt{short}: use the locale's short format. |
| 19658 |
\item\optfmt{medium}: use the locale's medium format. |
| 19659 |
\item\optfmt{long}: use the locale's long format. |
| 19660 |
\item\optfmt{full}: use the locale's full format. |
| 19661 |
\item\meta{pattern}: provide a custom pattern. |
| 19662 |
This should match the specifications for Java's |
| 19663 |
\href{http://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html}{\code{SimpleDateFormat}} |
| 19664 |
class~\cite{simpledateformat}. You may use \stringu\meta{hex} or |
| 19665 |
\code{\cs{glshex} \meta{hex}} to indicate Unicode characters |
| 19666 |
or \ics{cs.hash}, \ics{cs.percent}, \ics{cs.underscore}, \ics{cs.amp}, |
| 19667 |
\ics{cs.openbrace} and \ics{cs.closebrace} to indicate |
| 19668 |
\idx{hashchar}, \idx{percentchar}, \idx{underscorechar}, |
| 19669 |
\idx{ampchar}, \idx{openbracechar} and~\idx{closebracechar}. |
| 19670 |
\end{itemize} |
| 19671 |
|
| 19672 |
With the custom setting, if the pattern only contains date (but not |
| 19673 |
time) information, then it must be used with \csopt[date]{sort} |
| 19674 |
or \csopt[date-reverse]{sort}. If the pattern only contains time |
| 19675 |
(but not date) information, then it must be used with |
| 19676 |
\csopt[time]{sort} or \csopt[time\dhyphen reverse]{sort}. If the pattern |
| 19677 |
contains date and time information, then it must be used with |
| 19678 |
\csopt[datetime]{sort} or \csopt[datetime-reverse]{sort}. |
| 19679 |
|
| 19680 |
For example, suppose each entry provides information about a person |
| 19681 |
and the \field{user1} field is used to store their date of birth: |
| 19682 |
\begin{codeenv} |
| 19683 |
\atentry{entry}\marg{caesar, |
| 19684 |
\field{name}=\marg{Gaius Julius Caesar}, |
| 19685 |
\field{first}=\marg{Julius Caesar}, |
| 19686 |
\field{text}=\marg{Caesar}, |
| 19687 |
\field{description}=\marg{Roman politician and general}, |
| 19688 |
\field{user1}=\marg{13 July 100 BC} |
| 19689 |
} |
| 19690 |
\strut |
| 19691 |
\atentry{entry}\marg{wellington, |
| 19692 |
\field{name}=\marg{Arthur Wellesley, 1st Duke of Wellington}, |
| 19693 |
\field{first}=\marg{Arthur Wellesley (Duke of Wellington)}, |
| 19694 |
\field{text}=\marg{Wellington}, |
| 19695 |
\field{description}=\marg{Anglo-Irish soldier and statesman}, |
| 19696 |
\field{user1}=\marg{1 May 1769 AD} |
| 19697 |
} |
| 19698 |
\end{codeenv} |
| 19699 |
Then the entries can be sorted by date of birth using: |
| 19700 |
\begin{codeenv} |
| 19701 |
\gls{GlsXtrLoadResources}\oarg{ |
| 19702 |
\csopt[entries]{src},\comment{data in entries.bib} |
| 19703 |
\csopt[user1]{sort-field}, |
| 19704 |
\csopt[date]{sort}, |
| 19705 |
\csopt[d MMM y G]{date-sort-format} |
| 19706 |
} |
| 19707 |
\end{codeenv} |
| 19708 |
|
| 19709 |
The \code{G} (era) date pattern specifier expects a string, such as |
| 19710 |
\qt{AD}. It will match \idx{lowercase} forms, such as \qt{ad}, so if you |
| 19711 |
have \code{\cs{textsc}\marg{ad}} the interpreter will convert this to |
| 19712 |
\code{ad} (stripping the text-block command). However, in general |
| 19713 |
it's best to supply a semantic command that ensures that the |
| 19714 |
interpreted result matches the required format. |
| 19715 |
|
| 19716 |
For example, if \csfmt{era} is provided with: |
| 19717 |
\begin{codeenv} |
| 19718 |
\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{era}}[1]\marg{\cs{textsc}\marg{\cs{MakeLowercase}\marg{\idx{param}1}}}}} |
| 19719 |
\end{codeenv} |
| 19720 |
If the definition is hidden from the interpreter |
| 19721 |
(\csopt[false]{interpret-preamble}) and the field |
| 19722 |
value contains \verb|\era{AD}| then the custom command will simply be stripped |
| 19723 |
leaving \code{AD} which can be matched by \code{G}. |
| 19724 |
|
| 19725 |
If the definition is picked up by the interpreter then the field |
| 19726 |
value will contain \code{ad} (from \ics{MakeLowercase}) but this can |
| 19727 |
be matched by \code{G}, so it isn't a problem. |
| 19728 |
However, if the definition of \csfmt{era} is changed so that the era label |
| 19729 |
supplied in the argument is converted to something that doesn't |
| 19730 |
match \code{G} then the definition should be hidden from the |
| 19731 |
interpreter. |
| 19732 |
|
| 19733 |
Here's a complete document that changes the \field{group} fields to use |
| 19734 |
the year and era: |
| 19735 |
\begin{codeenv} |
| 19736 |
\cmd{documentclass}\marg{article} |
| 19737 |
\strut |
| 19738 |
\cmd{usepackage}[\styopt{record},\styopt[indexgroup]{style}]\marg{glossaries-extra} |
| 19739 |
\strut |
| 19740 |
\cs{newcommand}\marg{\gls{bibglsdategroup}}[7]\marg{\idx{param}1\idx{param}4\idx{param}7} |
| 19741 |
\cs{newcommand}\marg{\gls{bibglsdategrouptitle}}[7]\marg{\ics{number}\idx{param}1\cs{cs.space}\idx{param}4} |
| 19742 |
\strut |
| 19743 |
\gls{GlsXtrLoadResources}\oarg{ |
| 19744 |
\csopt[entries]{src}, |
| 19745 |
\csopt[user1]{sort-field}, |
| 19746 |
\csopt[date]{sort}, |
| 19747 |
\csopt[d MMM y G]{date-sort-format}, |
| 19748 |
\csopt[all]{selection} |
| 19749 |
} |
| 19750 |
\strut |
| 19751 |
\cmd{begin}\marg{document} |
| 19752 |
\cs{printunsrtglossaries} |
| 19753 |
\cmd{end}\marg{document} |
| 19754 |
\end{codeenv} |
| 19755 |
(The use of \ics{number} strips the leading zero from the year.) |
| 19756 |
|
| 19757 |
\optsection{group-formation} |
| 19758 |
|
| 19759 |
If the \field{group} field hasn't been set in |
| 19760 |
the \ext{bib} file or through options like \csopt{group}, then it is |
| 19761 |
assigned according to this option's setting during sorting if |
| 19762 |
\longarg{group} has been used. Permitted values: |
| 19763 |
\begin{itemize} |
| 19764 |
\item\optfmt{default}: the group is assigned according to |
| 19765 |
the sort method's default group formation. This is the default |
| 19766 |
setting. |
| 19767 |
|
| 19768 |
\item\optfmt{codepoint}: the group is set to |
| 19769 |
\format{bibglsunicodegroup}, where the first argument is the first |
| 19770 |
significant character (converted to \idx{lowercase} and decomposed, |
| 19771 |
if applicable) of the sort value. |
| 19772 |
|
| 19773 |
\item\optfmt{unicode category}: the group is set to |
| 19774 |
\format{bibglsunicodegroup}, where the first argument is the label |
| 19775 |
identifying the Unicode category of the first significant character |
| 19776 |
of the sort value. For example, the label \code{Ll} signifies a |
| 19777 |
\idx!{lowercase} letter and \code{Lu} signifies an \idx!{uppercase} |
| 19778 |
letter. |
| 19779 |
|
| 19780 |
\item\optfmt{unicode script}: the group is set to |
| 19781 |
\format{bibglsunicodegroup}, where the first argument is the |
| 19782 |
label identifying the Unicode script of the first significant |
| 19783 |
character of the sort value. For example, the label \code{LATIN} |
| 19784 |
indicates Latin, \code{GREEK} indicates Greek and \code{COMMON} |
| 19785 |
indicates common characters (such as mathematical Greek characters |
| 19786 |
that are often used with non-Greek scripts). |
| 19787 |
|
| 19788 |
\item\optfmt{unicode category and script}: the group is set to |
| 19789 |
\format{bibglsunicodegroup}, where the first argument is the |
| 19790 |
label corresponding to the Unicode category and script of the first |
| 19791 |
significant character of the sort value. For example, the label |
| 19792 |
\code{Ll.LATIN} indicates a \idx!{lowercase} Latin letter. |
| 19793 |
\end{itemize} |
| 19794 |
This option has no effect with \longarg{no-group} or if no sorting |
| 19795 |
is applied. Use \csopt{secondary-group-formation} for secondary |
| 19796 |
sorting and \csopt{dual-group-formation} for dual entries. |
| 19797 |
|
| 19798 |
\begin{important} |
| 19799 |
Settings other than the default can cause the groups to become |
| 19800 |
fragmented, so care is needed if you use this option. |
| 19801 |
See also \sectionref{sec:logicaldivisions}. |
| 19802 |
\end{important} |
| 19803 |
|
| 19804 |
|
| 19805 |
\section{Secondary Glossary} |
| 19806 |
\label{sec:secondaryopts} |
| 19807 |
|
| 19808 |
The \gls{secondaryglossary} may only be used with \csopt[define]{action} |
| 19809 |
(within the same resource set) since it's incompatible with the copy actions. |
| 19810 |
You may use \csopt{secondary} in the first resource set and a copy |
| 19811 |
action in a subsequent resource set. |
| 19812 |
|
| 19813 |
\optsection{secondary} |
| 19814 |
|
| 19815 |
It may be that you want to display a glossary twice but with a |
| 19816 |
different order. For example, the first time alphabetically and the |
| 19817 |
second time by category. One way to do this is to have two |
| 19818 |
\gls{GlsXtrLoadResources} that both load the same \ext{bib} file with |
| 19819 |
different \csopt{label-prefix} and \csopt{sort} settings, but this |
| 19820 |
is only possible with \csopt[all]{selection} or by ensuring you |
| 19821 |
reference each entry with both label prefixes. Another method is |
| 19822 |
to use \csopt[copy]{action} but this requires a second resource |
| 19823 |
command with the same selection criteria. |
| 19824 |
|
| 19825 |
A simpler method is to use a single \gls{GlsXtrLoadResources} |
| 19826 |
with the \csopt{secondary} option. The value |
| 19827 |
(which must be supplied) should be in the format: |
| 19828 |
\begin{definition} |
| 19829 |
\meta{sort}:\meta{field}:\meta{type} |
| 19830 |
\end{definition} |
| 19831 |
or |
| 19832 |
\begin{definition} |
| 19833 |
\meta{sort}:\meta{type} |
| 19834 |
\end{definition} |
| 19835 |
If the \meta{field} is omitted, the value of \csopt{sort-field} is |
| 19836 |
used. Remember that when the \glspl{primaryentry} are sorted, the |
| 19837 |
\field{sort} field will be set, which means that the \field{sort} fallback field |
| 19838 |
(see \sectionref{sec:fallbacks}) won't be used in the |
| 19839 |
\glsdisp{secondaryglossary}{secondary} sort. In |
| 19840 |
general it's best to supply the field unless one type is sorted and the |
| 19841 |
other isn't. (The actual sort value obtained by the |
| 19842 |
\glsdisp{secondaryglossary}{secondary} sort |
| 19843 |
will be saved in the \field{secondarysort} field in case you require it.) |
| 19844 |
|
| 19845 |
The value of \meta{sort} is as for \csopt{sort}, but note |
| 19846 |
that in this case the sort value \optfmt{unsrt} or \optfmt{none} |
| 19847 |
means to use the same ordering as the \glspl{primaryentry}. For |
| 19848 |
example, with \csopt[de-CH-1996]{sort}, |
| 19849 |
\csopt[none:copies]{secondary} the \code{copies} list will be |
| 19850 |
ordered according to \code{de-CH-1996} and not according to the |
| 19851 |
order in which they were read when the \ext{bib} file or files were |
| 19852 |
parsed. If \meta{sort} is \optfmt{custom}, then the rule should be |
| 19853 |
provided with \csopt{secondary-sort-rule}. |
| 19854 |
|
| 19855 |
This option will copy all the selected entries into the glossary labelled |
| 19856 |
\meta{type} sorted according to \meta{sort} (using \meta{field} as |
| 19857 |
the sort value). Note that this \emph{just copies the entry's label} |
| 19858 |
to the \gls{secondaryglossary} list rather than creating a duplicate entry, |
| 19859 |
which saves resources but it means that all the fields will be |
| 19860 |
identical. If you want groups in your glossary, the group |
| 19861 |
information for the \glspl{secondaryglossary} will be stored in the |
| 19862 |
internal \field{secondarygroup} field. The \field{group} field will |
| 19863 |
contain the group for the \gls{primaryglossary}. |
| 19864 |
|
| 19865 |
In order to switch fields in \ics{printunsrtglossary}, you need at |
| 19866 |
least v1.21 of \sty{glossaries-extra} which provides |
| 19867 |
\ics{glsxtrgroupfield} to keep track of the appropriate field label. |
| 19868 |
If this command is defined, the preamble for the \gls{secondaryglossary} |
| 19869 |
will be adjusted to locally change the field to |
| 19870 |
\field{secondarygroup}. With older versions, the group information |
| 19871 |
in the \gls{secondaryglossary} will be the same as for the |
| 19872 |
\gls{primaryglossary}. |
| 19873 |
|
| 19874 |
If the glossary \meta{type} doesn't exist, it will be |
| 19875 |
defined with \ics{provideignoredglossary*}\margm{type} |
| 19876 |
even if \longarg{no-provide-glossaries} is set. |
| 19877 |
Note that if the glossary already exists and contains entries, |
| 19878 |
the existing entries aren't re-ordered. The new entries are |
| 19879 |
simply appended to the list. |
| 19880 |
|
| 19881 |
For example, suppose the \ext{bib} file contains entries like: |
| 19882 |
\begin{codeenv} |
| 19883 |
\atentry{entry}\marg{quartz, |
| 19884 |
\field{name}=\marg{quartz}, |
| 19885 |
\field{description}=\marg{hard mineral consisting of silica}, |
| 19886 |
\field{category}=\marg{mineral} |
| 19887 |
} |
| 19888 |
\strut |
| 19889 |
\atentry{entry}\marg{cabbage, |
| 19890 |
\field{name}=\marg{cabbage}, |
| 19891 |
\field{description}=\marg{vegetable with thick green or purple leaves}, |
| 19892 |
\field{category}=\marg{vegetable} |
| 19893 |
} |
| 19894 |
\strut |
| 19895 |
\atentry{entry}\marg{waterfowl, |
| 19896 |
\field{name}=\marg{waterfowl}, |
| 19897 |
\field{description}=\marg{any bird that lives in or about water}, |
| 19898 |
\field{category}=\marg{animal} |
| 19899 |
} |
| 19900 |
\end{codeenv} |
| 19901 |
and the document preamble contains: |
| 19902 |
\begin{codeenv} |
| 19903 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[en-GB]{sort}, |
| 19904 |
\csopt[en-GB:category:topic]{secondary} |
| 19905 |
} |
| 19906 |
\end{codeenv} |
| 19907 |
This sorts the \glspl{primaryentry} according to the default |
| 19908 |
\csopt{sort-field} and then sorts the entries according |
| 19909 |
to the \field{category} field and copies this list to |
| 19910 |
the \code{topic} glossary (which will be provided if not defined.) |
| 19911 |
|
| 19912 |
The \glsdisp{secondaryglossary}{secondary list} can be displayed |
| 19913 |
with the hypertargets switched off to prevent duplicates. The |
| 19914 |
cross-references will link to the \glsdisp{primaryglossary}{original glossary}. |
| 19915 |
|
| 19916 |
For example: |
| 19917 |
\begin{codeenv*} |
| 19918 |
\ics{printunsrtglossary}\oarg{\printglossopt[Summary (alphabetical)]{title}} |
| 19919 |
\ics{printunsrtglossary}\oarg{\printglossopt[Summary (by topic)]{title},\printglossopt[false]{target}} |
| 19920 |
\end{codeenv*} |
| 19921 |
|
| 19922 |
The alternative (or if more than two lists are required) is to |
| 19923 |
reload the same \ext{bib} file with different label prefixes. |
| 19924 |
For example, if the entries are stored in \filefmt{entries.bib}: |
| 19925 |
\begin{codeenv} |
| 19926 |
\cs{newglossary*}\marg{nosort}\marg{Symbols (Unsorted)} |
| 19927 |
\cs{newglossary*}\marg{byname}\marg{Symbols (Letter Order)} |
| 19928 |
\cs{newglossary*}\marg{bydesc}\marg{Symbols (Ordered by Description)} |
| 19929 |
\cs{newglossary*}\marg{byid}\marg{Symbols (Ordered by Label)} |
| 19930 |
\strut |
| 19931 |
\gls{GlsXtrLoadResources}\oarg{ |
| 19932 |
\csopt[entries]{src},\comment{entries.bib} |
| 19933 |
\csopt[unsrt]{sort}, |
| 19934 |
\csopt[nosort]{type} |
| 19935 |
} |
| 19936 |
\strut |
| 19937 |
\gls{GlsXtrLoadResources}\oarg{ |
| 19938 |
\csopt[entries]{src},\comment{entries.bib} |
| 19939 |
\csopt[letter-case]{sort}, |
| 19940 |
\csopt[byname]{type}, |
| 19941 |
\csopt[byname.]{label-prefix} |
| 19942 |
} |
| 19943 |
\strut |
| 19944 |
\gls{GlsXtrLoadResources}\oarg{ |
| 19945 |
\csopt[entries]{src},\comment{entries.bib} |
| 19946 |
\csopt[locale]{sort}, |
| 19947 |
\csopt[description]{sort-field}, |
| 19948 |
\csopt[bydesc]{type}, |
| 19949 |
\csopt[bydesc.]{label-prefix} |
| 19950 |
} |
| 19951 |
\strut |
| 19952 |
\gls{GlsXtrLoadResources}\oarg{ |
| 19953 |
\csopt[entries]{src},\comment{entries.bib} |
| 19954 |
\csopt[letter]{sort}, |
| 19955 |
\csopt[id]{sort-field}, |
| 19956 |
\csopt[byid]{type}, |
| 19957 |
\csopt[byid.]{label-prefix} |
| 19958 |
} |
| 19959 |
\end{codeenv} |
| 19960 |
|
| 19961 |
\optsection{secondary-match} |
| 19962 |
|
| 19963 |
Similar to \csopt{match} but determines whether or not to include a |
| 19964 |
\gls{primaryentry} in the \glsdisp{secondaryglossary}{secondary |
| 19965 |
list}. The syntax is the same but this option is governed by |
| 19966 |
\csopt{secondary-match-op} and \csopt{secondary-match-action}. Note |
| 19967 |
that if an entry hasn't been selected for the |
| 19968 |
\glsdisp{primaryglossary}{primary list} then it won't be added to |
| 19969 |
the \glsdisp{secondaryglossary}{secondary list}, regardless of this |
| 19970 |
setting. |
| 19971 |
|
| 19972 |
\optsection{secondary-not-match} |
| 19973 |
|
| 19974 |
Similar to \csopt{not-match} but determines whether or not to |
| 19975 |
include a \gls{primaryentry} in the |
| 19976 |
\glsdisp{secondaryglossary}{secondary list}. The syntax is the same |
| 19977 |
but this option is governed by \csopt{secondary-match-op} and |
| 19978 |
\csopt{secondary-match-action}. Note that if an entry hasn't been |
| 19979 |
selected for the \glsdisp{primaryglossary}{primary list} then it |
| 19980 |
won't be added to the \glsdisp{secondaryglossary}{secondary list}, |
| 19981 |
regardless of this setting. |
| 19982 |
|
| 19983 |
\optsection{secondary-match-op} |
| 19984 |
|
| 19985 |
As \csopt{match-op} but for the \glsdisp{secondaryglossary}{secondary list} selection. |
| 19986 |
|
| 19987 |
\optsection{secondary-match-action} |
| 19988 |
|
| 19989 |
As \csopt{match-action} but for the \glsdisp{secondaryglossary}{secondary list} selection. |
| 19990 |
|
| 19991 |
\optsection{secondary-missing-sort-fallback} |
| 19992 |
|
| 19993 |
As \csopt{missing-sort-fallback} but for |
| 19994 |
\glsdisp{secondaryglossary}{secondary} sorting. |
| 19995 |
|
| 19996 |
\optsection{secondary-trim-sort} |
| 19997 |
|
| 19998 |
As \csopt{trim-sort} but for \glsdisp{secondaryglossary}{secondary} sorting. |
| 19999 |
|
| 20000 |
\optsection{secondary-sort-replace} |
| 20001 |
|
| 20002 |
As \csopt{sort-replace} but for \glsdisp{secondaryglossary}{secondary} sorting. |
| 20003 |
|
| 20004 |
\optsection{secondary-sort-rule} |
| 20005 |
|
| 20006 |
As \csopt{sort-rule} but for \glsdisp{secondaryglossary}{secondary} custom sorting. |
| 20007 |
|
| 20008 |
\optsection{secondary-break-at} |
| 20009 |
|
| 20010 |
As \csopt{break-at} but for \glsdisp{secondaryglossary}{secondary} entries. |
| 20011 |
|
| 20012 |
\optsection{secondary-break-marker} |
| 20013 |
|
| 20014 |
As \csopt{break-marker} but for \glsdisp{secondaryglossary}{secondary} entries. |
| 20015 |
|
| 20016 |
\optsection{secondary-break-at-match} |
| 20017 |
|
| 20018 |
As \csopt{break-at-match} but for \glsdisp{secondaryglossary}{secondary} entries. |
| 20019 |
|
| 20020 |
\optsection{secondary-break-at-match-op} |
| 20021 |
|
| 20022 |
As \csopt{break-at-match-op} but for \glsdisp{secondaryglossary}{secondary} entries. |
| 20023 |
|
| 20024 |
\optsection{secondary-break-at-not-match} |
| 20025 |
|
| 20026 |
As \csopt{break-at-not-match} but for \glsdisp{secondaryglossary}{secondary} entries. |
| 20027 |
|
| 20028 |
\optsection{secondary-sort-number-pad} |
| 20029 |
|
| 20030 |
As \csopt{sort-number-pad} but for \glsdisp{secondaryglossary}{secondary} entries. |
| 20031 |
|
| 20032 |
\optsection{secondary-sort-pad-plus} |
| 20033 |
|
| 20034 |
As \csopt{sort-pad-plus} but for \glsdisp{secondaryglossary}{secondary} entries. |
| 20035 |
|
| 20036 |
\optsection{secondary-sort-pad-minus} |
| 20037 |
|
| 20038 |
As \csopt{sort-pad-minus} but for \glsdisp{secondaryglossary}{secondary} entries. |
| 20039 |
|
| 20040 |
\optsection{secondary-identical-sort-action} |
| 20041 |
|
| 20042 |
As \csopt{identical-sort-action} but for \glsdisp{secondaryglossary}{secondary} entries. |
| 20043 |
|
| 20044 |
\optsection{secondary-sort-suffix} |
| 20045 |
|
| 20046 |
As \csopt{sort-suffix} but for \glsdisp{secondaryglossary}{secondary} entries. |
| 20047 |
|
| 20048 |
\optsection{secondary-sort-suffix-marker} |
| 20049 |
|
| 20050 |
As \csopt{sort-suffix-marker} but for \glsdisp{secondaryglossary}{secondary} entries. |
| 20051 |
|
| 20052 |
\optsection{secondary-strength} |
| 20053 |
|
| 20054 |
As \csopt{strength} but for \glsdisp{secondaryglossary}{secondary} entries. |
| 20055 |
|
| 20056 |
\optsection{secondary-decomposition} |
| 20057 |
|
| 20058 |
As \csopt{decomposition} but for \glsdisp{secondaryglossary}{secondary} entries. |
| 20059 |
|
| 20060 |
\optsection{secondary-letter-number-rule} |
| 20061 |
|
| 20062 |
As \csopt{letter-number-rule} but for \glsdisp{secondaryglossary}{secondary} letter-number sorting. |
| 20063 |
|
| 20064 |
\optsection{secondary-letter-number-punc-rule} |
| 20065 |
|
| 20066 |
As \csopt{letter-number-punc-rule} but for \glsdisp{secondaryglossary}{secondary} letter-number sorting. |
| 20067 |
|
| 20068 |
\optsection{secondary-numeric-sort-pattern} |
| 20069 |
|
| 20070 |
As \csopt{numeric-sort-pattern} but for \glsdisp{secondaryglossary}{secondary} |
| 20071 |
locale-sensitive numeric sorting. |
| 20072 |
|
| 20073 |
\optsection{secondary-numeric-locale} |
| 20074 |
|
| 20075 |
As \csopt{numeric-locale} but for \glsdisp{secondaryglossary}{secondary} |
| 20076 |
locale-sensitive numeric sorting. |
| 20077 |
|
| 20078 |
\optsection{secondary-date-sort-locale} |
| 20079 |
|
| 20080 |
As \csopt{date-sort-locale} but for \glsdisp{secondaryglossary}{secondary} date-time sorting. |
| 20081 |
|
| 20082 |
\optsection{secondary-date-sort-format} |
| 20083 |
|
| 20084 |
As \csopt{date-sort-format} but for \glsdisp{secondaryglossary}{secondary} date-time sorting. |
| 20085 |
|
| 20086 |
\optsection{secondary-group-formation} |
| 20087 |
|
| 20088 |
As \csopt{group-formation} but for \glsdisp{secondaryglossary}{secondary} sorting. |
| 20089 |
|
| 20090 |
\section{Dual Entries} |
| 20091 |
\label{sec:dualopts} |
| 20092 |
|
| 20093 |
\subsection{General Dual Settings} |
| 20094 |
\label{sec:dualoptsgeneral} |
| 20095 |
|
| 20096 |
\optsection[\subsubsection]{dual-prefix} |
| 20097 |
|
| 20098 |
This option indicates the prefix to use for the \glspl{dualentry}. The |
| 20099 |
default value is \idprefix{dual} (including the terminating period). |
| 20100 |
Any references to dual entries within the \ext{bib} file should use |
| 20101 |
the prefix \idprefix{dual} which will be replaced by \meta{value} |
| 20102 |
when the \ext{bib} file is parsed. |
| 20103 |
|
| 20104 |
As from version 1.8, the dual label prefix is identified |
| 20105 |
in the \ext{glstex} file with: |
| 20106 |
\begin{codeenv} |
| 20107 |
\format{bibglsdualprefixlabel} |
| 20108 |
\end{codeenv} |
| 20109 |
|
| 20110 |
\optsection[\subsubsection]{primary-dual-dependency} |
| 20111 |
|
| 20112 |
This is a boolean setting that determines whether or not \primary\ and |
| 20113 |
\dual\ entries should be considered mutual dependencies. The default value is |
| 20114 |
\csopt[true]{primary-dual-dependency}, which means that if a |
| 20115 |
\primary\ has records then the \dual\ is added as a dependency and vice versa. |
| 20116 |
The setting \csopt[false]{primary-dual-dependency} can't be used |
| 20117 |
with \csopt[none]{dual-sort} or \csopt[use]{dual-sort} (but may be |
| 20118 |
used with \csopt[combine]{dual-sort} and \csopt[none]{sort} or |
| 20119 |
\csopt[use]{sort}). |
| 20120 |
|
| 20121 |
\optsection[\subsubsection]{combine-dual-locations} |
| 20122 |
|
| 20123 |
This setting allows the \glspl{locationlist} for each \gls{primaryentry} |
| 20124 |
to be merged with that of the corresponding \gls{dualentry}. |
| 20125 |
The \meta{value} may be one of: |
| 20126 |
\begin{itemize} |
| 20127 |
\item\optfmt{false} This is the default setting. The |
| 20128 |
\glspl{locationlist} aren't combined. |
| 20129 |
|
| 20130 |
\item\optfmt{both} Both the \primary\ and \dual\ are given the combined |
| 20131 |
\gls{locationlist}. |
| 20132 |
|
| 20133 |
\item\optfmt{dual} Only the \dual\ is given the combined |
| 20134 |
\gls{locationlist}. The \glsdisp{primaryentry}{primary's} location list is emptied. |
| 20135 |
|
| 20136 |
\item\optfmt{primary} Only the \primary\ is given the combined |
| 20137 |
\gls{locationlist}. The \glsdisp{dualentry}{dual's} |
| 20138 |
\gls{locationlist} is emptied. |
| 20139 |
|
| 20140 |
\item\optfmt{dual retain principal} Like \optfmt{dual} but any |
| 20141 |
\glspl{principallocation} for \glspl{primaryentry} will have a copy left in the |
| 20142 |
\gls{primaryentry}['s] \igls{locationlist}. |
| 20143 |
\item\optfmt{primary retain principal} Like \optfmt{primary} but any |
| 20144 |
\glspl{principallocation} for \glspl{dualentry} will have a copy left in the |
| 20145 |
\gls{dualentry}['s] \igls{locationlist}. |
| 20146 |
\end{itemize} |
| 20147 |
|
| 20148 |
For example, suppose the file \filefmt{entries.bib} contains: |
| 20149 |
\begin{codeenv} |
| 20150 |
\atentry{dualindexentry}\marg{array, |
| 20151 |
\field{description}=\marg{ordered list of values} |
| 20152 |
} |
| 20153 |
\strut |
| 20154 |
\atentry{dualindexentry}\marg{vector, |
| 20155 |
\field{name}=\marg{vector}, |
| 20156 |
\field{description}=\marg{column or row of values} |
| 20157 |
} |
| 20158 |
\strut |
| 20159 |
\atentry{dualindexentry}\marg{set, |
| 20160 |
\field{description}=\marg{collection of values} |
| 20161 |
} |
| 20162 |
\strut |
| 20163 |
\atentry{dualindexentry}\marg{matrix, |
| 20164 |
\field{plural}=\marg{matrices}, |
| 20165 |
\field{description}=\marg{rectangular array of values} |
| 20166 |
} |
| 20167 |
\end{codeenv} |
| 20168 |
and the document contains: |
| 20169 |
\begin{codeenv} |
| 20170 |
\cmd{documentclass}\marg{article} |
| 20171 |
\strut |
| 20172 |
\cmd{usepackage}[colorlinks]\marg{hyperref} |
| 20173 |
\cmd{usepackage}[\styopt{record},\styopt{index},\styopt[indexgroup]{style}]\marg{glossaries-extra} |
| 20174 |
\strut |
| 20175 |
\gls{GlsXtrLoadResources}\oarg{ |
| 20176 |
\csopt[entries]{src}, |
| 20177 |
\csopt[index]{type}, |
| 20178 |
\csopt[idx.]{label-prefix}, |
| 20179 |
\csopt[gls.]{dual-prefix}, |
| 20180 |
\csopt[main]{dual-type} |
| 20181 |
} |
| 20182 |
\strut |
| 20183 |
\cmd{begin}\marg{document} |
| 20184 |
\cs{gls}\marg{gls.array}, \cs{gls}\marg{gls.vector}, \cs{gls}\marg{gls.set}, \cs{gls}\marg{gls.matrix}. |
| 20185 |
\strut |
| 20186 |
\cmd{newpage} |
| 20187 |
\cs{gls}\marg{gls.array}, \cs{gls}\marg{idx.vector}, \cs{gls}\marg{idx.set}, \cs{gls}\marg{gls.matrix}. |
| 20188 |
\strut |
| 20189 |
\cmd{newpage} |
| 20190 |
\cs{gls}\marg{gls.array}, \cs{gls}\marg{gls.vector}, \cs{gls}\marg{gls.set}, \cs{gls}\marg{gls.matrix}. |
| 20191 |
\strut |
| 20192 |
\cs{printunsrtglossaries} |
| 20193 |
\cmd{end}\marg{document} |
| 20194 |
\end{codeenv} |
| 20195 |
In this case, the \glspl{primaryentry} are placed in the \code{index} |
| 20196 |
glossary type and are assigned the prefix \idprefixfmt{idx} but only |
| 20197 |
two of the \glspl{primaryentry} have been used in the document (both on |
| 20198 |
page~2). |
| 20199 |
|
| 20200 |
The \glspl{dualentry} are assigned the prefix \idprefixfmt{gls} and are |
| 20201 |
placed in the \mainglossary. The \code{gls.array} |
| 20202 |
and \code{gls.matrix} entries have been indexed on pages~1, 2 and~3. |
| 20203 |
The \code{gls.vector} and \code{gls.set} entries have been indexed |
| 20204 |
on pages~1 and~3. |
| 20205 |
|
| 20206 |
With the default setting, some of the \glspl{location} are in the |
| 20207 |
\mainglossary\ (corresponding to \code{\cs{gls}\marg{gls.array}}, |
| 20208 |
\code{\cs{gls}\marg{gls.vector}}, \code{\cs{gls}\marg{gls.set}} and |
| 20209 |
\code{\cs{gls}\marg{gls.matrix}}) and some of the \glspl{location} are in the |
| 20210 |
\code{index} glossary (corresponding to \code{\cs{gls}\marg{idx.vector}} |
| 20211 |
and \code{\cs{gls}\marg{idx.set}}). |
| 20212 |
|
| 20213 |
If the option \csopt[primary]{combine-dual-locations} is added to |
| 20214 |
the resource set, then all the \glspl{location} are moved to the |
| 20215 |
\code{index} glossary. The entries in the \mainglossary\ no longer |
| 20216 |
have \glspl{location}. This is actually preferable for this type of |
| 20217 |
document and it's best not to reference the \primary\ (index) |
| 20218 |
entries as the hyperlink created by \ics{gls} will point to the |
| 20219 |
index, but these entries don't have descriptions, so it's less |
| 20220 |
useful than referencing the \dual\ (\code{main}) entries as then the |
| 20221 |
hyperlink can point to the definition in the \mainglossary. |
| 20222 |
|
| 20223 |
|
| 20224 |
\subsection{Dual Fields} |
| 20225 |
\label{sec:dualoptsfields} |
| 20226 |
|
| 20227 |
\optsection[\subsubsection]{dual-type} |
| 20228 |
|
| 20229 |
This option sets the \field{type} field for all \glspl{dualentry}. |
| 20230 |
(The \glspl{primaryentry} obey the \csopt{type} option.) This |
| 20231 |
will override any value of \field{type} provided in the \ext{bib} |
| 20232 |
file (or created through a mapping). The \meta{value} is required and |
| 20233 |
should be one of: |
| 20234 |
\begin{itemize} |
| 20235 |
\item \optfmt{false}: switches off this setting (default); |
| 20236 |
|
| 20237 |
\item \optfmt{same as entry}: sets the \field{type} to the |
| 20238 |
\gls{entrytype} (\idx!{lowercase} and without |
| 20239 |
the initial \code{@}). For example, if the entry was defined with |
| 20240 |
\atentry{dualentry}, the \field{type} will be set to |
| 20241 |
\optfmt{dualentry}. |
| 20242 |
If you've used \csopt{entry-type-aliases}, this refers to the target |
| 20243 |
\gls{entrytype} not the original \gls{entrytype} provided in the \ext{bib} |
| 20244 |
file. |
| 20245 |
|
| 20246 |
\item \optfmt{same as original entry}: set the \field{type} field |
| 20247 |
to the original \gls{entrytype} (\idx!{lowercase} and without |
| 20248 |
the initial \code{@}) before it was aliased (behaves like |
| 20249 |
\optfmt{same as entry} if the \gls{entrytype} wasn't aliased). |
| 20250 |
|
| 20251 |
\item \optfmt{same as base}: sets the \field{type} to the base name |
| 20252 |
of the \ext{bib} file (without the extension) that provided the |
| 20253 |
entry definition (new to v1.1); |
| 20254 |
|
| 20255 |
\item \optfmt{same as primary}: sets the \field{type} to the same as |
| 20256 |
the corresponding \gls{primaryentry}['s] \field{type} (which may have been |
| 20257 |
set with \csopt{type}). If the \gls{primaryentry} doesn't have the |
| 20258 |
\field{type} field set, the \glsdisp{dualentry}{dual's} \field{type} will remain |
| 20259 |
unchanged. |
| 20260 |
|
| 20261 |
\item \optfmt{same as parent}: sets the \field{type} to the same as |
| 20262 |
the entry's \parent\ (new to v1.9). If the entry doesn't have a |
| 20263 |
\parent\ or if the \parent\ doesn't have the \field{type} field set, |
| 20264 |
then no change is made. |
| 20265 |
|
| 20266 |
\item \optfmt{same as category} set the \field{type} field |
| 20267 |
to the same value as the \field{category} field |
| 20268 |
(\field{type} unchanged if \field{category} not set); |
| 20269 |
|
| 20270 |
\item \meta{label}: sets the \field{type} field to \meta{label}. |
| 20271 |
\end{itemize} |
| 20272 |
|
| 20273 |
Remember that the glossary with that label must have already |
| 20274 |
been defined (see \sectionref{sec:newglossary}). |
| 20275 |
For example: |
| 20276 |
\begin{codeenv} |
| 20277 |
\cs{newglossary*}\marg{english}\marg{English} |
| 20278 |
\cs{newglossary*}\marg{french}\marg{French} |
| 20279 |
\strut |
| 20280 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[en]{sort},\csopt[fr]{dual-sort}, |
| 20281 |
\csopt[english]{type}, |
| 20282 |
\csopt[french]{dual-type}} |
| 20283 |
\end{codeenv} |
| 20284 |
Alternatively: |
| 20285 |
\begin{codeenv} |
| 20286 |
\cs{newglossary*}\marg{dictionary}\marg{Dictionary} |
| 20287 |
\strut |
| 20288 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[en]{sort},\csopt[fr]{dual-sort}, |
| 20289 |
\csopt[dictionary]{type}, |
| 20290 |
\csopt[same as primary]{dual-type}} |
| 20291 |
\end{codeenv} |
| 20292 |
|
| 20293 |
\optsection[\subsubsection]{dual-category} |
| 20294 |
|
| 20295 |
This option sets the \field{category} field for all |
| 20296 |
\glspl{dualentry}. (The \glspl{primaryentry} obey the \csopt{category} option.) This |
| 20297 |
will override any value of \field{category} provided in the \ext{bib} |
| 20298 |
file (or created through a mapping). The \meta{value} may be empty or |
| 20299 |
one of: |
| 20300 |
\begin{itemize} |
| 20301 |
\item \optfmt{false}: switch off this setting (default); |
| 20302 |
\item \optfmt{same as entry}: sets the \field{category} to the |
| 20303 |
\gls{entrytype} (\idx{lowercase} and without |
| 20304 |
the initial \code{@}). For example, if the entry was defined with |
| 20305 |
\atentry{dualentry}, the \field{category} will be set to |
| 20306 |
\optfmt{dualentry}. |
| 20307 |
If you've used \csopt{entry-type-aliases}, this refers to the target |
| 20308 |
\gls{entrytype} not the original \gls{entrytype} provided in the \ext{bib} |
| 20309 |
file. |
| 20310 |
|
| 20311 |
\item \optfmt{same as original entry}: set the \field{category} field |
| 20312 |
to the original \gls{entrytype} (\idx{lowercase} and without |
| 20313 |
the initial \code{@}) before it was aliased (behaves like |
| 20314 |
\optfmt{same as entry} if the \gls{entrytype} wasn't aliased). |
| 20315 |
|
| 20316 |
\item \optfmt{same as base}: sets the \field{category} to the base |
| 20317 |
name of the \ext{bib} file (without the extension) that provided the |
| 20318 |
entry definition (new to v1.1); |
| 20319 |
|
| 20320 |
\item \optfmt{same as primary}: sets the \field{category} to the |
| 20321 |
same as the corresponding \gls{primaryentry}['s] \field{category} (which |
| 20322 |
may have been set with \csopt{category}). If the \gls{primaryentry} |
| 20323 |
doesn't have the \field{category} field set, the \glsdisp{dualentry}{dual's} |
| 20324 |
\field{category} will remain unchanged. |
| 20325 |
|
| 20326 |
\item \optfmt{same as type}: sets the \field{category} to the same |
| 20327 |
as the value of the entry's \field{type} field (which may have been |
| 20328 |
set with \csopt{dual-type}). If the entry doesn't have the |
| 20329 |
\field{type} field set, the \field{category} will remain unchanged. |
| 20330 |
|
| 20331 |
\item \meta{label}: sets the \field{category} field to \meta{label}. |
| 20332 |
\end{itemize} |
| 20333 |
|
| 20334 |
\optsection[\subsubsection]{dual-counter} |
| 20335 |
|
| 20336 |
As \csopt{counter} but for the \glspl{dualentry}. In this case |
| 20337 |
\meta{value} may be the name of the counter or |
| 20338 |
\optfmt{same as primary} which uses the counter for the |
| 20339 |
\gls{primaryentry} or \optfmt{false} to switch off this setting. |
| 20340 |
|
| 20341 |
\optsection[\subsubsection]{dual-short-case-change} |
| 20342 |
|
| 20343 |
As \csopt{short-case-change} but applies to the \field{dualshort} |
| 20344 |
field instead. |
| 20345 |
|
| 20346 |
\optsection[\subsubsection]{dual-long-case-change} |
| 20347 |
|
| 20348 |
As \csopt{long-case-change} but applies to the \field{duallong} |
| 20349 |
field instead. |
| 20350 |
|
| 20351 |
\optsection[\subsubsection]{dual-field} |
| 20352 |
|
| 20353 |
If this option is used, this will add \ics{glsxtrprovidestoragekey} |
| 20354 |
to the start of the \iext{glstex} file providing the key given by |
| 20355 |
\meta{value}. Any entries defined using a dual \gls{entrytype}, such as |
| 20356 |
\atentry{dualentry}, will be written to the \ext{glstex} file with |
| 20357 |
an extra field called \meta{value} that is set to the mirror entry. |
| 20358 |
If \meta{value} is omitted \csopt[dual]{dual-field} is assumed. If |
| 20359 |
you use a different value, you will need to redefine |
| 20360 |
\gls{GlsXtrDualField} (either locally or globally). |
| 20361 |
A value of \code{false} will switch off this setting (the default). |
| 20362 |
|
| 20363 |
For example, if the \ext{bib} file contains: |
| 20364 |
\begin{codeenv} |
| 20365 |
\atentry{dualentry}\marg{child, |
| 20366 |
\field{name}=\marg{child}, |
| 20367 |
\field{plural}=\marg{children}, |
| 20368 |
\field{description}=\marg{enfant} |
| 20369 |
} |
| 20370 |
\end{codeenv} |
| 20371 |
Then with \csopt[dual]{dual-field} (or simply \csopt{dual-field} |
| 20372 |
without a value) this will first add the line: |
| 20373 |
\begin{codeenv} |
| 20374 |
\cs{glsxtrprovidestoragekey}\marg{\field{dual}}\marg{}\marg{} |
| 20375 |
\end{codeenv} |
| 20376 |
at the start of the file and will include the line: |
| 20377 |
\begin{codeenv*} |
| 20378 |
\field{dual}=\marg{dual.child}, |
| 20379 |
\end{codeenv*} |
| 20380 |
for the \gls{primaryentry} (\code{child}) and the line: |
| 20381 |
\begin{codeenv} |
| 20382 |
\field{dual}=\marg{child}, |
| 20383 |
\end{codeenv} |
| 20384 |
for the \gls{dualentry} (\code{dual.child}). It's then possible to |
| 20385 |
reference one entry from the other. For example, the post-description |
| 20386 |
hook could contain: |
| 20387 |
\begin{codeenv} |
| 20388 |
\cs{ifglshasfield}\marg{\field{dual}}\marg{\cs{glscurrententrylabel}} |
| 20389 |
\marg{\comment{} |
| 20390 |
\cs{space} |
| 20391 |
(\cs{glshyperlink}\marg{\cs{glscurrentfieldvalue}})\comment{} |
| 20392 |
}\comment{} |
| 20393 |
\marg{}\comment{} |
| 20394 |
\end{codeenv} |
| 20395 |
Note that this new field won't be available for use within the |
| 20396 |
\iext{bib} file (unless it was previously defined in the document |
| 20397 |
before \gls!{GlsXtrLoadResources}). |
| 20398 |
|
| 20399 |
\optsection[\subsubsection]{dual-date-time-field-format} |
| 20400 |
|
| 20401 |
As \csopt{date-time-field-format} but is used for \glspl{dualentry}. |
| 20402 |
|
| 20403 |
\optsection[\subsubsection]{dual-date-field-format} |
| 20404 |
|
| 20405 |
As \csopt{date-field-format} but is used for \glspl{dualentry}. |
| 20406 |
|
| 20407 |
\optsection[\subsubsection]{dual-time-field-format} |
| 20408 |
|
| 20409 |
As \csopt{time-field-format} but is used for \glspl{dualentry}. |
| 20410 |
|
| 20411 |
\optsection[\subsubsection]{dual-date-time-field-locale} |
| 20412 |
|
| 20413 |
As \csopt{date-time-field-locale} but is used for \glspl{dualentry}. |
| 20414 |
|
| 20415 |
\optsection[\subsubsection]{dual-date-field-locale} |
| 20416 |
|
| 20417 |
As \csopt{date-field-locale} but is used for \glspl{dualentry}. |
| 20418 |
|
| 20419 |
\optsection[\subsubsection]{dual-time-field-locale} |
| 20420 |
|
| 20421 |
As \csopt{time-field-locale} but is used for \glspl{dualentry}. |
| 20422 |
|
| 20423 |
\subsection{Dual Sorting} |
| 20424 |
\label{sec:dualoptssort} |
| 20425 |
|
| 20426 |
\optsection[\subsubsection]{dual-sort} |
| 20427 |
|
| 20428 |
This option indicates how to sort the \glspl{dualentry}. |
| 20429 |
The \glspl{primaryentry} are sorted with the normal entries according to |
| 20430 |
\csopt{sort}, and the \glspl{dualentry} are sorted according to |
| 20431 |
\csopt{dual-sort} unless \csopt[combine]{dual-sort} in which case the |
| 20432 |
\glspl{dualentry} will be combined with the \glspl{primaryentry} and all the |
| 20433 |
entries will be sorted together according to the \csopt{sort} option. |
| 20434 |
|
| 20435 |
If \meta{value} isn't set to \optfmt{combine} then the |
| 20436 |
\glspl{dualentry} are sorted separately according to \meta{value} (as per |
| 20437 |
\csopt{sort}) and the \glspl{dualentry} will be appended at the end of |
| 20438 |
the \iext{glstex} file. The field used by the comparator is given by |
| 20439 |
\csopt{dual-sort-field}. |
| 20440 |
If \csopt[custom]{dual-sort}, then the \glspl{dualentry} are sorted according to the |
| 20441 |
rule provided by \csopt{dual-sort-rule}. |
| 20442 |
|
| 20443 |
For example: |
| 20444 |
\begin{codeenv} |
| 20445 |
\gls{GlsXtrLoadResources}\oarg{ |
| 20446 |
\csopt[entries-dual]{src}, |
| 20447 |
\csopt[en]{sort}, |
| 20448 |
\csopt[de-CH-1996]{dual-sort} |
| 20449 |
} |
| 20450 |
\end{codeenv} |
| 20451 |
This will sort the \glspl{primaryentry} according to \optfmt{en} |
| 20452 |
(English) and the \glspl{secondaryentry} according to \optfmt{de-CH-1996} |
| 20453 |
(Swiss German new orthography) whereas: |
| 20454 |
\begin{codeenv} |
| 20455 |
\gls{GlsXtrLoadResources}\oarg{ |
| 20456 |
\csopt[entries-dual]{src}, |
| 20457 |
\csopt[en-GB]{sort}, |
| 20458 |
\csopt[combine]{dual-sort} |
| 20459 |
} |
| 20460 |
\end{codeenv} |
| 20461 |
will combine the dual entries with the \glspl{primaryentry} and sort them |
| 20462 |
all according to the \optfmt{en-GB} locale (British English). |
| 20463 |
|
| 20464 |
If not set, \csopt{dual-sort} defaults to \optfmt{combine}. If |
| 20465 |
\meta{value} is omitted, \optfmt{resource} is assumed. |
| 20466 |
|
| 20467 |
\optsection[\subsubsection]{dual-sort-field} |
| 20468 |
|
| 20469 |
This option indicates the field to use when sorting dual entries |
| 20470 |
(when they haven't been combined with the \glspl{primaryentry}). The |
| 20471 |
default value is the same as the \csopt{sort-field} value. |
| 20472 |
|
| 20473 |
\optsection[\subsubsection]{dual-missing-sort-fallback} |
| 20474 |
|
| 20475 |
As \csopt{missing-sort-fallback} but for \dual\ sorting. |
| 20476 |
|
| 20477 |
\optsection[\subsubsection]{dual-trim-sort} |
| 20478 |
|
| 20479 |
As \csopt{trim-sort} but for \dual\ sorting. |
| 20480 |
|
| 20481 |
\optsection[\subsubsection]{dual-sort-replace} |
| 20482 |
|
| 20483 |
As \csopt{sort-replace} but for \dual\ sorting. |
| 20484 |
|
| 20485 |
\optsection[\subsubsection]{dual-sort-rule} |
| 20486 |
|
| 20487 |
As \csopt{sort-rule} but for \csopt[custom]{dual-sort}. |
| 20488 |
|
| 20489 |
\optsection[\subsubsection]{dual-break-at} |
| 20490 |
|
| 20491 |
As \csopt{break-at} but for \glspl{dualentry}. |
| 20492 |
|
| 20493 |
\optsection[\subsubsection]{dual-break-marker} |
| 20494 |
|
| 20495 |
As \csopt{break-marker} but for \glspl{dualentry}. |
| 20496 |
|
| 20497 |
\optsection[\subsubsection]{dual-break-at-match} |
| 20498 |
|
| 20499 |
As \csopt{break-at-match} but for \glspl{dualentry}. |
| 20500 |
|
| 20501 |
\optsection[\subsubsection]{dual-break-at-match-op} |
| 20502 |
|
| 20503 |
As \csopt{break-at-match-op} but for \glspl{dualentry}. |
| 20504 |
|
| 20505 |
\optsection[\subsubsection]{dual-break-at-not-match} |
| 20506 |
|
| 20507 |
As \csopt{break-at-not-match} but for \glspl{dualentry}. |
| 20508 |
|
| 20509 |
\optsection[\subsubsection]{dual-sort-number-pad} |
| 20510 |
|
| 20511 |
As \csopt{sort-number-pad} but for \glspl{dualentry}. |
| 20512 |
|
| 20513 |
\optsection[\subsubsection]{dual-sort-pad-plus} |
| 20514 |
|
| 20515 |
As \csopt{sort-pad-plus} but for \glspl{dualentry}. |
| 20516 |
|
| 20517 |
\optsection[\subsubsection]{dual-sort-pad-minus} |
| 20518 |
|
| 20519 |
As \csopt{sort-pad-minus} but for \glspl{dualentry}. |
| 20520 |
|
| 20521 |
\optsection[\subsubsection]{dual-identical-sort-action} |
| 20522 |
|
| 20523 |
As \csopt{identical-sort-action} but for \glspl{dualentry}. |
| 20524 |
|
| 20525 |
\optsection[\subsubsection]{dual-sort-suffix} |
| 20526 |
|
| 20527 |
As \csopt{sort-suffix} but for \glspl{dualentry}. |
| 20528 |
|
| 20529 |
\optsection[\subsubsection]{dual-sort-suffix-marker} |
| 20530 |
|
| 20531 |
As \csopt{sort-suffix-marker} but for \glspl{dualentry}. |
| 20532 |
|
| 20533 |
\optsection[\subsubsection]{dual-strength} |
| 20534 |
|
| 20535 |
As \csopt{strength} but for \glspl{dualentry}. |
| 20536 |
|
| 20537 |
\optsection[\subsubsection]{dual-decomposition} |
| 20538 |
|
| 20539 |
As \csopt{decomposition} but for \glspl{dualentry}. |
| 20540 |
|
| 20541 |
\optsection[\subsubsection]{dual-letter-number-rule} |
| 20542 |
|
| 20543 |
As \csopt{letter-number-rule} but for \glspl{dualentry} that use a |
| 20544 |
letter-number sort. |
| 20545 |
|
| 20546 |
\optsection[\subsubsection]{dual-letter-number-punc-rule} |
| 20547 |
|
| 20548 |
As \csopt{letter-number-punc-rule} but for \glspl{dualentry} that use a |
| 20549 |
letter-number sort. |
| 20550 |
|
| 20551 |
\optsection[\subsubsection]{dual-numeric-sort-pattern} |
| 20552 |
|
| 20553 |
As \csopt{numeric-sort-pattern} but for \glspl{dualentry} that use a |
| 20554 |
locale-sensitive numeric sort. |
| 20555 |
|
| 20556 |
\optsection[\subsubsection]{dual-numeric-locale} |
| 20557 |
|
| 20558 |
As \csopt{numeric-locale} but for \glspl{dualentry} that use a |
| 20559 |
locale-sensitive numeric sort. |
| 20560 |
|
| 20561 |
\optsection[\subsubsection]{dual-date-sort-locale} |
| 20562 |
|
| 20563 |
As \csopt{date-sort-locale} but for \glspl{dualentry} that |
| 20564 |
use a date/time sort. |
| 20565 |
|
| 20566 |
\optsection[\subsubsection]{dual-date-sort-format} |
| 20567 |
|
| 20568 |
As \csopt{date-sort-format} but for \glspl{dualentry} that |
| 20569 |
use a date/time sort. |
| 20570 |
|
| 20571 |
\optsection[\subsubsection]{dual-group-formation} |
| 20572 |
|
| 20573 |
As \csopt{group-formation} but for \dual\ sorting. |
| 20574 |
|
| 20575 |
|
| 20576 |
\subsection{Dual Mappings} |
| 20577 |
\label{sec:dualoptsmap} |
| 20578 |
|
| 20579 |
\optsection[\subsubsection]{dual-entry-map} |
| 20580 |
|
| 20581 |
This setting governs the behaviour of \atentry{dualentry} |
| 20582 |
definitions. The value consists of two comma-separated lists of |
| 20583 |
equal length identifying the field mapping used to create the |
| 20584 |
\gls{dualentry} from the \primary\ one. Note that the \field{alias} field |
| 20585 |
can't be mapped. |
| 20586 |
|
| 20587 |
The default setting is: |
| 20588 |
\begin{codeenv} |
| 20589 |
\csopt[ |
| 20590 |
\marg{\field{name},\field{plural},\field{description},\field{descriptionplural}}, |
| 20591 |
\marg{\field{description},\field{descriptionplural},\field{name},\field{plural}} |
| 20592 |
]{dual-entry-map} |
| 20593 |
\end{codeenv} |
| 20594 |
The \gls{dualentry} is created by copying the value of the field in the |
| 20595 |
first list \meta{list1} to the field in the corresponding place in the second |
| 20596 |
list \meta{list2}. Any additional fields are copied over to the same |
| 20597 |
field. |
| 20598 |
For example: |
| 20599 |
\begin{codeenv} |
| 20600 |
\atentry{dualentry}\marg{cat, |
| 20601 |
\field{name}=\marg{cat}, |
| 20602 |
\field{description}=\marg{chat}, |
| 20603 |
\field{see}=\marg{dog} |
| 20604 |
} |
| 20605 |
\end{codeenv} |
| 20606 |
defines two entries. The \gls{primaryentry} is essentially like: |
| 20607 |
\begin{codeenv} |
| 20608 |
\atentry{entry}\marg{cat, |
| 20609 |
\field{name}=\marg{cat}, |
| 20610 |
\field{plural}=\marg{cat\cs{glspluralsuffix} }, |
| 20611 |
\field{description}=\marg{chat}, |
| 20612 |
\field{descriptionplural}=\marg{chat\cs{glspluralsuffix} }, |
| 20613 |
\field{see}=\marg{dog} |
| 20614 |
} |
| 20615 |
\end{codeenv} |
| 20616 |
and the \gls{dualentry} is essentially like: |
| 20617 |
\begin{codeenv} |
| 20618 |
\atentry{entry}\marg{dual.cat, |
| 20619 |
\field{description}=\marg{cat}, |
| 20620 |
\field{descriptionplural}=\marg{cat\cs{glspluralsuffix} }, |
| 20621 |
\field{name}=\marg{chat}, |
| 20622 |
\field{plural}=\marg{chat\cs{glspluralsuffix} }, |
| 20623 |
\field{see}=\marg{dog} |
| 20624 |
} |
| 20625 |
\end{codeenv} |
| 20626 |
(except they're defined using \gls{bibglsnewdualentry} instead of |
| 20627 |
\gls{bibglsnewentry}, and each is considered dependent on the other.) |
| 20628 |
|
| 20629 |
The \field{see} field isn't listed in \csopt{dual-entry-map} so its |
| 20630 |
value is simply copied directly over to the \field{see} field in the |
| 20631 |
dual entry. Note that the missing \field{plural} and |
| 20632 |
\field{descriptionplural} fields have been filled in using their |
| 20633 |
fallback values (see \sectionref{sec:fallbacks}). |
| 20634 |
|
| 20635 |
In general \bibgls\ doesn't try to supply missing fields, but in the |
| 20636 |
dual entry cases it needs to do this for the mapped fields. This is |
| 20637 |
because the shuffled fields might have different default values from |
| 20638 |
the \styfmt{glossaries-extra} package's point of view. For example, |
| 20639 |
\gls{longnewglossaryentry} doesn't provide a default for |
| 20640 |
\field{descriptionplural} if it hasn't been set. |
| 20641 |
|
| 20642 |
\optsection[\subsubsection]{dual-abbrv-map} |
| 20643 |
|
| 20644 |
This is like \csopt{dual-entry-map} but applies to |
| 20645 |
\atentry{dualabbreviation} rather than \atentry{dualentry}. |
| 20646 |
Note that the \field{alias} field can't be mapped. The |
| 20647 |
default setting is: |
| 20648 |
\begin{codeenv} |
| 20649 |
\csopt[ |
| 20650 |
\marg{\field{short},\field{shortplural},\field{long},\field{longplural},\field{dualshort},\field{dualshortplural}, |
| 20651 |
\field{duallong},\field{duallongplural}}, |
| 20652 |
\marg{\field{dualshort},\field{dualshortplural},\field{duallong},\field{duallongplural},\field{short},\field{shortplural}, |
| 20653 |
\field{long},\field{longplural}} |
| 20654 |
]{dual-abbrv-map} |
| 20655 |
\end{codeenv} |
| 20656 |
|
| 20657 |
This essentially flips the \field{short} field with the |
| 20658 |
\field{dualshort} field and the \field{long} field with the |
| 20659 |
\field{duallong} field. See \atentry{dualabbreviation} |
| 20660 |
for further details. |
| 20661 |
|
| 20662 |
\optsection[\subsubsection]{dual-abbrventry-map} |
| 20663 |
|
| 20664 |
This is like \csopt{dual-entry-map} but applies to |
| 20665 |
\atentry{dualabbreviationentry} rather than \atentry{dualentry}. |
| 20666 |
Note that the \field{alias} field can't be mapped. The |
| 20667 |
default setting is: |
| 20668 |
\begin{codeenv} |
| 20669 |
\csopt[ |
| 20670 |
\marg{\field{long},\field{short},\field{shortplural}}, |
| 20671 |
\marg{\field{name},\field{text},\field{plural}} |
| 20672 |
]{dual-abbrventry-map} |
| 20673 |
\end{codeenv} |
| 20674 |
See \atentry{dualabbreviationentry} for further details. |
| 20675 |
|
| 20676 |
|
| 20677 |
\optsection[\subsubsection]{dual-symbol-map} |
| 20678 |
|
| 20679 |
This is like \csopt{dual-entry-map} but applies to |
| 20680 |
\atentry{dualsymbol} rather than \atentry{dualentry}. |
| 20681 |
Note that the \field{alias} field can't be mapped. The |
| 20682 |
default setting is: |
| 20683 |
\begin{codeenv} |
| 20684 |
\csopt[ |
| 20685 |
\marg{\field{name},\field{plural},\field{symbol},\field{symbolplural}}, |
| 20686 |
\marg{\field{symbol},\field{symbolplural},\field{name},\field{plural}} |
| 20687 |
]{dual-symbol-map} |
| 20688 |
\end{codeenv} |
| 20689 |
This essentially flips the \field{name} field with the |
| 20690 |
\field{symbol} field. |
| 20691 |
|
| 20692 |
\optsection[\subsubsection]{dual-indexentry-map} |
| 20693 |
|
| 20694 |
This is like \csopt{dual-entry-map} but applies to |
| 20695 |
\atentry{dualindexentry} rather than \atentry{dualentry}. |
| 20696 |
The default setting is: |
| 20697 |
\begin{codeenv} |
| 20698 |
\csopt[ |
| 20699 |
\marg{\field{name}}, |
| 20700 |
\marg{\field{name}} |
| 20701 |
]{dual-indexentry-map} |
| 20702 |
\end{codeenv} |
| 20703 |
Note that there must always be at least one pair, even if it's the |
| 20704 |
same field, since this identifies the field to use for the backlink, |
| 20705 |
if set. |
| 20706 |
|
| 20707 |
\optsection[\subsubsection]{dual-indexsymbol-map} |
| 20708 |
|
| 20709 |
This is like \csopt{dual-entry-map} but applies to both |
| 20710 |
\atentry{dualindexsymbol} and \atentry{dualindexnumber}. |
| 20711 |
The default setting is: |
| 20712 |
\begin{codeenv} |
| 20713 |
\csopt[ |
| 20714 |
\marg{\field{symbol},\field{name},\field{symbolplural},\field{plural}}, |
| 20715 |
\marg{\field{name},\field{symbol},\field{plural},\field{symbolplural}} |
| 20716 |
]{dual-indexsymbol-map} |
| 20717 |
\end{codeenv} |
| 20718 |
|
| 20719 |
\optsection[\subsubsection]{dual-indexabbrv-map} |
| 20720 |
|
| 20721 |
This is like \csopt{dual-entry-map} but applies to both the dual |
| 20722 |
\atentry{dualindexabbreviation} and tertiary |
| 20723 |
\atentry{tertiaryindexabbreviationentry} \glspl{entrytype}. |
| 20724 |
The default setting is: |
| 20725 |
\begin{codeenv} |
| 20726 |
\csopt[ |
| 20727 |
\marg{\field{name}}, |
| 20728 |
\marg{\field{name}} |
| 20729 |
]{dual-indexabbrv-map} |
| 20730 |
\end{codeenv} |
| 20731 |
|
| 20732 |
\subsection{Dual Back-Links} |
| 20733 |
\label{sec:dualoptsbacklinks} |
| 20734 |
|
| 20735 |
\optsection[\subsubsection]{dual-entry-backlink} |
| 20736 |
|
| 20737 |
This is a boolean setting. If \meta{boolean} is missing \optfmt{true} |
| 20738 |
is assumed. |
| 20739 |
|
| 20740 |
When used with \atentry{dualentry}, if \meta{boolean} is |
| 20741 |
\optfmt{true}, this will wrap the contents of the first mapped field |
| 20742 |
with \gls{bibglshyperlink}. The field is obtained from the first |
| 20743 |
mapping listed in \csopt{dual-entry-map}. |
| 20744 |
|
| 20745 |
For example, if the document contains: |
| 20746 |
\begin{codeenv} |
| 20747 |
\gls{GlsXtrLoadResources}\oarg{\csopt{dual-entry-backlink}, |
| 20748 |
\csopt[ |
| 20749 |
\marg{\field{name},\field{plural},\field{description},\field{descriptionplural}}, |
| 20750 |
\marg{\field{description},\field{descriptionplural},\field{name},\field{plural}} |
| 20751 |
]{dual-entry-map}, |
| 20752 |
\csopt[entries-dual]{src}} |
| 20753 |
\end{codeenv} |
| 20754 |
and if the \ext{bib} file contains: |
| 20755 |
\begin{codeenv} |
| 20756 |
\atentry{dualentry}\marg{child, |
| 20757 |
\field{name}=\marg{child}, |
| 20758 |
\field{plural}=\marg{children}, |
| 20759 |
\field{description}=\marg{enfant} |
| 20760 |
} |
| 20761 |
\end{codeenv} |
| 20762 |
Then the definition of the \gls{primaryentry} (\code{child}) in the |
| 20763 |
\ext{glstex} file will set the \field{description} field to: |
| 20764 |
\begin{codeenv} |
| 20765 |
\gls{bibglshyperlink}\marg{enfant}\marg{dual.child} |
| 20766 |
\end{codeenv} |
| 20767 |
and the \gls{dualentry} (\code{dual.child}) will have the |
| 20768 |
\field{description} field set to: |
| 20769 |
\begin{codeenv} |
| 20770 |
\gls{bibglshyperlink}\marg{child}\marg{child} |
| 20771 |
\end{codeenv} |
| 20772 |
This use of the wrapper \gls{bibglshyperlink} (rather than explicitly |
| 20773 |
using \ics{glshyperlink}) and inserting the actual field value |
| 20774 |
(rather than using commands like \ics{glsentryname}) allows it |
| 20775 |
to work with \ics{makefirstuc} if the field requires a case-change. |
| 20776 |
|
| 20777 |
The reason the \field{description} field is chosen for the modification is |
| 20778 |
because the first field listed in \meta{list1} of \csopt{dual-entry-map} |
| 20779 |
is the \field{name} field which maps to \field{description} (the |
| 20780 |
first field in the second list \meta{list2}). This means that the hyperlink for |
| 20781 |
the \gls{dualentry} should be put in the \field{description} field. |
| 20782 |
|
| 20783 |
For the \gls{primaryentry}, the \field{name} field is looked up in the |
| 20784 |
second list from the \csopt{dual-entry-map} setting. This is the |
| 20785 |
third item in this second list, so the third item in the first list |
| 20786 |
is selected, which also happens to be the \field{description} field, |
| 20787 |
so the hyperlink for the \gls{primaryentry} is put in the |
| 20788 |
\field{description} field. |
| 20789 |
|
| 20790 |
\optsection[\subsubsection]{dual-abbrv-backlink} |
| 20791 |
|
| 20792 |
This is analogous to \csopt{dual-entry-backlink} but for entries |
| 20793 |
defined with \atentry{dualabbreviation} instead of |
| 20794 |
\atentry{dualentry}. |
| 20795 |
|
| 20796 |
\optsection[\subsubsection]{dual-symbol-backlink} |
| 20797 |
|
| 20798 |
This is analogous to \csopt{dual-entry-backlink} but for entries |
| 20799 |
defined with \atentry{dualsymbol} instead of \atentry{dualentry}. |
| 20800 |
|
| 20801 |
\optsection[\subsubsection]{dual-abbrventry-backlink} |
| 20802 |
|
| 20803 |
Analogous to \csopt{dual-entry-backlink} but for entries |
| 20804 |
defined with \atentry{dualabbreviationentry} instead of |
| 20805 |
\atentry{dualentry}. This setting can be problematic as the |
| 20806 |
backlinks rely on the relevant field being known to \bibgls. |
| 20807 |
Since the abbreviation style typically sets the \field{name} |
| 20808 |
field (and sometimes the \field{description} field as well), you may |
| 20809 |
find that no backlink appears. A simple workaround is to |
| 20810 |
use \csopt{dual-field} (or \csopt[dual]{dual-field}) |
| 20811 |
to store the dual label in the \field{dual} field, and then |
| 20812 |
use a style that checks for this field and adds the backlink. |
| 20813 |
|
| 20814 |
With \sty{glossaries-extra} v1.30+ you can use: |
| 20815 |
\nosecdef{GlsXtrDualBackLink} |
| 20816 |
which encapsulates \meta{text} with a hyperlink to the \dual. |
| 20817 |
The \meta{label} identifies the entry that requires a backlink. |
| 20818 |
The \glsdisp{dualentry}{dual's} label is obtained from the field given by: |
| 20819 |
\nosecdef{GlsXtrDualField} |
| 20820 |
which defaults to \field{dual}. Note that if you assign a |
| 20821 |
different field label with \csopt{dual-field}, then you will |
| 20822 |
need to redefine \gls{GlsXtrDualField} as appropriate. |
| 20823 |
|
| 20824 |
For example: |
| 20825 |
\begin{codeenv} |
| 20826 |
\cs{renewcommand}*\marg{\ics{glsuserdescription}}[2]\marg{\comment{} |
| 20827 |
\gls{GlsXtrDualBackLink}\marg{\ics{glslonguserfont}\marg{\idx{param}1}}\marg{\idx{param}2}\comment{} |
| 20828 |
} |
| 20829 |
\cs{setabbreviationstyle}\marg{\abbrstyle{long-short-user}} |
| 20830 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt{dual-field}} |
| 20831 |
\end{codeenv} |
| 20832 |
|
| 20833 |
\optsection[\subsubsection]{dual-entryabbrv-backlink} |
| 20834 |
|
| 20835 |
As \csopt{dual-abbrventry-backlink} but for entries |
| 20836 |
defined with \atentry{dualentryabbreviation} instead of |
| 20837 |
\atentry{dualabbreviationentry}. |
| 20838 |
|
| 20839 |
\optsection[\subsubsection]{dual-indexentry-backlink} |
| 20840 |
|
| 20841 |
This is analogous to \csopt{dual-entry-backlink} but for entries |
| 20842 |
defined with \atentry{dualindexentry} instead of |
| 20843 |
\atentry{dualentry}. |
| 20844 |
|
| 20845 |
\optsection[\subsubsection]{dual-indexsymbol-backlink} |
| 20846 |
|
| 20847 |
This is analogous to \csopt{dual-entry-backlink} but for entries |
| 20848 |
defined with \atentry{dualindexsymbol} and |
| 20849 |
\atentry{dualindexnumber}. |
| 20850 |
|
| 20851 |
\optsection[\subsubsection]{dual-indexabbrv-backlink} |
| 20852 |
|
| 20853 |
This is analogous to \csopt{dual-entry-backlink} but for entries |
| 20854 |
defined with \atentry{dualindexabbreviation} and |
| 20855 |
\atentry{tertiaryindexabbreviationentry}. |
| 20856 |
|
| 20857 |
\optsection[\subsubsection]{dual-backlink} |
| 20858 |
|
| 20859 |
Shortcut for: |
| 20860 |
\begin{flushleft}\obeylines |
| 20861 |
\csopt[\meta{boolean}]{dual-entry-backlink}, |
| 20862 |
\csopt[\meta{boolean}]{dual-abbrventry-backlink}, |
| 20863 |
\csopt[\meta{boolean}]{dual-abbrv-backlink}, |
| 20864 |
\csopt[\meta{boolean}]{dual-symbol-backlink}, |
| 20865 |
\csopt[\meta{boolean}]{dual-indexentry-backlink}, |
| 20866 |
\csopt[\meta{boolean}]{dual-indexsymbol-backlink}, |
| 20867 |
\csopt[\meta{boolean}]{dual-indexabbrv-backlink} |
| 20868 |
\end{flushleft} |
| 20869 |
|
| 20870 |
\section{Tertiary Entries} |
| 20871 |
|
| 20872 |
\optsection{tertiary-prefix} |
| 20873 |
|
| 20874 |
This option indicates the prefix to use for the \glspl{tertiaryentry}. The |
| 20875 |
default value is \idprefix{tertiary} (including the terminating period). |
| 20876 |
|
| 20877 |
As from version 1.8, the \glsdisp{tertiaryentry}{tertiary} label prefix is identified |
| 20878 |
in the \ext{glstex} file with: |
| 20879 |
\begin{codeenv} |
| 20880 |
\format{bibglstertiaryprefixlabel} |
| 20881 |
\end{codeenv} |
| 20882 |
|
| 20883 |
\optsection{tertiary-type} |
| 20884 |
|
| 20885 |
This option indicates that the \glspl{tertiaryentry} should have |
| 20886 |
their \field{type} field set to \meta{value}. If \meta{value} is |
| 20887 |
empty the \field{type} is left unchanged. Unlike |
| 20888 |
the \csopt{type} and \csopt{dual-type} options, there are no |
| 20889 |
recognised keywords. |
| 20890 |
|
| 20891 |
\optsection{tertiary-category} |
| 20892 |
|
| 20893 |
This option indicates that the \glspl{tertiaryentry} should have |
| 20894 |
their \field{category} field set to \meta{value}. If \meta{value} is |
| 20895 |
empty the \field{category} is left unchanged. Unlike |
| 20896 |
the \csopt{category} and \csopt{dual-category} options, there are no |
| 20897 |
recognised keywords. |
| 20898 |
|
| 20899 |
\section{Compound (Combined or Multi) Entries} |
| 20900 |
\label{sec:compoundentries} |
| 20901 |
|
| 20902 |
These options refer to \glspl{compoundentry} which are either |
| 20903 |
defined in a \ext{bib} file with \atentry{compoundset} or are |
| 20904 |
defined in the document using \cs{multiglossaryentry} (or |
| 20905 |
\cs{provideglossaryentry}). See \sectionref{sec:compoundsetentry} |
| 20906 |
for further details. |
| 20907 |
|
| 20908 |
\optsection{compound-options-global} |
| 20909 |
|
| 20910 |
This is a boolean option. The default is |
| 20911 |
\csopt[true]{compound-options-global}. |
| 20912 |
|
| 20913 |
If \optfmt{true}, the \gls{compoundentry} options described in this |
| 20914 |
section, except for \csopt{compound-write-def}, pick up all |
| 20915 |
\glspl{compoundentry} provided in the document (defined either with |
| 20916 |
\atentry{compoundset} or in the document with |
| 20917 |
\ics{multiglossaryentry}). |
| 20918 |
|
| 20919 |
If \optfmt{false}, options only apply to \glspl{compoundentry} defined |
| 20920 |
with \atentry{compoundset} in the current \gls{resourceset}. |
| 20921 |
|
| 20922 |
If \igls{crossresourceref} are disabled then any instances of |
| 20923 |
\atentry{compoundset} in subsequent \glspl{resourceset} can only be |
| 20924 |
picked up from the \ext{aux} file on the next build. |
| 20925 |
|
| 20926 |
\optsection{compound-dependent} |
| 20927 |
|
| 20928 |
This is a boolean option. The default is |
| 20929 |
\csopt[false]{compound-dependent}. |
| 20930 |
|
| 20931 |
If you have chosen to switch off indexing for the \glspl{compotherlabel} |
| 20932 |
then they may not be selected (unless they have been indexed via |
| 20933 |
another method, such as explicitly using \cs{gls}). You can use this |
| 20934 |
option to make the \glspl{compotherlabel} dependencies of the |
| 20935 |
\gls{compmainlabel} (if the entry given by \gls{compmainlabel} is |
| 20936 |
present in the current \gls{resourceset}). |
| 20937 |
|
| 20938 |
This means that if the \gls{compmainlabel} is selected then the |
| 20939 |
\glspl{compotherlabel} should also be selected (if dependencies are |
| 20940 |
part of the selection criteria). |
| 20941 |
|
| 20942 |
\optsection{compound-add-hierarchy} |
| 20943 |
|
| 20944 |
This is a boolean option. The default is |
| 20945 |
\csopt[false]{compound-add-hierarchy}. |
| 20946 |
If true, this will set the \field{parent} field for each element |
| 20947 |
$e_i$ to the previous element $e_{i-1}$ in the list, provided that: |
| 20948 |
\begin{itemize} |
| 20949 |
\item the element $e_i$ isn't the first element in the list; |
| 20950 |
\item the element $e_i$ and the previous element $e_{i-1}$ are |
| 20951 |
present in the current \gls{resourceset}; |
| 20952 |
\item the element $e_i$ doesn't already have the \field{parent} field set; |
| 20953 |
\item the element $e_i$ isn't an \gls{ancestor} of the previous element $e_{i-1}$. |
| 20954 |
\item the previous element $e_{i-1}$ isn't an \gls{ancestor} of the |
| 20955 |
element $e_i$. |
| 20956 |
\end{itemize} |
| 20957 |
For example, if the \ext{bib} file contains: |
| 20958 |
\begin{codeenv} |
| 20959 |
\atentry{abbreviation}\marg{clostridium, |
| 20960 |
\field{short}=\marg{C.}, |
| 20961 |
\field{long}=\marg{Clostridium} |
| 20962 |
} |
| 20963 |
\atentry{index}\marg{botulinum} |
| 20964 |
\atentry{compoundset}\marg{cbot, |
| 20965 |
\field{elements}=\marg{clostridium,botulinum}} |
| 20966 |
\end{codeenv} |
| 20967 |
Then the \code{botulinum} entry will have its \field{parent} field |
| 20968 |
set to \code{clostridium}. The \code{clostridium} entry won't be |
| 20969 |
adjusted (since it's the first element in the list). |
| 20970 |
|
| 20971 |
\optsection{compound-has-records} |
| 20972 |
|
| 20973 |
This option may take one of the following values: |
| 20974 |
\begin{description} |
| 20975 |
\item[\optfmt{true}] |
| 20976 |
Any \gls{compoundentry} referenced with commands like |
| 20977 |
\ics{mgls} is considered to have \glspl{record} for each element for |
| 20978 |
selection purposes, even if there are no \glspl{record} in the \ext{aux} |
| 20979 |
file. (This is useful on the first \LaTeX\ run where the |
| 20980 |
\glspl{compoundentry} are defined with \atentry{compoundset}.) |
| 20981 |
|
| 20982 |
\item[\optfmt{false}] |
| 20983 |
The element \glspl{record} are created as they normally are with |
| 20984 |
commands like \cs{gls} that are internally used by \cs{mgls}. |
| 20985 |
|
| 20986 |
\item[\optfmt{default}] |
| 20987 |
Behaves like \csopt[true]{compound-has-records} if the current |
| 20988 |
\gls{resourceset} has any \ext{bib} files containing one or more |
| 20989 |
\atentry{compoundset} \glspl{entrytype}. Otherwise behaves like |
| 20990 |
\csopt[false]{compound-has-records}. |
| 20991 |
\end{description} |
| 20992 |
|
| 20993 |
The default is \csopt[default]{compound-has-records}. |
| 20994 |
If the value is omitted, \optfmt{true} is assumed. |
| 20995 |
|
| 20996 |
\optsection{compound-adjust-name} |
| 20997 |
|
| 20998 |
If an entry has been identified as the \gls{compmainlabel} in any |
| 20999 |
\glspl{compoundentry} then the \field{name} field can be adjusted |
| 21000 |
with this option. Allowed values: |
| 21001 |
\begin{itemize} |
| 21002 |
\item \optfmt{false} don't adjust the \field{name} field (default); |
| 21003 |
\item \optfmt{unique} only adjust the \field{name} field if |
| 21004 |
the entry is the \gls{compmainlabel} of exactly one set; |
| 21005 |
\item \optfmt{once} adjust the \field{name} field if |
| 21006 |
the entry is the \gls{compmainlabel} of any set. Only one adjustment |
| 21007 |
is made. If the entry is the \gls{compmainlabel} of multiple |
| 21008 |
\glspl{compoundentry} there's no guarantee which set will be chosen |
| 21009 |
for the adjustment. |
| 21010 |
\end{itemize} |
| 21011 |
|
| 21012 |
If the value isn't supplied, \optfmt{once} is assumed. As with |
| 21013 |
\csopt{name-case-change}, the pre-adjusted \field{name} value will |
| 21014 |
be copied to the \field{text} field provided the \field{text} field |
| 21015 |
hasn't already been set and provided that the entry isn't an |
| 21016 |
abbreviation. |
| 21017 |
|
| 21018 |
The adjusted value will be in the form: |
| 21019 |
\begin{codeenv*} |
| 21020 |
\ics{glsxtrmultientryadjustedname}\margm{sublist1}\margm{name}\margm{sublist2}\marg{mlabel} |
| 21021 |
\end{codeenv*} |
| 21022 |
where \meta{label} is the \gls{compoundentry} label, \meta{name} was |
| 21023 |
the value of the \field{name} field before the adjustment, |
| 21024 |
\meta{sublist1} is the list of \glspl{compotherlabel} before the |
| 21025 |
\gls{compmainlabel} (which will be empty if the \gls{compmainlabel} |
| 21026 |
is the first element in the set) and |
| 21027 |
\meta{sublist2} is the list of \glspl{compotherlabel} after the |
| 21028 |
\gls{compmainlabel} (which will be empty if the \gls{compmainlabel} |
| 21029 |
is the last element in the set). |
| 21030 |
|
| 21031 |
The adjustment is made before \csopt{name-case-change} (if set). |
| 21032 |
The control sequence case changes (such as |
| 21033 |
\csopt[firstuc-cs]{name-case-change}) will replace \cs{glsxtrmultientryadjustedname} |
| 21034 |
with the relevant command (\ics{Glsxtrmultientryadjustedname} for |
| 21035 |
\optfmt{firstuc-cs}, \ics{GlsXtrmultientryadjustedname} for |
| 21036 |
\optfmt{title-cs} and \cs{GLSxtrmultientryadjustedname} for |
| 21037 |
\optfmt{uc-cs}). |
| 21038 |
|
| 21039 |
\optsection{compound-main-type} |
| 21040 |
|
| 21041 |
Set the \field{type} field of the \glslink{compmainlabel}{main |
| 21042 |
entries}. The \meta{value} is required and should be one of: |
| 21043 |
\begin{itemize} |
| 21044 |
\item \optfmt{same as entry}: sets the \field{type} to the |
| 21045 |
\gls{entrytype} (\idx!{lowercase} and without |
| 21046 |
the initial \code{@}). For example, if the entry was defined with |
| 21047 |
\atentry{index}, the \field{type} will be set to \optfmt{index}. |
| 21048 |
If you've used \csopt{entry-type-aliases}, this refers to the target |
| 21049 |
\gls{entrytype} not the original \gls{entrytype} provided in the \ext{bib} |
| 21050 |
file. |
| 21051 |
|
| 21052 |
\item \optfmt{same as original entry}: set the \field{type} field |
| 21053 |
to the original \gls{entrytype} (\idx!{lowercase} and without |
| 21054 |
the initial \code{@}) before it was aliased (behaves like |
| 21055 |
\optfmt{same as entry} if the \gls{entrytype} wasn't aliased). |
| 21056 |
|
| 21057 |
\item \optfmt{same as base}: sets the \field{type} to the base name |
| 21058 |
of the \ext{bib} file (without the extension) that provided the |
| 21059 |
entry definition; |
| 21060 |
|
| 21061 |
\item \optfmt{same as category}: sets the \field{type} to the same |
| 21062 |
as the \field{category} field; |
| 21063 |
|
| 21064 |
\item \optfmt{same as parent}: sets the \field{type} to the same as |
| 21065 |
the entry's \parent. If the entry doesn't have a |
| 21066 |
\parent\ or if the \parent\ doesn't have the \field{type} field set, |
| 21067 |
then no change is made. |
| 21068 |
|
| 21069 |
\item \meta{label}: sets the \field{type} field to \meta{label}. |
| 21070 |
\end{itemize} |
| 21071 |
|
| 21072 |
This setting is governed by \csopt{compound-type-override}. |
| 21073 |
|
| 21074 |
\optsection{compound-other-type} |
| 21075 |
|
| 21076 |
Set the \field{type} field of the \glslink{compotherlabel}{other |
| 21077 |
entries}. The \meta{value} is required and should be one of: |
| 21078 |
\begin{itemize} |
| 21079 |
\item \optfmt{same as main}: sets the \field{type} to the same as |
| 21080 |
the \glslink{compmainlabel}{main entry}. |
| 21081 |
|
| 21082 |
\item \optfmt{same as entry}: sets the \field{type} to the |
| 21083 |
\gls{entrytype} (\idx!{lowercase} and without |
| 21084 |
the initial \code{@}). For example, if the entry was defined with |
| 21085 |
\atentry{index}, the \field{type} will be set to \optfmt{index}. |
| 21086 |
If you've used \csopt{entry-type-aliases}, this refers to the target |
| 21087 |
\gls{entrytype} not the original \gls{entrytype} provided in the \ext{bib} |
| 21088 |
file. |
| 21089 |
|
| 21090 |
\item \optfmt{same as original entry}: set the \field{type} field |
| 21091 |
to the original \gls{entrytype} (\idx!{lowercase} and without |
| 21092 |
the initial \code{@}) before it was aliased (behaves like |
| 21093 |
\optfmt{same as entry} if the \gls{entrytype} wasn't aliased). |
| 21094 |
|
| 21095 |
\item \optfmt{same as base}: sets the \field{type} to the base name |
| 21096 |
of the \ext{bib} file (without the extension) that provided the |
| 21097 |
entry definition; |
| 21098 |
|
| 21099 |
\item \optfmt{same as category}: sets the \field{type} to the same |
| 21100 |
as the \field{category} field; |
| 21101 |
|
| 21102 |
\item \optfmt{same as parent}: sets the \field{type} to the same as |
| 21103 |
the entry's \parent. If the entry doesn't have a |
| 21104 |
\parent\ or if the \parent\ doesn't have the \field{type} field set, |
| 21105 |
then no change is made. |
| 21106 |
|
| 21107 |
\item \meta{label}: sets the \field{type} field to \meta{label}. |
| 21108 |
\end{itemize} |
| 21109 |
|
| 21110 |
This setting is governed by \csopt{compound-type-override}. |
| 21111 |
|
| 21112 |
\optsection{compound-type-override} |
| 21113 |
|
| 21114 |
This is a boolean option. The default is |
| 21115 |
\csopt[false]{compound-type-override}. |
| 21116 |
|
| 21117 |
If \optfmt{true}, then the options \csopt{compound-main-type} |
| 21118 |
and \csopt{compound-other-type} will overwrite the \field{type} |
| 21119 |
field otherwise those options will only set the \field{type} field |
| 21120 |
if it hasn't already been set. |
| 21121 |
|
| 21122 |
\optsection{compound-write-def} |
| 21123 |
|
| 21124 |
If \glspl{compoundentry} are defined in the \ext{bib} files using |
| 21125 |
\atentry{compoundset}, this option governs whether or not to write |
| 21126 |
their definition to the \ext{glstex} file. The value may be one of: |
| 21127 |
\begin{definition} |
| 21128 |
\item[\optfmt{none}] Don't write the definitions to the \ext{glstex} |
| 21129 |
file. For example, if you are reloading a \ext{bib} file from |
| 21130 |
another \gls{resourceset}, you will need this option to prevent |
| 21131 |
duplicate definitions. (The alternative is to define |
| 21132 |
\gls{bibglsdefcompoundset} to use \ics{providemultiglossaryentry} |
| 21133 |
instead of \ics{multiglossaryentry}.) |
| 21134 |
|
| 21135 |
\item[\optfmt{all}] Write all definitions to the \ext{glstex} file, |
| 21136 |
regardless of whether or not they have been referenced using |
| 21137 |
commands like \cs{mgls}. |
| 21138 |
|
| 21139 |
\item[\optfmt{ref}] Only write the definitions for |
| 21140 |
\glspl{compoundentry} that have been referenced using commands like |
| 21141 |
\cs{mgls}. (Default.) |
| 21142 |
\end{definition} |
| 21143 |
|
| 21144 |
The \glspl{compoundentry} are defined in the \ext{glstex} file with |
| 21145 |
\gls{bibglsdefcompoundset}. |
| 21146 |
|
| 21147 |
\chapter{Provided Commands} |
| 21148 |
\label{sec:bibglscs} |
| 21149 |
|
| 21150 |
When \bibgls\ creates the \iext{glstex} file, it writes some |
| 21151 |
definitions for custom commands in the form \csfmt{bibgls\ldots} which |
| 21152 |
may be changed as required. The command definitions all use |
| 21153 |
\ics{providecommand} which means that you can define the command with |
| 21154 |
\ics{newcommand} before the resource file is loaded. |
| 21155 |
|
| 21156 |
Note that if you try to redefine any of these commands after the |
| 21157 |
resource file has been loaded with \ics{renewcommand}, you will get |
| 21158 |
an error on the first \LaTeX\ run when the \ext{glstex} file doesn't |
| 21159 |
exist. You may prefer to use \ics{glsrenewcommand} instead, which |
| 21160 |
will generate a warning instead of an error. |
| 21161 |
|
| 21162 |
Since many of the commands are actually used within the \ext{glstex} |
| 21163 |
file, it's best to use \cs{newcommand} before the first |
| 21164 |
\igls{resourceset} and \cs{renewcommand} between \iglspl{resourceset} |
| 21165 |
if adjustments are necessary. |
| 21166 |
|
| 21167 |
|
| 21168 |
\section{Entry Definitions} |
| 21169 |
\label{sec:newentrydefs} |
| 21170 |
|
| 21171 |
This section lists the commands (\csfmt{bibglsnew\ldots}) used to |
| 21172 |
define entries. Note that the entry definition commands are |
| 21173 |
actually used when \TeX\ inputs the resource file, so redefining |
| 21174 |
them after the resource file is loaded won't have an effect on the |
| 21175 |
entries defined in that resource file (but will affect entries defined |
| 21176 |
in subsequent resource files). Each provided command is defined in |
| 21177 |
the \ext{glstex} file immediately before the first entry that |
| 21178 |
requires it, so only the commands that are actually needed are |
| 21179 |
provided. |
| 21180 |
|
| 21181 |
The \field{sort} key may be set within the \ext{glstex} entry |
| 21182 |
definition, but its value is usually not required in the document |
| 21183 |
unless you are using a hybrid method with \styopt[hybrid]{record} |
| 21184 |
(in which case, it's redundant to get \bibgls\ to sort). |
| 21185 |
|
| 21186 |
After each entry is defined, if it has any associated \glspl{location} and |
| 21187 |
the default \csopt[true]{save-loclist} is set, then the |
| 21188 |
\glspl{location} are added using: |
| 21189 |
\nosecformatdef{glsxtrfieldlistadd} |
| 21190 |
Any additional fields that don't have associated keys are then set (if |
| 21191 |
required) with \ics{GlsXtrSetField}. |
| 21192 |
|
| 21193 |
\cssection{bibglsnewentry} |
| 21194 |
|
| 21195 |
\formatdef{bibglsnewentry} |
| 21196 |
This command is used to define terms identified with the |
| 21197 |
\atentry{entry} type. The definition provided in the \ext{glstex} |
| 21198 |
file is: |
| 21199 |
\begin{codeenv} |
| 21200 |
\cs{providecommand}\marg{\gls{bibglsnewentry}}[4]\marg{\comment{} |
| 21201 |
\cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{} |
| 21202 |
} |
| 21203 |
\end{codeenv} |
| 21204 |
This uses the starred form \ics{longnewglossaryentry*} that |
| 21205 |
doesn't automatically append \ics{nopostdesc} (which interferes with |
| 21206 |
the post-description hooks provided by category attributes). |
| 21207 |
|
| 21208 |
\cssection{bibglsnewsymbol} |
| 21209 |
|
| 21210 |
\formatdef{bibglsnewsymbol} |
| 21211 |
This command is used to define terms identified with the |
| 21212 |
\atentry{symbol} type. The definition provided in the \ext{glstex} |
| 21213 |
file is: |
| 21214 |
\begin{codeenv} |
| 21215 |
\cs{providecommand}\marg{\gls{bibglsnewsymbol}}[4]\marg{\comment{} |
| 21216 |
\cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{sort}=\marg{\idx{param}1},\field{category}=\marg{symbol},\idx{param}2}\marg{\idx{param}4}\comment{} |
| 21217 |
} |
| 21218 |
\end{codeenv} |
| 21219 |
Note that this sets the \field{sort} field to the label, but this |
| 21220 |
may be overridden by the \meta{options} if the \field{sort} field |
| 21221 |
was supplied or if \bibgls\ has determined the value whilst sorting |
| 21222 |
the entries. |
| 21223 |
|
| 21224 |
This also sets the \field{category} to \optfmt{symbol}, but again this may |
| 21225 |
be overridden by \meta{options} if the entry had the \field{category} |
| 21226 |
field set in the \ext{bib} file or if the \field{category} was |
| 21227 |
overridden with \csopt[\meta{value}]{category}. |
| 21228 |
|
| 21229 |
\cssection{bibglsnewnumber} |
| 21230 |
|
| 21231 |
\formatdef{bibglsnewnumber} |
| 21232 |
This command is used to define terms identified with the |
| 21233 |
\atentry{number} type. The definition provided in the \ext{glstex} |
| 21234 |
file is: |
| 21235 |
\begin{codeenv} |
| 21236 |
\cs{providecommand}\marg{\gls{bibglsnewnumber}}[4]\marg{\comment{} |
| 21237 |
\cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{sort}=\marg{\idx{param}1},\field{category}=\marg{number},\idx{param}2}\marg{\idx{param}4}\comment{} |
| 21238 |
} |
| 21239 |
\end{codeenv} |
| 21240 |
This is much the same as \gls{bibglsnewsymbol} above but sets the |
| 21241 |
\field{category} to \optfmt{number}. Again the \field{sort} and |
| 21242 |
\field{category} keys may be overridden by \meta{options}. |
| 21243 |
|
| 21244 |
\cssection{bibglsnewindex} |
| 21245 |
|
| 21246 |
\formatdef{bibglsnewindex} |
| 21247 |
This command is used to define terms identified with the |
| 21248 |
\atentry{index} type. The definition provided in the \ext{glstex} |
| 21249 |
file is: |
| 21250 |
\begin{codeenv} |
| 21251 |
\cs{providecommand}*\marg{\gls{bibglsnewindex}}[2]\marg{\comment{} |
| 21252 |
\gls{newglossaryentry}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}1},\field{category}=\marg{index},\field{description}=\marg{},\idx{param}2}\comment{} |
| 21253 |
} |
| 21254 |
\end{codeenv} |
| 21255 |
This makes the \field{name} default to the \meta{label}, assigns |
| 21256 |
the \field{category} to \code{index} and sets an empty |
| 21257 |
\field{description}. These settings may be overridden by |
| 21258 |
\meta{options}. |
| 21259 |
|
| 21260 |
Note that the \field{description} doesn't include |
| 21261 |
\ics{nopostdesc} to allow for the \idx{postdescriptionhook} used by |
| 21262 |
category attributes. |
| 21263 |
|
| 21264 |
\cssection{bibglsnewindexplural} |
| 21265 |
|
| 21266 |
\formatdef{bibglsnewindexplural} |
| 21267 |
This command is used to define terms identified with the |
| 21268 |
\atentry{indexplural} type. The definition provided in the \ext{glstex} |
| 21269 |
file is: |
| 21270 |
\begin{codeenv} |
| 21271 |
\cs{providecommand}\marg{\gls{bibglsnewindexplural}}[3]\marg{\comment{} |
| 21272 |
\gls{newglossaryentry}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{category}=\marg{indexplural},\field{description}=\marg{},\idx{param}2}\comment{} |
| 21273 |
} |
| 21274 |
\end{codeenv} |
| 21275 |
This assigns the \field{category} to \code{indexplural} and sets an empty |
| 21276 |
\field{description}. These settings may be overridden by \meta{options}. |
| 21277 |
|
| 21278 |
\cssection{bibglsnewabbreviation} |
| 21279 |
|
| 21280 |
\formatdef{bibglsnewabbreviation} |
| 21281 |
This command is used to define terms identified with the |
| 21282 |
\atentry{abbreviation} type. The definition provided in the \ext{glstex} |
| 21283 |
file is: |
| 21284 |
\begin{codeenv} |
| 21285 |
\cs{providecommand}\marg{\gls{bibglsnewabbreviation}}[4]\marg{\comment{} |
| 21286 |
\gls{newabbreviation}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{} |
| 21287 |
} |
| 21288 |
\end{codeenv} |
| 21289 |
Since this uses \gls{newabbreviation}, it obeys the |
| 21290 |
abbreviation style for its given \field{category} (which may have |
| 21291 |
been set in \meta{options}, either from the \field{category} field |
| 21292 |
in the \ext{bib} file or through the \csopt{category} option). |
| 21293 |
Similarly the \field{type} will obey \ics{glsxtrabbrvtype} unless |
| 21294 |
the value is supplied in the \ext{bib} file or through the |
| 21295 |
\csopt{type} option. |
| 21296 |
|
| 21297 |
\cssection{bibglsnewacronym} |
| 21298 |
|
| 21299 |
\formatdef{bibglsnewacronym} |
| 21300 |
This command is used to define terms identified with the |
| 21301 |
\atentry{acronym} type. The definition provided in the \ext{glstex} |
| 21302 |
file is: |
| 21303 |
\begin{codeenv} |
| 21304 |
\cs{providecommand}\marg{\gls{bibglsnewacronym}}[4]\marg{\comment{} |
| 21305 |
\gls{newacronym}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{} |
| 21306 |
} |
| 21307 |
\end{codeenv} |
| 21308 |
This works in much the same way as \gls{bibglsnewabbreviation}. |
| 21309 |
Remember that with the \styfmt{glossaries-extra} package \gls{newacronym} |
| 21310 |
is redefined to just use \gls{newabbreviation} with the default \field{type} |
| 21311 |
set to \ics{acronymtype} and the default \field{category} set to |
| 21312 |
\code{acronym}. |
| 21313 |
|
| 21314 |
\cssection{bibglsnewdualentry} |
| 21315 |
|
| 21316 |
\formatdef{bibglsnewdualentry} |
| 21317 |
This command is used to define terms identified with the |
| 21318 |
\atentry{dualentry} type. The definition provided in the \ext{glstex} |
| 21319 |
file is: |
| 21320 |
\begin{codeenv} |
| 21321 |
\cs{providecommand}\marg{\gls{bibglsnewdualentry}}[4]\marg{\comment{} |
| 21322 |
\cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{} |
| 21323 |
} |
| 21324 |
\end{codeenv} |
| 21325 |
|
| 21326 |
\cssection{bibglsnewdualindexentry} |
| 21327 |
|
| 21328 |
\formatdef{bibglsnewdualindexentry} |
| 21329 |
This command is used to define \primary\ terms identified with the |
| 21330 |
\atentry{dualindexentry} type. The definition provided in the \ext{glstex} |
| 21331 |
file is: |
| 21332 |
\begin{codeenv} |
| 21333 |
\cs{providecommand}\marg{\gls{bibglsnewdualindexentry}}[4]\marg{\comment{} |
| 21334 |
\cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{category}=\marg{index},\idx{param}2}\marg{}\comment{} |
| 21335 |
} |
| 21336 |
\end{codeenv} |
| 21337 |
Note that this definition ignores the \meta{description} argument. |
| 21338 |
|
| 21339 |
\cssection{bibglsnewdualindexentrysecondary} |
| 21340 |
|
| 21341 |
\formatdef{bibglsnewdualindexentrysecondary} |
| 21342 |
This command is used to define \glsdisp{dualentry}{secondary} terms identified with the |
| 21343 |
\atentry{dualindexentry} type. The definition provided in the \ext{glstex} |
| 21344 |
file is: |
| 21345 |
\begin{codeenv} |
| 21346 |
\cs{providecommand}\marg{\gls{bibglsnewdualindexentrysecondary}}[4]\marg{\comment{} |
| 21347 |
\cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{} |
| 21348 |
} |
| 21349 |
\end{codeenv} |
| 21350 |
|
| 21351 |
\cssection{bibglsnewdualindexsymbol} |
| 21352 |
|
| 21353 |
\formatdef{bibglsnewdualindexsymbol} |
| 21354 |
This command is used to define \primary\ terms identified with the |
| 21355 |
\atentry{dualindexsymbol} type. The definition provided in the \ext{glstex} |
| 21356 |
file is: |
| 21357 |
\begin{codeenv} |
| 21358 |
\cs{providecommand}\marg{\gls{bibglsnewdualindexsymbol}}[5]\marg{\comment{} |
| 21359 |
\cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{category}=\marg{index},\field{symbol}=\marg{\idx{param}4},\idx{param}2}\marg{}\comment{} |
| 21360 |
} |
| 21361 |
\end{codeenv} |
| 21362 |
Note that this definition ignores the \meta{description} argument. |
| 21363 |
|
| 21364 |
\cssection{bibglsnewdualindexsymbolsecondary} |
| 21365 |
|
| 21366 |
\formatdef{bibglsnewdualindexsymbolsecondary} |
| 21367 |
This command is used to define \glsdisp{dualentry}{secondary} terms identified with the |
| 21368 |
\atentry{dualindexsymbol} type. The definition provided in the \ext{glstex} |
| 21369 |
file is: |
| 21370 |
\begin{codeenv} |
| 21371 |
\cs{providecommand}\marg{\gls{bibglsnewdualindexsymbolsecondary}}[5]\marg{\comment{} |
| 21372 |
\cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{category}=\marg{symbol},\field{symbol}=\marg{\idx{param}4},\idx{param}2}\marg{\idx{param}5}\comment{} |
| 21373 |
} |
| 21374 |
\end{codeenv} |
| 21375 |
|
| 21376 |
\cssection{bibglsnewdualindexnumber} |
| 21377 |
|
| 21378 |
\formatdef{bibglsnewdualindexnumber} |
| 21379 |
This command is used to define \primary\ terms identified with the |
| 21380 |
\atentry{dualindexnumber} type. The definition provided in the \ext{glstex} |
| 21381 |
file is: |
| 21382 |
\begin{codeenv} |
| 21383 |
\cs{providecommand}\marg{\gls{bibglsnewdualindexnumber}}[5]\marg{\comment{} |
| 21384 |
\cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{category}=\marg{index},\field{symbol}=\marg{\idx{param}4},\idx{param}2}\marg{}\comment{} |
| 21385 |
} |
| 21386 |
\end{codeenv} |
| 21387 |
Note that this definition ignores the \meta{description} argument. |
| 21388 |
|
| 21389 |
\cssection{bibglsnewdualindexnumbersecondary} |
| 21390 |
|
| 21391 |
\formatdef{bibglsnewdualindexnumbersecondary} |
| 21392 |
This command is used to define \glsdisp{dualentry}{secondary} terms identified with the |
| 21393 |
\atentry{dualindexnumber} type. The definition provided in the \ext{glstex} |
| 21394 |
file is: |
| 21395 |
\begin{codeenv} |
| 21396 |
\cs{providecommand}\marg{\cs{bibglsnewdualindexnumbersecondary}}[5]\marg{\comment{} |
| 21397 |
\cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{category}=\marg{number},\field{symbol}=\marg{\idx{param}4},\idx{param}2}\marg{\idx{param}5}\comment{} |
| 21398 |
} |
| 21399 |
\end{codeenv} |
| 21400 |
|
| 21401 |
\cssection{bibglsnewdualindexabbreviation} |
| 21402 |
|
| 21403 |
\formatdef{bibglsnewdualindexabbreviation} |
| 21404 |
This command is used to define \primary\ terms identified with the |
| 21405 |
\atentry{dualindexabbreviation} type. The default definition provided in |
| 21406 |
the \ext{glstex} file is: |
| 21407 |
\begin{codeenv} |
| 21408 |
\cs{providecommand}\marg{\gls{bibglsnewdualindexabbreviation}}[7]\marg{\comment{} |
| 21409 |
\cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\comment{} |
| 21410 |
\field{name}=\marg{\cs{protect}\gls{bibglsuseabbrvfont}\marg{\idx{param}4}\marg{\cs{glscategory}\marg{\idx{param}2}}},\comment{} |
| 21411 |
\field{category}=\marg{index},\idx{param}3}\marg{}\comment{} |
| 21412 |
} |
| 21413 |
\end{codeenv} |
| 21414 |
In this case \meta{dual-label} is the \gls{dualentry}['s] label, which is used |
| 21415 |
to fetch the category label in \gls{bibglsuseabbrvfont}. (The |
| 21416 |
\field{category} field for the dual isn't used since a custom |
| 21417 |
definition of |
| 21418 |
\gls!{bibglsnewdualindexabbreviationsecondary} may override the |
| 21419 |
value known to \bibgls.) |
| 21420 |
|
| 21421 |
Note that (as shown above) with the default |
| 21422 |
\csopt[short]{abbreviation-name-fallback} the \field{name} uses: |
| 21423 |
\nosecformatdef{bibglsuseabbrvfont} |
| 21424 |
to format the name, which ensures that it uses the same font as the |
| 21425 |
short form for the \dual\ abbreviation. This will use |
| 21426 |
\ics{glsuseabbrvfont} if it's defined otherwise it will be defined |
| 21427 |
to replicate that command. If \csopt{abbreviation-name-fallback} is |
| 21428 |
set to some other field then the \field{name} uses: |
| 21429 |
\nosecformatdef{bibglsuselongfont} |
| 21430 |
instead, which ensures that it uses the same font as the |
| 21431 |
long form for the \dual\ abbreviation. |
| 21432 |
|
| 21433 |
\cssection{bibglsnewdualindexabbreviationsecondary} |
| 21434 |
|
| 21435 |
\formatdef{bibglsnewdualindexabbreviationsecondary} |
| 21436 |
This command is used to define \glsdisp{dualentry}{secondary} terms identified with the |
| 21437 |
\atentry{dualindexabbreviation} \gls{entrytype}. |
| 21438 |
The definition provided in the \ext{glstex} file is: |
| 21439 |
\begin{codeenv} |
| 21440 |
\cs{providecommand}\marg{\gls{bibglsnewdualindexabbreviationsecondary}}[6]\marg{\comment{} |
| 21441 |
\cs{ifstrempty}\marg{\idx{param}6}\comment{} |
| 21442 |
\marg{\gls{newabbreviation}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}4}\marg{\idx{param}5}}\comment{} |
| 21443 |
\marg{\gls{newabbreviation}\oarg{\idx{param}2,\field{description}=\marg{\idx{param}6}}\marg{\idx{param}1}\marg{\idx{param}4}\marg{\idx{param}5}}\comment{} |
| 21444 |
} |
| 21445 |
\end{codeenv} |
| 21446 |
This ensures that a missing or empty \field{description} doesn't |
| 21447 |
interfere with the abbreviation style. |
| 21448 |
|
| 21449 |
\cssection{bibglsnewdualabbreviationentry} |
| 21450 |
|
| 21451 |
\formatdef{bibglsnewdualabbreviationentry} |
| 21452 |
This command is used to define \primary\ terms identified with the |
| 21453 |
\atentry{dualabbreviationentry} type. The definition provided in the \ext{glstex} |
| 21454 |
file is: |
| 21455 |
\begin{codeenv} |
| 21456 |
\cs{providecommand}\marg{\gls{bibglsnewdualabbreviationentry}}[5]\marg{\comment{} |
| 21457 |
\gls{newabbreviation}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{} |
| 21458 |
} |
| 21459 |
\end{codeenv} |
| 21460 |
Note that this definition ignores the \meta{description} argument. |
| 21461 |
|
| 21462 |
\cssection{bibglsnewdualabbreviationentrysecondary} |
| 21463 |
|
| 21464 |
\formatdef{bibglsnewdualabbreviationentrysecondary} |
| 21465 |
This command is used to define \glsdisp{dualentry}{secondary} terms identified with the |
| 21466 |
\atentry{dualabbreviationentry} type. The definition provided in the \ext{glstex} |
| 21467 |
file is: |
| 21468 |
\begin{codeenv} |
| 21469 |
\cs{providecommand}\marg{\gls{bibglsnewdualabbreviationentrysecondary}}[5]\marg{\comment{} |
| 21470 |
\cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\idx{param}2}\marg{\idx{param}5}\comment{} |
| 21471 |
} |
| 21472 |
\end{codeenv} |
| 21473 |
Note that this definition ignores the \meta{short} and \meta{long} |
| 21474 |
arguments (which will typically be empty unless the default mappings |
| 21475 |
are changed). |
| 21476 |
|
| 21477 |
\cssection{bibglsnewdualentryabbreviation} |
| 21478 |
|
| 21479 |
\formatdef{bibglsnewdualentryabbreviation} |
| 21480 |
This command is used to define \primary\ terms identified with the |
| 21481 |
(now deprecated) \gls{entrytype} |
| 21482 |
\atentry{dualentryabbreviation}. The definition provided in the \ext{glstex} |
| 21483 |
file is: |
| 21484 |
\begin{codeenv} |
| 21485 |
\cs{providecommand}\marg{\gls{bibglsnewdualentryabbreviation}}[5]\marg{\comment{} |
| 21486 |
\gls{newabbreviation}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{} |
| 21487 |
} |
| 21488 |
\end{codeenv} |
| 21489 |
Note that this definition ignores the \meta{description} argument. |
| 21490 |
|
| 21491 |
\cssection{bibglsnewdualentryabbreviationsecondary} |
| 21492 |
|
| 21493 |
\formatdef{bibglsnewdualentryabbreviationsecondary} |
| 21494 |
This command is used to define \glsdisp{dualentry}{secondary} terms identified with the |
| 21495 |
(now deprecated) \gls{entrytype} |
| 21496 |
\atentry{dualentryabbreviation}. The definition provided in the \ext{glstex} |
| 21497 |
file is: |
| 21498 |
\begin{codeenv} |
| 21499 |
\cs{providecommand}\marg{\gls{bibglsnewdualentryabbreviationsecondary}}[5]\marg{\comment{} |
| 21500 |
\cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\idx{param}2}\marg{\idx{param}5}\comment{} |
| 21501 |
} |
| 21502 |
\end{codeenv} |
| 21503 |
Note that this definition ignores the \meta{short} and \meta{long} |
| 21504 |
arguments (which will typically be empty unless the default mappings |
| 21505 |
are changed). |
| 21506 |
|
| 21507 |
\cssection{bibglsnewdualsymbol} |
| 21508 |
|
| 21509 |
\formatdef{bibglsnewdualsymbol} |
| 21510 |
This command is used to define terms identified with the |
| 21511 |
\atentry{dualsymbol} type. The definition provided in the \ext{glstex} |
| 21512 |
file is: |
| 21513 |
\begin{codeenv} |
| 21514 |
\cs{providecommand}\marg{\gls{bibglsnewdualsymbol}}[4]\marg{\comment{} |
| 21515 |
\cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{sort}=\marg{\idx{param}1},\field{category}=\marg{symbol},\idx{param}2}\marg{\idx{param}4}} |
| 21516 |
\end{codeenv} |
| 21517 |
|
| 21518 |
\cssection{bibglsnewdualnumber} |
| 21519 |
|
| 21520 |
\formatdef{bibglsnewdualnumber} |
| 21521 |
This command is used to define terms identified with the |
| 21522 |
\atentry{dualnumber} type. The definition provided in the \ext{glstex} |
| 21523 |
file is: |
| 21524 |
\begin{codeenv} |
| 21525 |
\cs{providecommand}\marg{\gls{bibglsnewdualnumber}}[4]\marg{\comment{} |
| 21526 |
\cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{sort}=\marg{\idx{param}1},\field{category}=\marg{symbol},\idx{param}2}\marg{\idx{param}4}} |
| 21527 |
\end{codeenv} |
| 21528 |
|
| 21529 |
\cssection{bibglsnewdualabbreviation} |
| 21530 |
|
| 21531 |
\formatdef{bibglsnewdualabbreviation} |
| 21532 |
This command is used to define terms identified with the |
| 21533 |
\atentry{dualabbreviation} type where the \field{duallong} field |
| 21534 |
is swapped with the \field{long} field and the \field{dualshort} |
| 21535 |
field is swapped with the \field{short} field. The definition provided in the |
| 21536 |
\ext{glstex} file is: |
| 21537 |
\begin{codeenv} |
| 21538 |
\cs{providecommand}\marg{\gls{bibglsnewdualabbreviation}}[4]\marg{\comment{} |
| 21539 |
\gls{newabbreviation}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{} |
| 21540 |
} |
| 21541 |
\end{codeenv} |
| 21542 |
|
| 21543 |
\cssection{bibglsnewdualacronym} |
| 21544 |
|
| 21545 |
\formatdef{bibglsnewdualacronym} |
| 21546 |
This command is used to define terms identified with the |
| 21547 |
\atentry{dualacronym} type. The definition provided in the \ext{glstex} |
| 21548 |
file is: |
| 21549 |
\begin{codeenv} |
| 21550 |
\cs{providecommand}\marg{\gls{bibglsnewdualacronym}}[4]\marg{\comment{} |
| 21551 |
\gls{newacronym}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{} |
| 21552 |
} |
| 21553 |
\end{codeenv} |
| 21554 |
This works in much the same way as \gls{bibglsnewdualabbreviation}. |
| 21555 |
Remember that with the \styfmt{glossaries-extra} package \gls{newacronym} |
| 21556 |
is redefined to just use \gls{newabbreviation} with the default \field{type} |
| 21557 |
set to \ics{acronymtype} and the default \field{category} set to |
| 21558 |
\code{acronym}. |
| 21559 |
|
| 21560 |
\cssection{bibglsnewtertiaryindexabbreviationentry} |
| 21561 |
|
| 21562 |
\formatdef{bibglsnewtertiaryindexabbreviationentry} |
| 21563 |
This is used to define \primary\ terms identified with the |
| 21564 |
\atentry{tertiaryindexabbreviationentry} type. It's essentially |
| 21565 |
the same as \gls!{bibglsnewdualindexabbreviation}. |
| 21566 |
The definition provided in the \ext{glstex} file is: |
| 21567 |
\begin{codeenv} |
| 21568 |
\cs{providecommand}\marg{\gls{bibglsnewtertiaryindexabbreviationentry}}[7]\marg{\comment{} |
| 21569 |
\cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\comment{} |
| 21570 |
\field{name}=\marg{\cs{protect}\gls{bibglsuseabbrvfont}\marg{\idx{param}4}\marg{\cs{glscategory}\marg{\idx{param}2}}},\comment{} |
| 21571 |
\field{category}=\marg{index},\idx{param}3}{}\comment{} |
| 21572 |
} |
| 21573 |
\end{codeenv} |
| 21574 |
|
| 21575 |
\cssection{bibglsnewtertiaryindexabbreviationentrysecondary} |
| 21576 |
|
| 21577 |
\formatdef{bibglsnewtertiaryindexabbreviationentrysecondary} |
| 21578 |
This command is used to define both the |
| 21579 |
\glsdisp{secondaryentry}{secondary} and |
| 21580 |
\glsdisp{tertiaryentry}{tertiary} terms identified with the |
| 21581 |
\atentry{tertiaryindexabbreviationentry} type. The |
| 21582 |
\glsdisp{secondaryentry}{secondary} term is |
| 21583 |
an abbreviation and the \glsdisp{tertiaryentry}{tertiary} term is a regular entry. The |
| 21584 |
definition written to the \ext{glstex} file is: |
| 21585 |
\begin{codeenv} |
| 21586 |
\cs{providecommand}\marg{\gls{bibglsnewtertiaryindexabbreviationentrysecondary}}[8]\marg{\comment{} |
| 21587 |
\gls{newabbreviation}\oarg{\idx{param}3}\marg{\idx{param}1}\marg{\idx{param}6}\marg{\idx{param}7}\comment{} |
| 21588 |
\cs{longnewglossaryentry*}\marg{\idx{param}2}\comment{} |
| 21589 |
\marg{\field{name}=\marg{\cs{protect}\gls{bibglsuselongfont}\marg{\idx{param}7}\marg{\cs{glscategory}\marg{\idx{param}1}}},\idx{param}4}\comment{} |
| 21590 |
\marg{\idx{param}8}\comment{} |
| 21591 |
} |
| 21592 |
\end{codeenv} |
| 21593 |
The \meta{label} is the label for the |
| 21594 |
\glsdisp{secondaryentry}{secondary} (abbreviation) entry and |
| 21595 |
\meta{tertiary-label} is the label for the |
| 21596 |
\glsdisp{tertiaryentry}{tertiary} (regular) entry. The fifth |
| 21597 |
argument (\meta{primary name}) isn't used but is provided if |
| 21598 |
required for a custom redefinition. The \field{name} field for the |
| 21599 |
\glsdisp{tertiaryentry}{tertiary} is obtained from the \meta{long} |
| 21600 |
argument encapsulated by \gls{bibglsuselongfont} to format the name, |
| 21601 |
which ensures that it uses the same font as the long form for the |
| 21602 |
dual abbreviation. This will use \ics{glsuselongfont} if it's |
| 21603 |
defined otherwise it will be defined to replicate that command. |
| 21604 |
|
| 21605 |
\cssection{bibglsnewbibtexentry} |
| 21606 |
|
| 21607 |
\formatdef{bibglsnewbibtexentry} |
| 21608 |
This command is used to define the \glsdisp{mainentry}{main term} identified with |
| 21609 |
\atentry{bibtexentry}. |
| 21610 |
The definition written to the \ext{glstex} file is: |
| 21611 |
\begin{codeenv} |
| 21612 |
\cs{providecommand}\marg{\gls{bibglsnewbibtexentry}}[4]\marg{\comment{} |
| 21613 |
\cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{} |
| 21614 |
} |
| 21615 |
\end{codeenv} |
| 21616 |
|
| 21617 |
\cssection{bibglsnewcontributor} |
| 21618 |
|
| 21619 |
\formatdef{bibglsnewcontributor} |
| 21620 |
This command is used to define terms identified with |
| 21621 |
\atentry{contributor} (typically implicitly created through |
| 21622 |
\atentry{bibtexentry}). |
| 21623 |
The definition written to the \ext{glstex} file is: |
| 21624 |
\begin{codeenv} |
| 21625 |
\cs{providecommand}\marg{\gls{bibglsnewcontributor}}[4]\marg{\comment{} |
| 21626 |
\cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{} |
| 21627 |
} |
| 21628 |
\end{codeenv} |
| 21629 |
|
| 21630 |
\cssection{bibglsnewprogenitor} |
| 21631 |
|
| 21632 |
\formatdef{bibglsnewprogenitor} |
| 21633 |
This command is used to define the \glsdisp{mainentry}{main terms} created by |
| 21634 |
\atentry{progenitor}. The definition is written to the \ext{glstex} |
| 21635 |
file as: |
| 21636 |
\begin{codeenv} |
| 21637 |
\cs{providecommand}\marg{\gls{bibglsnewprogenitor}}[4]\marg{\comment{} |
| 21638 |
\cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{} |
| 21639 |
} |
| 21640 |
\end{codeenv} |
| 21641 |
|
| 21642 |
\cssection{bibglsnewspawnindex} |
| 21643 |
|
| 21644 |
\formatdef{bibglsnewspawnindex} |
| 21645 |
This command is used to define the \glsdisp{mainentry}{main terms} created by |
| 21646 |
\atentry{spawnindex}. The definition is written to the \ext{glstex} |
| 21647 |
file as: |
| 21648 |
\begin{codeenv} |
| 21649 |
\cs{providecommand}\marg{\gls{bibglsnewspawnindex}}[4]\marg{\comment{} |
| 21650 |
\cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{} |
| 21651 |
} |
| 21652 |
\end{codeenv} |
| 21653 |
|
| 21654 |
\cssection{bibglsnewspawnedindex} |
| 21655 |
|
| 21656 |
\formatdef{bibglsnewspawnedindex} |
| 21657 |
This command is used to define the \glsdisp{spawnedentry}{terms spawned} by |
| 21658 |
\atentry{progenitor} or \atentry{spawnindex}. The definition is written |
| 21659 |
to the \ext{glstex} file as: |
| 21660 |
\begin{codeenv} |
| 21661 |
\cs{providecommand}\marg{\gls{bibglsnewspawnedindex}}[2]\marg{\comment{} |
| 21662 |
\gls{newglossaryentry}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}1},\field{category}={index},\field{description}=\marg{},\idx{param}2}\comment{} |
| 21663 |
} |
| 21664 |
\end{codeenv} |
| 21665 |
|
| 21666 |
\cssection{bibglsnewspawnindexplural} |
| 21667 |
|
| 21668 |
\formatdef{bibglsnewspawnindexplural} |
| 21669 |
This command is used to define the \glsdisp{mainentry}{main terms} created by |
| 21670 |
\atentry{spawnindexplural}. The definition is written to the \ext{glstex} |
| 21671 |
file as: |
| 21672 |
\begin{codeenv} |
| 21673 |
\cs{providecommand}\marg{\gls{bibglsnewspawnindexplural}}[4]\marg{\comment{} |
| 21674 |
\cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{} |
| 21675 |
} |
| 21676 |
\end{codeenv} |
| 21677 |
|
| 21678 |
\cssection{bibglsnewspawnedindexplural} |
| 21679 |
|
| 21680 |
\formatdef{bibglsnewspawnedindexplural} |
| 21681 |
This command is used to define the \glsdisp{spawnedentry}{terms spawned} by |
| 21682 |
\atentry{spawnindexplural}. |
| 21683 |
The definition is written to the \ext{glstex} file as: |
| 21684 |
\begin{codeenv} |
| 21685 |
\cs{providecommand}\marg{\gls{bibglsnewspawnedindexplural}}[3]\marg{\comment{} |
| 21686 |
\gls{newglossaryentry}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{category}=\marg{indexplural},\field{description}=\marg{},\idx{param}2}\comment{} |
| 21687 |
} |
| 21688 |
\end{codeenv} |
| 21689 |
|
| 21690 |
\cssection{bibglsnewspawnentry} |
| 21691 |
|
| 21692 |
\formatdef{bibglsnewspawnentry} |
| 21693 |
This command is used to define the \glsdisp{mainentry}{main terms} created by |
| 21694 |
\atentry{spawnentry}. The definition is written to the \ext{glstex} |
| 21695 |
file as: |
| 21696 |
\begin{codeenv} |
| 21697 |
\cs{providecommand}\marg{\gls{bibglsnewspawnentry}}[4]\marg{\comment{} |
| 21698 |
\cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{} |
| 21699 |
} |
| 21700 |
\end{codeenv} |
| 21701 |
|
| 21702 |
\cssection{bibglsnewspawnedentry} |
| 21703 |
|
| 21704 |
\formatdef{bibglsnewspawnedentry} |
| 21705 |
This command is used to define the \glsdisp{spawnedentry}{terms spawned} by \atentry{spawnentry}. |
| 21706 |
The definition is written to the \ext{glstex} file as: |
| 21707 |
\begin{codeenv} |
| 21708 |
\cs{providecommand}\marg{\gls{bibglsnewspawnedentry}}[4]\marg{\comment{} |
| 21709 |
\cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{} |
| 21710 |
} |
| 21711 |
\end{codeenv} |
| 21712 |
|
| 21713 |
\cssection{bibglsnewspawnabbreviation} |
| 21714 |
|
| 21715 |
\formatdef{bibglsnewspawnabbreviation} |
| 21716 |
This command is used to define the \glsdisp{mainentry}{main terms} created by |
| 21717 |
\atentry{spawnabbreviation}. The definition is written to the \ext{glstex} |
| 21718 |
file as: |
| 21719 |
\begin{codeenv} |
| 21720 |
\cs{providecommand}\marg{\gls{bibglsnewspawnabbreviation}}[4]\marg{\comment{} |
| 21721 |
\gls{newabbreviation}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{} |
| 21722 |
} |
| 21723 |
\end{codeenv} |
| 21724 |
|
| 21725 |
\cssection{bibglsnewspawnedabbreviation} |
| 21726 |
|
| 21727 |
\formatdef{bibglsnewspawnedabbreviation} |
| 21728 |
This command is used to define the \glsdisp{spawnedentry}{terms spawned} by \atentry{spawnabbreviation}. |
| 21729 |
The definition is written to the \ext{glstex} file as: |
| 21730 |
\begin{codeenv} |
| 21731 |
\cs{providecommand}\marg{\gls{bibglsnewspawnedabbreviation}}[4]\marg{\comment{} |
| 21732 |
\gls{newabbreviation}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{} |
| 21733 |
} |
| 21734 |
\end{codeenv} |
| 21735 |
|
| 21736 |
\cssection{bibglsnewspawnacronym} |
| 21737 |
|
| 21738 |
\formatdef{bibglsnewspawnacronym} |
| 21739 |
This command is used to define the \glsdisp{mainentry}{main terms} created by |
| 21740 |
\atentry{spawnacronym}. The definition is written to the \ext{glstex} |
| 21741 |
file as: |
| 21742 |
\begin{codeenv} |
| 21743 |
\cs{providecommand}\marg{\gls{bibglsnewspawnacronym}}[4]\marg{\comment{} |
| 21744 |
\gls{newacronym}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{} |
| 21745 |
} |
| 21746 |
\end{codeenv} |
| 21747 |
|
| 21748 |
\cssection{bibglsnewspawnedacronym} |
| 21749 |
|
| 21750 |
\formatdef{bibglsnewspawnedacronym} |
| 21751 |
This command is used to define the \glsdisp{spawnedentry}{terms spawned} by \atentry{spawnacronym}. |
| 21752 |
The definition is written to the \ext{glstex} file as: |
| 21753 |
\begin{codeenv} |
| 21754 |
\cs{providecommand}\marg{\gls{bibglsnewspawnedacronym}}[4]\marg{\comment{} |
| 21755 |
\gls{newacronym}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{} |
| 21756 |
} |
| 21757 |
\end{codeenv} |
| 21758 |
|
| 21759 |
\cssection{bibglsnewspawnsymbol} |
| 21760 |
|
| 21761 |
\formatdef{bibglsnewspawnsymbol} |
| 21762 |
This command is used to define the \glsdisp{mainentry}{main terms} created by |
| 21763 |
\atentry{spawnsymbol}. The definition is written to the \ext{glstex} |
| 21764 |
file as: |
| 21765 |
\begin{codeenv} |
| 21766 |
\cs{providecommand}\marg{\gls{bibglsnewspawnsymbol}}[4]\marg{\comment{} |
| 21767 |
\cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{} |
| 21768 |
} |
| 21769 |
\end{codeenv} |
| 21770 |
|
| 21771 |
\cssection{bibglsnewspawnedsymbol} |
| 21772 |
|
| 21773 |
\formatdef{bibglsnewspawnedsymbol} |
| 21774 |
This command is used to define the \glsdisp{spawnedentry}{terms spawned} by \atentry{spawnsymbol}. |
| 21775 |
The definition is written to the \ext{glstex} file as: |
| 21776 |
\begin{codeenv} |
| 21777 |
\cs{providecommand}\marg{\gls{bibglsnewspawnedsymbol}}[4]\marg{\comment{} |
| 21778 |
\cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{sort}=\marg{\idx{param}1},\field{category}=\marg{spawnedsymbol},\idx{param}2}\marg{\idx{param}4}} |
| 21779 |
\end{codeenv} |
| 21780 |
|
| 21781 |
\cssection{bibglsnewspawnnumber} |
| 21782 |
|
| 21783 |
\formatdef{bibglsnewspawnnumber} |
| 21784 |
This command is used to define the \glsdisp{mainentry}{main terms} created by |
| 21785 |
\atentry{spawnnumber}. The definition is written to the \ext{glstex} |
| 21786 |
file as: |
| 21787 |
\begin{codeenv} |
| 21788 |
\cs{providecommand}\marg{\gls{bibglsnewspawnnumber}}[4]\marg{\comment{} |
| 21789 |
\cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{} |
| 21790 |
} |
| 21791 |
\end{codeenv} |
| 21792 |
|
| 21793 |
\cssection{bibglsnewspawnednumber} |
| 21794 |
|
| 21795 |
\formatdef{bibglsnewspawnednumber} |
| 21796 |
This command is used to define the \glsdisp{spawnedentry}{terms spawned} by \atentry{spawnnumber}. |
| 21797 |
The definition is written to the \ext{glstex} file as: |
| 21798 |
\begin{codeenv} |
| 21799 |
\cs{providecommand}\marg{\gls{bibglsnewspawnednumber}}[4]\marg{\comment{} |
| 21800 |
\cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{sort}=\marg{\idx{param}1},\field{category}=\marg{spawnednumber},\idx{param}2}\marg{\idx{param}4}} |
| 21801 |
\end{codeenv} |
| 21802 |
|
| 21803 |
\cssection{bibglsnewspawndualindexentry} |
| 21804 |
|
| 21805 |
\formatdef{bibglsnewspawndualindexentry} |
| 21806 |
This command is used to define the \gls{progenitor}['s] \primary\ term created by |
| 21807 |
\atentry{spawndualindexentry}. |
| 21808 |
The definition is written to the \ext{glstex} file as: |
| 21809 |
\begin{codeenv} |
| 21810 |
\cs{providecommand}\marg{\gls{bibglsnewspawndualindexentry}}[4]\marg{\comment{} |
| 21811 |
\cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{category}=\marg{index},\idx{param}2}{}\comment{} |
| 21812 |
} |
| 21813 |
\end{codeenv} |
| 21814 |
The \meta{description} argument is ignored. |
| 21815 |
|
| 21816 |
\cssection{bibglsnewspawndualindexentrysecondary} |
| 21817 |
|
| 21818 |
\formatdef{bibglsnewspawndualindexentrysecondary} |
| 21819 |
This command is used to define the \gls{progenitor}['s] |
| 21820 |
\glsdisp{dualentry}{secondary} (dual) term created by |
| 21821 |
\atentry{spawndualindexentry}. |
| 21822 |
The definition is written to the \ext{glstex} file as: |
| 21823 |
\begin{codeenv} |
| 21824 |
\cs{providecommand}\marg{\gls{bibglsnewspawndualindexentrysecondary}}[4]\marg{\comment{} |
| 21825 |
\cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{} |
| 21826 |
} |
| 21827 |
\end{codeenv} |
| 21828 |
|
| 21829 |
\section{Compound Entry Sets} |
| 21830 |
\label{sec:compounddefs} |
| 21831 |
|
| 21832 |
\cssection{bibglsdefcompoundset} |
| 21833 |
|
| 21834 |
\formatdef{bibglsdefcompoundset} |
| 21835 |
|
| 21836 |
The default definition uses \ics{multiglossaryentry}. |
| 21837 |
|
| 21838 |
\section{Location Lists and Cross-References} |
| 21839 |
\label{sec:loclistdefs} |
| 21840 |
|
| 21841 |
These commands deal with the way the \iglspl{locationlist} and |
| 21842 |
cross references are formatted. The commands typically aren't used until |
| 21843 |
the entry information is displayed in the glossary, so you may |
| 21844 |
redefine these commands after the resource file has been loaded. |
| 21845 |
|
| 21846 |
\cssection{bibglsseesep} |
| 21847 |
|
| 21848 |
\formatdef{bibglsseesep} |
| 21849 |
Any entries that provide a \field{see} field (and that field hasn't |
| 21850 |
be omitted from the \gls{locationlist} with \csopt[omit]{see}) will |
| 21851 |
have \gls{bibglsseesep} inserted between the \field{see} part and the |
| 21852 |
\gls{locationlist} (unless there are no \glspl{location}, in which case just |
| 21853 |
the \field{see} part is displayed without \gls{bibglsseesep}). |
| 21854 |
|
| 21855 |
This command is provided with: |
| 21856 |
\begin{codeenv} |
| 21857 |
\cs{providecommand}\marg{\gls{bibglsseesep}}\marg{, } |
| 21858 |
\end{codeenv} |
| 21859 |
You can define this before you load the \ext{bib} file: |
| 21860 |
\begin{codeenv} |
| 21861 |
\cs{newcommand}\marg{\gls{bibglsseesep}}\marg{; } |
| 21862 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}} |
| 21863 |
\end{codeenv} |
| 21864 |
Or you can redefine it afterwards: |
| 21865 |
\begin{codeenv} |
| 21866 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}} |
| 21867 |
\cs{glsrenewcommand}\marg{\gls{bibglsseesep}}\marg{; } |
| 21868 |
\end{codeenv} |
| 21869 |
|
| 21870 |
\cssection{bibglsseealsosep} |
| 21871 |
|
| 21872 |
\formatdef{bibglsseealsosep} |
| 21873 |
This is like \gls{bibglsseesep} but is used with cross-reference |
| 21874 |
lists provided with the \field{seealso} field, if supported. |
| 21875 |
|
| 21876 |
\cssection{bibglsaliassep} |
| 21877 |
|
| 21878 |
\formatdef{bibglsaliassep} |
| 21879 |
This is like \gls{bibglsseesep} but is used with cross-reference |
| 21880 |
lists provided with the \field{alias} field. |
| 21881 |
|
| 21882 |
\cssection{bibglsusesee} |
| 21883 |
|
| 21884 |
\formatdef{bibglsusesee} |
| 21885 |
Displays the formatted cross-reference list stored in the |
| 21886 |
\field{see} field for the given entry. This just defaults to |
| 21887 |
\ics{glsxtrusesee}\margm{label}. |
| 21888 |
|
| 21889 |
\cssection{bibglsuseseealso} |
| 21890 |
|
| 21891 |
\formatdef{bibglsuseseealso} |
| 21892 |
Displays the formatted cross-reference list stored in the |
| 21893 |
\field{seealso} field for the given entry. This just defaults to |
| 21894 |
\ics{glsxtruseseealso}\margm{label}. |
| 21895 |
|
| 21896 |
\cssection{bibglsusealias} |
| 21897 |
|
| 21898 |
\formatdef{bibglsusealias} |
| 21899 |
Displays the formatted cross-reference stored in the |
| 21900 |
\field{alias} field for the given entry. This is defined to use |
| 21901 |
\ics{glsseeformat}. |
| 21902 |
|
| 21903 |
\cssection{bibglsdelimN} |
| 21904 |
|
| 21905 |
\formatdef{bibglsdelimN} |
| 21906 |
Separator between individual \glspl{location}, except for the last. |
| 21907 |
This defaults to \ics{delimN}. |
| 21908 |
|
| 21909 |
\cssection{bibglslastDelimN} |
| 21910 |
|
| 21911 |
\formatdef{bibglslastDelimN} |
| 21912 |
Separator between penultimate and final individual \glspl{location}. |
| 21913 |
This defaults to \code{,\idx{nbspchar}} to discourage lonely \glspl{location}. |
| 21914 |
|
| 21915 |
\cssection{bibglscompact} |
| 21916 |
|
| 21917 |
\formatdef{bibglscompact} |
| 21918 |
This command is used with \csopt{compact-ranges} when the end |
| 21919 |
\gls{location} in a \idx{range} is compacted. |
| 21920 |
The first argument \meta{pattern} indicates the \gls{location} pattern: |
| 21921 |
\code{digit} for digits, \code{roman} for \idx!{lowercase} |
| 21922 |
Roman numerals, \code{ROMAN} for \idx!{uppercase} Roman |
| 21923 |
numerals and \code{alpha} for alphabetical \glspl{location}. The actual |
| 21924 |
\gls{location} is split into two parts, \meta{part1} and \meta{part2}. |
| 21925 |
The string concatenation \meta{part1}\meta{part2} forms the |
| 21926 |
actual \gls{location}. |
| 21927 |
|
| 21928 |
This just does \meta{part2} by default. |
| 21929 |
|
| 21930 |
\cssection{bibglspassim} |
| 21931 |
|
| 21932 |
\formatdef{bibglspassim} |
| 21933 |
If \csopt{max-loc-diff} is greater than~1, then any |
| 21934 |
\idxpl{implicit-range} that have skipped over gaps will be followed |
| 21935 |
by \gls{bibglspassim}, which is defined as: |
| 21936 |
\begin{codeenv} |
| 21937 |
\cs{providecommand}\marg{\gls{bibglspassim}}\marg{ \gls{bibglspassimname}} |
| 21938 |
\end{codeenv} |
| 21939 |
You can define this before you load the \ext{bib} file: |
| 21940 |
\begin{codeenv} |
| 21941 |
\cs{newcommand}\marg{\gls{bibglspassim}}\marg{} |
| 21942 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}} |
| 21943 |
\end{codeenv} |
| 21944 |
Or you can redefine it afterwards: |
| 21945 |
\begin{codeenv} |
| 21946 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}} |
| 21947 |
\cs{glsrenewcommand}\marg{\gls{bibglspassim}}\marg{} |
| 21948 |
\end{codeenv} |
| 21949 |
|
| 21950 |
\cssection{bibglspassimname} |
| 21951 |
|
| 21952 |
\formatdef{bibglspassimname} |
| 21953 |
The default definition is obtained from the \langxml. For example, with |
| 21954 |
\file{bib2gls-en.xml} the provided definition is: |
| 21955 |
\begin{codeenv} |
| 21956 |
\cs{providecommand}\marg{\gls{bibglspassimname}}\marg{passim} |
| 21957 |
\end{codeenv} |
| 21958 |
|
| 21959 |
\cssection{bibglsrange} |
| 21960 |
|
| 21961 |
\formatdef{bibglsrange} |
| 21962 |
\Idxpl{explicit-range} formed using \glsopt[\idx{openrange}]{format} and |
| 21963 |
\glsopt[\idx{closerange}]{format} or \glsopt[\idx{openrange}\meta{csname}]{format} and |
| 21964 |
\glsopt[\idx{closerange}\meta{csname}]{format} (where \meta{csname} matches and is a |
| 21965 |
text-block command without the initial backslash) in the optional |
| 21966 |
argument of commands like \ics{gls} or \ics{glsadd} are encapsulated within |
| 21967 |
the argument of \gls{bibglsrange}. By default, this simply does its |
| 21968 |
argument. This command is not used with \idxpl{implicit-range} that |
| 21969 |
are formed by collating consecutive \glspl{location} or when |
| 21970 |
\csopt[true]{merge-ranges} is used. |
| 21971 |
|
| 21972 |
\cssection{bibglsinterloper} |
| 21973 |
|
| 21974 |
\formatdef{bibglsinterloper} |
| 21975 |
If an \idxpl{explicit-range} conflicts with a record, a warning will be |
| 21976 |
issued and the conflicting record (the \idx{interloper}) will be shifted to the front |
| 21977 |
of the \idx{range} inside the argument of \gls{bibglsinterloper}. |
| 21978 |
The default definition just does \meta{location}\gls!{bibglsdelimN} |
| 21979 |
so that it fits neatly into the list. |
| 21980 |
|
| 21981 |
For example, suppose on page~4 of my document I start a \idx{range} with: |
| 21982 |
\begin{codeenv*} |
| 21983 |
\cs{glsadd}\oarg{\glsaddopt[\idx{openrange}]{format}}\marg{sample} |
| 21984 |
\end{codeenv*} |
| 21985 |
and end it on page~9 with: |
| 21986 |
\begin{codeenv*} |
| 21987 |
\cs{glsadd}\oarg{\glsaddopt[\idx{closerange}]{format}}\marg{sample} |
| 21988 |
\end{codeenv*} |
| 21989 |
This forms an \idx{explicit-range}, but let's suppose on page~6 I |
| 21990 |
have: |
| 21991 |
\begin{codeenv} |
| 21992 |
\cs{gls}\oarg{\glsopt[\encap{hyperbf}]{format}}\marg{sample} |
| 21993 |
\end{codeenv} |
| 21994 |
This record conflicts with the \idx{explicit-range} (which doesn't include |
| 21995 |
\encap{hyperbf} in the format). This causes a warning and |
| 21996 |
the conflicting entry will be moved before the start of the |
| 21997 |
\idx{explicit-range} resulting in \textbf{6}, 4--9. |
| 21998 |
|
| 21999 |
Note that \idxpl{implicit-range} can't be formed from \idxpl{interloper} (nor can |
| 22000 |
\idxpl{implicit-range} be merged with explicit ones with the default |
| 22001 |
\csopt[false]{merge-ranges}), |
| 22002 |
so if \code{\cs{gls}\oarg{\glsopt[\encap{hyperbf}]{format}}\marg{sample}} |
| 22003 |
also occurs on pages~7 and~8 then the result will be \textbf{6}, \textbf{7}, |
| 22004 |
\textbf{8}, 4--9. Either remove the \idx{explicit-range} or |
| 22005 |
remove the conflicting entries. (Alternatively, redefine |
| 22006 |
\gls{bibglsinterloper} to ignore its argument, which will |
| 22007 |
discard the conflicting entries.) |
| 22008 |
|
| 22009 |
\cssection{bibglspostlocprefix} |
| 22010 |
|
| 22011 |
\formatdef{bibglspostlocprefix} |
| 22012 |
If the \csopt{loc-prefix} option is on, \gls!{bibglslocprefix} will |
| 22013 |
be inserted at the start of \glspl{locationlist}, and its default |
| 22014 |
definition includes \gls{bibglspostlocprefix} |
| 22015 |
placed after the prefix text. This command is provided with: |
| 22016 |
\begin{codeenv} |
| 22017 |
\cs{providecommand}\marg{\gls{bibglspostlocprefix}}\marg{\cs{cs.space}} |
| 22018 |
\end{codeenv} |
| 22019 |
which puts a space between the prefix text and the \gls{locationlist}. |
| 22020 |
You can define this before you load the \ext{bib} file: |
| 22021 |
\begin{codeenv} |
| 22022 |
\cs{newcommand}\marg{\gls{bibglspostlocprefix}}\marg{: } |
| 22023 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt{loc-prefix}} |
| 22024 |
\end{codeenv} |
| 22025 |
Or you can redefine it afterwards: |
| 22026 |
\begin{codeenv} |
| 22027 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt{loc-prefix}} |
| 22028 |
\cs{glsrenewcommand}\marg{\gls{bibglspostlocprefix}}\marg{: } |
| 22029 |
\end{codeenv} |
| 22030 |
|
| 22031 |
\cssection{bibglslocprefix} |
| 22032 |
|
| 22033 |
\formatdef{bibglslocprefix} |
| 22034 |
If the \csopt{loc-prefix} option is on, this command will be |
| 22035 |
provided. The location of the definition is determined by the |
| 22036 |
\csopt{loc-prefix-def} option. For example, if the document has: |
| 22037 |
\begin{codeenv} |
| 22038 |
\gls{GlsXtrLoadResources}\oarg{\csopt[main]{type},\csopt[individual]{loc-prefix-def},\csopt[p.,pp.]{loc-prefix},\csopt[entries]{src}} |
| 22039 |
\end{codeenv} |
| 22040 |
then the following will be added to the \ext{glstex} file: |
| 22041 |
\begin{codeenv} |
| 22042 |
\cs{apptoglossarypreamble}\oarg{main}\marg{\comment{} |
| 22043 |
\cs{providecommand}\marg{\gls{bibglslocprefix}}[1]\marg{\comment{} |
| 22044 |
\cs{ifcase}\idx{param}\idx{param}1 |
| 22045 |
\cmd{or} p.\gls{bibglspostlocprefix} |
| 22046 |
\cmd{else} pp.\gls{bibglspostlocprefix} |
| 22047 |
\cmd{fi} |
| 22048 |
}\comment{} |
| 22049 |
} |
| 22050 |
\end{codeenv} |
| 22051 |
However, if the \csopt{type} key is missing or if the option |
| 22052 |
\csopt[local]{loc-prefix-def} is used, then the following will |
| 22053 |
be added instead: |
| 22054 |
\begin{codeenv} |
| 22055 |
\cs{appto}\cs{glossarypreamble}\marg{\comment{} |
| 22056 |
\cs{providecommand}\marg{\gls{bibglslocprefix}}[1]\marg{\comment{} |
| 22057 |
\cs{ifcase}\idx{param}1 |
| 22058 |
\cmd{or} p.\gls{bibglspostlocprefix} |
| 22059 |
\cmd{else} pp.\gls{bibglspostlocprefix} |
| 22060 |
\cmd{fi} |
| 22061 |
}\comment{} |
| 22062 |
} |
| 22063 |
\end{codeenv} |
| 22064 |
If \csopt[global]{loc-prefix-def} is used then the definition is |
| 22065 |
global (outside of the glossary preamble). |
| 22066 |
|
| 22067 |
\cssection{bibglspagename} |
| 22068 |
|
| 22069 |
\formatdef{bibglspagename} |
| 22070 |
If \csopt[true]{loc-prefix} is used, then this command is provided |
| 22071 |
using the value of \idx{tag.page} from the \langxml. For example with \file{bib2gls-en.xml} the definition is: |
| 22072 |
\begin{codeenv} |
| 22073 |
\cs{providecommand}\marg{\gls{bibglspagename}}\marg{Page} |
| 22074 |
\end{codeenv} |
| 22075 |
|
| 22076 |
\cssection{bibglspagesname} |
| 22077 |
|
| 22078 |
\formatdef{bibglspagesname} |
| 22079 |
If \csopt[true]{loc-prefix} is used, then this command is provided |
| 22080 |
using the value of \idx{tag.pages} from the \langxml. For example with \file{bib2gls-en.xml} the definition is: |
| 22081 |
\begin{codeenv} |
| 22082 |
\cs{providecommand}\marg{\gls{bibglspagesname}}\marg{Pages} |
| 22083 |
\end{codeenv} |
| 22084 |
|
| 22085 |
\cssection{bibglslocsuffix} |
| 22086 |
|
| 22087 |
\formatdef{bibglslocsuffix} |
| 22088 |
If the \csopt{loc-suffix} option is on, this command will be |
| 22089 |
provided. The location of the definition depends on the |
| 22090 |
\csopt{loc-suffix-def} option. |
| 22091 |
|
| 22092 |
This command's definition depends on the value provided by |
| 22093 |
\csopt{loc-suffix}. For example, with |
| 22094 |
\csopt[\ics{at}{\idx{periodchar}}]{loc-suffix} |
| 22095 |
the command is defined as: |
| 22096 |
\begin{codeenv} |
| 22097 |
\cs{providecommand}\marg{\gls{bibglslocsuffix}}[1]\marg{\ics{at}.} |
| 22098 |
\end{codeenv} |
| 22099 |
(which ignores the argument). |
| 22100 |
|
| 22101 |
Whereas with \csopt[\meta{A}\dcomma\meta{B}\dcomma\meta{C}]{loc-suffix} |
| 22102 |
the command is defined as: |
| 22103 |
\begin{codeenv} |
| 22104 |
\cs{providecommand}\marg{\gls{bibglslocsuffix}}[1]\marg{\cs{ifcase}\idx{param}1 \meta{A}\cmd{or} \meta{B}\cmd{else} \meta{C}\cmd{fi}} |
| 22105 |
\end{codeenv} |
| 22106 |
|
| 22107 |
Note that this is slightly different from \gls{bibglslocprefix} as |
| 22108 |
it includes the 0 case, which in this instance means that there were |
| 22109 |
no \glspl{location} but there was a cross-reference. This command isn't |
| 22110 |
added when the \gls{locationlist} is empty. |
| 22111 |
|
| 22112 |
\cssection{bibglslocationgroup} |
| 22113 |
|
| 22114 |
\formatdef{bibglslocationgroup} |
| 22115 |
When the \csopt{loc-counters} option is used, the \glspl{location} |
| 22116 |
for each entry are grouped together according to the counter |
| 22117 |
(in the order specified in the value of \csopt{loc-counters}). |
| 22118 |
Each group of \glspl{location} is encapsulated within |
| 22119 |
\gls{bibglslocationgroup}, where \meta{n} is the number |
| 22120 |
of \glspl{location} within the group, \meta{counter} is the |
| 22121 |
counter name and \meta{list} is the formatted \gls{location} sub-list. |
| 22122 |
By default, this simply does \meta{list}, but may be |
| 22123 |
defined (before the resources are loaded) or redefined |
| 22124 |
(after the resources are loaded) as required. |
| 22125 |
|
| 22126 |
For example: |
| 22127 |
\begin{codeenv} |
| 22128 |
\cs{newcommand}*\marg{\gls{bibglslocationgroup}}[3]\marg{\comment{} |
| 22129 |
\cs{ifnum}\idx{param}1=1 |
| 22130 |
\idx{param}2: |
| 22131 |
\cmd{else} |
| 22132 |
\idx{param}2s: |
| 22133 |
\cmd{fi} |
| 22134 |
\idx{param}3\comment{} |
| 22135 |
} |
| 22136 |
\strut |
| 22137 |
\gls{GlsXtrLoadResources}\oarg{ |
| 22138 |
\csopt[equation,page]{loc-counters},\comment{group locations by counter} |
| 22139 |
\csopt[entries]{src}\comment{data in entries.bib} |
| 22140 |
} |
| 22141 |
\end{codeenv} |
| 22142 |
This will prefix each group with the counter name, if there's |
| 22143 |
only one \gls{location}, or the counter name followed by \qt{s}, |
| 22144 |
if there are multiple \glspl{location} within the group. |
| 22145 |
|
| 22146 |
There are various ways to adapt this to translate the counter |
| 22147 |
name to a different textual label, such as: |
| 22148 |
\begin{codeenv} |
| 22149 |
\cs{providecommand}\marg{\cmd{pagename}}\marg{Page} |
| 22150 |
\cs{providecommand}\marg{\cmd{pagesname}}\marg{Pages} |
| 22151 |
\cs{providecommand}\marg{\cmd{equationname}}\marg{Equation} |
| 22152 |
\cs{providecommand}\marg{\cmd{equationsname}}\marg{Equations} |
| 22153 |
\strut |
| 22154 |
\cs{newcommand}*\marg{\gls{bibglslocationgroup}}[3]\marg{\comment{} |
| 22155 |
\ics{ifnum}\idx{param}1=1 |
| 22156 |
\ics{ifcsdef}\marg{\idx{param}2name}\marg{\cs{csuse}\marg{\idx{param}2name}}\marg{\idx{param}2}: |
| 22157 |
\cmd{else} |
| 22158 |
\cs{ifcsdef}\marg{\idx{param}2sname}\marg{\cs{csuse}\marg{\idx{param}2sname}}\marg{\idx{param}2s}: |
| 22159 |
\cmd{fi} |
| 22160 |
\idx{param}3\comment{} |
| 22161 |
} |
| 22162 |
\end{codeenv} |
| 22163 |
|
| 22164 |
\cssection{bibglslocationgroupsep} |
| 22165 |
|
| 22166 |
\formatdef{bibglslocationgroupsep} |
| 22167 |
When the \csopt{loc-counters} option is set, this command |
| 22168 |
is used to separate each \gls{location} sub-group. It may be defined |
| 22169 |
before the resources are loaded: |
| 22170 |
\begin{codeenv} |
| 22171 |
\cs{newcommand}*\marg{\gls{bibglslocationgroupsep}}\marg{; } |
| 22172 |
\strut |
| 22173 |
\gls{GlsXtrLoadResources}\oarg{ |
| 22174 |
\csopt[equation,page]{loc-counters},\comment{group locations by counter} |
| 22175 |
\csopt[entries]{src}\comment{data in entries.bib} |
| 22176 |
} |
| 22177 |
\end{codeenv} |
| 22178 |
or redefined after the resources are loaded: |
| 22179 |
\begin{codeenv} |
| 22180 |
\gls{GlsXtrLoadResources}\oarg{ |
| 22181 |
\csopt[equation,page]{loc-counters},\comment{group locations by counter} |
| 22182 |
\csopt[entries]{src}\comment{data in entries.bib} |
| 22183 |
} |
| 22184 |
\strut |
| 22185 |
\cs{glsrenewcommand}*\marg{\gls{bibglslocationgroupsep}}\marg{; } |
| 22186 |
\end{codeenv} |
| 22187 |
|
| 22188 |
\cssection{bibglsprimary} |
| 22189 |
|
| 22190 |
\formatdef{bibglsprimary} |
| 22191 |
When the \csopt{save-principal-locations} option is used, the |
| 22192 |
\glspl{principallocation} are stored in the \field{primarylocations} field |
| 22193 |
encapsulated with this command, unless the locations are split into |
| 22194 |
groups according to the location counter. |
| 22195 |
|
| 22196 |
The first argument is the number of \glspl{location} in the list. |
| 22197 |
The second argument is the list of \glspl{location} formatted in the |
| 22198 |
usual way. The default definition is to ignore the first argument |
| 22199 |
and simply do the second. |
| 22200 |
|
| 22201 |
If the locations are split into groups, then \gls{bibglsprimarylocationgroup} |
| 22202 |
is used for each group instead (separated with |
| 22203 |
\gls{bibglsprimarylocationgroupsep}). |
| 22204 |
|
| 22205 |
\cssection{bibglsprimarylocationgroup} |
| 22206 |
|
| 22207 |
\formatdef{bibglsprimarylocationgroup} |
| 22208 |
As \gls{bibglslocationgroup} but for primary group |
| 22209 |
locations. |
| 22210 |
|
| 22211 |
\cssection{bibglsprimarylocationgroupsep} |
| 22212 |
|
| 22213 |
\formatdef{bibglsprimarylocationgroupsep} |
| 22214 |
As \gls{bibglslocationgroupsep} but for primary group locations. |
| 22215 |
|
| 22216 |
\cssection{bibglssupplemental} |
| 22217 |
|
| 22218 |
\formatdef{bibglssupplemental} |
| 22219 |
When the \csopt{supplemental-locations} option is used, the |
| 22220 |
\glspl{location} from a \supplementarydocument\ are encapsulated |
| 22221 |
within the \meta{list} part of \gls{bibglssupplemental}. The first |
| 22222 |
argument \meta{n} (ignored by default) is the number of |
| 22223 |
\supplementarylocations. |
| 22224 |
|
| 22225 |
If multiple \supplemental\ sources are permitted (that is, |
| 22226 |
\bibgls\ has detected that the document is using at least |
| 22227 |
version 1.36 of \sty{glossaries-extra}), then the \meta{list} |
| 22228 |
part will consist of sub-lists for each external source. In this |
| 22229 |
case, \meta{n} will be the total number of elements across |
| 22230 |
all the sub-lists. |
| 22231 |
|
| 22232 |
\cssection{bibglssupplementalsublist} |
| 22233 |
|
| 22234 |
\formatdef{bibglssupplementalsublist} |
| 22235 |
If multiple \supplemental\ sources are permitted, this will be used |
| 22236 |
to format each sub-list, where \meta{n} (ignored by default) |
| 22237 |
is the number of elements in the sub-list, \meta{external document} |
| 22238 |
(ignored by default) is the external source and \meta{list} |
| 22239 |
is the list of \supplementarylocations\ in \meta{external document}. |
| 22240 |
|
| 22241 |
\cssection{bibglssupplementalsep} |
| 22242 |
|
| 22243 |
\formatdef{bibglssupplementalsep} |
| 22244 |
The separator between the main \gls{locationlist} and the supplementary |
| 22245 |
\gls{locationlist}. By default this is just \gls!{bibglsdelimN}. This may be |
| 22246 |
defined before the resources are loaded: |
| 22247 |
\begin{codeenv} |
| 22248 |
\cs{newcommand}\marg{\gls{bibglssupplementalsep}}\marg{; } |
| 22249 |
\strut |
| 22250 |
\gls{GlsXtrLoadResources}\oarg{ |
| 22251 |
\csopt[supplDoc]{supplemental-locations}, |
| 22252 |
\csopt[entries]{src}} |
| 22253 |
\end{codeenv} |
| 22254 |
or redefined after the resources are loaded: |
| 22255 |
\begin{codeenv} |
| 22256 |
\gls{GlsXtrLoadResources}\oarg{ |
| 22257 |
\csopt[supplDoc]{supplemental-locations}, |
| 22258 |
\csopt[entries]{src}} |
| 22259 |
\strut |
| 22260 |
\cs{glsrenewcommand}\marg{\gls{bibglssupplementalsep}}\marg{; } |
| 22261 |
\end{codeenv} |
| 22262 |
|
| 22263 |
\cssection{bibglssupplementalsubsep} |
| 22264 |
|
| 22265 |
\formatdef{bibglssupplementalsubsep} |
| 22266 |
The separator between the supplementary |
| 22267 |
\gls{location} sub-lists. By default this is just \gls!{bibglsdelimN}. |
| 22268 |
|
| 22269 |
\cssection{bibglshrefchar} |
| 22270 |
|
| 22271 |
\formatdef{bibglshrefchar} |
| 22272 |
Expands to a literal percent character followed by \meta{hex}. The |
| 22273 |
second argument is ignored. |
| 22274 |
|
| 22275 |
\cssection{bibglshrefunicode} |
| 22276 |
|
| 22277 |
\formatdef{bibglshrefunicode} |
| 22278 |
Expands to the second argument. The first argument is ignored. |
| 22279 |
|
| 22280 |
\cssection{bibglshexunicodechar} |
| 22281 |
|
| 22282 |
\formatdef{bibglshexunicodechar} |
| 22283 |
This command is used by the \csopt{hex-unicode-fields} option when |
| 22284 |
replacing any Unicode characters. The argument \meta{hex} is the hexadecimal |
| 22285 |
character code. Note that the argument isn't preceded by the double-quote |
| 22286 |
character~\idx{doublequotecharhex} (which is normally used to |
| 22287 |
identify hexadecimal numbers in \LaTeX). Instead, the definition |
| 22288 |
needs to insert this character, if appropriate. |
| 22289 |
|
| 22290 |
If \bibgls\ has detected that the \sty{hyperref} package has been |
| 22291 |
loaded, it will provide a definition that may be used in PDF |
| 22292 |
bookmarks provided that \sty{hyperref}'s \styoptfmt{unicode} option is |
| 22293 |
set. Otherwise the command will simply do |
| 22294 |
\code{\ics{cs.symbol}\marg{\idx{doublequotecharhex}\meta{hex}}} |
| 22295 |
(which will require an appropriate font in order to render the |
| 22296 |
symbol correctly). |
| 22297 |
|
| 22298 |
\section{Letter Groups} |
| 22299 |
\label{sec:lettergroupdefs} |
| 22300 |
|
| 22301 |
The commands listed in this section are provided for use with the |
| 22302 |
\longarg{group} switch and glossary styles that display the letter |
| 22303 |
group title. If these need their definitions altered, they should |
| 22304 |
be defined before the resource file is loaded if field expansion |
| 22305 |
is on (\longarg{expand-fields}) otherwise they may be redefined |
| 22306 |
afterwards. |
| 22307 |
|
| 22308 |
The base \isty{glossaries} package determines group titles through a fairly |
| 22309 |
simplistic rule. Both \idx!{makeindex} and \idx!{xindy} write the |
| 22310 |
line: |
| 22311 |
\nosecformatdef{glsgroupheading} |
| 22312 |
to the associated glossary file at the start of each new letter group. |
| 22313 |
For example, the \qt{A} letter group will be written as: |
| 22314 |
\begin{codeenv} |
| 22315 |
\gls{glsgroupheading}\marg{A} |
| 22316 |
\end{codeenv} |
| 22317 |
This is quite straightforward and the heading title can just be |
| 22318 |
\qt{A}. The \qt{Symbols} group is written as: |
| 22319 |
\begin{codeenv} |
| 22320 |
\gls{glsgroupheading}\marg{glssymbols} |
| 22321 |
\end{codeenv} |
| 22322 |
To allow for easy translation, the base \sty{glossaries} package has |
| 22323 |
the simple rule: |
| 22324 |
\begin{itemize} |
| 22325 |
\item if \csfmt{\meta{heading}groupname} exists use that; |
| 22326 |
\item otherwise just use \meta{heading}. |
| 22327 |
\end{itemize} |
| 22328 |
There's no \csfmt{Agroupname} provided, but \ics{glssymbolsgroupname} |
| 22329 |
is provided and is supported by the associated language modules, |
| 22330 |
such as \styfmt{glossaries-french}. (Similarly for the \qt{Numbers} |
| 22331 |
group.) |
| 22332 |
|
| 22333 |
The glossary styles that provide hyperlinks to the groups (such as |
| 22334 |
\glostyle{indexhypergroup}) use \meta{heading} to form the target |
| 22335 |
name. A problem arises when active characters occur in |
| 22336 |
\meta{heading}, which happens with extended characters and |
| 22337 |
\isty{inputenc}. |
| 22338 |
|
| 22339 |
The \sty{glossaries-extra} package (as from version 1.14) provides: |
| 22340 |
\nosecformatdef{glsxtrsetgrouptitle} |
| 22341 |
to set the title for a group with the given label. The internal |
| 22342 |
workings of \gls{glsgroupheading} are modified to use a slightly |
| 22343 |
altered rule: |
| 22344 |
\begin{itemize} |
| 22345 |
\item if a title has been set using |
| 22346 |
\gls{glsxtrsetgrouptitle}\margm{heading}\margm{title} for the given |
| 22347 |
\meta{heading}, use that; |
| 22348 |
\item if \csfmt{\meta{heading}groupname} exists, use that; |
| 22349 |
\item just use \meta{heading} for the title. |
| 22350 |
\end{itemize} |
| 22351 |
So if \gls{glsxtrsetgrouptitle} hasn't been used, it falls back on |
| 22352 |
the original rule. |
| 22353 |
|
| 22354 |
The problem is now how to make the indexing application use the |
| 22355 |
desired label in the argument of \gls{glsgroupheading} instead of selecting |
| 22356 |
the heading based on the first character of each sort value for each |
| 22357 |
\gls{top-levelentry} in that group. This can't be done with |
| 22358 |
\idx!{makeindex}, and with \idx!{xindy} it requires a custom language |
| 22359 |
module, which isn't a trivial task. |
| 22360 |
|
| 22361 |
With \bibgls, a different approach is used. The \iext{glstex} file |
| 22362 |
created isn't comparable to the \iext{gls} file created by |
| 22363 |
\idx!{makeindex} or \idx!{xindy}. There's nowhere for \bibgls\ to |
| 22364 |
write the \gls{glsgroupheading} line as it isn't creating the code |
| 22365 |
that typesets the glossary list. Instead it's creating the code that |
| 22366 |
defines the entries. The actual group heading is inserted by |
| 22367 |
\ics{printunsrtglossary} and it's only able to do this by checking if |
| 22368 |
the entry has a \field{group} field and comparing it to the previous |
| 22369 |
entry's \field{group} field. |
| 22370 |
|
| 22371 |
The behaviour of the group formation implemented by the sort |
| 22372 |
methods may be changed with \csopt{group-formation}. With any |
| 22373 |
setting other than \csopt[default]{group-formation}, the group label |
| 22374 |
is set to \format{bibglsunicodegroup} and the title is set to |
| 22375 |
\format{bibglsunicodegrouptitle} (see below) otherwise the label and |
| 22376 |
title are determined by the sort method. |
| 22377 |
|
| 22378 |
The collators used by the locale and letter-based rules save the |
| 22379 |
following information for each entry based on the first significant letter of |
| 22380 |
the \field{sort} field (if the letter is recognised as alphabetical, |
| 22381 |
according to the rule): |
| 22382 |
\begin{itemize} |
| 22383 |
\item \meta{title} The group's title. This is typically title-cased. |
| 22384 |
For example, if the rule recognises the digraph \qt{dz}, then the |
| 22385 |
title is \qt{Dz}. Exceptions to this are included in the \langxml. |
| 22386 |
If the key \idx{grouptitle.case.lc} exists, where |
| 22387 |
\meta{lc} is the \idx!{lowercase} version of \meta{title}, then the value |
| 22388 |
of that key is used instead. For example, the Dutch digraph \qt{ij} |
| 22389 |
should be converted to \qt{IJ}, so \file{bib2gls-en.xml} includes: |
| 22390 |
\begin{verbatim} |
| 22391 |
<entry key="grouptitle.case.ij">IJ</entry> |
| 22392 |
\end{verbatim} |
| 22393 |
(See the \longarg{group} switch for more details.) |
| 22394 |
\item \meta{letter} This is the actual letter at the start of the |
| 22395 |
given entry's \field{sort} field, which may be \idx!{lowercase} or may |
| 22396 |
contain diacritics that don't appear in \meta{title}. |
| 22397 |
\item \meta{id} A numeric identifier. This may be the collation key |
| 22398 |
or the code point for the given letter, depending on the sort |
| 22399 |
method. |
| 22400 |
\item \meta{type} The entry's glossary type. If not known, this will |
| 22401 |
be empty. (\bibgls\ won't know if you've modified the associated |
| 22402 |
\csfmt{bibglsnew\ldots} command to set the \field{type}. It can only |
| 22403 |
know the type if it's in the original \ext{bib} definition or is set |
| 22404 |
using resource options such as \csopt{type}.) |
| 22405 |
\end{itemize} |
| 22406 |
|
| 22407 |
The \field{group} field is then set using: |
| 22408 |
\begin{codeenv} |
| 22409 |
\field{group}=\marg{\gls{bibglslettergroup}\margm{title}\margm{letter}\margm{id}\margm{type}} |
| 22410 |
\end{codeenv} |
| 22411 |
This field needs to expand to a simple label, which \gls!{bibglslettergroup} |
| 22412 |
is designed to do. Note that non-letter groups are dealt with |
| 22413 |
separately (see below). |
| 22414 |
|
| 22415 |
\cssection{bibglssetlastgrouptitle} |
| 22416 |
|
| 22417 |
In the last resource (\ext{glstex}) file, after all the relevant |
| 22418 |
group titles have been set with the commands listed below, there's a |
| 22419 |
final title setting: |
| 22420 |
\formatdef{bibglssetlastgrouptitle} |
| 22421 |
This does nothing by default, but the arguments are set to |
| 22422 |
correspond to the group with the maximum id for that resource file. |
| 22423 |
It's provided as a convenient way of overriding the final group |
| 22424 |
title without the inconvenience of looking up the group label in the |
| 22425 |
\ext{glstex} file. If you have multiple glossaries or if you want to |
| 22426 |
override a different group, then you need to inspect the |
| 22427 |
\ext{glstex} file to work out the corresponding label (by finding |
| 22428 |
the \field{group} assignment for one of the entries in that group). |
| 22429 |
|
| 22430 |
The \meta{cs} argument is the control sequence used in the |
| 22431 |
\field{group} field to obtain the label from \meta{specs}. For |
| 22432 |
example, if the highest \meta{id} is 2147418112 from: |
| 22433 |
\begin{codeenv} |
| 22434 |
\field{group}=\marg{\gls{bibglslettergroup}\marg{Ø}\marg{Ø}\marg{2147418112}\marg{}} |
| 22435 |
\end{codeenv} |
| 22436 |
then the last group is identified with: |
| 22437 |
\begin{codeenv} |
| 22438 |
\gls{bibglssetlastgrouptitle}\marg{\gls{bibglslettergroup}}\marg{\marg{Ø}\marg{Ø}\marg{2147418112}\marg{}} |
| 22439 |
\end{codeenv} |
| 22440 |
In this case \meta{cs} is \gls{bibglslettergroup} and \meta{specs} |
| 22441 |
are the arguments for that command. If you want \gls{bibglssetlastgrouptitle} |
| 22442 |
to change the group title then you need to define it before the |
| 22443 |
\igls{resourceset}. For example: |
| 22444 |
\begin{codeenv} |
| 22445 |
\cs{newcommand}*\marg{\gls{bibglssetlastgrouptitle}}[2]\marg{\comment{} |
| 22446 |
\cs{glsxtrsetgrouptitle}\marg{\idx{param}1\idx{param}2}\marg{Foreign Words}} |
| 22447 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}} |
| 22448 |
\end{codeenv} |
| 22449 |
If you need to change a particular group title, then it has to be |
| 22450 |
done after the \idx{resourceset}: |
| 22451 |
\begin{codeenv} |
| 22452 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}} |
| 22453 |
\cs{glsxtrsetgrouptitle} |
| 22454 |
\marg{\gls{bibglslettergroup}\marg{\marg{Ø}\marg{Ø}\marg{2147418112}\marg{}}}\comment{label} |
| 22455 |
\marg{Foreign Words}\comment{title} |
| 22456 |
\end{codeenv} |
| 22457 |
|
| 22458 |
\cssection{bibglshypergroup} |
| 22459 |
|
| 22460 |
\formatdef{bibglshypergroup} |
| 22461 |
|
| 22462 |
If the \iext{log} file indicates that \isty{hyperref} has been loaded |
| 22463 |
and the \longarg{group} switch is used, then this command will be |
| 22464 |
used to create the navigation information for glossary styles such |
| 22465 |
as \glostyle{indexhypergroup}. Note that this requires at least |
| 22466 |
\isty{glossaries} v4.53 and \isty{glossaries-extra} v1.53. If older |
| 22467 |
versions are detected, this command will simply ignore its |
| 22468 |
arguments. |
| 22469 |
|
| 22470 |
\subsection{Top-Level Groups Only} |
| 22471 |
\label{sec:toplevelgroups} |
| 22472 |
\renewcommand{\cssectioncmd}{\subsubsection} |
| 22473 |
|
| 22474 |
The default \csopt{group-level} setting will only create groups for |
| 22475 |
the \glspl{top-levelentry}. Any \glspl{sub-entry} are considered to |
| 22476 |
be part of the \gls{top-levelentry}['s] group. If hierarchical |
| 22477 |
groups are enabled, the commands defined in \sectionref{sec:hiergroups} |
| 22478 |
are provided. |
| 22479 |
|
| 22480 |
\cssection{bibglssetlettergrouptitle} |
| 22481 |
|
| 22482 |
For each \idx{lettergroup} that's detected, \bibgls\ will write the line: |
| 22483 |
\formatdef{bibglssetlettergrouptitle} |
| 22484 |
in the \ext{glstex} file, which sets the group's title using: |
| 22485 |
\begin{codeenv} |
| 22486 |
\format{glsxtrsetgrouptitle} |
| 22487 |
\end{codeenv} |
| 22488 |
where the \meta{group label} part matches the corresponding \field{group} |
| 22489 |
value. |
| 22490 |
|
| 22491 |
Note that \gls{bibglssetlettergrouptitle} only has a single |
| 22492 |
argument, but that argument contains the four arguments needed by |
| 22493 |
\gls!{bibglslettergroup} and \gls!{bibglslettergrouptitle}. |
| 22494 |
These arguments are as described above. |
| 22495 |
|
| 22496 |
If \gls{glsxtrsetgrouptitle} has been defined (\sty{glossaries-extra} |
| 22497 |
version 1.14 onwards), then \gls{bibglssetlettergrouptitle} will be |
| 22498 |
defined as: |
| 22499 |
\begin{codeenv} |
| 22500 |
\cs{providecommand}\marg{\gls{bibglssetlettergrouptitle}}[1]\marg{\comment{} |
| 22501 |
\cs{glsxtrsetgrouptitle}\marg{\gls{bibglslettergroup}\idx{param}1}\marg{\gls{bibglslettergrouptitle}\idx{param}1}} |
| 22502 |
\end{codeenv} |
| 22503 |
If an earlier version of \sty{glossaries-extra} is used, then this |
| 22504 |
function can't be supported and the command will be defined to |
| 22505 |
simply ignore its argument. This will fall back on the original |
| 22506 |
method of just using \meta{title} as the label. |
| 22507 |
|
| 22508 |
Since \gls{bibglssetlettergrouptitle} is used in the \ext{glstex} file to |
| 22509 |
set the group titles, the associated commands need to be defined |
| 22510 |
before the resource file is loaded if their definitions require |
| 22511 |
modification. After the resource file has been loaded, you can |
| 22512 |
adjust the title of a specific group, but you'll need to check the |
| 22513 |
\ext{glstex} file for the appropriate arguments. For example, if the |
| 22514 |
\ext{glstex} file contains: |
| 22515 |
\begin{codeenv} |
| 22516 |
\gls{bibglssetlettergrouptitle}\marg{\marg{\AE}\marg{\ae}\marg{7274496}\marg{}} |
| 22517 |
\end{codeenv} |
| 22518 |
but you actually want the group title to appear as \qt{\AE\ (AE)} |
| 22519 |
instead of just \qt{\AE}, then after the resource file has been |
| 22520 |
loaded you can do: |
| 22521 |
\begin{codeenv} |
| 22522 |
\gls{glsxtrsetgrouptitle} |
| 22523 |
\marg{\gls{bibglslettergroup}\marg{\AE}\marg{\ae}\marg{7274496}\marg{}}\comment{label} |
| 22524 |
\marg{\AE\ (AE)}\comment{title} |
| 22525 |
\end{codeenv} |
| 22526 |
|
| 22527 |
\cssection{bibglslettergroup} |
| 22528 |
|
| 22529 |
\formatdef{bibglslettergroup} |
| 22530 |
This command is used to determine the \idx{lettergroup} label. The |
| 22531 |
default definition is \meta{type}\meta{id}, which ensures that no |
| 22532 |
problematic characters occur in the label since \meta{type} can't |
| 22533 |
contains special characters and \meta{id} is numeric. The |
| 22534 |
\meta{type} is included in case there are multiple glossaries, since |
| 22535 |
the hyperlink name must be unique. |
| 22536 |
|
| 22537 |
\cssection{bibglslettergrouptitle} |
| 22538 |
|
| 22539 |
\formatdef{bibglslettergrouptitle} |
| 22540 |
This command is used to determine the \idx{lettergroup} title. |
| 22541 |
The default definition is \ics{unexpanded}\margm{title}, which guards |
| 22542 |
against any expansion issues that may arise with characters outside |
| 22543 |
the basic Latin set. |
| 22544 |
|
| 22545 |
For example: |
| 22546 |
\begin{codeenv} |
| 22547 |
\atentry{entry}\marg{angstrom, |
| 22548 |
\field{name}=\marg{\cs{AA} ngstr\cs{umlaut}om} |
| 22549 |
\field{description}=\marg{a unit of length equal to one hundred-millionth |
| 22550 |
of a centimetre} |
| 22551 |
} |
| 22552 |
\end{codeenv} |
| 22553 |
The \field{sort} value is \qtt{\AA ngstr\"om}. With \csopt[en]{sort} |
| 22554 |
the \meta{title} part will be \code{A} but with \csopt[sv]{sort} |
| 22555 |
the \meta{title} part will be \code{\AA}. In both cases the |
| 22556 |
\meta{letter} argument will be \code{\AA}. |
| 22557 |
|
| 22558 |
Take care if you are using a script that needs encapsulating. For |
| 22559 |
example, with the \isty{CJKutf8} package the \idx{CJK} characters need to |
| 22560 |
be placed within the \env{CJK} environment, so any letter group |
| 22561 |
titles that contain \idx{CJK} characters will need special attention. |
| 22562 |
|
| 22563 |
For example, suppose the \ext{bib} file contains entries in the |
| 22564 |
form: |
| 22565 |
\begin{codeenv} |
| 22566 |
\atentry{dualentry}\marg{\meta{label}, |
| 22567 |
\field{name} = \marg{\gls{cjkname}\margm{\idx{CJK} characters}}, |
| 22568 |
\field{description} = \margm{English translation} |
| 22569 |
} |
| 22570 |
\end{codeenv} |
| 22571 |
and the document contains: |
| 22572 |
\begin{codeenv} |
| 22573 |
\cmd{usepackage}\marg{CJKutf8} |
| 22574 |
\cmd{usepackage}[\styopt{record},\styopt[indexgroup]{style},\styopt{nomain}]\marg{glossaries-extra} |
| 22575 |
\strut |
| 22576 |
\cs{newglossary*}\marg{japanese}\marg{Japanese to English} |
| 22577 |
\cs{newglossary*}\marg{english}\marg{English to Japanese} |
| 22578 |
\strut |
| 22579 |
\ics{newrobustcmd}\marg{\gls{cjkname}}[1]\marg{\cmd{begin}\marg{CJK}\marg{UTF8}\marg{min}\idx{param}1\cmd{end}\marg{CJK}} |
| 22580 |
\strut |
| 22581 |
\gls{GlsXtrLoadResources}\oarg{ |
| 22582 |
\csopt[testcjk]{src},\comment{bib file} |
| 22583 |
\csopt[ja-JP]{sort},\comment{locale used to sort \glspl{primaryentry}} |
| 22584 |
\csopt[en-GB]{dual-sort},\comment{locale used to sort \glspl{dualentry}} |
| 22585 |
\csopt[japanese]{type},\comment{put the \gls{primaryentry} in the 'japanese' glossary} |
| 22586 |
\csopt[english]{dual-type},\comment{put the \gls{dualentry} in the 'english' glossary} |
| 22587 |
\csopt[en.]{dual-prefix} |
| 22588 |
} |
| 22589 |
\end{codeenv} |
| 22590 |
then \idx{CJK} characters will appear in the \meta{title} argument of |
| 22591 |
\gls{bibglslettergrouptitle} which causes a problem because they need |
| 22592 |
to be encapsulated within the \env{CJK} environment. This can be more |
| 22593 |
conveniently done with the user supplied \inlinedef{cjkname}, but the \idx{CJK} |
| 22594 |
characters need to be protected from expansion so \ics{unexpanded} is |
| 22595 |
also needed. The new definition of \gls{bibglslettergrouptitle} needs |
| 22596 |
to be defined before \gls{GlsXtrLoadResources}. For example: |
| 22597 |
\begin{codeenv} |
| 22598 |
\cs{newcommand}\marg{\gls{bibglslettergrouptitle}}[4]\marg{\cs{unexpanded}\marg{\gls{cjkname}\marg{\idx{param}1}}} |
| 22599 |
\end{codeenv} |
| 22600 |
There's a slight problem here in that the English letter group titles |
| 22601 |
also end up encapsulated. An alternative approach is to use the |
| 22602 |
\meta{type} part to provide different forms. For example: |
| 22603 |
\begin{codeenv} |
| 22604 |
\cs{newcommand}*\marg{\cmd{englishlettergroup}}[1]\marg{\idx{param}1} |
| 22605 |
\cs{newcommand}*\marg{\cmd{japaneselettergroup}}[1]\marg{\gls{cjkname}\marg{\idx{param}1}} |
| 22606 |
\cs{newcommand}\marg{\gls{bibglslettergrouptitle}}[4]\marg{\comment{} |
| 22607 |
\cs{unexpanded}\marg{\cs{csuse}\marg{\idx{param}4lettergroup}\marg{\idx{param}1}}} |
| 22608 |
\end{codeenv} |
| 22609 |
|
| 22610 |
\cssection{bibglssetothergrouptitle} |
| 22611 |
|
| 22612 |
The label and title for \idxpl{symbolgroup} |
| 22613 |
are dealt with in a similar way to the \idxpl!{lettergroup}, but in this |
| 22614 |
case the title is set using: |
| 22615 |
\formatdef{bibglssetothergrouptitle} |
| 22616 |
This is defined in an analogous manner: |
| 22617 |
\begin{codeenv} |
| 22618 |
\cs{providecommand}\marg{\gls{bibglssetothergrouptitle}}[1]\marg{\comment{} |
| 22619 |
\cs{glsxtrsetgrouptitle}\marg{\gls{bibglsothergroup}\idx{param}1}\marg{\gls{bibglsothergrouptitle}\idx{param}1}} |
| 22620 |
\end{codeenv} |
| 22621 |
where the group label is obtained using \gls!{bibglsothergroup} and |
| 22622 |
the group title is obtained from \gls!{bibglsothergrouptitle}. |
| 22623 |
Note that since non-alphabetic characters don't have upper or lower |
| 22624 |
case versions, there are only three arguments. The other difference |
| 22625 |
between this and the letter group version is that the \meta{id} is |
| 22626 |
given in hexadecimal format (corresponding to the character code). |
| 22627 |
|
| 22628 |
For example, suppose my \ext{bib} file contains: |
| 22629 |
\begin{codeenv} |
| 22630 |
\atentry{entry}\marg{sauthor, |
| 22631 |
\field{name}=\marg{/Author}, |
| 22632 |
\field{description} = \marg{author string} |
| 22633 |
} |
| 22634 |
\end{codeenv} |
| 22635 |
If a locale sort is used, the leading slash \code{/} will be |
| 22636 |
ignored and this entry will belong to the \qt{A} letter group using |
| 22637 |
the letter commands described above. If, instead, one of the |
| 22638 |
character code sort methods are used, such as |
| 22639 |
\csopt[letter-case]{sort}, then this entry will be identified as |
| 22640 |
belonging to a symbol (or \qt{other}) group and the title will be |
| 22641 |
set using: |
| 22642 |
\begin{codeenv} |
| 22643 |
\gls{bibglssetothergrouptitle}\marg{\marg{/}\marg{2F}\marg{}} |
| 22644 |
\end{codeenv} |
| 22645 |
|
| 22646 |
\cssection{bibglsothergroup} |
| 22647 |
|
| 22648 |
\formatdef{bibglsothergroup} |
| 22649 |
This expands to the label for \idxpl{symbolgroup}. This just |
| 22650 |
defaults to \code{glssymbols} (ignoring all arguments), which |
| 22651 |
replicates the label used when \idx!{makeindex} or \idx!{xindy} |
| 22652 |
generate the glossary files. |
| 22653 |
|
| 22654 |
\cssection{bibglsothergrouptitle} |
| 22655 |
|
| 22656 |
\formatdef{bibglsothergrouptitle} |
| 22657 |
This expands to the title for \idxpl{symbolgroup}. This just |
| 22658 |
expands to \ics{glssymbolsgroupname} by default. |
| 22659 |
|
| 22660 |
\cssection{bibglssetemptygrouptitle} |
| 22661 |
|
| 22662 |
Used when the sort value degenerates to an empty string. This command |
| 22663 |
sets the label and title. |
| 22664 |
\formatdef{bibglssetemptygrouptitle} |
| 22665 |
(Note the inner group, as with the other similar |
| 22666 |
\csfmt{bibglsset\ldots grouptitle} commands.) |
| 22667 |
|
| 22668 |
\cssection{bibglsemptygroup} |
| 22669 |
|
| 22670 |
\formatdef{bibglsemptygroup} |
| 22671 |
This expands to the label for \idxpl{emptygroup}. This |
| 22672 |
defaults to \code{glssymbols} to make it consistent with |
| 22673 |
\idxpl{nonlettergroup} (since the sort value likely contained |
| 22674 |
unknown symbol commands). |
| 22675 |
|
| 22676 |
\cssection{bibglsemptygrouptitle} |
| 22677 |
|
| 22678 |
\formatdef{bibglsemptygrouptitle} |
| 22679 |
This expands to the group title for \idx{emptygroup}. This just |
| 22680 |
expands to \ics{glssymbolsgroupname} by default. |
| 22681 |
|
| 22682 |
\cssection{bibglssetnumbergrouptitle} |
| 22683 |
|
| 22684 |
The numeric sort methods (\tableref{tab:sortoptionsnumerical}) |
| 22685 |
all create \idxpl{numbergroup} instead of letter |
| 22686 |
or symbol groups. These behave in an analogous way to the above. |
| 22687 |
\formatdef{bibglssetnumbergrouptitle} |
| 22688 |
In this case \meta{value} is the actual numeric sort value, and |
| 22689 |
\meta{id} is a decimal number obtained from converting \meta{value} |
| 22690 |
to an integer. This command is defined as: |
| 22691 |
\begin{codeenv} |
| 22692 |
\cs{providecommand}\marg{\gls{bibglssetnumbergrouptitle}}[1]\marg{\comment{} |
| 22693 |
\cs{glsxtrsetgrouptitle}\marg{\gls{bibglsnumbergroup}\idx{param}1}\marg{\gls{bibglsnumbergrouptitle}\idx{param}1}} |
| 22694 |
\end{codeenv} |
| 22695 |
|
| 22696 |
\cssection{bibglsnumbergroup} |
| 22697 |
|
| 22698 |
The \idx{numbergroup} label is obtained from: |
| 22699 |
\formatdef{bibglsnumbergroup} |
| 22700 |
This just defaults to \code{glsnumbers}. |
| 22701 |
|
| 22702 |
\cssection{bibglsnumbergrouptitle} |
| 22703 |
|
| 22704 |
The \idx{numbergroup} title is obtained from: |
| 22705 |
\formatdef{bibglsnumbergrouptitle} |
| 22706 |
This just defaults to \ics{glsnumbersgroupname}. |
| 22707 |
|
| 22708 |
\cssection{bibglssetdatetimegrouptitle} |
| 22709 |
|
| 22710 |
The date-time sort methods (\tableref{tab:sortoptionsdatetime}) |
| 22711 |
create \idxpl{datetimegroup}. These behave in an analogous way to the above. |
| 22712 |
\formatdef{bibglssetdatetimegrouptitle} |
| 22713 |
This command is defined as: |
| 22714 |
\begin{codeenv} |
| 22715 |
\cs{providecommand}\marg{\gls{bibglssetdatetimegrouptitle}}[1]\marg{\comment{} |
| 22716 |
\cs{glsxtrsetgrouptitle} |
| 22717 |
\marg{\gls{bibglsdatetimegroup}\idx{param}1}\comment{} |
| 22718 |
\marg{\gls{bibglsdatetimegrouptitle}\idx{param}1}\comment{} |
| 22719 |
} |
| 22720 |
\end{codeenv} |
| 22721 |
|
| 22722 |
\cssection{bibglsdatetimegroup} |
| 22723 |
|
| 22724 |
\formatdef{bibglsdatetimegroup} |
| 22725 |
|
| 22726 |
This command is used for \idx{datetimegroup} labels with \optfmt{datetime} sorting |
| 22727 |
(\tableref{tab:sortoptionsdatetime}). This has ten arguments, which means a |
| 22728 |
little trickery is needed to deal with the tenth argument. |
| 22729 |
The default definition is: |
| 22730 |
\begin{codeenv} |
| 22731 |
\cs{providecommand}\marg{\gls{bibglsdatetimegroup}}[9]\marg{\idx{param}1\idx{param}2\idx{param}3\ics{@firstofone}} |
| 22732 |
\end{codeenv} |
| 22733 |
This forms the group label from the year \meta{YYYY}, month \meta{MM}, |
| 22734 |
day \meta{DD} and \meta{type}. |
| 22735 |
|
| 22736 |
\cssection{bibglsdatetimegrouptitle} |
| 22737 |
|
| 22738 |
\formatdef{bibglsdatetimegrouptitle} |
| 22739 |
|
| 22740 |
This command is used for \idx{datetimegroup} titles with \optfmt{datetime} sorting |
| 22741 |
(\tableref{tab:sortoptionsdatetime}). |
| 22742 |
The default definition is: |
| 22743 |
\begin{codeenv} |
| 22744 |
\cs{providecommand}\marg{\gls{bibglsdatetimegrouptitle}}[9]\marg{\idx{param}1-\idx{param}2-\idx{param}3\ics{@gobble}} |
| 22745 |
\end{codeenv} |
| 22746 |
This sets the title to the numeric |
| 22747 |
\code{\meta{YYYY}-\meta{MM}-\meta{DD}} |
| 22748 |
but may be redefined as appropriate. |
| 22749 |
|
| 22750 |
\cssection{bibglssetdategrouptitle} |
| 22751 |
|
| 22752 |
The date sort methods (\tableref{tab:sortoptionsdatetime}) |
| 22753 |
create \idxpl{dategroup} (the time isn't included). These behave in an |
| 22754 |
analogous way to the above. |
| 22755 |
\formatdef{bibglssetdategrouptitle} |
| 22756 |
This command is defined as: |
| 22757 |
\begin{codeenv} |
| 22758 |
\cs{providecommand}\marg{\gls{bibglssetdategrouptitle}}[1]\marg{\comment{} |
| 22759 |
\cs{glsxtrsetgrouptitle}\marg{\gls{bibglsdategroup}\idx{param}1}\marg{\gls{bibglsdategrouptitle}\idx{param}1}} |
| 22760 |
\end{codeenv} |
| 22761 |
|
| 22762 |
\cssection{bibglsdategroup} |
| 22763 |
|
| 22764 |
\formatdef{bibglsdategroup} |
| 22765 |
|
| 22766 |
This command is used for \idx{dategroup} labels with \optfmt{date} (no time) sorting |
| 22767 |
(\tableref{tab:sortoptionsdatetime}). The default definition is: |
| 22768 |
\begin{codeenv} |
| 22769 |
\cs{providecommand}\marg{\gls{bibglsdategroup}}[7]\marg{\idx{param}1\idx{param}2\idx{param}4\idx{param}7} |
| 22770 |
\end{codeenv} |
| 22771 |
This forms the group label from the year, month, era and type. |
| 22772 |
In this case, the era is a textual representation not the numeric |
| 22773 |
value used in calculating the sort value. |
| 22774 |
|
| 22775 |
\cssection{bibglsdategrouptitle} |
| 22776 |
|
| 22777 |
\formatdef{bibglsdategrouptitle} |
| 22778 |
This command is used for \idx{dategroup} titles with \optfmt{date} (no time) sorting |
| 22779 |
(\tableref{tab:sortoptionsdatetime}). The default definition is: |
| 22780 |
\begin{codeenv} |
| 22781 |
\cs{providecommand}\marg{\gls{bibglsdategrouptitle}}[7]\marg{\idx{param}1-\idx{param}2} |
| 22782 |
\end{codeenv} |
| 22783 |
This just sets the title to the numeric year-month form |
| 22784 |
\code{\meta{YYYY}-\meta{MM}}. |
| 22785 |
|
| 22786 |
\cssection{bibglssettimegrouptitle} |
| 22787 |
|
| 22788 |
The time sort methods (\tableref{tab:sortoptionsdatetime}) |
| 22789 |
create \idxpl{timegroup} (the date isn't included). These behave in an |
| 22790 |
analogous way to the above. |
| 22791 |
\formatdef{bibglssettimegrouptitle} |
| 22792 |
This command is defined as: |
| 22793 |
\begin{codeenv} |
| 22794 |
\cs{providecommand}\marg{\gls{bibglssettimegrouptitle}}[1]\marg{\comment{} |
| 22795 |
\cs{glsxtrsetgrouptitle}\marg{\gls{bibglstimegroup}\idx{param}1}\marg{\gls{bibglstimegrouptitle}\idx{param}1}} |
| 22796 |
\end{codeenv} |
| 22797 |
|
| 22798 |
\cssection{bibglstimegroup} |
| 22799 |
|
| 22800 |
\formatdef{bibglstimegroup} |
| 22801 |
This command is used for \idx{timegroup} labels with \optfmt{time} (no date) sorting |
| 22802 |
(\tableref{tab:sortoptionsdatetime}). |
| 22803 |
This command is defined as: |
| 22804 |
\begin{codeenv} |
| 22805 |
\cs{providecommand}\marg{\gls{bibglstimegroup}}[7]\marg{\idx{param}1\idx{param}2\idx{param}7} |
| 22806 |
\end{codeenv} |
| 22807 |
|
| 22808 |
\cssection{bibglstimegrouptitle} |
| 22809 |
|
| 22810 |
\formatdef{bibglstimegrouptitle} |
| 22811 |
|
| 22812 |
This command is used for \idx{timegroup} titles with \optfmt{time} (no date) sorting |
| 22813 |
(\tableref{tab:sortoptionsdatetime}). |
| 22814 |
This command is defined as: |
| 22815 |
\begin{codeenv} |
| 22816 |
\cs{providecommand}\marg{\gls{bibglstimegrouptitle}}[7]\marg{\idx{param}1} |
| 22817 |
\end{codeenv} |
| 22818 |
|
| 22819 |
\cssection{bibglssetunicodegrouptitle} |
| 22820 |
|
| 22821 |
\formatdef{bibglssetunicodegrouptitle} |
| 22822 |
This command is used to assign the group titles when the group |
| 22823 |
formation is set to any value other than the default. For example, |
| 22824 |
this command will be used with \csopt[codepoint]{group-formation}. |
| 22825 |
The label is obtained from \gls{bibglsunicodegroup} and the title is |
| 22826 |
obtained from \gls{bibglsunicodegrouptitle}. |
| 22827 |
|
| 22828 |
\cssection{bibglsunicodegroup} |
| 22829 |
|
| 22830 |
\formatdef{bibglsunicodegroup} |
| 22831 |
The \meta{label} depends on the \csopt{group-formation} setting: |
| 22832 |
\begin{itemize} |
| 22833 |
\item\csopt[codepoint]{group-formation}: the \meta{label} is the |
| 22834 |
Unicode value of \meta{character} (converted to \idx!{lowercase} and |
| 22835 |
decomposed, if applicable); |
| 22836 |
\item\csopt[unicode category]{group-formation}: the \meta{label} is the |
| 22837 |
Unicode category of \meta{character} (for example, \code{Lu} means |
| 22838 |
an \idx!{uppercase} letter); |
| 22839 |
\item\csopt[unicode script]{group-formation}: the \meta{label} is the |
| 22840 |
Unicode script associated with \meta{character} (for example, |
| 22841 |
\code{LATIN}); |
| 22842 |
\item\csopt[unicode category and script]{group-formation}: the \meta{label} |
| 22843 |
identifies both the Unicode category and script associated with |
| 22844 |
\meta{character} (for example, \code{Lu.LATIN}). |
| 22845 |
\end{itemize} |
| 22846 |
(Similarly for \csopt{secondary-group-formation} and |
| 22847 |
\csopt{dual-group-formation}.) By default this command expands to |
| 22848 |
\meta{type}\meta{label}. |
| 22849 |
|
| 22850 |
The \meta{character} is the first significant character of the sort |
| 22851 |
value. The \meta{id} is the hexadecimal code of (possibly decomposed) |
| 22852 |
\meta{character}. The case of codepoint \meta{id} may or may not correspond |
| 22853 |
to the case of \meta{character}. |
| 22854 |
|
| 22855 |
For example, with \csopt[codepoint]{group-formation}, an unset |
| 22856 |
\field{type} and a sort value of \qt{\AA ngstr\"om} with \qt{\AA} as a |
| 22857 |
significant character distinct from \qt{A} then the \field{group} |
| 22858 |
field will be assigned using: |
| 22859 |
\begin{codeenv} |
| 22860 |
\field{group}=\marg{\gls{bibglsunicodegroup}\marg{å}\marg{Å}\marg{C5}\marg{}} |
| 22861 |
\end{codeenv} |
| 22862 |
whereas with \csopt[unicode category and script]{group-formation} it will be: |
| 22863 |
\begin{codeenv} |
| 22864 |
\field{group}=\marg{\gls{bibglsunicodegroup}\marg{Lu.LATIN}\marg{Å}\marg{C5}\marg{}} |
| 22865 |
\end{codeenv} |
| 22866 |
(\idx!{uppercase} Latin letter). |
| 22867 |
|
| 22868 |
If instead \qt{\AA} is considered equivalent to \qt{A} according to the |
| 22869 |
collator, then with \csopt[codepoint]{group-formation}, the value will be: |
| 22870 |
\begin{codeenv} |
| 22871 |
\field{group}=\marg{\gls{bibglsunicodegroup}\marg{a}\marg{Å}\marg{61}\marg{}} |
| 22872 |
\end{codeenv} |
| 22873 |
Note that the \meta{id} is now \hex{61} (the decomposed \qt{A} |
| 22874 |
converted to \idx{lowercase}) not \hex{C5}. |
| 22875 |
|
| 22876 |
\cssection{bibglsunicodegrouptitle} |
| 22877 |
|
| 22878 |
\formatdef{bibglsunicodegrouptitle} |
| 22879 |
The title for Unicode group formations is simply defined as |
| 22880 |
\code{\cs{unexpanded}\margm{label}} so you will need to change it to |
| 22881 |
something more appropriate. For example (before the \igls{resourceset}): |
| 22882 |
\begin{codeenv} |
| 22883 |
\cs{newcommand}\marg{\gls{bibglsunicodegrouptitle}}[4]\marg{\comment{} |
| 22884 |
\ifnumhex{\idx{param}3}>64 |
| 22885 |
\ifnumhex{\idx{param}3} < 91 |
| 22886 |
A-{}-Z\comment{} |
| 22887 |
\cmd{else} |
| 22888 |
\ifnumhex{\idx{param}3} > 96 |
| 22889 |
\ifnumhex{\idx{param}3} < 123 |
| 22890 |
A-{}-Z\comment{} |
| 22891 |
\cmd{fi} |
| 22892 |
\cmd{fi} |
| 22893 |
\cmd{fi} |
| 22894 |
\cmd{fi} |
| 22895 |
} |
| 22896 |
\end{codeenv} |
| 22897 |
This will make the title \qt{A--Z} if \meta{id} is greater |
| 22898 |
than 64 and less than 91 or greater than 96 and less than 123 |
| 22899 |
(and will be empty otherwise). |
| 22900 |
|
| 22901 |
Note that this setting can create an odd effect if the sorting |
| 22902 |
causes the groups to be split up. For example, if some of the sort values |
| 22903 |
start with extended or non-Latin characters this can break up the |
| 22904 |
groups. First check how the group labels are assigned using: |
| 22905 |
\begin{codeenv} |
| 22906 |
\cs{newcommand}\marg{\gls{bibglsunicodegrouptitle}}\marg{\gls{bibglsunicodegroup}} |
| 22907 |
\end{codeenv} |
| 22908 |
then adjust the definition of \gls{bibglsunicodegroup} until the |
| 22909 |
grouping is correct, and then change the definition of |
| 22910 |
\gls{bibglsunicodegrouptitle} so that the title is correct. |
| 22911 |
|
| 22912 |
\cssection{bibglssetmergedgrouptitle} |
| 22913 |
|
| 22914 |
Used when groups are merged by \csopt{merge-small-groups}. This command |
| 22915 |
sets the label and title. |
| 22916 |
\formatdef{bibglssetmergedgrouptitle} |
| 22917 |
(Note the inner group, as with the other similar |
| 22918 |
\csfmt{bibglsset\ldots grouptitle} commands.) |
| 22919 |
|
| 22920 |
\cssection{bibglsmergedgroup} |
| 22921 |
|
| 22922 |
\formatdef{bibglsmergedgroup} |
| 22923 |
This expands to the label for merged groups. |
| 22924 |
|
| 22925 |
\cssection{bibglsmergedgrouptitle} |
| 22926 |
|
| 22927 |
\formatdef{bibglsmergedgrouptitle} |
| 22928 |
This expands to the group title for merged groups. |
| 22929 |
|
| 22930 |
\cssection{bibglsmergedgroupfmt} |
| 22931 |
|
| 22932 |
\formatdef{bibglsmergedgroupfmt} |
| 22933 |
Used by \gls{bibglsmergedgrouptitle} and |
| 22934 |
\gls{bibglsmergedgrouphierfmt} to format merged group titles. The |
| 22935 |
first argument \meta{n} is the total number of groups that have been |
| 22936 |
merged, the second argument, \meta{g$_1$} is the first group title, |
| 22937 |
\marg{\meta{g$_2$}\ldots\meta{g$_n$}} are the middle group titles |
| 22938 |
(empty if $\meta{n}=2$), and \meta{g$_n$} is the last group title. |
| 22939 |
|
| 22940 |
The default definition is: |
| 22941 |
\begin{codeenv} |
| 22942 |
\cs{providecommand}\marg{\gls{bibglsmergedgroupfmt}}[4]\marg{\idx{param}2, |
| 22943 |
\cs{ifcase}\idx{param}1\cmd{or}\cmd{or}\cmd{or} \idx{param}3, |
| 22944 |
\cmd{else}\ldots, \cmd{fi} \idx{param}4} |
| 22945 |
\end{codeenv} |
| 22946 |
|
| 22947 |
|
| 22948 |
\subsection{Hierarchical Groups} |
| 22949 |
\label{sec:hiergroups} |
| 22950 |
|
| 22951 |
Hierarchical letter groups are set with analogous commands that have |
| 22952 |
\code{hier} appended to the command name. There are also two extra |
| 22953 |
arguments, \meta{parent} (the \gls{parententry}['s] label) and |
| 22954 |
\meta{level} (the hierarchical level). |
| 22955 |
|
| 22956 |
\cssection{bibglsgrouplevel} |
| 22957 |
|
| 22958 |
\formatdef{bibglsgrouplevel} |
| 22959 |
This command is used when \csopt{group-level} is used to apply group |
| 22960 |
formations for different hierarchical levels. The \meta{label} |
| 22961 |
argument is the label that would normally be applied to level~0. |
| 22962 |
The \meta{n} argument is the hierarchical level (0 for |
| 22963 |
\glspl{top-levelentry}). By default, this command simply expands to |
| 22964 |
\meta{label}. |
| 22965 |
|
| 22966 |
\cssection{bibglshiersubgrouptitle} |
| 22967 |
|
| 22968 |
Hierarchical group titles are formatted using: |
| 22969 |
\formatdef{bibglshiersubgrouptitle} |
| 22970 |
This is defined as: |
| 22971 |
\begin{codeenv} |
| 22972 |
\cs{providecommand}\marg{\gls{bibglshiersubgrouptitle}}[3]\marg{\cs{ifnum}\idx{param}1>0 \cs{Glsxtrhiername}\marg{\idx{param}2} / \cmd{fi} \idx{param}3} |
| 22973 |
\end{codeenv} |
| 22974 |
The first argument \meta{level} is the hierarchical level, the |
| 22975 |
second argument is the \gls{parententry} label (empty for |
| 22976 |
$\meta{level}=0$), and the third argument \meta{title} is the |
| 22977 |
normal title that would apply to the group with the default |
| 22978 |
\csopt[0]{group-level} setting. Note that this uses |
| 22979 |
\cs{Glsxtrhiername}\margm{parent} if $\meta{level}>0$. |
| 22980 |
If this isn't required then redefine \gls{bibglshiersubgrouptitle} |
| 22981 |
to simply expand to \meta{title} (\code{\idx{param}3}). |
| 22982 |
|
| 22983 |
\cssection{bibglssetlettergrouptitlehier} |
| 22984 |
\formatdef{bibglssetlettergrouptitlehier} |
| 22985 |
As \gls{bibglssetlettergrouptitle} but used for hierarchical groups. |
| 22986 |
|
| 22987 |
\cssection{bibglslettergrouphier} |
| 22988 |
\formatdef{bibglslettergrouphier} |
| 22989 |
As \gls{bibglslettergroup} but used for hierarchical groups. It |
| 22990 |
expands to the hierarchical letter group label. |
| 22991 |
This is defined as: |
| 22992 |
\begin{codeenv} |
| 22993 |
\cs{providecommand}\marg{\gls{bibglslettergrouphier}}[6]\marg{\idx{param}4\idx{param}5\idx{param}3} |
| 22994 |
\end{codeenv} |
| 22995 |
|
| 22996 |
\cssection{bibglslettergrouptitlehier} |
| 22997 |
\formatdef{bibglslettergrouptitlehier} |
| 22998 |
As \gls{bibglslettergrouptitle} but used for hierarchical groups. It |
| 22999 |
expands to the hierarchical letter group title. This is defined as: |
| 23000 |
\begin{codeenv} |
| 23001 |
\cs{providecommand}\marg{\gls{bibglslettergrouptitlehier}}[6]\marg{\cs{protect}\gls{bibglshiersubgrouptitle}\marg{\idx{param}6}\marg{\idx{param}5}\marg{\cs{unexpanded}\marg{\idx{param}1}}} |
| 23002 |
\end{codeenv} |
| 23003 |
|
| 23004 |
\cssection{bibglssetothergrouptitlehier} |
| 23005 |
\formatdef{bibglssetothergrouptitlehier} |
| 23006 |
As \gls{bibglssetothergrouptitle} but used for hierarchical groups. |
| 23007 |
|
| 23008 |
\cssection{bibglsothergrouphier} |
| 23009 |
\formatdef{bibglsothergrouphier} |
| 23010 |
As \gls{bibglsothergroup} but used for hierarchical groups. It |
| 23011 |
expands to the hierarchical other group label. |
| 23012 |
This is defined as: |
| 23013 |
\begin{codeenv} |
| 23014 |
\cs{providecommand}\marg{\gls{bibglsothergrouphier}}[5]\marg{\idx{param}3\idx{param}4glssymbols} |
| 23015 |
\end{codeenv} |
| 23016 |
|
| 23017 |
\cssection{bibglsothergrouptitlehier} |
| 23018 |
\formatdef{bibglsothergrouptitlehier} |
| 23019 |
As \gls{bibglsothergrouptitle} but used for hierarchical groups. It |
| 23020 |
expands to the hierarchical other group title. This is defined as: |
| 23021 |
\begin{codeenv} |
| 23022 |
\cs{providecommand}\marg{\gls{bibglsothergrouptitlehier}}[5]\marg{\cs{protect}\gls{bibglshiersubgrouptitle}\marg{\idx{param}5}\marg{\idx{param}4}\marg{\cs{protect}\cs{glssymbolsgroupname}}} |
| 23023 |
\end{codeenv} |
| 23024 |
|
| 23025 |
\cssection{bibglssetemptygrouptitlehier} |
| 23026 |
\formatdef{bibglssetemptygrouptitlehier} |
| 23027 |
As \gls{bibglssetemptygrouptitle} but used for hierarchical groups. |
| 23028 |
|
| 23029 |
\cssection{bibglsemptygrouphier} |
| 23030 |
\formatdef{bibglsemptygrouphier} |
| 23031 |
As \gls{bibglsemptygroup} but used for hierarchical groups. It |
| 23032 |
expands to the hierarchical empty group label. |
| 23033 |
This is defined as: |
| 23034 |
\begin{codeenv} |
| 23035 |
\cs{providecommand}\marg{\gls{bibglsemptygrouphier}}[3]\marg{\idx{param}1\idx{param}2glssymbols} |
| 23036 |
\end{codeenv} |
| 23037 |
|
| 23038 |
\cssection{bibglsemptygrouptitlehier} |
| 23039 |
\formatdef{bibglsemptygrouptitlehier} |
| 23040 |
As \gls{bibglsemptygrouptitle} but used for hierarchical groups. It |
| 23041 |
expands to the hierarchical empty group title. This is defined as: |
| 23042 |
\begin{codeenv} |
| 23043 |
\cs{providecommand}\marg{\gls{bibglsemptygrouptitlehier}}[3]\marg{\cs{protect}\gls{bibglshiersubgrouptitle}\marg{\idx{param}3}\marg{\idx{param}2}\marg{\cs{protect}\cs{glssymbolsgroupname}}} |
| 23044 |
\end{codeenv} |
| 23045 |
|
| 23046 |
\cssection{bibglssetnumbergrouptitlehier} |
| 23047 |
\formatdef{bibglssetnumbergrouptitlehier} |
| 23048 |
As \gls{bibglssetnumbergrouptitle} but used for hierarchical groups. |
| 23049 |
|
| 23050 |
\cssection{bibglsnumbergrouphier} |
| 23051 |
\formatdef{bibglsnumbergrouphier} |
| 23052 |
As \gls{bibglsnumbergroup} but used for hierarchical groups. It |
| 23053 |
expands to the hierarchical number group label. |
| 23054 |
This is defined as: |
| 23055 |
\begin{codeenv} |
| 23056 |
\cs{providecommand}\marg{\gls{bibglsnumbergrouphier}}[5]\marg{\idx{param}3\idx{param}4glsnumbers} |
| 23057 |
\end{codeenv} |
| 23058 |
|
| 23059 |
\cssection{bibglsnumbergrouptitlehier} |
| 23060 |
\formatdef{bibglsnumbergrouptitlehier} |
| 23061 |
As \gls{bibglsnumbergrouptitle} but used for hierarchical groups. It |
| 23062 |
expands to the hierarchical number group title. This is defined as: |
| 23063 |
\begin{codeenv} |
| 23064 |
\cs{providecommand}\marg{\gls{bibglsnumbergrouptitlehier}}[5]\marg{\cs{protect}\gls{bibglshiersubgrouptitle}\marg{\idx{param}5}\marg{\idx{param}4}\marg{\cs{protect}\cs{glsnumbersgroupname}}} |
| 23065 |
\end{codeenv} |
| 23066 |
|
| 23067 |
\cssection{bibglssetdatetimegrouptitlehier} |
| 23068 |
\formatdef{bibglssetdatetimegrouptitlehier} |
| 23069 |
As \gls{bibglssetdatetimegrouptitle} but used for hierarchical groups. |
| 23070 |
|
| 23071 |
\cssection{bibglsdatetimegrouphier} |
| 23072 |
\formatdef{bibglsdatetimegrouphier} |
| 23073 |
As \gls{bibglsdatetimegroup} but used for hierarchical groups. It |
| 23074 |
expands to the hierarchical \idx{datetimegroup} label. |
| 23075 |
Since this has more than 9 arguments, it is defined in two parts: |
| 23076 |
\begin{codeenv} |
| 23077 |
\cs{providecommand}\marg{\gls{bibglsdatetimegrouphier}}[9]\marg{\idx{param}1\idx{param}2\idx{param}3\gls{bibglsdatetimegrouphierfinalargs}} |
| 23078 |
\end{codeenv} |
| 23079 |
The final arguments are obtained with \gls{bibglsdatetimegrouphierfinalargs}. |
| 23080 |
|
| 23081 |
\cssection{bibglsdatetimegrouphierfinalargs} |
| 23082 |
\formatdef{bibglsdatetimegrouphierfinalargs} |
| 23083 |
This picks up the final three arguments for \gls{bibglsdatetimegrouphier}: |
| 23084 |
\begin{codeenv} |
| 23085 |
\cs{providecommand}*\marg{\gls{bibglsdatetimegrouphierfinalargs}}[3]\marg{\idx{param}1\idx{param}2} |
| 23086 |
\end{codeenv} |
| 23087 |
|
| 23088 |
\cssection{bibglsdatetimegrouptitlehier} |
| 23089 |
\formatdef{bibglsdatetimegrouptitlehier} |
| 23090 |
As \gls{bibglsdatetimegrouptitle} but used for hierarchical groups. It |
| 23091 |
expands to the hierarchical \idx{datetimegroup} title. |
| 23092 |
Since this has more than 9 arguments, it is defined in two parts: |
| 23093 |
\begin{codeenv} |
| 23094 |
\cs{providecommand}\marg{\gls{bibglsdatetimegrouptitlehier}}[9]\marg{\gls{bibglsdatetimegrouptitlehierfinalargs}\marg{\idx{param}1-\idx{param}2-\idx{param}3}} |
| 23095 |
\end{codeenv} |
| 23096 |
The final arguments are obtained with \gls{bibglsdatetimegrouptitlehierfinalargs}. |
| 23097 |
|
| 23098 |
\cssection{bibglsdatetimegrouptitlehierfinalargs} |
| 23099 |
\formatdef{bibglsdatetimegrouptitlehierfinalargs} |
| 23100 |
This picks up the final three arguments for \gls{bibglsdatetimegrouptitlehier}: |
| 23101 |
\begin{codeenv} |
| 23102 |
\cs{providecommand}*\marg{\gls{bibglsdatetimegrouptitlehierfinalargs}}[4]\marg{\cs{protect}\gls{bibglshiersubgrouptitle}\marg{\idx{param}4}\marg{\idx{param}3}\marg{\idx{param}1}} |
| 23103 |
\end{codeenv} |
| 23104 |
In this case, the first argument is set by |
| 23105 |
\gls{bibglsdatetimegrouptitlehier} to the date |
| 23106 |
(\code{\meta{YYYY}-\meta{MM}-\meta{DD}}). The remaining arguments |
| 23107 |
are the \meta{type}, \meta{parent} and \meta{level} information. |
| 23108 |
|
| 23109 |
\cssection{bibglssetdategrouptitlehier} |
| 23110 |
\formatdef{bibglssetdategrouptitlehier} |
| 23111 |
As \gls{bibglssetdategrouptitle} but used for hierarchical groups. |
| 23112 |
|
| 23113 |
\cssection{bibglsdategrouphier} |
| 23114 |
\formatdef{bibglsdategrouphier} |
| 23115 |
As \gls{bibglsdategroup} but used for hierarchical groups. It |
| 23116 |
expands to the hierarchical date group label. |
| 23117 |
This is defined as: |
| 23118 |
\begin{codeenv} |
| 23119 |
\cs{providecommand}\marg{\gls{bibglsdategrouphier}}[9]\marg{\idx{param}1\idx{param}2\idx{param}4\idx{param}7\idx{param}8} |
| 23120 |
\end{codeenv} |
| 23121 |
|
| 23122 |
\cssection{bibglsdategrouptitlehier} |
| 23123 |
\formatdef{bibglsdategrouptitlehier} |
| 23124 |
As \gls{bibglsdategrouptitle} but used for hierarchical groups. It |
| 23125 |
expands to the hierarchical date group title. This is defined as: |
| 23126 |
\begin{codeenv} |
| 23127 |
\cs{providecommand}\marg{\gls{bibglsdategrouptitlehier}}[9]\marg{\cs{protect}\gls{bibglshiersubgrouptitle}\marg{\idx{param}9}\marg{\idx{param}8}\marg{\idx{param}1-\idx{param}2}} |
| 23128 |
\end{codeenv} |
| 23129 |
|
| 23130 |
\cssection{bibglssettimegrouptitlehier} |
| 23131 |
\formatdef{bibglssettimegrouptitlehier} |
| 23132 |
As \gls{bibglssettimegrouptitle} but used for hierarchical groups. |
| 23133 |
|
| 23134 |
\cssection{bibglstimegrouphier} |
| 23135 |
\formatdef{bibglstimegrouphier} |
| 23136 |
As \gls{bibglstimegroup} but used for hierarchical groups. It |
| 23137 |
expands to the hierarchical time group label. This is defined as: |
| 23138 |
\begin{codeenv} |
| 23139 |
\cs{providecommand}\marg{\gls{bibglstimegrouphier}}[9]\marg{\idx{param}1\idx{param}2\idx{param}7\idx{param}8} |
| 23140 |
\end{codeenv} |
| 23141 |
|
| 23142 |
\cssection{bibglstimegrouptitlehier} |
| 23143 |
\formatdef{bibglstimegrouptitlehier} |
| 23144 |
As \gls{bibglstimegrouptitle} but used for hierarchical groups. It |
| 23145 |
expands to the hierarchical time group title. This is defined as: |
| 23146 |
\begin{codeenv} |
| 23147 |
\cs{providecommand}\marg{\gls{bibglstimegrouptitlehier}}[9]\marg{\cs{protect}\gls{bibglshiersubgrouptitle}\marg{\idx{param}9}\marg{\idx{param}8}{\idx{param}1}} |
| 23148 |
\end{codeenv} |
| 23149 |
|
| 23150 |
\cssection{bibglssetunicodegrouptitlehier} |
| 23151 |
\formatdef{bibglssetunicodegrouptitlehier} |
| 23152 |
As \gls{bibglssetunicodegrouptitle} but used for hierarchical groups. |
| 23153 |
|
| 23154 |
\cssection{bibglsunicodegrouphier} |
| 23155 |
\formatdef{bibglsunicodegrouphier} |
| 23156 |
As \gls{bibglsunicodegroup} but used for hierarchical groups. This |
| 23157 |
expands to the hierarchical group label: |
| 23158 |
\begin{codeenv} |
| 23159 |
\cs{providecommand}\marg{\gls{bibglsunicodegrouphier}}[6]\marg{\idx{param}4\idx{param}5\idx{param}3} |
| 23160 |
\end{codeenv} |
| 23161 |
|
| 23162 |
\cssection{bibglsunicodegrouptitlehier} |
| 23163 |
\formatdef{bibglsunicodegrouptitlehier} |
| 23164 |
As \gls{bibglsunicodegrouptitle} but used for hierarchical groups. This |
| 23165 |
expands to the hierarchical group title: |
| 23166 |
\begin{codeenv} |
| 23167 |
\cs{providecommand}\marg{\gls{bibglsunicodegrouptitlehier}}[6]\marg{\cs{protect}\gls{bibglshiersubgrouptitle}\marg{\idx{param}6}\marg{\idx{param}5}\marg{\cs{unexpanded}\marg{\idx{param}1}}} |
| 23168 |
\end{codeenv} |
| 23169 |
|
| 23170 |
\cssection{bibglssetmergedgrouptitlehier} |
| 23171 |
\formatdef{bibglssetmergedgrouptitlehier} |
| 23172 |
As \gls{bibglssetmergedgrouptitle} but used for hierarchical groups. |
| 23173 |
|
| 23174 |
\cssection{bibglsmergedgrouphier} |
| 23175 |
\formatdef{bibglsmergedgrouphier} |
| 23176 |
As \gls{bibglsmergedgroup} but used for hierarchical groups. This |
| 23177 |
expands to the hierarchical group label: |
| 23178 |
\begin{codeenv} |
| 23179 |
\cs{providecommand}\marg{\gls{bibglsmergedgrouphier}}[8]\marg{merged.\idx{param}1} |
| 23180 |
\end{codeenv} |
| 23181 |
|
| 23182 |
\cssection{bibglsmergedgrouptitlehier} |
| 23183 |
\formatdef{bibglsmergedgrouptitlehier} |
| 23184 |
As \gls{bibglsmergedgrouptitle} but used for hierarchical groups. This |
| 23185 |
expands to the hierarchical group title: |
| 23186 |
\begin{codeenv} |
| 23187 |
\cs{providecommand}\marg{\gls{bibglsmergedgrouptitlehier}}[8]\marg{\comment{} |
| 23188 |
\cs{unexpanded}\marg{\cs{ifnum}\idx{param}8=0\gls{bibglsmergedgroupfmt}\marg{\idx{param}3}\marg{\idx{param}4}\marg{\idx{param}5}\marg{\idx{param}6}\cmd{else}\gls{bibglsmergedgrouphierfmt}\marg{\idx{param}3}\marg{\idx{param}4}\marg{\idx{param}5}\marg{\idx{param}6}\cmd{fi}}\comment{} |
| 23189 |
} |
| 23190 |
\end{codeenv} |
| 23191 |
This uses \gls{bibglsmergedgroupfmt} ($\meta{level}=0$) or |
| 23192 |
\gls{bibglsmergedgrouphierfmt} ($\meta{level}>0$) to format the title. |
| 23193 |
|
| 23194 |
\cssection{bibglsmergedgrouphierfmt} |
| 23195 |
|
| 23196 |
\formatdef{bibglsmergedgrouphierfmt} |
| 23197 |
Used by \gls{bibglsmergedgrouphierfmt} to format merged hierarchical group titles. |
| 23198 |
The first argument \meta{n} is the total number of groups that have been |
| 23199 |
merged, the second argument, \meta{g$_1$} is the first group title, |
| 23200 |
\marg{\meta{g$_2$}\ldots\meta{g$_n$}} are the middle group titles |
| 23201 |
(empty if $\meta{n}=2$), and \meta{g$_n$} is the last group title. |
| 23202 |
|
| 23203 |
The default definition depends on whether or not \bibgls\ has |
| 23204 |
detected \sty{hyperref} in the document's \ext{log} file. If it has, |
| 23205 |
then the definition is: |
| 23206 |
\begin{codeenv} |
| 23207 |
\cs{providecommand}\marg{\gls{bibglsmergedgrouphierfmt}}[4]\marg{\idx{param}2, |
| 23208 |
\ics{texorpdfstring}\marg{\marg{\cs{def}\gls{bibglshiersubgrouptitle}\idx{param}\idx{param}1\idx{param}\idx{param}2\idx{param}\idx{param}3{\idx{param}\idx{param}3}\cs{ifcase}\idx{param}1\cmd{or}\cmd{or}\cmd{or} |
| 23209 |
\idx{param}3, \cmd{else}\cmd{ldots}, \cmd{fi} |
| 23210 |
\idx{param}4}}\marg{\cs{ifcase}\idx{param}1\cmd{or}\cmd{or}\cmd{or} |
| 23211 |
\idx{param}3, \cmd{else}\cmd{ldots}, \cmd{fi} \idx{param}4}} |
| 23212 |
\end{codeenv} |
| 23213 |
Otherwise the definition is: |
| 23214 |
\begin{codeenv} |
| 23215 |
\cs{providecommand}\marg{\gls{bibglsmergedgrouphierfmt}}[4]\marg{\idx{param}2, |
| 23216 |
\marg{\cs{def}\gls{bibglshiersubgrouptitle}\idx{param}\idx{param}1\idx{param}\idx{param}2\idx{param}\idx{param}3{\idx{param}\idx{param}3}\cs{ifcase}\idx{param}1\cmd{or}\cmd{or}\cmd{or} |
| 23217 |
\idx{param}3, \cmd{else}\cmd{ldots}, \cmd{fi} |
| 23218 |
\idx{param}4}} |
| 23219 |
\end{codeenv} |
| 23220 |
This locally redefines \gls{bibglshiersubgrouptitle} to just do its |
| 23221 |
final argument to allow for a more compact title. |
| 23222 |
|
| 23223 |
\renewcommand{\cssectioncmd}{\subsection} |
| 23224 |
\section{Flattened Entries} |
| 23225 |
\label{sec:flattendefs} |
| 23226 |
|
| 23227 |
These commands relate to the way the \field{name} field is altered |
| 23228 |
when flattening \glspl{lonelychildentry} with the \csopt{flatten-lonely} |
| 23229 |
option. |
| 23230 |
|
| 23231 |
\cssection{bibglsflattenedhomograph} |
| 23232 |
|
| 23233 |
\formatdef{bibglsflattenedhomograph} |
| 23234 |
The default definition simply does \meta{name}. |
| 23235 |
|
| 23236 |
This command is used if the \child\ and \parent\ names are identical. |
| 23237 |
For example, suppose the \ext{bib} file contains: |
| 23238 |
\begin{codeenv} |
| 23239 |
\atentry{index}\marg{super.glossary, \field{name}=\marg{glossary}} |
| 23240 |
\strut |
| 23241 |
\atentry{entry}\marg{glossarycol, |
| 23242 |
\field{parent}=\marg{super.glossary}, |
| 23243 |
\field{description}=\marg{collection of glosses} |
| 23244 |
} |
| 23245 |
\strut |
| 23246 |
\atentry{entry}\marg{glossarylist, |
| 23247 |
\field{parent}=\marg{super.glossary}, |
| 23248 |
\field{description}=\marg{list of technical words} |
| 23249 |
} |
| 23250 |
\end{codeenv} |
| 23251 |
The \glspl{childentry} don't have a \field{name} field, so the value is assumed |
| 23252 |
to be the same as the \glsdisp{parententry}{parent's} \field{name} field. |
| 23253 |
Here's an example document where both \glspl{childentry} are used: |
| 23254 |
\begin{codeenv} |
| 23255 |
\cmd{documentclass}\marg{article} |
| 23256 |
\strut |
| 23257 |
\cmd{usepackage}[\styopt{record},\istyopt{subentrycounter},\styopt[treenoname]{style}]\marg{glossaries-extra} |
| 23258 |
\strut |
| 23259 |
\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}} |
| 23260 |
\strut |
| 23261 |
\cmd{begin}\marg{document} |
| 23262 |
\cs{gls}\marg{glossarycol} (collection) vs \cs{gls}\marg{glossarylist} (list). |
| 23263 |
\strut |
| 23264 |
\cs{printunsrtglossary} |
| 23265 |
\cmd{end}\marg{document} |
| 23266 |
\end{codeenv} |
| 23267 |
This uses one of the glossary styles designed for \iglspl{homograph} and the |
| 23268 |
glossary has the structure: |
| 23269 |
\begin{flushleft} |
| 23270 |
\textbf{glossary}\par |
| 23271 |
\quad 1) collection of glosses 1\par |
| 23272 |
\quad 2) list of technical words 1 |
| 23273 |
\end{flushleft} |
| 23274 |
If \glsdisp{lonelychildentry}{only one child entry} is selected, then the result looks a little |
| 23275 |
odd. For example: |
| 23276 |
\begin{flushleft} |
| 23277 |
\textbf{glossary}\par |
| 23278 |
\quad 1) collection of glosses 1 |
| 23279 |
\end{flushleft} |
| 23280 |
With the \csopt{flatten-lonely} option, the \parent\ is removed and |
| 23281 |
the \child\ is moved up a \hierarchicallevel. With |
| 23282 |
\csopt[postsort]{flatten-lonely} this would normally adjust the |
| 23283 |
name so that it appears as \meta{parent name}, \meta{child name} |
| 23284 |
but in this case it would look a little odd for the name to |
| 23285 |
appear as \qt{glossary, glossary} so instead the name is |
| 23286 |
set to: |
| 23287 |
\begin{codeenv} |
| 23288 |
\gls{bibglsflattenedhomograph}\marg{glossary}\marg{super.glossary} |
| 23289 |
\end{codeenv} |
| 23290 |
(where the first argument is the original name and the second argument is the |
| 23291 |
label of the \gls{parententry}). |
| 23292 |
|
| 23293 |
This means that the name simply appears as \qt{glossary}, even if |
| 23294 |
the \csopt[postsort]{flatten-lonely} option is used. Note that if |
| 23295 |
the \gls{parententry} is removed, the \parent\ label won't be of |
| 23296 |
much use. You can test for existence using \ics{ifglsentryexists} |
| 23297 |
in case you want to vary the way the name is displayed according to |
| 23298 |
whether or not the \parent\ is still present. |
| 23299 |
|
| 23300 |
\cssection{bibglsflattenedchildpresort} |
| 23301 |
|
| 23302 |
\formatdef{bibglsflattenedchildpresort} |
| 23303 |
|
| 23304 |
Used by the \csopt[presort]{flatten-lonely} option. This defaults |
| 23305 |
to just \meta{child name}. If you want to change this, remember that |
| 23306 |
you can let the interpreter know by adding the definition to |
| 23307 |
\atentry{preamble}. For example: |
| 23308 |
\begin{codeenv} |
| 23309 |
\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\gls{bibglsflattenedchildpresort}}[2]\marg{\idx{param}1 (\idx{param}2)}}} |
| 23310 |
\end{codeenv} |
| 23311 |
|
| 23312 |
\cssection{bibglsflattenedchildpostsort} |
| 23313 |
|
| 23314 |
\formatdef{bibglsflattenedchildpostsort} |
| 23315 |
|
| 23316 |
Used by the \csopt[postsort]{flatten-lonely} option. This defaults |
| 23317 |
to \code{\meta{parent name}, \meta{child name}}. |
| 23318 |
|
| 23319 |
Note that the arguments are in the reverse order to those of the |
| 23320 |
previous command. This is done to assist the automated first letter |
| 23321 |
upper-casing. If either command is redefined to alter the ordering, |
| 23322 |
then this can confuse the case-changing mechanism, in which case you |
| 23323 |
may want to consider switching on the expansion of the \field{name} |
| 23324 |
field using: |
| 23325 |
\begin{codeenv} |
| 23326 |
\gls{glssetexpandfield}\marg{name} |
| 23327 |
\end{codeenv} |
| 23328 |
(before \gls{GlsXtrLoadResources}). |
| 23329 |
|
| 23330 |
\section{Other} |
| 23331 |
|
| 23332 |
\cssection{bibglscopytoglossary} |
| 23333 |
|
| 23334 |
\formatdef{bibglscopytoglossary} |
| 23335 |
This command is provided if the \csopt{copy-to-glossary} option is |
| 23336 |
set and is used to copy an entry to another glossary. The definition |
| 23337 |
is: |
| 23338 |
\begin{codeenv} |
| 23339 |
\cmd{providecommand}\marg{\gls{bibglscopytoglossary}}[2]{\comment{} |
| 23340 |
\ics{ifglossaryexists*}\marg{}\comment{} |
| 23341 |
\marg{\ics{GlsXtrIfInGlossary}\marg{\idx{param}1}\marg{\idx{param}2}\marg{}\marg{\ics{glsxtrcopytoglossary}\marg{\idx{param}1}\marg{\idx{param}2}}}\comment{} |
| 23342 |
\marg{}\comment{} |
| 23343 |
} |
| 23344 |
\end{codeenv} |
| 23345 |
This ensures that the entry is only copied if the glossary exists |
| 23346 |
and if the entry hasn't already been copied to it. |
| 23347 |
|
| 23348 |
This command isn't used by the \csopt[copy]{action} or |
| 23349 |
\csopt[copy or define]{action} settings, which use \ics{glsxtrcopytoglossary} |
| 23350 |
directly. |
| 23351 |
|
| 23352 |
\cssection{bibglssettotalrecordcount} |
| 23353 |
|
| 23354 |
\formatdef{bibglssettotalrecordcount} |
| 23355 |
This command is provided if \longarg{record-count} is used. It's |
| 23356 |
used to set the \field{recordcount} field to the total number of |
| 23357 |
records for the given entry. This is defined as: |
| 23358 |
\begin{codeenv} |
| 23359 |
\cmd{providecommand}*\marg{\gls{bibglssettotalrecordcount}}[2]\marg{\comment{} |
| 23360 |
\cs{GlsXtrSetField}\marg{\idx{param}1}\marg{\field{recordcount}}\marg{\idx{param}2}\comment{} |
| 23361 |
} |
| 23362 |
\end{codeenv} |
| 23363 |
|
| 23364 |
\cssection{bibglssetrecordcount} |
| 23365 |
|
| 23366 |
\formatdef{bibglssetrecordcount} |
| 23367 |
This command is provided if \longarg{record-count} is used. It's |
| 23368 |
used to set the \field{recordcount.counter} field to the total number of |
| 23369 |
records associated with the given counter for the given entry. This |
| 23370 |
is defined as: |
| 23371 |
\begin{codeenv} |
| 23372 |
\cmd{providecommand}*\marg{\gls{bibglssetrecordcount}}[3]\marg{\comment{} |
| 23373 |
\cs{GlsXtrSetField}\marg{\idx{param}1}\marg{recordcount.\idx{param}2}\marg{\idx{param}3}\comment{} |
| 23374 |
} |
| 23375 |
\end{codeenv} |
| 23376 |
|
| 23377 |
\cssection{bibglssetlocationrecordcount} |
| 23378 |
|
| 23379 |
\formatdef{bibglssetlocationrecordcount} |
| 23380 |
This command is provided if \longarg{record-count-unit} is used. |
| 23381 |
It's used to set the \field{recordcount.counter.location} field to |
| 23382 |
the total number of records associated with the given location for |
| 23383 |
the given entry. This is defined as: |
| 23384 |
\begin{codeenv} |
| 23385 |
\cmd{providecommand}*\marg{\gls{bibglssetlocationrecordcount}}[4]\marg{\comment{} |
| 23386 |
\cs{GlsXtrSetField}\marg{\idx{param}1}\marg{recordcount.\idx{param}2.\ics{glsxtrdetoklocation}\idx{param}3}\marg{\idx{param}4}\comment{} |
| 23387 |
} |
| 23388 |
\end{codeenv} |
| 23389 |
|
| 23390 |
\cssection{bibglshyperlink} |
| 23391 |
|
| 23392 |
\formatdef{bibglshyperlink} |
| 23393 |
Used by the \hyperref[sec:dualoptsbacklinks]{back link options}, |
| 23394 |
this just defaults to: |
| 23395 |
\begin{codeenv} |
| 23396 |
\ics{glshyperlink}\oargm{text}\margm{label} |
| 23397 |
\end{codeenv} |
| 23398 |
|
| 23399 |
\cssection{bibglssetwidest} |
| 23400 |
|
| 23401 |
\formatdef{bibglssetwidest} |
| 23402 |
This is used by \csopt{set-widest} to set the widest name for the |
| 23403 |
given \hierarchicallevel\ where the glossary type can't be determined. |
| 23404 |
This is defined as: |
| 23405 |
\begin{codeenv} |
| 23406 |
\cs{providecommand}*\marg{\gls{bibglssetwidest}}[2]\marg{\cs{glsxtrSetWidest}\marg{}\marg{\idx{param}1}\marg{\idx{param}2}} |
| 23407 |
\end{codeenv} |
| 23408 |
if \ics{glsxtrSetWidest} has been defined, or: |
| 23409 |
\begin{codeenv} |
| 23410 |
\cs{providecommand}*\marg{\gls{bibglssetwidest}}[2]\marg{\cs{glsupdatewidest}\oarg{\idx{param}1}\marg{\idx{param}2}} |
| 23411 |
\end{codeenv} |
| 23412 |
if \ics{glsupdatewidest} is defined, otherwise it will be |
| 23413 |
defined to use \ics{glssetwidest}: |
| 23414 |
\begin{codeenv} |
| 23415 |
\cs{providecommand}*\marg{\gls{bibglssetwidest}}[2]\marg{\cs{glssetwidest}\oarg{\idx{param}1}\marg{\idx{param}2}} |
| 23416 |
\end{codeenv} |
| 23417 |
Since this isn't scoped, this will affect other glossaries. |
| 23418 |
In general, if you have more than one glossary it's best to |
| 23419 |
set the \field{type} using options like \csopt{type}. |
| 23420 |
|
| 23421 |
\cssection{bibglssetwidestfortype} |
| 23422 |
|
| 23423 |
\formatdef{bibglssetwidestfortype} |
| 23424 |
This is used by \csopt{set-widest} to set the widest name for the |
| 23425 |
given \hierarchicallevel\ where the glossary type is known. This |
| 23426 |
is defined as: |
| 23427 |
\begin{codeenv} |
| 23428 |
\cs{providecommand}*\marg{\gls{bibglssetwidestfortype}}[3]\marg{\comment{} |
| 23429 |
\cs{glsxtrSetWidest}\marg{\idx{param}1}\marg{\idx{param}2}\marg{\idx{param}3}\comment{} |
| 23430 |
} |
| 23431 |
\end{codeenv} |
| 23432 |
if \ics{glsxtrSetWidest} has been defined, or: |
| 23433 |
\begin{codeenv} |
| 23434 |
\cs{providecommand}*\marg{\gls{bibglssetwidestfortype}}[3]\marg{\comment{} |
| 23435 |
\cs{apptoglossarypreamble}\oarg{\idx{param}1}\marg{\cs{glsupdatewidest}\oarg{\idx{param}2}\marg{\idx{param}3}}\comment{} |
| 23436 |
} |
| 23437 |
\end{codeenv} |
| 23438 |
if \ics{glsupdatewidest} is defined, otherwise it will be |
| 23439 |
defined to use \ics{glssetwidest}: |
| 23440 |
\begin{codeenv} |
| 23441 |
\cs{providecommand}*\marg{\gls{bibglssetwidestfortype}}[3]\marg{\comment{} |
| 23442 |
\cs{apptoglossarypreamble}\oarg{\idx{param}1}\marg{\cs{glssetwidest}\oarg{\idx{param}2}\marg{\idx{param}3}}\comment{} |
| 23443 |
} |
| 23444 |
\end{codeenv} |
| 23445 |
Since the glossary preamble is scoped, this won't affect other |
| 23446 |
glossaries. |
| 23447 |
|
| 23448 |
\cssection{bibglssetwidestfallback} |
| 23449 |
|
| 23450 |
\formatdef{bibglssetwidestfallback} |
| 23451 |
This is used by \csopt{set-widest} instead of \gls{bibglssetwidest} |
| 23452 |
when all \field{name} fields end up as an empty string when |
| 23453 |
interpreted by \bibgls. This typically means that all the |
| 23454 |
\field{name} fields contain unknown commands. This fallback command |
| 23455 |
will use: |
| 23456 |
\begin{codeenv} |
| 23457 |
\ics{glsxtrSetWidestFallback}\marg{2}\margm{glossary list} |
| 23458 |
\end{codeenv} |
| 23459 |
if defined otherwise it will use \ics{glsFindWidestLevelTwo}, which |
| 23460 |
sets the widest name for the \glsdisp{top-levelentry}{top-level} and |
| 23461 |
first two sub-levels across all the listed glossaries. |
| 23462 |
|
| 23463 |
\cssection{bibglssetwidestfortypefallback} |
| 23464 |
|
| 23465 |
\formatdef{bibglssetwidestfortypefallback} |
| 23466 |
This is used by \csopt{set-widest} instead of |
| 23467 |
\gls{bibglssetwidestfortype} |
| 23468 |
when all \field{name} fields end up as an empty string when |
| 23469 |
interpreted by \bibgls. This typically means that all the |
| 23470 |
\field{name} fields contain unknown commands. This fallback command |
| 23471 |
will append \gls{bibglssetwidestfallback} to the glossary preamble |
| 23472 |
for the given type. |
| 23473 |
|
| 23474 |
\cssection{bibglssetwidesttoplevelfallback} |
| 23475 |
|
| 23476 |
\formatdef{bibglssetwidesttoplevelfallback} |
| 23477 |
This is used by \csopt{set-widest} instead of \gls{bibglssetwidest} |
| 23478 |
when all \field{name} fields end up as an empty string when |
| 23479 |
interpreted by \bibgls. This typically means that all the |
| 23480 |
\field{name} fields contain unknown commands. This fallback command |
| 23481 |
will use: |
| 23482 |
\begin{codeenv} |
| 23483 |
\ics{glsxtrSetWidestFallback}\marg{0}\margm{glossary list} |
| 23484 |
\end{codeenv} |
| 23485 |
if defined otherwise it will use \ics{glsFindWidestTopLevelName}, |
| 23486 |
which sets the widest name for the \glsdisp{top-levelentry}{top-level}. |
| 23487 |
|
| 23488 |
\cssection{bibglssetwidesttoplevelfortypefallback} |
| 23489 |
|
| 23490 |
\formatdef{bibglssetwidesttoplevelfortypefallback} |
| 23491 |
This is used by \csopt{set-widest} instead of |
| 23492 |
\gls{bibglssetwidestfortype} |
| 23493 |
when all \field{name} fields end up as an empty string when |
| 23494 |
interpreted by \bibgls. This typically means that all the |
| 23495 |
\field{name} fields contain unknown commands. This fallback command |
| 23496 |
will append \gls{bibglssetwidesttoplevelfallback} to the glossary |
| 23497 |
preamble of the given type. |
| 23498 |
|
| 23499 |
\cssection{bibglscontributorlist} |
| 23500 |
|
| 23501 |
\formatdef{bibglscontributorlist} |
| 23502 |
This is used when \csopt{bibtex-contributor-fields} is set. The |
| 23503 |
definition depends on whether or not \ics{DTLformatlist} has been |
| 23504 |
defined: |
| 23505 |
\begin{codeenv} |
| 23506 |
\ics{ifdef}\cs{DTLformatlist} |
| 23507 |
\marg{\comment{datatool v2.28+} |
| 23508 |
\cs{providecommand}*\marg{\gls{bibglscontributorlist}}[2]\marg{\cs{DTLformatlist}\marg{\idx{param}1}} |
| 23509 |
} |
| 23510 |
\marg{\comment{datatool v2.27 or earlier} |
| 23511 |
\cs{providecommand}*\marg{\gls{bibglscontributorlist}}[2]\marg{\comment{} |
| 23512 |
\ics{def}\cmd{bibgls@sep}\marg{}\comment{} |
| 23513 |
\ics{@for}\cmd{bibgls@item}:=\idx{param}1\cmd{do}\marg{\cmd{bibgls@sep}\cmd{bibgls@item}\cs{def}\cmd{bibgls@sep}\marg{, }}\comment{} |
| 23514 |
} |
| 23515 |
} |
| 23516 |
\end{codeenv} |
| 23517 |
The second argument allows you to provide definitions like: |
| 23518 |
\begin{codeenv} |
| 23519 |
\cs{newcommand}*\marg{\gls{bibglscontributorlist}}[2]\marg{\comment{} |
| 23520 |
\cs{ifcase}\idx{param}2 |
| 23521 |
\cmd{or} |
| 23522 |
name: |
| 23523 |
\cmd{else} |
| 23524 |
names: |
| 23525 |
\cmd{fi} |
| 23526 |
\cs{DTLformatlist}\marg{\idx{param}1}\comment{} |
| 23527 |
} |
| 23528 |
\end{codeenv} |
| 23529 |
|
| 23530 |
\cssection{bibglscontributor} |
| 23531 |
|
| 23532 |
\formatdef{bibglscontributor} |
| 23533 |
This is used when \csopt{bibtex-contributor-fields} is set. The |
| 23534 |
definition depends on the value of \csopt{contributor-order}. Note that if you |
| 23535 |
have multiple resource sets, that option governs the way \bibgls's version of |
| 23536 |
\gls{bibglscontributor} behaves. The definition is written to the \ext{glstex} |
| 23537 |
using \cs{providecommand}, so \LaTeX\ will only pick up the first definition. |
| 23538 |
|
| 23539 |
\cssection{bibglsdatetime} |
| 23540 |
|
| 23541 |
\formatdef{bibglsdatetime} |
| 23542 |
Used to encapsulate date-time fields identified with |
| 23543 |
\csopt{date-time-fields}. |
| 23544 |
Since \gls{bibglsdatetime} requires more than nine arguments, the |
| 23545 |
remaining four arguments are picked up with: |
| 23546 |
\nosecdef{bibglsdatetimeremainder} |
| 23547 |
The default definitions are: |
| 23548 |
\begin{codeenv} |
| 23549 |
\cs{providecommand}\marg{\gls{bibglsdatetime}}[9]\marg{\gls{bibglsdatetimeremainder}} |
| 23550 |
\cs{providecommand}\marg{\gls{bibglsdatetimeremainder}}[4]\marg{\idx{param}4} |
| 23551 |
\end{codeenv} |
| 23552 |
|
| 23553 |
\cssection{bibglsdate} |
| 23554 |
|
| 23555 |
\formatdef{bibglsdate} |
| 23556 |
Used to encapsulate date fields identified with |
| 23557 |
\csopt{date-fields}. |
| 23558 |
The default definition is: |
| 23559 |
\begin{codeenv} |
| 23560 |
\cs{providecommand}\marg{\gls{bibglsdate}}[7]\marg{\idx{param}7} |
| 23561 |
\end{codeenv} |
| 23562 |
|
| 23563 |
\cssection{bibglstime} |
| 23564 |
|
| 23565 |
\formatdef{bibglstime} |
| 23566 |
Used to encapsulate date fields identified with |
| 23567 |
\csopt{time-fields}. |
| 23568 |
The default definition is: |
| 23569 |
\begin{codeenv} |
| 23570 |
\cs{providecommand}\marg{\gls{bibglstime}}[7]\marg{\idx{param}7} |
| 23571 |
\end{codeenv} |
| 23572 |
|
| 23573 |
\cssection{bibglsprimaryprefixlabel} |
| 23574 |
|
| 23575 |
\formatdef{bibglsprimaryprefixlabel} |
| 23576 |
A hook to pick up the \primary\ prefix label (identified with |
| 23577 |
\csopt{label-prefix}) if required. This does nothing by default. If |
| 23578 |
required, this command should be defined before the |
| 23579 |
\igls{resourceset} is loaded. |
| 23580 |
|
| 23581 |
\cssection{bibglsdualprefixlabel} |
| 23582 |
|
| 23583 |
\formatdef{bibglsdualprefixlabel} |
| 23584 |
A hook to pick up the \dual\ prefix label (identified with |
| 23585 |
\csopt{dual-prefix}) if required. This does nothing by default. If |
| 23586 |
required, this command should be defined before the |
| 23587 |
\igls{resourceset} is loaded. |
| 23588 |
|
| 23589 |
\cssection{bibglstertiaryprefixlabel} |
| 23590 |
|
| 23591 |
\formatdef{bibglstertiaryprefixlabel} |
| 23592 |
A hook to pick up the \glsdisp{tertiaryentry}{tertiary} prefix label (identified with |
| 23593 |
\csopt{tertiary-prefix}) if required. This does nothing by default. If |
| 23594 |
required, this command should be defined before the |
| 23595 |
\igls{resourceset} is loaded. |
| 23596 |
|
| 23597 |
\cssection{bibglsexternalprefixlabel} |
| 23598 |
|
| 23599 |
\formatdef{bibglsexternalprefixlabel} |
| 23600 |
A hook to pick up the \meta{n}th external prefix label (identified with |
| 23601 |
\csopt{ext-prefixes}) if required. This does nothing by default and |
| 23602 |
won't be used if the list of external prefixes is empty. If required, |
| 23603 |
this command should be defined before the \igls{resourceset} is |
| 23604 |
loaded. |
| 23605 |
|
| 23606 |
\cssection{bibglshashchar} |
| 23607 |
|
| 23608 |
\formatdef{bibglshashchar} |
| 23609 |
Expands to a literal hash character (\,\idx{hashchar}\,). |
| 23610 |
|
| 23611 |
\cssection{bibglsunderscorechar} |
| 23612 |
|
| 23613 |
\formatdef{bibglsunderscorechar} |
| 23614 |
Expands to a literal underscore character (\,\idx{underscorechar}\,). |
| 23615 |
|
| 23616 |
\cssection{bibglsdollarchar} |
| 23617 |
|
| 23618 |
\formatdef{bibglsdollarchar} |
| 23619 |
Expands to a literal dollar character (\,\idx{dollarchar}\,). |
| 23620 |
|
| 23621 |
\cssection{bibglsampersandchar} |
| 23622 |
|
| 23623 |
\formatdef{bibglsampersandchar} |
| 23624 |
Expands to a literal ampersand character (\,\idx{ampchar}\,). |
| 23625 |
|
| 23626 |
\cssection{bibglscircumchar} |
| 23627 |
|
| 23628 |
\formatdef{bibglscircumchar} |
| 23629 |
Expands to a literal circumflex character (\,\idx{circumchar}\,). |
| 23630 |
|
| 23631 |
\cssection{bibglsaposchar} |
| 23632 |
|
| 23633 |
\formatdef{bibglsaposchar} |
| 23634 |
Expands to a literal apostrophe character (\,\idx{aposchar}\,). |
| 23635 |
This command is only provided if \longarg{replace-quotes} is used. |
| 23636 |
|
| 23637 |
\cssection{bibglsdoublequotechar} |
| 23638 |
|
| 23639 |
\formatdef{bibglsdoublequotechar} |
| 23640 |
Expands to a literal double-quote character (\,\idx{doublequotechar}\,). |
| 23641 |
This command is only provided if \longarg{replace-quotes} is used. |
| 23642 |
|
| 23643 |
\cssection{bibglsuppercase} |
| 23644 |
|
| 23645 |
\formatdef{bibglsuppercase} |
| 23646 |
Converts \meta{text} to \idx{uppercase}. This just uses |
| 23647 |
\ics{glsuppercase} (if \sty{glossaries} v4.50+, |
| 23648 |
\sty{glossaries-extra} v1.49+ and \sty{mfirstuc} v2.08+) |
| 23649 |
or \ics{MakeTextUppercase} by default. |
| 23650 |
|
| 23651 |
\cssection{bibglslowercase} |
| 23652 |
|
| 23653 |
\formatdef{bibglslowercase} |
| 23654 |
Converts \meta{text} to \idx{lowercase}. This just uses |
| 23655 |
\ics{glslowercase} (if \sty{glossaries} v4.50+, |
| 23656 |
\sty{glossaries-extra} v1.49+ and \sty{mfirstuc} v2.08+) |
| 23657 |
\ics{MakeTextLowercase} by default. |
| 23658 |
|
| 23659 |
\cssection{bibglstitlecase} |
| 23660 |
|
| 23661 |
\formatdef{bibglstitlecase} |
| 23662 |
Converts \meta{text} to \idx{titlecase}. This just uses |
| 23663 |
\ics{capitalisewords} by default. |
| 23664 |
|
| 23665 |
\cssection{bibglsfirstuc} |
| 23666 |
|
| 23667 |
\formatdef{bibglsfirstuc} |
| 23668 |
Converts the first letter of \meta{text} to \idx{uppercase}. This just uses |
| 23669 |
\ics{makefirstuc} by default. |
| 23670 |
|
| 23671 |
\cssection{BibGlsNoCaseChange} |
| 23672 |
|
| 23673 |
Behaves as \cs{NoCaseChange} within \bibgls, so it will prevent its argument |
| 23674 |
from being altered by options such as \csopt{short-case-change} or if the |
| 23675 |
interpreter encounters this command within a case-changing command such as |
| 23676 |
\cs{glsuppercase}. However, the definition provided in the \ext{glstex} file |
| 23677 |
simply expands to \meta{text} in the document without adding the command to the |
| 23678 |
case-changing exclusion list so it won't prevent any case-change within |
| 23679 |
the \LaTeX\ document. |
| 23680 |
|
| 23681 |
\cssection{bibglsdefinitionindex} |
| 23682 |
|
| 23683 |
\formatdef{bibglsdefinitionindex} |
| 23684 |
If \csopt{save-definition-index} has been set this command expands to the |
| 23685 |
\gls{definitionindex} of the entry identified by \meta{label}. This |
| 23686 |
command will only be provided in the \ext{glstex} file if |
| 23687 |
\csopt{save-definition-index} has been set. However, the command is |
| 23688 |
always defined by the \texparserlib\ |
| 23689 |
but will expand to empty if the associated resource option hasn't |
| 23690 |
been set. |
| 23691 |
|
| 23692 |
\cssection{bibglsuseindex} |
| 23693 |
|
| 23694 |
\formatdef{bibglsuseindex} |
| 23695 |
If \csopt{save-use-index} has been set this command expands to the |
| 23696 |
\gls{orderofuseindex} of the entry identified by \meta{label}. This |
| 23697 |
command will only be provided in the \ext{glstex} file if |
| 23698 |
\csopt{save-use-index} has been set. However, the command is |
| 23699 |
always defined by the \texparserlib\ |
| 23700 |
but will expand to empty if the associated resource option hasn't |
| 23701 |
been set. |
| 23702 |
|
| 23703 |
\chapter{Converting Existing \iext{tex} to \iext{bib}} |
| 23704 |
\label{sec:tex2bib} |
| 23705 |
\setsecdepth{1} |
| 23706 |
\renewcommand{\cssectioncmd}{\subsubsection} |
| 23707 |
|
| 23708 |
There are some supplementary command line tools provided with |
| 23709 |
\bibgls\ that can convert certain types of data from existing |
| 23710 |
documents to \iext{bib} files: |
| 23711 |
\begin{itemize} |
| 23712 |
\item \idx{convertgls2bib} converts |
| 23713 |
data from commands like \gls{newglossaryentry} to \ext{bib} entry |
| 23714 |
data (see \sectionref{sec:gls2bib}). |
| 23715 |
|
| 23716 |
\item \idx{datatool2bib} converts \sty{datatool} databases to |
| 23717 |
\ext{bib} entry data (see \sectionref{sec:gls2bib}). |
| 23718 |
\end{itemize} |
| 23719 |
|
| 23720 |
These command line tools share the same common switches listed in |
| 23721 |
\sectionref{sec:commonswitches}. Additionally, they share the switches |
| 23722 |
listed in \sectionref{sec:shared2bibswitches}, but they may also |
| 23723 |
have their specific switches, which are described in the relevant |
| 23724 |
section. |
| 23725 |
|
| 23726 |
\begin{important} |
| 23727 |
It's likely that you will need to post-process the \ext{bib} files |
| 23728 |
or at least double-check that the conversion has been performed |
| 23729 |
adequately. |
| 23730 |
\end{important} |
| 23731 |
|
| 23732 |
The \ext{bib} format has case-insensitive field names. However, the |
| 23733 |
source files input by the converter tool typically have |
| 23734 |
case-sensitive labels that correspond to the destination \ext{bib} |
| 23735 |
field. The converter tools will convert the fields to |
| 23736 |
\idx{lowercase} after any mappings have been applied. |
| 23737 |
Use \converterlongarg{field-case} to change this. |
| 23738 |
Additionally, the \ext{bib} format prohibits certain characters in |
| 23739 |
field names and entry labels (such as spaces), so these will be |
| 23740 |
stripped. The resulting field names must be non-empty. |
| 23741 |
|
| 23742 |
The \texparserlib\ is used to parse the input files. The conversion |
| 23743 |
tool may automatically implement the relevant packages (such as |
| 23744 |
\sty{datatool} and \sty{datagidx} for \idx{datatool2bib}). |
| 23745 |
However, the behaviour of some commands may be |
| 23746 |
modified to better suit the conversion process. |
| 23747 |
|
| 23748 |
Note that \ics{IfTeXParserLib} will expand to its first argument, |
| 23749 |
but \ics{IfNotBibGls} will also expand to its first argument, since |
| 23750 |
it's only defined to expand to its second argument by the \bibgls\ |
| 23751 |
interpreter not by the \texparserlib\ core code. |
| 23752 |
|
| 23753 |
Avoid any overly complicated code within the \ext{tex} file. The |
| 23754 |
\texparserlib\ isn't a \TeX\ engine! The input \ext{tex} file |
| 23755 |
doesn't need to be a complete document, but if you want certain |
| 23756 |
commands recognised from packages that the \texparserlib\ supports, |
| 23757 |
you'll need to include \ics{usepackage} in the \ext{tex} file. If |
| 23758 |
you want to quit parsing the \ext{tex} file at the start of the |
| 23759 |
document, use the \converterlongarg{preamble-only} switch. |
| 23760 |
|
| 23761 |
\begin{important} |
| 23762 |
The \texparserlib\ recognises |
| 23763 |
\ics{input} and \ics{include} and so will also parse the referenced |
| 23764 |
file if either command is encountered. |
| 23765 |
If you have multiple files, it's better to pass just the relevant |
| 23766 |
file to the conversion tool rather than the main document file. |
| 23767 |
\end{important} |
| 23768 |
|
| 23769 |
\section{Shared Conversion Tool Switches} |
| 23770 |
\label{sec:shared2bibswitches} |
| 23771 |
|
| 23772 |
\converterarg{texenc} |
| 23773 |
|
| 23774 |
The character \igls{encoding} of the source \ext{tex} file. If omitted, the |
| 23775 |
\idx{JVM}['s] default \gls{encoding} is assumed (which may or |
| 23776 |
may not be the same as the operating system's default). |
| 23777 |
|
| 23778 |
\converterarg{bibenc} |
| 23779 |
|
| 23780 |
The character \igls{encoding} of the \ext{bib} file. If omitted, the same |
| 23781 |
\gls{encoding} as the \ext{tex} file is assumed. |
| 23782 |
|
| 23783 |
\converterarg{space-sub} |
| 23784 |
|
| 23785 |
The \ext{bib} format doesn't allow spaces in labels. If your original |
| 23786 |
definitions in your \ext{tex} file have spaces, use this option to |
| 23787 |
replace spaces in labels. Each space will be substituted with |
| 23788 |
\meta{replacement}. Where applicable, the cross-referencing fields, \field{see}, |
| 23789 |
\field{seealso} and \field{alias}, will also be adjusted, but any |
| 23790 |
references using \ics{gls} etc will have to be substituted manually |
| 23791 |
(or use a global search and replace action in your text editor). |
| 23792 |
If you want to strip the spaces, use an empty string for |
| 23793 |
\meta{replacement}. You'll need to delimit this according to your |
| 23794 |
operating system. For example: |
| 23795 |
\begin{verbatim} |
| 23796 |
convertgls2bib --space-sub '' entries.tex entries.bib |
| 23797 |
\end{verbatim} |
| 23798 |
Alternatively, use \converterlongarg{field-map} to supply an |
| 23799 |
alternative field name. |
| 23800 |
|
| 23801 |
\begin{important} |
| 23802 |
Note that all forbidden punctuation characters |
| 23803 |
(such as commas, equal signs and braces) will be automatically stripped. |
| 23804 |
\end{important} |
| 23805 |
|
| 23806 |
\converterarg{preamble-only} |
| 23807 |
|
| 23808 |
Stop parsing if the start of the \env{document} environment is found. |
| 23809 |
|
| 23810 |
\converterarg{no-preamble-only} |
| 23811 |
|
| 23812 |
Parse the entire file (default). Be prepared for a lot of |
| 23813 |
\qt{unknown command} warnings if you make the conversion tool parse an |
| 23814 |
entire document. |
| 23815 |
|
| 23816 |
\converterarg{overwrite} |
| 23817 |
|
| 23818 |
Allow existing \ext{bib} files to be overwritten. (Default unless |
| 23819 |
otherwise specified.) |
| 23820 |
|
| 23821 |
\converterarg{no-overwrite} |
| 23822 |
|
| 23823 |
Don't allow existing \ext{bib} files to be overwritten. |
| 23824 |
|
| 23825 |
\converterarg{ignore-fields} |
| 23826 |
|
| 23827 |
Omit all the fields listed in \meta{list} from the \ext{bib} file. |
| 23828 |
This option is cumulative. |
| 23829 |
Note that in earlier versions of \idx{convertgls2bib} an empty list |
| 23830 |
cancelled the list of ignored fields. As from version 4.0, you will |
| 23831 |
need to use \converterlongarg{no-ignore-fields} to clear the list. |
| 23832 |
|
| 23833 |
Each item in the list should identify |
| 23834 |
the field by its original case-sensitive key. |
| 23835 |
|
| 23836 |
\converterarg{no-ignore-fields} |
| 23837 |
|
| 23838 |
Cancels the effect of \converterlongarg{ignore-fields}. |
| 23839 |
|
| 23840 |
\converterarg{field-map} |
| 23841 |
|
| 23842 |
Provides a mapping from source labels to the field names used in |
| 23843 |
the destination \ext{bib} file. The argument should be a |
| 23844 |
comma-separated list of \code{\meta{src-label}=\meta{dest-field}} |
| 23845 |
pairs. |
| 23846 |
This option is cumulative. |
| 23847 |
|
| 23848 |
For \idx{convertgls2bib}, the source labels are the keys used in |
| 23849 |
commands such as \gls{newglossaryentry}. These should ordinarily not |
| 23850 |
need any mappings. However, you may, for example, want to convert |
| 23851 |
the user keys to something more appropriate. |
| 23852 |
For \idx{datatool2bib}, the source labels are the column keys. |
| 23853 |
|
| 23854 |
\converterarg{no-field-map} |
| 23855 |
|
| 23856 |
Cancels all field mappings. |
| 23857 |
|
| 23858 |
\converterarg{field-case} |
| 23859 |
|
| 23860 |
Specifies whether or not to change the case of the field name when |
| 23861 |
writing to the \ext{bib} file. Valid \meta{setting}: |
| 23862 |
\optfmt{none} (no case-change), \optfmt{lc} (to \idx{lowercase}, default), |
| 23863 |
\optfmt{uc} (to \idx{uppercase}), \optfmt{title} (to \idx{titlecase}), |
| 23864 |
or \optfmt{sentence} (to \idx{sentencecase}). Note that since spaces |
| 23865 |
aren't permitted in field names, the last two are equivalent. |
| 23866 |
The case-change is applied after mapping. |
| 23867 |
|
| 23868 |
\converterarg{index-conversion} |
| 23869 |
|
| 23870 |
Use \atentry{index} instead of \atentry{entry} if the |
| 23871 |
\field{description} is empty or, for \idx{convertgls2bib}, if the |
| 23872 |
\field{description} is simply \ics{nopostdesc} or |
| 23873 |
\ics{glsxtrnopostpunc}. (Only applies to terms that would otherwise |
| 23874 |
be converted to \atentry{entry}, such as those defined with |
| 23875 |
\gls{newglossaryentry} in the case of \idx{convertgls2bib}.) |
| 23876 |
|
| 23877 |
\converterarg{no-index-conversion} |
| 23878 |
|
| 23879 |
Don't convert \atentry{entry} to \atentry{index} (default). |
| 23880 |
|
| 23881 |
\converterarg{log-file} |
| 23882 |
|
| 23883 |
The log file is optional for the converter applications. It's |
| 23884 |
provided for use with the \texparserlib\ debugging modes |
| 23885 |
(\commonlongarg{debug-mode}) which writes |
| 23886 |
logging information to this file (which can be sizeable). |
| 23887 |
A log file will automatically be created if debugging is enabled, |
| 23888 |
otherwise it will need to be explicitly created with |
| 23889 |
\converterlongarg{log-file} if required. The default name, if |
| 23890 |
automatically created, is the name of the converter application with |
| 23891 |
the \ext{log} file extension. |
| 23892 |
|
| 23893 |
\begin{important} |
| 23894 |
Unlike \bibgls's \longarg{log-file} switch, the conversion |
| 23895 |
tools don't have a corresponding short switch. |
| 23896 |
\end{important} |
| 23897 |
|
| 23898 |
\section{\glsfmttext{idx.convertgls2bib}: Conversion from \styfmt{glossaries} or |
| 23899 |
\styfmt{glossaries-extra}} |
| 23900 |
\label{sec:gls2bib} |
| 23901 |
\setsecdepth{2} |
| 23902 |
|
| 23903 |
If you have already been using the \styfmt{glossaries} or |
| 23904 |
\styfmt{glossaries-extra} package with a large file containing all your |
| 23905 |
definitions using commands like \gls{newglossaryentry}, then you can |
| 23906 |
use the supplementary tool \idx{convertgls2bib} to convert the definitions |
| 23907 |
to the \ext{bib} format required by \bibgls. The syntax is: |
| 23908 |
\begin{alltt} |
| 23909 |
convertgls2bib \oargm{options} \meta{tex file} \meta{bib file} |
| 23910 |
\end{alltt} |
| 23911 |
where \meta{tex file} is the \ext{tex} file and \meta{bib file} is |
| 23912 |
the \ext{bib} file. This application is less secure than \bibgls\ as |
| 23913 |
it doesn't use \idx{kpsewhich} to check \texmfcnf{openinany} and |
| 23914 |
\texmfcnf{openoutany}. Take care not to accidentally overwrite |
| 23915 |
existing \ext{bib} files as there's no check to determine if |
| 23916 |
\meta{bib file} already exists with the default \converterlongarg{overwrite}. |
| 23917 |
|
| 23918 |
If the \ext{bib} extension is missing from \meta{bib file}, it will |
| 23919 |
be added. The extension is required for \meta{tex file}. |
| 23920 |
|
| 23921 |
\subsection{Command Line Arguments} |
| 23922 |
|
| 23923 |
The \meta{options} specific to \idx{convertgls2bib} are described below. |
| 23924 |
This is in addition to those described in \sectionref{sec:commonswitches} |
| 23925 |
and \sectionref{sec:shared2bibswitches}. Note that |
| 23926 |
\convertglsbiblongarg{split-on-type} overrides the default |
| 23927 |
\converterlongarg{overwrite} setting. |
| 23928 |
|
| 23929 |
\convertglsbibarg{ignore-sort} |
| 23930 |
|
| 23931 |
Omit the \field{sort} field. This is the default since \bibgls\ can |
| 23932 |
work out a more intuitive sort value than either \idx!{makeindex} or |
| 23933 |
\idx!{xindy}. |
| 23934 |
This option is automatically set if the \field{sort} field is |
| 23935 |
included in \converterlongarg{ignore-fields}. |
| 23936 |
|
| 23937 |
\convertglsbibarg{no-ignore-sort} |
| 23938 |
|
| 23939 |
Don't ignore the \field{sort} field. |
| 23940 |
|
| 23941 |
\convertglsbibarg{ignore-type} |
| 23942 |
|
| 23943 |
Omit the \field{type} field in the \ext{bib} file. You may find it |
| 23944 |
more flexible not to be locked into a specific glossary type if you |
| 23945 |
have a large database of entries. |
| 23946 |
This option is automatically set if the \field{type} field is |
| 23947 |
included in \converterlongarg{ignore-fields}. |
| 23948 |
|
| 23949 |
\convertglsbibarg{no-ignore-type} |
| 23950 |
|
| 23951 |
Don't omit the \field{type} field (default unless |
| 23952 |
\convertglsbiblongarg{split-on-type}). |
| 23953 |
|
| 23954 |
\convertglsbibarg{ignore-category} |
| 23955 |
|
| 23956 |
Omit the \field{category} field in the \ext{bib} file. |
| 23957 |
This option is automatically set if the \field{category} field is |
| 23958 |
included in \converterlongarg{ignore-fields}. |
| 23959 |
|
| 23960 |
\convertglsbibarg{no-ignore-category} |
| 23961 |
|
| 23962 |
Don't omit the \field{category} field (default unless |
| 23963 |
\convertglsbiblongarg{split-on-category}). |
| 23964 |
|
| 23965 |
\convertglsbibarg{split-on-type} |
| 23966 |
|
| 23967 |
Split the entries into separate files according to the \field{type} |
| 23968 |
field. Any entries that have the \field{type} field set to \ics{glsdefaulttype} |
| 23969 |
or that don't have the \field{type} field set and there's no default provided |
| 23970 |
by the command used to define the entry (see below) then the |
| 23971 |
\atentryfmt{\meta{entry}} data will be written to the main \meta{bib |
| 23972 |
file}. Otherwise entries will be written to the split file |
| 23973 |
(in the same directory as \meta{bib file}). |
| 23974 |
|
| 23975 |
The split file name depends on whether or not the |
| 23976 |
\convertglsbiblongarg{split-on-category} switch has also been used. With both |
| 23977 |
and if the category and field values are different then |
| 23978 |
the file name is \metametafilefmt{}{type}{-}{category}{.bib} otherwise |
| 23979 |
it's \metafilefmt{}{type}{.bib}. |
| 23980 |
|
| 23981 |
Commands that have a default type are as follows: |
| 23982 |
\begin{itemize} |
| 23983 |
\item \gls{newabbreviation}, \gls{newacronym}, \ics{oldacronym}, |
| 23984 |
\gls{newdualentry}: |
| 23985 |
the default type is assumed to be \code{abbreviations} (regardless |
| 23986 |
of the definition of \ics{acronymtype} or \ics{glsxtrabbrvtype}); |
| 23987 |
\item \gls{glsxtrnewsymbol}: the default type is assumed to be \code{symbols}; |
| 23988 |
\item \gls{glsxtrnewnumber}: the default type is assumed to be \code{numbers}; |
| 23989 |
\item \gls{newterm}: the default type is assumed to be \code{index}. |
| 23990 |
\end{itemize} |
| 23991 |
|
| 23992 |
This option automatically implements \convertglsbiblongarg{ignore-type} and |
| 23993 |
\converterlongarg{no-overwrite}. |
| 23994 |
|
| 23995 |
\convertglsbibarg{no-split-on-type} |
| 23996 |
|
| 23997 |
Don't split the entries into separate files according to their type |
| 23998 |
(default). |
| 23999 |
|
| 24000 |
\convertglsbibarg{split-on-category} |
| 24001 |
|
| 24002 |
Split the entries into separate files according to the \field{category}. |
| 24003 |
If the \field{category} field isn't present and there's no default provided |
| 24004 |
by the command used to define the entry (see below) then the |
| 24005 |
\atentryfmt{\meta{entry}} data will be written to the main \meta{bib |
| 24006 |
file}. Otherwise entries will be written to the split file |
| 24007 |
(in the same directory as \meta{bib file}). |
| 24008 |
|
| 24009 |
The split file name depends on whether or not the |
| 24010 |
\convertglsbiblongarg{split-on-type} switch has also been used. With both and |
| 24011 |
if the category and field values are different then |
| 24012 |
the file name is \metametafilefmt{}{type}{}{category}{.bib} otherwise |
| 24013 |
it's \metafilefmt{}{category}{.bib}. |
| 24014 |
|
| 24015 |
Commands that have a default category are as follows: |
| 24016 |
\begin{itemize} |
| 24017 |
\item \gls{newabbreviation}, \gls{newacronym}, \ics{oldacronym}, |
| 24018 |
\gls{newdualentry}: |
| 24019 |
the default category is assumed to be \code{abbreviation}; |
| 24020 |
\item \gls{glsxtrnewsymbol}: the default category is assumed to be \code{symbol}; |
| 24021 |
\item \gls{glsxtrnewnumber}: the default category is assumed to be \code{number}; |
| 24022 |
\item \gls{newterm}: the default category is assumed to be \code{index}. |
| 24023 |
\end{itemize} |
| 24024 |
|
| 24025 |
For example, if you have both \convertglsbiblongarg{split-on-type} and |
| 24026 |
\convertglsbiblongarg{split-on-category}, then the default file name for |
| 24027 |
\gls{newabbreviation} will be |
| 24028 |
\filefmt{abbreviations-abbreviation.bib} but the default file name |
| 24029 |
for \gls{newterm} will be \filefmt{index.bib}. Whereas if you only |
| 24030 |
have \convertglsbiblongarg{split-on-category} and not |
| 24031 |
\convertglsbiblongarg{split-on-type}, then then default file name for |
| 24032 |
\gls{newabbreviation} will be \filefmt{abbreviation.bib}. |
| 24033 |
|
| 24034 |
This option automatically implements \convertglsbiblongarg{ignore-category} and |
| 24035 |
\converterlongarg{no-overwrite}. |
| 24036 |
|
| 24037 |
\convertglsbibarg{no-split-on-category} |
| 24038 |
|
| 24039 |
Don't split the entries into separate files according to their |
| 24040 |
category (default). |
| 24041 |
|
| 24042 |
|
| 24043 |
\convertglsbibarg{absorb-see} |
| 24044 |
|
| 24045 |
Absorb any cross-referencing information identified with |
| 24046 |
\ics{glssee} or \ics{glsxtrindexseealso} commands into |
| 24047 |
the corresponding entry (default). |
| 24048 |
|
| 24049 |
\convertglsbibarg{no-absorb-see} |
| 24050 |
|
| 24051 |
Don't absorb any cross-referencing information identified with \ics{glssee} |
| 24052 |
or \ics{glsxtrindexseealso} commands. |
| 24053 |
|
| 24054 |
\convertglsbibarg{internal-field-map} |
| 24055 |
|
| 24056 |
Appends the given internal field to key mappings to the predefined |
| 24057 |
list. This action is cumulative. The mappings are needed for |
| 24058 |
\gls{glssetexpandfield} and \gls{glssetnoexpandfield}, which use |
| 24059 |
\idx{internalfields} for their arguments. |
| 24060 |
Note that this is different from \converterlongarg{field-map} which |
| 24061 |
maps the key used in commands like \gls{newglossaryentry} to |
| 24062 |
the corresponding field label written the \ext{bib} file. |
| 24063 |
|
| 24064 |
\subsection{Recognised Commands} |
| 24065 |
|
| 24066 |
The \idx{convertgls2bib} application recognises the commands listed below as well as |
| 24067 |
some standard commands such as \ics{newcommand}. The \texparserlib\ |
| 24068 |
is instructed to skip its usual implementation of the |
| 24069 |
\sty{glossaries} and \sty{glossaries-extra} packages as only a |
| 24070 |
limited set of commands need to be defined. |
| 24071 |
|
| 24072 |
In all cases below, if \meta{\keyvallist} contains: |
| 24073 |
\begin{codeenv*} |
| 24074 |
\field{see}=\marg{[\ics{seealsoname}]\meta{label(s)}} |
| 24075 |
\end{codeenv*} |
| 24076 |
or |
| 24077 |
\begin{codeenv*} |
| 24078 |
\field{see}=\marg{[\ics{alsoname}]\meta{label(s)}} |
| 24079 |
\end{codeenv*} |
| 24080 |
this will be substituted with: |
| 24081 |
\begin{codeenv*} |
| 24082 |
\field{seealso}=\margm{label(s)} |
| 24083 |
\end{codeenv*} |
| 24084 |
For example: |
| 24085 |
\begin{codeenv} |
| 24086 |
\gls{newterm}\oarg{\field{see}=\marg{[\cs{seealsoname}]goose}}\marg{duck} |
| 24087 |
\end{codeenv} |
| 24088 |
will be written as: |
| 24089 |
\begin{codeenv} |
| 24090 |
\atentry{index}\marg{duck, |
| 24091 |
\field{seealso} = \marg{goose} |
| 24092 |
} |
| 24093 |
\end{codeenv} |
| 24094 |
Note that it won't convert \code{\field{see}=\marg{[see also]\meta{labels}}}. |
| 24095 |
If you have used explicit text instead of \ics{seealsoname} or |
| 24096 |
\ics{alsoname} then consider performing a global search and replace |
| 24097 |
on your file using your text editor. |
| 24098 |
|
| 24099 |
Additionally, if \meta{\keyvallist} contains: |
| 24100 |
\begin{codeenv} |
| 24101 |
\field{type}=\marg{\ics{glsdefaulttype}} |
| 24102 |
\end{codeenv} |
| 24103 |
then this field will be ignored. (This \field{type} value is |
| 24104 |
recommended in \meta{\keyvallist} when loading files with |
| 24105 |
\gls{loadglsentries}\oargm{type}\margm{file} to allow the optional |
| 24106 |
argument to set the \field{type}. With \bibgls\ you can use the |
| 24107 |
\csopt{type} option instead.) |
| 24108 |
|
| 24109 |
\cssection{glsexpandfields} |
| 24110 |
The base \styfmt{glossaries} package provides: |
| 24111 |
\formatdef{glsexpandfields} |
| 24112 |
If present, this instructs \idx{convertgls2bib} to expand all fields |
| 24113 |
except for those explicitly identified by \gls{glssetnoexpandfield}. |
| 24114 |
Remember that there are many commands that aren't recognised by |
| 24115 |
\idx{convertgls2bib} so it may not be possible to correctly expand |
| 24116 |
field values. Conversely, there are some commands that will be |
| 24117 |
expanded by \idx{convertgls2bib} that aren't expandable in \TeX\ |
| 24118 |
(such as \ics{MakeUppercase} and \ics{char}). |
| 24119 |
|
| 24120 |
\cssection{glsnoexpandfields} |
| 24121 |
The base \styfmt{glossaries} package provides: |
| 24122 |
\formatdef{glsnoexpandfields} |
| 24123 |
If present, this instructs \idx{convertgls2bib} to not expand fields |
| 24124 |
unless explicitly identified by \gls{glssetexpandfield}. |
| 24125 |
|
| 24126 |
\cssection{glssetexpandfield} |
| 24127 |
The base \styfmt{glossaries} package provides: |
| 24128 |
\formatdef{glssetexpandfield} |
| 24129 |
If present, this instructs \idx{convertgls2bib} to expand the |
| 24130 |
given field, even if \gls{glsnoexpandfields} has been used. |
| 24131 |
Note that the argument should be the internal field label. |
| 24132 |
The default set of mappings are recognised. Any additional mappings |
| 24133 |
will need to be added with |
| 24134 |
\convertglsbiblongarg{internal-field-map}. |
| 24135 |
|
| 24136 |
\cssection{glssetnoexpandfield} |
| 24137 |
The base \styfmt{glossaries} package provides: |
| 24138 |
\formatdef{glssetnoexpandfield} |
| 24139 |
If present, this instructs \idx{convertgls2bib} to not expand the |
| 24140 |
given field, even if \gls{glsexpandfields} has been used. |
| 24141 |
Unlike the default behaviour with the \sty{glossaries} package, there are no |
| 24142 |
fields explicitly switched off by default with \idx{convertgls2bib}. |
| 24143 |
|
| 24144 |
\cssection{loadglsentries} |
| 24145 |
The base \styfmt{glossaries} package provides: |
| 24146 |
\formatdef{loadglsentries} |
| 24147 |
This locally redefines \ics{glsdefaulttype} to \meta{type} (if the optional argument is supplied) |
| 24148 |
and inputs \meta{file}. If the \meta{file} doesn't have an extension, \ext{tex} is assumed. |
| 24149 |
(The \texparserlib\ also recognises \ics{input}.) |
| 24150 |
|
| 24151 |
In general, it's better to simply use \meta{file} as the source file |
| 24152 |
when running \idx{convertgls2bib} instead of using the main document |
| 24153 |
file as the source. |
| 24154 |
|
| 24155 |
\cssection{newglossaryentry} |
| 24156 |
The base \styfmt{glossaries} package provides: |
| 24157 |
\formatdef{newglossaryentry} |
| 24158 |
This is converted to: |
| 24159 |
\begin{codeenv} |
| 24160 |
\atentry{entry}\marg{\meta{label}, |
| 24161 |
\meta{\keyvallist} |
| 24162 |
} |
| 24163 |
\end{codeenv} |
| 24164 |
\ics{newentry} is recognised as a synonym of \gls{newglossaryentry}. |
| 24165 |
|
| 24166 |
\cssection{provideglossaryentry} |
| 24167 |
The base \styfmt{glossaries} package provides: |
| 24168 |
\formatdef{provideglossaryentry} |
| 24169 |
This is converted to: |
| 24170 |
\begin{codeenv} |
| 24171 |
\atentry{entry}\marg{\meta{label}, |
| 24172 |
\meta{\keyvallist} |
| 24173 |
} |
| 24174 |
\end{codeenv} |
| 24175 |
but only if \meta{label} hasn't already been defined. |
| 24176 |
|
| 24177 |
\cssection{longnewglossaryentry} |
| 24178 |
The base \styfmt{glossaries} package provides: |
| 24179 |
\formatdef{longnewglossaryentry} |
| 24180 |
This is converted to: |
| 24181 |
\begin{codeenv} |
| 24182 |
\atentry{entry}\marg{\meta{label}, |
| 24183 |
\meta{\keyvallist}, |
| 24184 |
\field{description} = \margm{description} |
| 24185 |
} |
| 24186 |
\end{codeenv} |
| 24187 |
The starred version provided by the \styfmt{glossaries-extra} package |
| 24188 |
is also recognised. The unstarred version strips trailing spaces |
| 24189 |
from \meta{description}. (This doesn't add \ics{nopostdesc}, but |
| 24190 |
\styfmt{glossaries-extra} defaults to \styopt{nopostdot}.) |
| 24191 |
|
| 24192 |
\cssection{longprovideglossaryentry} |
| 24193 |
|
| 24194 |
The base \styfmt{glossaries} package provides: |
| 24195 |
\formatdef{longprovideglossaryentry} |
| 24196 |
As above, but only if \meta{label} hasn't already been defined. |
| 24197 |
|
| 24198 |
\cssection{newterm} |
| 24199 |
|
| 24200 |
The base \styfmt{glossaries} package provides: |
| 24201 |
\formatdef{newterm} |
| 24202 |
(when the \styopt{index} option is used). |
| 24203 |
This is converted to: |
| 24204 |
\begin{codeenv} |
| 24205 |
\atentry{index}\marg{\meta{label}, |
| 24206 |
\meta{\keyvallist} |
| 24207 |
} |
| 24208 |
\end{codeenv} |
| 24209 |
if the optional argument is present, otherwise it's just converted |
| 24210 |
to: |
| 24211 |
\begin{codeenv} |
| 24212 |
\atentry{index}\marg{\meta{label}} |
| 24213 |
\end{codeenv} |
| 24214 |
|
| 24215 |
If \converterlongarg{space-sub} is used and \meta{label} contains one or |
| 24216 |
more spaces, then \field{name} will be set if not included in |
| 24217 |
\meta{\keyvallist}. For example, if \filefmt{entries.bib} |
| 24218 |
contains: |
| 24219 |
\begin{codeenv} |
| 24220 |
\gls{newterm}\marg{sea lion} |
| 24221 |
\gls{newterm}\oarg{\field{seealso}=\marg{sea lion}}\marg{seal} |
| 24222 |
\end{codeenv} |
| 24223 |
then: |
| 24224 |
\begin{verbatim} |
| 24225 |
convertgls2bib --space-sub '-' entries.bib entries.tex |
| 24226 |
\end{verbatim} |
| 24227 |
will write the terms to \filefmt{entries.tex} as: |
| 24228 |
\begin{codeenv} |
| 24229 |
\atentry{index}\marg{sea-lion, |
| 24230 |
\field{name} = \marg{sea lion} |
| 24231 |
} |
| 24232 |
\strut |
| 24233 |
\atentry{index}\marg{seal, |
| 24234 |
\field{seealso} = \marg{sea-lion} |
| 24235 |
} |
| 24236 |
\end{codeenv} |
| 24237 |
whereas just: |
| 24238 |
\begin{verbatim} |
| 24239 |
convertgls2bib entries.bib entries.tex |
| 24240 |
\end{verbatim} |
| 24241 |
will write the terms to \filefmt{entries.tex} as: |
| 24242 |
\begin{codeenv} |
| 24243 |
\atentry{index}\marg{sea lion} |
| 24244 |
\strut |
| 24245 |
\atentry{index}\marg{seal, |
| 24246 |
\field{seealso} = \marg{sea lion} |
| 24247 |
} |
| 24248 |
\end{codeenv} |
| 24249 |
which will cause a problem when the \ext{bib} file is parsed |
| 24250 |
by \bibgls\ (and will probably also cause a problem for |
| 24251 |
bibliographic management systems). |
| 24252 |
|
| 24253 |
\cssection{newabbreviation} |
| 24254 |
The \styfmt{glossaries-extra} package provides: |
| 24255 |
\formatdef{newabbreviation} |
| 24256 |
This is converted to: |
| 24257 |
\begin{codeenv} |
| 24258 |
\atentry{abbreviation}\marg{\meta{label}, |
| 24259 |
\field{short} = \margm{short}, |
| 24260 |
\field{long} = \margm{long}, |
| 24261 |
\meta{\keyvallist} |
| 24262 |
} |
| 24263 |
\end{codeenv} |
| 24264 |
if the optional argument is present, otherwise it's converted to: |
| 24265 |
\begin{codeenv} |
| 24266 |
\atentry{abbreviation}\marg{\meta{label}, |
| 24267 |
\field{short} = \margm{short}, |
| 24268 |
\field{long} = \margm{long} |
| 24269 |
} |
| 24270 |
\end{codeenv} |
| 24271 |
|
| 24272 |
\cssection{newacronym} |
| 24273 |
The base \styfmt{glossaries} package provides: |
| 24274 |
\formatdef{newacronym} |
| 24275 |
(which is redefined by \styfmt{glossaries-extra} to use |
| 24276 |
\gls{newabbreviation}). |
| 24277 |
|
| 24278 |
As above but uses \atentry{acronym} instead. The base package also |
| 24279 |
provides \ics{oldacronym}, which emulates the way abbreviations were |
| 24280 |
defined with the precursor \styfmt{glossary} package. This has |
| 24281 |
different syntax to \gls{newacronym} but is also recognised by \idx{convertgls2bib} |
| 24282 |
and is converted to \atentry{acronym}. |
| 24283 |
|
| 24284 |
\cssection{glsxtrnewsymbol} |
| 24285 |
The \styfmt{glossaries-extra} package provides: |
| 24286 |
\formatdef{glsxtrnewsymbol} |
| 24287 |
(when the \styopt{symbols} option is used). |
| 24288 |
This is converted to: |
| 24289 |
\begin{codeenv} |
| 24290 |
\atentry{symbol}\marg{\meta{label}, |
| 24291 |
\field{name} = \margm{symbol} |
| 24292 |
} |
| 24293 |
\end{codeenv} |
| 24294 |
if the optional argument is missing, otherwise it's converted to: |
| 24295 |
\begin{codeenv} |
| 24296 |
\atentry{symbol}\marg{\meta{label}, |
| 24297 |
\field{name} = \margm{symbol}, |
| 24298 |
\meta{\keyvallist} |
| 24299 |
} |
| 24300 |
\end{codeenv} |
| 24301 |
unless \meta{\keyvallist} contains the \field{name} field, |
| 24302 |
in which case it's converted to: |
| 24303 |
\begin{codeenv} |
| 24304 |
\atentry{symbol}\marg{\meta{label}, |
| 24305 |
\meta{\keyvallist} |
| 24306 |
} |
| 24307 |
\end{codeenv} |
| 24308 |
\ics{newsym} is recognised as a synonym for \gls{glsxtrnewsymbol}. |
| 24309 |
|
| 24310 |
\cssection{glsxtrnewnumber} |
| 24311 |
|
| 24312 |
The \styfmt{glossaries-extra} package provides: |
| 24313 |
\formatdef{glsxtrnewnumber} |
| 24314 |
(when the \styopt{numbers} option is used). |
| 24315 |
This is converted to: |
| 24316 |
\begin{codeenv} |
| 24317 |
\atentry{number}\marg{\meta{label}, |
| 24318 |
\field{name} = \margm{label} |
| 24319 |
} |
| 24320 |
\end{codeenv} |
| 24321 |
if the optional argument is missing, otherwise it's converted to: |
| 24322 |
\begin{codeenv} |
| 24323 |
\atentry{number}\marg{\meta{label}, |
| 24324 |
\field{name} = \margm{label}, |
| 24325 |
\meta{\keyvallist} |
| 24326 |
} |
| 24327 |
\end{codeenv} |
| 24328 |
if \field{name} isn't listed in \meta{\keyvallist}, |
| 24329 |
otherwise it's converted to: |
| 24330 |
\begin{codeenv} |
| 24331 |
\atentry{number}\marg{\meta{label}, |
| 24332 |
\meta{\keyvallist} |
| 24333 |
} |
| 24334 |
\end{codeenv} |
| 24335 |
\ics{newnum} is recognised as a synonym for \gls{glsxtrnewnumber}. |
| 24336 |
|
| 24337 |
\cssection{newdualentry} |
| 24338 |
|
| 24339 |
\formatdef{newdualentry} |
| 24340 |
This command isn't provided by either \styfmt{glossaries} or |
| 24341 |
\styfmt{glossaries-extra} but is used as an example in the |
| 24342 |
\sty{glossaries} user manual~\cite{glossaries} and in the sample file |
| 24343 |
\file{sample-dual.tex} that accompanies the \sty{glossaries} |
| 24344 |
package. Since this command seems to be used quite a bit (given the |
| 24345 |
number of times it crops up on sites like |
| 24346 |
\href{https://tex.stackexchange.com/}{\TeX\ on StackExchange}), |
| 24347 |
\idx{convertgls2bib} also supports it unless this command is |
| 24348 |
defined using \ics{newcommand} or \ics{renewcommand} in the |
| 24349 |
input file. In which case the default definition will be overridden. |
| 24350 |
|
| 24351 |
If the command definition isn't overridden, then it's converted to: |
| 24352 |
\begin{codeenv} |
| 24353 |
\atentry{dualabbreviationentry}\marg{\meta{label}, |
| 24354 |
\field{short} = \margm{short}, |
| 24355 |
\field{long} = \margm{long}, |
| 24356 |
\field{description} = \margm{description}, |
| 24357 |
\meta{\keyvallist} |
| 24358 |
} |
| 24359 |
\end{codeenv} |
| 24360 |
if \meta{\keyvallist} is supplied, otherwise it's converted to: |
| 24361 |
\begin{codeenv} |
| 24362 |
\atentry{dualabbreviationentry}\marg{\meta{label}, |
| 24363 |
\field{short} = \margm{short}, |
| 24364 |
\field{long} = \margm{long}, |
| 24365 |
\field{description} = \margm{description} |
| 24366 |
} |
| 24367 |
\end{codeenv} |
| 24368 |
|
| 24369 |
For example, if the original \ext{tex} file contains: |
| 24370 |
\begin{codeenv} |
| 24371 |
\cs{newcommand}*\marg{\gls{newdualentry}}[5][]\marg{\comment{} |
| 24372 |
\gls{newglossaryentry}\marg{main-\idx{param}2}\marg{\field{name}=\marg{\idx{param}4},\comment{} |
| 24373 |
\field{text}=\marg{\idx{param}3\cs{glsadd}\marg{\idx{param}2}},\comment{} |
| 24374 |
\field{description}=\marg{\idx{param}5},\comment{} |
| 24375 |
\idx{param}1 |
| 24376 |
}\comment{} |
| 24377 |
\gls{newacronym}\marg{\idx{param}2}\marg{\idx{param}3\cs{glsadd}\marg{main-\idx{param}2}}\marg{\idx{param}4}\comment{} |
| 24378 |
} |
| 24379 |
\strut |
| 24380 |
\gls{newdualentry}\marg{svm}\comment{label} |
| 24381 |
\marg{SVM}\comment{abbreviation} |
| 24382 |
\marg{support vector machine}\comment{long form} |
| 24383 |
\marg{Statistical pattern recognition technique}\comment{description} |
| 24384 |
\end{codeenv} |
| 24385 |
then the \ext{bib} file will contain: |
| 24386 |
\begin{codeenv} |
| 24387 |
\atentry{entry}\marg{main-svm, |
| 24388 |
\field{name} = \marg{support vector machine}, |
| 24389 |
\field{description} = \marg{Statistical pattern recognition technique}, |
| 24390 |
\field{text} = \marg{SVM\cs{glsadd}\marg{svm}} |
| 24391 |
} |
| 24392 |
\strut |
| 24393 |
\atentry{acronym}\marg{svm, |
| 24394 |
\field{short} = \marg{SVM\cs{glsadd}\marg{main-svm}}, |
| 24395 |
\field{long} = \marg{support vector machine} |
| 24396 |
} |
| 24397 |
\end{codeenv} |
| 24398 |
since \gls{newdualentry} was defined with \ics{newcommand}. However, |
| 24399 |
if the original file uses \ics{providecommand} or omits the |
| 24400 |
definition of \gls{newdualentry}, then the \ext{bib} file will |
| 24401 |
contain: |
| 24402 |
\begin{codeenv} |
| 24403 |
\atentry{dualabbreviationentry}\marg{svm, |
| 24404 |
\field{short} = \marg{SVM}, |
| 24405 |
\field{description} = \marg{Statistical pattern recognition technique}, |
| 24406 |
\field{long} = \marg{support vector machine} |
| 24407 |
} |
| 24408 |
\end{codeenv} |
| 24409 |
|
| 24410 |
\section{\glsfmttext{idx.datatool2bib}: Conversion from |
| 24411 |
\styfmt{datatool}} |
| 24412 |
\label{sec:datatool2bib} |
| 24413 |
|
| 24414 |
A \isty{datatool} database can be converted to a \ext{bib} file |
| 24415 |
with the supplementary tool \idx{datatool2bib}. The syntax is: |
| 24416 |
\begin{alltt} |
| 24417 |
datatool2bib \oargm{options} \meta{tex file} \meta{bib file} |
| 24418 |
\end{alltt} |
| 24419 |
where \meta{tex file} is the \ext{tex} file and \meta{bib file} is |
| 24420 |
the \ext{bib} file. This application is less secure than \bibgls\ as |
| 24421 |
it doesn't use \idx{kpsewhich} to check \texmfcnf{openinany} and |
| 24422 |
\texmfcnf{openoutany}. Take care not to accidentally overwrite |
| 24423 |
existing \ext{bib} files as there's no check to determine if |
| 24424 |
\meta{bib file} already exists with the default \converterlongarg{overwrite}. |
| 24425 |
|
| 24426 |
This tool is primarily intended to convert \sty{datagidx} databases, |
| 24427 |
so it will automatically assume that \sty{datagidx} is loaded. |
| 24428 |
It can, however, be used for general databases, but you will need to |
| 24429 |
choose an appropriate column with unique values for the entry label (with |
| 24430 |
\datatoolbiblongarg{label} or use \datatoolbiblongarg{auto-label}). |
| 24431 |
|
| 24432 |
The \meta{tex file} may be a complete document (in which case, you |
| 24433 |
may want to use \converterlongarg{preamble-only} if the database |
| 24434 |
commands are all in the preamble) or may be a file that just |
| 24435 |
contains the database construction commands. The conversion tool |
| 24436 |
uses the \texparserlib\ which has some limited support for |
| 24437 |
\sty{datatool}, including database construction commands and file |
| 24438 |
input commands \ics{DTLloaddb}, \ics{DTLloaddbtex} and the newer |
| 24439 |
\gls{DTLread}. |
| 24440 |
|
| 24441 |
For example, suppose I have a document file called |
| 24442 |
\filefmt{myDoc.tex} that contains: |
| 24443 |
\begin{codeenv} |
| 24444 |
\csfmt{documentclass}\marg{article} |
| 24445 |
\csfmt{usepackage}\marg{datatool} |
| 24446 |
\gls{DTLnewdb}\marg{mydata} |
| 24447 |
\gls{DTLnewrow}\marg{mydata} |
| 24448 |
\gls{DTLnewdbentry}\marg{mydata}\marg{Forename}\marg{John} |
| 24449 |
\gls{DTLnewdbentry}\marg{mydata}\marg{Surname}\marg{Smith} |
| 24450 |
\comment{...} |
| 24451 |
\cmd{begin}\marg{document} |
| 24452 |
\comment{...} |
| 24453 |
\cmd{end}\marg{document} |
| 24454 |
\end{codeenv} |
| 24455 |
Then I can extract this data with: |
| 24456 |
\begin{codeenv} |
| 24457 |
datatool2bib \converterlongarg{preamble-only} myDoc.tex mydata.bib |
| 24458 |
\end{codeenv} |
| 24459 |
If the database commands are instead in a separate file called, say, |
| 24460 |
\filefmt{mydata.tex} which is simply input in \filefmt{myDoc.tex} |
| 24461 |
then \filefmt{mydata.tex} can then be used for the \meta{tex file} |
| 24462 |
input file: |
| 24463 |
\begin{verbatim} |
| 24464 |
datatool2bib mydata.tex mydata.bib |
| 24465 |
\end{verbatim} |
| 24466 |
Note that the \texparserlib\ also recognises commands such as |
| 24467 |
\gls{dtlexpandnewvalue}. If this is in \filefmt{myDoc.tex} rather |
| 24468 |
than in \filefmt{mydata.tex} and only \filefmt{mydata.tex} is parsed |
| 24469 |
then the \texparserlib\ won't encounter \gls{dtlexpandnewvalue} and |
| 24470 |
so won't enable new value expansion. You can, however, use |
| 24471 |
\code{\datatoolbiblongarg{setup} expand-new-value} to switch on new |
| 24472 |
value expansion. |
| 24473 |
|
| 24474 |
If the data source is in a CSV file, then the \texparserlib\ can |
| 24475 |
parse it but only if the file is referenced in \ics{DTLloaddb} (pre |
| 24476 |
\sty{datatool} v3.0) or \gls{DTLread} (\sty{datatool} v3.0+). |
| 24477 |
For the newer \gls{DTLread} command, the \code{format=\iext{csv}} setting is |
| 24478 |
required to parse CSV files or \code{format=\iext{tsv}} for TSV files. |
| 24479 |
If the file contains \LaTeX\ commands, \code{content=tex} is |
| 24480 |
required otherwise \code{content=literal} is required. |
| 24481 |
|
| 24482 |
So in order to convert a CSV file called \filefmt{mydata.csv} to |
| 24483 |
a \ext{bib} file, the \texparserlib\ needs to parse: |
| 24484 |
\begin{codeenv} |
| 24485 |
\gls{DTLread}\oarg{format=csv,content=literal}\marg{mydata.csv} |
| 24486 |
\end{codeenv} |
| 24487 |
Rather than having to parse the entire document source file or |
| 24488 |
create a stub file that simply contains this command, you can use |
| 24489 |
the \datatoolbiblongarg{read} switch instead: |
| 24490 |
\begin{codeenv} |
| 24491 |
datatool2bib \datatoolbiblongarg{read} format=csv,content=literal mydata.csv mydata.bib |
| 24492 |
\end{codeenv} |
| 24493 |
This is equivalent to creating a stub file with just the |
| 24494 |
\gls{DTLread} line. |
| 24495 |
|
| 24496 |
In general, better results are obtained if \idx{datatool2bib} parses |
| 24497 |
\gls{datagidx.newterm} and \gls{datagidx.newacro} instead of the |
| 24498 |
actual \sty{datagidx} databases. The custom \sty{datagidx} databases |
| 24499 |
have a number of columns for internal use that are not applicable to |
| 24500 |
\bibgls. |
| 24501 |
|
| 24502 |
When you run \idx{datatool2bib} from the command line, there will be |
| 24503 |
two lines reporting the number of databases found by parsing the |
| 24504 |
input. For example: |
| 24505 |
\begin{verbatim} |
| 24506 |
1 database (datatool) found |
| 24507 |
0 databases (datagidx) found |
| 24508 |
\end{verbatim} |
| 24509 |
The first line indicates the number of regular \sty{datatool} |
| 24510 |
databases that were found by the \texparserlib. The second line |
| 24511 |
indicates the number of \sty{datagidx} databases that were detected |
| 24512 |
by scanning for \gls{datagidx.newterm} and \gls{datagidx.newacro}. |
| 24513 |
|
| 24514 |
In the first case, the source field labels will correspond to the |
| 24515 |
column keys (such as \optfmt{Label}, \optfmt{Name}, |
| 24516 |
\optfmt{Description} and \optfmt{Symbol}), whereas in the second |
| 24517 |
case the source field labels will correspond to the option keys for |
| 24518 |
\gls{datagidx.newterm} and \gls{datagidx.newacro} (such as \optfmt{description} and |
| 24519 |
\optfmt{symbol}, but not the \optfmt{label} key, which will be |
| 24520 |
dropped from the list after its value is saved elsewhere). |
| 24521 |
|
| 24522 |
\subsection{Command Line Arguments} |
| 24523 |
|
| 24524 |
The \meta{options} specific to \idx{datatool2bib} are described below. |
| 24525 |
This is in addition to those described in \sectionref{sec:commonswitches} |
| 24526 |
and \sectionref{sec:shared2bibswitches}. |
| 24527 |
|
| 24528 |
\datatoolbibarg{label} |
| 24529 |
|
| 24530 |
Obtain the \ext{bib} entry label from the column identified by the |
| 24531 |
\meta{column-key}. Note that the column key is the original |
| 24532 |
case-sensitive column label not the mapped field. |
| 24533 |
The label will be obtained by copying the value from the given |
| 24534 |
column and processing according to \converterlongarg{space-sub} |
| 24535 |
(and stripping forbidden characters). This option is not applicable |
| 24536 |
to \gls{datagidx.newterm} and \gls{datagidx.newacro}. |
| 24537 |
|
| 24538 |
\begin{important} |
| 24539 |
The chosen column should have unique values (and should still be |
| 24540 |
unique after processing). |
| 24541 |
\end{important} |
| 24542 |
|
| 24543 |
The default setting is \code{\datatoolbiblongarg{label} Label} |
| 24544 |
since this is the column used for labels with \styfmt{datagidx} (but |
| 24545 |
is only applicable if you save the database with \cs{DTLwrite} |
| 24546 |
rather than having \idx{datatool2bib} parse \gls{datagidx.newterm} |
| 24547 |
and \gls{datagidx.newacro}). |
| 24548 |
|
| 24549 |
If you are converting a general \sty{datatool} database, either |
| 24550 |
choose a different column or switch on the auto label. |
| 24551 |
|
| 24552 |
\datatoolbibarg{auto-label} |
| 24553 |
|
| 24554 |
If there is no appropriate column for a label, this option may be |
| 24555 |
used to automatically generate the label in the form |
| 24556 |
\meta{prefix}\meta{n}. If |
| 24557 |
\datatoolbiblongarg{auto-label-prefix} is set, that will provide the |
| 24558 |
\meta{prefix}, otherwise the prefix will match the database label. |
| 24559 |
|
| 24560 |
\datatoolbibarg{no-auto-label} |
| 24561 |
|
| 24562 |
Switches off automatic labelling. The labels will be created from |
| 24563 |
the column identified by \datatoolbiblongarg{label}. |
| 24564 |
|
| 24565 |
\datatoolbibarg{auto-label-prefix} |
| 24566 |
|
| 24567 |
Sets the prefix for use with \datatoolbiblongarg{auto-label}. |
| 24568 |
This option automatically implements |
| 24569 |
\datatoolbiblongarg{auto-label}. |
| 24570 |
|
| 24571 |
\datatoolbibarg{read} |
| 24572 |
|
| 24573 |
Instead of parsing the provided \ext{tex} file in the usual manner, |
| 24574 |
the \datatoolbiblongarg{read} option will act as though the input |
| 24575 |
is: |
| 24576 |
\begin{codeenv} |
| 24577 |
\gls+{DTLread}\oargm{options}\marg{filename} |
| 24578 |
\end{codeenv} |
| 24579 |
where \meta{filename} is the input filename supplied to |
| 24580 |
\idx{datatool2bib}. This can be use where the source file is a |
| 24581 |
CSV file rather than a \LaTeX\ file. |
| 24582 |
|
| 24583 |
\datatoolbibarg{setup} |
| 24584 |
Implements \code{\gls{DTLsetup}\margm{options}} before parsing. |
| 24585 |
Note that this can be counteracted by any changes to the settings |
| 24586 |
within the file being parsed. |
| 24587 |
|
| 24588 |
\datatoolbibarg{save-datum} |
| 24589 |
Equivalent to: |
| 24590 |
\begin{codeenv} |
| 24591 |
\datatoolbiblongarg{save-value} "-value" \datatoolbiblongarg{save-currency} "-currency" |
| 24592 |
\end{codeenv} |
| 24593 |
For example, if the CSV file |
| 24594 |
\filefmt{products.csv} contains: |
| 24595 |
\begin{alltt} |
| 24596 |
ID,Product,Quantity,Price |
| 24597 |
1,Sample,3,"\$1,234.50" |
| 24598 |
\end{alltt} |
| 24599 |
then with: |
| 24600 |
\begin{codeenv} |
| 24601 |
datatool2bib \datatoolbiblongarg{label} Product \datatoolbiblongarg{read} "format=csv,content=literal" products.csv products.bib |
| 24602 |
\end{codeenv} |
| 24603 |
The \filefmt{products.bib} file will contain: |
| 24604 |
\begin{codeenv} |
| 24605 |
\atentry{entry}\marg{Sample, |
| 24606 |
\fieldfmt{id} = \marg{1}, |
| 24607 |
\fieldfmt{product} = \marg{Sample}, |
| 24608 |
\fieldfmt{quantity} = \marg{3}, |
| 24609 |
\fieldfmt{price} = \marg{\cs{cs.dollar}1,234.5} |
| 24610 |
} |
| 24611 |
\end{codeenv} |
| 24612 |
Whereas with: |
| 24613 |
\begin{codeenv} |
| 24614 |
datatool2bib \datatoolbiblongarg{save-datum} \datatoolbiblongarg{label} Product \datatoolbiblongarg{read} "format=csv,content=literal" products.csv products.bib |
| 24615 |
\end{codeenv} |
| 24616 |
\begin{codeenv} |
| 24617 |
\atentry{entry}\marg{Sample, |
| 24618 |
\fieldfmt{id} = \marg{1}, |
| 24619 |
\fieldfmt{product} = \marg{Sample}, |
| 24620 |
\fieldfmt{quantity} = \marg{3}, |
| 24621 |
\fieldfmt{price} = \marg{\cs{cs.dollar}1,234.5}, |
| 24622 |
\fieldfmt{price-value} = \marg{1234.5}, |
| 24623 |
\fieldfmt{price-currency} = \marg{\cs{cs.dollar}} |
| 24624 |
} |
| 24625 |
\end{codeenv} |
| 24626 |
Note that the original number formatting is retained in the |
| 24627 |
\fieldfmt{price} field but the plain numeric value is saved in the |
| 24628 |
\fieldfmt{price-value} field and the currency symbol is saved in the |
| 24629 |
\fieldfmt{price-currency} field. These custom fields will all need |
| 24630 |
to be defined or aliased when the \ext{bib} file is read by \bibgls. |
| 24631 |
|
| 24632 |
For further information on the \sty{datatool} datum format see the |
| 24633 |
\sty{datatool} v3.0+ user manual. You need to set the |
| 24634 |
decimal and number group characters with \ics{DTLsetnumberchars} and |
| 24635 |
the currency symbol with \ics{DTLnewcurrencysymbol} for the values |
| 24636 |
to be parsed correctly. |
| 24637 |
|
| 24638 |
\datatoolbibarg{no-save-datum} |
| 24639 |
Equivalent to: |
| 24640 |
\begin{codeenv} |
| 24641 |
\datatoolbiblongarg{no-save-value} \datatoolbiblongarg{no-save-currency} |
| 24642 |
\end{codeenv} |
| 24643 |
|
| 24644 |
\datatoolbibarg{save-value} |
| 24645 |
|
| 24646 |
If a field contains a formatted numeric value or currency (according |
| 24647 |
to the current \sty{datatool} settings), the numeric value will be |
| 24648 |
saved in the field \meta{field}\meta{prefix} if it's different from |
| 24649 |
the value in \meta{field}. |
| 24650 |
|
| 24651 |
\datatoolbibarg{no-save-value} |
| 24652 |
|
| 24653 |
Don't save numeric values in a separate field (default). |
| 24654 |
|
| 24655 |
\datatoolbibarg{save-currency} |
| 24656 |
|
| 24657 |
If a field contains a formatted currency (according |
| 24658 |
to the current \sty{datatool} settings), the currency symbol will be |
| 24659 |
saved in the field \meta{field}\meta{prefix}. |
| 24660 |
|
| 24661 |
\datatoolbibarg{no-save-currency} |
| 24662 |
|
| 24663 |
Don't save the currency symbol in a separate field (default). |
| 24664 |
|
| 24665 |
\datatoolbibarg{split} |
| 24666 |
|
| 24667 |
If multiple databases are found in the input file, create a separate |
| 24668 |
output file for each database. If the output \meta{bib file} provided to |
| 24669 |
\idx{datatool2bib} is given as \filefmt{\meta{base}.bib} then each |
| 24670 |
database \meta{dbname} will be saved in the file |
| 24671 |
\filefmt{\meta{base}-\meta{dbname}.bib}. |
| 24672 |
|
| 24673 |
\datatoolbibarg{no-split} |
| 24674 |
|
| 24675 |
All data found from parsing the input file will be saved in the |
| 24676 |
single output \meta{bib file} (default). |
| 24677 |
|
| 24678 |
\datatoolbibarg{detect-symbols} |
| 24679 |
|
| 24680 |
Attempt to detect entries that should be \atentry{symbol} or |
| 24681 |
\atentry{number} based on the value of the \field{name} field. |
| 24682 |
This tries to expand the value of the name field with |
| 24683 |
\ics{DTLgidxParen} and \ics{DTLgidxIgnore} locally defined to |
| 24684 |
discard their argument. If the result is empty or if the first |
| 24685 |
character of the result is not alphabetic then, |
| 24686 |
if the result parses as an integer, \atentry{number} |
| 24687 |
will be chosen otherwise \atentry{symbol} will be chosen. |
| 24688 |
(An empty result can occur if the \field{name} field solely consists |
| 24689 |
of commands that are unknown to the \texparserlib, which suggests |
| 24690 |
symbols rather than words.) |
| 24691 |
|
| 24692 |
This setting is only applicable for entries defined with |
| 24693 |
\sty{datagidx}['s] \cs{newterm} command, not with general |
| 24694 |
\sty{datatool} databases. Note that if this |
| 24695 |
results in a change to the entry type from its default |
| 24696 |
\atentry{entry} then \converterlongarg{index-conversion} won't |
| 24697 |
convert the type to \atentry{index}, regardless of whether or |
| 24698 |
not the \field{description} field is set. |
| 24699 |
|
| 24700 |
\datatoolbibarg{no-detect-symbols} |
| 24701 |
|
| 24702 |
Don't attempt to detect symbols (default). |
| 24703 |
|
| 24704 |
\datatoolbibarg{numeric-locale} |
| 24705 |
|
| 24706 |
For use with \datatoolbiblongarg{detect-symbols}, this switch |
| 24707 |
identifies the locale used for numeric parsing to determine whether |
| 24708 |
or not the \atentry{number} entry type should be used. |
| 24709 |
If omitted, the \idx{JVM}['s] default locale is assumed. |
| 24710 |
|
| 24711 |
\datatoolbibarg{adjust-gls} |
| 24712 |
|
| 24713 |
This setting is the default. |
| 24714 |
Any instance of commands like \ics{datagidx.gls} found in field |
| 24715 |
values will have their labels adjusted, if they have been modified |
| 24716 |
due to stripping spaces etc. Also, the syntax of \sty{datagidx}['s] |
| 24717 |
\ics{datagidx.gls} is slightly different from \sty{glossaries}['s] |
| 24718 |
\ics{gls} as the format is incorporated at the start of the label. |
| 24719 |
If this is detected, the format will be added as an optional |
| 24720 |
argument, matching the \sty{glossaries} syntax. |
| 24721 |
|
| 24722 |
Additionally, commands that have different names from those provided |
| 24723 |
by \sty{glossaries} will be replaced with the closest match. For |
| 24724 |
example, \ics{datagidx.glsnl} will be replaced with \code{\ics{gls}*} |
| 24725 |
(no hyperlink). |
| 24726 |
|
| 24727 |
\datatoolbibarg{no-adjust-gls} |
| 24728 |
|
| 24729 |
Don't adjust commands like \ics{datagidx.gls} in field values. |
| 24730 |
|
| 24731 |
\datatoolbibarg{dependency-field} |
| 24732 |
|
| 24733 |
Sets the name of the dependency field. Has no effect with |
| 24734 |
\datatoolbiblongarg{no-strip-glsadd}. With |
| 24735 |
\datatoolbiblongarg{strip-glsadd}, the label from the |
| 24736 |
stripped \ics{datagidx.glsadd} argument will be added to the field identified |
| 24737 |
by \meta{field}. The default is \fieldfmt{dependency} which will be ignored |
| 24738 |
by \bibgls\ unless instructed otherwise (via resource options such |
| 24739 |
as \csopt{field-aliases} or by defining the field with commands such |
| 24740 |
as \cs{glsaddstoragekey}). |
| 24741 |
|
| 24742 |
For example, \meta{field} could be set to \field{see} (but be aware |
| 24743 |
that this won't be merged with any existing \field{see} value for |
| 24744 |
the same entry) or the new document to use the created \ext{bib} |
| 24745 |
file could define \meta{field} and reference it in |
| 24746 |
\csopt{dependency-fields}. |
| 24747 |
|
| 24748 |
The \meta{field} will have any invalid content stripped and will be |
| 24749 |
adjusted to match the \converterlongarg{field-case} setting. |
| 24750 |
If the \meta{field} ends up as an empty string, it will behave as |
| 24751 |
\datatoolbiblongarg{no-dependency-field}. |
| 24752 |
|
| 24753 |
\datatoolbibarg{no-dependency-field} |
| 24754 |
|
| 24755 |
Don't save any labels stripped with |
| 24756 |
\datatoolbiblongarg{strip-glsadd}. |
| 24757 |
|
| 24758 |
\datatoolbibarg{strip} |
| 24759 |
|
| 24760 |
Switch on all strip options. |
| 24761 |
|
| 24762 |
\datatoolbibarg{no-strip} |
| 24763 |
|
| 24764 |
Switch off all strip options. |
| 24765 |
|
| 24766 |
\datatoolbibarg{strip-glsadd} |
| 24767 |
|
| 24768 |
Any instance of \ics{datagidx.glsadd} found in field values will be |
| 24769 |
stripped, along with the argument. Note that this command is |
| 24770 |
provided by \sty{datagidx} and, unlike the analogous |
| 24771 |
\sty{glossaries} command, it doesn't have an optional argument but |
| 24772 |
instead allows the format option to be included in the mandatory |
| 24773 |
argument. |
| 24774 |
|
| 24775 |
This setting is the default as \cs{glsadd} is rarely needed in field |
| 24776 |
values with \bibgls, as dependencies and the \csopt{selection} |
| 24777 |
criteria are usually sufficient. |
| 24778 |
|
| 24779 |
\datatoolbibarg{no-strip-glsadd} |
| 24780 |
|
| 24781 |
No search is made for \ics{datagidx.glsadd} in field values. Note |
| 24782 |
that this means that no adjustments for the different syntax will be |
| 24783 |
made. |
| 24784 |
|
| 24785 |
\datatoolbibarg{strip-acronym-font} |
| 24786 |
|
| 24787 |
Any instance of \ics{acronymfont} found in field values will be |
| 24788 |
strip and the braces around the argument will be removed. |
| 24789 |
|
| 24790 |
This setting is the default since \cs{acronymfont} should not be |
| 24791 |
used with \sty{glossaries-extra}. |
| 24792 |
|
| 24793 |
\datatoolbibarg{no-strip-acronym-font} |
| 24794 |
|
| 24795 |
No search is made for \cs{acronymfont} in the field values. Note |
| 24796 |
that the use of \cs{acronymfont} is deprecated with |
| 24797 |
\sty{glossaries-extra} as it has a different abbreviation mechanism |
| 24798 |
to the base \sty{glossaries} package. |
| 24799 |
|
| 24800 |
\datatoolbibarg{strip-case-change} |
| 24801 |
|
| 24802 |
The following \idxpl{casecommands} will be stripped from field |
| 24803 |
values and the braces around the argument will be removed: |
| 24804 |
\csfmt{uppercase}, \csfmt{lowercase}, |
| 24805 |
\ics{MakeTextUppercase}, \ics{MakeTextLowercase}, |
| 24806 |
\ics{MakeUppercase}, \ics{MakeLowercase}, and the \sty{mfirstuc} |
| 24807 |
commands. |
| 24808 |
|
| 24809 |
\datatoolbibarg{no-strip-case-change} |
| 24810 |
|
| 24811 |
Don't strip the \idxpl{casecommands} from field values (default). |
| 24812 |
|
| 24813 |
\subsection{Recognised Commands} |
| 24814 |
|
| 24815 |
This section lists \isty{datatool} and \isty{datagidx} commands that |
| 24816 |
are recognised by \idx{datatool2bib}. (There may be other commands |
| 24817 |
that are also recognised but aren't relevant to the conversion |
| 24818 |
process.) See the \sty{datatool} user manual for further |
| 24819 |
information. |
| 24820 |
|
| 24821 |
\cssection{DTLsetup} |
| 24822 |
Some but not all \sty{datatool} settings are |
| 24823 |
recognised by the \texparserlib. Of those that are recognised, the |
| 24824 |
settings pertinent to \idx{datatool2bib} are: \optfmt{default-name}, |
| 24825 |
\optfmt{store-datum}, \optfmt{new-value-trim}, |
| 24826 |
\optfmt{new-value-expand}, and \optfmt{io}. |
| 24827 |
|
| 24828 |
The \optfmt{io} setting |
| 24829 |
takes a comma-separated list of default I/O options applicable to |
| 24830 |
\gls{DTLread} (and \cs{DTLwrite}). Recognised I/O options: |
| 24831 |
\optfmt{name}, \optfmt{keys}, \optfmt{headers}, \optfmt{expand}, |
| 24832 |
\optfmt{format}, \optfmt{add-delimiter}, \optfmt{csv-escape-chars}, |
| 24833 |
\optfmt{csv-content}, \optfmt{csv-blank}, \optfmt{csv-skip-lines} |
| 24834 |
(and synonym \optfmt{omitlines}), \optfmt{no-header} (and synonym |
| 24835 |
\optfmt{noheader}), \optfmt{auto-keys} (and synonym |
| 24836 |
\optfmt{autokeys}), \optfmt{overwrite}, \optfmt{load-action}, |
| 24837 |
\optfmt{delimiter}, and \optfmt{separator}. |
| 24838 |
|
| 24839 |
\cssection{DTLread} |
| 24840 |
Loads a database from the given file, where the format should be |
| 24841 |
identified in \meta{options} with the \optfmt{format} key. The |
| 24842 |
default is \code{format=csv}, which indicates that the file is a CSV |
| 24843 |
file. For tab-separated files, use \code{format=tsv}. If the CSV/TSV |
| 24844 |
file contains \TeX\ markup within the cells, use |
| 24845 |
\code{csv-content=tex} otherwise use \code{csv-content=literal}. |
| 24846 |
|
| 24847 |
Note that: |
| 24848 |
\begin{codeenv} |
| 24849 |
datatool2bib \datatoolbiblongarg{read} \meta{io-options} \meta{filename} \meta{bib file} |
| 24850 |
\end{codeenv} |
| 24851 |
is equivalent to creating a file \filefmt{otherfile.tex} with a single line: |
| 24852 |
\begin{codeenv} |
| 24853 |
\gls{DTLread}\oargm{io-options}\margm{filename} |
| 24854 |
\end{codeenv} |
| 24855 |
and then running: |
| 24856 |
\begin{alltt} |
| 24857 |
datatool2bib otherfile.tex \meta{bib file} |
| 24858 |
\end{alltt} |
| 24859 |
|
| 24860 |
\begin{important} |
| 24861 |
The \texparserlib\ also recognises \ics{DTLwrite} but |
| 24862 |
\idx{datatool2bib} redefines the command to do nothing. |
| 24863 |
\end{important} |
| 24864 |
|
| 24865 |
\cssection{dtlexpandnewvalue} |
| 24866 |
New values will be expanded before being added to the database. |
| 24867 |
Note that the \texparserlib\ may not expand commands in the same way |
| 24868 |
as \TeX, and it won't be able to expand unknown commands. |
| 24869 |
|
| 24870 |
\cssection{dtlnoexpandnewvalue} |
| 24871 |
New values will not be expanded before being added to the database |
| 24872 |
(default). |
| 24873 |
|
| 24874 |
\cssection{DTLnewdb} |
| 24875 |
Defines a new database with the given label. |
| 24876 |
|
| 24877 |
\cssection{DTLnewrow} |
| 24878 |
Creates a new row in the database identified the given label. |
| 24879 |
|
| 24880 |
\cssection{DTLnewdbentry} |
| 24881 |
Adds a new entry to the final row of the given database. |
| 24882 |
|
| 24883 |
For example: |
| 24884 |
\begin{codeenv} |
| 24885 |
\gls+{DTLnewdb}\marg{mydata} |
| 24886 |
\gls+{DTLnewrow}\marg{mydata} |
| 24887 |
\gls+{DTLnewdbentry}\marg{mydata}\marg{Forename}\marg{John} |
| 24888 |
\gls{DTLnewdbentry}\marg{mydata}\marg{Surname}\marg{Smith} |
| 24889 |
\gls{DTLnewdbentry}\marg{mydata}\marg{Email}\marg{[email protected]} |
| 24890 |
\gls{DTLnewrow}\marg{mydata} |
| 24891 |
\gls{DTLnewdbentry}\marg{mydata}\marg{Forename}\marg{Jane} |
| 24892 |
\gls{DTLnewdbentry}\marg{mydata}\marg{Surname}\marg{Doe} |
| 24893 |
\gls{DTLnewdbentry}\marg{mydata}\marg{Email}\marg{[email protected]} |
| 24894 |
\end{codeenv} |
| 24895 |
This can be converted using, for example (assuming the above is in |
| 24896 |
the file \filefmt{mydata.tex}): |
| 24897 |
\begin{codeenv} |
| 24898 |
datatool2bib \datatoolbiblongarg{auto-label} mydata.tex mydata.bib |
| 24899 |
\end{codeenv} |
| 24900 |
This will create the file \filefmt{mydata.bib}, which will contain: |
| 24901 |
\begin{codeenv} |
| 24902 |
\atentry{entry}\marg{mydata1, |
| 24903 |
\fieldfmt{forename} = \marg{John}, |
| 24904 |
\fieldfmt{surname} = \marg{Smith}, |
| 24905 |
\fieldfmt{email} = \marg{[email protected]} |
| 24906 |
} |
| 24907 |
\strut |
| 24908 |
\atentry{entry}\marg{mydata2, |
| 24909 |
\fieldfmt{forename} = \marg{Jane}, |
| 24910 |
\fieldfmt{surname} = \marg{Doe}, |
| 24911 |
\fieldfmt{email} = \marg{[email protected]} |
| 24912 |
} |
| 24913 |
\end{codeenv} |
| 24914 |
(Use \converterlongarg{index-conversion} to use \atentry{index} instead |
| 24915 |
of \atentry{entry} where there's no \field{description}.) |
| 24916 |
The \csopt{assign-fields} resource option can be used to set |
| 24917 |
the \field{name} field to a concatenation of the forename and |
| 24918 |
surname fields (which would need to be aliased or defined if |
| 24919 |
required). |
| 24920 |
|
| 24921 |
\cssection{DTLaction} |
| 24922 |
This general purpose action command can be used to create and append |
| 24923 |
to databases. The applicable actions that are recognised by the |
| 24924 |
\texparserlib\ (and therefore by \idx{datatool2bib}) are: |
| 24925 |
\optfmt{new}, \optfmt{new row}, \optfmt{new entry}, and |
| 24926 |
\optfmt{add column}. |
| 24927 |
|
| 24928 |
For example: |
| 24929 |
\begin{codeenv} |
| 24930 |
\gls+{DTLsetup}\marg{default-name=mydata} |
| 24931 |
\gls+{DTLaction}\marg{new} |
| 24932 |
\gls{DTLaction}\oarg{ |
| 24933 |
assign = |
| 24934 |
\marg{ |
| 24935 |
Name = \marg{José Arara}, |
| 24936 |
Score = 68, |
| 24937 |
Award = \marg{\cs{cs.dollar}2,453.99} |
| 24938 |
} |
| 24939 |
}\marg{new row} |
| 24940 |
\gls{DTLaction}\oarg{ |
| 24941 |
assign = |
| 24942 |
\marg{ |
| 24943 |
Name = \marg{Zoë Zebra}, |
| 24944 |
Score = 73, |
| 24945 |
Award = \marg{\cs{cs.dollar}2,542} |
| 24946 |
} |
| 24947 |
}\marg{new row} |
| 24948 |
\end{codeenv} |
| 24949 |
This can be converted using, for example (assuming the above is in |
| 24950 |
the file \filefmt{mydata.tex}): |
| 24951 |
\begin{codeenv} |
| 24952 |
datatool2bib \datatoolbiblongarg{label} Name mydata.tex mydata.bib |
| 24953 |
\end{codeenv} |
| 24954 |
This will create the file \filefmt{mydata.bib}, which will contain: |
| 24955 |
\begin{codeenv} |
| 24956 |
\atentry{entry}\marg{JoséArara, |
| 24957 |
\field{name} = \marg{José Arara}, |
| 24958 |
\fieldfmt{score} = \marg{68}, |
| 24959 |
\fieldfmt{award} = \marg{\cs{cs.dollar}2,453.99} |
| 24960 |
} |
| 24961 |
\strut |
| 24962 |
\atentry{entry}{ZoëZebra, |
| 24963 |
\field{name} = \marg{Zoë Zebra}, |
| 24964 |
\fieldfmt{score} = \marg{73}, |
| 24965 |
\fieldfmt{award} = \marg{\cs{cs.dollar}2,542} |
| 24966 |
} |
| 24967 |
\end{codeenv} |
| 24968 |
Again, use \converterlongarg{index-conversion} to use |
| 24969 |
\atentry{index} instead of \atentry{entry} if the |
| 24970 |
\field{description} field is missing. |
| 24971 |
|
| 24972 |
The \iext{dtltex} and \ext{dbtex} file formats are also recognised |
| 24973 |
by the \texparserlib. The commands used in those files are not |
| 24974 |
intended for document use, but the files may be passed to |
| 24975 |
\idx{datatool2bib} as the input file. See the \sty{datatool} v3.0+ |
| 24976 |
user manual for further details of those formats. |
| 24977 |
|
| 24978 |
\prefixedcssection{datagidx}{newgidx} |
| 24979 |
Defines a new \sty{datagidx} database, which may be referenced in |
| 24980 |
\gls{datagidx.newterm} and \gls{datagidx.newacro} by the |
| 24981 |
\optfmt{database} key in their optional argument (which be parsed |
| 24982 |
and then dropped from the field list). |
| 24983 |
|
| 24984 |
\prefixedcssection{datagidx}{newterm} |
| 24985 |
This is similar to the \gls{newterm} command provided by |
| 24986 |
\sty{glossaries} (via the \styopt{index} package option), but has |
| 24987 |
slightly different behaviour. With \sty{datagidx}, the mandatory |
| 24988 |
argument is the name. The label may be supplied in the optional |
| 24989 |
argument. If omitted, the label is obtained from the name. The |
| 24990 |
\idx{datatool2bib} application will try to mimic the process used by |
| 24991 |
\sty{datagidx} to create the label from the name, but may not |
| 24992 |
produce an exact match. It's therefore important to double-check the |
| 24993 |
resulting \ext{bib} file afterwards. |
| 24994 |
|
| 24995 |
Each \gls{datagidx.newterm} will be converted to \atentry{entry} |
| 24996 |
unless it has both the \field{long} and \field{short} fields set, in |
| 24997 |
which case it will be converted to \atentry{abbreviation}. If there |
| 24998 |
is no \field{description} and \converterlongarg{index-conversion} is |
| 24999 |
used, then \atentry{index} will be used instead of \atentry{entry} |
| 25000 |
(but not if the term has been identified as an abbreviation). |
| 25001 |
|
| 25002 |
\prefixedcssection{datagidx}{newacro} |
| 25003 |
This is simply a wrapper command that internally uses |
| 25004 |
\gls{datagidx.newterm}. However, \idx{datatool2bib} has a slightly |
| 25005 |
different behaviour that doesn't add the formatting or case-changing |
| 25006 |
commands (since these can be dealt with by the abbreviation style or |
| 25007 |
\bibgls\ resource options). |
| 25008 |
|
| 25009 |
\chapter{Examples} |
| 25010 |
\label{sec:examples} |
| 25011 |
\setsecdepth*{0} |
| 25012 |
\renewcommand{\cssectioncmd}{\subsection} |
| 25013 |
|
| 25014 |
The example files described here can be found in the |
| 25015 |
\filefmt{examples} sub-directory. The \ext{bib} files are listed |
| 25016 |
first and then sample files that use the \ext{bib} data. |
| 25017 |
Make sure you have the latest versions of \styfmt{glossaries}, |
| 25018 |
\styfmt{mfirstuc}, \styfmt{glossaries-extra} and \bibgls\ if you |
| 25019 |
want to try these out. (The \exfile{sample-media.tex} file requires |
| 25020 |
at least \styfmt{datatool} v2.28.) If you get any undefined control |
| 25021 |
sequence or undefined style errors then you need to update your |
| 25022 |
\TeX\ distribution. Use the \longarg{group} switch when invoking |
| 25023 |
\bibgls\ for all these examples if you want the glossaries divided |
| 25024 |
into groups. The set of system calls for the document build in the |
| 25025 |
examples below may require an extra \LaTeX\ run to ensure the PDF |
| 25026 |
bookmarks are up-to-date when \sty{hyperref} is used. |
| 25027 |
|
| 25028 |
These files are just examples of how to use \bibgls. There are other |
| 25029 |
ways of defining similar entries and sometimes alternatives are |
| 25030 |
suggested. Use the code here as a starting point if you need data |
| 25031 |
like this and adapt it to a format appropriate for your |
| 25032 |
requirements. There are also some example documents in the |
| 25033 |
\href{https://www.dickimaw-books.com/gallery}{Dickimaw Books gallery}. |
| 25034 |
|
| 25035 |
\filesection{no-interpret-preamble.bib} |
| 25036 |
|
| 25037 |
The \exfile{no-interpret-preamble.bib} file contains command |
| 25038 |
definitions used in some of the \field{name} fields. Although these |
| 25039 |
commands aren't used explicitly in the document, they need to be |
| 25040 |
defined when the names are displayed in the document (typically in |
| 25041 |
the glossary). These commands are much like the \gls{sortop} command |
| 25042 |
described on \glsxtrpageref{sortop} and need to be hidden |
| 25043 |
from \bibgls's interpreter. This file doesn't contain any entry |
| 25044 |
definitions and must be loaded first with |
| 25045 |
\csopt[false]{interpret-preamble}. The |
| 25046 |
\exfile{interpret-preamble.bib} or \exfile{interpret-preamble2.bib} |
| 25047 |
file can then be loaded to provide alternative definitions for |
| 25048 |
\bibgls's interpreter. |
| 25049 |
|
| 25050 |
The first command is: |
| 25051 |
\nosecdef{sortname} |
| 25052 |
This is used in the \field{name} fields for entries containing |
| 25053 |
information about a person. The aim here is for \bibgls\ to sort |
| 25054 |
according to \meta{surname}, \meta{first name(s)} but for the |
| 25055 |
glossary to display \meta{first name(s)} \meta{surname}. For names |
| 25056 |
with a \qt{von} part, there's another command: |
| 25057 |
\nosecdef{sortvonname} |
| 25058 |
which has a similar purpose. |
| 25059 |
The third command is: |
| 25060 |
\nosecdef{sortart} |
| 25061 |
This is the same as \gls{sortname} but is designed for titles, |
| 25062 |
phrases or sentences that start with an article (such as \qt{a} or |
| 25063 |
\qt{the}). Although it has the same definition as \gls{sortname} |
| 25064 |
in this file, in the interpreted files the article part is omitted |
| 25065 |
to completely ignore them in the sorting. |
| 25066 |
The fourth command is: |
| 25067 |
\nosecdef{sortmediacreator} |
| 25068 |
which again is functionally the same as \gls{sortname}. |
| 25069 |
|
| 25070 |
The names could be specified using \BibTeX's |
| 25071 |
syntax instead with \csopt{bibtex-contributor-fields} to convert it, |
| 25072 |
but the aim here is to show a variety of ways to use \bibgls. For an |
| 25073 |
example of \csopt{bibtex-contributor-fields}, see the way the |
| 25074 |
\fieldfmt{cast} field in \exfile{films.bib} is dealt with. |
| 25075 |
|
| 25076 |
Although the file only contains ASCII characters, it starts with |
| 25077 |
an \gls{encoding} line to prevent \bibgls\ from searching the entire file |
| 25078 |
for it. (That's not so much of an issue with a short file, but may |
| 25079 |
cause an unnecessary delay for much longer files.) |
| 25080 |
|
| 25081 |
The contents of \filefmt{no-interpret-preamble.bib} are as follows: |
| 25082 |
\lstinputlisting[firstline=5]{../examples/no-interpret-preamble.bib} |
| 25083 |
|
| 25084 |
\filesection{interpret-preamble.bib} |
| 25085 |
|
| 25086 |
This provides definitions of \gls{sortname}, \gls{sortvonname}, |
| 25087 |
\gls{sortart} and \gls{sortmediacreator} in \atentry{preamble} |
| 25088 |
that can be picked up by the interpreter and used during sorting. |
| 25089 |
Note that in this case \gls{sortart} is defined to ignore the |
| 25090 |
article to completely ignore it from sorting. If you happen to have |
| 25091 |
\qt{a \meta{something}} and \qt{the \meta{something}} where the |
| 25092 |
\meta{something}s are identical, you may want to append the article |
| 25093 |
to disambiguate them. |
| 25094 |
|
| 25095 |
The contents of \filefmt{interpret-preamble.bib} are as follows: |
| 25096 |
\lstinputlisting[firstline=5]{../examples/interpret-preamble.bib} |
| 25097 |
|
| 25098 |
\filesection{interpret-preamble2.bib} |
| 25099 |
|
| 25100 |
An alternative to \exfile{interpret-preamble.bib} with a different |
| 25101 |
definition of \gls{sortmediacreator}. This uses \cs{renewcommand} |
| 25102 |
instead of \cs{providecommand} so \csopt[false]{write-preamble} |
| 25103 |
is required to prevent \LaTeX\ from picking up the definitions. |
| 25104 |
|
| 25105 |
The contents of \filefmt{interpret-preamble2.bib} are as follows: |
| 25106 |
\lstinputlisting[firstline=5]{../examples/interpret-preamble2.bib} |
| 25107 |
|
| 25108 |
\filesection{constants.bib} |
| 25109 |
|
| 25110 |
The \exfile{constants.bib} file contains mathematical constants. |
| 25111 |
These all use a custom \gls{entrytype} \atentryfmt{constant}, which must |
| 25112 |
be aliased otherwise the entries will all be ignored. The entries |
| 25113 |
all have custom fields, which also need to be aliased. |
| 25114 |
For example: |
| 25115 |
\begin{codeenv} |
| 25116 |
\csopt[constant=entry]{entry-type-aliases}, |
| 25117 |
\csopt[ |
| 25118 |
\fieldfmt{constantname}=\field{name}, |
| 25119 |
\fieldfmt{constantsymbol}=\field{symbol}, |
| 25120 |
\fieldfmt{definition}=\field{description}, |
| 25121 |
\fieldfmt{identifier}=\field{category}, |
| 25122 |
\fieldfmt{value}=\field{user1} |
| 25123 |
]{field-aliases} |
| 25124 |
\end{codeenv} |
| 25125 |
This setting means that, for example, |
| 25126 |
\begin{codeenv} |
| 25127 |
\atentryfmt{constant}\marg{root2, |
| 25128 |
\fieldfmt{constantname}=\marg{Pythagoras' constant}, |
| 25129 |
\fieldfmt{constantsymbol}=\marg{\cs{ensuremath}\marg{\ics{surd}2}}, |
| 25130 |
\fieldfmt{definition}=\marg{the square root of 2}, |
| 25131 |
\fieldfmt{value}=\marg{1.41421}, |
| 25132 |
\fieldfmt{identifier}=\marg{constant} |
| 25133 |
} |
| 25134 |
\end{codeenv} |
| 25135 |
is treated as though it was defined as: |
| 25136 |
\begin{codeenv} |
| 25137 |
\atentry{entry}\marg{root2, |
| 25138 |
\field{name}=\marg{Pythagoras' constant}, |
| 25139 |
\field{symbol}=\marg{\cs{ensuremath}\marg{\cs{surd}2}}, |
| 25140 |
\field{description}=\marg{the square root of 2}, |
| 25141 |
\field{user1}=\marg{1.41421}, |
| 25142 |
\field{category}=\marg{constant} |
| 25143 |
} |
| 25144 |
\end{codeenv} |
| 25145 |
This use of custom fields and \glspl{entrytype} allows more flexibility. |
| 25146 |
For example, I may have another document that uses the same |
| 25147 |
\ext{bib} file but requires a different definition: |
| 25148 |
\begin{codeenv} |
| 25149 |
\atentry{number}\marg{root2, |
| 25150 |
\field{description}=\marg{Pythagoras' constant}, |
| 25151 |
\field{name}=\marg{\cs{ensuremath}\marg{\cs{surd}2}} |
| 25152 |
} |
| 25153 |
\end{codeenv} |
| 25154 |
which can be obtained with: |
| 25155 |
\begin{codeenv} |
| 25156 |
\csopt[constant=number]{entry-type-aliases}, |
| 25157 |
\csopt[ |
| 25158 |
\fieldfmt{constantname}=\field{description}, |
| 25159 |
\fieldfmt{constantsymbol}=\field{name} |
| 25160 |
]{field-aliases} |
| 25161 |
\end{codeenv} |
| 25162 |
Since the other custom fields haven't be aliased, they're ignored. |
| 25163 |
|
| 25164 |
The custom fields are: \fieldfmt{identifier} (set to \code{constant} |
| 25165 |
for all the entries), \fieldfmt{constantname} (the constant's name), |
| 25166 |
\fieldfmt{definition} (a definition of the constant), |
| 25167 |
\fieldfmt{value} (the approximate numeric value of the constant), |
| 25168 |
\fieldfmt{constantsymbol} (the symbolic representation of the |
| 25169 |
constant) and \fieldfmt{alternative} (alternative symbol). |
| 25170 |
There are three entries that don't have the custom |
| 25171 |
\fieldfmt{value} field: \code{zero} and \code{one} (the exact value |
| 25172 |
is in the \fieldfmt{constantsymbol} field in both cases) and \code{imaginary} |
| 25173 |
(where there's no real number value). |
| 25174 |
|
| 25175 |
I've provided some commands in the \atentry{preamble} for |
| 25176 |
constants that are represented by Latin and Greek letters. |
| 25177 |
These can be defined in the document before the \igls{resourceset} |
| 25178 |
if different notation is required. The upright Greek commands require |
| 25179 |
the \isty{upgreek} package. |
| 25180 |
|
| 25181 |
If it's likely that there may be a need to sort according to |
| 25182 |
\fieldfmt{definition}, then it would be better to use \gls!{sortart} |
| 25183 |
describe above: |
| 25184 |
\begin{codeenv} |
| 25185 |
\atentryfmt{constant}\marg{root2, |
| 25186 |
\fieldfmt{constantname}=\marg{Pythagoras' constant}, |
| 25187 |
\fieldfmt{constantsymbol}=\marg{\cs{ensuremath}\marg{\cs{surd}2}}, |
| 25188 |
\fieldfmt{definition}=\marg{\gls{sortart}\marg{the}\marg{square root of 2}}, |
| 25189 |
\fieldfmt{value}=\marg{1.41421}, |
| 25190 |
\fieldfmt{identifier}=\marg{constant} |
| 25191 |
} |
| 25192 |
\end{codeenv} |
| 25193 |
Remember that this would need \exfile{no-interpret-preamble.bib} to |
| 25194 |
ensure the command is recognised in the document. |
| 25195 |
|
| 25196 |
The contents of \filefmt{constants.bib} are as follows: |
| 25197 |
\lstinputlisting[firstline=5]{../examples/constants.bib} |
| 25198 |
|
| 25199 |
\filesection{chemicalformula.bib} |
| 25200 |
|
| 25201 |
The \exfile{chemicalformula.bib} file contains chemical formulae. |
| 25202 |
Each entry has a field that uses \ics{ce} provided by \sty{mhchem} |
| 25203 |
so the document will need to load that package. Since all resource |
| 25204 |
files must be loaded in the preamble, it's possible to ensure that |
| 25205 |
the package is loaded using: |
| 25206 |
\begin{codeenv} |
| 25207 |
\atentry{preamble}\marg{\qtdelim{\cs{usepackage}\marg{mhchem}}} |
| 25208 |
\end{codeenv} |
| 25209 |
However, it's best just to load it in the document otherwise it |
| 25210 |
won't be available before the \ext{glstex} file has been loaded. |
| 25211 |
Also, \sty{glossaries} (and therefore \sty{glossaries-extra}) must be |
| 25212 |
loaded after \sty{hyperref}, which usually needs to be loaded last |
| 25213 |
so most packages should be loaded before \sty{glossaries-extra}. |
| 25214 |
Instead, I've just put a comment in the \ext{bib} file as a |
| 25215 |
reminder. |
| 25216 |
|
| 25217 |
All entries are defined using a custom \gls{entrytype} |
| 25218 |
\atentryfmt{chemical}. This must be aliased using |
| 25219 |
\csopt{entry-type-aliases} or the entries will be ignored. For |
| 25220 |
example, to make \atentryfmt{chemical} behave like \atentry{symbol}: |
| 25221 |
\begin{codeenv} |
| 25222 |
\csopt[\fieldfmt{chemical}=\field{symbol}]{entry-type-aliases} |
| 25223 |
\end{codeenv} |
| 25224 |
Remember that with the \atentry{symbol} type, if the \field{sort} |
| 25225 |
field is omitted \bibgls\ will fallback on the label by default. It |
| 25226 |
can be changed to fallback on the \field{name} field instead using |
| 25227 |
\csopt[name]{symbol-sort-fallback}. This will require the use of |
| 25228 |
the interpreter if the name contains a command but \bibgls\ |
| 25229 |
recognises the \sty{mhchem} package and has a limited ability to |
| 25230 |
interpret \cs{ce}. If \atentryfmt{chemical} is changed to |
| 25231 |
\atentry{entry} instead then the fallback for the \field{sort} will be the |
| 25232 |
entry's \field{name}. |
| 25233 |
|
| 25234 |
All entries only contain custom fields, which will all be ignored by |
| 25235 |
\bibgls\ unless defined or aliased: \fieldfmt{identifier}, which is set to |
| 25236 |
\code{chemical} for all entries, \fieldfmt{formula}, which is set to the |
| 25237 |
chemical formula, and \fieldfmt{chemicalname}, which is set to the chemical |
| 25238 |
name. This allows the flexibility of determining whether the |
| 25239 |
\field{name} or \field{symbol} field should contain the chemical |
| 25240 |
formula on a per-resource basis. For example: |
| 25241 |
\begin{codeenv} |
| 25242 |
\csopt[\fieldfmt{formula}=\field{name},\fieldfmt{chemicalname}=\field{description}]{field-aliases} |
| 25243 |
\end{codeenv} |
| 25244 |
or |
| 25245 |
\begin{codeenv} |
| 25246 |
\csopt[\fieldfmt{chemicalname}=\field{name},\fieldfmt{formula}=\field{symbol}]{field-aliases} |
| 25247 |
\end{codeenv} |
| 25248 |
|
| 25249 |
The contents of \filefmt{chemicalformula.bib} are as follows: |
| 25250 |
\lstinputlisting[firstline=5]{../examples/chemicalformula.bib} |
| 25251 |
|
| 25252 |
\filesection{bacteria.bib} |
| 25253 |
|
| 25254 |
The \exfile{bacteria.bib} file contains bacteria abbreviations. |
| 25255 |
These all use the \atentry{abbreviation} \gls{entrytype} with a |
| 25256 |
\field{short} and \field{long} field. |
| 25257 |
|
| 25258 |
The entries all have a custom field \fieldfmt{identifier} set to |
| 25259 |
\code{bacteria}. This will be ignored by \bibgls\ unless it's |
| 25260 |
defined using \cs{glsaddkey} or \cs{glsaddstoragekey} or if it's |
| 25261 |
aliased with \csopt{field-aliases}. |
| 25262 |
|
| 25263 |
The contents of \filefmt{bacteria.bib} are as follows: |
| 25264 |
\lstinputlisting[firstline=5]{../examples/bacteria.bib} |
| 25265 |
|
| 25266 |
\filesection{baseunits.bib} |
| 25267 |
|
| 25268 |
The \exfile{baseunits.bib} file contains base \idxpl{SIunit}. The entries |
| 25269 |
are all defined using the custom \atentryfmt{unit} |
| 25270 |
\gls{entrytype}. This must be aliased with \csopt{entry-type-aliases} otherwise |
| 25271 |
\bibgls\ will ignore all the entries. For example: |
| 25272 |
\begin{codeenv} |
| 25273 |
\csopt[\fieldfmt{unit}=\field{symbol}]{entry-type-aliases} |
| 25274 |
\end{codeenv} |
| 25275 |
will make \bibgls\ treat the entries as though they were defined |
| 25276 |
using \atentry{symbol}. (Remember that \atentry{symbol} \glspl{entrytype} |
| 25277 |
use the label as the fallback field for \field{sort}.) |
| 25278 |
|
| 25279 |
The entries all have custom fields \fieldfmt{unitname}, |
| 25280 |
\fieldfmt{unitsymbol} and \fieldfmt{measurement}, one of which must |
| 25281 |
be aliased or copied to \field{name} if \atentryfmt{unit} is aliased |
| 25282 |
to an \gls{entrytype} that requires it. The other custom fields may be aliased or |
| 25283 |
copied to \field{symbol} and \field{description} as required. The |
| 25284 |
\fieldfmt{unitsymbol} fields all use \ics{si} provided by the |
| 25285 |
\isty{siunitx} package, so that package must be loaded in the |
| 25286 |
document. This is one of the small number of packages recognised by |
| 25287 |
\bibgls, so it's possible to sort according to the symbol if |
| 25288 |
required. |
| 25289 |
|
| 25290 |
The entries also all have a custom field \fieldfmt{identifier} set to |
| 25291 |
\code{baseunit}. This will be ignored by \bibgls\ unless it's |
| 25292 |
defined using \cs{glsaddkey} or \cs{glsaddstoragekey} or if it's |
| 25293 |
aliased with \csopt{field-aliases}. |
| 25294 |
|
| 25295 |
The contents of \filefmt{baseunits.bib} are as follows: |
| 25296 |
\lstinputlisting[firstline=5]{../examples/baseunits.bib} |
| 25297 |
|
| 25298 |
\filesection{derivedunits.bib} |
| 25299 |
|
| 25300 |
The \exfile{derivedunits.bib} file is much like \exfile{baseunits.bib} |
| 25301 |
but contains derived units and in this case the custom \gls{entrytype} |
| 25302 |
is \atentryfmt{measurement}, which must be aliased |
| 25303 |
otherwise the entries will all be ignored. |
| 25304 |
The entries all have a custom field \fieldfmt{identifier} set to |
| 25305 |
\code{derivedunit}. This will be ignored by \bibgls\ unless it's |
| 25306 |
defined using \cs{glsaddkey} or \cs{glsaddstoragekey} or if it's |
| 25307 |
aliased with \csopt{field-aliases}. |
| 25308 |
|
| 25309 |
The contents of \filefmt{derivedunits.bib} are as follows: |
| 25310 |
\lstinputlisting[firstline=5]{../examples/derivedunits.bib} |
| 25311 |
|
| 25312 |
\filesection{people.bib} |
| 25313 |
|
| 25314 |
The \exfile{people.bib} file contains details about people. |
| 25315 |
The \field{name} fields contain custom commands provided in |
| 25316 |
\exfile{no-interpret-preamble.bib} and |
| 25317 |
\exfile{interpret-preamble.bib}. |
| 25318 |
Remember that if \exfile{no-interpret-preamble.bib} is |
| 25319 |
loaded first, the definitions provided in that file will be the one |
| 25320 |
in use in the document. The \exfile{interpret-preamble.bib} file |
| 25321 |
then needs to be loaded to provide the definitions for \bibgls's |
| 25322 |
interpreter. |
| 25323 |
|
| 25324 |
The information for each person is supplied in an \atentry{entry} |
| 25325 |
type. There are some non-standard fields: \fieldfmt{born}, |
| 25326 |
\fieldfmt{died} and \fieldfmt{othername}. These fields will be ignored |
| 25327 |
unless keys are provided (using \cs{glsaddkey} or |
| 25328 |
\cs{glsaddstoragekey}) or the fields are aliased (using |
| 25329 |
\csopt{field-aliases}). The \fieldfmt{born} and \fieldfmt{died} |
| 25330 |
fields have dates that are \emph{almost} in the default \code{en-GB} |
| 25331 |
locale format with the \idx{JRE} \idx{localeprovider}, but they include a |
| 25332 |
tilde \idx{nbspchar} to prevent awkward line breaks. By default \bibgls's |
| 25333 |
interpreter converts \idx{nbspchar} to the non-breaking space character |
| 25334 |
\hex{A0} which isn't recognised by the date format. This can easily |
| 25335 |
be fixed with the \longarg{break-space} switch which will interpret |
| 25336 |
\idx{nbspchar} as a normal breakable space (\hex{20}), so with that switch |
| 25337 |
\csopt[date]{sort} or \csopt[date-reverse]{sort} can be used on |
| 25338 |
either of those fields. However, the \idx{CLDR} has a slightly |
| 25339 |
different default format than the \idx{JRE} for dates with |
| 25340 |
\code{en-GB}, so it's probably simplest to actually specify the |
| 25341 |
required format. |
| 25342 |
|
| 25343 |
An alternative approach would be to provide a command that can be |
| 25344 |
modified in the document to adjust the date style. For example, the |
| 25345 |
\fieldfmt{born} field could be specified as: |
| 25346 |
\begin{codeenv} |
| 25347 |
\fieldfmt{born}=\marg{\cmd{formatdate}\marg{13}\marg{7}\marg{100}\marg{BC}} |
| 25348 |
\end{codeenv} |
| 25349 |
The definition provided for the document could then be, for example: |
| 25350 |
\begin{codeenv} |
| 25351 |
\cs{providecommand}\marg{\cmd{formatdate}}[4]\marg{\ics{DTMdisplaydate}\marg{\idx{param}3}\marg{\idx{param}2}\marg{\idx{param}1}\marg{-1} \idx{param}4} |
| 25352 |
\end{codeenv} |
| 25353 |
(where \ics{DTMdisplaydate} is provided by the \isty{datetime2} |
| 25354 |
package) and a definition could be provided for \bibgls's |
| 25355 |
interpreter, for example: |
| 25356 |
\begin{codeenv} |
| 25357 |
\cs{providecommand}\marg{\cmd{formatdate}}[4]\marg{\idx{param}1/\idx{param}2/\idx{param}3 \idx{param}4} |
| 25358 |
\end{codeenv} |
| 25359 |
This would need the date format set. For example, |
| 25360 |
\csopt[d/M/y G]{date-sort-format}. |
| 25361 |
|
| 25362 |
Some of the entries, such as \code{caesar}, have a \field{first} |
| 25363 |
field. In those cases the \field{first} field is slightly different |
| 25364 |
from the \field{name} field (for example, \qt{Gaius} is omitted in |
| 25365 |
\code{caesar}'s \field{first} field). The other entries don't have a |
| 25366 |
\field{first} field. They can simply have the \field{name} copied to |
| 25367 |
\field{first} with the \csopt{replicate-fields} option (so that the |
| 25368 |
full name is shown on first use) or the \field{first} field can be |
| 25369 |
ignored with \csopt{ignore-fields} (so all entries will use the |
| 25370 |
\field{text} field on first use). The \csopt{replicate-override} |
| 25371 |
option can be used to force the \field{name} field to be copied to |
| 25372 |
the \field{first} field, even if the \field{first} field is already |
| 25373 |
set. Alternatively, with \csopt[true]{replicate-override} and |
| 25374 |
\csopt[\field{first}=\field{name}]{replicate-fields}, the \field{first} field be |
| 25375 |
copied to the \field{name} field. For consistency, the \field{first} |
| 25376 |
fields use the same custom commands as used in the \field{name} |
| 25377 |
field. |
| 25378 |
|
| 25379 |
There's one name with a \qt{von} part. In this case the \field{name} |
| 25380 |
field is set to: |
| 25381 |
\begin{codeenv} |
| 25382 |
\gls{sortvonname}\marg{Manfred}\marg{von}\marg{Richthofen} |
| 25383 |
\end{codeenv} |
| 25384 |
which will come under the \qt{V} letter group since \gls{sortvonname} |
| 25385 |
is defined as \meta{von} \meta{surname}, \meta{first name(s)} |
| 25386 |
|
| 25387 |
If you prefer that this name should come under \qt{R} instead, then |
| 25388 |
you need to adjust the definition of \gls{sortvonname}: |
| 25389 |
\begin{codeenv} |
| 25390 |
\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{sortname}}[2]\marg{\idx{param}2, \idx{param}1} |
| 25391 |
\cs{providecommand}\marg{\cmd{sortvonname}}[3]\marg{\idx{param}3, \idx{param}1 \idx{param}2}}} |
| 25392 |
\end{codeenv} |
| 25393 |
An alternative approach would be to format the names using |
| 25394 |
\BibTeX's contributor syntax and use |
| 25395 |
\csopt[name]{bibtex-contributor-fields} to convert them. |
| 25396 |
|
| 25397 |
There are also some synonyms provided with \atentry{index} |
| 25398 |
\glspl{entrytype} that have the \field{alias} field to redirect to the |
| 25399 |
\gls{mainentry}. These don't include a \field{description} or any of the other |
| 25400 |
fields as that would be redundant. All the information can be found |
| 25401 |
in the \gls{mainentry}. |
| 25402 |
|
| 25403 |
Except for the aliases, the entries have a custom field |
| 25404 |
\fieldfmt{identifier} set to \code{person}. This will be ignored by |
| 25405 |
\bibgls\ unless it's defined using \cs{glsaddkey} or |
| 25406 |
\cs{glsaddstoragekey} or if it's aliased with \csopt{field-aliases}. |
| 25407 |
|
| 25408 |
The contents of \filefmt{people.bib} are as follows: |
| 25409 |
\lstinputlisting[firstline=5]{../examples/people.bib} |
| 25410 |
|
| 25411 |
\filesection{books.bib} |
| 25412 |
|
| 25413 |
The \exfile{books.bib} file contains details about books. |
| 25414 |
As above, the entries use custom commands provided in |
| 25415 |
\exfile{no-interpret-preamble.bib} and |
| 25416 |
\exfile{interpret-preamble.bib} or |
| 25417 |
\exfile{interpret-preamble2.bib}. |
| 25418 |
The entries all have a custom field \fieldfmt{identifier} set to |
| 25419 |
\code{book} and other custom fields \fieldfmt{author} and |
| 25420 |
\fieldfmt{year}. |
| 25421 |
These will be ignored by \bibgls\ unless they're |
| 25422 |
defined using \cs{glsaddkey} or \cs{glsaddstoragekey} or if they're |
| 25423 |
aliased with \csopt{field-aliases}. |
| 25424 |
|
| 25425 |
There are other ways in which this data could be specified. For |
| 25426 |
example, the \field{description} field could contain a brief summary |
| 25427 |
(or \qt{log line}). The \fieldfmt{author} field could use \BibTeX's |
| 25428 |
syntax instead with \csopt{bibtex-contributor-fields} to convert it. |
| 25429 |
Alternatively, the entries could be defined using standard \BibTeX\ |
| 25430 |
\glspl{entrytype} that are all aliased to \atentry{bibtexentry}. |
| 25431 |
|
| 25432 |
The contents of \filefmt{books.bib} are as follows: |
| 25433 |
\lstinputlisting[firstline=5]{../examples/books.bib} |
| 25434 |
|
| 25435 |
\filesection{films.bib} |
| 25436 |
|
| 25437 |
The \exfile{films.bib} file contains details about films. |
| 25438 |
As above, the entries use custom commands provided in |
| 25439 |
\exfile{no-interpret-preamble.bib} and |
| 25440 |
\exfile{interpret-preamble.bib}. |
| 25441 |
The entries all have a custom field \fieldfmt{identifier} set to |
| 25442 |
\code{film} and other custom fields \fieldfmt{cast}, \fieldfmt{director} and |
| 25443 |
\fieldfmt{year}. These will be ignored by \bibgls\ unless they're |
| 25444 |
defined using \cs{glsaddkey} or \cs{glsaddstoragekey} or if they're |
| 25445 |
aliased with \csopt{field-aliases}. |
| 25446 |
|
| 25447 |
This example file references entries defined in \exfile{books.bib} |
| 25448 |
through the use of the special |
| 25449 |
\glsdisp{idx.idprefix.extn}{\idprefixfmt{ext1}} prefix. |
| 25450 |
To avoid a label conflict \exfile{films.bib} prefixes all labels |
| 25451 |
with \idprefixfmt{film} rather than relying on \csopt{label-prefix}. |
| 25452 |
This ensures that both \exfile{books.bib} and \exfile{films.bib} |
| 25453 |
can be loaded in the same resource set (otherwise they'd have to be |
| 25454 |
loaded in separate resource sets with different prefixes). Remember |
| 25455 |
that you can use \gls{glsxtrnewgls}. For example: |
| 25456 |
\begin{codeenv} |
| 25457 |
\gls{glsxtrnewgls}\marg{film.}\marg{\cmd{film}} |
| 25458 |
\end{codeenv} |
| 25459 |
This means you can do, for example, just \verb|\film{bladerunner}| |
| 25460 |
if you want to reference a film without worrying about the prefix. |
| 25461 |
|
| 25462 |
As with all the example files, there are other ways in which |
| 25463 |
to specify the data, depending on your requirements. For example, |
| 25464 |
the \fieldfmt{director} field could use \BibTeX's contributor syntax |
| 25465 |
(as the \fieldfmt{cast} field does). Some of |
| 25466 |
the films actually had more than one director but only one is listed |
| 25467 |
per film in this sample file for simplicity. Similarly, the |
| 25468 |
\fieldfmt{cast} field only contains the principal actors rather than the |
| 25469 |
complete list. The book on which the film is based |
| 25470 |
could be contained in a cross-reference field or a custom |
| 25471 |
\fieldfmt{basedon} field. |
| 25472 |
|
| 25473 |
The book \qt{Do Androids Dream of Electric Sheep?}\ referenced at the end |
| 25474 |
of the \qt{Blade Runner} film's \field{description} ends with |
| 25475 |
a question mark. (Similarly for \qt{Why Didn't They Ask Evans?}) |
| 25476 |
If the \field{description} field is simply set as: |
| 25477 |
\begin{codeenv} |
| 25478 |
\field{description}=\marg{a film starring Harrison Ford, Rutger Hauer |
| 25479 |
and Sean Young loosely based on the novel |
| 25480 |
\cs{gls}\marg{ext1.doandroidsdreamofelectricsheep}}, |
| 25481 |
\end{codeenv} |
| 25482 |
then the \styopt{postdot} package option will produce an odd |
| 25483 |
result as the inserted \idx{full-stop} immediately follows the question |
| 25484 |
mark. This is an awkward situation. One possibility is to explicitly |
| 25485 |
put the \idx{full-stop} at the end of the \field{description} field for all the |
| 25486 |
other entries and omit it for the problematic entries, but this |
| 25487 |
interferes with the possibility of a category-dependent |
| 25488 |
\idx{postdescriptionhook}. |
| 25489 |
|
| 25490 |
Another option is to put \ics{nopostdesc} in the |
| 25491 |
problematic entries. For example: |
| 25492 |
\begin{codeenv} |
| 25493 |
\field{description}=\marg{a film starring Harrison Ford, Rutger Hauer |
| 25494 |
and Sean Young loosely based on the novel |
| 25495 |
\cs{gls}\marg{ext1.doandroidsdreamofelectricsheep}\cs{nopostdesc}}, |
| 25496 |
\end{codeenv} |
| 25497 |
Be careful with this as it will completely suppress the |
| 25498 |
\idx{postdescriptionhook}. |
| 25499 |
A third possibility is to use \ics{glsxtrnopostpunc} instead: |
| 25500 |
\begin{codeenv} |
| 25501 |
\field{description}=\marg{a film starring Harrison Ford, Rutger Hauer |
| 25502 |
and Sean Young loosely based on the novel |
| 25503 |
\cs{gls}\marg{ext1.doandroidsdreamofelectricsheep}\cs{glsxtrnopostpunc}}, |
| 25504 |
\end{codeenv} |
| 25505 |
This doesn't interfere with the \idx{postdescriptionhook} but if a hook |
| 25506 |
is provided the post-punctuation may then be required. In both of |
| 25507 |
the above two cases, \csopt{strip-trailing-nopost} could be used |
| 25508 |
to remove the suppression commands from the \field{description} |
| 25509 |
fields if a hook is defined. However this doesn't deal with hooks |
| 25510 |
that only conditionally append text. |
| 25511 |
|
| 25512 |
The best solution is with \styfmt{glossaries-extra} v1.23+ which |
| 25513 |
provides \ics{glsxtrrestorepostpunc} for use in the category |
| 25514 |
\idxpl{postdescriptionhook} that counteracts \cs{glsxtrnopostpunc}. |
| 25515 |
This can be placed inside a \idx{conditional}, as used in |
| 25516 |
\exfile{sample-media.tex}, and does nothing if \cs{glsxtrnopostpunc} |
| 25517 |
doesn't occur in the \field{description} field. (Note that |
| 25518 |
\cs{glsxtrrestorepostpunc} can't be used to counteract |
| 25519 |
\cs{nopostdesc}, since that completely suppresses the hook.) |
| 25520 |
|
| 25521 |
The contents of \filefmt{films.bib} are as follows: |
| 25522 |
\lstinputlisting[firstline=5]{../examples/films.bib} |
| 25523 |
|
| 25524 |
\filesection{citations.bib} |
| 25525 |
|
| 25526 |
The \exfile{citations.bib} file is actually a \BibTeX\ file, but it |
| 25527 |
can be parsed by \bibgls\ if the \BibTeX\ \glspl{entrytype} are converted |
| 25528 |
to \atentry{bibtexentry}, which can easily be done with: |
| 25529 |
\begin{codeenv} |
| 25530 |
\csopt[\ics{GlsXtrBibTeXEntryAliases}]{entry-type-aliases} |
| 25531 |
\end{codeenv} |
| 25532 |
The field names will also need to be defined or aliased. For |
| 25533 |
example: |
| 25534 |
\begin{codeenv} |
| 25535 |
\csopt[\fieldfmt{title}=\field{name}]{field-aliases} |
| 25536 |
\end{codeenv} |
| 25537 |
If \bibgls\ is then run with \longarg{cite-as-record} any |
| 25538 |
\ics{citation} commands found in the \ext{aux} file will be treated |
| 25539 |
as ignored records. The \atentry{preamble} provides a formatting |
| 25540 |
command that's used by both \BibTeX\ and \bibgls, so \cs{providecommand} |
| 25541 |
is required rather than \cs{newcommand} as it will appear in both |
| 25542 |
the \iext{bbl} and the \iext{glstex} files. (In general it's best to |
| 25543 |
use \cs{providecommand} rather than \cs{newcommand} in the |
| 25544 |
\atentry{preamble} but in this case it's essential.) |
| 25545 |
The contents of \filefmt{citations.bib} are as follows: |
| 25546 |
\lstinputlisting[firstline=5]{../examples/citations.bib} |
| 25547 |
|
| 25548 |
\filesection{mathgreek.bib} |
| 25549 |
|
| 25550 |
The \exfile{mathgreek.bib} file contains Greek letters for use in |
| 25551 |
maths mode. These are all defined with \atentry{symbol}, which means |
| 25552 |
that by default the \field{sort} field will be obtained from the |
| 25553 |
label not from the \field{name} field. However, if you want to sort |
| 25554 |
by the \field{name} field (for example, with \csopt[name]{sort-field}) |
| 25555 |
the \texparserlib\ recognises all the mathematical Greek letter commands |
| 25556 |
provided in the \LaTeX\ kernel. Additionally it recognises |
| 25557 |
\ics{omicron} which isn't provided by \LaTeX\ (the symbol can be |
| 25558 |
reproduced with a \idx!{lowercase} Latin \qt{o}). Note that |
| 25559 |
\isty{glossaries-extra-bib2gls} (\sty{glossaries-extra} v1.27+) |
| 25560 |
provides all the missing Greek letters (such as \cs{omicron}). |
| 25561 |
|
| 25562 |
The \ext{bib} file could just use \code{o}: |
| 25563 |
\begin{codeenv} |
| 25564 |
\atentry{symbol}\marg{omicron, |
| 25565 |
\field{name}=\marg{\cs{ensuremath}\marg{o}}, |
| 25566 |
\field{description}=\marg{omicron}, |
| 25567 |
\fieldfmt{identifier}=\marg{mathgreek} |
| 25568 |
} |
| 25569 |
\end{codeenv} |
| 25570 |
but this means that if \bibgls\ sorts according to the \field{name} |
| 25571 |
field using a letter sort, this entry will come before all the other |
| 25572 |
Greek letters since the character \qt{o} has Unicode value \hex{6F} |
| 25573 |
whereas, for example, mathematical italic small alpha ($\alpha$) |
| 25574 |
has Unicode value \hex{1D6FC}. This means that for sorting purposes |
| 25575 |
it's better to use \ics{omicron}: |
| 25576 |
\begin{codeenv} |
| 25577 |
\atentry{symbol}\marg{omicron, |
| 25578 |
\field{name}=\marg{\cs{ensuremath}\marg{\cs{omicron}}}, |
| 25579 |
\field{description}=\marg{omicron}, |
| 25580 |
\fieldfmt{identifier}=\marg{mathgreek} |
| 25581 |
} |
| 25582 |
\end{codeenv} |
| 25583 |
but \LaTeX\ needs a definition for this, so it's provided in the |
| 25584 |
\atentry{preamble}: |
| 25585 |
\begin{codeenv} |
| 25586 |
\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cs{omicron}}\marg{o}}} |
| 25587 |
\end{codeenv} |
| 25588 |
(With \sty{glossaries-extra} v1.27+, this is no longer needed.) |
| 25589 |
The \texparserlib\ and \sty{glossaries-extra-bib2gls} |
| 25590 |
similarly provide the missing \idx!{uppercase} |
| 25591 |
Greek letters, and these can be dealt with in the same way. |
| 25592 |
|
| 25593 |
The contents of \filefmt{mathgreek.bib} are as follows: |
| 25594 |
\lstinputlisting[firstline=5]{../examples/mathgreek.bib} |
| 25595 |
|
| 25596 |
\filesection{bigmathsymbols.bib} |
| 25597 |
|
| 25598 |
The \exfile{bigmathsymbols.bib} file contains mathematical symbols |
| 25599 |
that have a large version in display mode. As with |
| 25600 |
\exfile{mathgreek.bib} the entries are defined using |
| 25601 |
\atentry{symbol}. This example file requires the \isty{stix} package |
| 25602 |
as not all of the commands are provided by the \LaTeX\ kernel. |
| 25603 |
This file also has a preamble: |
| 25604 |
\begin{codeenv} |
| 25605 |
\atentry{preamble}\marg{\qtdelim{\cmd{providecommand}\marg{\cmd{bigoperatornamefmt}}[1]\marg{\comment{} |
| 25606 |
\idx{mshiftchar}\ics{displaystyle}\idx{param}1\ics{textstyle}\idx{param}1\idx{mshiftchar}} |
| 25607 |
\cmd{providecommand}\marg{\cmd{nary}}[1]\marg{\idx{mshiftchar}\idx{param}1\idx{mshiftchar}-ary}}} |
| 25608 |
\end{codeenv} |
| 25609 |
The first command \inlinedef{bigoperatornamefmt} |
| 25610 |
is used in the \field{name} field to display both the in-line and display |
| 25611 |
versions of the symbol. The \texparserlib\ only has a limited ability to |
| 25612 |
interpret this as not all the symbols have Unicode in-line and large versions. |
| 25613 |
In some cases, such as the integral symbol $\int$, there is only a small |
| 25614 |
version. (A large version would require construction from \hex{2320}, |
| 25615 |
\hex{23AE} and \hex{2321}, which is too complicated in this context.) |
| 25616 |
However, the interpreter works well enough to guess at the widest |
| 25617 |
name if \csopt{set-widest} is used. There's no advantage in sorting |
| 25618 |
according to the \field{name} field here, unless a custom rule is |
| 25619 |
provided, as the Unicode symbols are scattered about different |
| 25620 |
blocks. Better approaches are to sort according to document use |
| 25621 |
(\csopt[use]{sort}) or to sort according to the \field{description} |
| 25622 |
field. |
| 25623 |
|
| 25624 |
The other custom command is \inlinedef{nary} to provide semantic markup for |
| 25625 |
\qt{$n$-ary}. This could be defined without an argument: |
| 25626 |
\begin{codeenv} |
| 25627 |
\cmd{providecommand}\marg{\cmd{nary}}\marg{\idx{mshiftchar}n\idx{mshiftchar}-ary} |
| 25628 |
\end{codeenv} |
| 25629 |
but providing an argument will allow \code{\csfmt{nary}\marg{n}} to work |
| 25630 |
with first letter upper-casing in the event that the |
| 25631 |
\field{description} field has a case-change applied (otherwise |
| 25632 |
it would end up as \qt{$N$-ARY}). Of course, it may be that no case-change |
| 25633 |
should be applied, but this example is just for illustrative purposes. |
| 25634 |
|
| 25635 |
As with the other sample \ext{bib} files, each entry is given a |
| 25636 |
custom \fieldfmt{identifier} field, which by default will be |
| 25637 |
ignored. In this case, \fieldfmt{identifier} is either set to |
| 25638 |
\code{naryoperator} (for $n$-ary operators) or \code{integral} |
| 25639 |
for integrals. |
| 25640 |
|
| 25641 |
The contents of \filefmt{bigmathsymbols.bib} are as follows: |
| 25642 |
\lstinputlisting[firstline=5]{../examples/bigmathsymbols.bib} |
| 25643 |
|
| 25644 |
\filesection{mathsrelations.bib} |
| 25645 |
|
| 25646 |
The \exfile{mathsrelations.bib} file contains mathematical |
| 25647 |
relational symbols. These use the maths shift character |
| 25648 |
\idx{mshiftchar} in the \field{name} field and just the symbol in |
| 25649 |
the \field{text} field. This just illustrates an alternative way of |
| 25650 |
defining symbols. Since \ics{ensuremath} isn't used, commands like |
| 25651 |
\cs{gls} must be explicitly placed in maths mode. For example, |
| 25652 |
\code{\idx{mshiftchar}\cs{gls}\marg{leq}\idx{mshiftchar}} rather than simply |
| 25653 |
\code{\cs{gls}\marg{leq}}. The custom \fieldfmt{identifier} field is |
| 25654 |
set to \code{relation}. |
| 25655 |
|
| 25656 |
The contents of \filefmt{mathsrelations.bib} are as follows: |
| 25657 |
\lstinputlisting[firstline=5]{../examples/mathsrelations.bib} |
| 25658 |
|
| 25659 |
\filesection{binaryoperators.bib} |
| 25660 |
|
| 25661 |
The \exfile{binaryoperators.bib} file contains mathematical binary |
| 25662 |
operators. The format is much like the above |
| 25663 |
\exfile{mathsrelations.bib} file. The custom \fieldfmt{identifier} |
| 25664 |
field is set to \code{binaryoperator}. |
| 25665 |
|
| 25666 |
The contents of \filefmt{binaryoperators.bib} are as follows: |
| 25667 |
\lstinputlisting[firstline=5]{../examples/binaryoperators.bib} |
| 25668 |
|
| 25669 |
\filesection{unaryoperators.bib} |
| 25670 |
|
| 25671 |
The \exfile{unaryoperators.bib} file contains mathematical unary |
| 25672 |
operators. As above, this again uses \atentry{symbol} to define the symbols, |
| 25673 |
but in this case \ics{ensuremath} is used in the \field{name} |
| 25674 |
field and there's no \field{text} field. I've also used \ics{mathord} |
| 25675 |
to ensure the symbol is treated as a unary (rather than binary) |
| 25676 |
operator, except for the \ics{forall} entry which is already defined as an |
| 25677 |
ordinary maths symbol. |
| 25678 |
|
| 25679 |
The contents of \filefmt{unaryoperators.bib} are as follows: |
| 25680 |
\lstinputlisting[firstline=5]{../examples/unaryoperators.bib} |
| 25681 |
|
| 25682 |
\filesection{mathsobjects.bib} |
| 25683 |
|
| 25684 |
The \exfile{mathsobjects.bib} file contains entries related to |
| 25685 |
mathematical objects (sets, spaces, vectors and matrices). This |
| 25686 |
provides some custom formatting commands in the preamble: |
| 25687 |
\nosecdef{setfmt} |
| 25688 |
which is used to format \meta{symbol} as a set, |
| 25689 |
\nosecdef{setcontentsfmt} |
| 25690 |
which is used to format the set contents, |
| 25691 |
\nosecdef{setmembershipfmt} |
| 25692 |
which is used to format the set membership criteria, |
| 25693 |
\nosecdef{setcardfmt} |
| 25694 |
which is used to format the cardinality of a set, |
| 25695 |
(Note this uses \ics{vert} not \textbar\ as in some of the earlier |
| 25696 |
examples.) |
| 25697 |
\nosecdef{numspacefmt} |
| 25698 |
which is used to format \meta{symbol} as a number space, |
| 25699 |
\nosecdef{transposefmt} |
| 25700 |
which is used to format matrix and vector transposes, |
| 25701 |
\nosecdef{invfmt} |
| 25702 |
which is used to format inverses, |
| 25703 |
\nosecdef{vecfmt} |
| 25704 |
which is used to format \meta{symbol} as a vector, and |
| 25705 |
\nosecdef{mtxfmt} |
| 25706 |
which is used to format \meta{symbol} as a matrix. |
| 25707 |
These commands are intended for use with \gls{glsxtrfmt}, |
| 25708 |
but \gls!{setmembershipfmt} causes a problem as it has two |
| 25709 |
arguments and \gls{glsxtrfmt} requires the control sequence to |
| 25710 |
have exactly one argument. This means employing a little trick. |
| 25711 |
A command with just one argument is provided: |
| 25712 |
\nosecdef{setmembershiponeargfmt} |
| 25713 |
that requires the actual two arguments to be supplied inside |
| 25714 |
\code{\idx!{param}1}. The outer grouping is removed and the two-argument |
| 25715 |
\gls!{setmembershipfmt} command is applied: |
| 25716 |
\begin{codeenv} |
| 25717 |
\cs{providecommand}\marg{\gls{setmembershiponeargfmt}}[1]\marg{\gls{setmembershipfmt}\idx{param}1} |
| 25718 |
\end{codeenv} |
| 25719 |
This means that the entry needs to be referenced in the document |
| 25720 |
using: |
| 25721 |
\begin{codeenv} |
| 25722 |
\gls{glsxtrfmt}\marg{setmembership}\marg{\margm{variable(s)}\margm{condition}} |
| 25723 |
\end{codeenv} |
| 25724 |
The simplest thing to do here is to provide a wrapper command in the |
| 25725 |
document, for example: |
| 25726 |
\begin{codeenv} |
| 25727 |
\cs{newcommand}*\marg{\cmd{setmembership}}[2]\marg{\gls{glsxtrfmt}\marg{setmembership}\marg{\marg{\idx{param}1}\marg{\idx{param}2}}} |
| 25728 |
\end{codeenv} |
| 25729 |
Now this can be used as: |
| 25730 |
\begin{codeenv} |
| 25731 |
\cmd{setmembership}\margm{variable(s)}\margm{condition} |
| 25732 |
\end{codeenv} |
| 25733 |
|
| 25734 |
There are essentially two types of entry defined in this file: |
| 25735 |
entries that demonstrate the formatting for the objects |
| 25736 |
and entries that represent specific objects. In the first case |
| 25737 |
there's a custom \fieldfmt{format} field |
| 25738 |
that's set to the control sequence name of the relevant semantic |
| 25739 |
command. If this field is defined or aliased then it can be used |
| 25740 |
with \gls!{glsxtrfmt} (as in the example above). |
| 25741 |
|
| 25742 |
In both cases there's a custom \fieldfmt{identifier} field that |
| 25743 |
reflects the type of object: \code{set} for sets, |
| 25744 |
\code{numberspace} for number spaces, |
| 25745 |
\code{matrix} for matrices or vectors. |
| 25746 |
|
| 25747 |
Be careful with the set cardinality example. Remember that nested |
| 25748 |
links cause problems and the \sty{glossaries-extra} manual advises |
| 25749 |
against using commands like \cs{gls} or \gls!{glsxtrfmt} within |
| 25750 |
link text and that includes within the \meta{text} argument of |
| 25751 |
\gls!{glsxtrfmt}. See \exfile{sample-maths.tex} for suggested |
| 25752 |
usage. |
| 25753 |
|
| 25754 |
Some of the \field{description} fields use \gls!{sortart}, so |
| 25755 |
\exfile{no-interpret-preamble.bib} and |
| 25756 |
\exfile{interpret-preamble.bib} are also needed. |
| 25757 |
|
| 25758 |
The contents of \filefmt{mathsobjects.bib} are as follows: |
| 25759 |
\lstinputlisting[firstline=5]{../examples/mathsobjects.bib} |
| 25760 |
|
| 25761 |
\filesection{miscsymbols.bib} |
| 25762 |
|
| 25763 |
The \exfile{miscsymbols.bib} file contains text symbols provided |
| 25764 |
by the \isty{marvosym} and \isty{ifsym} packages. The \sty{ifsym} |
| 25765 |
package needs to be loaded with the \styoptfmt{weather} option |
| 25766 |
to provide the weather commands. Unfortunately both packages define |
| 25767 |
\csfmt{Sun} and \csfmt{Lightning}, which causes a conflict. See |
| 25768 |
\exfile{sample-textsymbols.tex} for a workaround. Alternatively, |
| 25769 |
you can load \sty{ifsym} without the \styoptfmt{weather} option |
| 25770 |
and use the internal definition of \sty{ifsym}'s \csfmt{Sun} |
| 25771 |
and \csfmt{Lightning} commands: |
| 25772 |
\begin{codeenv} |
| 25773 |
\atentryfmt{icon}\marg{sun, |
| 25774 |
\fieldfmt{icon}=\marg{\ics{textweathersymbol}\marg{16}}, |
| 25775 |
\fieldfmt{description}=\marg{sunny}, |
| 25776 |
\fieldfmt{identifier}=\marg{weather} |
| 25777 |
} |
| 25778 |
\strut |
| 25779 |
\atentryfmt{icon}\marg{lightning, |
| 25780 |
\fieldfmt{icon}=\marg{\cs{textweathersymbol}\marg{26}}, |
| 25781 |
\field{description}=\marg{thunderstorm}, |
| 25782 |
\fieldfmt{identifier}=\marg{weather} |
| 25783 |
} |
| 25784 |
\end{codeenv} |
| 25785 |
This removes the conflict, and \csfmt{Sun} and \csfmt{Lightning} |
| 25786 |
are as defined by \sty{marvosym}. |
| 25787 |
|
| 25788 |
This file uses a custom \gls{entrytype} \atentryfmt{icon}, which must be |
| 25789 |
aliased to a recognised entry identifier otherwise the entries will |
| 25790 |
all be ignored. For example: |
| 25791 |
\begin{codeenv} |
| 25792 |
\csopt[\fieldfmt{icon}=\field{symbol}]{entry-type-aliases} |
| 25793 |
\end{codeenv} |
| 25794 |
|
| 25795 |
There are three types of symbols defined: media controls, information |
| 25796 |
and weather. They have the custom \fieldfmt{identifier} |
| 25797 |
field set to \code{mediacontrol}, \code{information} and |
| 25798 |
\code{weather}, respectively. There are two other custom fields: |
| 25799 |
\fieldfmt{icon} and \fieldfmt{icondescription}. These will need to |
| 25800 |
be aliased to \field{name} and \field{description}. |
| 25801 |
|
| 25802 |
Neither of these packages are recognised by \bibgls, which means |
| 25803 |
that \csopt{set-widest} won't be able to determine the widest name |
| 25804 |
nor is this data suitable for sorting according to the |
| 25805 |
\fieldfmt{icon} field (or its alias). Instead, either sort by label |
| 25806 |
(which is the default for \atentry{symbol}) or by the |
| 25807 |
\field{description}. If you want to use one of the |
| 25808 |
\glostyle{alttree} styles you can still use \csopt{set-widest}, but |
| 25809 |
it will have to use the fallback command. Alternatively, you can |
| 25810 |
omit \csopt{set-widest} and explicitly use |
| 25811 |
\cs{glsFindWidestTopLevelName}. |
| 25812 |
|
| 25813 |
The contents of \filefmt{miscsymbols.bib} are as follows: |
| 25814 |
\lstinputlisting[firstline=5]{../examples/miscsymbols.bib} |
| 25815 |
|
| 25816 |
\filesection{markuplanguages.bib} |
| 25817 |
|
| 25818 |
The \exfile{markuplanguages.bib} file includes a mixture of |
| 25819 |
\atentry{entry} and \atentry{abbreviation} definitions. A~custom |
| 25820 |
command is provided in \atentry{preamble} to tag the letters |
| 25821 |
in the \field{long} field that are used to form the abbreviation. |
| 25822 |
This simply does its argument and is provided in case it's not set |
| 25823 |
up in the document. If you do want to enable tagging using |
| 25824 |
\ics{GlsXtrEnableInitialTagging}, remember that this command must be |
| 25825 |
used before the abbreviations are defined, which means before |
| 25826 |
the resource file is input with \gls{GlsXtrLoadResources}. |
| 25827 |
Similarly, the abbreviation style must be set before the |
| 25828 |
abbreviations are defined. |
| 25829 |
|
| 25830 |
For convenience \atentry{string} is also used to define a \ext{bib} |
| 25831 |
variable, which may be appended to fields using the \ext{bib} |
| 25832 |
concatenation character \idx{stringconcat}. As with the other sample |
| 25833 |
\ext{bib} files, there's a custom field \fieldfmt{identifier} |
| 25834 |
which will be ignored unless defined or aliased. |
| 25835 |
|
| 25836 |
The empty braces at the start some of the fields are there to |
| 25837 |
protect against first letter uppercasing within \TeX, where it might cause a |
| 25838 |
problem. (For example, with the \catattr{glossname} attribute.) |
| 25839 |
|
| 25840 |
The contents of \filefmt{markuplanguages.bib} are as follows: |
| 25841 |
\lstinputlisting[firstline=5]{../examples/markuplanguages.bib} |
| 25842 |
|
| 25843 |
\filesection{usergroups.bib} |
| 25844 |
|
| 25845 |
The \exfile{usergroups.bib} file requires either \XeLaTeX\ or |
| 25846 |
\LuaLaTeX\ as some of the entry labels use \idx{non-ASCII} characters. |
| 25847 |
This file has a mixture of \atentry{abbreviation} and |
| 25848 |
\atentry{index} entries. It also uses \atentry{string} for |
| 25849 |
convenience and provides a custom command \csfmt{dash} in |
| 25850 |
\atentry{preamble}. Each entry is the name of a \TeX\ user group: |
| 25851 |
the international \idx{TUG} and all the local groups. |
| 25852 |
Most of them have an abbreviated name, so they're defined with |
| 25853 |
\atentry{abbreviation}. There are a few without an abbreviation, so |
| 25854 |
they're defined with \atentry{index} instead. There's one alias. |
| 25855 |
(The information was obtained from \idx{TUG}['s] |
| 25856 |
\href{http://tug.org/usergroups.html}{user groups |
| 25857 |
page}~\cite{tugusergroups}.) |
| 25858 |
|
| 25859 |
As with the other examples, there are some custom fields which will |
| 25860 |
be ignored if they aren't defined or aliased: \fieldfmt{identifier} |
| 25861 |
(set to \code{texusergroup}), \fieldfmt{language} (a comma-separated |
| 25862 |
list of language tags) and \fieldfmt{translation} (provides a |
| 25863 |
translation if the user group name isn't in English). |
| 25864 |
|
| 25865 |
Not all entries have a \fieldfmt{translation} field. It it's |
| 25866 |
omitted, then the user group name is in English, otherwise it's |
| 25867 |
in the first language listed in the \fieldfmt{language} field. |
| 25868 |
Most of the language tags are just the ISO 639-1 language code, but |
| 25869 |
a few of them include the ISO 3166-1 region code as well. |
| 25870 |
|
| 25871 |
The contents of \filefmt{usergroups.bib} are as follows: |
| 25872 |
\begin{lstlisting}[escapechar=|] |
| 25873 |
% Encoding: UTF-8 |
| 25874 |
|
| 25875 |
% Requires XeLaTeX/LuaLaTeX for non-ASCII labels |
| 25876 |
|
| 25877 |
@string{tug={\TeX\ Users Group}} |
| 25878 |
|
| 25879 |
@preamble{"\providecommand{\dash}{\,---\,}"} |
| 25880 |
|
| 25881 |
@abbreviation{TUG, |
| 25882 |
short={TUG}, |
| 25883 |
long=tug, |
| 25884 |
language={en}, |
| 25885 |
identifier={texusergroup} |
| 25886 |
} |
| 25887 |
|
| 25888 |
@abbreviation{bgTeX, |
| 25889 |
short={bgTeX}, |
| 25890 |
long={Bulgarian \LaTeX\ Users Group}, |
| 25891 |
language={bg}, |
| 25892 |
identifier={texusergroup} |
| 25893 |
} |
| 25894 |
|
| 25895 |
@abbreviation{latex-br, |
| 25896 |
short={latex-br}, |
| 25897 |
long={Grupo de Usuários}, |
| 25898 |
language={pt-BR}, |
| 25899 |
identifier={texusergroup}, |
| 25900 |
translation={Brazilian }#tug |
| 25901 |
} |
| 25902 |
|
| 25903 |
@abbreviation{CTeX, |
| 25904 |
short={CTeX}, |
| 25905 |
long={Chinese \TeX\ Society}, |
| 25906 |
identifier={texusergroup}, |
| 25907 |
language={zh} |
| 25908 |
} |
| 25909 |
|
| 25910 |
@abbreviation{CSTUG, |
| 25911 |
short={CSTUG}, |
| 25912 |
long={|Československé sdružení uživatelů TeXu|, z.~s.}, |
| 25913 |
language={cs}, |
| 25914 |
identifier={texusergroup}, |
| 25915 |
translation={Czech Republic }#tug |
| 25916 |
} |
| 25917 |
|
| 25918 |
@abbreviation{DANTE, |
| 25919 |
short={DANTE e.V.}, |
| 25920 |
long={Deutschsprachige Anwendervereinigung \TeX\ e.V.}, |
| 25921 |
language={de}, |
| 25922 |
identifier={texusergroup}, |
| 25923 |
translation={German Speaking }#tug |
| 25924 |
} |
| 25925 |
|
| 25926 |
@abbreviation{DKTUG, |
| 25927 |
short={DK-TUG}, |
| 25928 |
long={Danish }#tug, |
| 25929 |
language={da}, |
| 25930 |
identifier={texusergroup} |
| 25931 |
} |
| 25932 |
|
| 25933 |
@index{EUG, |
| 25934 |
name={Estonian User Group}, |
| 25935 |
language={et}, |
| 25936 |
identifier={texusergroup} |
| 25937 |
} |
| 25938 |
|
| 25939 |
@abbreviation{CervanTeX, |
| 25940 |
short={CervanTeX}, |
| 25941 |
long={Grupo de Usuarios de \TeX\ Hispanohablantes}, |
| 25942 |
language={es}, |
| 25943 |
identifier={texusergroup}, |
| 25944 |
translation={Spanish Speaking }#tug |
| 25945 |
} |
| 25946 |
|
| 25947 |
@abbreviation{TirantloTeX, |
| 25948 |
short={Tirant lo \TeX}, |
| 25949 |
long={Catalan }#tug, |
| 25950 |
language={ca}, |
| 25951 |
identifier={texusergroup} |
| 25952 |
} |
| 25953 |
|
| 25954 |
@abbreviation{GUTenberg, |
| 25955 |
short={GUTenberg}, |
| 25956 |
long={Groupe francophone des utilisateurs de \TeX}, |
| 25957 |
language={fr}, |
| 25958 |
identifier={texusergroup}, |
| 25959 |
translation={French Speaking }#tug |
| 25960 |
} |
| 25961 |
|
| 25962 |
@abbreviation{UKTUG, |
| 25963 |
short={UK-TUG}, |
| 25964 |
long={UK }#tug, |
| 25965 |
language={en-GB}, |
| 25966 |
identifier={texusergroup} |
| 25967 |
} |
| 25968 |
|
| 25969 |
@abbreviation{|\greekmono ɛϕτ|, |
| 25970 |
short={|\greekmono ɛϕτ|}, |
| 25971 |
long={|\greekmono Σύλλογος Ελλήνων Φίλων του| \TeX}, |
| 25972 |
language={el}, |
| 25973 |
identifier={texusergroup}, |
| 25974 |
translation={Greek \TeX\ Friends} |
| 25975 |
} |
| 25976 |
|
| 25977 |
@abbreviation{MaTeX, |
| 25978 |
short={MaTeX}, |
| 25979 |
long={Magyar \TeX\ Egyesület}, |
| 25980 |
language={hu}, |
| 25981 |
identifier={texusergroup}, |
| 25982 |
translation={Hungarian }#tug |
| 25983 |
} |
| 25984 |
|
| 25985 |
@abbreviation{ITALIC, |
| 25986 |
short={ITALIC}, |
| 25987 |
long={Irish \TeX\ and \LaTeX\ In-print Community}, |
| 25988 |
language={en-IE,en-GB}, |
| 25989 |
identifier={texusergroup} |
| 25990 |
} |
| 25991 |
|
| 25992 |
@abbreviation{ÍsTeX, |
| 25993 |
short={ÍsTeX}, |
| 25994 |
long={Vefur íslenskra \TeX\ notenda}, |
| 25995 |
language={is}, |
| 25996 |
identifier={texusergroup}, |
| 25997 |
translation={Icelandic }#tug |
| 25998 |
} |
| 25999 |
|
| 26000 |
@abbreviation{GuIT, |
| 26001 |
short={GuIT}, |
| 26002 |
long={Gruppo Utilizzatori Italiani di \TeX}, |
| 26003 |
language={it}, |
| 26004 |
identifier={texusergroup}, |
| 26005 |
translation={Italian }#tug |
| 26006 |
} |
| 26007 |
|
| 26008 |
@abbreviation{KTS, |
| 26009 |
short={KTS}, |
| 26010 |
identifier={texusergroup}, |
| 26011 |
long={Korean \TeX\ Society}, |
| 26012 |
language={ko} |
| 26013 |
} |
| 26014 |
|
| 26015 |
@index{KTUG, |
| 26016 |
alias={KTS}, |
| 26017 |
identifier={texusergroup} |
| 26018 |
} |
| 26019 |
|
| 26020 |
@index{LTVG, |
| 26021 |
name={Lietuvos \TeX'o |Vartotojų Grupė|}, |
| 26022 |
language={lt}, |
| 26023 |
identifier={texusergroup}, |
| 26024 |
translation={Lithuanian }#tug |
| 26025 |
} |
| 26026 |
|
| 26027 |
@index{mxTeX, |
| 26028 |
name={\TeX\ México}, |
| 26029 |
language={es-MX}, |
| 26030 |
identifier={texusergroup}, |
| 26031 |
translation={Mexican }#tug |
| 26032 |
} |
| 26033 |
|
| 26034 |
@abbreviation{NTG, |
| 26035 |
short={NTG}, |
| 26036 |
long={Nederlandstalige \TeX\ Gebruikersgroep}, |
| 26037 |
language={nl}, |
| 26038 |
identifier={texusergroup}, |
| 26039 |
translation={Netherlands }#tug |
| 26040 |
} |
| 26041 |
|
| 26042 |
@index{NTUG, |
| 26043 |
name={Nordic \TeX\ Users Group}, |
| 26044 |
language={da,et,fi,fo,is,nb,nn,sv}, |
| 26045 |
identifier={texusergroup} |
| 26046 |
} |
| 26047 |
|
| 26048 |
@abbreviation{GUST, |
| 26049 |
short={GUST}, |
| 26050 |
long={Polska Grupa |Użytkowników| Systemu \TeX}, |
| 26051 |
language={pl}, |
| 26052 |
identifier={texusergroup}, |
| 26053 |
translation={Polish }#tug |
| 26054 |
} |
| 26055 |
|
| 26056 |
@abbreviation{GUTpt, |
| 26057 |
short={GUTpt}, |
| 26058 |
long={Grupo de Utilizadores de \TeX}, |
| 26059 |
language={pt}, |
| 26060 |
identifier={texusergroup}, |
| 26061 |
translation={Portuguese }#tug |
| 26062 |
} |
| 26063 |
|
| 26064 |
@abbreviation{VietTUG, |
| 26065 |
short={VietTUG}, |
| 26066 |
long={Vietnamese }#tug, |
| 26067 |
language={vi}, |
| 26068 |
identifier={texusergroup} |
| 26069 |
} |
| 26070 |
|
| 26071 |
@abbreviation{LUGSA, |
| 26072 |
short={LUGSA}, |
| 26073 |
long={\LaTeX\ User Group\dash South Africa}, |
| 26074 |
language={en-ZA}, |
| 26075 |
identifier={texusergroup} |
| 26076 |
} |
| 26077 |
|
| 26078 |
|
| 26079 |
\end{lstlisting} |
| 26080 |
|
| 26081 |
\filesection{animals.bib} |
| 26082 |
|
| 26083 |
The \exfile{animals.bib} file contains entries defined using |
| 26084 |
\atentry{entry}. As with the above example \ext{bib} files, there's |
| 26085 |
a custom \fieldfmt{identifier} field that will be ignored unless |
| 26086 |
defined or aliased. |
| 26087 |
|
| 26088 |
The contents of \filefmt{animals.bib} are as follows: |
| 26089 |
\lstinputlisting[firstline=5]{../examples/animals.bib} |
| 26090 |
|
| 26091 |
\filesection{minerals.bib} |
| 26092 |
|
| 26093 |
The \exfile{minerals.bib} file contains entries defined using |
| 26094 |
\atentry{entry}. As with the above example \ext{bib} files, there's |
| 26095 |
a custom \fieldfmt{identifier} field that will be ignored unless |
| 26096 |
defined or aliased. |
| 26097 |
|
| 26098 |
The contents of \filefmt{minerals.bib} are as follows: |
| 26099 |
\lstinputlisting[firstline=5]{../examples/minerals.bib} |
| 26100 |
|
| 26101 |
\filesection{vegetables.bib} |
| 26102 |
|
| 26103 |
The \exfile{vegetables.bib} file contains entries defined using |
| 26104 |
\atentry{entry} and an entry defined with \atentry{index} with just |
| 26105 |
the \field{alias} field. As with the above example \ext{bib} files, there's |
| 26106 |
a custom \fieldfmt{identifier} field that will be ignored unless |
| 26107 |
defined or aliased. |
| 26108 |
|
| 26109 |
The contents of \filefmt{vegetables.bib} are as follows: |
| 26110 |
\lstinputlisting[firstline=5]{../examples/vegetables.bib} |
| 26111 |
|
| 26112 |
\filesection{terms.bib} |
| 26113 |
|
| 26114 |
The \exfile{terms.bib} file contains entries defined using |
| 26115 |
\atentry{index}. Unlike the above sample \ext{bib} files, there |
| 26116 |
are no custom fields here. |
| 26117 |
|
| 26118 |
The contents of \filefmt{terms.bib} are as follows: |
| 26119 |
\lstinputlisting[firstline=5]{../examples/terms.bib} |
| 26120 |
|
| 26121 |
\filesection{topics.bib} |
| 26122 |
|
| 26123 |
The \exfile{topics.bib} file contains entries defined using |
| 26124 |
\atentry{index}. Again there are no custom fields here. |
| 26125 |
|
| 26126 |
The contents of \filefmt{topics.bib} are as follows: |
| 26127 |
\lstinputlisting[firstline=5]{../examples/topics.bib} |
| 26128 |
|
| 26129 |
\filesection{sample-hierarchical.tex} |
| 26130 |
|
| 26131 |
This example uses the \exfile{terms.bib}, \exfile{animals.bib}, |
| 26132 |
\exfile{minerals.bib} and \exfile{vegetables.bib} files to create a |
| 26133 |
\gls{hierarchicalglossary}. These are specified with the resource option: |
| 26134 |
\begin{codeenv} |
| 26135 |
\csopt[{terms,animals,minerals,vegetables}]{src} |
| 26136 |
\end{codeenv} |
| 26137 |
The custom \fieldfmt{identifier} field is |
| 26138 |
aliased to the \field{parent} field since it conveniently matches |
| 26139 |
the labels of the animal, mineral and vegetable entries in the |
| 26140 |
\exfile{terms.bib} file: |
| 26141 |
\begin{codeenv} |
| 26142 |
\csopt[{identifier=parent}]{field-aliases} |
| 26143 |
\end{codeenv} |
| 26144 |
The default \csopt{selection} setting means that only those terms |
| 26145 |
referenced in the document and their dependencies are selected. The |
| 26146 |
referenced entries simply have \qt{1} in the \igls{locationlist} as |
| 26147 |
it's only a trivial single-paged example. |
| 26148 |
|
| 26149 |
The dependencies that haven't actually been referenced in the |
| 26150 |
document don't have a \igls{locationlist}. (The \qt{seal} entry is a |
| 26151 |
dependency, but it's also been referenced in the document, so it has a |
| 26152 |
\igls{locationlist}.) The \qt{quartz}, \qt{beryl} and \qt{marrow} |
| 26153 |
entries are dependencies because they occur in the description of |
| 26154 |
some of the referenced entries. Normally this would mean that they |
| 26155 |
have no \igls{locationlist} after the first \LaTeX+\bibgls+\LaTeX\ |
| 26156 |
build but once the glossary has been created the references to those |
| 26157 |
dependent entries in the descriptions will create records and so on |
| 26158 |
the next \bibgls+\LaTeX\ they will also have \iglspl{locationlist}. |
| 26159 |
This would make the complete document build: |
| 26160 |
\begin{verbatim} |
| 26161 |
pdflatex sample-hierarchical |
| 26162 |
bib2gls --group sample-hierarchical |
| 26163 |
pdflatex sample-hierarchical |
| 26164 |
bib2gls --group sample-hierarchical |
| 26165 |
pdflatex sample-hierarchical |
| 26166 |
\end{verbatim} |
| 26167 |
However, in this example I've decided to \glsdisp{ignoredrecord}{ignore} any records |
| 26168 |
created in the glossary: |
| 26169 |
\begin{codeenv} |
| 26170 |
\ics{GlsXtrSetDefaultNumberFormat}\marg{\encap{glsignore}} |
| 26171 |
\end{codeenv} |
| 26172 |
This means that the document build is the usual \LaTeX+\bibgls+\LaTeX. |
| 26173 |
|
| 26174 |
I've used the \glostyle{treegroup} style so I need to invoke |
| 26175 |
\bibgls\ with the \longarg{group} switch. This creates letter groups |
| 26176 |
for the \glspl{top-levelentry}. Note that \glspl{sub-entry} never have letter groups. |
| 26177 |
|
| 26178 |
The complete code is listed below. The document build is: |
| 26179 |
\begin{verbatim} |
| 26180 |
pdflatex sample-hierarchical |
| 26181 |
bib2gls --group sample-hierarchical |
| 26182 |
pdflatex sample-hierarchical |
| 26183 |
\end{verbatim} |
| 26184 |
The complete document is shown in \figureref{fig:sample-hierarchical.pdf}. |
| 26185 |
|
| 26186 |
\lstinputlisting[firstline=5]{../examples/sample-hierarchical.tex} |
| 26187 |
|
| 26188 |
\begin{figure} |
| 26189 |
\figcontents |
| 26190 |
{% |
| 26191 |
\frame{\includegraphics[height=.9\textheight]{../examples/sample-hierarchical.pdf}}% |
| 26192 |
} |
| 26193 |
{\caption{\filefmt{sample-hierarchical.pdf}}} |
| 26194 |
{fig:sample-hierarchical.pdf} |
| 26195 |
\end{figure} |
| 26196 |
|
| 26197 |
\filesection{sample-nested.tex} |
| 26198 |
|
| 26199 |
As discussed in \sectionref{sec:logicaldivisions} there are three |
| 26200 |
ways of creating logical divisions when displaying the entries |
| 26201 |
through the use of the \field{type}, \field{group} and \field{parent} fields. |
| 26202 |
In general, \glspl{hierarchicalglossary} are created with |
| 26203 |
the \field{parent} field and an appropriate glossary style (as in |
| 26204 |
the previous \exfile{sample-hierarchical.tex} example). |
| 26205 |
|
| 26206 |
This example creates a \hierarchical\ effect but the entries don't |
| 26207 |
actually have a \hierarchical\ structure as none of them have the |
| 26208 |
\field{parent} field set. Instead, what were the \glspl{childentry} in |
| 26209 |
\exfile{sample-hierarchical.tex} now have the \field{type} field |
| 26210 |
set. The \hierarchical\ effect is achieved with |
| 26211 |
\ics{printunsrtinnerglossary} (which requires at least |
| 26212 |
\sty{glossaries-extra} v1.44). |
| 26213 |
|
| 26214 |
\begin{important} |
| 26215 |
The \ics{printunsrtinnerglossary} command is unsuitable for use |
| 26216 |
with tabular-like styles, such as \glostyle{long}, and can be |
| 26217 |
problematic with \glostyle{list} styles. However, those styles |
| 26218 |
aren't suitable for \glspl{hierarchicalglossary} anyway. |
| 26219 |
\end{important} |
| 26220 |
|
| 26221 |
Normally, \hierarchy\ is achieve through definitions like: |
| 26222 |
\begin{codeenv} |
| 26223 |
\atentry{index}\marg{animal} |
| 26224 |
\atentry{entry}\marg{duck,\field{name}=\marg{duck}, |
| 26225 |
\field{description}=\marg{a waterbird with webbed feet}, |
| 26226 |
\field{parent}=\marg{animal} |
| 26227 |
} |
| 26228 |
\end{codeenv} |
| 26229 |
The previous example did this by loading both the \exfile{terms.bib} |
| 26230 |
and \exfile{animals.bib} files and aliasing the custom |
| 26231 |
\fieldfmt{identifier} field to \field{parent}. In this example, the |
| 26232 |
custom field is aliased to \field{type}, which effectively makes the |
| 26233 |
definitions behave like: |
| 26234 |
\begin{codeenv} |
| 26235 |
\atentry{index}\marg{animal} |
| 26236 |
\atentry{entry}\marg{duck,\field{name}=\marg{duck}, |
| 26237 |
\field{description}=\marg{a waterbird with webbed feet}, |
| 26238 |
\field{type}=\marg{animal} |
| 26239 |
} |
| 26240 |
\end{codeenv} |
| 26241 |
The aim here is for the \code{animal} entry to be placed in the |
| 26242 |
\gls{mainglossary} so that it's listed with \cs{printunsrtglossary}. The |
| 26243 |
\code{duck} entry is placed in a glossary that has a label |
| 26244 |
(\code{animal}) that matches the label of the \qt{parent} entry |
| 26245 |
(even though it's technically not a \parent). This new glossary |
| 26246 |
(\code{animal}) can be automatically defined by invoking \bibgls\ |
| 26247 |
with the \longarg{provide-glossaries} switch. |
| 26248 |
|
| 26249 |
This example document defines a custom handler function that |
| 26250 |
will do the current entry as normal (with \cs{glsxtrunsrtdo}) but |
| 26251 |
will then check for the existence of a glossary that has the same |
| 26252 |
label as the current entry. This requires the starred version of |
| 26253 |
\ics{ifglossaryexists} to included ignored glossaries in the |
| 26254 |
existence check. If the glossary exists, it's then displayed using |
| 26255 |
\ics{printunsrtinnerglossary}: |
| 26256 |
\begin{codeenv} |
| 26257 |
\cs{newcommand}\marg{\csfmt{nestedhandler}}[1]\marg{\comment{} |
| 26258 |
\cs{glsxtrunsrtdo}\marg{\idx{hashchar}1}\comment{} |
| 26259 |
\ics{ifglossaryexists*}\marg{\idx{hashchar}1}\comment{} |
| 26260 |
\marg{\comment{} |
| 26261 |
\cs{printunsrtinnerglossary}\oarg{\printglossopt[\idx{hashchar}1]{type},\printglossopt[++1]{leveloffset},\printglossopt[false]{groups}} |
| 26262 |
\marg{}\marg{}\comment{} |
| 26263 |
}\comment{} |
| 26264 |
\marg{}\comment{} |
| 26265 |
} |
| 26266 |
\end{codeenv} |
| 26267 |
The \printglossopt{leveloffset} option is required to achieve a |
| 26268 |
\hierarchical\ effect (provided the glossary style supports it) and |
| 26269 |
the \printglossopt[false]{groups} option is needed to prevent letter |
| 26270 |
groups showing for the nested glossary, which would otherwise create |
| 26271 |
a strange effect. (This example uses the \glostyle{treegroup} style, |
| 26272 |
which provides a \gls{hierarchicalglossary} with letter groups.) |
| 26273 |
|
| 26274 |
The \cs{printunsrtglossary} handler macro then needs to be set to |
| 26275 |
this custom macro when the \gls{mainglossary} is displayed: |
| 26276 |
\begin{codeenv} |
| 26277 |
\cs{printunsrtglossary*}\marg{\cs{let}\cs{printunsrtglossaryhandler}\csfmt{nestedhandler}} |
| 26278 |
\end{codeenv} |
| 26279 |
The main difficulty comes with ensuring that all the necessary |
| 26280 |
entries are selected. Now that the custom \fieldfmt{identifier} |
| 26281 |
field has been aliased to \field{type} rather than \field{parent}, |
| 26282 |
the \code{animal} entry is no longer considered a dependent. The |
| 26283 |
\code{duck} entry has been referenced in the document with \cs{gls} |
| 26284 |
but the \code{animal} entry hasn't. The previous example ensured |
| 26285 |
that the \code{animal} entry was selected because it was a \parent\ of |
| 26286 |
a selected entry. If the same resource options are used in this |
| 26287 |
example, the \gls{mainglossary} will be empty, which means that the |
| 26288 |
nested glossaries won't be displayed either. |
| 26289 |
|
| 26290 |
One way to ensure that the \code{animal}, \code{mineral} and |
| 26291 |
\code{vegetable} entries are selected is to identify the \field{type} |
| 26292 |
field as a dependency field: |
| 26293 |
\begin{codeenv} |
| 26294 |
\gls{GlsXtrLoadResources}\oarg{\csopt[{terms,animals,minerals,vegetables}]{src}, |
| 26295 |
\csopt[{identifier=type}]{field-aliases}, |
| 26296 |
\csopt[{type}]{dependency-fields} |
| 26297 |
} |
| 26298 |
\end{codeenv} |
| 26299 |
This will achieve the same effect as the |
| 26300 |
\exfile{sample-hierarchical.tex} document, but it's a far more |
| 26301 |
convoluted method. The reason this example document is listed here |
| 26302 |
is to demonstrate a sightly modified \hierarchical\ effect that can't |
| 26303 |
be achieved through the normal method. |
| 26304 |
|
| 26305 |
Suppose that, for some strange reason, I want the \qt{animal}, |
| 26306 |
\qt{mineral} and \qt{vegetable} entries to be listed in a different |
| 26307 |
order (say, reverse alphabetical). The other entries (\qt{duck} etc) |
| 26308 |
need to be sorted in normal alphabetical order. |
| 26309 |
|
| 26310 |
The \csopt{sort} option applies the same sort method to all |
| 26311 |
\hierarchical\ levels. The sort \emph{value} chosen for particular entries |
| 26312 |
can be altered through the use of fallbacks (such as the |
| 26313 |
\csopt{entry-sort-fallback} or \csopt{symbol-sort-fallback} options) |
| 26314 |
and a letter comparator may be used to resolve identical sort |
| 26315 |
values (\csopt{identical-sort-action}), but the same sort algorithm |
| 26316 |
is applied to all entries in the same set (primary, secondary or dual |
| 26317 |
within the same resource set). The only way to apply different sort |
| 26318 |
methods is to separate the entries into different resource sets (or |
| 26319 |
use dual or secondary sorting). |
| 26320 |
|
| 26321 |
This can be achieved by having one resource set for the \glspl{mainentry} |
| 26322 |
with one sort method and another resource set for all the other |
| 26323 |
entries with a different sort method: |
| 26324 |
\begin{codeenv} |
| 26325 |
\gls{GlsXtrLoadResources}\oarg{\csopt[terms]{src},\csopt[en-reverse]{sort}} |
| 26326 |
|
| 26327 |
\gls{GlsXtrLoadResources}\oarg{\csopt[animals,minerals,vegetables]{src},\csopt[en]{sort}, |
| 26328 |
\csopt[{identifier=type}]{field-aliases},\csopt[{type}]{dependency-fields} |
| 26329 |
} |
| 26330 |
\end{codeenv} |
| 26331 |
This works when cross-resource dependencies are permitted (see |
| 26332 |
\sectionref{sec:resourcesets}). In the event that cross-resource |
| 26333 |
dependencies aren't permitted, the selection criteria is more |
| 26334 |
complicated: |
| 26335 |
\begin{codeenv} |
| 26336 |
\gls{GlsXtrLoadResources}\oarg{\csopt[terms,animals,minerals,vegetables]{src}, |
| 26337 |
\csopt[en-reverse]{sort}, |
| 26338 |
\csopt[{identifier=parent}]{field-aliases}, |
| 26339 |
\csopt[ancestors but not recorded]{selection} |
| 26340 |
} |
| 26341 |
|
| 26342 |
\gls{GlsXtrLoadResources}\oarg{ |
| 26343 |
\csopt[animals,minerals,vegetables]{src}, |
| 26344 |
\csopt[{identifier=type}]{field-aliases}, |
| 26345 |
\csopt[{type}]{dependency-fields} |
| 26346 |
\csopt[en]{sort} |
| 26347 |
} |
| 26348 |
\end{codeenv} |
| 26349 |
Fortunately in this example, cross-resource dependencies are |
| 26350 |
permitted so the simpler alternative works. (If they're not |
| 26351 |
permitted, the \bibgls\ transcript file will contain |
| 26352 |
\qt{Cross-resource references can't be supported for resource set |
| 26353 |
\meta{filename}}.) |
| 26354 |
|
| 26355 |
The complete code is listed below. The document build is: |
| 26356 |
\begin{verbatim} |
| 26357 |
pdflatex sample-nested |
| 26358 |
bib2gls --group --provide-glossaries sample-nested |
| 26359 |
pdflatex sample-nested |
| 26360 |
\end{verbatim} |
| 26361 |
The complete document is shown in \figureref{fig:sample-nested.pdf}. |
| 26362 |
|
| 26363 |
\lstinputlisting[firstline=5]{../examples/sample-nested.tex} |
| 26364 |
|
| 26365 |
\begin{figure} |
| 26366 |
\figcontents |
| 26367 |
{% |
| 26368 |
\frame{\includegraphics[height=.9\textheight]{../examples/sample-nested.pdf}}% |
| 26369 |
} |
| 26370 |
{\caption{\filefmt{sample-nested.pdf}}} |
| 26371 |
{fig:sample-nested.pdf} |
| 26372 |
\end{figure} |
| 26373 |
|
| 26374 |
\filesection{sample-constants.tex} |
| 26375 |
|
| 26376 |
This example uses the \exfile{constants.bib} file. The aim here |
| 26377 |
is to just have a list of all the constants defined in the \ext{bib} |
| 26378 |
file. (There are no references in the document.) This means I need |
| 26379 |
to use: |
| 26380 |
\begin{codeenv} |
| 26381 |
\csopt[all]{selection} |
| 26382 |
\end{codeenv} |
| 26383 |
in order to select all entries. I also need to alias the custom |
| 26384 |
\atentryfmt{constant} \gls{entrytype} otherwise all the entries will be |
| 26385 |
ignored. I decided to make \atentryfmt{constant} behave like |
| 26386 |
\atentry{number} for semantic reasons: |
| 26387 |
\begin{codeenv} |
| 26388 |
\csopt[constant=number]{entry-type-aliases} |
| 26389 |
\end{codeenv} |
| 26390 |
The custom fields also need aliasing: |
| 26391 |
\begin{codeenv} |
| 26392 |
\csopt[ |
| 26393 |
\fieldfmt{identifier}=\field{category}, |
| 26394 |
\fieldfmt{constantsymbol}=\field{name}, |
| 26395 |
\fieldfmt{constantname}=\field{description}, |
| 26396 |
\fieldfmt{value}=\field{user1}, |
| 26397 |
\fieldfmt{definition}=\field{user2}, |
| 26398 |
\fieldfmt{alternative}=\field{user3}, |
| 26399 |
]{field-aliases} |
| 26400 |
\end{codeenv} |
| 26401 |
I decided to use the \glostyle{altlist} style, so I've instructed |
| 26402 |
\bibgls\ to determine the widest name: |
| 26403 |
\begin{codeenv} |
| 26404 |
\csopt{set-widest} |
| 26405 |
\end{codeenv} |
| 26406 |
It's always a good idea to specify the glossary type when using |
| 26407 |
\csopt{set-widest}, although in this example there's only one |
| 26408 |
glossary so it doesn't make much difference. |
| 26409 |
\begin{codeenv} |
| 26410 |
\csopt[main]{type} |
| 26411 |
\end{codeenv} |
| 26412 |
I decided to order the constants according to their (approximate) |
| 26413 |
numerical value. I've aliased the custom \fieldfmt{value} field to |
| 26414 |
\field{user1}, so I can sort by that field using a numerical |
| 26415 |
comparison: |
| 26416 |
\begin{codeenv} |
| 26417 |
\csopt[\field{user1}]{sort-field}, |
| 26418 |
\csopt[double]{sort} |
| 26419 |
\end{codeenv} |
| 26420 |
There are three entries without the \fieldfmt{user1} field (as the |
| 26421 |
custom \fieldfmt{value} field is missing in the \ext{bib} file): |
| 26422 |
\code{zero}, \code{one} and \code{imaginary}. In the case of |
| 26423 |
\code{zero} and \code{one} the exact value can be obtained from the |
| 26424 |
\field{name} field. Since I've change the default \csopt{sort-field}, I |
| 26425 |
can't use \csopt{symbol-sort-fallback}. Instead I need to use: |
| 26426 |
\begin{codeenv} |
| 26427 |
\csopt[\field{name}]{missing-sort-fallback} |
| 26428 |
\end{codeenv} |
| 26429 |
|
| 26430 |
What happens with the \code{imaginary} entry? It has no real |
| 26431 |
representation. The transcript (\ext{glg}) file shows the message: |
| 26432 |
\begin{verbatim} |
| 26433 |
Warning: Can't parse sort value 'i' for: imaginary |
| 26434 |
\end{verbatim} |
| 26435 |
With the numerical sort methods, if the field can't be parsed the |
| 26436 |
value defaults to 0. This means that both \code{zero} and |
| 26437 |
\code{imaginary} have 0 as the sort value, so the |
| 26438 |
\csopt{identical-sort-action} is implemented. The default setting |
| 26439 |
means that \bibgls\ will fallback on comparing the entry labels, so |
| 26440 |
\code{imaginary} comes before \code{zero}. |
| 26441 |
|
| 26442 |
Since I'm just using the \glostyle{alttree} style, I only need |
| 26443 |
\sty{glossary-tree}. I can improve efficiency in the document build |
| 26444 |
by preventing the other glossary style packages from being loaded |
| 26445 |
using the \styopt{nostyles} package option. This also prevents |
| 26446 |
\sty{glossary-tree} from being loaded, but I can both load it and |
| 26447 |
patch the styles with \sty{glossaries-extra-stylemods} through the |
| 26448 |
option \styopt[tree]{stylemods}. Since the default \glostyle{list} |
| 26449 |
style is no longer available, I need to set a new default with |
| 26450 |
\styopt[alttree]{style}. I also want to automatically insert a |
| 26451 |
\idx{full-stop} after the description, which can be done with |
| 26452 |
\styopt{postdot}. Don't forget that the \styopt{record} option is |
| 26453 |
always needed when using \bibgls. This means that the |
| 26454 |
\sty{glossaries-extra} package needs to be loaded as follows: |
| 26455 |
\begin{codeenv} |
| 26456 |
\cs{usepackage}\oarg{\styopt{record},\styopt{nostyles},\styopt{postdot},\styopt[tree]{stylemods},\styopt[alttree]{style}} |
| 26457 |
\marg{glossaries-extra} |
| 26458 |
\end{codeenv} |
| 26459 |
I've assigned the custom \fieldfmt{constantname} field to the |
| 26460 |
\field{description} field and the custom \fieldfmt{constantsymbol} field to the |
| 26461 |
\field{name} field. This means that by default the glossary list |
| 26462 |
will just show the symbolic representation and the constant's name. |
| 26463 |
I'd like to append the value and definition after the description. |
| 26464 |
With the base \sty{glossaries} package this would require defining a |
| 26465 |
new glossary style but with \sty{glossaries-extra} it can easily be |
| 26466 |
achieved through the \idx{postdescriptionhook}. |
| 26467 |
|
| 26468 |
I've aliased the custom \fieldfmt{identifier} field to |
| 26469 |
\field{category}, which means that all the entries will have the |
| 26470 |
\field{category} set to \code{constant}. The |
| 26471 |
\idx{postdescriptionhook} is obtained from |
| 26472 |
\idx{glsxtrpostdesccategory}, so I need to define |
| 26473 |
the command \csfmt{glsxtrpostdescconstant}. A simple definition is: |
| 26474 |
\begin{codeenv} |
| 26475 |
\cs{newcommand}\marg{\cmd{glsxtrpostdescconstant}}\marg{\comment{} |
| 26476 |
\cs{space} (approximately \cs{glsentryuseri}\marg{\cs{glscurrententrylabel}})\comment{} |
| 26477 |
: \cs{glsentryuserii}\marg{\cs{glscurrententrylabel}}\comment{} |
| 26478 |
} |
| 26479 |
\end{codeenv} |
| 26480 |
This is fine if all entries have the \field{user1} and \field{user2} |
| 26481 |
fields set. A more generic approach tests for the existence of these |
| 26482 |
fields. This can either be done with \ics{ifglshasfield}: |
| 26483 |
\begin{codeenv} |
| 26484 |
\cs{newcommand}\marg{\cmd{glsxtrpostdescconstant}}\marg{\comment{} |
| 26485 |
\cs{ifglshasfield}\marg{\field{user1}}\marg{\cs{glscurrententrylabel}}\comment{} |
| 26486 |
\marg{ (approximately \cs{glscurrentfieldvalue})}\comment{} |
| 26487 |
\marg{}\comment{} |
| 26488 |
\cs{ifglshasfield}\marg{\field{user2}}\marg{\cs{glscurrententrylabel}}\comment{} |
| 26489 |
\marg{: \cs{glscurrentfieldvalue}}\comment{} |
| 26490 |
\marg{}\comment{} |
| 26491 |
} |
| 26492 |
\end{codeenv} |
| 26493 |
or with \ics{glsxtrifhasfield}: |
| 26494 |
\begin{codeenv} |
| 26495 |
\cs{newcommand}\marg{\cmd{glsxtrpostdescconstant}}{\comment{} |
| 26496 |
\cs{glsxtrifhasfield}\marg{\field{useri}}\marg{\cs{glscurrententrylabel}}\comment{} |
| 26497 |
\marg{ (approximately \cs{glscurrentfieldvalue})}\comment{} |
| 26498 |
\marg{}\comment{} |
| 26499 |
\cs{glsxtrifhasfield}\marg{\field{userii}}\marg{\cs{glscurrententrylabel}}\comment{} |
| 26500 |
\marg{: \cs{glscurrentfieldvalue}}\comment{} |
| 26501 |
\marg{}\comment{} |
| 26502 |
} |
| 26503 |
\end{codeenv} |
| 26504 |
(Note the need to use the internal field label \field{useri} and |
| 26505 |
\field{userii} with \ics{glsxtrifhasfield}.) |
| 26506 |
|
| 26507 |
A modification can be made to also show the alternative |
| 26508 |
representation (obtained from the custom \fieldfmt{alternative} |
| 26509 |
field which has been aliased to \field{user3}): |
| 26510 |
\begin{codeenv} |
| 26511 |
\cs{newcommand}\marg{\cmd{glsxtrpostdescconstant}}{\comment{} |
| 26512 |
\cs{glsxtrifhasfield}\marg{\field{useriii}}\marg{\cs{glscurrententrylabel}}\comment{} |
| 26513 |
\marg{ (also denoted \cs{glscurrentfieldvalue} |
| 26514 |
\cs{glsxtrifhasfield}\marg{\field{useri}}\marg{\cs{glscurrententrylabel}}\comment{} |
| 26515 |
\marg{, approximately \cs{glscurrentfieldvalue}}\comment{} |
| 26516 |
\marg{}\comment{} |
| 26517 |
)\comment{} |
| 26518 |
}\comment{} |
| 26519 |
\marg{\comment{} |
| 26520 |
\cs{glsxtrifhasfield}\marg{\field{useri}}\marg{\cs{glscurrententrylabel}}\comment{} |
| 26521 |
\marg{ (approximately \cs{glscurrentfieldvalue})}\comment{} |
| 26522 |
\marg{}\comment{} |
| 26523 |
}\comment{} |
| 26524 |
\cs{glsxtrifhasfield}\marg{\field{userii}}\marg{\cs{glscurrententrylabel}}\comment{} |
| 26525 |
\marg{: \cs{glscurrentfieldvalue}}\comment{} |
| 26526 |
\marg{}\comment{} |
| 26527 |
} |
| 26528 |
\end{codeenv} |
| 26529 |
If you have at least \styfmt{glossaries-extra} v1.31, it's better to use: |
| 26530 |
\begin{codeenv} |
| 26531 |
\ics{glsdefpostdesc}\marg{constant} |
| 26532 |
\end{codeenv} |
| 26533 |
instead of: |
| 26534 |
\begin{codeenv} |
| 26535 |
\cs{newcommand}\marg{\cmd{glsxtrpostdescconstant}} |
| 26536 |
\end{codeenv} |
| 26537 |
as it can guard against accidental misspelling of the \code{glsxtrpostdesc} |
| 26538 |
part of the command name. |
| 26539 |
|
| 26540 |
The complete code is listed below. The document build is: |
| 26541 |
\begin{verbatim} |
| 26542 |
pdflatex sample-constants |
| 26543 |
bib2gls sample-constants |
| 26544 |
pdflatex sample-constants |
| 26545 |
\end{verbatim} |
| 26546 |
The complete document is shown in \figureref{fig:sample-constants.pdf}. |
| 26547 |
|
| 26548 |
\lstinputlisting[firstline=5]{../examples/sample-constants.tex} |
| 26549 |
|
| 26550 |
\begin{figure} |
| 26551 |
\figcontents |
| 26552 |
{% |
| 26553 |
\frame{\includegraphics[height=.9\textheight]{../examples/sample-constants.pdf}}% |
| 26554 |
} |
| 26555 |
{\caption{\filefmt{sample-constants.pdf}}} |
| 26556 |
{fig:sample-constants.pdf} |
| 26557 |
\end{figure} |
| 26558 |
|
| 26559 |
\filesection{sample-chemical.tex} |
| 26560 |
|
| 26561 |
This example just uses the \exfile{chemicalformula.bib} file. The aim here |
| 26562 |
is to have a list of chemical formulae referenced in the document |
| 26563 |
but not have a number list. I could use the \styopt{nonumberlist} |
| 26564 |
package option to suppress the number list display, but it's more |
| 26565 |
efficient to instruct \bibgls\ to not save the number list with: |
| 26566 |
\begin{codeenv} |
| 26567 |
\csopt[false]{save-locations} |
| 26568 |
\end{codeenv} |
| 26569 |
All entries are defined in \exfile{chemicalformula.bib} using |
| 26570 |
a custom \gls{entrytype} \atentryfmt{chemical} which needs to be aliased |
| 26571 |
in order for the entries to be recognised: |
| 26572 |
\begin{codeenv} |
| 26573 |
\csopt[chemical=symbol]{entry-type-aliases} |
| 26574 |
\end{codeenv} |
| 26575 |
Additionally, the entries only have custom fields, so these also |
| 26576 |
need to be aliased. In this case I want the formula in the \field{name} field |
| 26577 |
and the chemical name in the \field{description} field: |
| 26578 |
\begin{codeenv} |
| 26579 |
\csopt[\fieldfmt{formula}=\field{name},\fieldfmt{chemicalname}=\field{description}]{field-aliases} |
| 26580 |
\end{codeenv} |
| 26581 |
The \atentry{symbol} \gls{entrytype} falls back on the label for the |
| 26582 |
\field{sort} value by default, but I've decided |
| 26583 |
to fallback on the \field{name} field for sorting: |
| 26584 |
\begin{codeenv} |
| 26585 |
\csopt[\field{name}]{symbol-sort-fallback} |
| 26586 |
\end{codeenv} |
| 26587 |
An alternative approach would simply be to alias |
| 26588 |
\atentryfmt{chemical} to \atentry{entry} instead. |
| 26589 |
|
| 26590 |
Since the \field{name} field contains chemical formulae rather than |
| 26591 |
words, it makes more sense to use one of the letter sort methods |
| 26592 |
rather than a locale collator. In this case the names contain |
| 26593 |
mixtures of letters and numbers, so one of the letter-number sort |
| 26594 |
methods (listed in \tableref{tab:sortoptionsletternumber}) would be |
| 26595 |
appropriate. |
| 26596 |
|
| 26597 |
I want to use the \glostyle{alttreegroup} style (provided by |
| 26598 |
\sty{glossary-tree}). Since I don't require the other style |
| 26599 |
packages, I've used \styopt{nostyles} to suppress the automatic |
| 26600 |
loading and \styopt[tree]{stylemods} to both load |
| 26601 |
\sty{glossary-tree} and patch it. The \glostyle{alttreegroup} style |
| 26602 |
needs to know the widest name, so I've use \csopt{set-widest} for |
| 26603 |
convenience. The default behaviour of the tree styles is to |
| 26604 |
format the name in bold. This is done through the command |
| 26605 |
\ics{glstreenamefmt} which is defined as: |
| 26606 |
\begin{codeenv} |
| 26607 |
\cs{newcommand}*\marg{\cs{glstreenamefmt}}[1]\marg{\cs{textbf}\marg{\idx{param}1}} |
| 26608 |
\end{codeenv} |
| 26609 |
The group headings use \ics{glstreegroupheaderfmt} which defaults to |
| 26610 |
\cs{glstreenamefmt}. Since I want to keep bold headings, I need to |
| 26611 |
redefine this as well: |
| 26612 |
\begin{codeenv} |
| 26613 |
\cs{renewcommand}*\marg{\cs{glstreenamefmt}}[1]\marg{\idx{param}1} |
| 26614 |
\cs{renewcommand}*\marg{\cs{glstreegroupheaderfmt}}[1]\marg{\cs{textbf}\marg{\idx{param}1}} |
| 26615 |
\end{codeenv} |
| 26616 |
(For a more compact layout, you could use \glostyle{mcolalttreegroup} |
| 26617 |
instead.) |
| 26618 |
I also need the \longarg{group} switch to make the sort method |
| 26619 |
automatically assign letter groups. |
| 26620 |
|
| 26621 |
The complete code is listed below. The document build is: |
| 26622 |
\begin{verbatim} |
| 26623 |
pdflatex sample-chemical |
| 26624 |
bib2gls --group sample-chemical |
| 26625 |
pdflatex sample-chemical |
| 26626 |
\end{verbatim} |
| 26627 |
The complete document is shown in \figureref{fig:sample-chemical.pdf}. |
| 26628 |
|
| 26629 |
\lstinputlisting[firstline=5]{../examples/sample-chemical.tex} |
| 26630 |
|
| 26631 |
\begin{figure} |
| 26632 |
\figcontents |
| 26633 |
{% |
| 26634 |
\frame{\includegraphics[height=.9\textheight]{../examples/sample-chemical.pdf}}% |
| 26635 |
} |
| 26636 |
{\caption{\filefmt{sample-chemical.pdf}}} |
| 26637 |
{fig:sample-chemical.pdf} |
| 26638 |
\end{figure} |
| 26639 |
|
| 26640 |
\filesection{sample-bacteria.tex} |
| 26641 |
|
| 26642 |
This example just uses the \exfile{bacteria.bib} file. The aim here |
| 26643 |
is to have a simple list of the bacteria referenced in the document. |
| 26644 |
Bacteria names are often shown in the long form on first use |
| 26645 |
(without the short form) and then the short form on subsequent use. |
| 26646 |
This can easily be done with the \abbrstyle{long-only-short-only} |
| 26647 |
style. Bacteria are usually typeset in italic. It's best to create a |
| 26648 |
semantic command for this: |
| 26649 |
\begin{codeenv} |
| 26650 |
\cs{newcommand}\marg{\cmd{bacteriafont}}[1]\marg{\cs{emph}\marg{\idx{param}1}} |
| 26651 |
\end{codeenv} |
| 26652 |
There are two methods to apply this to the bacteria entries. The |
| 26653 |
first is to redefine the formatting commands used by the |
| 26654 |
\abbrstyle{long-only-short-only} style: |
| 26655 |
\begin{codeenv} |
| 26656 |
\cs{renewcommand}*\marg{\ics{glsabbrvonlyfont}}[1]\marg{\cmd{bacteriafont}\marg{\idx{param}1}} |
| 26657 |
\cs{renewcommand}*\marg{\ics{glslongonlyfont}}[1]\marg{\cmd{bacteriafont}\marg{\idx{param}1}} |
| 26658 |
\end{codeenv} |
| 26659 |
This is fine if I don't intend to use this style for other types of |
| 26660 |
abbreviations. However, I may decide to extend the document at a |
| 26661 |
later date to include other abbreviations that need |
| 26662 |
\abbrstyle{long-only-short-only} but shouldn't be emphasized. |
| 26663 |
This can be done through the use of \idxpl{categoryattribute}. |
| 26664 |
The font used for the \field{name} in the glossary is governed by |
| 26665 |
the \catattr{glossnamefont} attribute, the font used for the |
| 26666 |
\field{description} in the glossary is governed by the |
| 26667 |
\catattr{glossdescfont} attribute and the font used by commands like |
| 26668 |
\cs{gls} in the document is governed by the \catattr{textformat} |
| 26669 |
attribute (\styfmt{glossaries-extra} v1.21+). So if I set |
| 26670 |
the \field{category} to \code{bacteria} then I can do: |
| 26671 |
\begin{codeenv} |
| 26672 |
\cs{setabbreviationstyle}\oarg{bacteria}\marg{\abbrstyle{long-only-short-only}} |
| 26673 |
\cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{textformat}}\marg{bacteriafont} |
| 26674 |
\cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{glossnamefont}}\marg{bacteriafont} |
| 26675 |
\end{codeenv} |
| 26676 |
and (if the \field{description} field is displayed in the glossary): |
| 26677 |
\begin{codeenv} |
| 26678 |
\cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{glossdescfont}}\marg{bacteriafont} |
| 26679 |
\end{codeenv} |
| 26680 |
(Note that the attribute value is the control sequence name without |
| 26681 |
the initial backslash.) |
| 26682 |
|
| 26683 |
I'd like to use the \glostyle{bookindex} style, which is |
| 26684 |
provided by the \isty{glossary-bookindex} |
| 26685 |
package.\footnote{\styfmt{glossary-bookindex} |
| 26686 |
is distributed with \styfmt{glossaries-extra} v1.21+.} This isn't loaded |
| 26687 |
automatically, but it can be loaded through the |
| 26688 |
\styopt{stylemods} package option: |
| 26689 |
\begin{codeenv} |
| 26690 |
\cmd{usepackage}[\styopt{record},\comment{use bib2gls} |
| 26691 |
\styopt{nostyles},\comment{don't load default style packages} |
| 26692 |
\styopt[bookindex]{stylemods},\comment{load glossary-bookindex.sty and patch styles} |
| 26693 |
\styopt[bookindex]{style}]\marg{glossaries-extra} |
| 26694 |
\end{codeenv} |
| 26695 |
I've used the \styopt{nostyles} package option to suppress loading |
| 26696 |
the default style packages, since I'm not using them. If you inspect |
| 26697 |
the \ext{log} file, you may notice that \sty{glossary-tree} is still |
| 26698 |
loaded. This is because it's required by \sty{glossary-bookindex} |
| 26699 |
as the \glostyle{bookindex} style is based on the \glostyle{index} |
| 26700 |
style provided by \sty{glossary-tree}. |
| 26701 |
With this style I need to use the \longarg{group} switch to instruct |
| 26702 |
the sort method to automatically create the letter groups. |
| 26703 |
|
| 26704 |
The \glostyle{bookindex} style doesn't show the \field{description} |
| 26705 |
field (which means I don't need the \catattr{glossdescfont} |
| 26706 |
attribute) and, since the \abbrstyle{long-only-short-only} style sets |
| 26707 |
the \field{name} to the short form by default, only the short form |
| 26708 |
will show in the glossary. I'd rather it was just the long form. |
| 26709 |
This could simply be done using \csopt{replicate-fields} to copy the |
| 26710 |
\field{long} field to the \field{name} field: |
| 26711 |
\begin{codeenv} |
| 26712 |
\csopt[\field{long}=\field{name}]{replicate-fields} |
| 26713 |
\end{codeenv} |
| 26714 |
Again, I want to consider the possibility of adding other types of |
| 26715 |
abbreviations and this might not be appropriate for them (for |
| 26716 |
example, I might want some abbreviations with the long form followed |
| 26717 |
by the short form in parentheses). Another |
| 26718 |
approach is to redefine \ics{glsxtrbookindexname} which is used by |
| 26719 |
the \glostyle{bookindex} style to display the name. This takes the |
| 26720 |
entry's label as the argument. The default definition is: |
| 26721 |
\begin{codeenv} |
| 26722 |
\cs{newcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\cs{glossentryname}\marg{\idx{param}1}} |
| 26723 |
\end{codeenv} |
| 26724 |
This can be changed to test for the entry's category: |
| 26725 |
\begin{codeenv} |
| 26726 |
\cs{renewcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\comment{} |
| 26727 |
\ics{glsifcategory}\marg{\idx{param}1}\marg{bacteria} |
| 26728 |
\marg{\cs{glossentrynameother}\marg{\idx{param}1}\marg{\field{long}}}\comment{} |
| 26729 |
\marg{\cs{glossentryname}\marg{\idx{param}1}}\comment{} |
| 26730 |
} |
| 26731 |
\end{codeenv} |
| 26732 |
Note that I've used \ics{glossentrynameother} here rather than |
| 26733 |
\ics{glsentrylong}. This ensures that it follows the same formatting |
| 26734 |
as \ics{glossentryname} (so it will use \ics{glsnamefont} or the |
| 26735 |
\catattr{glossnamefont} attribute, the \catattr{glossname} |
| 26736 |
attribute, and the \idx{postnamehook}, if set). In this case it |
| 26737 |
picks up the \catattr{glossnamefont} attribute, which is used |
| 26738 |
instead of \cs{glsnamefont}. |
| 26739 |
|
| 26740 |
If the \field{sort} field is missing for abbreviation styles, the |
| 26741 |
fallback value is the \field{short} field (not the \field{name} |
| 26742 |
field). In this case it would be better to fallback on the |
| 26743 |
\field{long} field instead, which can be done with the |
| 26744 |
\csopt{abbreviation-sort-fallback} option: |
| 26745 |
\begin{codeenv} |
| 26746 |
\csopt[\field{long}]{abbreviation-sort-fallback} |
| 26747 |
\end{codeenv} |
| 26748 |
If I do add other types of abbreviations, they will all be sorted |
| 26749 |
according to the \field{long} form, but at least this way I can have |
| 26750 |
some \meta{long} (\meta{short}) names as well. |
| 26751 |
|
| 26752 |
The complete code is listed below. The document build is: |
| 26753 |
\begin{verbatim} |
| 26754 |
pdflatex sample-bacteria |
| 26755 |
bib2gls --group sample-bacteria |
| 26756 |
pdflatex sample-bacteria |
| 26757 |
\end{verbatim} |
| 26758 |
This simple example only references entries on the first page so all |
| 26759 |
entries just have~1 in the number list. The complete document is |
| 26760 |
shown in \figureref{fig:sample-bacteria.pdf}. |
| 26761 |
|
| 26762 |
\lstinputlisting[firstline=5]{../examples/sample-bacteria.tex} |
| 26763 |
|
| 26764 |
\begin{figure} |
| 26765 |
\figcontents |
| 26766 |
{% |
| 26767 |
\frame{\includegraphics[height=.9\textheight]{../examples/sample-bacteria.pdf}}% |
| 26768 |
} |
| 26769 |
{\caption{\filefmt{sample-bacteria.pdf}}} |
| 26770 |
{fig:sample-bacteria.pdf} |
| 26771 |
\end{figure} |
| 26772 |
|
| 26773 |
\filesection{sample-units1.tex} |
| 26774 |
|
| 26775 |
This example uses the \exfile{baseunits.bib} and |
| 26776 |
\exfile{derivedunits.bib} files. The aim here is to have a glossary |
| 26777 |
in two blocks: base units and derived units. This can be achieved by |
| 26778 |
first loading \exfile{baseunits.bib} with \csopt{group} set to the |
| 26779 |
desired group title (\qt{Base Units} in this case) and then load |
| 26780 |
\exfile{derivedunits.bib} with the \csopt{group} set to the desired |
| 26781 |
title (\qt{Derived Units} in this case). Remember that the |
| 26782 |
\field{group} field needs to be used as a label. If the group title |
| 26783 |
contains any problematic characters or commands, then it's better to |
| 26784 |
use labels: |
| 26785 |
\begin{codeenv} |
| 26786 |
\csopt[baseunits]{group} |
| 26787 |
\end{codeenv} |
| 26788 |
for the first \igls{resourceset} and |
| 26789 |
\begin{codeenv} |
| 26790 |
\csopt[derivedunits]{group} |
| 26791 |
\end{codeenv} |
| 26792 |
for the second, and then set the group titles: |
| 26793 |
\begin{codeenv} |
| 26794 |
\gls{glsxtrsetgrouptitle}\marg{baseunits}\marg{Base Units} |
| 26795 |
\gls{glsxtrsetgrouptitle}\marg{derivedunits}\marg{Derived Units} |
| 26796 |
\end{codeenv} |
| 26797 |
I've used this method to make it easier to adapt to other languages |
| 26798 |
that may need extended characters in the group titles. |
| 26799 |
The \csopt{group} option requires the \longarg{group} switch to |
| 26800 |
ensure that the \field{group} field is correctly assigned. |
| 26801 |
|
| 26802 |
The \exfile{baseunits.bib} file use a custom \gls{entrytype} |
| 26803 |
\atentryfmt{unit}, which must be aliased otherwise \bibgls\ |
| 26804 |
will ignore the entries. I decided to use \atentry{symbol} for |
| 26805 |
semantic reasons: |
| 26806 |
\begin{codeenv} |
| 26807 |
\csopt[unit=symbol]{entry-type-aliases} |
| 26808 |
\end{codeenv} |
| 26809 |
Similarly for the custom \atentryfmt{measurement} \gls{entrytype} in |
| 26810 |
\exfile{derivedunits.bib}: |
| 26811 |
\begin{codeenv} |
| 26812 |
\csopt[measurement=symbol]{entry-type-aliases} |
| 26813 |
\end{codeenv} |
| 26814 |
Remember that \atentry{symbol} uses the label as the default sort fallback, |
| 26815 |
so I've changed it to use \field{name} instead: |
| 26816 |
\begin{codeenv} |
| 26817 |
\csopt[\field{name}]{symbol-sort-fallback} |
| 26818 |
\end{codeenv} |
| 26819 |
An alternative approach would be to alias \atentryfmt{unit} |
| 26820 |
and \atentryfmt{measurement} to \atentry{entry} instead. |
| 26821 |
|
| 26822 |
Since there's no \csopt{type} set, all entries end up in the |
| 26823 |
\gls{mainglossary}, but since there are two resource commands the glossary |
| 26824 |
ends up with sorted blocks. |
| 26825 |
|
| 26826 |
The document doesn't include any commands like \cs{gls}, so |
| 26827 |
I've use \csopt[all]{selection} to select all entries in the \ext{bib} |
| 26828 |
files. There won't be any number lists since there are no records. |
| 26829 |
I need a glossary style that shows the \field{symbol} field so I've |
| 26830 |
used \glostyle{mcolindexgroup}. Again I've suppressed the automatic |
| 26831 |
loading of the default styles with \styopt{nostyles} and used |
| 26832 |
\styopt[mcols]{stylemods} to load \isty{glossary-mcols} and patch the |
| 26833 |
styles. Note that although I've used \styopt{nostyles}, the |
| 26834 |
\sty{glossary-tree} style is loaded as it's required by |
| 26835 |
\sty{glossary-mcols}. |
| 26836 |
|
| 26837 |
As with the previous example, the custom fields need to be aliased: |
| 26838 |
\begin{codeenv} |
| 26839 |
\csopt[ |
| 26840 |
\fieldfmt{unitname}=\field{name}, |
| 26841 |
\fieldfmt{unitsymbol}=\field{symbol}, |
| 26842 |
\fieldfmt{measurement}=\field{description} |
| 26843 |
]{field-aliases} |
| 26844 |
\end{codeenv} |
| 26845 |
|
| 26846 |
The complete document code is listed below. The document build is: |
| 26847 |
\begin{verbatim} |
| 26848 |
pdflatex sample-units1 |
| 26849 |
bib2gls --group sample-units1 |
| 26850 |
pdflatex sample-units1 |
| 26851 |
\end{verbatim} |
| 26852 |
The complete document is shown in \figureref{fig:sample-units1.pdf}. |
| 26853 |
|
| 26854 |
\lstinputlisting[firstline=5]{../examples/sample-units1.tex} |
| 26855 |
|
| 26856 |
\begin{figure} |
| 26857 |
\figcontents |
| 26858 |
{% |
| 26859 |
\frame{\includegraphics[height=.9\textheight]{../examples/sample-units1.pdf}}% |
| 26860 |
} |
| 26861 |
{\caption{\filefmt{sample-units1.pdf}}} |
| 26862 |
{fig:sample-units1.pdf} |
| 26863 |
\end{figure} |
| 26864 |
|
| 26865 |
\filesection{sample-units2.tex} |
| 26866 |
|
| 26867 |
This example is provided for comparison with |
| 26868 |
\exfile{sample-units1.tex}. Instead of having a single glossary with |
| 26869 |
sorted blocks this example has two glossaries: |
| 26870 |
\begin{codeenv} |
| 26871 |
\ics{newglossary*}\marg{baseunits}\marg{Base Units} |
| 26872 |
\cs{newglossary*}\marg{derivedunits}\marg{Derived Units} |
| 26873 |
\end{codeenv} |
| 26874 |
I've used the \styopt{section} package option to use \ics{section*} for the |
| 26875 |
glossary titles. This overrides the default \ics{chapter*} which is |
| 26876 |
used with book or report type of classes. I've also used the |
| 26877 |
\styopt{nomain} option to suppress the creation of the \gls{mainglossary} |
| 26878 |
as I want to define my own glossary types instead. |
| 26879 |
|
| 26880 |
As before the custom \glspl{entrytype} need to be aliased: |
| 26881 |
\begin{codeenv} |
| 26882 |
\csopt[unit=symbol]{entry-type-aliases} |
| 26883 |
\end{codeenv} |
| 26884 |
for the first \igls{resourceset} and |
| 26885 |
\begin{codeenv} |
| 26886 |
\csopt[measurement=symbol]{entry-type-aliases} |
| 26887 |
\end{codeenv} |
| 26888 |
for the second. Similarly for the custom entry fields: |
| 26889 |
\begin{codeenv} |
| 26890 |
\csopt[ |
| 26891 |
\fieldfmt{unitname}=\field{name}, |
| 26892 |
\fieldfmt{unitsymbol}=\field{symbol}, |
| 26893 |
\fieldfmt{measurement}=\field{description} |
| 26894 |
]{field-aliases} |
| 26895 |
\end{codeenv} |
| 26896 |
The \longarg{group} switch is needed to ensure that the |
| 26897 |
\field{group} field is automatically assigned by the sort method. |
| 26898 |
|
| 26899 |
The complete document code is listed below. The document build is: |
| 26900 |
\begin{verbatim} |
| 26901 |
pdflatex sample-units2 |
| 26902 |
bib2gls --group sample-units2 |
| 26903 |
pdflatex sample-units2 |
| 26904 |
\end{verbatim} |
| 26905 |
The complete document is shown in \figureref{fig:sample-units2.pdf}. |
| 26906 |
|
| 26907 |
\lstinputlisting[firstline=5]{../examples/sample-units2.tex} |
| 26908 |
|
| 26909 |
\begin{figure} |
| 26910 |
\figcontents |
| 26911 |
{% |
| 26912 |
\frame{\includegraphics[height=.9\textheight]{../examples/sample-units2.pdf}}% |
| 26913 |
} |
| 26914 |
{\caption{\filefmt{sample-units2.pdf}}} |
| 26915 |
{fig:sample-units2.pdf} |
| 26916 |
\end{figure} |
| 26917 |
|
| 26918 |
\filesection{sample-units3.tex} |
| 26919 |
|
| 26920 |
This is another example that uses the \exfile{baseunits.bib} and |
| 26921 |
\exfile{derivedunits.bib} files. As before the custom fields need to be aliased: |
| 26922 |
\begin{codeenv} |
| 26923 |
\csopt[ |
| 26924 |
\fieldfmt{unitname}=\field{name}, |
| 26925 |
\fieldfmt{unitsymbol}=\field{symbol}, |
| 26926 |
\fieldfmt{measurement}=\field{description} |
| 26927 |
]{field-aliases} |
| 26928 |
\end{codeenv} |
| 26929 |
This time I want two glossaries containing all the units (base and |
| 26930 |
derived) where the first glossary is ordered by name and the second |
| 26931 |
is ordered by symbol. This can be done with a single resource |
| 26932 |
command that instructs \bibgls\ to make the custom \atentryfmt{unit} |
| 26933 |
and \atentryfmt{measurement} \glspl{entrytype} behave like |
| 26934 |
\atentry{dualsymbol}: |
| 26935 |
\begin{codeenv} |
| 26936 |
\csopt[ |
| 26937 |
unit=dualsymbol, |
| 26938 |
measurement=dualsymbol |
| 26939 |
]{entry-type-aliases} |
| 26940 |
\end{codeenv} |
| 26941 |
This causes the \field{name} and \field{symbol} fields to be swapped in the |
| 26942 |
dual list. Remember that the fallback for the \field{sort} field is the label |
| 26943 |
for the symbol \glspl{entrytype} so I need \csopt[\field{name}]{symbol-sort-fallback} |
| 26944 |
to fallback on \field{name} field instead. (Alternative, I could just sort by |
| 26945 |
the \field{name} field instead using \csopt[\field{name}]{sort-field}.) |
| 26946 |
|
| 26947 |
The primary entries can still be sorted according to the default |
| 26948 |
locale collator, but the dual entries need a sort method that's |
| 26949 |
better suited to symbols. Fortunately, \bibgls\ has some (very |
| 26950 |
limited) support for \isty{siunitx} and is able to interpret |
| 26951 |
the \ics{si} commands in the sample \ext{bib} files. Since |
| 26952 |
\idxpl{SIunit} are a mix of letters and numbers I've used one of the |
| 26953 |
letter-number methods listed in |
| 26954 |
\tableref{tab:sortoptionsletternumber}. |
| 26955 |
|
| 26956 |
I've decided to define a custom style for the first glossary. Since |
| 26957 |
it's based on the \glostyle{long3col-booktabs} style I need to |
| 26958 |
load \isty{glossary-longbooktabs}, which can conveniently be done with |
| 26959 |
the \styopt{stylemods} option. This uses \env{longtable} (provided |
| 26960 |
by \isty{longtable}, which is automatically loaded) which means |
| 26961 |
an extra \LaTeX\ call is required in the build process to ensure the |
| 26962 |
column widths are correct. Again I'm using \styopt{nostyles} to |
| 26963 |
suppress the automatic loading of the default styles, however |
| 26964 |
\sty{glossary-tree} will be loaded as it's listed in the value of |
| 26965 |
\styopt{stylemods} and \isty{glossary-long} will be loaded as it's |
| 26966 |
required by \sty{glossary-longbooktabs}. I can't use my custom style |
| 26967 |
in the \styopt{style} package option as it hasn't been defined at |
| 26968 |
that point. The default \glostyle{list} style is now unavailable |
| 26969 |
since \styopt{nostyles} has prevented it from being defined, so |
| 26970 |
I've used \styopt[alttree]{style} to ensure there's a valid default |
| 26971 |
style. |
| 26972 |
|
| 26973 |
Since my custom style is based on one of the long styles, I need to |
| 26974 |
set the length register \ics{glsdescwidth} to adjust the width of |
| 26975 |
the description column: |
| 26976 |
\begin{codeenv} |
| 26977 |
\cmd{setlength}\marg{\cs{glsdescwidth}}\marg{.4\cmd{hsize}} |
| 26978 |
\end{codeenv} |
| 26979 |
The \glostyle{long3col-booktabs} style sets up a three column |
| 26980 |
\env{longtable} so I just need to adjust the table header (to rename |
| 26981 |
the column headers) and the way each row is formatted: |
| 26982 |
\begin{codeenv} |
| 26983 |
\ics{newglossarystyle}\marg{units}\comment{style name} |
| 26984 |
\marg{\comment{base it on \glostyle{long3col-booktabs}} |
| 26985 |
\ics{setglossarystyle}\marg{long3col-booktabs}\comment{} |
| 26986 |
\cs{renewcommand}*\marg{\ics{glossaryheader}}\marg{\comment{} |
| 26987 |
\ics{toprule} |
| 26988 |
\ics{bfseries} Name \idx{colsep} |
| 26989 |
\cs{bfseries} Measurement \idx{colsep} |
| 26990 |
\cs{bfseries} Symbol |
| 26991 |
\ics{tabularnewline}\ics{midrule}\ics{endhead} |
| 26992 |
\ics{bottomrule}\ics{endfoot}}\comment{} |
| 26993 |
\comment{main entries:} |
| 26994 |
\cs{renewcommand}\marg{\ics{glossentry}}[2]\marg{\comment{} |
| 26995 |
\ics{glsentryitem}\marg{\idx{param}\idx{param}1}\ics{glstarget}\marg{\idx{param}\idx{param}1}\marg{\cs{glossentryname}\marg{\idx{param}\idx{param}1}} \idx{colsep} |
| 26996 |
\cs{glossentrydesc}\marg{\idx{param}\idx{param}1}\ics{glspostdescription} \idx{colsep} |
| 26997 |
\cs{glossentrysymbol}\marg{\idx{param}\idx{param}1}\cs{tabularnewline} |
| 26998 |
}\comment{} |
| 26999 |
} |
| 27000 |
\end{codeenv} |
| 27001 |
There are no \glspl{sub-entry} in this document so I haven't bothered to |
| 27002 |
redefine \ics{subglossentry}. (The tabular styles aren't appropriate |
| 27003 |
for \glspl{hierarchicalglossary}.) This puts the symbol into the third |
| 27004 |
column (rather than the \gls{locationlist}, which is ignored). |
| 27005 |
This style supports the letter group separator (although it doesn't |
| 27006 |
title the groups), so if I want this I need to use the |
| 27007 |
\longarg{group} switch. |
| 27008 |
|
| 27009 |
I also need to make sure I've defined a glossary for the dual |
| 27010 |
entries: |
| 27011 |
\begin{codeenv} |
| 27012 |
\cs{newglossary*}\marg{units}\marg{Units of Measurement (by SI unit)} |
| 27013 |
\end{codeenv} |
| 27014 |
and specify the glossary types for the primary and dual entries: |
| 27015 |
\begin{codeenv} |
| 27016 |
\csopt[main]{type}, |
| 27017 |
\csopt[units]{dual-type} |
| 27018 |
\end{codeenv} |
| 27019 |
The complete document code is listed below. The document build is: |
| 27020 |
\begin{verbatim} |
| 27021 |
pdflatex sample-units3 |
| 27022 |
bib2gls --group sample-units3 |
| 27023 |
pdflatex sample-units3 |
| 27024 |
pdflatex sample-units3 |
| 27025 |
\end{verbatim} |
| 27026 |
The two pages of the document are shown in |
| 27027 |
\figureref{fig:sample-units3.pdf}. |
| 27028 |
|
| 27029 |
\lstinputlisting[firstline=5]{../examples/sample-units3.tex} |
| 27030 |
|
| 27031 |
\begin{figure} |
| 27032 |
\figcontents |
| 27033 |
{\pdftwocol{../examples/sample-units3.pdf}{2}} |
| 27034 |
{\caption{\filefmt{sample-units3.pdf}}} |
| 27035 |
{fig:sample-units3.pdf} |
| 27036 |
\end{figure} |
| 27037 |
|
| 27038 |
\filesection{sample-media.tex} |
| 27039 |
|
| 27040 |
This example uses the sample files \exfile{books.bib}, |
| 27041 |
\exfile{films.bib}, \exfile{no-interpret-preamble.bib} and |
| 27042 |
\exfile{interpret-preamble.bib}. The aim is to produce a combined |
| 27043 |
list of books and films in a single glossary. The films are based on |
| 27044 |
some of the books so some of the entries have the same name. The |
| 27045 |
default setting for identical sort values is |
| 27046 |
\csopt[id]{identical-sort-action}, which means that the ordering for |
| 27047 |
the duplicate names is based on the entry labels. This can lead to |
| 27048 |
the odd effect of sometimes having the film listed first |
| 27049 |
(\code{film.thebigsleep} comes before \code{thebigsleep}) and |
| 27050 |
sometimes having the book listed first (\code{brightonrock} comes |
| 27051 |
before \code{film.brightonrock}). |
| 27052 |
|
| 27053 |
One possible solution would be to also assign prefixes for the book |
| 27054 |
labels, but \csopt{label-prefix} is applied to all primary entries |
| 27055 |
for the given resource set and can't be applied selectively, so this |
| 27056 |
would require editing the \exfile{books.bib} file. |
| 27057 |
|
| 27058 |
A more consistent approach would be to fallback on the category. |
| 27059 |
This means that the \field{category} field needs to be set. There |
| 27060 |
are two simple ways to achieve this: use \csopt[same as base]{category} |
| 27061 |
(which sets the \field{category} to \code{books} for entries in |
| 27062 |
\exfile{books.bib} and to \code{films} for entries in |
| 27063 |
\exfile{films.bib}) or alias the custom \fieldfmt{identifier} field to |
| 27064 |
\field{category}. I've chosen the latter method and also provided |
| 27065 |
aliases for the custom \fieldfmt{year} and \fieldfmt{cast} fields: |
| 27066 |
\begin{codeenv} |
| 27067 |
\csopt[\fieldfmt{identifier}=\field{category},\fieldfmt{year}=\field{user1},\fieldfmt{cast}=\field{user2}]{field-aliases}, |
| 27068 |
\csopt[\field{category}]{identical-sort-action} |
| 27069 |
\end{codeenv} |
| 27070 |
This ensures that books always come before films with the same |
| 27071 |
title. An oddity is the film \qt{Whisky Galore!}\ which is one |
| 27072 |
character different from the book \qt{Whisky Galore} but the default |
| 27073 |
locale collator ignores punctuation so the two titles are considered |
| 27074 |
identical by the collator (but not by \csopt[non-unique]{sort-suffix}). |
| 27075 |
If a letter comparison was used instead, they would no longer be |
| 27076 |
considered identical, but in this case the film would |
| 27077 |
still be placed after the book since the film title is longer. |
| 27078 |
|
| 27079 |
Since I've set the \field{category} I can provide semantic |
| 27080 |
formatting commands (as for \exfile{sample-bacteria.tex}): |
| 27081 |
\begin{codeenv} |
| 27082 |
\cs{newcommand}*\marg{\cmd{bookfont}}[1]\marg{\cs{emph}\marg{\idx{param}1}} |
| 27083 |
\cs{newcommand}*\marg{\cmd{filmfont}}[1]\marg{\ics{textsf}\marg{\ics{em} \idx{param}1}} |
| 27084 |
\cs{glssetcategoryattribute}\marg{book}\marg{\catattr{textformat}}\marg{bookfont} |
| 27085 |
\cs{glssetcategoryattribute}\marg{book}\marg{\catattr{glossnamefont}}\marg{bookfont} |
| 27086 |
\cs{glssetcategoryattribute}\marg{film}\marg{\catattr{textformat}}\marg{filmfont} |
| 27087 |
\cs{glssetcategoryattribute}\marg{film}\marg{\catattr{glossnamefont}}\marg{filmfont} |
| 27088 |
\end{codeenv} |
| 27089 |
I've given films a slightly different format to make them easier to |
| 27090 |
distinguish from books of the same name. |
| 27091 |
|
| 27092 |
Both \exfile{books.bib} and \exfile{films.bib} had the custom |
| 27093 |
\fieldfmt{year} field, indicating the year of first publication |
| 27094 |
or release, which I've assigned to the \field{user1} field. |
| 27095 |
I can define \idxpl{postnamehook} for each category |
| 27096 |
to append the year in brackets after the name is displayed in the |
| 27097 |
glossary: |
| 27098 |
\begin{codeenv} |
| 27099 |
\cs{newcommand}*\marg{\postnamehook{book}}\marg{\comment{} |
| 27100 |
\cs{ifglshasfield}\marg{\field{user1}}\marg{\cs{glscurrententrylabel}}\comment{} |
| 27101 |
\marg{\cs{space}(published \cs{glscurrentfieldvalue})}\comment{} |
| 27102 |
\marg{}\comment{} |
| 27103 |
} |
| 27104 |
\strut |
| 27105 |
\cs{newcommand}*\marg{\postnamehook{film}}\marg{\comment{} |
| 27106 |
\cs{ifglshasfield}\marg{\field{user1}}\marg{\cs{glscurrententrylabel}}\comment{} |
| 27107 |
\marg{\cs{space}(released \cs{glscurrentfieldvalue})}\comment{} |
| 27108 |
\marg{}\comment{} |
| 27109 |
} |
| 27110 |
\end{codeenv} |
| 27111 |
As with the post-description hook, if you have at least |
| 27112 |
\styfmt{glossaries-extra} v1.31, it's better to use: |
| 27113 |
\begin{codeenv} |
| 27114 |
\ics{glsdefpostname}\margm{category} |
| 27115 |
\end{codeenv} |
| 27116 |
instead of: |
| 27117 |
\begin{codeenv} |
| 27118 |
\cs{newcommand}\marg{\cs{glsxtrpostnamecategory}} |
| 27119 |
\end{codeenv} |
| 27120 |
as it can guard against accidental misspelling of the \code{glsxtrpostname} |
| 27121 |
part of the command name. |
| 27122 |
|
| 27123 |
I've assigned the \fieldfmt{cast} field to the \field{user2} field, |
| 27124 |
and since this field uses \BibTeX's contributor markup I need to |
| 27125 |
convert this to a form that's easier to customize: |
| 27126 |
\begin{codeenv} |
| 27127 |
\csopt[\field{user2}]{bibtex-contributor-fields} |
| 27128 |
\end{codeenv} |
| 27129 |
I'm not sorting by this field and it would look better in the |
| 27130 |
document to list the forenames before the surname so I've also done: |
| 27131 |
\begin{codeenv} |
| 27132 |
\csopt[forenames]{contributor-order} |
| 27133 |
\end{codeenv} |
| 27134 |
Since I have at least version 2.28 of \sty{datatool-base} installed, |
| 27135 |
the list will be formatted using \ics{DTLformatlist}. If I want an |
| 27136 |
Oxford comma, I need to redefine \ics{DTLlistformatoxford} in the document: |
| 27137 |
\begin{codeenv} |
| 27138 |
\cs{renewcommand}*\marg{\cs{DTLlistformatoxford}}\marg{,} |
| 27139 |
\end{codeenv} |
| 27140 |
If I want to change \qt{\&} to \qt{and} I also need to redefine |
| 27141 |
\ics{DTLandname}: |
| 27142 |
\begin{codeenv} |
| 27143 |
\cs{renewcommand}*\marg{\cs{DTLandname}}\marg{and} |
| 27144 |
\end{codeenv} |
| 27145 |
If \ics{DTLformatlist} isn't defined (\sty{datatool-base} v2.27 or |
| 27146 |
earlier), the cast list will look a little odd as it uses a comma |
| 27147 |
separator between all elements of this list, including the final |
| 27148 |
pair (so there's no final \& or \qt{and}). |
| 27149 |
|
| 27150 |
I've provided a \idx{postdescriptionhook} |
| 27151 |
\ics{glsxtrpostdesccategory} to append the cast list: |
| 27152 |
\begin{codeenv} |
| 27153 |
\cs{newcommand}*\marg{\postdeschook{film}}\marg{\comment{} |
| 27154 |
\cs{ifglshasfield}\marg{\field{user2}}\marg{\cs{glscurrententrylabel}}\comment{} |
| 27155 |
\marg{\comment{} |
| 27156 |
\cs{glsxtrrestorepostpunc} \comment{requires glossaries-extra v1.23+} |
| 27157 |
\cs{cs.space}featuring \cs{glscurrentfieldvalue} |
| 27158 |
}\comment{} |
| 27159 |
\marg{}\comment{} |
| 27160 |
} |
| 27161 |
\end{codeenv} |
| 27162 |
This uses \ics{glsxtrrestorepostpunc} to restore the |
| 27163 |
post-description punctuation if it was suppressed with |
| 27164 |
\ics{glsxtrnopostpunc}. This means that if I decide not to include |
| 27165 |
the \field{user2} field then the post-description punctuation will |
| 27166 |
be revert back to being suppressed for entries containing |
| 27167 |
\cs{glsxtrnopostpunc} in the \field{description} field. |
| 27168 |
|
| 27169 |
I haven't referenced any of the entries in the main body of the |
| 27170 |
document, so I've used \csopt[all]{selection} to select all entries. |
| 27171 |
This means that there are no number lists on the first document |
| 27172 |
build (\LaTeX+\bibgls+\LaTeX) but the next build would show \glspl{location} for |
| 27173 |
the books that have been referenced by the film entries. Since this |
| 27174 |
looks a bit odd, I've added \csopt[false]{save-locations} to |
| 27175 |
prevent \bibgls\ from saving the \glspl{location}. |
| 27176 |
|
| 27177 |
I've used a style that shows letter group headings so I need to use |
| 27178 |
the \longarg{group} switch. |
| 27179 |
The complete document code is listed below. The document build is: |
| 27180 |
\begin{verbatim} |
| 27181 |
pdflatex sample-media |
| 27182 |
bib2gls --group sample-media |
| 27183 |
pdflatex sample-media |
| 27184 |
\end{verbatim} |
| 27185 |
The four pages of the document are shown in |
| 27186 |
\figureref{fig:sample-media.pdf}. |
| 27187 |
|
| 27188 |
\lstinputlisting[firstline=5]{../examples/sample-media.tex} |
| 27189 |
|
| 27190 |
\begin{figure} |
| 27191 |
\figcontents |
| 27192 |
{\pdftwocol{../examples/sample-media.pdf}{4}} |
| 27193 |
{\caption{\filefmt{sample-media.pdf}}} |
| 27194 |
{fig:sample-media.pdf} |
| 27195 |
\end{figure} |
| 27196 |
|
| 27197 |
\filesection{sample-people.tex} |
| 27198 |
|
| 27199 |
This example uses the files \exfile{people.bib}, |
| 27200 |
\exfile{no-interpret-preamble.bib} and \exfile{interpret-preamble.bib}. The |
| 27201 |
aim here is to have a list of people ordered alphabetically by |
| 27202 |
surname with a brief description, the same list ordered by date of |
| 27203 |
birth and an index of all the people without their details but with |
| 27204 |
a number list indicating where that person was mentioned in the |
| 27205 |
document. The first two lists shouldn't include aliases but the |
| 27206 |
index should. Not all the entries defined in \exfile{people.bib} |
| 27207 |
are included in the document. Those that aren't either explicitly |
| 27208 |
referenced or aliased are filtered by the \csopt{selection} criteria. |
| 27209 |
I've used a style that shows letter group headings so I need to use |
| 27210 |
the \longarg{group} switch. |
| 27211 |
|
| 27212 |
Since this is just an example document all the \cs{gls} commands |
| 27213 |
only occur on page~1, which means that each number list is just |
| 27214 |
\qt{1}. A real document would have the references scattered about. |
| 27215 |
The aliases haven't actually been referenced anywhere in the |
| 27216 |
document. |
| 27217 |
|
| 27218 |
The \fieldfmt{born}, \fieldfmt{died} and \fieldfmt{othername} fields will be |
| 27219 |
ignored by default since they don't correspond to recognised keys, |
| 27220 |
so the keys either need to be defined or the fields need to be |
| 27221 |
mapped to existing keys. In this case I've decided to map them to |
| 27222 |
the \field{user1}, \field{user2} and \field{user3} fields using |
| 27223 |
\csopt{field-aliases}: |
| 27224 |
\begin{codeenv} |
| 27225 |
\csopt[\fieldfmt{born}=\field{user1},\fieldfmt{died}=\field{user2},\fieldfmt{othername}=\field{user3}]{field-aliases} |
| 27226 |
\end{codeenv} |
| 27227 |
Although the aliases haven't been referenced in the document, I've |
| 27228 |
taken into account the possibility that they might later be added. |
| 27229 |
To prevent them from showing in the first two lists I've filtered |
| 27230 |
them out. This is easy to do since the aliases are all defined using |
| 27231 |
\atentry{index} whereas the remaining (non-aliased) entries are |
| 27232 |
defined using \atentry{entry} so \csopt{match} can be used to only |
| 27233 |
select entries defined with \atentry{entry}: |
| 27234 |
\begin{codeenv} |
| 27235 |
\csopt[entrytype=entry]{match} |
| 27236 |
\end{codeenv} |
| 27237 |
|
| 27238 |
I'd like the first use of \ics{gls} to display the full name, except |
| 27239 |
for the entry that has the \field{first} field set. The remaining |
| 27240 |
entries only have \field{text} set to a shortened version of the |
| 27241 |
name so they need to have the \field{name} field copied to the |
| 27242 |
\field{first} field using \csopt{replicate-fields}: |
| 27243 |
\begin{codeenv} |
| 27244 |
\csopt[\field{name}=\marg{\field{first}}]{replicate-fields} |
| 27245 |
\end{codeenv} |
| 27246 |
|
| 27247 |
I'd like the first use to show the other name in parentheses where |
| 27248 |
provided. The simplest way to achieve this is by defining the |
| 27249 |
\idx{postlinkhook} \ics{glsxtrpostlinkcategory}. If the |
| 27250 |
\field{category} field isn't specified it will default to |
| 27251 |
\code{general} (for entries defined with \atentry{entry}), so I |
| 27252 |
could just define \csfmt{glsxtrpostlinkgeneral} but to allow for |
| 27253 |
the possibility of extending the document to incorporate other types |
| 27254 |
of entries I decided to set the \field{category} to \code{people} |
| 27255 |
through the use of the \csopt{category} option: |
| 27256 |
\begin{codeenv} |
| 27257 |
\csopt[people]{category} |
| 27258 |
\end{codeenv} |
| 27259 |
|
| 27260 |
This means that I now need to define a command called |
| 27261 |
\csfmt{glsxtrpostlinkpeople} that will be used after instances of |
| 27262 |
\cs{gls} etc where the entry has the \field{category} set to |
| 27263 |
\code{people}. This first tests if that was the first use of the |
| 27264 |
entry with \ics{glsxtrifwasfirstuse} and then tests if the |
| 27265 |
\field{user3} field is set. If so, it does a space followed by that |
| 27266 |
field's value in parentheses. The entry's label can be obtained from |
| 27267 |
\ics{glslabel}: |
| 27268 |
\begin{codeenv} |
| 27269 |
\cs{newcommand}*\marg{\postlinkhook{people}}\marg{\comment{} |
| 27270 |
\cs{glsxtrifwasfirstuse} |
| 27271 |
\marg{\comment{} |
| 27272 |
\cs{ifglshasfield}\marg{\field{user3}}\marg{\cs{glslabel}}\comment{} |
| 27273 |
\marg{\cs{space}(\cs{glscurrentfieldvalue})}\comment{} |
| 27274 |
\marg{}\comment{} |
| 27275 |
}\comment{} |
| 27276 |
\marg{}\comment{} |
| 27277 |
} |
| 27278 |
\end{codeenv} |
| 27279 |
|
| 27280 |
I'd also like to do something similar after the name when the entry |
| 27281 |
is displayed in the glossary. This means defining the \idx{postnamehook} |
| 27282 |
\ics{glsxtrpostnamecategory}, in this case |
| 27283 |
\csfmt{glsxtrpostnamepeople}. The entry's label is referenced |
| 27284 |
with \ics{glscurrententrylabel}: |
| 27285 |
\begin{codeenv} |
| 27286 |
\cs{newcommand}*\marg{\postnamehook{people}}\marg{\comment{} |
| 27287 |
\cs{ifglshasfield}\marg{\field{user3}}\marg{\cs{glscurrententrylabel}}\comment{} |
| 27288 |
\marg{\cs{space}(\cs{glscurrentfieldvalue})}\comment{} |
| 27289 |
\marg{}\comment{} |
| 27290 |
} |
| 27291 |
\end{codeenv} |
| 27292 |
(A different command is used since \cs{gls} may occur in the |
| 27293 |
description, which would interfere with the current entry label if |
| 27294 |
they shared the same command to reference the label.) |
| 27295 |
|
| 27296 |
The \idx{postdescriptionhook} can be used to append the birth and |
| 27297 |
death dates. Although all the entries that have been selected from \exfile{people.bib} have a |
| 27298 |
\fieldfmt{died} field, I've added a check for the corresponding |
| 27299 |
\field{user3} field in case new references are added for people who are |
| 27300 |
still alive: |
| 27301 |
\begin{codeenv} |
| 27302 |
\cs{newcommand}*\marg{\postdeschook{people}}\marg{\comment{} |
| 27303 |
\cs{ifglshasfield}\marg{\field{user1}}\marg{\cs{glscurrententrylabel}} |
| 27304 |
\marg{\comment{born} |
| 27305 |
\cs{space}(\cs{glscurrentfieldvalue}\ics{comma}-{}-\cs{comma}\comment{} |
| 27306 |
\cs{ifglshasfield}\marg{user2}\marg{\cs{glscurrententrylabel}} |
| 27307 |
\marg{\comment{died} |
| 27308 |
\cs{glscurrentfieldvalue} |
| 27309 |
}\comment{} |
| 27310 |
\marg{}\comment{} |
| 27311 |
)\comment{} |
| 27312 |
}\comment{} |
| 27313 |
\marg{}\comment{} |
| 27314 |
} |
| 27315 |
\end{codeenv} |
| 27316 |
|
| 27317 |
The first list is quite straight-forward and can be created with: |
| 27318 |
\begin{codeenv} |
| 27319 |
\gls!{GlsXtrLoadResources}\oarg{ |
| 27320 |
\csopt[people]{src}, |
| 27321 |
\csopt[entrytype=entry]{match}, |
| 27322 |
\csopt[people]{category}, |
| 27323 |
\csopt[\field{name}=\marg{\field{first}}]{replicate-fields}, |
| 27324 |
\csopt[\fieldfmt{born}=\field{user1},\fieldfmt{died}=\field{user2},\fieldfmt{othername}=\field{user3}]{field-aliases} |
| 27325 |
} |
| 27326 |
\end{codeenv} |
| 27327 |
I have used the \csopt{sort} option and there's no document language, |
| 27328 |
so \bibgls\ will sort according to my locale. The custom |
| 27329 |
commands \gls{sortname} and \gls{sortvonname} ensure that the |
| 27330 |
entries are all sorted alphabetically according to the surnames. |
| 27331 |
|
| 27332 |
The second list can easily be created by adding the \csopt{secondary} |
| 27333 |
option: |
| 27334 |
\begin{codeenv} |
| 27335 |
\csopt[date:\field{user1}:bybirth]{secondary} |
| 27336 |
\end{codeenv} |
| 27337 |
This sorts according to the \field{user1} field (which was |
| 27338 |
originally the \fieldfmt{birth} field). |
| 27339 |
Note that different locales have different default date formats. |
| 27340 |
There may also be a difference in the default date format depending |
| 27341 |
on the Java \idx{localeprovider}. For example, if you switch from |
| 27342 |
using the \idx{JRE} to using the \idx{CLDR} you may find a change in |
| 27343 |
the default format. In case the format provided in the \ext{bib} |
| 27344 |
file isn't recognised, the required format can be set with: |
| 27345 |
\begin{codeenv} |
| 27346 |
\csopt[d MMM YYYY G]{secondary-date-sort-format} |
| 27347 |
\end{codeenv} |
| 27348 |
|
| 27349 |
Since the dates contain \glsname{idx.nbspchar}, this will need to be |
| 27350 |
converted to a space in the sort value for the pattern to match. |
| 27351 |
This can either be done with the \longarg{break-space} switch or |
| 27352 |
add to the global \bibgls\ options in the document: |
| 27353 |
\begin{codeenv} |
| 27354 |
\gls{BibGlsOptions}\marg{break-space} |
| 27355 |
\end{codeenv} |
| 27356 |
|
| 27357 |
I've changed the date group headings by redefining \gls{bibglsdategroup} and |
| 27358 |
\gls{bibglsdategrouptitle}, which means that the grouping in the |
| 27359 |
\code{bybirth} glossary will be in the form \meta{year} \meta{era}: |
| 27360 |
\begin{codeenv} |
| 27361 |
\cs{newcommand}\marg{\gls{bibglsdategroup}}[7]\marg{\idx{param}1\idx{param}4\idx{param}7} |
| 27362 |
\cs{newcommand}\marg{\gls{bibglsdategrouptitle}}[7]\marg{\cs{number}\idx{param}1\ \idx{param}4} |
| 27363 |
\end{codeenv} |
| 27364 |
I've also defined the \code{bybirth} glossary and supplied a title: |
| 27365 |
\begin{codeenv} |
| 27366 |
\cs{newglossary*}\marg{bybirth}\marg{People (Ordered by Birth)} |
| 27367 |
\end{codeenv} |
| 27368 |
|
| 27369 |
The first two glossaries have entries with fairly long names (especially those |
| 27370 |
with the \idx{postnamehook}), so the best style is the |
| 27371 |
\glostyle{altlistgroup}. The \sty{glossaries-extra-stylemods} |
| 27372 |
package patches this style to discourage page breaks occurring after |
| 27373 |
group headings, so I've also used the \styopt{stylemods} |
| 27374 |
option to automatically load that package. I'd like to use the |
| 27375 |
\glostyle{bookindex} style for the index, which is provided by |
| 27376 |
\sty{glossary-bookindex}, so I need: |
| 27377 |
\begin{codeenv} |
| 27378 |
\styopt[list,bookindex]{stylemods} |
| 27379 |
\end{codeenv} |
| 27380 |
This ensures that \isty{glossary-list} and \sty{glossary-bookindex} |
| 27381 |
are loaded and patches the list styles. |
| 27382 |
|
| 27383 |
The first two glossaries would look better with a terminating |
| 27384 |
\idx{full-stop}, so I've used the \styopt{postdot} package option. |
| 27385 |
(The \glostyle{bookindex} style doesn't use the \field{description} |
| 27386 |
field and therefore doesn't use the \idx{postdescriptionhook}.) |
| 27387 |
The index glossary type can be defined with the \styopt{index} |
| 27388 |
package option. I've set the default style to \glostyle{altlistgroup} |
| 27389 |
but this can locally be changed to \glostyle{bookindex} when I |
| 27390 |
display the index. The \styopt{record} option is needed to use |
| 27391 |
\bibgls, so the \styfmt{glossaries-extra} package is loaded with: |
| 27392 |
\begin{codeenv} |
| 27393 |
\cmd{usepackage}[\styopt{record},\comment{using bib2gls} |
| 27394 |
\styopt{index},\comment{create index glossary} |
| 27395 |
\styopt{postdot},\comment{dot after descriptions} |
| 27396 |
\comment{load glossary-list.sty and glossary-bookindex.sty and patch:} |
| 27397 |
\styopt[list,bookindex]{stylemods}, |
| 27398 |
\styopt[altlistgroup]{style}]\marg{glossaries-extra} |
| 27399 |
\end{codeenv} |
| 27400 |
|
| 27401 |
The index needs to include all the entries that have already been |
| 27402 |
defined but also needs to include the aliased entries. This means |
| 27403 |
that existing entries simply need their label copied to the |
| 27404 |
\code{index} glossary but the other entries need to be defined |
| 27405 |
so this requires setting the \csopt{action} option: |
| 27406 |
\begin{codeenv} |
| 27407 |
\csopt[define or copy]{action} |
| 27408 |
\end{codeenv} |
| 27409 |
I would also like to have groups in the index (which the |
| 27410 |
\glostyle{bookindex} style supports) so I need to specify a field |
| 27411 |
in which to save the group information using |
| 27412 |
\csopt{copy-action-group-field}: |
| 27413 |
\begin{codeenv} |
| 27414 |
\csopt[indexgroup]{copy-action-group-field} |
| 27415 |
\end{codeenv} |
| 27416 |
I need to remember to redefine \ics{glsxtrgroupfield} to this value before |
| 27417 |
displaying the index: |
| 27418 |
\begin{codeenv} |
| 27419 |
\cs{renewcommand}\marg{\cs{glsxtrgroupfield}}\marg{indexgroup} |
| 27420 |
\end{codeenv} |
| 27421 |
|
| 27422 |
The aliased entries won't be selected by default since they haven't |
| 27423 |
been used in the document, so I need to change the selection |
| 27424 |
criteria with \csopt{selection}: |
| 27425 |
\begin{codeenv} |
| 27426 |
\csopt[recorded and deps and see]{selection} |
| 27427 |
\end{codeenv} |
| 27428 |
|
| 27429 |
In the index, I'd like the surnames first. This can be done by |
| 27430 |
redefining the custom commands used in the \field{name} fields. |
| 27431 |
There's a slight complication here. These commands aren't defined on |
| 27432 |
the first \LaTeX\ run as their definitions are written to the |
| 27433 |
\ext{glstex} file by \bibgls, so I can't use \cs{renewcommand} (although |
| 27434 |
I could use \cs{glsrenewcommand}). |
| 27435 |
Instead I've provided some custom commands: |
| 27436 |
\begin{codeenv} |
| 27437 |
\cs{newcommand}*\marg{\cmd{swaptwo}}[2]\marg{\idx{param}2, \idx{param}1} |
| 27438 |
\cs{newcommand}*\marg{\cmd{swapthree}}[3]\marg{\idx{param}2 \idx{param}3, \idx{param}1} |
| 27439 |
\end{codeenv} |
| 27440 |
Now I just need to make an assignment using \ics{let}: |
| 27441 |
\begin{codeenv} |
| 27442 |
\cs{let}\gls{sortname}\cmd{swaptwo} |
| 27443 |
\cs{let}\gls{sortart}\cmd{swaptwo} |
| 27444 |
\cs{let}\gls{sortvonname}\cmd{swapthree} |
| 27445 |
\end{codeenv} |
| 27446 |
This doesn't perform any check to determine if the commands are |
| 27447 |
already defined so there won't be a problem on the first run. |
| 27448 |
|
| 27449 |
The first two glossaries shouldn't have number lists: |
| 27450 |
\begin{codeenv*} |
| 27451 |
\cs{printunsrtglossary}\oarg{\printglossopt[People (Alphabetical)]{title},\printglossopt{nonumberlist}} |
| 27452 |
\cs{printunsrtglossary}\oarg{\printglossopt[bybirth]{type},\printglossopt[false]{target},\printglossopt{nonumberlist}} |
| 27453 |
\end{codeenv*} |
| 27454 |
I'd like to use \sty{hyperref} but I have to switch off the |
| 27455 |
hypertargets for the second glossary otherwise I'll end up with |
| 27456 |
duplicate targets. This is done with \code{\printglossopt[false]{target}}. |
| 27457 |
All references using \cs{gls} etc will link to the first glossary. |
| 27458 |
|
| 27459 |
I could also do this for the index but the cross-references in the |
| 27460 |
aliased entries will link to the first glossary rather than the |
| 27461 |
relevant entry in the index. The simplest way to fix this is to |
| 27462 |
redefine \ics{glolinkprefix} to provide a different target: |
| 27463 |
\begin{codeenv} |
| 27464 |
\cs{renewcommand}*\marg{\cs{glolinkprefix}}\marg{idx:} |
| 27465 |
\end{codeenv} |
| 27466 |
These redefinitions need to be done before the index. I've decided |
| 27467 |
to use the starred \ics{printunsrtglossary*} to localise these |
| 27468 |
changes, although that's not needed for this document since the |
| 27469 |
index comes right at the end: |
| 27470 |
\begin{codeenv*} |
| 27471 |
\cs{printunsrtglossary*} |
| 27472 |
\oarg{\printglossopt[index]{type},\printglossopt[\glostyle{bookindex}]{style}} |
| 27473 |
\marg{\comment{} |
| 27474 |
\cs{let}\gls!{sortname}\cmd{swaptwo} |
| 27475 |
\cs{let}\gls!{sortart}\cmd{swaptwo} |
| 27476 |
\cs{let}\gls!{sortvonname}\cmd{swapthree} |
| 27477 |
\cs{renewcommand}\marg{\cs{glsxtrgroupfield}}\marg{indexgroup}\comment{} |
| 27478 |
\cs{renewcommand}*\marg{\cs{glolinkprefix}}\marg{idx:}\comment{} |
| 27479 |
} |
| 27480 |
\end{codeenv*} |
| 27481 |
The complete document code is listed below. The document build is: |
| 27482 |
\begin{verbatim} |
| 27483 |
pdflatex sample-people |
| 27484 |
bib2gls --group --break-space sample-people |
| 27485 |
pdflatex sample-people |
| 27486 |
\end{verbatim} |
| 27487 |
The four pages of the document are shown in \figureref{fig:sample-people.pdf}. |
| 27488 |
|
| 27489 |
\lstinputlisting[firstline=5]{../examples/sample-people.tex} |
| 27490 |
|
| 27491 |
\begin{figure} |
| 27492 |
\figcontents |
| 27493 |
{\pdftwocol{../examples/sample-people.pdf}{4}} |
| 27494 |
{\caption{\filefmt{sample-people.pdf}}} |
| 27495 |
{fig:sample-people.pdf} |
| 27496 |
\end{figure} |
| 27497 |
|
| 27498 |
\filesection{sample-authors.tex} |
| 27499 |
|
| 27500 |
This example uses the files \exfile{people.bib}, |
| 27501 |
\exfile{books.bib}, \exfile{no-interpret-preamble.bib} and |
| 27502 |
\exfile{interpret-preamble2.bib}. The aim is to reference the books |
| 27503 |
in \exfile{books.bib} and have them listed by author. This means |
| 27504 |
finding a way of assigning each book entry a \field{parent} field that |
| 27505 |
contains the label identifying the relevant author in \exfile{people.bib}. |
| 27506 |
I've used a style that shows letter group headings so I need to use |
| 27507 |
the \longarg{group} switch. |
| 27508 |
|
| 27509 |
To recap, each author is defined in \exfile{people.bib} in the form: |
| 27510 |
\begin{codeenv} |
| 27511 |
\atentry{entry}\marg{dickens, |
| 27512 |
\field{name}=\marg{\gls{sortname}\marg{Charles}\marg{Dickens}}, |
| 27513 |
\field{text}=\marg{Dickens}, |
| 27514 |
\field{description}=\marg{English writer and social critic}, |
| 27515 |
\fieldfmt{born}=\marg{7\idx{nbspchar}February 1812 AD}, |
| 27516 |
\fieldfmt{died}=\marg{9\idx{nbspchar}June 1870 AD}, |
| 27517 |
\fieldfmt{identifier}=\marg{person} |
| 27518 |
} |
| 27519 |
\end{codeenv} |
| 27520 |
and each book is defined in \exfile{books.bib} in the form: |
| 27521 |
\begin{codeenv} |
| 27522 |
\atentry{entry}\marg{bleakhouse, |
| 27523 |
\field{name}=\marg{Bleak House}, |
| 27524 |
\field{description}=\marg{novel by Charles Dickens}, |
| 27525 |
\fieldfmt{identifier}=\marg{book}, |
| 27526 |
\fieldfmt{author}=\marg{\gls{sortmediacreator}\marg{Charles}\marg{Dickens}}, |
| 27527 |
\fieldfmt{year}=\marg{1852} |
| 27528 |
} |
| 27529 |
\end{codeenv} |
| 27530 |
There's a field here (the custom \fieldfmt{author} field) that contains |
| 27531 |
the author's name, and this can be aliased to the \field{parent} |
| 27532 |
field with \csopt{field-aliases}: |
| 27533 |
\begin{codeenv} |
| 27534 |
\csopt[\fieldfmt{author}=\field{parent}]{field-aliases} |
| 27535 |
\end{codeenv} |
| 27536 |
but the author's label in the \exfile{people.bib} |
| 27537 |
file is just the \idx!{lowercase} surname. |
| 27538 |
|
| 27539 |
Remember from \sectionref{sec:texparserlib} that the interpreter |
| 27540 |
will be used on the \field{parent} field if the value contains |
| 27541 |
\idx{escchar} or \idx{bgroupchar} or \idx{egroupchar} and |
| 27542 |
\csopt[true]{interpret-label-fields}. This means that with this |
| 27543 |
field alias and the interpreter on, \bibgls\ will attempt to |
| 27544 |
interpret the field contents. So all that's needed is to ensure that |
| 27545 |
\bibgls\ is given a definition of \gls{sortmediacreator} that |
| 27546 |
ignores the first argument and converts the second argument to lower |
| 27547 |
case. This definition is available in |
| 27548 |
\exfile{interpret-preamble2.bib} but, since this file uses |
| 27549 |
\cs{renewcommand} rather than \cs{providecommand}, |
| 27550 |
\csopt[false]{write-preamble} is required to prevent \LaTeX\ from |
| 27551 |
picking up this definition. |
| 27552 |
|
| 27553 |
As with the \exfile{sample-people.tex} example, I need to copy |
| 27554 |
the \field{name} field to the \field{first} field if that field is |
| 27555 |
missing using \csopt{replicate-fields}: |
| 27556 |
\begin{codeenv} |
| 27557 |
\csopt[\field{name}=\marg{\field{first}}]{replicate-fields} |
| 27558 |
\end{codeenv} |
| 27559 |
and I also want to provide a semantic command to format the book |
| 27560 |
title, so the field aliases also need to convert the custom |
| 27561 |
\fieldfmt{identifier} field to \field{category}: |
| 27562 |
\begin{codeenv} |
| 27563 |
\csopt[\fieldfmt{identifier}=\field{category},\fieldfmt{author}=\field{parent}]{field-aliases} |
| 27564 |
\end{codeenv} |
| 27565 |
so that the document can set the \catattr{textformat} and |
| 27566 |
\catattr{glossnamefont} attributes: |
| 27567 |
\begin{codeenv} |
| 27568 |
\cs{newcommand}*\marg{\cmd{bookfont}}[1]\marg{\cs{emph}\marg{\idx{param}1}} |
| 27569 |
\cs{glssetcategoryattribute}\marg{book}\marg{\catattr{textformat}}\marg{bookfont} |
| 27570 |
\cs{glssetcategoryattribute}\marg{book}\marg{\catattr{glossnamefont}}\marg{bookfont} |
| 27571 |
\end{codeenv} |
| 27572 |
As with \exfile{sample-media.tex}, the terminating question mark at |
| 27573 |
the end of some of the \field{name} fields can cause an awkward |
| 27574 |
situation if \cs{gls} is used at the end of a sentence. This can be |
| 27575 |
dealt with by getting \bibgls\ to make a note of the fields that |
| 27576 |
end with sentence-terminating punctuation through the use of |
| 27577 |
the \csopt{check-end-punctuation} option. In this example, the |
| 27578 |
\field{name}, \field{text} and \field{first} fields are the same for |
| 27579 |
all the books, so it's sufficient just to check the \field{name} |
| 27580 |
field: |
| 27581 |
\begin{codeenv} |
| 27582 |
\csopt[\field{name}]{check-end-punctuation} |
| 27583 |
\end{codeenv} |
| 27584 |
With \sty{glossaries-extra} v1.23+ it's easy to hook into the |
| 27585 |
\idx{postlinkhook} to check if |
| 27586 |
\fielddisp{fieldendpunc}{nameendpunc} exists: |
| 27587 |
\begin{codeenv} |
| 27588 |
\cs{renewcommand}*\marg{\cs{glsxtrifcustomdiscardperiod}}[2]\marg{\comment{} |
| 27589 |
\cs{GlsXtrIfFieldUndef}\marg{\fielddisp{fieldendpunc}{nameendpunc}}\marg{\cs{glslabel}}\marg{\idx{param}2}\marg{\idx{param}1}\comment{} |
| 27590 |
} |
| 27591 |
\end{codeenv} |
| 27592 |
This will now cause the full stops following: |
| 27593 |
\begin{codeenv} |
| 27594 |
\cs{gls}\marg{whydidnttheyaskevans}. |
| 27595 |
\end{codeenv} |
| 27596 |
and |
| 27597 |
\begin{codeenv} |
| 27598 |
\cs{gls}\marg{doandroidsdreamofelectricsheep}. |
| 27599 |
\end{codeenv} |
| 27600 |
to be discarded. |
| 27601 |
|
| 27602 |
The complete document code is listed below. The document build is: |
| 27603 |
\begin{verbatim} |
| 27604 |
pdflatex sample-authors |
| 27605 |
bib2gls --group sample-authors |
| 27606 |
pdflatex sample-authors |
| 27607 |
\end{verbatim} |
| 27608 |
The resulting document is shown in \figureref{fig:sample-authors.pdf}. |
| 27609 |
|
| 27610 |
\lstinputlisting[firstline=5]{../examples/sample-authors.tex} |
| 27611 |
|
| 27612 |
\begin{figure} |
| 27613 |
\figcontents |
| 27614 |
{% |
| 27615 |
\frame{\includegraphics[height=.9\textheight]{../examples/sample-authors.pdf}}% |
| 27616 |
} |
| 27617 |
{\caption{\filefmt{sample-authors.pdf}}} |
| 27618 |
{fig:sample-authors.pdf} |
| 27619 |
\end{figure} |
| 27620 |
|
| 27621 |
\filesection{sample-citations.tex} |
| 27622 |
|
| 27623 |
This example uses the \BibTeX\ file \exfile{citations.bib} to create |
| 27624 |
a document that has both a bibliography created by \BibTeX\ and |
| 27625 |
glossaries created by \bibgls\ listing the authors and the titles. |
| 27626 |
There are no glossary reference commands, such as \cs{gls}, but |
| 27627 |
\bibgls\ can be run with \longarg{cite-as-record} to treat the |
| 27628 |
\ics{citation} commands (written to the \ext{aux} file by \ics{cite}) |
| 27629 |
as ignored records. Since \cs{cite} doesn't record the page number, |
| 27630 |
there are no associated \glspl{location}. |
| 27631 |
|
| 27632 |
The \mainglossary\ isn't required, so I've used |
| 27633 |
\styopt{nomain} to suppress its creation. I want to use both the |
| 27634 |
\glostyle{altlist} and \glostyle{indexgroup} styles but none of the |
| 27635 |
other styles, so I've used \styopt{nostyles} to prevent the |
| 27636 |
automatic loading of the default style packages and |
| 27637 |
\styopt{stylemods} to load the \sty{glossary-tree} and |
| 27638 |
\sty{glossary-list} packages and patch the styles. A \idx{full-stop} |
| 27639 |
is automatically placed after the descriptions with |
| 27640 |
\styopt{postdot}. |
| 27641 |
\begin{codeenv} |
| 27642 |
\cs{usepackage}\oarg{\styopt{record},\comment{using bib2gls} |
| 27643 |
\styopt{nomain},\comment{don't define main glossary} |
| 27644 |
\styopt{postdot},\comment{full stop after descriptions} |
| 27645 |
\styopt{nostyles},\comment{don't load default styles} |
| 27646 |
\comment{load glossary-tree and glossary-list and patch styles:} |
| 27647 |
\styopt[tree,list]{stylemods} |
| 27648 |
}\marg{glossaries-extra} |
| 27649 |
\end{codeenv} |
| 27650 |
Next I need to create the glossaries for the list of authors and |
| 27651 |
list of titles: |
| 27652 |
\begin{codeenv} |
| 27653 |
\cs{newglossary*}\marg{contributors}\marg{Authors} |
| 27654 |
\cs{newglossary*}\marg{titles}\marg{Titles} |
| 27655 |
\end{codeenv} |
| 27656 |
The simplest way of assigning the authors to the \code{contributors} |
| 27657 |
glossary and the titles to the \code{titles} glossary is to use: |
| 27658 |
\begin{codeenv} |
| 27659 |
\csopt[contributors]{type} |
| 27660 |
\end{codeenv} |
| 27661 |
in the \idx{resourceset} and provide a |
| 27662 |
modified version of \gls{bibglsnewbibtexentry} that assigns |
| 27663 |
\field{type} after the options: |
| 27664 |
\begin{codeenv} |
| 27665 |
\cs{newcommand}\marg{\gls{bibglsnewbibtexentry}}[4]\marg{\comment{} |
| 27666 |
\gls{longnewglossaryentry}*\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2,\field{type}=\marg{titles}}\marg{\idx{param}4}\comment{} |
| 27667 |
} |
| 27668 |
\end{codeenv} |
| 27669 |
The standard \BibTeX\ \glspl{entrytype} need aliasing to |
| 27670 |
\atentry{bibtexentry}: |
| 27671 |
\begin{codeenv} |
| 27672 |
\csopt[\ics{GlsXtrBibTeXEntryAliases}]{entry-type-aliases} |
| 27673 |
\end{codeenv} |
| 27674 |
and the \fieldfmt{title} field is aliased to \field{name}: |
| 27675 |
\begin{codeenv} |
| 27676 |
\csopt[\fieldfmt{title}=\field{name}]{field-aliases} |
| 27677 |
\end{codeenv} |
| 27678 |
(The other fields aren't required for the glossary lists.) |
| 27679 |
The \field{category} is set to the original \gls{entrytype}: |
| 27680 |
\begin{codeenv} |
| 27681 |
\csopt[same as original entry]{category} |
| 27682 |
\end{codeenv} |
| 27683 |
So, for example, an entry that's provided in the \ext{bib} file with |
| 27684 |
\atentryfmt{article} has the \field{category} field set to |
| 27685 |
\code{article}. (Compare this with \csopt[same as entry]{category} |
| 27686 |
which would set the \field{category} to \code{bibtexentry}.) |
| 27687 |
The spawned entries are all defined using \atentry{contributor} and |
| 27688 |
aren't aliased so both the \gls{entrytype} and the original \gls{entrytype} |
| 27689 |
are \code{contributor}. |
| 27690 |
|
| 27691 |
In order to list the titles according to category, I've use this as |
| 27692 |
the sort field: |
| 27693 |
\begin{codeenv} |
| 27694 |
\csopt[\field{category}]{sort-field} |
| 27695 |
\end{codeenv} |
| 27696 |
and setting the sort suffix to the \field{name} field sub-sorts |
| 27697 |
the \atentry{bibtexentry} types according to the title |
| 27698 |
(which was aliased to the \field{name}) and the |
| 27699 |
\atentry{contributor} types according to the author: |
| 27700 |
\begin{codeenv} |
| 27701 |
\csopt[\field{name}]{sort-suffix} |
| 27702 |
\end{codeenv} |
| 27703 |
|
| 27704 |
Next the groups identified by the labels \code{article} and \code{book} |
| 27705 |
are assigned titles. |
| 27706 |
\begin{codeenv} |
| 27707 |
\gls{glsxtrsetgrouptitle}\marg{article}\marg{Articles} |
| 27708 |
\gls{glsxtrsetgrouptitle}\marg{book}\marg{Books} |
| 27709 |
\end{codeenv} |
| 27710 |
The \field{group} field is actually set to the associated letter by the default |
| 27711 |
\csopt{sort} method. The desired labels are stored in the \field{category} |
| 27712 |
field. Since the entries are sorted by category, then they are naturally |
| 27713 |
in those sub-blocks, which means that the group titles can be set by locally |
| 27714 |
redefining \ics{glsxtrgroupfield} to \code{category}: |
| 27715 |
\begin{codeenv} |
| 27716 |
\cs{printunsrtglossary*}[\printglossopt[titles]{type},\printglossopt[indexgroup]{style}] |
| 27717 |
\marg{\comment{} |
| 27718 |
\cs{renewcommand}\marg{\cs{glsxtrgroupfield}}\marg{\field{category}}\comment{} |
| 27719 |
\cs{renewcommand}\marg{\cs{glstreenamefmt}}[1]\marg{\cs{emph}\marg{\idx{param}1}}\comment{} |
| 27720 |
\cs{renewcommand}\marg{\cs{glstreegroupheaderfmt}}[1]\marg{\ics{textbf}\marg{\idx{param}1}}\comment{} |
| 27721 |
} |
| 27722 |
\end{codeenv} |
| 27723 |
This again contradicts the advice given in |
| 27724 |
\sectionref{sec:logicaldivisions} as I'm sorting by the |
| 27725 |
\field{group} label. (Technically it's sorting by the |
| 27726 |
\field{category} label but this is being used as the group.) In this |
| 27727 |
case it's not a problem as the labels closely match the titles and |
| 27728 |
the sorting options ensure that the groups aren't broken up. |
| 27729 |
|
| 27730 |
There's no \field{description} field set for these entries, but the |
| 27731 |
\idx{postdescriptionhook} can still be used to append information. |
| 27732 |
In this case, I've appended a cross-reference to the bibliography. |
| 27733 |
Since the bibliography entry and the glossary term both have the |
| 27734 |
same label, the citation can easily be obtained with |
| 27735 |
\code{\ics{cite}\marg{\cs{glscurrententrylabel}}}: |
| 27736 |
\begin{codeenv} |
| 27737 |
\cs{newcommand}\marg{\postdeschook{article}}\marg{\cs{cite}\marg{\cs{glscurrententrylabel}}} |
| 27738 |
\cs{newcommand}\marg{\postdeschook{book}}\marg{\cs{cite}\marg{\cs{glscurrententrylabel}}} |
| 27739 |
\end{codeenv} |
| 27740 |
Note that this needs to be done for each \BibTeX\ \gls{entrytype}, but in |
| 27741 |
this case the \ext{bib} file only contains \atentryfmt{article} and |
| 27742 |
\atentryfmt{book} entries. (Similarly for the group titles above.) |
| 27743 |
|
| 27744 |
The list of contributors can simply be displayed with: |
| 27745 |
\begin{codeenv} |
| 27746 |
\cs{printunsrtglossary}[\printglossopt[contributors]{type},\printglossopt[altlist]{style}] |
| 27747 |
\end{codeenv} |
| 27748 |
This will only list the names as there's no description, but again |
| 27749 |
the \idx{postdescriptionhook} can be used, in this case for the \code{contributor} |
| 27750 |
category. The hook iterates |
| 27751 |
over the internal list provided by the \field{bibtexentry} field. |
| 27752 |
This allows the titles to be listed as well: |
| 27753 |
\begin{codeenv} |
| 27754 |
\cs{newcommand}\marg{\postdeschook{contributor}}\marg{\comment{} |
| 27755 |
\ics{glsxtrifhasfield}\marg{\field{bibtexentry}}\marg{\cs{glscurrententrylabel}}\comment{} |
| 27756 |
\marg{\comment{} |
| 27757 |
\cs{glsxtrfieldforlistloop} |
| 27758 |
\marg{\cs{glscurrententrylabel}}\marg{\field{bibtexentry}}\comment{} |
| 27759 |
\marg{\csfmt{contributorhandler}}\comment{} |
| 27760 |
}\comment{} |
| 27761 |
\marg{\ics{par} No titles.}\comment{} |
| 27762 |
} |
| 27763 |
\end{codeenv} |
| 27764 |
The \idx{handler} macro displays the name of the associated |
| 27765 |
\atentry{bibtexentry} term and the citation: |
| 27766 |
\begin{codeenv} |
| 27767 |
\cs{newcommand}\marg{\csfmt{contributorhandler}}[1]\marg{\cs{par}\ics{glsentryname}\marg{\idx{param}1} \cs{cite}\marg{\idx{param}1}} |
| 27768 |
\end{codeenv} |
| 27769 |
|
| 27770 |
The complete document code is listed below. The document build is: |
| 27771 |
\begin{verbatim} |
| 27772 |
pdflatex sample-citations |
| 27773 |
bib2gls --cite-as-record sample-citations |
| 27774 |
bibtex sample-citations |
| 27775 |
pdflatex sample-citations |
| 27776 |
pdflatex sample-citations |
| 27777 |
\end{verbatim} |
| 27778 |
The resulting document is shown in \figureref{fig:sample-citations.pdf}. |
| 27779 |
|
| 27780 |
\lstinputlisting[firstline=7]{../examples/sample-citations.tex} |
| 27781 |
|
| 27782 |
\begin{figure} |
| 27783 |
\figcontents |
| 27784 |
{\pdftwocol{../examples/sample-citations.pdf}{2}} |
| 27785 |
{\caption{\filefmt{sample-citations.pdf}}} |
| 27786 |
{fig:sample-citations.pdf} |
| 27787 |
\end{figure} |
| 27788 |
|
| 27789 |
\filesection{sample-msymbols.tex} |
| 27790 |
|
| 27791 |
This example uses \exfile{bigmathsymbols.bib}, |
| 27792 |
\exfile{mathsrelations.bib}, \exfile{binaryoperators.bib}, |
| 27793 |
\exfile{unaryoperators.bib} and \exfile{mathgreek.bib}. The \isty{stix} |
| 27794 |
package is required for some of the commands used in |
| 27795 |
\exfile{bigmathsymbols.bib}, so that must be loaded in the document. |
| 27796 |
|
| 27797 |
I'm using the \glostyle{mcolalttree} style for this document, |
| 27798 |
which means that the \sty{glossary-mcols} package is required and |
| 27799 |
the styles need patching, which can be done with |
| 27800 |
the \styopt{stylemods} package option: |
| 27801 |
\begin{codeenv} |
| 27802 |
\cs{usepackage}\oarg{\styopt{record},\comment{using bib2gls} |
| 27803 |
\styopt{nostyles},\comment{don't load default styles} |
| 27804 |
\styopt{postdot},\comment{append a dot after descriptions} |
| 27805 |
\styopt[mcols]{stylemods},\comment{load glossary-mcols.sty and patch} |
| 27806 |
\styopt[mcolalttree]{style}}\marg{glossaries-extra} |
| 27807 |
\end{codeenv} |
| 27808 |
|
| 27809 |
I'm not referencing any of the entries in the document as I'm just |
| 27810 |
generating a complete list of all the defined symbols. This means I |
| 27811 |
need to tell \bibgls\ to select all entries and don't bother saving |
| 27812 |
the \field{location} field: |
| 27813 |
\begin{codeenv} |
| 27814 |
\csopt[false]{save-locations}, |
| 27815 |
\csopt[all]{selection} |
| 27816 |
\end{codeenv} |
| 27817 |
Since I'm using a style that's based on \glostyle{alttree} I need to |
| 27818 |
find the widest \field{name}, which can be done with \csopt{set-widest}. |
| 27819 |
|
| 27820 |
The simplest way of dividing the glossary into logical blocks is to |
| 27821 |
sort according to the category, but first I need to use \csopt{field-aliases} |
| 27822 |
to convert the custom \fieldfmt{identifier} field to \field{category}: |
| 27823 |
\begin{codeenv} |
| 27824 |
\csopt[\fieldfmt{identifier}=\field{category}]{field-aliases} |
| 27825 |
\end{codeenv} |
| 27826 |
and sort by the \field{category} field: |
| 27827 |
\begin{codeenv} |
| 27828 |
\csopt[\field{category}]{sort-field} |
| 27829 |
\end{codeenv} |
| 27830 |
Since this will cause identical sort values, I need to provide a |
| 27831 |
a way of ordering these identical values. Here I've decided |
| 27832 |
to fallback on the \field{description} field: |
| 27833 |
\begin{codeenv} |
| 27834 |
\csopt[\field{description}]{identical-sort-action} |
| 27835 |
\end{codeenv} |
| 27836 |
This means that entries will be ordered by \field{category} and |
| 27837 |
then \field{description}, which naturally creates blocks of symbol |
| 27838 |
types in the glossary. This only uses a simple case-sensitive string |
| 27839 |
comparison which is fine for English, but for another language it |
| 27840 |
would be better to use \csopt{sort-suffix} as in the |
| 27841 |
\exfile{sample-textsymbols.tex} file. |
| 27842 |
|
| 27843 |
Remember that I want a small vertical gap between each logical |
| 27844 |
block. These need the \field{group} field which, with the default |
| 27845 |
locale sort, is obtained from the first letter of the sort value. |
| 27846 |
In this case the sort value is obtained from the \field{category} |
| 27847 |
field, and as each category happens to start with a different |
| 27848 |
letter, this means I get the desired effect. However, in the event |
| 27849 |
that I add more entries with a new category that happens to start |
| 27850 |
with the same letter as an existing category, it's better to provide |
| 27851 |
a more future-proof method, so I've set the \field{group} field to |
| 27852 |
fetch its value from the \field{category} field: |
| 27853 |
\begin{codeenv} |
| 27854 |
\csopt[\field{category}=\field{group}]{replicate-fields} |
| 27855 |
\end{codeenv} |
| 27856 |
(Since the \csopt{field-aliases} option is always performed before |
| 27857 |
\csopt{replicate-fields}, the \field{category} field will already |
| 27858 |
have been set and is available for replicating.) |
| 27859 |
|
| 27860 |
This means that I'm essentially sorting by the \field{group} labels, |
| 27861 |
which this manual has warned against doing. In this case, it's an |
| 27862 |
acceptable break from that rule as I've used options that ensure the |
| 27863 |
groups aren't broken up during sorting and I'm not concerned with the group |
| 27864 |
titles. A method such as that used in \exfile{sample-textsymbols2.tex} |
| 27865 |
would end up with titled blocks, which I don't want here. By using |
| 27866 |
resource options such as \csopt{field-aliases} and |
| 27867 |
\csopt{replicate-fields} I can avoid the warning that's triggered |
| 27868 |
with the default \longarg{warn-non-bib-fields}. |
| 27869 |
|
| 27870 |
The complete document code is listed below. The document build is: |
| 27871 |
\begin{verbatim} |
| 27872 |
pdflatex sample-msymbols |
| 27873 |
bib2gls sample-msymbols |
| 27874 |
pdflatex sample-msymbols |
| 27875 |
\end{verbatim} |
| 27876 |
The resulting document is shown in \figureref{fig:sample-msymbols.pdf}. |
| 27877 |
|
| 27878 |
\lstinputlisting[firstline=5]{../examples/sample-msymbols.tex} |
| 27879 |
|
| 27880 |
\begin{figure} |
| 27881 |
\figcontents |
| 27882 |
{% |
| 27883 |
\frame{\includegraphics[height=.9\textheight]{../examples/sample-msymbols.pdf}}% |
| 27884 |
} |
| 27885 |
{\caption{\filefmt{sample-msymbols.pdf}}} |
| 27886 |
{fig:sample-msymbols.pdf} |
| 27887 |
\end{figure} |
| 27888 |
|
| 27889 |
\filesection{sample-maths.tex} |
| 27890 |
|
| 27891 |
This example uses \exfile{bigmathsymbols.bib} and \exfile{mathsobjects.bib}. |
| 27892 |
It has a fairly similar preamble to \exfile{sample-msymbols.tex}, |
| 27893 |
but \exfile{no-interpret-preamble.bib} and |
| 27894 |
\exfile{interpret-preamble.bib} are now needed to provide |
| 27895 |
the \gls!{sortart} command: |
| 27896 |
\begin{codeenv} |
| 27897 |
\gls{GlsXtrLoadResources}\oarg{ |
| 27898 |
\csopt[no-interpret-preamble]{src}, |
| 27899 |
\csopt[false]{interpret-preamble} |
| 27900 |
} |
| 27901 |
\end{codeenv} |
| 27902 |
There's also an extra custom field to alias: |
| 27903 |
\begin{codeenv} |
| 27904 |
\csopt[\fieldfmt{identifier}=\field{category},\fieldfmt{format}=\field{user1}]{field-aliases} |
| 27905 |
\end{codeenv} |
| 27906 |
I've aliased \fieldfmt{format} to \field{user1} since \gls!{glsxtrfmt} |
| 27907 |
defaults to that field. If I decided to use a different field I also |
| 27908 |
need to remember to redefine \ics{GlsXtrFmtField} to match. |
| 27909 |
|
| 27910 |
As with \exfile{sample-msymbols.tex} I'm sorting by the |
| 27911 |
\field{category} label and this value is copied to the \field{group} |
| 27912 |
field, but again I don't have a \gls{hierarchicalglossary} as the logical |
| 27913 |
blocks don't have titles. |
| 27914 |
|
| 27915 |
In this document I only want to select entries that have been |
| 27916 |
indexed, so I've omitted the \csopt{selection} option I used in the |
| 27917 |
\exfile{sample-msymbols.tex} example, however |
| 27918 |
I still don't want any number lists so I still have |
| 27919 |
\csopt[false]{save-locations}. |
| 27920 |
|
| 27921 |
I want \gls!{glsxtrfmt} to index the term (which it doesn't by default) so |
| 27922 |
that means I need to redefine \ics{GlsXtrFmtDefaultOptions} |
| 27923 |
to prevent it from using \code{noindex}: |
| 27924 |
\begin{codeenv} |
| 27925 |
\cs{renewcommand}\marg{\cs{GlsXtrFmtDefaultOptions}}\marg{} |
| 27926 |
\end{codeenv} |
| 27927 |
I've provided some convenient wrapper commands that use |
| 27928 |
\gls!{glsxtrfmt*} or the non-linking \gls!{glsxtrentryfmt} that |
| 27929 |
are in the form: |
| 27930 |
\begin{codeenv} |
| 27931 |
\cs{newcommand}\marg{\cmd{set}}[2][]\marg{\gls{glsxtrfmt*}\oarg{\idx{param}1}\marg{set}\marg{\idx{param}2}} |
| 27932 |
\cs{newcommand}\marg{\cmd{nlset}}[1]\marg{\gls{glsxtrentryfmt}\marg{set}\marg{\idx{param}1}} |
| 27933 |
\end{codeenv} |
| 27934 |
The use of the starred form allows: |
| 27935 |
\begin{codeenv} |
| 27936 |
\cmd{[}\cmd{set}\marg{A} = \cs{gls}\marg{bigcup}[\idx{sbchar}\marg{i=1}\idx{spchar}n] \cmd{set}\marg{B}[\idx{sbchar}i] \cmd{]} |
| 27937 |
\end{codeenv} |
| 27938 |
which produces: |
| 27939 |
\[ \mathcal{A} = \bigcup_{i=1}^n \mathcal{B}_i \] |
| 27940 |
Note the difference if the optional arguments aren't used: |
| 27941 |
\begin{codeenv} |
| 27942 |
\cmd{[}\cmd{set}\marg{A} = \cs{gls}\marg{bigcup}\idx{sbchar}\marg{i=1}\idx{spchar}n \cmd{set}\marg{B}\idx{sbchar}i \cmd{]} |
| 27943 |
\end{codeenv} |
| 27944 |
This produces: |
| 27945 |
\[ \mathcal{A} = \bigcup{}_{i=1}^n \mathcal{B}{}_i \] |
| 27946 |
|
| 27947 |
Be careful with the set cardinality example. You might be tempted to |
| 27948 |
nest \csfmt{set} within the argument of \csfmt{setcard} but this |
| 27949 |
results in nested hyperlinks. These are unpredictable and there's no |
| 27950 |
consistent handling of them between different PDF viewers. It can |
| 27951 |
also be confusing to the reader. If |
| 27952 |
$\lvert\mathcal{B}_1\cup\mathcal{B}_2\rvert$ |
| 27953 |
shows up as what appears to be a single hyperlink, where would the |
| 27954 |
reader expect the target? This is the reason for providing the |
| 27955 |
non-linking commands like \csfmt{nlset} and \csfmt{nlsetcard}. |
| 27956 |
|
| 27957 |
The complete document code is listed below. The document build is: |
| 27958 |
\begin{verbatim} |
| 27959 |
pdflatex sample-maths |
| 27960 |
bib2gls sample-maths |
| 27961 |
pdflatex sample-maths |
| 27962 |
\end{verbatim} |
| 27963 |
The resulting document is shown in \figureref{fig:sample-maths.pdf}. |
| 27964 |
|
| 27965 |
\lstinputlisting[firstline=5]{../examples/sample-maths.tex} |
| 27966 |
|
| 27967 |
\begin{figure} |
| 27968 |
\figcontents |
| 27969 |
{% |
| 27970 |
\frame{\includegraphics[height=.9\textheight]{../examples/sample-maths.pdf}}% |
| 27971 |
} |
| 27972 |
{\caption{\filefmt{sample-maths.pdf}}} |
| 27973 |
{fig:sample-maths.pdf} |
| 27974 |
\end{figure} |
| 27975 |
|
| 27976 |
\filesection{sample-textsymbols.tex} |
| 27977 |
|
| 27978 |
This example uses \exfile{miscsymbols.bib}. |
| 27979 |
This requires both \isty{marvosym} and (with the \styoptfmt{weather} option) |
| 27980 |
\isty{ifsym}. Unfortunately both define the commands \csfmt{Sun} |
| 27981 |
and \csfmt{Lightning}, so these commands need to be undefined after |
| 27982 |
the first package is loaded and before the second. |
| 27983 |
Since I want the definitions provide by \sty{ifsym} I have to first |
| 27984 |
load \sty{marvosym}, then undefine the conflicting commands and then |
| 27985 |
load \sty{ifsym}: |
| 27986 |
\begin{codeenv} |
| 27987 |
\cs{usepackage}\marg{etoolbox} |
| 27988 |
\cs{usepackage}\marg{marvosym} |
| 27989 |
\cs{undef}\cmd{Sun} |
| 27990 |
\cs{undef}\cmd{Lightning} |
| 27991 |
\cs{usepackage}\oarg{\styoptfmt{weather}}\marg{ifsym} |
| 27992 |
\end{codeenv} |
| 27993 |
The \sty{etoolbox} package is also loaded as it provides |
| 27994 |
\ics{undef}. (An alternative is to modify the |
| 27995 |
\exfile{miscsymbols.bib} file so that it uses \sty{ifsym}'s more |
| 27996 |
generic \cs{textweathersymbol} command and omit the \styoptfmt{weather} |
| 27997 |
option when loading the package, but the method used here |
| 27998 |
demonstrates how to deal with such conflicts.) |
| 27999 |
|
| 28000 |
The custom \gls{entrytype} \atentryfmt{icon} must be aliased for the |
| 28001 |
entries to be recognised: |
| 28002 |
\begin{codeenv} |
| 28003 |
\csopt[icon=symbol]{entry-type-aliases} |
| 28004 |
\end{codeenv} |
| 28005 |
|
| 28006 |
Since none of the entries have a \field{name} or \field{description} |
| 28007 |
field, the custom fields \fieldfmt{icon} and |
| 28008 |
\fieldfmt{icondescription} need to be aliased to them. |
| 28009 |
The document uses the \glostyle{alttreegroup} style where the groups |
| 28010 |
are obtained from the \field{category}, which again I obtain from |
| 28011 |
the custom \fieldfmt{identifier} field using: |
| 28012 |
\begin{codeenv} |
| 28013 |
\csopt[ |
| 28014 |
\fieldfmt{identifier}=\field{category}, |
| 28015 |
\fieldfmt{icon}=\field{name}, |
| 28016 |
\fieldfmt{icondescription}=\field{description}]{field-aliases}, |
| 28017 |
\csopt[\field{category}=\field{group}]{replicate-fields} |
| 28018 |
\end{codeenv} |
| 28019 |
The \field{group} field is just a label and an appropriate title needs to be |
| 28020 |
supplied for each group label: |
| 28021 |
\begin{codeenv} |
| 28022 |
\cs{glsxtrsetgrouptitle}\marg{information}\marg{Information} |
| 28023 |
\cs{glsxtrsetgrouptitle}\marg{mediacontrol}\marg{Media Controls} |
| 28024 |
\cs{glsxtrsetgrouptitle}\marg{weather}\marg{Weather Symbols} |
| 28025 |
\end{codeenv} |
| 28026 |
This also requires sorting first by \field{category} and then |
| 28027 |
fallback on another field. The most appropriate here is the |
| 28028 |
\field{description} field, but instead of using |
| 28029 |
\csopt{identical-sort-action}, I'm using \csopt{sort-suffix}, |
| 28030 |
which works better with the default locale sort when the fallback |
| 28031 |
field consists of words or phrases. |
| 28032 |
\begin{codeenv} |
| 28033 |
\csopt[\field{category}]{sort-field}, |
| 28034 |
\csopt[\field{description}]{sort-suffix}, |
| 28035 |
\csopt[|]{sort-suffix-marker} |
| 28036 |
\end{codeenv} |
| 28037 |
Since I'm using one of the \glostyle{alttree} styles, I need to set |
| 28038 |
the widest name: |
| 28039 |
\begin{codeenv} |
| 28040 |
\csopt{set-widest} |
| 28041 |
\end{codeenv} |
| 28042 |
In this case, \bibgls\ won't be able to determine the widest name |
| 28043 |
since it doesn't recognise any of the commands, so it will have to |
| 28044 |
use the fallback command, which will use one of the commands |
| 28045 |
provided by the \sty{glossaries-extra-stylemods} package. |
| 28046 |
|
| 28047 |
This is actually not the best method as \bibgls\ can't see the group |
| 28048 |
titles as they're in the document, so it's only able to sort by the |
| 28049 |
label. While this might work for English, it can become a problem |
| 28050 |
for other languages that use extended Latin or non-Latin characters |
| 28051 |
in their alphabet. A much better method is to treat this as a |
| 28052 |
\gls{hierarchicalglossary} with topic titles as the \glspl{top-levelentry}. |
| 28053 |
This is covered in the next example \exfile{sample-textsymbols2.tex}. |
| 28054 |
|
| 28055 |
The complete document code is listed below. The document build is: |
| 28056 |
\begin{verbatim} |
| 28057 |
pdflatex sample-textsymbols |
| 28058 |
bib2gls sample-textsymbols |
| 28059 |
pdflatex sample-textsymbols |
| 28060 |
\end{verbatim} |
| 28061 |
The resulting document is shown in \figureref{fig:sample-textsymbols.pdf}. |
| 28062 |
|
| 28063 |
\lstinputlisting[firstline=6]{../examples/sample-textsymbols.tex} |
| 28064 |
|
| 28065 |
\begin{figure} |
| 28066 |
\figcontents |
| 28067 |
{% |
| 28068 |
\frame{\includegraphics[height=.9\textheight]{../examples/sample-textsymbols.pdf}}% |
| 28069 |
} |
| 28070 |
{\caption{\filefmt{sample-textsymbols.pdf}}} |
| 28071 |
{fig:sample-textsymbols.pdf} |
| 28072 |
\end{figure} |
| 28073 |
|
| 28074 |
\filesection{sample-textsymbols2.tex} |
| 28075 |
|
| 28076 |
This example is a better approach than the |
| 28077 |
\exfile{sample-textsymbols.tex} example above. As with the previous |
| 28078 |
example, this requires both \isty{marvosym} and \isty{ifsym} so the |
| 28079 |
same patch is applied to avoid conflict. |
| 28080 |
|
| 28081 |
As before, the custom \gls{entrytype} \atentryfmt{icon} must be aliased for the |
| 28082 |
entries to be recognised: |
| 28083 |
\begin{codeenv} |
| 28084 |
\csopt[icon=symbol]{entry-type-aliases} |
| 28085 |
\end{codeenv} |
| 28086 |
|
| 28087 |
The \exfile{topics.bib} file contains terms with |
| 28088 |
labels that match the custom \fieldfmt{identifier} fields used in |
| 28089 |
the \exfile{miscsymbols.bib} file. So both files are loaded and the |
| 28090 |
\fieldfmt{identifier} field is now aliased to \field{parent}. These |
| 28091 |
\glspl{parententry} represent the topics and unlike the previous example |
| 28092 |
it's now possible to sort by the topic title (obtained from the |
| 28093 |
\field{name} field) instead of by the label. |
| 28094 |
\begin{codeenv} |
| 28095 |
\csopt[topics,miscsymbols]{src}, |
| 28096 |
\csopt[ |
| 28097 |
\fieldfmt{identifier}=\field{parent}, |
| 28098 |
\fieldfmt{icon}=\field{name}, |
| 28099 |
\fieldfmt{icondescription}=\field{description}]{field-aliases}, |
| 28100 |
\end{codeenv} |
| 28101 |
There's no \csopt{sort-field} option in this example. The default |
| 28102 |
\field{sort} field is used. Since it's not set for any of the |
| 28103 |
entries, the fallback value will be used. In the case of the topic |
| 28104 |
titles (\atentry{index} and \atentry{indexplural}), I want to sort |
| 28105 |
by the \field{name}, which is the default fallback if the |
| 28106 |
\field{sort} field is missing for the index \glspl{entrytype}. |
| 28107 |
|
| 28108 |
The default fallback for the \field{sort} field for \atentry{symbol} |
| 28109 |
entries is the label, but in this case I want to use the |
| 28110 |
\field{description} field: |
| 28111 |
\begin{codeenv} |
| 28112 |
\csopt[description]{symbol-sort-fallback} |
| 28113 |
\end{codeenv} |
| 28114 |
The best styles for this kind of glossary are the topic styles |
| 28115 |
provided by \isty{glossary-topic}. This package was only added to |
| 28116 |
\sty{glossaries-extra} v1.40, so you need to make sure you have at |
| 28117 |
least that version installed. |
| 28118 |
|
| 28119 |
In this case I've decided to use the \glostyle{topic} style. I can |
| 28120 |
use it with or without the \csopt{set-widest} option. |
| 28121 |
As with the previous example, \bibgls\ won't be able to determine |
| 28122 |
the widest name since it doesn't recognise any of the commands |
| 28123 |
contained in the \field{name} fields, so it will have to use the |
| 28124 |
fallback method, which will use one of the commands provided by the |
| 28125 |
\sty{glossaries-extra-stylemods} package. The \code{tree} option is |
| 28126 |
needed to enable the appropriate commands: |
| 28127 |
\begin{codeenv} |
| 28128 |
\cmd{usepackage}\oarg{\styopt{record}, |
| 28129 |
\styopt{nostyles}, |
| 28130 |
\styopt{postdot}, |
| 28131 |
\styopt[tree,topic]{stylemods}, |
| 28132 |
\styopt[topic]{style}}\marg{glossaries-extra} |
| 28133 |
\end{codeenv} |
| 28134 |
|
| 28135 |
The complete document code is listed below. The document build is: |
| 28136 |
\begin{verbatim} |
| 28137 |
pdflatex sample-textsymbols2 |
| 28138 |
bib2gls --group sample-textsymbols2 |
| 28139 |
pdflatex sample-textsymbols2 |
| 28140 |
\end{verbatim} |
| 28141 |
The resulting document is shown in \figureref{fig:sample-textsymbols2.pdf}. |
| 28142 |
|
| 28143 |
\lstinputlisting[firstline=5]{../examples/sample-textsymbols2.tex} |
| 28144 |
|
| 28145 |
\begin{figure} |
| 28146 |
\figcontents |
| 28147 |
{% |
| 28148 |
\frame{\includegraphics[height=.9\textheight]{../examples/sample-textsymbols2.pdf}}% |
| 28149 |
} |
| 28150 |
{\caption{\filefmt{sample-textsymbols2.pdf}}} |
| 28151 |
{fig:sample-textsymbols2.pdf} |
| 28152 |
\end{figure} |
| 28153 |
|
| 28154 |
\filesection{sample-markuplanguages.tex} |
| 28155 |
|
| 28156 |
This example uses \exfile{markuplanguages.bib}. Since the file |
| 28157 |
includes abbreviations, any commands that must be used before |
| 28158 |
abbreviations are defined need to go before |
| 28159 |
\gls!{GlsXtrLoadResources}. This includes the abbreviation style, |
| 28160 |
which I've set to \abbrstyle{long-short-desc}: |
| 28161 |
\begin{codeenv} |
| 28162 |
\cs{setabbreviationstyle}\oarg{markuplanguage}\marg{\abbrstyle{long-short-desc}} |
| 28163 |
\end{codeenv} |
| 28164 |
This style sets the \field{name} field using |
| 28165 |
\ics{glsxtrlongshortdescname}, which defaults to the long form |
| 28166 |
followed by the short form in parentheses. I decided to switch this |
| 28167 |
round so that the short form is shown first, which conveniently |
| 28168 |
matches the default \csopt{abbreviation-sort-fallback}. |
| 28169 |
\begin{codeenv} |
| 28170 |
\cs{renewcommand}*\marg{\cs{glsxtrlongshortdescname}}\marg{\comment{} |
| 28171 |
\cs{protect}\ics{glsabbrvfont}\marg{\ics{the}\ics{glsshorttok}}\cs{space} |
| 28172 |
\ics{glsxtrparen}\marg{\ics{glslongfont}\marg{\cs{the}\ics{glslongtok}}}\comment{} |
| 28173 |
} |
| 28174 |
\end{codeenv} |
| 28175 |
(The long form is still shown before the short form on the first use |
| 28176 |
of \cs{gls} in the document. The switch in the above code only |
| 28177 |
affects how the term is displayed in the glossary.) |
| 28178 |
|
| 28179 |
This redefinition must be done before the abbreviations are defined |
| 28180 |
as it's expanded when the \field{name} field is set. (Note the need |
| 28181 |
to protect commands that shouldn't be expanded.) If I decide not to change |
| 28182 |
the \field{name} format in this way, I would then need to use |
| 28183 |
\csopt[long]{abbreviation-sort-fallback}. |
| 28184 |
|
| 28185 |
I also decided to make use of the custom command \csfmt{abbrvtag} |
| 28186 |
that marks up the letters in the \field{long} field used to obtain |
| 28187 |
the abbreviation. As with the abbreviation style, this must be |
| 28188 |
done before the abbreviations are defined: |
| 28189 |
\begin{codeenv} |
| 28190 |
\cs{GlsXtrEnableInitialTagging}\marg{markuplanguage}\marg{\cmd{abbrvtag}} |
| 28191 |
\end{codeenv} |
| 28192 |
If you accidentally place it after \gls{GlsXtrLoadResources}, you'll |
| 28193 |
encounter an error on the second \LaTeX\ run (but not the first). |
| 28194 |
This is because \ics{GlsXtrEnableInitialTagging} requires that the |
| 28195 |
supplied command (\csfmt{abbrvtag} in this case) be undefined. On |
| 28196 |
the first \LaTeX\ it's undefined, but on the second it picks up |
| 28197 |
the \atentry{preamble} definition, which is now in the resource file. |
| 28198 |
|
| 28199 |
The tagging format is governed by \ics{glsxtrtagfont} which |
| 28200 |
underlines its argument by default. I've redefined it to also |
| 28201 |
convert the letter to \idx{uppercase}: |
| 28202 |
\begin{codeenv} |
| 28203 |
\cs{renewcommand}*\marg{\cs{glsxtrtagfont}}[1]\marg{\ics{underline}\marg{\cs{glsuppercase}\marg{\idx{param}1}}} |
| 28204 |
\end{codeenv} |
| 28205 |
Note that in the \code{mathml} case, the first tag consists of more |
| 28206 |
than one letter: |
| 28207 |
\begin{codeenv} |
| 28208 |
\field{long}=\marg{\cmd{abbrvtag}\marg{m\cs{NoCaseChange}\marg{ath}}ematical }\idx{stringconcat}markuplang |
| 28209 |
\end{codeenv} |
| 28210 |
Here \ics{NoCaseChange} prevents \ics{glsuppercase} |
| 28211 |
from applying the case change. |
| 28212 |
|
| 28213 |
The default \csopt{selection} criteria includes entries that have |
| 28214 |
been indexed and any cross-references. Some of the |
| 28215 |
\field{description} fields include \ics{glsxtrshort}, which \bibgls\ picks |
| 28216 |
up and the referenced entry is included in the dependency list. |
| 28217 |
However, I don't want any indexing |
| 28218 |
performed by commands occurring in the glossary. This can be dealt |
| 28219 |
with in one of two ways: either switch the format to \encap{glsignore} |
| 28220 |
or suppress the indexing by changing the default options with |
| 28221 |
\ics{GlsXtrSetDefaultGlsOpts}. In this case I decided to turn the |
| 28222 |
records into ignored records: |
| 28223 |
\begin{codeenv} |
| 28224 |
\ics{GlsXtrSetDefaultNumberFormat}\marg{\encap{glsignore}} |
| 28225 |
\end{codeenv} |
| 28226 |
This means that some of the entries won't have \glspl{locationlist}, so |
| 28227 |
I've defined a \idx{postdescriptionhook} that inserts a \idx{full-stop} after the |
| 28228 |
\field{description} if there's no \gls{location} otherwise it inserts a |
| 28229 |
comma: |
| 28230 |
\begin{codeenv} |
| 28231 |
\cs{newcommand}\marg{\postdeschook{markuplanguage}}\marg{\comment{} |
| 28232 |
\cs{glsxtrifhasfield}\marg{\field{location}}\marg{\cs{glscurrententrylabel}}\comment{} |
| 28233 |
\marg{,}\comment{} |
| 28234 |
\marg{.}\comment{} |
| 28235 |
} |
| 28236 |
\end{codeenv} |
| 28237 |
I've used \csopt{loc-suffix} to append a \idx{full-stop} after the |
| 28238 |
\glspl{locationlist}. This doesn't affect the entries that haven't been |
| 28239 |
indexed. |
| 28240 |
|
| 28241 |
I decided to convert the first letter of the \field{name} field to |
| 28242 |
\idx{uppercase}. Since the \field{name} is implicitly set for |
| 28243 |
abbreviations based on the style, I've decided to implement this |
| 28244 |
through the \catattr{glossname} attribute rather than using |
| 28245 |
\csopt{name-case-change}: |
| 28246 |
\begin{codeenv} |
| 28247 |
\cs{glssetcategoryattribute}\marg{markuplanguage}\marg{\catattr{glossname}}\marg{firstuc} |
| 28248 |
\end{codeenv} |
| 28249 |
If this line causes an error when the glossary is displayed that goes |
| 28250 |
away if it's commented out, make sure you have at least version 2.06 |
| 28251 |
of \sty{mfirstuc}. For most of the entries, this doesn't make a |
| 28252 |
difference as they already start with a capital. It's only the |
| 28253 |
\code{markdown} entry that's actually affected. |
| 28254 |
|
| 28255 |
The description case change is dealt with by \bibgls\ instead: |
| 28256 |
\begin{codeenv} |
| 28257 |
\csopt[firstuc]{description-case-change} |
| 28258 |
\end{codeenv} |
| 28259 |
This works better than the \catattr{glossdesc} attribute as \bibgls\ can |
| 28260 |
convert commands like \ics{glstext} into \ics{Glstext} which |
| 28261 |
\ics{makefirstuc} can't do. (Although in this particular example, |
| 28262 |
there's no difference as both instances of \cs{glstext} already |
| 28263 |
produce \idx{uppercase} text.) |
| 28264 |
|
| 28265 |
The complete document code is listed below. The document build is: |
| 28266 |
\begin{verbatim} |
| 28267 |
pdflatex sample-markuplanguages |
| 28268 |
bib2gls --group sample-markuplanguages |
| 28269 |
pdflatex sample-markuplanguages |
| 28270 |
\end{verbatim} |
| 28271 |
The resulting document is shown in \figureref{fig:sample-markuplanguages.pdf}. |
| 28272 |
|
| 28273 |
\lstinputlisting[firstline=5]{../examples/sample-markuplanguages.tex} |
| 28274 |
|
| 28275 |
\begin{figure} |
| 28276 |
\figcontents |
| 28277 |
{% |
| 28278 |
\frame{\includegraphics[height=.9\textheight]{../examples/sample-markuplanguages.pdf}}% |
| 28279 |
} |
| 28280 |
{\caption{\filefmt{sample-markuplanguages.pdf}}} |
| 28281 |
{fig:sample-markuplanguages.pdf} |
| 28282 |
\end{figure} |
| 28283 |
|
| 28284 |
|
| 28285 |
\filesection{sample-usergroups.tex} |
| 28286 |
|
| 28287 |
This example uses \exfile{usergroups.bib}. This requires \XeLaTeX\ |
| 28288 |
or \LuaLaTeX\ as the \ext{bib} file includes \idx{non-ASCII} labels. |
| 28289 |
The entries include fields in different languages, the main one |
| 28290 |
being English. If an entry has a non-English \field{name} or |
| 28291 |
\field{long} field, it also includes the custom field |
| 28292 |
\fieldfmt{translation} that provides an (approximate) translation. |
| 28293 |
If this field is present, the language is given by the first element |
| 28294 |
of the custom \fieldfmt{language} field. |
| 28295 |
|
| 28296 |
In this case, I'm providing keys for the custom |
| 28297 |
\fieldfmt{language} and \fieldfmt{translation} fields, and, for a bit |
| 28298 |
of variety from the other examples, I'm ignoring the custom |
| 28299 |
\fieldfmt{identifier} field. The custom keys are provided with |
| 28300 |
\ics{glsaddstoragekey}: |
| 28301 |
\begin{codeenv} |
| 28302 |
\cs{glsaddstoragekey}\marg{language}\marg{}\marg{\cmd{glsentrylanguage}} |
| 28303 |
\cs{glsaddstoragekey}\marg{translation}\marg{}\marg{\cmd{glsentrytranslation}} |
| 28304 |
\end{codeenv} |
| 28305 |
The \ext{bib} file includes abbreviations. Remember that the |
| 28306 |
abbreviation style must be set before the resource file is loaded: |
| 28307 |
\begin{codeenv} |
| 28308 |
\cs{setabbreviationstyle}\oarg{tug}\marg{\abbrstyle{long-short-user}} |
| 28309 |
\end{codeenv} |
| 28310 |
For this example, I'm explicitly setting the \field{category} field |
| 28311 |
to \code{tug}: |
| 28312 |
\begin{codeenv} |
| 28313 |
\csopt[tug]{category} |
| 28314 |
\end{codeenv} |
| 28315 |
Some of the fields end with a \idx{full-stop}. This isn't a problem with |
| 28316 |
the \field{long} field as the first use follows the long form with |
| 28317 |
the short form in parentheses, but it will be a problem on |
| 28318 |
subsequent use if the \field{short} field ends with a \idx{full-stop}. |
| 28319 |
This means I need to check for end-of-sentence punctuation |
| 28320 |
for the \field{short} field. It's also a good idea to do this for |
| 28321 |
the \field{name} field for the non-abbreviations. |
| 28322 |
\begin{codeenv} |
| 28323 |
\csopt[\field{name},\field{short}]{check-end-punctuation} |
| 28324 |
\end{codeenv} |
| 28325 |
It's now possible to discard a \idx{full-stop} that follows |
| 28326 |
\ics{gls}: |
| 28327 |
\begin{codeenv} |
| 28328 |
\cs{renewcommand}*\marg{\cs{glsxtrifcustomdiscardperiod}}[2]\marg{\comment{} |
| 28329 |
\ics{ifglshasshort}\marg{\cs{glslabel}}\comment{} |
| 28330 |
\marg{\comment{} |
| 28331 |
\cs{glsxtrifwasfirstuse}\marg{}\comment{} |
| 28332 |
\marg{\comment{} |
| 28333 |
\cs{GlsXtrIfFieldUndef}\marg{\fielddisp{fieldendpunc}{shortendpunc}}\marg{\cs{glslabel}}\marg{\idx{param}2}\marg{\idx{param}1}\comment{} |
| 28334 |
}\comment{} |
| 28335 |
}\comment{} |
| 28336 |
\marg{\comment{} |
| 28337 |
\cs{GlsXtrIfFieldUndef}\marg{\fielddisp{fieldendpunc}{nameendpunc}}\marg{\cs{glslabel}}\marg{\idx{param}2}\marg{\idx{param}1}\comment{} |
| 28338 |
}\comment{} |
| 28339 |
} |
| 28340 |
\end{codeenv} |
| 28341 |
This first tests if the entry that's just been referenced has a |
| 28342 |
\field{short} field. If it has, then the next test is to check if |
| 28343 |
that was the first use for that entry. If it was, nothing is done. |
| 28344 |
If it wasn't, then \cs{GlsXtrIfFieldUndef} is used to determine |
| 28345 |
if \fielddisp{fieldendpunc}{shortendpunc} has been set. If it has |
| 28346 |
been set then the period discard function is performed. If the |
| 28347 |
entry doesn't have a \field{short} field, then the |
| 28348 |
\fielddisp{fieldendpunc}{nameendpunc} field needs checking instead. |
| 28349 |
|
| 28350 |
Since the document requires \XeLaTeX\ or \LuaLaTeX\ and has some |
| 28351 |
\idx{non-ASCII} characters, it needs \sty{fontspec} and an |
| 28352 |
appropriate font. In this case I've chosen \qt{Linux Libertine O}. |
| 28353 |
If you don't have it installed, you'll need to change it. |
| 28354 |
\begin{verbatim} |
| 28355 |
\usepackage{fontspec} |
| 28356 |
\setmainfont{Linux Libertine O} |
| 28357 |
\end{verbatim} |
| 28358 |
Since it's a multilingual document I also need \isty{polyglossia} |
| 28359 |
with the main language set to \code{english}: |
| 28360 |
\begin{codeenv} |
| 28361 |
\cmd{usepackage}\marg{polyglossia} |
| 28362 |
\ics{setmainlanguage}\oarg{variant=uk}\marg{english} |
| 28363 |
\end{codeenv} |
| 28364 |
Now comes the difficult bit. The document needs to determine what |
| 28365 |
other languages need to be loaded. The \sty{tracklang} package |
| 28366 |
provides a convenient interface when dealing with language tags. |
| 28367 |
This is automatically loaded by \styfmt{glossaries} but I've loaded |
| 28368 |
it here explicitly as a reminder: |
| 28369 |
\begin{verbatim} |
| 28370 |
\usepackage{tracklang} |
| 28371 |
\end{verbatim} |
| 28372 |
Once the \hyperref[sec:resourcesets]{resource file} has been loaded, I need to |
| 28373 |
iterate over all the defined entries and check if the \fieldfmt{translation} |
| 28374 |
field has been set. If it has, then the first language tag in the |
| 28375 |
\fieldfmt{language} field will supply the language, but this needs to be |
| 28376 |
converted from the \idx{IETF} language tag to a language name recognised by |
| 28377 |
\isty{polyglossia}. |
| 28378 |
|
| 28379 |
Iterating over all entries can be done with \ics{forglsentries} |
| 28380 |
but remember that no entries will be defined before \bibgls\ has |
| 28381 |
been run, so this does nothing on the first \LaTeX\ run. |
| 28382 |
\begin{codeenv} |
| 28383 |
\cs{forglsentries}\marg{\cmd{thislabel}}\marg{\comment{} |
| 28384 |
\cs{glsxtrifhasfield}\marg{translation}\marg{\cmd{thislabel}}\comment{} |
| 28385 |
\marg{\comment{} |
| 28386 |
\comment{requires glossaries-extra v1.24} |
| 28387 |
\cs{glsxtrforcsvfield}\marg{\cmd{thislabel}}\marg{language}\marg{\cmd{addfirstlang}}\comment{} |
| 28388 |
}\comment{} |
| 28389 |
\marg{}\comment{} |
| 28390 |
} |
| 28391 |
\end{codeenv} |
| 28392 |
Within the outer (\cs{forglsentries}) \idx{loop}, there's a check |
| 28393 |
for the \fieldfmt{translation} field using \ics{glsxtrifhasfield}. |
| 28394 |
If it's present, then the first element of the \fieldfmt{language} |
| 28395 |
field is required. The simplest way to get this is to use |
| 28396 |
\ics{glsxtrforcsvfield} which iterates over all elements of the |
| 28397 |
given field (\fieldfmt{language} in this case) and break out of the |
| 28398 |
\idx{loop} (with \ics{glsxtrendfor}) once the language has been found. |
| 28399 |
|
| 28400 |
The \idx{handler} function (\csfmt{addfirstlang}) is defined so that it |
| 28401 |
adds the given language tag as a tracked language using |
| 28402 |
\ics{TrackLocale}. This command sets |
| 28403 |
\ics{TrackLangLastTrackedDialect} to the associated |
| 28404 |
(\sty{tracklang}) dialect label for convenience. This dialect label |
| 28405 |
can then be converted to the root language label using |
| 28406 |
\ics{TrackedLanguageFromDialect}. If this language is supported |
| 28407 |
by \isty{polyglossia}, then there should be a file called |
| 28408 |
\metafilefmt{gloss-}{language}{.ldf}. |
| 28409 |
|
| 28410 |
Some of the entries use the same language, so it's necessary to |
| 28411 |
check if the language has already been defined before loading it. |
| 28412 |
There's also a problem in that the language file should not be |
| 28413 |
loaded in a scoped context, but both \ics{glsxtrforcsvfield} |
| 28414 |
and the unstarred \ics{glsxtrifhasfield} add implicit grouping. |
| 28415 |
To solve both problems, an internal \sty{etoolbox} list is |
| 28416 |
defined: |
| 28417 |
\begin{verbatim} |
| 28418 |
\newcommand{\langlist}{}% |
| 28419 |
\end{verbatim} |
| 28420 |
and \ics{xifinlist} is used to first check if the language label is |
| 28421 |
already in the list before adding it. Since this part of the code is |
| 28422 |
scoped, the global \ics{listxadd} is used to add the language label |
| 28423 |
to the list. |
| 28424 |
|
| 28425 |
Next the \field{useri} field is set to |
| 28426 |
\encapdisp{textlanguage}{text\meta{language}} |
| 28427 |
which is the name of the control sequence used with |
| 28428 |
\sty{polyglossia} to switch language for a short block of text. This means that |
| 28429 |
\gls{glsxtrentryfmt}\margm{text} can be used to format \meta{text} |
| 28430 |
in the relevant language. Finally, \ics{glsxtrendfor} is used to |
| 28431 |
break out of the \idx{loop}. |
| 28432 |
\begin{codeenv} |
| 28433 |
\cs{newcommand}*\marg{\cmd{addfirstlang}}[1]\marg{\comment{} |
| 28434 |
\cs{TrackLocale}\marg{\idx{param}1}\comment{} |
| 28435 |
\ics{edef}\cmd{thislanguage}\marg{\comment{} |
| 28436 |
\cs{TrackedLanguageFromDialect}\cs{TrackLangLastTrackedDialect}}\comment{} |
| 28437 |
\ics{IfFileExists}\marg{gloss-\cmd{thislanguage}.ldf}\comment{} |
| 28438 |
\marg{\comment{} |
| 28439 |
\ics{xifinlist}\marg{\cmd{thislanguage}}\marg{\cmd{langlist}}\marg{}\comment{} |
| 28440 |
\marg{\ics{listxadd}\marg{\cmd{langlist}}\marg{\cmd{thislanguage}}}\comment{} |
| 28441 |
\ics{xGlsXtrSetField}\marg{\cmd{thislabel}}\marg{\field{useri}}\marg{\encapdisp{textlanguage}{text\cmd{thislanguage}}}\comment{} |
| 28442 |
\ics{glsxtrendfor} |
| 28443 |
}\comment{} |
| 28444 |
\marg{}\comment{} |
| 28445 |
} |
| 28446 |
\end{codeenv} |
| 28447 |
Once the \ics{forglsentries} \idx{loop} has found the appropriate |
| 28448 |
languages, it's now necessary to iterate over the internal list |
| 28449 |
\csfmt{langlist} and set the language: |
| 28450 |
\begin{codeenv} |
| 28451 |
\ics{forlistloop}\marg{\ics{setotherlanguage}}\marg{\cmd{langlist}} |
| 28452 |
\end{codeenv} |
| 28453 |
The \abbrstyle{long-short-user} style now needs to be adjusted |
| 28454 |
to ensure that it picks up the appropriate language change. |
| 28455 |
By default this style checks the \field{useri} field, so this needs |
| 28456 |
to be changed to \fieldfmt{translation} by redefining |
| 28457 |
\ics{glsxtruserfield}: |
| 28458 |
\begin{codeenv} |
| 28459 |
\cs{renewcommand}*\marg{\cs{glsxtruserfield}}\marg{translation} |
| 28460 |
\end{codeenv} |
| 28461 |
The command that governs the format of the parenthetical material |
| 28462 |
(\ics{glsxtruserparen}) also needs adjusting. I've changed the |
| 28463 |
space before the parenthesis to \ics{cs.space} because some of the |
| 28464 |
long fields end with a \idx{full-stop} and this corrects the |
| 28465 |
spacing. The \fieldfmt{translation} field is in English, |
| 28466 |
so this needs to be encapsulated with \icsdisp{textlanguage}{textenglish} |
| 28467 |
in case the surrounding text is in a different language. |
| 28468 |
\begin{codeenv} |
| 28469 |
\cs{renewcommand}*\marg{\cs{glsxtruserparen}}[2]\marg{\comment{} |
| 28470 |
\cs{cs.space} |
| 28471 |
\cs{glsxtrparen}\marg{\idx{param}1\comment{} |
| 28472 |
\cs{ifglshasfield}\marg{\cs{glsxtruserfield}}\marg{\idx{param}2}\marg{, |
| 28473 |
\csdisp{textlanguage}{textenglish}\marg{\cs{glscurrentfieldvalue}}}\marg{}}\comment{} |
| 28474 |
} |
| 28475 |
\end{codeenv} |
| 28476 |
Next I've defined a convenient command for use in the \catattr{textformat} |
| 28477 |
attributes for the custom \code{tug} category: |
| 28478 |
\begin{codeenv} |
| 28479 |
\cs{newcommand}*\marg{\cmd{tugtextformat}}[1]\marg{\comment{} |
| 28480 |
\cs{glsxtrentryfmt}\marg{\cs{glslabel}}\marg{\idx{param}1}\comment{} |
| 28481 |
} |
| 28482 |
\end{codeenv} |
| 28483 |
This uses \gls{glsxtrentryfmt} to encapsulate the given text |
| 28484 |
in the appropriate language command (if provided). When this is set |
| 28485 |
as the \catattr{textformat} attribute, it will be used instead of |
| 28486 |
\ics{glstextformat}, which means that the entry label can be |
| 28487 |
referenced with \cs{glslabel}. |
| 28488 |
|
| 28489 |
There's a similar command for use in the \catattr{glossnamefont} |
| 28490 |
attribute. This is used in the glossary, so the label is referenced |
| 28491 |
with \cs{glscurrententrylabel}: |
| 28492 |
\begin{codeenv} |
| 28493 |
\cs{newcommand}*\marg{\cmd{tugnameformat}}[1]\marg{\comment{} |
| 28494 |
\cs{glsxtrentryfmt}\marg{\cs{glscurrententrylabel}}\marg{\idx{param}1}\comment{} |
| 28495 |
} |
| 28496 |
\end{codeenv} |
| 28497 |
The attributes can now be set to the relevant control sequence name: |
| 28498 |
\begin{codeenv} |
| 28499 |
\cs{glssetcategoryattribute}\marg{tug}\marg{\catattr{textformat}}\marg{tugtextformat} |
| 28500 |
\cs{glssetcategoryattribute}\marg{tug}\marg{\catattr{glossnamefont}}\marg{tugnameformat} |
| 28501 |
\end{codeenv} |
| 28502 |
|
| 28503 |
The document uses the \glostyle{bookindex} style, which is set in |
| 28504 |
the package options: |
| 28505 |
\begin{codeenv} |
| 28506 |
\cmd{usepackage}\oarg{\styopt{record}, |
| 28507 |
\styopt{nostyles}, |
| 28508 |
\styopt[bookindex]{stylemods}, |
| 28509 |
\styopt[bookindex]{style} |
| 28510 |
}\marg{glossaries-extra} |
| 28511 |
\end{codeenv} |
| 28512 |
The \glostyle{bookindex} style ignores the \field{description} field, so I've |
| 28513 |
provided a \idx{postnamehook} to append it in parentheses (with the |
| 28514 |
translation, if provided): |
| 28515 |
\begin{codeenv} |
| 28516 |
\cs{newcommand}\marg{\postnamehook{tug}}\marg{\comment{} |
| 28517 |
\ics{ifglshasdesc}\marg{\cs{glscurrententrylabel}}\comment{} |
| 28518 |
\marg{\cs{cs.space}(\cs{glossentrydesc}\marg{\cs{glscurrententrylabel}}\comment{} |
| 28519 |
\cs{glsxtrifhasfield}\marg{translation}\marg{\cs{glscurrententrylabel}}\comment{} |
| 28520 |
\marg{, \csdisp{textlanguage}{textenglish}\marg{\cs{glscurrentfieldvalue}}}\comment{} |
| 28521 |
\marg{}\comment{} |
| 28522 |
)}\comment{} |
| 28523 |
\marg{\comment{} |
| 28524 |
\cs{glsxtrifhasfield}\marg{translation}\marg{\cs{glscurrententrylabel}}\comment{} |
| 28525 |
\marg{\cs{cs.space}(\csdisp{textlanguage}{textenglish}\marg{\cs{glscurrentfieldvalue}})}\comment{} |
| 28526 |
\marg{}\comment{} |
| 28527 |
}\comment{} |
| 28528 |
} |
| 28529 |
\end{codeenv} |
| 28530 |
Remember that this hook is included within the \field{name} font |
| 28531 |
(provided by the \catattr{glossnamefont} attribute in this case) |
| 28532 |
so \csdisp{textlanguage}{textenglish} is again used to switch the language to |
| 28533 |
English for the translation. |
| 28534 |
|
| 28535 |
The complete document code is listed below. The document build is: |
| 28536 |
\begin{verbatim} |
| 28537 |
xelatex sample-usergroups |
| 28538 |
bib2gls --group sample-usergroups |
| 28539 |
xelatex sample-usergroups |
| 28540 |
xelatex sample-usergroups |
| 28541 |
\end{verbatim} |
| 28542 |
The two pages of the document are shown in |
| 28543 |
\figureref{fig:sample-usergroups.pdf}. Since the entries have all |
| 28544 |
been referenced on page~1, the \glspl{locationlist} are all simply~\qt{1}. |
| 28545 |
|
| 28546 |
%\lstinputlisting[firstline=5]{../examples/sample-usergroups.tex} |
| 28547 |
\begin{lstlisting}[escapechar=|] |
| 28548 |
\documentclass{scrreprt} |
| 28549 |
|
| 28550 |
\usepackage{fontspec} |
| 28551 |
\setmainfont{Linux Libertine O} |
| 28552 |
|
| 28553 |
\usepackage{polyglossia} |
| 28554 |
\setmainlanguage[variant=uk]{english} |
| 28555 |
\usepackage{tracklang} |
| 28556 |
\usepackage{etoolbox} |
| 28557 |
|
| 28558 |
\usepackage[record,% use bib2gls |
| 28559 |
nostyles,% don't load default styles |
| 28560 |
stylemods={bookindex}, |
| 28561 |
style={bookindex} |
| 28562 |
]{glossaries-extra} |
| 28563 |
|
| 28564 |
\glsaddstoragekey{language}{}{\glsentrylanguage} |
| 28565 |
\glsaddstoragekey{translation}{}{\glsentrytranslation} |
| 28566 |
|
| 28567 |
\setabbreviationstyle[tug]{long-short-user} |
| 28568 |
|
| 28569 |
\GlsXtrLoadResources[ |
| 28570 |
src={usergroups}, % data in usergroups.bib |
| 28571 |
check-end-punctuation={name,short}, |
| 28572 |
category=tug |
| 28573 |
] |
| 28574 |
|
| 28575 |
\renewcommand*{\glsxtrifcustomdiscardperiod}[2]{% |
| 28576 |
\ifglshasshort{\glslabel}% |
| 28577 |
{% |
| 28578 |
\glsxtrifwasfirstuse{}% |
| 28579 |
{% |
| 28580 |
\GlsXtrIfFieldUndef{shortendpunc}{\glslabel}{#2}{#1}% |
| 28581 |
}% |
| 28582 |
}% |
| 28583 |
{% |
| 28584 |
\GlsXtrIfFieldUndef{nameendpunc}{\glslabel}{#2}{#1}% |
| 28585 |
}% |
| 28586 |
} |
| 28587 |
|
| 28588 |
\newcommand{\langlist}{}% |
| 28589 |
|
| 28590 |
\newcommand*{\addfirstlang}[1]{% |
| 28591 |
\TrackLocale{#1}% |
| 28592 |
\edef\thislanguage{% |
| 28593 |
\TrackedLanguageFromDialect\TrackLangLastTrackedDialect}% |
| 28594 |
\IfFileExists{gloss-\thislanguage.ldf}% |
| 28595 |
{% |
| 28596 |
\xifinlist{\thislanguage}{\langlist}{}% |
| 28597 |
{\listxadd{\langlist}{\thislanguage}}% |
| 28598 |
\xGlsXtrSetField{\thislabel}{useri}{text\thislanguage}% |
| 28599 |
\glsxtrendfor |
| 28600 |
}% |
| 28601 |
{}% |
| 28602 |
} |
| 28603 |
|
| 28604 |
\forglsentries{\thislabel}{% |
| 28605 |
\glsxtrifhasfield{translation}{\thislabel}% |
| 28606 |
{% |
| 28607 |
% requires glossaries-extra v1.24 |
| 28608 |
\glsxtrforcsvfield{\thislabel}{language}{\addfirstlang}% |
| 28609 |
}% |
| 28610 |
{}% |
| 28611 |
} |
| 28612 |
|
| 28613 |
\forlistloop{\setotherlanguage}{\langlist} |
| 28614 |
|
| 28615 |
\renewcommand*{\glsxtruserfield}{translation} |
| 28616 |
|
| 28617 |
\renewcommand*{\glsxtruserparen}[2]{% |
| 28618 |
\ |
| 28619 |
\glsxtrparen{#1% |
| 28620 |
\ifglshasfield{\glsxtruserfield}{#2}{, |
| 28621 |
\textenglish{\glscurrentfieldvalue}}{}}% |
| 28622 |
} |
| 28623 |
|
| 28624 |
\newcommand*{\tugtextformat}[1]{% |
| 28625 |
\glsxtrentryfmt{\glslabel}{#1}% |
| 28626 |
} |
| 28627 |
|
| 28628 |
\newcommand*{\tugnameformat}[1]{% |
| 28629 |
\glsxtrentryfmt{\glscurrententrylabel}{#1}% |
| 28630 |
} |
| 28631 |
|
| 28632 |
\glssetcategoryattribute{tug}{textformat}{tugtextformat} |
| 28633 |
\glssetcategoryattribute{tug}{glossnamefont}{tugnameformat} |
| 28634 |
|
| 28635 |
\newcommand{\glsxtrpostnametug}{% |
| 28636 |
\ifglshasdesc{\glscurrententrylabel}% |
| 28637 |
{\ (\glossentrydesc{\glscurrententrylabel}% |
| 28638 |
\glsxtrifhasfield{translation}{\glscurrententrylabel}% |
| 28639 |
{, \textenglish{\glscurrentfieldvalue}}% |
| 28640 |
{}% |
| 28641 |
)}% |
| 28642 |
{% |
| 28643 |
\glsxtrifhasfield{translation}{\glscurrententrylabel}% |
| 28644 |
{\ (\textenglish{\glscurrentfieldvalue})}% |
| 28645 |
{}% |
| 28646 |
}% |
| 28647 |
} |
| 28648 |
|
| 28649 |
\begin{document} |
| 28650 |
\chapter{Sample} |
| 28651 |
\section{First Use} |
| 28652 |
\gls{TUG}. \gls{bgTeX}. \gls{latex-br}. \gls{CTeX}. |
| 28653 |
\gls{CSTUG}. \gls{DANTE}. \gls{DKTUG}. \gls{EUG}. |
| 28654 |
\gls{CervanTeX}. \gls{TirantloTeX}. \gls{GUTenberg}. |
| 28655 |
\gls{UKTUG}. \gls{|\greekmono ɛϕτ|}. \gls{MaTeX}. \gls{ITALIC}. |
| 28656 |
\gls{ÍsTeX}. \gls{GuIT}. \gls{KTS}. \gls{LTVG}. |
| 28657 |
\gls{mxTeX}. \gls{NTG}. \gls{NTUG}. \gls{GUST}. \gls{GUTpt}. |
| 28658 |
\gls{VietTUG}. \gls{LUGSA}. |
| 28659 |
|
| 28660 |
\section{Next Use} |
| 28661 |
|
| 28662 |
\gls{TUG}. \gls{bgTeX}. \gls{latex-br}. \gls{CTeX}. |
| 28663 |
\gls{CSTUG}. \gls{DANTE}. \gls{DKTUG}. \gls{EUG}. |
| 28664 |
\gls{CervanTeX}. \gls{TirantloTeX}. \gls{GUTenberg}. |
| 28665 |
\gls{UKTUG}. \gls{|\greekmono ɛϕτ|}. \gls{MaTeX}. \gls{ITALIC}. |
| 28666 |
\gls{ÍsTeX}. \gls{GuIT}. \gls{KTS}. \gls{LTVG}. |
| 28667 |
\gls{mxTeX}. \gls{NTG}. \gls{NTUG}. \gls{GUST}. \gls{GUTpt}. |
| 28668 |
\gls{VietTUG}. \gls{LUGSA}. |
| 28669 |
|
| 28670 |
\printunsrtglossaries |
| 28671 |
\end{document} |
| 28672 |
\end{lstlisting} |
| 28673 |
|
| 28674 |
\begin{figure} |
| 28675 |
\figcontents |
| 28676 |
{\pdftwocol{../examples/sample-usergroups.pdf}{2}} |
| 28677 |
{\caption{\filefmt{sample-usergroups.pdf}}} |
| 28678 |
{fig:sample-usergroups.pdf} |
| 28679 |
\end{figure} |
| 28680 |
|
| 28681 |
\filesection{sample-multi1.tex} |
| 28682 |
|
| 28683 |
This example uses \exfile{bacteria.bib}, |
| 28684 |
\exfile{markuplanguages.bib}, \exfile{vegetables.bib}, \exfile{minerals.bib}, |
| 28685 |
\exfile{animals.bib}, \exfile{chemicalformula.bib}, |
| 28686 |
\exfile{baseunits.bib} and \exfile{derivedunits.bib}. |
| 28687 |
Since there's one or more UTF-8 character, the document requires |
| 28688 |
UTF-8 support: |
| 28689 |
\begin{verbatim} |
| 28690 |
\usepackage[T1]{fontenc} |
| 28691 |
\usepackage[utf8]{inputenc} |
| 28692 |
\end{verbatim} |
| 28693 |
|
| 28694 |
The aim of this example document is to have a separate glossary |
| 28695 |
(without number lists) for each type of data (bacteria, markup |
| 28696 |
languages, vegetables, minerals, animals, chemical formula, base |
| 28697 |
units and derived units) and also an |
| 28698 |
index listing all referenced entries with number lists as well as |
| 28699 |
aliased entries that haven't explicitly been used but the |
| 28700 |
cross-reference term as been indexed. This requires: |
| 28701 |
\begin{codeenv} |
| 28702 |
\csopt[recorded and deps and see]{selection} |
| 28703 |
\end{codeenv} |
| 28704 |
to ensure the aliased entries are selected. |
| 28705 |
|
| 28706 |
Since I don't need the default \mainglossary\ (I'm providing |
| 28707 |
my own custom glossaries) I've used the \styopt{nomain} option to |
| 28708 |
suppress its automatic creation, but I do want the \code{index} |
| 28709 |
glossary so I've used the \styopt{index} package option. As with the |
| 28710 |
other examples, I've used \styopt{nostyles} to suppress the creation |
| 28711 |
of the default styles and used \styopt{stylemods} to load the |
| 28712 |
particular style packages that I need and use |
| 28713 |
\sty{glossaries-extra-stylemods} to patch them. The index needs to |
| 28714 |
be in an unnumbered chapter, which is the default for book-like |
| 28715 |
styles, but I want the other glossaries in unnumbered sections so |
| 28716 |
I've used the \styopt{section} option. I just need to remember to |
| 28717 |
switch this before displaying the index: |
| 28718 |
\begin{codeenv} |
| 28719 |
\cmd{usepackage}\oarg{\styopt{record},\comment{use bib2gls} |
| 28720 |
\styopt{section},\comment{use \ics{section*} for glossary headings} |
| 28721 |
\styopt{postdot},\comment{insert dot after descriptions in glossaries} |
| 28722 |
\styopt{nomain},\comment{don't create 'main' glossary} |
| 28723 |
\styopt{index},\comment{create 'index' glossary} |
| 28724 |
\styopt{nostyles},\comment{don't load default styles} |
| 28725 |
\comment{load and patch required style packages:} |
| 28726 |
\styopt[list,mcols,tree,bookindex]{stylemods} |
| 28727 |
}\marg{glossaries-extra} |
| 28728 |
\end{codeenv} |
| 28729 |
The remaining glossaries need defining: |
| 28730 |
\begin{codeenv} |
| 28731 |
\cs{newglossary*}\marg{bacteria}\marg{Bacteria} |
| 28732 |
\cs{newglossary*}\marg{markuplanguage}\marg{Markup Languages} |
| 28733 |
\cs{newglossary*}\marg{vegetable}\marg{Vegetables} |
| 28734 |
\cs{newglossary*}\marg{mineral}\marg{Minerals} |
| 28735 |
\cs{newglossary*}\marg{animal}\marg{Animals} |
| 28736 |
\cs{newglossary*}\marg{chemical}\marg{Chemical Formula} |
| 28737 |
\cs{newglossary*}\marg{baseunit}\marg{SI Units} |
| 28738 |
\cs{newglossary*}\marg{derivedunit}\marg{Derived Units} |
| 28739 |
\end{codeenv} |
| 28740 |
As with \exfile{sample-bacteria.tex} and \exfile{sample-markuplanguages.tex} |
| 28741 |
I need to set the abbreviation styles before the abbreviations are |
| 28742 |
defined: |
| 28743 |
\begin{codeenv} |
| 28744 |
\cs{setabbreviationstyle}\oarg{bacteria}\marg{\abbrstyle{long-only-short-only}} |
| 28745 |
\cs{setabbreviationstyle}\oarg{markuplanguage}\marg{\abbrstyle{long-short-desc}} |
| 28746 |
\end{codeenv} |
| 28747 |
Unlike the \exfile{sample-markuplanguages.tex} example, I'm not interested |
| 28748 |
in tagging the initials in this case, but I still want to change the |
| 28749 |
way the \field{name} field is set with the |
| 28750 |
\abbrstyle{long-short-desc} abbreviation style: |
| 28751 |
\begin{codeenv} |
| 28752 |
\cs{renewcommand}*\marg{\cs{glsxtrlongshortdescname}}\marg{\comment{} |
| 28753 |
\cs{protect}\cs{glsabbrvfont}\marg{\cs{the}\cs{glsshorttok}}\cs{space} |
| 28754 |
\cs{glsxtrparen}\marg{\cs{glslongfont}\marg{\cs{the}\cs{glslongtok}}}\comment{} |
| 28755 |
} |
| 28756 |
\end{codeenv} |
| 28757 |
Remember that this also needs to be set before the abbreviations are |
| 28758 |
defined. The \catattr{textformat} and \catattr{glossnamefont} |
| 28759 |
attributes may be set after definition: |
| 28760 |
\begin{codeenv} |
| 28761 |
\cs{newcommand}\marg{\cmd{bacteriafont}}[1]\marg{\cs{emph}\marg{\idx{param}1}} |
| 28762 |
\cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{textformat}}\marg{bacteriafont} |
| 28763 |
\cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{glossnamefont}}\marg{bacteriafont} |
| 28764 |
\end{codeenv} |
| 28765 |
The description font also needs to be set since this will contain |
| 28766 |
the long form: |
| 28767 |
\begin{codeenv} |
| 28768 |
\cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{glossdescfont}}\marg{bacteriafont} |
| 28769 |
\end{codeenv} |
| 28770 |
|
| 28771 |
The \code{markuplanguage} glossary contains descriptions and some |
| 28772 |
long names, so it's better suited to the \glostyle{altlist} style, |
| 28773 |
in which case the descriptions would look better if they started |
| 28774 |
with a capital letter: |
| 28775 |
\begin{codeenv} |
| 28776 |
\cs{glssetcategoryattribute}\marg{markuplanguage}\marg{\catattr{glossdesc}}\marg{firstuc} |
| 28777 |
\end{codeenv} |
| 28778 |
Remember that the \glostyle{altlist} style uses the |
| 28779 |
\env{description} environment, which is governed by the document |
| 28780 |
class (and may be modified by list-related packages). In this case, |
| 28781 |
one of the KOMA-Script classes is used, so the list items are |
| 28782 |
typeset in sans-serif. |
| 28783 |
|
| 28784 |
There are various ways of dealing with the duplicated data in the |
| 28785 |
index, such as using the \csopt{secondary} option or having a |
| 28786 |
separate resource set with a copy \csopt{action}. In this case, I've |
| 28787 |
decided to use a dual entry system. Since the entries aren't defined |
| 28788 |
using any dual types, I've used \csopt{entry-type-aliases} to |
| 28789 |
make \bibgls\ treat them as though they were, and I also need to |
| 28790 |
alias the custom \atentryfmt{chemical}, \atentryfmt{unit} and |
| 28791 |
\atentryfmt{measurement} \glspl{entrytype}: |
| 28792 |
\begin{codeenv} |
| 28793 |
\csopt[ |
| 28794 |
abbreviation=dualindexabbreviation, |
| 28795 |
entry=dualindexentry, |
| 28796 |
symbol=dualindexsymbol, |
| 28797 |
unit=dualindexsymbol, |
| 28798 |
measurement=dualindexsymbol, |
| 28799 |
chemical=dualindexsymbol |
| 28800 |
]{entry-type-aliases} |
| 28801 |
\end{codeenv} |
| 28802 |
Note that I haven't aliased the \atentry{index} types as I only want |
| 28803 |
these in the index and not replicated in a separate glossary. |
| 28804 |
|
| 28805 |
The primary entries for the \atentry{dualindexabbreviation} type |
| 28806 |
ignore the short form. It would be useful to store it. This could be |
| 28807 |
done by copying the \field{short} field with |
| 28808 |
\csopt{replicate-fields}. For example, |
| 28809 |
\csopt[\field{short}=\field{symbol}]{replicate-fields}. However, this will cause the |
| 28810 |
\field{symbol} field to be set for both the primary and dual |
| 28811 |
entries, which will cause an unwanted duplication if the dual |
| 28812 |
entries are displayed using a glossary style that shows the |
| 28813 |
\field{symbol} field. Another field (such as \field{user1}) could be |
| 28814 |
used instead or \gls{bibglsnewdualindexabbreviation} could be |
| 28815 |
defined before \gls{GlsXtrLoadResources}: |
| 28816 |
\begin{codeenv} |
| 28817 |
\cs{newcommand}\marg{\gls{bibglsnewdualindexabbreviation}}[7]\marg{\comment{} |
| 28818 |
\cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\comment{} |
| 28819 |
\field{name}=\marg{\cs{protect}\gls{bibglsuselongfont}\marg{\idx{param}4}\marg{\cs{glscategory}\marg{\idx{param}2}}},\comment{} |
| 28820 |
\field{symbol}=\marg{\cs{protect}\gls{bibglsuseabbrvfont}\marg{\idx{param}5}\marg{\cs{glscategory}\marg{\idx{param}2}}},\comment{} |
| 28821 |
\field{category}=\marg{index},\idx{param}3}\marg{}\comment{} |
| 28822 |
} |
| 28823 |
\end{codeenv} |
| 28824 |
However, this will affect all \atentry{dualindexabbreviation} |
| 28825 |
\glspl{entrytype}, but it's not necessary for the bacteria abbreviations. |
| 28826 |
Instead it's simpler to just keep a record of the dual label so that |
| 28827 |
the short form can be obtained from the dual entry: |
| 28828 |
\begin{codeenv} |
| 28829 |
\csopt{dual-field} |
| 28830 |
\end{codeenv} |
| 28831 |
|
| 28832 |
By default, the \atentry{dualindexabbreviation} \gls{entrytype} falls back on the |
| 28833 |
\field{short} field if the \field{name} is omitted. In this case I |
| 28834 |
want it to fall back on the \field{long} field instead. |
| 28835 |
\begin{codeenv} |
| 28836 |
\csopt[long]{abbreviation-name-fallback} |
| 28837 |
\end{codeenv} |
| 28838 |
Remember that the sort fallback for abbreviations is still \field{short} (but can be |
| 28839 |
changed with \csopt{abbreviation-sort-fallback}), but I've changed |
| 28840 |
the sort fallback for symbols: |
| 28841 |
\begin{codeenv} |
| 28842 |
\csopt[name]{symbol-sort-fallback} |
| 28843 |
\end{codeenv} |
| 28844 |
I also need to alias the custom fields (especially for those in the |
| 28845 |
\exfile{chemicalformula.bib}, \exfile{baseunits.bib} and |
| 28846 |
\exfile{derivedunits.bib} files): |
| 28847 |
\begin{codeenv} |
| 28848 |
\csopt[ |
| 28849 |
\fieldfmt{identifier}=\field{category}, |
| 28850 |
\fieldfmt{formula}=\field{symbol}, |
| 28851 |
\fieldfmt{chemicalname}=\field{name}, |
| 28852 |
\fieldfmt{unitname}=\field{name}, |
| 28853 |
\fieldfmt{unitsymbol}=\field{symbol}, |
| 28854 |
\fieldfmt{measurement}=\field{description} |
| 28855 |
]{field-aliases} |
| 28856 |
\end{codeenv} |
| 28857 |
There's a slight problem here. This ensures that the entries defined |
| 28858 |
in \exfile{chemicalformula.bib} have a \field{name} and |
| 28859 |
\field{symbol} field, which are swapped round for the dual |
| 28860 |
(according to the default \csopt{dual-indexsymbol-map}) but these |
| 28861 |
entries don't have a \field{description} field. Since I'd like to |
| 28862 |
use the \glostyle{mcolalttreegroup} style, this will end up with |
| 28863 |
the odd appearance of the formula (stored in the \field{name} field for the |
| 28864 |
dual) followed by the chemical name (stored in the \field{symbol} |
| 28865 |
field for the dual) in parenthesis. This is the default \meta{name} |
| 28866 |
(\meta{symbol}) \meta{description} format for the style. I've fixed |
| 28867 |
this by locally redefining \ics{glsxtralttreeSymbolDescLocation} for |
| 28868 |
just that glossary: |
| 28869 |
\begin{codeenv} |
| 28870 |
\cs{printunsrtglossary*}\oarg{\printglossopt[chemical]{type},\printglossopt[mcolalttreegroup]{style}} |
| 28871 |
\marg{\comment{} |
| 28872 |
\cs{renewcommand}\cs{glsxtralttreeSymbolDescLocation}[2]\marg{\comment{} |
| 28873 |
\ics{glossentrysymbol}\marg{\idx{param}1}\cs{glspostdescription}\ics{glsxtrAltTreePar} |
| 28874 |
}\comment{} |
| 28875 |
\cs{renewcommand}*\marg{\cs{glstreenamefmt}}[1]\marg{\idx{param}1}\comment{} |
| 28876 |
\cs{renewcommand}*\marg{\cs{glstreegroupheaderfmt}}[1]\marg{\cs{textbf}\marg{\idx{param}1}}\comment{} |
| 28877 |
} |
| 28878 |
\end{codeenv} |
| 28879 |
I've also redefined \cs{glstreenamefmt} to prevent the names |
| 28880 |
appearing in bold, which means I also need to redefine |
| 28881 |
\cs{glstreegroupheaderfmt} to keep the headers bold. |
| 28882 |
|
| 28883 |
All the \atentryfmt{dualindex\meta{type}} \glspl{entrytype} provide a primary |
| 28884 |
entry that behaves like \atentry{index}. The secondary behaves like |
| 28885 |
\atentryfmt{\meta{type}}. This means that the primaries are |
| 28886 |
conveniently gathered together with all the unaliased \atentry{index} |
| 28887 |
entries, so the primary \gls{entrytype} needs to be set to \code{index}: |
| 28888 |
\begin{codeenv} |
| 28889 |
\csopt[index]{type} |
| 28890 |
\end{codeenv} |
| 28891 |
The dual \gls{entrytype} depends on the entry's category. Since I've |
| 28892 |
defined my custom glossaries with a label that matches the |
| 28893 |
custom \fieldfmt{identifier} field, I can both alias this custom field |
| 28894 |
to the \field{category} field and also set \csopt{dual-type} so that |
| 28895 |
it matches the category: |
| 28896 |
\begin{codeenv} |
| 28897 |
\csopt[\fieldfmt{identifier}=\field{category}]{field-aliases}, |
| 28898 |
\csopt[same as category]{dual-type} |
| 28899 |
\end{codeenv} |
| 28900 |
The primary entries (in the \code{index} glossary) need to be sorted |
| 28901 |
alphabetically, and since the document is in English I'm sorting |
| 28902 |
according to that language (identified by the language code |
| 28903 |
\code{en}), but I also want to make sure that all the primary |
| 28904 |
entries are sorted by the \field{name} field to avoid discrepancies |
| 28905 |
in the fallback value for the \field{sort} field: |
| 28906 |
\begin{codeenv} |
| 28907 |
\csopt[en]{sort}, |
| 28908 |
\csopt[name]{sort-field} |
| 28909 |
\end{codeenv} |
| 28910 |
With \csopt[long]{abbreviation-name-fallback} now set, |
| 28911 |
this means that \emph{Coxiella burnetii} comes after |
| 28912 |
\emph{Clostridium tetani} in the index. I haven't changed the sort |
| 28913 |
field for the dual entries, so in that case the |
| 28914 |
\csopt{abbreviation-sort-fallback} and \csopt{symbol-sort-fallback} |
| 28915 |
settings will be used with the duals. This means that |
| 28916 |
\emph{C.\ burnetii} is between \emph{C.\ botulinum} and \emph{C.\ |
| 28917 |
perfringens} rather than after \emph{C.\ tetani}. |
| 28918 |
|
| 28919 |
I'd like to sort the dual entries according to a letter-number rule |
| 28920 |
(as for the above \exfile{sample-chemical.tex} and \exfile{sample-units3.tex} |
| 28921 |
examples) |
| 28922 |
but this would order \qt{b\'ilinite} after \qt{biotite} in the |
| 28923 |
\code{minerals} glossary, so instead I'm also using the English sort |
| 28924 |
rule for the duals, but with the numbers padded: |
| 28925 |
\begin{codeenv} |
| 28926 |
\csopt[en]{dual-sort}, |
| 28927 |
\csopt[2]{dual-sort-number-pad}, |
| 28928 |
\end{codeenv} |
| 28929 |
This method doesn't work as well as the method used in |
| 28930 |
\exfile{sample-chemical.tex} as it doesn't separate the capitals, |
| 28931 |
digits and \idx!{lowercase} characters in the way that can be achieved with the |
| 28932 |
letter-number methods. An improvement can be made by changing the |
| 28933 |
break-points. I could use \csopt[upper-upper]{dual-break-at} but |
| 28934 |
this would put \qt{seal} before \qt{sea lion} in the \code{animal} |
| 28935 |
glossary, so instead I've used: |
| 28936 |
\begin{codeenv} |
| 28937 |
\csopt[upper-upper-word]{dual-break-at} |
| 28938 |
\end{codeenv} |
| 28939 |
This now puts \qt{sea lion} before \qt{seal}. Unfortunately the word |
| 28940 |
break points will cause a break at the markers used to indicate |
| 28941 |
positive and negative numbers that are inserted with |
| 28942 |
\csopt{dual-sort-number-pad}, so these need to be changed to |
| 28943 |
something that won't cause them to be discarded: |
| 28944 |
\begin{codeenv} |
| 28945 |
\csopt[0]{dual-sort-pad-minus}, |
| 28946 |
\csopt[1]{dual-sort-pad-plus} |
| 28947 |
\end{codeenv} |
| 28948 |
|
| 28949 |
The document loads \sty{hyperref} which means that all the \cs{gls} |
| 28950 |
references will create hyperlinks. Since the primaries are in the |
| 28951 |
index, the default prefixes mean that, for example, |
| 28952 |
\code{\cs{gls}\marg{svg}} links to the \qt{scalable vector graphics} item in |
| 28953 |
the index rather than to the abbreviation \qt{SVG} in the |
| 28954 |
\code{markuplanguage} glossary. There are two alternatives: change |
| 28955 |
\code{\cs{gls}\marg{svg}} to \code{\cs{gls}\marg{dual.svg}} or change the |
| 28956 |
default prefixes, which is the more convenient approach and is the one used |
| 28957 |
here: |
| 28958 |
\begin{codeenv} |
| 28959 |
\csopt[idx.]{label-prefix}, |
| 28960 |
\csopt[\empty]{dual-prefix} |
| 28961 |
\end{codeenv} |
| 28962 |
Now \code{\cs{gls}\marg{svg}} refers to the dual abbreviation \qt{SVG} and |
| 28963 |
\code{\cs{gls}\marg{idx.svg}} refers to the primary entry \qt{scalable vector |
| 28964 |
graphics}. Unfortunately this means that the records created with |
| 28965 |
\code{\cs{gls}\marg{svg}} now refer to the dual abbreviation and will end up |
| 28966 |
being displayed in the glossary instead of the index. This can be |
| 28967 |
fixed with: |
| 28968 |
\begin{codeenv} |
| 28969 |
\csopt[primary]{combine-dual-locations} |
| 28970 |
\end{codeenv} |
| 28971 |
Which transfers the dual entry \glspl{location} to the corresponding |
| 28972 |
primary. |
| 28973 |
|
| 28974 |
The other problem is the cross-references in the \field{description} |
| 28975 |
fields. Since the labels don't start with \qt{\idprefix{dual}} \bibgls\ |
| 28976 |
will assume they refer to the primary entries, which means that |
| 28977 |
\qt{\idprefixfmt{idx}} (the value of \csopt{label-prefix}) will be |
| 28978 |
inserted. This means that they'll link to the index rather than the |
| 28979 |
glossary entry. It also means that the cross-references where the |
| 28980 |
dual is an abbreviation won't behave like an abbreviation as the |
| 28981 |
reference is to the primary (non-abbreviation) entry. This can be |
| 28982 |
fixed by setting \csopt{cs-label-prefix} to the same value as |
| 28983 |
\csopt{dual-prefix}: |
| 28984 |
\begin{codeenv} |
| 28985 |
\csopt[\empty]{cs-label-prefix} |
| 28986 |
\end{codeenv} |
| 28987 |
The index is displayed using the \glostyle{bookindex} style. This |
| 28988 |
doesn't show the description or symbol by default, but it would be |
| 28989 |
useful to include the symbol in parentheses after the name. This can |
| 28990 |
be done by redefining \ics{glsxtrbookindexname}: |
| 28991 |
\begin{codeenv} |
| 28992 |
\cs{renewcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\comment{} |
| 28993 |
\cs{glossentryname}\marg{\idx{param}1}\comment{} |
| 28994 |
\cs{ifglshassymbol}\marg{\idx{param}1}\marg{\cs{space}(\cs{glossentrysymbol}\marg{\idx{param}1})}\marg{}\comment{} |
| 28995 |
} |
| 28996 |
\end{codeenv} |
| 28997 |
However the chemical forumlae look a little odd in parentheses |
| 28998 |
(especially those that contain parenthetical parts) but this can be |
| 28999 |
fixed by adding a category check: |
| 29000 |
\begin{codeenv} |
| 29001 |
\cs{renewcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\comment{} |
| 29002 |
\cs{glossentryname}\marg{\idx{param}1}\comment{} |
| 29003 |
\cs{ifglshassymbol}\marg{\idx{param}1}\comment{} |
| 29004 |
\marg{\comment{} |
| 29005 |
\cs{glsifcategory}\marg{\idx{param}1}\marg{chemical}\comment{} |
| 29006 |
\marg{, \cs{glossentrysymbol}\marg{\idx{param}1}}\comment{} |
| 29007 |
\marg{\cs{space}(\cs{glossentrysymbol}\marg{\idx{param}1})}\comment{} |
| 29008 |
}\comment{} |
| 29009 |
\marg{}\comment{} |
| 29010 |
} |
| 29011 |
\end{codeenv} |
| 29012 |
Unfortunately \ics{glossentrysymbol} doesn't pick up the |
| 29013 |
\catattr{glossnamefont} attribute, so if the short form of the |
| 29014 |
abbreviations is saved in the \field{symbol} field, using one of the |
| 29015 |
methods discussed above, then the custom \csfmt{bacteriafont} won't |
| 29016 |
be applied. (As from \sty{glossaries-extra} version 1.42, there is |
| 29017 |
now the \catattr{glosssymbolfont} attribute that's used by |
| 29018 |
\ics{glossentrysymbol}.) |
| 29019 |
|
| 29020 |
A simple solution is to use \ics{glossentrynameother} instead: |
| 29021 |
\begin{codeenv} |
| 29022 |
\cs{renewcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\comment{} |
| 29023 |
\cs{glossentryname}\marg{\idx{param}1}\comment{} |
| 29024 |
\cs{ifglshassymbol}\marg{\idx{param}1}\comment{} |
| 29025 |
\marg{\comment{} |
| 29026 |
\cs{glsifcategory}\marg{\idx{param}1}\marg{chemical}\comment{} |
| 29027 |
\marg{, \cs{glossentrysymbol}\marg{\idx{param}1}}\comment{} |
| 29028 |
\marg{\cs{space}(\cs{glossentrynameother}\marg{\idx{param}1}\marg{\field{symbol}})}\comment{} |
| 29029 |
}\comment{} |
| 29030 |
\marg{}\comment{} |
| 29031 |
} |
| 29032 |
\end{codeenv} |
| 29033 |
However, since I decided not to store the short form in the |
| 29034 |
\field{symbol} field and just saved the dual entry label instead, I |
| 29035 |
need to lookup the short form from the dual entry: |
| 29036 |
\begin{codeenv} |
| 29037 |
\cs{renewcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\comment{} |
| 29038 |
\cs{glossentryname}\marg{\idx{param}1}\comment{} |
| 29039 |
\cs{ifglshassymbol}\marg{\idx{param}1}\comment{} |
| 29040 |
\marg{\comment{} |
| 29041 |
\cs{glsifcategory}\marg{\idx{param}1}\marg{chemical}\comment{} |
| 29042 |
\marg{, \ics{glossentrysymbol}\marg{\idx{param}1}}\comment{} |
| 29043 |
\marg{\cs{space}(\ics{glossentrynameother}\marg{\idx{param}1}\marg{\field{symbol}})}\comment{} |
| 29044 |
}\comment{} |
| 29045 |
\marg{\comment{} |
| 29046 |
\cs{glsifcategory}\marg{\idx{param}1}\marg{markuplanguage}\comment{} |
| 29047 |
\marg{\comment{} |
| 29048 |
\cs{glsxtrifhasfield}\marg{\field{short}}\marg{\cs{glsxtrusefield}\marg{\idx{param}1}\marg{\field{dual}}}\comment{} |
| 29049 |
\marg{\cs{space}(\cs{glscurrentfieldvalue})}\comment{} |
| 29050 |
\marg{}\comment{} |
| 29051 |
}\comment{} |
| 29052 |
\marg{}\comment{} |
| 29053 |
}\comment{} |
| 29054 |
} |
| 29055 |
\end{codeenv} |
| 29056 |
Not all of the markup languages are abbreviations so this uses |
| 29057 |
\ics{glsxtrifhasfield} to check if the \field{short} field is set. |
| 29058 |
The dual entry's label is easily obtained because \csopt{dual-field} |
| 29059 |
has provided the \fieldfmt{dual} internal field and set it to the |
| 29060 |
corresponding label. |
| 29061 |
|
| 29062 |
It's sometimes useful for the index to include a reference to the |
| 29063 |
term's definition. This can be done by making use of |
| 29064 |
\idx{glsextrapostnamehook}, which can be redefined before the |
| 29065 |
glossaries to automatically record each entry: |
| 29066 |
\begin{codeenv} |
| 29067 |
\cs{renewcommand}\marg{\cs{glsextrapostnamehook}}[1]\marg{\cs{glsadd}\oarg{\glsaddopt[\encap{hyperbf}]{format}}\marg{\idx{param}1}} |
| 29068 |
\end{codeenv} |
| 29069 |
This needs to be redefined to ignore its argument before the index, |
| 29070 |
to avoid the redundant index record: |
| 29071 |
\begin{codeenv} |
| 29072 |
\cs{renewcommand}\marg{\cs{glsextrapostnamehook}}[1]\marg{} |
| 29073 |
\end{codeenv} |
| 29074 |
Remember that if any records are added within a glossary, an extra |
| 29075 |
\LaTeX\ and \bibgls\ call are required to ensure that the \gls{locationlist} |
| 29076 |
is correct, so the document build is: |
| 29077 |
\begin{verbatim} |
| 29078 |
pdflatex sample-multi1 |
| 29079 |
bib2gls --group sample-multi1 |
| 29080 |
pdflatex sample-multi1 |
| 29081 |
bib2gls --group sample-multi1 |
| 29082 |
pdflatex sample-multi1 |
| 29083 |
\end{verbatim} |
| 29084 |
The complete document code is listed below. |
| 29085 |
The resulting document is shown in \figureref{fig:sample-multi1.pdf} |
| 29086 |
and \figureref{fig:sample-multi1.pdf2}. |
| 29087 |
|
| 29088 |
\lstinputlisting[firstline=5]{../examples/sample-multi1.tex} |
| 29089 |
|
| 29090 |
\begin{figure} |
| 29091 |
\figcontents |
| 29092 |
{\pdftwocol{../examples/sample-multi1.pdf}{4}} |
| 29093 |
{\caption{\filefmt{sample-multi1.pdf} (pages~1 to~4)}} |
| 29094 |
{fig:sample-multi1.pdf} |
| 29095 |
\end{figure} |
| 29096 |
|
| 29097 |
\begin{figure} |
| 29098 |
\figcontents |
| 29099 |
{\pdftwocol[5]{../examples/sample-multi1.pdf}{8}} |
| 29100 |
{\caption{\filefmt{sample-multi1.pdf} (pages~5 to 8)}} |
| 29101 |
{fig:sample-multi1.pdf2} |
| 29102 |
\end{figure} |
| 29103 |
|
| 29104 |
\filesection{sample-multi2.tex} |
| 29105 |
|
| 29106 |
This example is an alternative approach to |
| 29107 |
\exfile{sample-multi1.tex}. Instead of using dual \glspl{entrytype} to |
| 29108 |
define entries that appear in both a glossary and the index, this |
| 29109 |
example makes use of \csopt{record-label-prefix} to reselect the |
| 29110 |
recorded entries for the index. This is more complicated but it |
| 29111 |
allows the entries that have natural word ordering to use a locale |
| 29112 |
sort method while the entries that are symbolic can use one of the |
| 29113 |
letter-number sort methods. |
| 29114 |
|
| 29115 |
This document uses some additional \ext{bib} files to the previous |
| 29116 |
example, so it has extra glossaries, which all need to be defined: |
| 29117 |
\begin{codeenv} |
| 29118 |
\cs{newglossary*}\marg{bacteria}\marg{Bacteria} |
| 29119 |
\cs{newglossary*}\marg{markuplanguage}\marg{Markup Languages} |
| 29120 |
\cs{newglossary*}\marg{vegetable}\marg{Vegetables} |
| 29121 |
\cs{newglossary*}\marg{mineral}\marg{Minerals} |
| 29122 |
\cs{newglossary*}\marg{animal}\marg{Animals} |
| 29123 |
\cs{newglossary*}\marg{chemical}\marg{Chemical Formula} |
| 29124 |
\cs{newglossary*}\marg{baseunit}\marg{SI Units} |
| 29125 |
\cs{newglossary*}\marg{measurement}\marg{Measurements} |
| 29126 |
\cs{newglossary*}\marg{film}\marg{Films} |
| 29127 |
\cs{newglossary*}\marg{book}\marg{Books} |
| 29128 |
\cs{newglossary*}\marg{person}\marg{People} |
| 29129 |
\cs{newglossary*}\marg{mediacontrol}\marg{Media Control Symbols} |
| 29130 |
\cs{newglossary*}\marg{information}\marg{Information Symbols} |
| 29131 |
\cs{newglossary*}\marg{weather}\marg{Weather Symbols} |
| 29132 |
\end{codeenv} |
| 29133 |
Note that this is a total of 15~glossaries (including the |
| 29134 |
\code{index}). With the basic \ics{cs.makeglossaries} method, this would |
| 29135 |
require 16 write registers (including the write register used to |
| 29136 |
create the indexing style file), and a total of $15\times3 + 1 = 46$ |
| 29137 |
associated files. (This doesn't include the standard \ext{aux} file |
| 29138 |
or the \iext{out} file created by \sty{hyperref}.) With \bibgls, no |
| 29139 |
additional write registers are required and the number of associated |
| 29140 |
\bibgls\ files is equal to the number of resource commands plus the |
| 29141 |
transcript file (in this example, $9+1=10$). |
| 29142 |
|
| 29143 |
Since this document requires \exfile!{people.bib}, \exfile!{books.bib} |
| 29144 |
and \exfile!{films.bib} it also requires the files that |
| 29145 |
supply the definitions of the custom commands |
| 29146 |
(\exfile!{no-interpret-preamble.bib} and either |
| 29147 |
\exfile!{interpret-preamble.bib} or \exfile!{interpret-preamble2.bib}) |
| 29148 |
to ensure the custom commands are provided both for the document and |
| 29149 |
for \bibgls's interpreter. |
| 29150 |
|
| 29151 |
The first resource set to be loaded simply reads |
| 29152 |
\exfile{no-interpret-preamble.bib} with the preamble interpreter |
| 29153 |
switched off: |
| 29154 |
\begin{codeenv} |
| 29155 |
\gls{GlsXtrLoadResources}\oarg{ |
| 29156 |
\csopt[no-interpret-preamble]{src}, |
| 29157 |
\csopt[false]{interpret-preamble} |
| 29158 |
} |
| 29159 |
\end{codeenv} |
| 29160 |
This ensures that \LaTeX\ can pick up the provided commands and |
| 29161 |
prevents them from being added to the interpreter. |
| 29162 |
|
| 29163 |
The \exfile{people.bib} file is the next to be loaded with |
| 29164 |
\exfile{interpret-preamble.bib}. This is loaded separately from the |
| 29165 |
other resources as this needs the \field{name} field to be copied to |
| 29166 |
\field{first} (if not already set), as in the |
| 29167 |
\exfile{sample-people.tex} file. By having a separate resource set, |
| 29168 |
this setting doesn't affect the other entries. I've also converted |
| 29169 |
the date fields so that I can customise the format in the document. |
| 29170 |
\begin{codeenv} |
| 29171 |
\gls{GlsXtrLoadResources}\oarg{ |
| 29172 |
\csopt[interpret-preamble,people]{src}, |
| 29173 |
\csopt[ |
| 29174 |
\fieldfmt{identifier}=\field{category}, |
| 29175 |
\fieldfmt{born}=\field{user1}, |
| 29176 |
\fieldfmt{died}=\field{user2}, |
| 29177 |
\fieldfmt{othername}=\field{user3} |
| 29178 |
]{field-aliases}, |
| 29179 |
\csopt[\field{name}=\marg{\field{first}}]{replicate-fields}, |
| 29180 |
\csopt[person]{type}, |
| 29181 |
\csopt[false]{save-locations} |
| 29182 |
\csopt[\field{user1},\field{user2}]{date-fields}, |
| 29183 |
\csopt[d MMM y G]{date-field-format} |
| 29184 |
} |
| 29185 |
\end{codeenv} |
| 29186 |
As with the \exfile{sample-people.tex} document, I need to use the |
| 29187 |
\longarg{break-space} switch to convert the \idx{nbspchar} to a |
| 29188 |
normal breakable space so that it matches the given format. I've |
| 29189 |
loaded the \sty{datetime2} package:\footnote{The |
| 29190 |
\styoptfmt{en-GB} option to \sty{datetime2} also requires that |
| 29191 |
\styfmt{datetime2-english} must be installed.} |
| 29192 |
\begin{verbatim} |
| 29193 |
\usepackage[en-GB]{datetime2} |
| 29194 |
\end{verbatim} |
| 29195 |
so that I can use \ics{DTMdisplaydate} to adjust the formatting: |
| 29196 |
\begin{codeenv} |
| 29197 |
\cs{newcommand}*\marg{\gls{bibglsdate}}[7]\marg{\cs{DTMdisplaydate}\marg{\idx{param}1}\marg{\idx{param}2}\marg{\idx{param}3}\marg{\idx{param}4}} |
| 29198 |
\end{codeenv} |
| 29199 |
This needs to go before the \idx{resourceset} is loaded. Note that |
| 29200 |
the \styoptfmt{en-GB} option identifies the document locale as |
| 29201 |
\code{en-GB} (since there are no language packages loaded). |
| 29202 |
|
| 29203 |
Note that unlike \exfile{sample-people.tex} which had |
| 29204 |
\csopt[people]{category}, this document obtains the \field{category} field |
| 29205 |
from the custom \fieldfmt{identifier} field, which in this case |
| 29206 |
has the value \code{person}. This means that the category hooks from |
| 29207 |
\exfile{sample-people.tex} need to be renamed to reflect the |
| 29208 |
different category label: |
| 29209 |
\begin{codeenv} |
| 29210 |
\cs{newcommand}*\marg{\postlinkhook{person}}{\comment{} |
| 29211 |
\cs{glsxtrifwasfirstuse} |
| 29212 |
\marg{\comment{} |
| 29213 |
\cs{ifglshasfield}\marg{\field{user3}}\marg{\cs{glslabel}}\comment{} |
| 29214 |
\marg{\cs{space}(\cs{glscurrentfieldvalue})}\comment{} |
| 29215 |
\marg{}\comment{} |
| 29216 |
}\comment{} |
| 29217 |
\marg{}\comment{} |
| 29218 |
} |
| 29219 |
\strut |
| 29220 |
\cs{newcommand}*\marg{\postnamehook{person}}\marg{\comment{} |
| 29221 |
\cs{ifglshasfield}\marg{\field{user3}}\marg{\cs{glscurrententrylabel}}\comment{} |
| 29222 |
\marg{\cs{space}(\cs{glscurrentfieldvalue})}\comment{} |
| 29223 |
\marg{}\comment{} |
| 29224 |
} |
| 29225 |
\strut |
| 29226 |
\cs{newcommand}*\marg{\postdeschook{person}}\marg{\comment{} |
| 29227 |
\cs{ifglshasfield}\marg{\field{user1}}\marg{\cs{glscurrententrylabel}} |
| 29228 |
\marg{\comment{born} |
| 29229 |
\cs{space}(\cs{glscurrentfieldvalue}\cs{comma}-{}-\cs{comma}\comment{} |
| 29230 |
\cs{ifglshasfield}\marg{\field{user2}}\marg{\cs{glscurrententrylabel}} |
| 29231 |
\marg{\comment{died} |
| 29232 |
\cs{glscurrentfieldvalue} |
| 29233 |
}\comment{} |
| 29234 |
\marg{}\comment{} |
| 29235 |
)\comment{} |
| 29236 |
}\comment{} |
| 29237 |
\marg{}\comment{} |
| 29238 |
} |
| 29239 |
\end{codeenv} |
| 29240 |
The other \ext{bib} files that require locale sorting can now be |
| 29241 |
loaded, but remember that the abbreviation style settings must be |
| 29242 |
set first since this resource set includes abbreviations: |
| 29243 |
\begin{codeenv} |
| 29244 |
\cs{setabbreviationstyle}\oarg{bacteria}\marg{\abbrstyle{long-only-short-only}} |
| 29245 |
\cs{setabbreviationstyle}\oarg{markuplanguage}\marg{\abbrstyle{long-short-desc}} |
| 29246 |
\strut |
| 29247 |
\cs{renewcommand}*\marg{\cs{glsxtrlongshortdescname}}\marg{\comment{} |
| 29248 |
\cs{protect}\cs{glsabbrvfont}\marg{\cs{the}\cs{glsshorttok}}\cs{space} |
| 29249 |
\glsxtrparen{\glslongfont{\the\glslongtok}}% |
| 29250 |
} |
| 29251 |
\end{codeenv} |
| 29252 |
Now the resource set can be loaded: |
| 29253 |
\begin{codeenv} |
| 29254 |
\gls{GlsXtrLoadResources}\oarg{ |
| 29255 |
\csopt[bacteria,markuplanguages,vegetables, |
| 29256 |
minerals,animals,books,films]{src}, |
| 29257 |
\csopt[\fieldfmt{identifier}=\field{category}]{field-aliases}, |
| 29258 |
\csopt[same as category]{type}, |
| 29259 |
\csopt[false]{save-locations} |
| 29260 |
} |
| 29261 |
\end{codeenv} |
| 29262 |
The semantic markup command and attributes are as for |
| 29263 |
\exfile{sample-multi1.tex}: |
| 29264 |
\begin{codeenv} |
| 29265 |
\cs{newcommand}\marg{\cmd{bacteriafont}}[1]\marg{\cs{emph}\marg{\idx{param}1}} |
| 29266 |
\cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{textformat}}\marg{bacteriafont} |
| 29267 |
\cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{glossnamefont}}\marg{bacteriafont} |
| 29268 |
\cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{glossdescfont}}\marg{bacteriafont} |
| 29269 |
\cs{glssetcategoryattribute}\marg{markuplanguage}\marg{\catattr{glossdesc}}\marg{firstuc} |
| 29270 |
\end{codeenv} |
| 29271 |
Similarly for the books: |
| 29272 |
\begin{codeenv} |
| 29273 |
\cs{newcommand}\marg{\cmd{bookfont}}[1]\marg{\cs{emph}\marg{\idx{param}1}} |
| 29274 |
\cs{glssetcategoryattribute}\marg{book}\marg{\catattr{textformat}}\marg{bookfont} |
| 29275 |
\cs{glssetcategoryattribute}\marg{book}\marg{\catattr{glossnamefont}}\marg{bookfont} |
| 29276 |
\end{codeenv} |
| 29277 |
(as for \exfile{sample-media.tex}) and for films: |
| 29278 |
\begin{codeenv} |
| 29279 |
\cs{newcommand}\marg{\cmd{filmfont}}[1]\marg{\cs{emph}\marg{\idx{param}1}} |
| 29280 |
\cs{glssetcategoryattribute}\marg{film}\marg{\catattr{textformat}}\marg{filmfont} |
| 29281 |
\cs{glssetcategoryattribute}\marg{film}\marg{\catattr{glossnamefont}}\marg{filmfont} |
| 29282 |
\end{codeenv} |
| 29283 |
|
| 29284 |
Next come the chemical formulae: |
| 29285 |
\begin{codeenv} |
| 29286 |
\gls{GlsXtrLoadResources}\oarg{ |
| 29287 |
\csopt[chemicalformula]{src}, |
| 29288 |
\csopt[chemical=symbol]{entry-type-aliases}, |
| 29289 |
\csopt[ |
| 29290 |
\fieldfmt{identifier}=\field{category}, |
| 29291 |
\fieldfmt{formula}=\field{name}, |
| 29292 |
\fieldfmt{chemicalname}=\field{description} |
| 29293 |
]{field-aliases}, |
| 29294 |
\csopt[chemical]{type}, |
| 29295 |
\csopt{set-widest}, |
| 29296 |
\csopt[letternumber-case]{sort}, |
| 29297 |
\csopt[\field{name}]{symbol-sort-fallback}, |
| 29298 |
\csopt[false]{save-locations} |
| 29299 |
} |
| 29300 |
\end{codeenv} |
| 29301 |
and the \idxpl{SIunit}, which are now combined into a single |
| 29302 |
glossary: |
| 29303 |
\begin{codeenv} |
| 29304 |
\gls{GlsXtrLoadResources}\oarg{ |
| 29305 |
\csopt[baseunits,derivedunits]{src}, |
| 29306 |
\csopt[\fieldfmt{measurement}=\field{symbol},\fieldfmt{unit}=\field{symbol}]{entry-type-aliases}, |
| 29307 |
\csopt[ |
| 29308 |
\fieldfmt{unitname}=\field{description}, |
| 29309 |
\fieldfmt{unitsymbol}=\field{symbol}, |
| 29310 |
\fieldfmt{measurement}=\field{name} |
| 29311 |
]{field-aliases}, |
| 29312 |
\csopt[measurement]{category}, |
| 29313 |
\csopt[measurement]{type}, |
| 29314 |
\csopt{set-widest}, |
| 29315 |
\csopt[\field{name}]{symbol-sort-fallback}, |
| 29316 |
\csopt[false]{save-locations} |
| 29317 |
} |
| 29318 |
\end{codeenv} |
| 29319 |
Here the \field{name} field is obtained from the custom |
| 29320 |
\fieldfmt{measurement} field. Since this contains a word, the |
| 29321 |
default locale sort is appropriate. I've locally redefined |
| 29322 |
\ics{glsxtralttreeSymbolDescLocation} to place the symbol in |
| 29323 |
parentheses after the description: |
| 29324 |
\begin{codeenv} |
| 29325 |
\cs{printunsrtglossary*}\oarg{\printglossopt[measurement]{type},\printglossopt[alttree]{style},\printglossopt{nogroupskip}} |
| 29326 |
\marg{\comment{} |
| 29327 |
\cs{renewcommand}\marg{\cs{glsxtralttreeSymbolDescLocation}}[2]\marg{\comment{} |
| 29328 |
\cs{glossentrydesc}\marg{\idx{param}1}\comment{} |
| 29329 |
\cs{ifglshassymbol}\marg{\idx{param}1}\marg{\cs{space}(\cs{glossentrysymbol}\marg{\idx{param}1})}\marg{}\comment{} |
| 29330 |
\cs{glspostdescription} |
| 29331 |
\cs{glsxtrAltTreePar} |
| 29332 |
}\comment{} |
| 29333 |
} |
| 29334 |
\end{codeenv} |
| 29335 |
|
| 29336 |
The base units are replicated in the \code{baseunit} glossary, this |
| 29337 |
time with the \field{name} field obtained from the custom |
| 29338 |
\fieldfmt{unitsymbol} field. This means that I need to find a way to |
| 29339 |
prevent duplicate labels. The simplest method is to use |
| 29340 |
\csopt{duplicate-label-suffix}: |
| 29341 |
\begin{codeenv} |
| 29342 |
\gls{GlsXtrLoadResources}\oarg{ |
| 29343 |
\csopt[baseunits]{src}, |
| 29344 |
\csopt[unit=symbol]{entry-type-aliases}, |
| 29345 |
\csopt[ |
| 29346 |
\fieldfmt{unitname}=\field{description}, |
| 29347 |
\fieldfmt{unitsymbol}=\field{name} |
| 29348 |
]{field-aliases}, |
| 29349 |
\csopt[measurement]{category}, |
| 29350 |
\csopt[baseunit]{type}, |
| 29351 |
\csopt[.copy]{duplicate-label-suffix}, |
| 29352 |
\csopt[\field{name}]{symbol-sort-fallback}, |
| 29353 |
\csopt[false]{save-locations} |
| 29354 |
} |
| 29355 |
\end{codeenv} |
| 29356 |
I can't use \csopt{set-widest} here as it won't pick up the modified |
| 29357 |
label and will instead use the label from the original entry. |
| 29358 |
Instead I've used \cs{glsFindWidestTopLevelName} to find it: |
| 29359 |
\begin{codeenv} |
| 29360 |
\cs{printunsrtglossary*}\oarg{\printglossopt[baseunit]{type},\printglossopt[alttree]{style},\printglossopt{nogroupskip}} |
| 29361 |
\marg{\comment{} |
| 29362 |
\cs{glsFindWidestTopLevelName}\oarg{baseunit}\comment{} |
| 29363 |
} |
| 29364 |
\end{codeenv} |
| 29365 |
|
| 29366 |
The text symbols from \exfile{miscsymbols.bib} are all loaded in a |
| 29367 |
single \igls{resourceset}, where the \field{type} field can be |
| 29368 |
obtained from the \field{category}, which in turns is obtained from |
| 29369 |
the custom \fieldfmt{identifier} field. Since \bibgls\ doesn't |
| 29370 |
recognise any of the symbol commands, I'm sorting according to the |
| 29371 |
\field{description} field. (Even if \bibgls\ could determine a |
| 29372 |
Unicode value for each of the symbols, sorting by the description |
| 29373 |
makes more sense in this case.) |
| 29374 |
\begin{codeenv} |
| 29375 |
\gls{GlsXtrLoadResources}\oarg{ |
| 29376 |
\csopt[miscsymbols]{src}, |
| 29377 |
\csopt[ |
| 29378 |
\fieldfmt{identifier}=\field{category}, |
| 29379 |
\fieldfmt{icon}=\field{name}, |
| 29380 |
\fieldfmt{icondescription}=\field{description} |
| 29381 |
]{field-aliases}, |
| 29382 |
\csopt[icon=symbol]{entry-type-aliases}, |
| 29383 |
\csopt[same as category]{type}, |
| 29384 |
\csopt[\field{description}]{sort-field}, |
| 29385 |
\csopt[false]{save-locations}, |
| 29386 |
\csopt{set-widest} |
| 29387 |
} |
| 29388 |
\end{codeenv} |
| 29389 |
|
| 29390 |
Finally, all recorded and cross-referenced terms are needed for the |
| 29391 |
index. This includes entries that have already been defined in the |
| 29392 |
earlier \iglspl{resourceset} (so a guard against duplicates is |
| 29393 |
necessary) but it also includes entries from the \exfile{terms.bib} |
| 29394 |
file that haven't yet been dealt with. I'd like the index to start |
| 29395 |
with a \idx{symbolgroup} containing the icons from |
| 29396 |
\exfile{miscsymbols.bib}. This needs to be dealt with separately from |
| 29397 |
the rest of the index to keep them together in a single group: |
| 29398 |
\begin{codeenv} |
| 29399 |
\gls{GlsXtrLoadResources}\oarg{ |
| 29400 |
\csopt[miscsymbols]{src}, |
| 29401 |
\csopt[recorded no deps]{selection}, |
| 29402 |
\csopt[.copy]{duplicate-label-suffix}, |
| 29403 |
\csopt[icon=index]{entry-type-aliases}, |
| 29404 |
\csopt[ |
| 29405 |
\fieldfmt{identifier}=\field{category}, |
| 29406 |
\fieldfmt{icondescription}=\field{symbol}, |
| 29407 |
\fieldfmt{icon}=\field{name} |
| 29408 |
]{field-aliases}, |
| 29409 |
\csopt[index]{type}, |
| 29410 |
\csopt[\field{symbol}]{sort-field}, |
| 29411 |
\csopt[glssymbols]{group} |
| 29412 |
} |
| 29413 |
\end{codeenv} |
| 29414 |
Since I know that there are no \glsdisp{parententry}{parents} or cross-references in this |
| 29415 |
set of entries I've used \csopt[recorded no deps]{selection} to skip |
| 29416 |
the dependency checks. In this \igls{resourceset}, the \field{name} |
| 29417 |
field has the symbol command (obtained from the custom |
| 29418 |
\fieldfmt{icon} field), and the \field{symbol} field has the symbol |
| 29419 |
description (obtained from the custom \fieldfmt{icondescription} |
| 29420 |
field), which is used as the sort field. I've set the \field{group} |
| 29421 |
label to \code{glssymbols}, which keeps all these entries in a |
| 29422 |
single group and the title will be obtained from |
| 29423 |
\ics{glssymbolsgroupname}. |
| 29424 |
|
| 29425 |
Before loading the final \igls{resourceset} \ics{glsxtrlongshortdescname} needs |
| 29426 |
to be changed |
| 29427 |
so that the abbreviations using the \abbrstyle{long-short-desc} |
| 29428 |
style (that is, the abbreviations with the \field{category} set to |
| 29429 |
\code{markuplanguage}) have the \field{name} field set to |
| 29430 |
\meta{long} (\meta{short}): |
| 29431 |
\begin{codeenv} |
| 29432 |
\cs{renewcommand}*\marg{\cs{glsxtrlongshortdescname}}\marg{\comment{} |
| 29433 |
\cs{protect}\cs{glslongfont}\marg{\cs{the}\cs{glslongtok}}\cs{space} |
| 29434 |
\cs{glsxtrparen}\marg{\cs{glsabbrvfont}\marg{\cs{the}\cs{glsshorttok}}}\comment{} |
| 29435 |
} |
| 29436 |
\end{codeenv} |
| 29437 |
The \abbrstyle{long-only-short-only} style has a similar command, |
| 29438 |
but it was only introduced to \sty{glossaries-extra} version 1.25: |
| 29439 |
\begin{codeenv} |
| 29440 |
\cs{renewcommand}*\marg{\ics{glsxtronlyname}}{\comment{} |
| 29441 |
\cs{protect}\cs{glsabbrvonlyfont}\marg{\cs{the}\cs{glslongtok}}\comment{} |
| 29442 |
} |
| 29443 |
\end{codeenv} |
| 29444 |
|
| 29445 |
The abbreviations all need to be sorted according to the long form: |
| 29446 |
\begin{codeenv} |
| 29447 |
\csopt[\field{long}]{abbreviation-sort-fallback} |
| 29448 |
\end{codeenv} |
| 29449 |
The custom \glspl{entrytype} and fields again need to be aliased |
| 29450 |
\begin{codeenv} |
| 29451 |
\csopt[ |
| 29452 |
chemical=index, |
| 29453 |
measurement=entry, |
| 29454 |
unit=dualentry, |
| 29455 |
icon=index |
| 29456 |
]{entry-type-aliases}, |
| 29457 |
\csopt[ |
| 29458 |
\fieldfmt{identifier}=\field{category}, |
| 29459 |
\fieldfmt{formula}=\field{symbol}, |
| 29460 |
\fieldfmt{chemicalname}=\field{name}, |
| 29461 |
\fieldfmt{unitname}=\field{description}, |
| 29462 |
\fieldfmt{unitsymbol}=\field{symbol}, |
| 29463 |
\fieldfmt{measurement}=\field{name}, |
| 29464 |
\fieldfmt{icon}=\field{symbol}, |
| 29465 |
\fieldfmt{icondescription}=\field{name} |
| 29466 |
]{field-aliases} |
| 29467 |
\end{codeenv} |
| 29468 |
The chemical formulae and icons are now defined using |
| 29469 |
\atentry{index} with the \field{name} field set to a word form |
| 29470 |
(chemical name and icon description). This means |
| 29471 |
they're appropriate for alphabetical sorting. (Both \atentry{entry} |
| 29472 |
and \atentry{symbol} require the \field{description} field, which is |
| 29473 |
why I've aliased \atentryfmt{chemical} and \atentryfmt{icon} |
| 29474 |
to \atentry{index} here.) The custom \atentryfmt{measurement} |
| 29475 |
\gls{entrytype} has a \field{description} field (obtained from |
| 29476 |
\fieldfmt{unitname}), so that's aliased to \atentry{entry} as again |
| 29477 |
the \field{name} field is suitable for alphabetical sorting. |
| 29478 |
|
| 29479 |
I've aliased \atentryfmt{unit} to \atentry{dualentry} |
| 29480 |
rather than \atentry{symbol} as I want both the unit name and the |
| 29481 |
measurement in the index and I've combined their \glspl{locationlist}: |
| 29482 |
\begin{codeenv} |
| 29483 |
\csopt[both]{combine-dual-locations} |
| 29484 |
\end{codeenv} |
| 29485 |
Both primary and dual entries need to go in the \code{index} |
| 29486 |
glossary: |
| 29487 |
\begin{codeenv} |
| 29488 |
\csopt[index]{type}, |
| 29489 |
\csopt[index]{dual-type} |
| 29490 |
\end{codeenv} |
| 29491 |
|
| 29492 |
All \ext{bib} files used in the previous \iglspl{resourceset} are needed |
| 29493 |
as well as the \exfile{terms.bib} file: |
| 29494 |
\begin{codeenv} |
| 29495 |
\csopt[terms,bacteria,markuplanguages,vegetables,minerals, |
| 29496 |
animals,chemicalformula,baseunits,derivedunits,people, |
| 29497 |
films,books,miscsymbols]{src} |
| 29498 |
\end{codeenv} |
| 29499 |
but this time I also want to select entries that haven't been |
| 29500 |
recorded but have a cross-reference to a recorded entry: |
| 29501 |
\begin{codeenv} |
| 29502 |
\csopt{selection}[recorded and deps and see] |
| 29503 |
\end{codeenv} |
| 29504 |
Again it's necessary to provide a way to avoid duplicate entry |
| 29505 |
labels, which can be done with |
| 29506 |
\begin{codeenv} |
| 29507 |
\csopt[.copy]{duplicate-label-suffix}, |
| 29508 |
\end{codeenv} |
| 29509 |
as above. However, this will cause the cross-references (from the |
| 29510 |
\field{alias} fields) to link to the glossary rather than the index. |
| 29511 |
This may or may not confuse the reader. For consistency, it may be |
| 29512 |
more suitable to have the cross-reference in the index link to the |
| 29513 |
aliased entry in the index rather than in the glossary. I've |
| 29514 |
therefore instead used: |
| 29515 |
\begin{codeenv} |
| 29516 |
\csopt[idx.]{label-prefix}, |
| 29517 |
\csopt[idx.]{record-label-prefix}, |
| 29518 |
\end{codeenv} |
| 29519 |
This means that the entries defined in \exfile{terms.bib} need to be |
| 29520 |
referenced with this prefix. |
| 29521 |
|
| 29522 |
All instances of \cs{gls} will link to the original entry, so all |
| 29523 |
entries except for those in the \exfile{terms.bib} file will link to |
| 29524 |
the relevant glossary. Those in the \exfile{terms.bib} file will |
| 29525 |
link to the index. It's possible to disable the hyperlinks for those |
| 29526 |
entries, but the reader may find it useful to jump to the index to |
| 29527 |
look up other \glspl{location} for that entry in the document. |
| 29528 |
|
| 29529 |
To deal with the identical book and film titles, I'm again using the |
| 29530 |
\field{category} to resolve identical sort values: |
| 29531 |
\begin{codeenv} |
| 29532 |
\csopt[\field{category}]{identical-sort-action} |
| 29533 |
\end{codeenv} |
| 29534 |
For the people who have a \field{first} field, I've decided that |
| 29535 |
this would be more appropriate for the index as it's more compact |
| 29536 |
than the \field{name}, so here I've done the reverse to earlier and copied the |
| 29537 |
\field{first} field (if supplied) into the \field{name} field, but |
| 29538 |
since the \field{name} field is already provided the override |
| 29539 |
setting needs to be on: |
| 29540 |
\begin{codeenv} |
| 29541 |
\csopt{replicate-override}, |
| 29542 |
\csopt[\field{first}=\field{name}]{replicate-fields} |
| 29543 |
\end{codeenv} |
| 29544 |
As with \exfile{sample-people.tex} I've provided some custom |
| 29545 |
commands to make it easier to locally redefine \gls{sortname} and |
| 29546 |
\gls{sortvonname}: |
| 29547 |
\begin{codeenv} |
| 29548 |
\cs{newcommand}*\marg{\cmd{swaptwo}}[2]\marg{\idx{param}2, \idx{param}1} |
| 29549 |
\cs{newcommand}*\marg{\cmd{swapthree}}[3]\marg{\idx{param}2 \idx{param}3, \idx{param}1} |
| 29550 |
\end{codeenv} |
| 29551 |
I've redefined \ics{glsxtrbookindexname} in a similar manner to |
| 29552 |
\exfile{sample-multi1.tex} but it has some modifications: |
| 29553 |
\begin{codeenv} |
| 29554 |
\cs{renewcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\comment{} |
| 29555 |
\cs{glossentryname}\marg{\idx{param}1}\comment{} |
| 29556 |
\cs{ifglshassymbol}\marg{\idx{param}1}\comment{} |
| 29557 |
\marg{\comment{} |
| 29558 |
\cs{glsifcategory}\marg{\idx{param}1}\marg{chemical}\comment{} |
| 29559 |
\marg{, \cs{glossentrysymbol}\marg{\idx{param}1}}\comment{} |
| 29560 |
\marg{\cs{space}(\cs{glossentrynameother}\marg{\idx{param}1}\marg{\field{symbol}})}\comment{} |
| 29561 |
}\comment{} |
| 29562 |
\marg{\comment{} |
| 29563 |
\cs{glsifcategory}\marg{\idx{param}1}\marg{film}\comment{} |
| 29564 |
\marg{\cs{cs.space}(film)}\comment{} |
| 29565 |
\marg{}\comment{} |
| 29566 |
}\comment{} |
| 29567 |
} |
| 29568 |
\end{codeenv} |
| 29569 |
This appends \qt{(film)} to film names. I've chosen this method |
| 29570 |
rather than using the \idx{postnamehook} as I only want this in the |
| 29571 |
index and not in the list of films. |
| 29572 |
|
| 29573 |
For some of the entries that are referenced in the document, I've |
| 29574 |
appended information in parentheses: |
| 29575 |
\begin{codeenv} |
| 29576 |
\cs{gls}\marg{Al2SO43} (\ics{glsdesc}\marg{Al2SO43}) |
| 29577 |
\end{codeenv} |
| 29578 |
This is all right for odd instances, but if this always needs to be done |
| 29579 |
on first use, then it's better to use the \idx{postlinkhook}, which |
| 29580 |
is what I've done for the icons for comparison: |
| 29581 |
\begin{codeenv} |
| 29582 |
\cs{newcommand}*\marg{\postlinkhook{mediacontrol}}\marg{\comment{} |
| 29583 |
\ics{glsxtrpostlinkAddDescOnFirstUse} |
| 29584 |
} |
| 29585 |
\strut |
| 29586 |
\cs{newcommand}*\marg{\postlinkhook{information}}\marg{\comment{} |
| 29587 |
\cs{glsxtrpostlinkAddDescOnFirstUse} |
| 29588 |
} |
| 29589 |
\strut |
| 29590 |
\cs{newcommand}*\marg{\postlinkhook{weather}}\marg{\comment{} |
| 29591 |
\cs{glsxtrpostlinkAddDescOnFirstUse} |
| 29592 |
} |
| 29593 |
\end{codeenv} |
| 29594 |
|
| 29595 |
I've also provided some custom commands to make it easier to reference |
| 29596 |
entries without worrying about the prefixes: |
| 29597 |
\begin{codeenv} |
| 29598 |
\cs{newcommand}\marg{\csfmt{unit}}\marg{\ics{glssymbol}} |
| 29599 |
\cs{newcommand}\marg{\csfmt{measurement}}\marg{\cs{gls}} |
| 29600 |
\gls{glsxtrnewgls}\marg{film.}\marg{\csfmt{film}} |
| 29601 |
\end{codeenv} |
| 29602 |
|
| 29603 |
As with \exfile{sample-multi1.tex}, it would be useful to include |
| 29604 |
the page where the entries are defined in their corresponding lists. |
| 29605 |
Again this can be done by redefining the general purpose |
| 29606 |
non-category post-name hook \ics{glsextrapostnamehook}: |
| 29607 |
\begin{codeenv} |
| 29608 |
\cs{newcommand}*\marg{\cs{glsextrapostnamehook}}[1]\marg{\comment{} |
| 29609 |
\cs{glsadd}\oarg{\glsaddopt[\encap{hyperbf}]{format}}\marg{\idx{param}1}\comment{} |
| 29610 |
} |
| 29611 |
\end{codeenv} |
| 29612 |
This needs resetting before the index, since it's redundant to |
| 29613 |
record an entry in the index. This will require an extra |
| 29614 |
\bibgls+\LaTeX\ system call as this code can't be performed until |
| 29615 |
the glossaries have been created. |
| 29616 |
|
| 29617 |
The complete document code is listed below. The document build is: |
| 29618 |
\begin{verbatim} |
| 29619 |
pdflatex sample-multi2 |
| 29620 |
bib2gls --group --break-space sample-multi2 |
| 29621 |
pdflatex sample-multi2 |
| 29622 |
bib2gls --group --break-space sample-multi2 |
| 29623 |
pdflatex sample-multi2 |
| 29624 |
\end{verbatim} |
| 29625 |
The resulting document is shown in \figureref{fig:sample-multi2.pdf}, |
| 29626 |
\figureref{fig:sample-multi2.pdf2} and \figureref{fig:sample-multi2.pdf3}. |
| 29627 |
|
| 29628 |
\lstinputlisting[firstline=5]{../examples/sample-multi2.tex} |
| 29629 |
|
| 29630 |
\begin{figure} |
| 29631 |
\figcontents |
| 29632 |
{\pdftwocol{../examples/sample-multi2.pdf}{4}} |
| 29633 |
{\caption{\filefmt{sample-multi2.pdf} (pages~1 to~4)}} |
| 29634 |
{fig:sample-multi2.pdf} |
| 29635 |
\end{figure} |
| 29636 |
|
| 29637 |
\begin{figure} |
| 29638 |
\figcontents |
| 29639 |
{\pdftwocol[5]{../examples/sample-multi2.pdf}{8}} |
| 29640 |
{\caption{\filefmt{sample-multi2.pdf} (pages~5 to 8)}} |
| 29641 |
{fig:sample-multi2.pdf2} |
| 29642 |
\end{figure} |
| 29643 |
|
| 29644 |
\begin{figure} |
| 29645 |
\figcontents |
| 29646 |
{\pdftwocol[9]{../examples/sample-multi2.pdf}{12}} |
| 29647 |
{\caption{\filefmt{sample-multi2.pdf} (pages~9 and 12)}} |
| 29648 |
{fig:sample-multi2.pdf3} |
| 29649 |
\end{figure} |
| 29650 |
|
| 29651 |
\setupglossaries{indexonlyfirst} |
| 29652 |
\printstyoptsummary |
| 29653 |
\printcommandsummary |
| 29654 |
%\printcommandtopic |
| 29655 |
|
| 29656 |
\bibliographystyle{plain} |
| 29657 |
\bibliography{bib2gls-cite} |
| 29658 |
|
| 29659 |
\renewcommand*{\glsxtrbookindexsubname}[1]{% |
| 29660 |
\glsifcategory{#1}{command}% |
| 29661 |
{% |
| 29662 |
\glsxtrifhasfield{useri}{#1}% |
| 29663 |
{\glossentrynameother{#1}{useri}}% |
| 29664 |
{\glossentryname{#1}}% |
| 29665 |
}% |
| 29666 |
{\glossentryname{#1}}% |
| 29667 |
} |
| 29668 |
\newcommand{\locationfont}{\small} |
| 29669 |
\newcommand{\widecrossreffont}{\footnotesize} |
| 29670 |
\newcommand{\ifwidecrossref}[3]{% |
| 29671 |
\dimen0=0pt\relax |
| 29672 |
\glsxtrifhasfield*{see}{#1}% |
| 29673 |
{\settowidth{\dimen0}{\locationfont\glsxtrusesee{#1}}}% |
| 29674 |
{% |
| 29675 |
\glsxtrifhasfield*{seealso}{#1}% |
| 29676 |
{\settowidth{\dimen0}{\locationfont\glsxtruseseealso{#1}}}% |
| 29677 |
{% |
| 29678 |
\glsxtrifhasfield*{alias}{#1}% |
| 29679 |
{\settowidth{\dimen0}{\locationfont\glsxtrusealias{#1}}}% |
| 29680 |
{}% |
| 29681 |
}% |
| 29682 |
}% |
| 29683 |
\ifdim\dimen0>0.4\linewidth #2\else#3\fi |
| 29684 |
} |
| 29685 |
\newcommand{\precrossref}{} |
| 29686 |
\newcommand{\indexdotfill}{\,\cleaders\hbox to .44em{\hss\textcolor{lightgray}{.}\hss}\hfill\,} |
| 29687 |
\renewcommand*{\glsxtrbookindexprelocation}[1]{% |
| 29688 |
\glsxtrifhasfield*{location}{#1}% |
| 29689 |
{\nobreak\indexdotfill |
| 29690 |
\ifwidecrossref{#1}% |
| 29691 |
{\def\precrossref{\widecrossreffont\glstreesubitem}}% |
| 29692 |
{\def\precrossref{, }}% |
| 29693 |
}% |
| 29694 |
{% |
| 29695 |
\ifwidecrossref{#1}{\nobreak\def\precrossref{\widecrossreffont\glstreesubitem}}% |
| 29696 |
{\def\precrossref{\nobreak\indexdotfill}}% |
| 29697 |
\glsxtrprelocation |
| 29698 |
}% |
| 29699 |
} |
| 29700 |
\renewcommand{\glsxtrbookindexlocation}[2]{% |
| 29701 |
\begingroup |
| 29702 |
\locationfont |
| 29703 |
#2% |
| 29704 |
\glsxtrifhasfield{see}{#1}{\precrossref\glsxtrusesee{#1}}% |
| 29705 |
{% |
| 29706 |
\glsxtrifhasfield{seealso}{#1}% |
| 29707 |
{\precrossref\glsxtruseseealso{#1}}% |
| 29708 |
{% |
| 29709 |
\glsxtrifhasfield{alias}{#1}{\precrossref\glsxtrusealias{#1}}{}% |
| 29710 |
}% |
| 29711 |
}% |
| 29712 |
\endgroup |
| 29713 |
\let\precrossref\empty |
| 29714 |
} |
| 29715 |
% With \printcommandtopic missing a lot of spawned entries will |
| 29716 |
% appear in the index without a record. Without the topic list they |
| 29717 |
% need to be skipped |
| 29718 |
\renewcommand{\printunsrtglossaryentryprocesshook}[1]{% |
| 29719 |
\glsxtrifhasfield*{progenitor}{#1}% |
| 29720 |
{%\typeout{SKIPPING [has progenitor] #1} |
| 29721 |
\printunsrtglossaryskipentry |
| 29722 |
}% |
| 29723 |
{% |
| 29724 |
\GlsXtrIfFieldEqStr*{originalentrytype}{#1}{topic}% |
| 29725 |
{% |
| 29726 |
\glsxtrifhasfield*{location}{#1}% |
| 29727 |
{}% |
| 29728 |
{% |
| 29729 |
\ifglshasdesc{#1}{}% |
| 29730 |
{% |
| 29731 |
%\typeout{SKIPPING [no location] #1} |
| 29732 |
\printunsrtglossaryskipentry |
| 29733 |
}% |
| 29734 |
}% |
| 29735 |
}% |
| 29736 |
{% |
| 29737 |
\GlsXtrIfFieldValueInCsvList*{#1}{category}% |
| 29738 |
{abbreviationstyle,packageoption,glossarystyle,package}% |
| 29739 |
{% |
| 29740 |
\glsxtrifhasfield*{location}{#1}{}% |
| 29741 |
{%\typeout{SKIPPING [topic \glscategory{#1} no location] #1}% |
| 29742 |
\printunsrtglossaryskipentry |
| 29743 |
}% |
| 29744 |
}% |
| 29745 |
{}% |
| 29746 |
}% |
| 29747 |
}% |
| 29748 |
} |
| 29749 |
\renewcommand*{\unicodecategoryfmt}[1]{\textsf{#1}} |
| 29750 |
\glsrenewcommand*{\bibglspassim}{} |
| 29751 |
\newcommand{\glsxtrpostnamecommand}{% |
| 29752 |
\glsxtrifhasfield{userii}{\glscurrententrylabel}{ (\glscurrentfieldvalue)}{}% |
| 29753 |
} |
| 29754 |
\printunsrtglossary[type=index] |
| 29755 |
\end{document} |