diff options
Diffstat (limited to 'support/bib2gls/src')
-rw-r--r-- | support/bib2gls/src/bib2gls-begin.tex | 6151 | ||||
-rw-r--r-- | support/bib2gls/src/bib2gls-cite.bib | 157 | ||||
-rw-r--r-- | support/bib2gls/src/bib2gls.bib | 16439 | ||||
-rw-r--r-- | support/bib2gls/src/bib2gls.pod | 304 | ||||
-rw-r--r-- | support/bib2gls/src/bib2gls.tex | 22549 | ||||
-rw-r--r-- | support/bib2gls/src/convertgls2bib.pod | 94 |
6 files changed, 45694 insertions, 0 deletions
diff --git a/support/bib2gls/src/bib2gls-begin.tex b/support/bib2gls/src/bib2gls-begin.tex new file mode 100644 index 0000000000..f30604e4ba --- /dev/null +++ b/support/bib2gls/src/bib2gls-begin.tex @@ -0,0 +1,6151 @@ +% arara: lualatex +% arara: bib2gls: {group: on} if missing("glstex") || changed(toFile("bib2gls.bib")) || found("log", "Warning: Glossary entry") +% arara: bibtex +% arara: lualatex if changed("glstex") || missing("toc") +% arara: bib2gls: {group: on} +% arara: lualatex +% arara: lualatex if found ("log", "Rerun") +\documentclass[titlepage=false,fontsize=12pt,captions=tableheading]{scrreprt} + +\usepackage[no-math]{fontspec} +\setmainfont{Linux Libertine O} + +\newfontface\cyrillicmono{FreeMono}[Scale=MatchLowercase] +\newcommand{\textcyrillicmono}[1]{{\cyrillicmono #1}} + +\usepackage[x11names]{xcolor} +\usepackage{upquote} +\usepackage{hologo} +\usepackage{pifont} +\usepackage{graphicx} +\usepackage{tcolorbox} +\usepackage{datetime2} +\usepackage{siunitx} +\usepackage[version=4]{mhchem} + +\usepackage{xr-hyper} +\usepackage[hidelinks]{hyperref} +\usepackage[record, + entrycounter,subentrycounter,%need to define counters for some examples + nostyles,stylemods={bookindex},style=index]{glossaries-extra} + +\setupglossaries{entrycounter=false,subentrycounter=false} + +\definecolor{field}{named}{DarkSlateGray4} +\definecolor{cs}{named}{DarkSeaGreen4} +\definecolor{styopt}{named}{DarkOrchid4} +\definecolor{entry}{named}{SteelBlue4} +\definecolor{comment}{named}{gray} +\definecolor{attribute}{named}{Purple4} +\definecolor{style}{named}{Blue4} + +\newcommand{\extstyopt}{\textsuperscript{\textdagger}} + +\newcommand{\dhyphen}{% + \texorpdfstring + {\discretionary{}{}{}\texttt{-}}% + {-}% +} + +\renewrobustcmd{\-}{% + \discretionary + {{\rmfamily\char\ifnum\hyphenchar\font<0 + \defaulthyphenchar\else\hyphenchar\font\fi + }}% + {}{}% +} + +\setabbreviationstyle[common]{short-nolong} +\setabbreviationstyle[markwordsexample]{long-hyphen-short-hyphen} +\glssetcategoryattribute{markwordsexample}{markwords}{true} +\GlsXtrEnableInitialTagging{taggingexample}{\itag} +\glssetcategoryattribute{discardperiodexample}{discardperiod}{true} +\glssetcategoryattribute{initialism}{insertdots}{true} +\glssetcategoryattribute{initialism}{discardperiod}{true} +\glssetcategoryattribute{initialism}{retainfirstuseperiod}{true} +\setabbreviationstyle[initialism]{short-long} +\setabbreviationstyle[abbrvtrans]{long-short-user} +\setabbreviationstyle[longshortem]{long-short-em} +\setabbreviationstyle[shortsc]{short-sc-nolong} + +\newcommand{\bibglspassim}{} +\newcommand{\bibglsseealsosep}{\par\hangindent .75em\parindent .75em\relax} + +\newcommand*{\csfmt}[1]{% + \texorpdfstring + {\csfmtfont{\char`\\ #1}}% + {\string\\#1}% +} + +\newcommand*{\csref}{\gls} + +\newcommand{\texparserdefnote}{} + +\GlsXtrLoadResources[ + src={bib2gls}, + max-loc-diff=3, + entry-type-aliases={ + exampleentry=entry, + examplesymbol=symbol, + exampleabbreviation=abbreviation + }, + unknown-entry-alias={index}, + field-aliases={note=user2}, + symbol-sort-fallback={name}, + break-at={none}, + sort-replace={{,? +}{|},{\glshex2423}{ }, + {\string\\([a-zA-Z])}{\glscapturedgroup1}, + {([a-zA-Z])\string\.}{\glscapturedgroup1}} +] + +\DTMsavetimestamp{creation}{2017-01-20T15:39:00Z} + +\IfFileExists{../java/Bib2Gls.java} +{ + \DTMsavefilemoddate{moddate}{../java/Bib2Gls.java} +} +{ + \DTMsavenow{moddate} +} + +\newcommand{\bibgls}{\appfmt{bib2gls}} + +\newcommand*{\BibTeX}{\hologo{BibTeX}} +\newcommand*{\eTeX}{\hologo{eTeX}} +\newcommand*{\XeLaTeX}{\hologo{XeLaTeX}} +\newcommand*{\LuaLaTeX}{\hologo{LuaLaTeX}} +\newcommand*{\pdfLaTeX}{\hologo{pdfLaTeX}} + +\newcommand*{\ctanfile}[2]{% + \href{http://mirrors.ctan.org/macros/latex/contrib/#1/#2}{\nolinkurl{#2}}% +} + +\newcommand{\hex}[1]{0x#1} + +\newcommand{\qt}[1]{``#1''} + +\newcommand{\qtt}[1]{\qt{\,\texttt{#1}\,}} + +\newcommand{\incorrect}{\marginpar{\textcolor{red}{\ding{55}}}} +\newcommand{\correct}{\marginpar{\textcolor{green}{\ding{52}}}} + +\newcounter{result} + +\newenvironment{result}% +{% + \renewcommand{\glslinkpresetkeys}{\setkeys{glslink}{hyper=false,local}}% + \glsresetentrycounter + \stepcounter{result}% + \renewcommand{\GlsEntryCounterLabelPrefix}{glsentry\theresult-}% + \begin{quotation}% + \marginpar + [\raisebox{-2.5ex}{\ding{43}}]% + {\raisebox{-2.5ex}{\reflectbox{\ding{43}}}}% + \ignorespaces +} +{\end{quotation}\ignorespacesafterend} + +\newcommand{\dequals}{% + \texorpdfstring + {\discretionary{}{}{}\texttt{=}\discretionary{}{}{}}% + {=}% +} + +\newcommand{\dcomma}{% + \texorpdfstring + {\texttt{,}\discretionary{}{}{}}% + {,}% +} + +\newcommand{\dcolon}{% + \texorpdfstring + {\texttt{:}\discretionary{}{}{}}% + {:}% +} + +\pdfstringdefDisableCommands{% + \def\dhyphen{-}% + \def\dcolon{:}% + \def\dcomma{,}% + \def\dequals{,}% + \let\-\empty +} + +\newcommand*{\csfmtfont}[1]{\texttt{#1}} + +\newcommand*{\appfmt}[1]{\texorpdfstring{\texttt{#1}}{#1}} +\newcommand*{\styfmt}[1]{\texorpdfstring{\textsf{#1}}{#1}} +\newcommand*{\envfmt}[1]{\texorpdfstring{\textsf{#1}}{#1}} +\newcommand*{\optfmt}[1]{\texorpdfstring{\texttt{#1}}{#1}} +\newcommand*{\csoptfmt}[1]{\texorpdfstring{\textcolor{cs}{\optfmt{#1}}}{#1}} +\newcommand*{\styoptfmt}[1]{\texorpdfstring{\textcolor{styopt}{\optfmt{#1}}}{#1}} +\newcommand*{\fieldfmt}[1]{\texorpdfstring{\texttt{\color{field}#1}}{#1}} +\newcommand*{\entryfmt}[1]{\texorpdfstring{\texttt{\color{entry}#1}}{#1}} +\newcommand*{\atentryfmt}[1]{\entryfmt{@#1}} +\newcommand*{\abbrstylefmt}[1]{\texorpdfstring{\textsf{\color{style}#1}}{#1}} +\newcommand*{\glostylefmt}[1]{\texorpdfstring{\textsf{#1}}{#1}} +\newcommand*{\catattrfmt}[1]{\texorpdfstring{\textsf{\color{attribute}#1}}{#1}} +\newcommand*{\counterfmt}[1]{\texorpdfstring{\textsf{#1}}{#1}} +\newcommand*{\filefmt}[1]{\texorpdfstring{\texttt{#1}}{#1}} +\newcommand*{\metafilefmt}[3]{% + \filefmt{#1}\discretionary{}{}{}\meta{#2}\discretionary{}{}{}\filefmt{#3}% +} + +\newcommand*{\extfmt}[1]{\filefmt{.#1}}% + +\newcommand*{\argor}{\texorpdfstring{\protect\textbar}{|}} + +\newrobustcmd*{\texmeta}[1]{{\normalfont\normalcolor$\langle$\emph{#1}$\rangle$}} + +\newcommand*{\meta}[1]{% + \texorpdfstring{\ifmmode\text{\texmeta{#1}}\else\texmeta{#1}\fi}{#1}% +} + +\newcommand*{\oarg}[1]{\discretionary{}{}{}[#1]} +\newcommand*{\oargm}[1]{\oarg{\meta{#1}}} + +\newcommand*{\marg}[1]{\texorpdfstring + {\discretionary{}{}{}\char`\{#1\char`\} }% + {\{#1\}}% +} + +\newcommand*{\margm}[1]{\marg{\meta{#1}}} + +\newcommand{\switcharg}{} +\newcommand{\switchalt}{} + +\makeatletter +\newcommand{\code}[1]{\texorpdfstring{{\ttfamily\obeyspaces #1}}{#1}} +\newcommand{\setupcodeenvfmts}{% + \def\cmd{\char`\\}% + \def\comment##1{\mbox{\textcolor{comment}{\idx{commentchar}\ ##1}}}% + \renewcommand*{\styfmt}[1]{##1}% + \renewcommand*{\counterfmt}[1]{##1}% + \renewcommand*{\catattrfmt}[1]{\textcolor{attribute}{##1}}% + \renewcommand*{\abbrstylefmt}[1]{\textcolor{style}{##1}}% + \renewcommand*{\csfmtfont}[1]{\textcolor{cs}{##1}}% +} +\newenvironment{codeenv} + {% + \renewcommand{\glslinkpresetkeys}{\setkeys{glslink}{noindex}}% + \setupcodeenvfmts + \begin{flushleft}\textcolor{lightgray}{\hrulefill}\par\nopagebreak + \medskip\nopagebreak + \ttfamily\obeylines\frenchspacing\@vobeyspaces} + {\nopagebreak\textcolor{lightgray}{\hrulefill}% + \end{flushleft}\ignorespacesafterend} + +\newenvironment{codeenv*} + {% + \setupcodeenvfmts + \begin{flushleft}\ttfamily\obeylines\frenchspacing\@vobeyspaces + \parindent\z@\parfillskip\@flushglue\parskip\z@skip + } + {\end{flushleft}\ignorespacesafterend} + +\makeatother + +\newcommand{\primary}{\emph} +\newcommand{\primaryloc}[1]{\underline{\hyperbf{#1}}} + +\newcommand{\pidx}[1][]{\gls[textformat=primary,format=primaryloc,#1]} +\newcommand{\pidxpl}[1][]{\glspl[textformat=primary,format=primaryloc,#1]} +\newcommand{\pIdx}[1][]{\Gls[textformat=primary,format=primaryloc,#1]} +\newcommand{\pIdxpl}[1][]{\Glspl[textformat=primary,format=primaryloc,#1]} + +\newcommand{\idx}{\gls} +\newcommand{\idxpl}{\glspl} +\newcommand{\Idx}{\Gls} +\newcommand{\Idxpl}{\Glspl} + +\glsxtrnewgls{ext.}{\ext} + +\newcommand*{\iext}[1]{% + \glsxtrtitleorpdforheading{\idx{ext.#1}}{.#1}{\extfmt{#1}}% +} + +\newcommand{\sty}{\gls} + +\newcommand*{\isty}[1]{% + \texorpdfstring{\idx{#1}}{#1}% +} + +\newcommand*{\env}[1]{% + \texorpdfstring{\idx{env.#1}}{#1}% +} + +\newcommand*{\abbrstyle}[2][]{% + \texorpdfstring{\idx[#1]{abbrstyle.#2}}{#2}% +} + +\newcommand*{\glostyle}[1]{% + \texorpdfstring{\idx{glostyle.#1}}{#1}% +} + +\newcommand*{\catattr}[1]{% + \texorpdfstring{\idx{catattr.#1}}{#1}% +} + +\newcommand*{\counter}[1]{% + \texorpdfstring{\idx{ctr.#1}}{#1}% +} + +\newcommand*{\styopt}[2][]{% + \texorpdfstring% + {% + \gls{styopt.#2}\styoptfmt{\ifblank{#1}{}{\dequals\marg{#1}}}% + }% + {#2\ifblank{#1}{}{=#1}}% +} + +\newcommand*{\keyvallist}{% + \texorpdfstring + {key\dequals value list}% + {key=value list}% +} + +\newcommand{\nosecformatdef}[1]{% + \begin{definition} + \gls[format=primaryloc]{#1}% + \glsentryuseri{#1}% + \end{definition}\ignorespaces +} + +\newcommand*{\cs}{\gls} + +\newcommand*{\ics}[1][]{\cs[noindex=false,#1]} + +\newcommand*{\icswithargs}[2][]{\cs{#2}\glsentryuseri{#2}} + +\newcommand*{\postdeschook}[2][]{% + \glslink[#1]{idx.glsxtrpostdesccategory}{\csfmt{glsxtrpostdesc#2}}} + +\newcommand*{\postlinkhook}[2][]{% + \glslink[#1]{idx.glsxtrpostlinkcategory}{\csfmt{glsxtrpostlink#2}}} + + +\glsxtrnewgls{file.}{\exfile} + +\newcommand*{\csopt}[2][]{\gencsopt{#1}{opt}{#2}}% +\newcommand*{\glsopt}[2][]{\gencsopt{#1}{gls}{#2}}% +\newcommand*{\glsaddopt}[2][]{\gencsopt{#1}{glsadd}{#2}}% +\newcommand*{\printglossopt}[2][]{\gencsopt{#1}{printgloss}{#2}}% + +\newcommand*{\gencsopt}[3]{% + \texorpdfstring% + {% + \gls{#2.#3}% + \csoptfmt{\ifblank{#1}{}{\dequals\marg{#1}}}% + }% + {#3\ifblank{#1}{}{=#1}}% +} + +\newcommand*{\field}[1]{% + \texorpdfstring + {\gls{field.#1}}% + {#1}% +} + +\newcommand*{\atentry}[2][]{% + \texorpdfstring + {\gls[#1]{entry.#2}}% + {#2}% +} + +\newrobustcmd{\longswitch}{\string-{}\string-} + +\newcommand*{\longargfmt}[1]{% + \texorpdfstring{\texttt{\longswitch #1}}% + {\string-\string-#1}% +} + +\newcommand*{\shortargfmt}[1]{% + \texorpdfstring{\texttt{\string-#1}}% + {\string-#1}% +} + +\newcommand*{\longarg}[1]{% + \texorpdfstring + {\gls{switch.#1}}% + {\string-\string-#1}% +} + +\definecolor{defbackground}{rgb}{1,1,0.75} + +\newsavebox\borderedboxcontents +\newlength\borderedboxwidth + +\newenvironment{definition}% +{% + \setlength{\fboxsep}{4pt}\setlength{\fboxrule}{1.25pt}% + \begin{lrbox}{\borderedboxcontents}% + \setlength\borderedboxwidth\linewidth + \addtolength\borderedboxwidth{-2\fboxrule}% + \addtolength\borderedboxwidth{-2\fboxsep}% + \begin{minipage}{\borderedboxwidth} + \flushleft\ttfamily\ignorespaces +}% +{% + \end{minipage}% + \end{lrbox}\par\medskip\noindent + \fcolorbox{black}{defbackground}{\usebox\borderedboxcontents}% + \medskip\par\noindent + \ignorespacesafterend +} + +\newtcolorbox{important}{colback=red!5!white,colframe=red} + +\newcommand*{\sectionref}[1]{section~\ref{#1}} +\newcommand*{\Sectionref}[1]{Section~\ref{#1}} + +\newcommand{\doglossaryentry}[1]{% + \glsxtrglossentry{#1} & \glsentrydesc{#1}\glspostdescription\\% +} +\newcounter{localglossary} +\newenvironment{localglossary} +{% + \stepcounter{localglossary}% + \renewcommand{\glolinkprefix}{\thelocalglossary.}% + \GlsXtrStartUnsetBuffering* +} +{% + \par + \begin{tabular}{ll} + \GlsXtrForUnsetBufferedList\doglossaryentry + \end{tabular} + \GlsXtrStopUnsetBuffering + \par +} +\pagestyle{headings} + +\newcommand{\glossarytitle}{Index} +\externaldocument{bib2gls} + +\newcommand{\addr}[1]{\\\href{https://www.#1/}{\nolinkurl{#1}}} +\title{\styfmt{glossaries-extra} and \bibgls: An Introductory Guide} +\author{Nicola Talbot\addr{dickimaw-books.com}} +\date{\DTMusedate{moddate}} + +\makeatletter +\begingroup + \renewcommand{\addr}[1]{} + \let\texorpdfstring\@secondoftwo + \DTMsetstyle{pdf} + \protected@edef\x{\endgroup + \noexpand\hypersetup{% + pdfinfo={ + Title={\@title}, + Author={\@author}, + CreationDate={\DTMuse{creation}}, + ModDate={\DTMuse{moddate}}, + }% + }% + }\x + +\makeatother + +\begin{document} +\maketitle +\pagenumbering{alph} +\thispagestyle{empty} + +\begin{abstract} +This document is an introductory guide to \bibgls\ and the +\sty{glossaries-extra} package to help you get started. For +further information, including more complex commands and settings, +see the main \bibgls\ user manual (\filefmt{bib2gls.pdf}, +in the same directory as this document), +the \isty{glossaries-extra} user manual, +(distributed with the \sty{glossaries-extra} +package~\cite{glossaries-extra}) +and the \isty{glossaries} user manual +(distributed with the \sty{glossaries} package~\cite{glossaries}). +See also the gallery~\cite{gallery} for examples. + +The \sty{glossaries} package is the \emph{base} package. The +\sty{glossaries-extra} package internally loads the \sty{glossaries} package +and extends it, providing extra options or modifying the base +commands to increase flexibility. If you want to use \bibgls, you +must load \sty{glossaries-extra}, which provides the interface +required by \bibgls. +This document doesn't cover the other indexing methods described in +the base package. If you get an undefined control sequence or +unknown option error when trying out any of the examples here, check +that you are using the latest versions of \sty{glossaries}, +\sty{glossaries-extra} and \bibgls. +\end{abstract} + +\clearpage +\pagenumbering{roman} +\tableofcontents + +\clearpage +\pagenumbering{arabic} + +\chapter{Introduction} +\label{sec:beginintro} + +The \sty{glossaries} package provides a way of defining terms, +notation or abbreviations that can then be used in the document. +This ensures consistent naming and formatting. (With the help of the +\sty{hyperref} package, it's also possible to create hyperlinks from +the reference to a place in the document that provides a definition +of the term, but more about that later.) Each entry (term, +notation or abbreviation) is defined using: +\nosecformatdef{newglossaryentry} +Here's a simple example: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\ics{usepackage}\marg{glossaries} +\strut +\gls{newglossaryentry}\marg{duck}\comment{label} +\marg{\comment{ information about this term:} + \field{name}=\marg{duck},\comment{ display name} + \field{description}=\marg{a waterbird with webbed feet}\comment{description} +} +\strut +\gls{newglossaryentry}\marg{goose}\comment{ label} +\marg{\comment{information about this term:} + \field{name}=\marg{goose},\comment{display name} + \field{plural}=\marg{geese},\comment{plural form} + \field{description}=\marg{a large waterbird with a long neck, short legs, + webbed feet and a short broad bill} +} +\strut +\cmd{begin}\marg{document} +The pond contained a \gls{gls}\marg{duck} (\gls{glsentrydesc}\marg{duck}) and +a \gls{gls}\marg{goose} (\gls{glsentrydesc}\marg{goose}). \gls{Glspl}\marg{duck} and +\gls{glspl}\marg{goose} are fowl. +\cmd{end}\marg{document} +\end{codeenv} +The resulting text is: +\begin{result} +The pond contained a \gls{ex1.duck} (\glsentrydesc{ex1.duck}) and +a \gls{ex1.goose} (\glsentrydesc{ex1.goose}). \Glspl{ex1.duck} and +\glspl{ex1.goose} are fowl. +\end{result} +For convenience, the text produced by commands such as \cs{gls} is called the +\pidx{link-text} (even if there are no hyperlinks). + +The first argument of \gls{newglossaryentry} is a label that +uniquely identifies the term (see \sectionref{sec:labels}). The +second argument is a comma-separated list of +\meta{setting}\dequals\meta{value} assignments. Each \meta{setting} +is referred to as a \qt{key} in the \isty{glossaries} manual or as a +\qt{field} in the \bibgls\ manual. A list of the available base keys +can be found in the \isty{glossaries} user manual. The +\isty{glossaries-extra} package provides some additional keys that +are described in the \sty{glossaries-extra} manual. The \bibgls\ +user manual summarises all keys (fields) in \sectionref{sec:fields}. + +The term \qt{field} not only includes the keys that may be used with +\gls{newglossaryentry} but also internal labels (which may or may +not have a corresponding key) that are used to store information. +Note that there are some fields that may be used in the document +that are considered internal fields by \bibgls\ because the field +value is typically set as a by-product of the way that \bibgls\ +works. If these fields are set manually then you may get unexpected +results as this can break \bibgls's normal operation. + +\begin{important} +If the field value contains commas or equal signs the value must be grouped +to hide those characters from the \meta{key}\dequals\meta{value} parser. +When using \bibgls, the field value must be delimited according to +the \ext{bib} file format. +\end{important} + +The two main keys are \field{name} and \field{description}. The +\field{name} identifies how the term should be displayed in the +glossary (see \sectionref{sec:displaygloss}). It also provides the +default singular term, if not explicitly given. The default plural +is obtained by appending \qt{s} to the singular form. If this isn't +correct (as with \qt{geese}), then the plural form can be specified +with the \field{plural} key. + +The description (set with the \field{description} key) is usually +only displayed in the glossary, but you can display it in the text +using: +\nosecformatdef{glsentrydesc} +as in the above example. This simply expands to the value of the +\field{description} field (or does nothing if there's no entry +associated with the given label). + +The main command used to reference a term is: +\nosecformatdef{gls} +In the above example, \gls{gls} just displays the singular form, but you +can provide alternative text to use the first time a term is +referenced (see \sectionref{sec:firstuse}). The plural form is obtained with +the \pidx{variant} command: +\nosecformatdef{glspl} +There are other \idxpl{variant} of \gls{gls} that perform +\glslink{case-change}{case-changing}. +If you want to start a sentence with an entry then you can use: +\nosecformatdef{Gls} +for the singular form and +\nosecformatdef{Glspl} +for the plural form. For all capitals, use: +\nosecformatdef{GLS} +for the singular form and +\nosecformatdef{GLSpl} +for the plural form. Any mention of \gls{gls} and its +\idxpl{variant} in this guide or in the user manuals means that the +comments applied to \gls{gls} also apply to the plural and +case-changing versions. + +The \meta{insert} optional argument is provided to insert additional material. +For example: +\begin{codeenv} +The \gls{gls}\marg{goose} liked the \gls{gls}\marg{duck}['s] hat. +\end{codeenv} +which produces (assuming the above definitions): +\begin{result} +The \gls{ex1.goose} liked the \gls{ex1.duck}['s] hat. +\end{result} +In some cases, there may not be a noticeable difference between the +above and the following: +\begin{codeenv} +The \gls{gls}\marg{goose} liked the \gls{gls}\marg{duck}'s hat. +\end{codeenv} +It depends on other settings, such as whether or not hyperlinks have +been enabled. (The inserted material is commonly moved inside the +hyperlink.) Take care if you need a literal open square bracket +following \code{\cs{gls}\margm{label}} as you need to prevent it from being +interpreted as the optional \meta{insert} argument. For example: +\begin{codeenv} +The \gls{gls}\marg{goose} liked the \gls{gls}\marg{duck}\marg{['s]} hat. +\end{codeenv} +which now produces: +\begin{result} +The \gls{ex1.goose} liked the \gls{ex1.duck}{['s]} hat. +\end{result} +An alternative in this case could be to define: +\begin{codeenv} +\cmd{newcommand}*\marg{\cmd{missing}}[1]\marg{[\gls*{param}1]} +\end{codeenv} +and then use: +\begin{codeenv} +The \gls{gls}\marg{goose} liked the \gls{gls}\marg{duck}\cmd{missing}\marg{'s} hat. +\end{codeenv} +This conveniently hides the open square bracket from \cs{gls}. + +\begin{important} +Commands like \gls{gls} are \idx{robust}. Commands like +\gls{glsentrydesc} are \idx{expandable}. (See \sectionref{sec:robust}.) +If you want the entry to appear in a PDF bookmark, you need to use an +expandable command to reference it. +\end{important} + +There are some helper commands that internally use +\gls{newglossaryentry}, such as \cs{newabbreviation} (described in +\sectionref{sec:abbreviations}) and \cs{glsxtrnewsymbol} (described +in \sectionref{sec:symbols}). If the description contains explicit paragraph +breaks then: +\nosecformatdef{longnewglossaryentry} +is required instead. + +\section{Labels} +\label{sec:labels} + +The label used to identify the entry can't contain any special characters, such +as \gls{commentchar} (percent), \gls{ampchar} (ampersand), \gls{param} (hash), +\gls{mshiftchar} (dollar), or \gls{nbspchar} (tilde). Be careful of packages +that make other characters active (such as \isty{babel} with its shortcuts). If +you are using \isty{inputenc}, this also includes extended Latin characters and +characters from other scripts. If you want to include UTF-8 characters in the +label then you must use a \TeX\ engine with native Unicode support (that is, +\XeLaTeX\ or \LuaLaTeX). + +For example, with no UTF-8 support (not even \sty{inputenc}): +\begin{codeenv} +\gls{newglossaryentry}\marg{elite}\comment{label (no UTF-8 support)} +\marg{ + \field{name} = \marg{\marg{\gls{acute}e}lite}, + \field{description} = \marg{group of people regarded as + the best of a particular society or organisation} +} +\end{codeenv} +or with \sty{inputenc}: +\begin{codeenv} +\gls{newglossaryentry}\marg{elite}\comment{label (UTF-8 not natively supported)} +\marg{ + \field{name} = \marg{élite}, + \field{description} = \marg{group of people regarded as + the best of a particular society or organisation} +} +\end{codeenv} +Whereas with \XeLaTeX\ or \LuaLaTeX\ you can do: +\begin{codeenv} +\gls{newglossaryentry}\marg{élite}\comment{label (UTF-8 natively supported)} +\marg{ + \field{name} = \marg{élite}, + \field{description} = \marg{group of people regarded as + the best of a particular society or organisation} +} +\end{codeenv} + +You may have noticed the grouping of the initial (accented) letter +in the \gls{ASCII} example (\code{\marg{\gls{acute}e}lite}). This is +necessary to ensure that the first-letter case-changing commands, +such as \ics{Gls}, work. It also used to be required around the +\qtt{é} with \sty{inputenc}, but if you have up-to-date versions of +\sty{glossaries} and \sty{datatool} then it should no longer be +necessary. No special treatment is needed with \XeLaTeX\ or +\LuaLaTeX\ where \qtt{é} is a single token. + +If you can't use extended characters in the label (because you're +not using \XeLaTeX\ or \LuaLaTeX), then simply stripping the accents +to create an \gls{ASCII} alternative may be sufficient, but take +care if this may cause a conflict. For example: +\begin{codeenv} +\gls{newglossaryentry}\marg{resume}\comment{label} +\marg{ + \field{name} = \marg{resume}, + \field{description} = \marg{continue after an interruption} +} +\strut +\gls{newglossaryentry}\marg{resumee}\comment{label} +\marg{ + \field{name} = \marg{r\gls{acute}esum\gls{acute}e}, + \field{description} = \marg{summary of something or curriculum vitae} +} +\end{codeenv} +For languages that use a non-Latin script, if you can't or don't +want to use \XeLaTeX\ or \LuaLaTeX, then you need to decide the most +appropriate \gls{ASCII} naming scheme. +For example: +\begin{codeenv} +\gls{newglossaryentry}\marg{goose}\comment{using translation for label} +\marg{ + \field{name} = \marg{\textcyrillicmono{гусь}}, + \field{plural} = \marg{\textcyrillicmono{гуси}}, + \field{description} = \marg{\textnormal{\ldots}} +} +\end{codeenv} +or +\begin{codeenv} +\gls{newglossaryentry}\marg{hus}\comment{using closest ASCII match for label} +\marg{ + \field{name} = \marg{\textcyrillicmono{гусь}}, + \field{plural} = \marg{\textcyrillicmono{гуси}}, + \field{description} = \marg{\textnormal{\ldots}} +} +\end{codeenv} + +In addition to labels identifying entries, there are also labels +that identify other things, such as a glossary, category or letter +group. The same restrictions apply to those labels. + +\section{First Use} +\label{sec:firstuse} + +Each entry has a \pidx{firstuseflag} (boolean variable) that +determines whether or not the entry has been referenced in the +document. Commands like \gls{gls} and \gls{glspl} change the flag +to indicate that the entry has been used. Commands like +\gls{glsentrydesc} don't. Here's a modification of the earlier +example document that provides different versions depending on +whether or not the entry has already been referenced: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\marg{glossaries} +\strut +\gls{newglossaryentry}\marg{duck}\comment{label} +\marg{\comment{information about this term:} + \field{name} = \marg{Duck (noun)},\comment{display name} + \field{first} = \marg{duck (quack, quack)},\comment{first use singular} + \field{firstplural} = \marg{ducks (quack, quack)},\comment{first use plural} + \field{text} = \marg{duck},\comment{subsequent use singular} + \field{description} = \marg{a waterbird with webbed feet}\comment{description} +} +\strut +\gls{newglossaryentry}\marg{goose}\comment{label} +\marg{\comment{information about this term:} + \field{name} = \marg{Goose (noun, pl.\ geese)},\comment{display name} + \field{first} = \marg{goose (honk, honk)},\comment{first use singular} + \field{firstplural} = \marg{geese (honk, honk)},\comment{first use plural} + \field{text} = \marg{goose},\comment{subsequent use singular} + \field{plural} = \marg{geese},\comment{subsequent use plural} + \field{description}=\marg{a large waterbird with a long neck, short legs, + webbed feet and a short broad bill} +} +\strut +\cmd{begin}\marg{document} +The pond contained a \gls{gls}\marg{duck}\cmd{footnote}\marg{\gls{glsentryname}\marg{duck}: +\gls{glsentrydesc}\marg{duck}} and two +\gls{glspl}\marg{goose}\cmd{footnote}\marg{\gls{glsentryname}\marg{goose}: +\gls{glsentrydesc}\marg{goose}}. \gls{Glspl}\marg{duck} and \gls{glspl}\marg{goose} are fowl. +\cmd{end}\marg{document} +\end{codeenv} +This now produces: +\begin{result} +The pond contained a \gls{ex2.duck}\footnote{\glsentryname{ex2.duck}: +\glsentrydesc{ex2.duck}} and two +\glspl{ex2.goose}\footnote{\glsentryname{ex2.goose}: +\glsentrydesc{ex2.goose}}. \Glspl{ex2.duck} and \glspl{ex2.goose} are fowl. +\end{result} +This uses: +\nosecformatdef{glsentryname} +which works in a similar way to \gls{glsentrydesc}. In this case, +\gls{glsentryname} simply expands to the value of the \field{name} +key. There's also a case-changing version: +\nosecformatdef{Glsentryname} +which changes the initial character to \idx{uppercase}, +but (unlike \cs{glsentryname}) this command isn't expandable. If, +for example, I had instead set the duck's \field{name} key using: +\begin{codeenv} +\field{name} = \marg{duck (noun)} +\end{codeenv} +then I would need to use \code{\gls{Glsentryname}\marg{duck}} +instead. + +So on \pidx{firstuse}, \cs{gls} uses the value of the \field{first} key +and \cs{glspl} uses the value of the \field{firstplural} key. On +\pidx{subsequentuse}, \cs{gls} uses the value of the \field{text} key and +\cs{glspl} uses the value of the \field{plural} key. \pIdx{regular} +abbreviations also follow this usage. \pIdx{non-regular} +abbreviations follow a different behaviour for \gls{gls} (and its +\idxpl{variant}) that's determined by the abbreviation style. + +If the first use for a particular group of terms always has the +same pattern (such as following the term with a brief description or +alternative representation), then it's simpler to use one of the +automated methods provided, such as the abbreviation mechanism +(\sectionref{sec:abbreviations}) or changing the formatting +(\sectionref{sec:glsformats}). + +You can test if an entry has been used with: +\nosecformatdef{ifglsused} +This requires that the entry (identified by \meta{label}) is +defined. If it isn't then neither \meta{true} nor \meta{false} is +done and an error or warning occurs. Otherwise, the command will do +\meta{true} if the entry has been used or \meta{false} if the entry +hasn't been used. + +When using \bibgls, entries are never defined on the first \LaTeX\ +run, so you may instead prefer: +\nosecformatdef{GlsXtrIfUnusedOrUndefined} +which does \meta{true} if either the entry hasn't been defined or +hasn't been marked as used, otherwise it does \meta{false}. + +Neither \gls{ifglsused} nor \gls{GlsXtrIfUnusedOrUndefined} should +occur in the \idx{postlinkhook} (described later) as the entry will have already +been used by that point. Instead, you need \gls{glsxtrifwasfirstuse} +(see \sectionref{sec:postlinkhooks}). + +\section{Categories} +\label{sec:categories} + +The \isty{glossaries-extra} extension package provides the +\field{category} key, which isn't available with just the base +\sty{glossaries} package. The value of this key must be a +label as it's used to construct command names. You can choose +whatever label you like (as long as it conforms to the valid +labelling scheme, described in \sectionref{sec:labels}). If you +don't specify a category, then \gls{newglossaryentry} and +\gls{longnewglossaryentry} assume \code{general}. The helper +commands, such as \gls{newabbreviation}, have different defaults. + +For example: +\begin{codeenv} +\gls{newglossaryentry}\marg{amethyst} +\marg{ + \field{name} = \marg{amethyst}, + \field{description} = \marg{a purple type of quartz}, + \field{category} = \marg{mineral} +} +\end{codeenv} +The value of the \field{category} field for a given entry can be obtained +with: +\nosecformatdef{glscategory} +where \meta{label} identifies the entry. This command is expandable +and does nothing if the entry hasn't been defined. You can test the +value of the \field{category} field using: +\nosecformatdef{glsifcategory} +This checks if the \field{category} field for the entry given by +\meta{label} is set to \meta{category}, but doesn't perform any +expansion of \meta{category}. It generates an error if the entry +doesn't exist (or warning with \styopt[warn]{undefaction}). + +The category allows you to apply certain types of formatting, such +as the \idx{postlinkhook} (\sectionref{sec:postlinkhooks}). +For abbreviations, the category also governs the abbreviation style (see +\sectionref{sec:abbreviations}) and can be used for filtering. +Categories may be assigned \pidxpl{attribute} that can also be used +to modify formatting or styles. + +Unlike the \idx{postlinkhook}, which +needs to be defined before an entry is \emph{used} (with commands like +\gls{gls}), some \idxpl{attribute} need to be set before the entry +is \emph{defined}, so it's best to set them up as soon as possible in the +preamble (after loading \sty{glossaries-extra}). + +\section{Adding Extra Information} +\label{sec:userkeys} + +In addition to the \field{name} and \field{description} keys, +there's also a \field{symbol} key which allows you to store an +associated symbol. The value can be obtained with: +\nosecformatdef{glssymbol} +(which is robust and recognises the \idx{postlinkhook}) or with: +\nosecformatdef{glsentrysymbol} +(which behaves like \gls{glsentrydesc} and \gls{glsentryname}). +Neither of the above commands affect the \idx{firstuseflag}. +For example: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[hidelinks]\marg{hyperref} +\cmd{usepackage}\marg{glossaries} +\strut +\gls{newglossaryentry}\marg{pi}\comment{label} +\marg{\comment{settings:} + \field{name} = \marg{Archimedes' constant}, + \field{symbol} = \marg{\gls[noindex=false]{ensuremath}\marg{\cmd{pi}}}, + \field{description} = \marg{ratio of a circle's circumference to its +diameter} +} +\strut +\gls{newglossaryentry}\marg{thetai}\comment{label} +\marg{\comment{settings:} + \field{name} = \marg{theta parameter}, + \field{symbol} = \marg{\gls{ensuremath}\marg{\cmd{theta}\gls{sbchar}i}}, + \field{description} = \marg{one of the model parameters} +} +\strut +\cmd{begin}\marg{document} +\gls{gls}\marg{pi} (\gls{glssymbol}\marg{pi}). Compare \gls{mshiftchar}\gls{glssymbol}\marg{thetai}\gls[noindex=false]{spchar}2\gls{mshiftchar} +with \gls{mshiftchar}\gls{glssymbol}\marg{thetai}[\gls{spchar}2]\gls{mshiftchar}. +\cmd{end}\marg{document} +\end{codeenv} +This produces: +\begin{result} +\gls{ex.pi} (\glssymbol{ex.pi}). Compare $\glssymbol{ex.thetai}^2$ +with $\glssymbol{ex.thetai}[^2]$. +\end{result} +Note that in this case there is now a difference between using the +final optional \meta{insert} argument and simply appending the extra +material. This is a result of the hyperlink that causes an +interruption between the subscript \code{\gls{sbchar}i} and the following +superscript \code{\gls{spchar}2}. (In this case, there's no target for the +hyperlinks. That's covered in \sectionref{sec:displaygloss}.) + +If you have additional information, such as a translation, +associated image or citation, then you can supply this with the six +user keys: +\field{user1}\glsaddeach{field.user2,field.user3,field.user4,field.user5}, +\ldots, \field{user6}. The value of the +first field (\field{user1}) can be obtained with: +\nosecformatdef{glsuseri} +(which behaves like \gls{glssymbol}) or with: +\nosecformatdef{glsentryuseri} +(which behaves like \gls{glsentrysymbol}). +\glsaddeach{glsuserii,glsuseriii,glsuseriv,glsuserv,% +glsentryuserii,glsentryuseriii,glsentryuseriv,glsentryuserv}% +The other fields are similarly obtained using \idx{lowercase} Roman +numerals, so value of the sixth field (\field{user6}) can be obtained with: +\nosecformatdef{glsuservi} +(which behaves like \gls{glssymbol}) or with: +\nosecformatdef{glsentryuservi} +(which behaves like \gls{glsentrysymbol}). +For example: +\begin{codeenv} +\gls{newglossaryentry}\marg{polly.parrot}\comment{label} +\marg{\comment{} + \field{name} = \marg{Polly Parrot}, + \field{description} = \marg{Senior assistant at the International Society +of Duck and Geese}, + \field{user1} = \marg{British},\comment{nationality} + \field{user2} = \marg{1970-12-31},\comment{date of birth} + \field{user3} = \marg{female},\comment{gender} + \field{user4} = \marg{43 The Lane, Some Town, Noshire AB1 2XY},\comment{address} + \field{user5} = \marg{polly.parrot@example.com}\comment{email} +} +\end{codeenv} + +Alternatively you can define your own custom keys. If you don't need +commands equivalent to \gls{glssymbol}, then you can use: +\nosecformatdef{glsaddstoragekey} +where \meta{key} is the name of the new key, \meta{default value} is +the default value if the key isn't explicitly set and \meta{no link +cs} is the name of the command to access the field value (equivalent +to \gls{glsentrysymbol}). If you want commands equivalent to +\gls{glssymbol} that have the \meta{options} and \meta{insert} +optional arguments and obey the \idx{postlinkhook}, then use +\nosecformatdef{glsaddkey} +The first three arguments are as for \gls{glsaddstoragekey}. +The next argument \meta{no link ucfirst cs} is like \meta{no link +cs} but converts the first letter to \idx{uppercase} (analogous to +\gls{Glsentryname}). The final three commands behave like +\gls{glssymbol}, but \meta{link ucfirst cs} converts the first +letter to \idx{uppercase} and \meta{link allcaps cs} converts the entire +value to \idx{uppercase}. + +The new keys must be provided before the entries are defined (and +the key definitions must come before the first \idx{resourceset} +if you use \bibgls). For example: +\begin{codeenv} +\gls{glsaddstoragekey}\marg{\fieldfmt{nationality}}\marg{}\marg{\cmd{Nationality}} +\gls{glsaddstoragekey}\marg{\fieldfmt{dateofbirth}}\marg{}\marg{\cmd{DateOfBirth}} +\gls{glsaddstoragekey}\marg{\fieldfmt{gender}}\marg{}\marg{\cmd{Gender}} +\gls{glsaddstoragekey}\marg{\fieldfmt{address}}\marg{}\marg{\cmd{Address}} +\gls{glsaddstoragekey}\marg{\fieldfmt{email}}\marg{}\marg{\cmd{Email}} +\gls{newglossaryentry}\marg{polly.parrot}\comment{label} +\marg{\comment{} + \field{name} = \marg{Polly Parrot}, + \field{description} = \marg{Senior assistant at the International Society +of Duck and Geese}, + \fieldfmt{nationality} = \marg{British},\comment{nationality} + \fieldfmt{dateofbirth} = \marg{1970-12-31},\comment{date of birth} + \fieldfmt{gender} = \marg{female},\comment{gender} + \fieldfmt{address} = \marg{43 The Lane, Some Town, Noshire AB1 2XY},\comment{address} + \fieldfmt{email} = \marg{polly.parrot@example.com}\comment{email} +} +\end{codeenv} + +In addition to the commands like \gls{glssymbol} and +\gls{glsentrysymbol}, there are other ways of accessing the field +value or checking if the field has been set. In the commands listed +below, the field label is the \emph{internal} label. In some cases, +this is the same as the key, but there are a few that have a +different internal label. See Table~\ref*{tab:internalfields} in the +\bibgls\ user manual or Table~4.1 in the \sty{glossaries} user +manual~\cite{glossaries}. Custom fields provided with +\gls{glsaddkey} or \gls{glsaddstoragekey} have matching key and +internal field labels. + +The \sty{glossaries-extra} package provides a generic way of +accessing a field, analogous to commands like \gls{glsentryname}: +\nosecformatdef{glsxtrusefield} +This expands to the field value if defined or does nothing if the +entry or field isn't defined. + +The base \sty{glossaries} package provides: +\nosecformatdef{ifglshassymbol} +which tests if the \field{symbol} field has been assigned. There are similar +commands for other common fields. For a more general purpose test, you +can use: +\nosecformatdef{ifglshasfield} +which checks if the given entry (identified by \meta{entry label}, +which must be defined) has the field identified by \meta{field label} +set to a non-empty value. Within \meta{true}, you can access the +field value with: +\nosecformatdef{glscurrentfieldvalue} +The \sty{glossaries-extra} package provides a similar command: +\nosecformatdef{glsxtrifhasfield} +which doesn't test if the entry exists. The unstarred form adds +implicit grouping around \meta{true} or \meta{false} (allowing +nested use). The starred form \gls{glsxtrifhasfield*} doesn't. +You can compare the field value with a string using: +\nosecformatdef{GlsXtrIfFieldEqStr} +If you need the string to be (protected) fully expanded before +comparison, you need: +\nosecformatdef{GlsXtrIfFieldEqXpStr} +If you additionally need the field value (protected) fully expanded +before comparison, use: +\nosecformatdef{GlsXtrIfXpFieldEqXpStr} +For a complete list of field commands, see the +\sty{glossaries-extra} user manual~\cite{glossaries-extra}. + +The earlier \code{duck} and \code{goose} examples from +\sectionref{sec:firstuse} can be rewritten to move the parenthetical +material into separate keys: +\begin{codeenv} +\gls{newglossaryentry}\marg{duck}\comment{label} +\marg{\comment{information about this term:} + \field{name} = \marg{duck}, + \field{user1} = \marg{noun}, + \field{user2} = \marg{quack, quack}, + description = {a waterbird with webbed feet} +} +\strut +\gls{newglossaryentry}\marg{goose}\comment{label} +\marg{\comment{information about this term:} + \field{name} = \marg{goose}, + \field{plural} = \marg{geese}, + \field{user1} = \marg{noun}, + \field{user2} = \marg{honk, honk}, + \field{description}=\marg{a large waterbird with a long neck, short legs, + webbed feet and a short broad bill} +} +\end{codeenv} +The \idx{postlinkhook} and glossary style can then be modified to +include the additional information. For example: +\begin{codeenv} +\gls[noindex=false]{glsdefpostlink}\marg{general}\marg{\comment{post-link hook} + \gls[noindex=false]{glsxtrifwasfirstuse}\marg{\cmd{space}(\gls{glsentryuserii}\marg{\gls{glslabel}})}{}\comment{} +} +\strut +\gls[noindex=false]{glssetcategoryattribute}\marg{general}\marg{glossname}\marg{firstuc} +\strut +\gls[noindex=false]{glsdefpostname}\marg{general}\marg{\comment{post-name hook} + \cmd{space} + (\gls{glsentryuseri}\marg{\gls[noindex=false]{glscurrententrylabel}}\comment{} + \gls{GlsXtrIfXpFieldEqXpStr}\marg{plural}\marg{\gls{glscurrententrylabel}}\comment{} + \marg{\gls[noindex=false]{glsentrytext}\marg{\gls{glscurrententrylabel}}s}\marg{}\comment{} + \marg{, pl.\gls{cs.space}\gls[noindex=false]{glsentryplural}{\gls{glscurrententrylabel}}}\comment{} + )\comment{} +} +\end{codeenv} +The \idx{postlinkhook} appends the value of the \field{user2} field +after the \idx{firstuse} of \gls{gls} (or its \idxpl{variant}). +The \catattr{glossname} attribute is set to \code{firstuc}, which +converts the first letter of the \field{name} field to +\idx{uppercase} when it's displayed in the glossary. The +\idx{postnamehook} appends (in parentheses) the value of the +\field{user1} field and then checks if the plural form is the same +as the singular form with \qt{s} appended, and only displays the +plural if they are different. See \sectionref{sec:glsformats} and +\sectionref{sec:displaygloss} for further details. + +\section{Accessibility Support} +\label{sec:accsupp} + +The base \sty{glossaries} package is distributed with the +supplementary \sty{glossaries-accsupp} package, which uses the +\sty{accsupp} package~\cite{accsupp} to provide accessibility support. With the +\sty{glossaries-extra} extension package, the +\sty{glossaries-accsupp} package needs to be loaded after \sty{glossaries} +but before \sty{glossaries-extra} sets up the accessibility +integration support. The simplest way to do this is with +\sty{glossaries-extra}'s \styopt{accsupp} package option. + +The accessibility support is provided through the PDF +\code{ActualText} specification (via the \sty{accsupp} package). +If you need \code{E} or \code{Alt} instead of \code{ActualText} then redefine: +\nosecformatdef{glsaccsupp} +as appropriate. For example: +\begin{codeenv} +\cmd{renewcommand}*\marg{\gls{glsaccsupp}}[2]\marg{\comment{} + \cmd{BeginAccSupp}\marg{Alt=\marg{\gls{param}1}}\gls{param}2\cmd{EndAccSupp}\marg{}\comment{} +} +\end{codeenv} + +The \sty{glossaries-accsupp} package provides additional keys (see +Table~\ref{tab:accsuppfields} in the \bibgls\ user manual or +Chapter~18 of the \sty{glossaries} user manual~\cite{glossaries}). +The main keys are \field{access}, which provides an alternative to +the \field{name} field, \field{symbolaccess}, which provides an +alternative to the \field{symbol} field and \field{shortaccess}, +which provides an alternative to the \field{short} field, +\field{firstaccess}, which provides an alternative to the +\field{first} field, and \field{textaccess}, which provides an +alternative to the \field{text} field. If any of the accessibility +fields are unset, no accessibility support is provided for that +field. +For example: +\begin{codeenv} +\gls{newglossaryentry}\marg{R}\comment{label} +\marg{\comment{settings:} + \field{name} = \marg{\cmd{ensuremath}\marg{\cmd{Re}}}, + \field{access} = \marg{set of real numbers symbol},\comment{name access} + \field{textaccess} = \marg{set of real numbers},\comment{text access} + \field{firstaccess} = \marg{set of real numbers},\comment{first access} + \field{description} = \marg{set of real numbers} +} +\end{codeenv} +This means that when the \field{name} field is displayed in the +glossary, the corresponding accessibility text is \qt{set of real +numbers symbol}, but the \idx{link-text} for \gls{gls} is just +\qt{set of real numbers} (for both \idx{firstuse} and subsequent +use). + +There are some category attributes that govern the default settings +of some fields when using \gls{newabbreviation} (see +\sectionref{sec:abbreviations}). If accessibility support is +provided, there are some additional attributes (introduced to +\sty{glossaries-extra} version 1.31): +\begin{description} +\item[\catattr{accessinsertdots}] This is a boolean attribute that behaves like +\catattr{insertdots} but only applies to the \field{shortaccess} +field, if it hasn't explicitly been set. This is useful for +initialisms that should be read out as letters but the screen reader +might interpret as a word. For example: +\begin{codeenv} +\gls{glssetcategoryattribute}\marg{initialism}\marg{\catattr{accessinsertdots}}\marg{true} +\gls{newabbreviation}\oarg{\field{category}=initialism}\marg{pi}\marg{PI}\marg{Private Investigator} +\end{codeenv} +This means that the short form appears as just \qt{PI} in the +document text, but the accessibility text is \qt{P.I.} which prompts +the screen reader to read it as an abbreviation instead of the word +\qt{pi}. Since the \field{shortaccess} field is an aid to the screen +reader and doesn't modify the visible text, there's no check +for the \catattr{retainfirstuseperiod} or \catattr{discardperiod} +attributes for that field. This setting doesn't affect the +accessibility support for the \field{name}, \field{first} or +\field{text} fields. + +\item[\catattr{nameshortaccess}] This is a boolean attribute, where +the value \code{true} indicates the attribute is set. If the +\field{shortaccess} field is assigned (either explicitly with the key or +implicitly through the use of the \catattr{accessinsertdots} +attribute) and the \field{access} field isn't specified, then if the +\catattr{nameshortaccess} attribute is set this will copy the +\field{shortaccess} field to the \field{access} field. For example: +\begin{codeenv} +\gls{glssetcategoryattribute}\marg{initialism}\marg{\catattr{accessinsertdots}}\marg{true} +\gls{glssetcategoryattribute}\marg{initialism}\marg{\catattr{nameshortaccess}}\marg{true} +\gls{newabbreviation}\oarg{\field{category}=initialism}\marg{pi}\marg{PI}\marg{Private Investigator} +\end{codeenv} +Abbreviations that behave like regular terms (such as +\abbrstyle{short-nolong}) may also need \catattr{textshortaccess} +and \catattr{firstshortaccess} set. + +\item[\catattr{textshortaccess}] Like \catattr{nameshortaccess}, but +applies to the \field{textaccess} field. + +\item[\catattr{firstshortaccess}] Like \catattr{firstshortaccess}, but +applies to the \field{firstaccess} field. + +\item[\catattr{accessaposplural}] If the \field{shortaccess} field +is set (either explicitly with the key or implicitly through the use +of the \catattr{accessinsertdots} attribute) and the +\field{shortpluralaccess} field isn't set, the +\catattr{accessaposplural} boolean attribute behaves like +\catattr{aposplural} but only applies to the +\field{shortpluralaccess} field. If the \catattr{accessaposplural} +attribute isn't set but the \catattr{aposplural} attribute is set, +then that's used instead. If you want \catattr{aposplural} on but +not apply it to \field{shortpluralaccess} then you need to set the +\catattr{accessaposplural} attribute to \code{false}. + +\item[\catattr{accessnoshortplural}] A boolean attribute like +\catattr{accessaposplural} but analogous to \catattr{noshortplural} +instead. +\end{description} +These attributes have no effect for entries that aren't defined +using \gls{newabbreviation}. (These attributes apply to +\gls{newacronym} provided it internally uses \gls{newabbreviation}, +which is does by default with \sty{glossaries-extra}.) + +\section{Prefixes} +\label{sec:prefixes} + +The \sty{glossaries} package is distributed with the supplementary +\sty{glossaries-prefix} package. This automatically loads +\sty{glossaries}, but if you are using \sty{glossaries-extra}, it's +best loaded after. This supplementary package supplies extra keys +and some commands analogous to \gls{gls}. The main purpose is to +provide a different prefix to \gls{gls}, depending on whether it's +the \idx{firstuse} or subsequent use. For example, if the +\idx{firstuse} starts with a vowel (or vowel sound), you may need \qt{an +\gls{gls}\margm{label}} but if the subsequent use starts with a +constant, you may need \qt{a \gls{gls}\margm{label}}. The prefix for +the \idx{firstuse} form is specified in the \field{prefixfirst} +field, and the prefix for the subsequent use form is specified in the +\field{prefix} field. If a space is required between the prefix and +\gls{gls}, this needs to be included, as the prefixing system allows +for prefixes like l' which shouldn't be followed by a space. + +To include the prefix, use: +\nosecformatdef{pgls} +instead of \gls{gls}. For example: +\begin{codeenv} +\cmd{documentclass}\marg{book} +\strut +\cmd{usepackage}\marg{glossaries-extra} +\cmd{usepackage}\marg{glossaries-prefix} +\strut +\gls{newabbreviation} + \oarg{\field{prefixfirst}=\marg{a\gls[noindex=false]{nbspchar}},\field{prefix}=\marg{an\cmd{space}}} + \marg{svm}\marg{SVM}\marg{support vector machine} +\strut +\cmd{begin}\marg{document} +With a prefix: \gls{pgls}\marg{svm} or \gls{pgls}\marg{svm}. +Without a prefix: the \gls{gls}\marg{svm}. +\cmd{end}\marg{document} +\end{codeenv} +This produces: +\begin{result} +With a prefix: a support vector machine (SVM) or an SVM. Without a +prefix: the SVM. +\end{result} + +\section{Spaces} +\label{sec:spaces} + +With \LaTeX\ in general, spaces are sometimes significant and +sometimes ignored. When defining entries, any spaces around the +equal sign or comma are ignored. For example, if an entry is defined +as +\begin{codeenv} +\gls{newglossaryentry}\marg{sample} +\marg{ + \field{name} = \marg{sample} , \field{description} = \marg{an example} +} +\end{codeenv} +then +\begin{codeenv} +/\gls{gls}\marg{sample}/ +\end{codeenv} +will produce +\begin{result} +/sample/ +\end{result} +(no spaces). Similarly with: +\begin{codeenv} +\gls{newglossaryentry}\marg{sample} +\marg{ + \field{name} = sample , \field{description} = \marg{an example} +} +\end{codeenv} +However, spaces at the start or end of the value if it's been +enclosed in braces aren't ignored. For example, if the entry is now +defined as: +\begin{codeenv} +\gls{newglossaryentry}\marg{sample} +\marg{ + \field{name} = \marg{ sample } , \field{description} = {an example}\incorrect +} +\end{codeenv} +then: +\begin{codeenv} +/\gls{gls}\marg{sample}/ +\end{codeenv} +produces: +\begin{result} +/ sample / +\end{result} +The spaces in this case have been retained. The unstarred version of +\gls{longnewglossaryentry} appends extra code to the end of the +description, which removes any trailing spaces (and also the +\gls{postdescriptionhook}). The starred version +\gls{longnewglossaryentry*} (only available with \sty{glossaries-extra}) +doesn't. In both cases any leading spaces are retained. For example, +if the entry is defined as: +\begin{codeenv} +\gls{longnewglossaryentry}\marg{sample}\marg{name=\marg{sample}}\marg{ an example }\incorrect +\end{codeenv} +then: +\begin{codeenv} +/\gls{glsentrydesc}\marg{sample}/ +\end{codeenv} +produces: +\begin{result} +/ an example/ +\end{result} +(trailing space removed), whereas if the entry is defined as: +\begin{codeenv} +\gls{longnewglossaryentry*}\marg{sample}\marg{name=\marg{sample}}\marg{ an example }\incorrect +\end{codeenv} +then: +\begin{codeenv} +/\gls{glsentrydesc}\marg{sample}/ +\end{codeenv} +produces: +\begin{result} +/ an example / +\end{result} +(leading and trailing spaces retained). + +Spaces in labels are significant. For example, in \verb|\gls{ duck }| +the spaces are considered part of the label. If the entry was +actually defined without spaces in the label then the entry +referenced in \verb|\gls{ duck }| won't be found. + +\section{Undefined References} +\label{sec:undefaction} + +If an entry that hasn't been defined is referenced with \gls{gls}, +by default an error is triggered. For example: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\marg{glossaries} +\strut +\cmd{begin}\marg{document} +A \gls{gls}\marg{duck}. +\cmd{end}\marg{document} +\end{codeenv} +This produces the error: +\begin{verbatim} +Glossary entry `duck' has not been defined. +\end{verbatim} +If you instruct \LaTeX\ to ignore the error and continue, the result +is +\begin{result} +A . +\end{result} +The \sty{glossaries-extra} package provides the option +\styopt[warn]{undefaction}, which will convert the error to a +warning. For example: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[\styopt{undefaction}=warn]\marg{glossaries-extra} +\strut +\cmd{begin}\marg{document} +A \gls{gls}\marg{duck}. +\cmd{end}\marg{document} +\end{codeenv} +This now produces the warning: +\begin{verbatim} +Glossary entry `duck' has not been defined on input line 6 +\end{verbatim} +(There are also other warnings about an empty \code{main} glossary.) +The result is now: +\begin{result} +A ??. +\end{result} +This replaces the undefined reference with two question marks, just like +undefined cross-references. +Notice the difference between using \gls{ifglshasfield}: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[\styopt{undefaction}=warn]\marg{glossaries-extra} +\strut +\cmd{begin}\marg{document} +A \gls{gls}\marg{duck} +(\gls{ifglshasfield}\marg{\gls[noindex=false]{field.useri}}\marg{duck}\marg{\gls{glscurrentfieldvalue}}\marg{not set}). +\cmd{end}\marg{document} +\end{codeenv} +which produces: +\begin{result} +A ?? (??). +\end{result} +(and has two undefined warnings) and using \gls{glsxtrifhasfield}: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[\styopt{undefaction}=warn]\marg{glossaries-extra} +\strut +\cmd{begin}\marg{document} +A \gls{gls}\marg{duck} +(\gls{glsxtrifhasfield}\marg{\field{useri}}\marg{duck}\marg{\gls{glscurrentfieldvalue}}\marg{not set}). +\cmd{end}\marg{document} +\end{codeenv} +which only has one undefined warning and produces: +\begin{result} +A ?? (not set). +\end{result} + +When you incorporate \bibgls\ into the build process (see +\sectionref{sec:bib2gls}), the first \LaTeX\ run doesn't have any +entries defined. One of the actions that the \styopt{record} option +automatically performs is to switch on \styopt[warn]{undefaction}, which avoids +undefined errors on the first \LaTeX\ run. For example: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[\styopt{record}]\marg{glossaries-extra} +\strut +\cmd{begin}\marg{document} +A \gls{gls}\marg{duck} +(\gls{glsxtrifhasfield}\marg{\field{useri}}\marg{duck}\marg{\gls{glscurrentfieldvalue}}\marg{not set}). +\cmd{end}\marg{document} +\end{codeenv} +This produces the same result as the previous example, but there's +only the one warning (about an undefined reference) and no warning +about the empty \code{main} glossary. + +\section{Robust, Fragile and Expandable Commands} +\label{sec:robust} + +Commands like \gls{gls} are \pidx{robust}. This protects them from +premature expansion in situations that would otherwise break the +command. If content containing a \idx{robust} command is written to +an external file, the \idx{robust} command itself is written instead of its +definition. For example, consider the following document: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\cmd{newcommand}\marg{\csfmt{test}}\marg{some sample text} +\cmd{begin}\marg{document} +\gls{tableofcontents} +\gls[noindex=false]{section}\marg{\csfmt{test}} +\cmd{end}\marg{document} +\end{codeenv} +In this case, \csfmt{test} is expandable. Its definition doesn't +contain anything complicated. The \ext{toc} file (which is input by +\csfmt{tableofcontents}\glsadd{toc}) contains the line: +\begin{codeenv} +\cmd{contentsline} \marg{section}\marg{\cmd{numberline} \marg{1}some sample text}\marg{1} +\end{codeenv} +So \csfmt{test} has been expanded to its definition when it was +written to the \ext{toc} file. If \csfmt{test} is defined in terms +of another command, that will also be expanded. For example: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\cmd{newcommand}\marg{\csfmt{sample}}\marg{\gls{emph}\marg{sample}} +\cmd{newcommand}\marg{\csfmt{test}}\marg{some \csfmt{sample}\gls{cs.space}text} +\cmd{begin}\marg{document} +\gls{tableofcontents} +\gls{section}\marg{\csfmt{test}} +\cmd{end}\marg{document} +\end{codeenv} +The \ext{toc} file now contains: +\begin{codeenv} +\cmd{contentsline} \marg{section}\marg{\cmd{numberline} \marg{1}some \gls{emph} \marg{sample}\gls{cs.space}text}\marg{1} +\end{codeenv} +So \csfmt{sample} has also been expanded but neither +\gls{emph} nor \idx{cs.space} (backslash space) have +been expanded. \Idx{robust} commands don't expand. For example: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\marg{glossaries} +\strut +\gls{newglossaryentry}\marg{duck} +\marg{ + \field{name}=\marg{duck}, + \field{description}=\marg{a waterbird with webbed feet} +} +\strut +\cmd{begin}\marg{document} +\gls{tableofcontents} +\gls{section}\marg{\gls{Gls}\marg{duck}: \gls{glsentrydesc}\marg{duck}} +\cmd{end}\marg{document} +\end{codeenv} +The \ext{toc} file now contains: +\begin{codeenv} +\cmd{contentsline} \marg{section}\marg{\cmd{numberline} \marg{1}\gls{Gls} \marg{duck}: a waterbird with +webbed feet}\marg{1} +\end{codeenv} +So \gls{Gls} doesn't expand, and the command itself is written to the +\ext{toc} file, but \gls{glsentrydesc} does expand. + +A \pidx{fragile} command is one that breaks (causes an error) when +it's expanded in this type of context. One such command is \gls{footnote}. +For example, the following won't work: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\marg{glossaries} +\strut +\gls{newglossaryentry}\marg{duck} +\marg{ + \field{name}=\marg{duck}, + \field{description}=\marg{a waterbird with webbed feet} +} +\strut +\cmd{begin}\marg{document} +\gls{tableofcontents} +\gls{section}\marg{\gls{Gls}\marg{duck}\gls{footnote}\marg{\gls{glsentrydesc}\marg{duck}}}\incorrect +\cmd{end}\marg{document} +\end{codeenv} +This causes the error: +\begin{verbatim} +! Argument of \@sect has an extra }. +\end{verbatim} +Inserting \gls{protect} before the command prevents the attempted +expansion, which makes the command behave as though it was robust: +\begin{codeenv} +\gls{section}\marg{\gls{Gls}\marg{duck}\gls{protect}\gls{footnote}\marg{\gls{glsentrydesc}\marg{duck}}} +\end{codeenv} +In this case, it's unlikely that you'd want the footnote to appear +in the \gls{toc}, so it would be better to use the optional +argument: +\begin{codeenv} +\gls{section}\oarg{Duck}\marg{\gls{Gls}\marg{duck}\gls{footnote}\marg{\gls{glsentrydesc}\marg{duck}}}\correct +\end{codeenv} +Now the \ext{toc} file is just: +\begin{codeenv} +\cmd{contentsline} \marg{section}\marg{\cmd{numberline} \marg{1}Duck}\marg{1} +\end{codeenv} +If the \field{description} field contains a \idx{fragile} command +then \gls{glsentrydesc} will break in expandable contexts. For +example, the following doesn't work: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\marg{glossaries} +\strut +\gls{newglossaryentry}\marg{duck} +\marg{ + \field{name}=\marg{duck}, + \field{description}=\marg{a waterbird\gls{footnote}\marg{a bird that lives on or + near water} with webbed feet} +} +\strut +\cmd{begin}\marg{document} +\gls{tableofcontents} +\gls{section}\marg{\gls{Gls}\marg{duck}: \gls{glsentrydesc}\marg{duck}}\incorrect +\cmd{end}\marg{document} +\end{codeenv} +This is a contrived example. In this case, it would be better to +also define the term \qt{waterbird}: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\marg{glossaries} +\strut +\gls{newglossaryentry}\marg{waterbird} +\marg{ + \field{name}=\marg{waterbird}, + \field{description}=\marg{a bird that lives on or near water} +} +\strut +\gls{newglossaryentry}\marg{duck} +\marg{ + \field{name}=\marg{duck}, + \field{description}=\marg{a \gls{gls}\marg{waterbird} with webbed feet} +} +\strut +\cmd{begin}\marg{document} +\gls{tableofcontents} +\gls{section}\marg{\gls{Gls}\marg{duck}: \gls{glsentrydesc}\marg{duck}} +\cmd{end}\marg{document} +\end{codeenv} +The \ext{toc} file now contains: +\begin{codeenv} +\cmd{contentsline} \marg{section}\marg{\cmd{numberline} \marg{1}\gls{Gls} \marg{duck}: a \gls{gls} \marg{waterbird} +with webbed feet}\marg{1} +\end{codeenv} + +\begin{important} +The examples in this section are used to illustrate the differences +between \idx{fragile}, \idx{robust} and \idx{expandable} commands. +In general, it's better not to use commands like \gls{gls} in +headings or captions (see \sectionref{sec:headings}). Using +commands like \gls{gls} in field values can be problematic (see +\sectionref{sec:nested}). +\end{important} + +By default, most of the field values are expanded when the entry is +defined. This allows for defining entries programmatically, but it +can cause a problem if the value contains any \idx{fragile} commands. +For example: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\marg{glossaries} +\strut +\gls{newglossaryentry}\marg{duck}\comment{label} +\marg{ + \field{name} = \marg{duck}, + \field{first} = \marg{duck\gls{footnote}\marg{quack, quack}},\incorrect + \field{description} = \marg{a waterbird with webbed feet} +} +\strut +\cmd{begin}\marg{document} +A \gls{gls}\marg{duck}. +\cmd{end}\marg{document} +\end{codeenv} +This causes the confusing error: +\begin{verbatim} +! Undefined control sequence. +\in@ #1#2->\begingroup \def \in@@ +\end{verbatim} +In order for this example to work, the \idx{fragile} command must either be +protected: +\begin{codeenv} +\gls{newglossaryentry}\marg{duck}\comment{label} +\marg{ + \field{name} = \marg{duck}, + \field{first} = \marg{duck\gls{protect}\gls{footnote}\marg{quack, quack}},\correct + \field{description} = \marg{a waterbird with webbed feet} +} +\end{codeenv} +or the expansion must first be switched off: +\begin{codeenv} +\gls{glsnoexpandfields} \correct +\gls{newglossaryentry}\marg{duck}\comment{label} +\marg{ + \field{name} = \marg{duck}, + \field{first} = \marg{duck\gls{footnote}\marg{quack, quack}}, + \field{description} = \marg{a waterbird with webbed feet} +} +\end{codeenv} +Since it's not possible to programmatically define entries with +\bibgls, the expansion is automatically switched off as \bibgls\ +writes \gls{glsnoexpandfields} to the \ext{glstex} file (although +you can disable this feature with \longarg{expand-fields}). + +The reason why \gls{footnote} didn't cause a problem in the +\field{description} field \emph{when the entry was defined} is that, by +default, expansion isn't performed on the \field{name}, +\field{description} and \field{symbol} fields, regardless of whether +or not \gls{glsnoexpandfields} has been used. This only applies to +the point when the entries are being defined. Unprotected +\idx{fragile} commands can still cause a problem if the value is +later used in a problematic context (such as the earlier example +where \gls{glsentrydesc} was used in a section heading). + +\chapter{Abbreviations} +\label{sec:abbreviations} + +The abbreviation handling provided by the base \isty{glossaries} +package is quite restrictive and only one abbreviation style can be +used for all abbreviations. The \isty{glossaries-extra} package +internally loads the \sty{glossaries} package and extends it, +providing new options and a better abbreviation mechanism that +allows different styles per category. + +The base \sty{glossaries} package provides: +\nosecformatdef{newacronym} +The extension package \sty{glossaries-extra} provides: +\nosecformatdef{newabbreviation} +which internally uses \gls{newglossaryentry} with the +\field{category} set to \code{abbreviation} (which can be +overridden in the optional \meta{\keyvallist}). +The \gls{glossaries-extra} package also redefines \gls{newacronym} in +terms of \gls{newabbreviation} so that it effectively behaves like: +\begin{codeenv} +\gls{newabbreviation}\oarg{\gls[noindex=false]{field.type}=\gls{acronymtype},\field{category}=acronym,\meta{\keyvallist}} +\margm{label}\margm{short}\margm{long} +\end{codeenv} +This makes it easier to transfer over from the base \sty{glossaries} +package, but if you use \gls{newacronym} remember that the +\field{category} is set to \code{acronym} instead of \code{abbreviation}. + +In both cases, \meta{label} is the entry's label used to identify +the abbreviation in commands like \gls{gls}, \meta{short} is the +short form and \meta{long} is the long form. Any additional +settings, such as the \field{category} or \field{description} +can be set in the optional argument. + +The style must be set \emph{before the abbreviations are defined} +using: +\nosecformatdef{setabbreviationstyle} +where \meta{category} is the category label and \meta{style-name} is +the name of the style. If the optional argument is omitted, +\code{abbreviation} is assumed. The \sty{glossaries-extra} package +automatically sets the default styles: +\begin{codeenv*} +\gls{setabbreviationstyle}\marg{\abbrstyle{long-short}} +\gls{setabbreviationstyle}\oarg{acronym}\marg{\abbrstyle{short-nolong}} +\end{codeenv*} +This means that if you don't explicitly set the style then any +abbreviation defined with \gls{newacronym} will use the +\abbrstyle{short-nolong} style (unless you change the category in +the optional argument) and other abbreviations will use the +\abbrstyle{long-short} style. + +If these styles aren't suitable, then you need to change them. Any +abbreviation that's defined with a category that hasn't been +assigned a style will fallback on the style for the default +\code{abbreviation} category. There are many predefined styles to +choose from and they come with commands to help adjust the +formatting. See the \sty{glossaries-extra} user +manual~\cite{glossaries-extra} for the +complete list. The \sty{glossaries-extra} package also comes with a +sample document +\ctanfile{glossaries-extra/samples}{sample-abbr-styles.pdf} +demonstrating all the predefined styles. + +The style determines whether the abbreviation is treated as a +\idx{regular} term. There are also some \idxpl{categoryattribute} that govern +abbreviations (see below and \sectionref{sec:accsupp}). These +should also be set before the abbreviation is defined. + +Some of the styles set the \field{description} field (typically to +the \meta{long} form). The styles that end with \code{-desc} don't, +and so that key must be set explicitly in the \meta{\keyvallist} optional part. + +Here's a simple example that uses both \gls{newabbreviation} and +\gls{newacronym} to illustrate the difference: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\marg{glossaries-extra} +\strut +\gls{newabbreviation}\marg{tug}\marg{TUG}\marg{\cmd{TeX}\gls{cs.space}Users Group} +\gls{newabbreviation}\marg{cldr}\marg{CLDR}\marg{Unicode Common Locale Data +Repository} +\strut +\gls{newacronym}\marg{SIunit}\marg{SI unit}\marg{International System of Units} +\gls{newacronym}\marg{ascii}\marg{ASCII}\marg{American Standard Code for +Information Interchange} +\strut +\cmd{begin}\marg{document} +First use: \gls{gls}\marg{tug}, \gls{gls}\marg{cldr}, \gls{gls}\marg{SIunit}, \gls{gls}\marg{ascii}. +Next use: \gls{gls}\marg{tug}, \gls{gls}\marg{cldr}, \gls{gls}\marg{SIunit}, \gls{gls}\marg{ascii}. +\cmd{end}\marg{document} +\end{codeenv} +This produces: +\begin{result} +First use: \gls{TUG}, \gls{CLDR}, \gls{SIunit}, \gls{ASCII}. +Next use: \gls{TUG}, \gls{CLDR}, \gls{SIunit}, \gls{ASCII}. +\end{result} +Note that the \idx{firstuse} of \code{SIunit} and \code{ascii} only +show the short form. This is because the default style for the +\code{acronym} category is the \abbrstyle{short-nolong} style, which +doesn't show the long form with \gls{gls} (and its \idxpl{variant}). + +The final optional \meta{insert} argument of commands like \gls{gls} +is typically moved inside, depending on the style. For example: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\marg{glossaries-extra} +\strut +\gls{newabbreviation}\marg{svm}\marg{SVM}\marg{support vector machine} +\strut +\cmd{begin}\marg{document} +The \gls{gls}\marg{svm}\oarg{'s} parameters are\cmd{ldots} +\cmd{end}\marg{document} +\end{codeenv} +This produces: +\begin{result} +The \gls{ex.svm}['s] parameters are\ldots +\end{result} +Compare this with: +\begin{codeenv} +The \gls{gls}\marg{svm}'s parameters are\cmd{ldots}\incorrect +\end{codeenv} +which produces: +\begin{result} +The \gls{ex.svm}'s parameters are\ldots +\end{result} + +\section{Only Long or Only Short} +\label{sec:longorshort} + +If you only want \gls{gls} to show the short form but not the long +form (including on \idx{firstuse}), use one of the \code{-nolong} +styles (such as \abbrstyle{short-nolong}). If you only want the long +form and not the short form (including subsequent use), use one of +the \code{-noshort} styles (such as \abbrstyle{long-noshort}). + +If you want only the long form on \idx{firstuse} (without the short +form) and only the short form subsequently then use one of the +\code{-only} styles, such as \abbrstyle{long-only-short-only}. + +If you need to reshow the full form, you can reset the +\idx{firstuseflag} with: +\nosecformatdef{glsreset} +which will make the next instance of \code{\gls{gls}\margm{labe}} +act according to \idx{firstuse}. + +\begin{important} +If you need an abbreviation in a caption or section title, see +\sectionref{sec:headings}. +\end{important} + +Otherwise, if you want a \emph{specific} instance to show only the short +form, without modifying the \idx{firstuseflag}, then use +\nosecformatdef{glsxtrshort} +If you want a specific instance to show only the long form, without +modifying the \idx{firstuseflag}, then use +\nosecformatdef{glsxtrlong} +If you want a specific instance to show both the long and short form, without +modifying the \idx{firstuseflag}, then use +\nosecformatdef{glsxtrfull} +Depending on the style, this may not exactly match the format +produced by the \idx{firstuse} of \code{\gls{gls}\margm{label}}. +Don't use these commands for every use. Change the style instead, +which will make it easier to modify the document at a later date. + +If you find these commands quite long-winded, there are some +shortcuts available with the \styopt{shortcuts} option, but as these +may interfere with other packages, you might want to consider +investigating your text editor settings as the more sophisticated +ones provide ways of inserting commonly-used commands to save typing. + +\section{Plural Abbreviations} +\label{sec:pluralabbr} + +If the abbreviation represents something countable then the plural +form can again be obtained with \gls{glspl}: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\marg{glossaries-extra} +\strut +\gls{newabbreviation}\marg{svm}\marg{SVM}\marg{support vector machine} +\strut +\cmd{begin}\marg{document} +First use: \gls{glspl}\marg{svm}. Next use: \gls{glspl}\marg{svm}. +\cmd{end}\marg{document} +\end{codeenv} +This produces: +\begin{result} +First use: \glspl{ex.svm}. Next use: \glspl{ex.svm}. +\end{result} +The default plural short and long forms are obtained by +appending the letter \qt{s} after the singular form. These can be +changed on an individual basis with the \field{shortplural} and +\field{longplural} keys. For example: +\begin{codeenv} +\gls{newabbreviation} + [\field{longplural}=\marg{lower triangular matrices}] + \marg{ltm}\marg{LTM}\marg{lower triangular matrix} +\end{codeenv} + +It may be that you prefer to keep the short plural form the same as +the short singular value for all abbreviations within a particular +category. You can implement this with the +\catattr{noshortplural} attribute, which must be set to \code{true} +before the abbreviations for that category are defined. For example: +\begin{codeenv} +\gls{glssetcategoryattribute}\marg{abbreviation}\marg{\catattr{noshortplural}}\marg{true} +\gls{newabbreviation}\marg{svm}\marg{SVM}\marg{support vector machine} +\end{codeenv} +Now: +\begin{codeenv} +First use: \gls{glspl}\marg{svm}. Next use: \gls{glspl}\marg{svm}. +\end{codeenv} +produces: +\begin{result} +First use: support vector machines (SVM). Next use: SVM. +\end{result} +A related attribute is \catattr{aposplural} which inserts \qtt{'s} +(apostrophe followed by \qt{s}) to form the default short plural to +help avoid ambiguity with \idx{lowercase} abbreviations where it might +not be obvious that the \qt{s} indicates a plural (rather than +another letter in the abbreviation). Again, this needs to be set +before the abbreviations for the given category (or categories) are +defined (but check with your supervisor, publisher or editor as this +usage is controversial). + +\section{Abbreviation Markup} +\label{sec:markwords} + +The \catattr{markwords} attribute can be set to \code{true} to +indicate that \gls{newabbreviation} should parse the long form and +markup the words using: +\nosecformatdef{glsxtrword} +The words are separated with +\nosecformatdef{glsxtrwordsep} +For example: +\begin{codeenv} +\gls{glssetcategoryattribute}\marg{abbreviation}\marg{\catattr{markwords}}\marg{true} +\gls{newabbreviation}\marg{ssl}\marg{SSL}\marg{Secure Sockets Layer} +\end{codeenv} +This is essentially the same as +\begin{codeenv} +\gls{newabbreviation}\marg{ssl}\marg{SSL}\marg{\gls{glsxtrword}\marg{Secure}\gls{glsxtrwordsep} +\gls{glsxtrword}\marg{Sockets}\gls{glsxtrwordsep}\gls{glsxtrword}\marg{Layer}} +\end{codeenv} +This is typically used with the \code{-hyphen} abbreviation styles, +such as \abbrstyle{long-hyphen-short-hyphen}. +If the final optional \meta{insert} argument of commands like +\gls{gls} starts with a hyphen, \gls{glsxtrwordsep} is locally +changed to a hyphen. + +For example: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\marg{glossaries-extra} +\strut +\gls{setabbreviationstyle}\marg{\abbrstyle[noindex=false]{long-hyphen-short-hyphen}} +\strut +\gls{glssetcategoryattribute}\marg{abbreviation}\marg{\catattr{markwords}}\marg{true} +\strut +\gls{newabbreviation}\marg{ssl}\marg{SSL}\marg{Secure Sockets Layer} +\strut +\cmd{begin}\marg{document} +First use: \gls{gls}\marg{ssl}\oarg{-enabled}. Next use: \gls{gls}\marg{ssl}\oarg{-enabled}. +\cmd{end}\marg{document} +\end{codeenv} +This produces: +\begin{result} +First use: \gls{ex.ssl}[-enabled]. Next use: \gls{ex.ssl}[-enabled]. +\end{result} +Compare this with: +\begin{codeenv} +First use: \gls{gls}\marg{ssl}-enabled. Next use: \gls{gls}\marg{ssl}-enabled.\incorrect +\end{codeenv} +which instead produces: +\begin{result} +First use: \gls{ex.ssl}-enabled. Next use: \gls{ex.ssl}-enabled. +\end{result} +Whereas: +\begin{codeenv} +First use: \gls{gls}\marg{ssl}\oarg{ enabled}. Next use: \gls{gls}\marg{ssl}\oarg{ enabled}. +\end{codeenv} +produces: +\begin{result} +First use: \gls{ex.ssl}[ enabled]. Next use: \gls{ex.ssl}[ enabled]. +\end{result} +Note that this is different to the result obtained with the +\abbrstyle{long-short} style which doesn't include the inserted +material in the parentheses (and doesn't check if the inserted +text starts with a hyphen). + +There's a related attribute \catattr{markshortwords} which applies +to the short form instead. This is only useful if the short form contains +spaces. + +Another markup-related attribute is \catattr{tagging}. In general, +you don't need to explicitly set this attribute. Instead, you need +to define a tagging command using: +\nosecformatdef{GlsXtrEnableInitialTagging} +This (robustly) defines \meta{cs} (a control sequence) to accept a +single argument, which you need to use in the \meta{long} part of the +abbreviation definition (it's not inserted automatically). + +The \gls{GlsXtrEnableInitialTagging} command also sets the +\catattr{tagging} attribute to \code{true} for each of the listed +categories, which ensures that \meta{cs} uses +\nosecformatdef{glsxtrtagfont} +within the glossary (see \sectionref{sec:displaygloss}). Within the +main text the command simply does its argument. +For example: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\marg{glossaries-extra} +\strut +\gls{GlsXtrEnableInitialTagging}\marg{abbreviation}\marg{\cmd{itag}} +\strut +\gls{newabbreviation}\marg{xml}\marg{XML}\marg{e\cmd{itag}\marg{x}tensible \cmd{itag}\marg{m}arkup +\cmd{itag}\marg{l}anguage} +\strut +\cmd{begin}\marg{document} +First use: \gls{gls}\marg{xml}. Next use: \gls{gls}\marg{xml}. +\cmd{end}\marg{document} +\end{codeenv} +This produces: +\begin{result} +First use: \gls{ex.xml}. Next use: \gls{ex.xml}. +\end{result} +This doesn't show the markup as the tagging command (\csfmt{itag} in +this example) simply expands to its argument in the main document +text. The difference is only evident in the glossary. + +If all your abbreviations are defined in a separate file, it's +useful to provide a definition of the tagging command with +\gls{providecommand} to ensure it's defined if you decide not to use +\gls{GlsXtrEnableInitialTagging}. With \bibgls, you can include it +in the \atentry{preamble}. For example: +\begin{codeenv} +\atentry{preamble}\marg{"\gls{providecommand}\marg{\cmd{itag}}\oarg{1}\marg{\gls{param}1}"} +\end{codeenv} + +\section{Dotted Abbreviations} +\label{sec:dotabbr} + +If an abbreviation ends with a \idx{full-stop}, it can be awkward +when it appears at the end of a sentence, as you can end up with two +dots by mistake. For example: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\marg{glossaries-extra} +\strut +\gls{newabbreviation}\marg{dante}\marg{DANTE e.V.} +\marg{Deutschsprachige Anwendervereinigung \cmd{TeX}\gls{cs.space}e.V.} +\strut +\gls{newabbreviation}\marg{gp}\marg{G.P.}\marg{General Practitioner} +\strut +\cmd{begin}\marg{document} +\gls{gls}\marg{dante} is a local \cmd{TeX}\gls{cs.space}user group. +The German-speaking local \cmd{TeX}\gls{cs.space}user group is \gls{gls}\marg{dante}. +\strut +A \gls{gls}\marg{gp} is a medical doctor. +I went to my surgery to see the \gls{gls}\marg{gp}. +\cmd{end}\marg{document} +\end{codeenv} +This results in: +\begin{result} +\gls{ex.dante} is a local \TeX\ user group. +The German-speaking local \TeX\ user group is \gls{ex.dante}\relax.\incorrect + +A \gls{ex.gp} is a medical doctor. +I went to my surgery to see the \gls{ex.gp}\relax.\incorrect +\end{result} +The awkward double-dot is caused by the final dot in the +short form followed by the sentence terminating \idx{full-stop}. + +If the \catattr{discardperiod} attribute is set to \code{true}, the +\idx{postlinkhook} will look ahead for a \idx{full-stop}. If it +finds one, it will be discarded. For example: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\marg{glossaries-extra} +\strut +\gls{glssetcategoryattribute}\marg{abbreviationdot}\marg{\catattr{discardperiod}}\marg{true} +\strut +\gls{newabbreviation}\oarg{\field{category}=abbreviationdot} + \marg{dante}\marg{DANTE e.V.}\marg{Deutschsprachige Anwendervereinigung \cmd{TeX}\gls{cs.space}e.V.} +\strut +\gls{newabbreviation}\oarg{\field{category}=abbreviationdot} + \marg{gp}\marg{G.P.}\marg{General Practitioner} +\strut +\cmd{begin}\marg{document} +\gls{gls}\marg{dante} is a local \cmd{TeX}\gls{cs.space}user group. +The German-speaking local \cmd{TeX}\gls{cs.space}user group is \gls{gls}\marg{dante}. +\strut +A \gls{gls}\marg{gp} is a medical doctor. +I went to my surgery to see the \gls{gls}\marg{gp}. +\cmd{end}\marg{document} +\end{codeenv} +This now results in: +\begin{result} +\gls{ex.dante} is a local \TeX\ user group. +The German-speaking local \TeX\ user group is \gls{ex.dante}. + +A \gls{ex.gp} is a medical doctor. +I went to my surgery to see the \gls{ex.gp}. +\end{result} +This attribute only affects the \emph{non-plural} commands, such as +\gls{gls} and \gls{glsxtrshort}. If the last paragraph in the above +example is changed to: +\begin{codeenv} +A \gls{gls}\marg{gp} is a medical doctor. +I went to my surgery to see the \gls{glspl}\marg{gp}. +\end{codeenv} +then the result is: +\begin{result} +A \gls{ex.gp} is a medical doctor. +I went to my surgery to see the \glspl{ex.gp}. +\end{result} +In this case there's no need to discard the terminating +\idx{full-stop} as the plural form doesn't end with one. If the +plural form also ends with a \idx{full-stop} (for example, if the +\catattr{noshortplural} attribute is also set) then you additionally +need to set the \catattr{pluraldiscardperiod} attribute. + +The \idx{postlinkhook} is also applied to other commands, such as +\gls{glsxtrfull}, \gls{glsxtrlong}, \gls{glsxtrshort} and \gls{glssymbol}. +For example: +\begin{codeenv} +I went to my surgery to see the \gls{glsxtrshort}\marg{gp}. +\end{codeenv} +results in: +\begin{result} +I went to my surgery to see the \glsxtrshort{ex.gp}. +\end{result} +In some cases, this may be inappropriate, for example: +\begin{codeenv} +I went to my surgery to see the \gls{glsxtrlong}\marg{gp}. +\end{codeenv} +results in: +\begin{result} +I went to my surgery to see the \glsxtrlong{ex.gp}. +\end{result} +In this case the terminating \idx{full-stop} shouldn't be discarded. +There are several ways to prevent it. For example, moving the +\idx{full-stop} into the \meta{insert} argument: +\begin{codeenv} +I went to my surgery to see the \gls{glsxtrlong}\marg{gp}\oarg{.} +\end{codeenv} +This results in: +\begin{result} +I went to my surgery to see the \glsxtrlong{ex.gp}[.] +\end{result} +Alternatively, insert \csfmt{relax} before the \idx{full-stop}: +\begin{codeenv} +I went to my surgery to see the \gls{glsxtrlong}\marg{gp}\cmd{relax}. +\end{codeenv} + +Depending on the abbreviation style, it may be inappropriate for the +\idx{firstuse} to discard the \idx{full-stop}. In this case, it's a +bit of a nuisance to keep track of whether the term is being +referenced for the first time. Instead, set the +\catattr{retainfirstuseperiod} attribute to \code{true}. + +If you have many abbreviations defined without dots and then you +later decide to insert them, you may prefer an automated approach. +This can be done by setting the \catattr{insertdots} attribute to \code{true}. +For example: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\marg{glossaries-extra} +\strut +\gls{glssetcategoryattribute}\marg{initialism}\marg{\catattr{insertdots}}\marg{true} +\gls{glssetcategoryattribute}\marg{initialism}\marg{\catattr{discardperiod}}\marg{true} +\gls{glssetcategoryattribute}\marg{initialism}\marg{\catattr{retainfirstuseperiod}}\marg{true} +\strut +\gls{setabbreviationstyle}\oarg{initialism}\marg{\abbrstyle[noindex=false]{short-long}} +\strut +\gls{newabbreviation}\oarg{\field{category}=initialism} + \marg{gp}\marg{GP}\marg{General Practitioner} +\strut +\cmd{begin}\marg{document} +Today I went to my surgery to see the \gls{gls}\marg{gp}. +Tomorrow I'm going to my surgery to see the \gls{gls}\marg{gp}. +\cmd{end}\marg{document} +\end{codeenv} +This produces: +\begin{result} +Today I went to my surgery to see the \gls{ex2.gp}. +Tomorrow I'm going to my surgery to see the \gls{ex2.gp}. +\end{result} + +\section{Translations} +\label{sec:abbrvtrans} + +If an abbreviation needs to be accompanied by a translation, then +you can use a custom field or one of the supplied user fields +described in \sectionref{sec:userkeys} to store the translation. The +\code{-user} abbreviation styles can be used to include the extra +information if the field is set. The \field{user1} field +is the default, but you can change this by redefining: +\nosecformatdef{glsxtruserfield} +to the \emph{internal} field name. (For example, \field{userii} for +\field{user2}.) In the sample document below, the translation is +supplied in the default \field{user1} field: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\marg{glossaries-extra} +\strut +\gls{setabbreviationstyle}\marg{\abbrstyle{long-short-user}} +\strut +\gls{newabbreviation}\oarg{\field{user1}=\marg{ribonucleic acid}} + \marg{rna}\marg{RNA}\marg{ribonukleins\gls[noindex=false]{umlaut}aure} +\strut +\cmd{begin}\marg{document} +First use: \gls{gls}\marg{rna}. Next use: \gls{gls}\marg{rna}. +\cmd{end}\marg{document} +\end{codeenv} +This produces: +\begin{result} +First use: \gls{ex.rna}. Next use: \gls{ex.rna}. +\end{result} +If the field is empty, \abbrstyle{long-short-user} behaves like +\abbrstyle{long-short}. + +Here's an example where the native language is English: +\begin{codeenv} +\gls{newabbreviation}\marg{iso}\marg{ISO}\marg{International Organization for Standardization} +\strut +\gls{newabbreviation}\oarg{ + \field{user1} = \marg{Associa\gls{c}\marg{c}\gls{cs.tilde}ao Brasileria de Normas T\cs{acute}ecnicas}, + \field{user2} = \marg{pt-BR}, + \field{category} = \marg{foreignabbreviation} +} +\marg{abnt}\marg{ABNT}\marg{Brazilian National Standards Organization} +\strut +\gls{newabbreviation}\oarg{ + \field{user1} = \marg{Deutsches Institut f\gls{umlaut}ur Normung e.V.}, + \field{user2} = \marg{de-1996}, + \field{category} = \marg{foreignabbreviation} +}\marg{din}\marg{DIN}\marg{German Institute for Standardization} +\end{codeenv} +The use of the custom \field{category} label +\code{foreignabbrevaiation} means I can set up different abbreviation +styles. For example: +\begin{codeenv} +\gls{setabbreviationstyle}\marg{short-nolong} +\gls{setabbreviationstyle}\oarg{foreignabbreviation}\marg{long-short-user} +\end{codeenv} +This example differs from the previous one as there are now two +foreign languages (Portuguese and German) with English as the native +language. The previous had German as the native language and English +as the sole foreign language. In this case, I've used the +\field{user2} field to identify the language of the original text +(stored in the \field{user1} field). + +For example, suppose I'm using \sty{babel} with the language options +\code{british}, \code{brazilian} and \code{ngerman}: +\begin{codeenv} +\cmd{usepackage}[main=british,brazilian,ngerman]\marg{babel} +\end{codeenv} +then I might want to modify \gls{glsxtruserparen} to use +\gls{foreignlanguage}. This would be easier if the \field{user2} +field used a recognised \sty{babel} dialect label, but that's less +consistent across documents. For example, in another document I +might use \code{UKenglish} or just \code{english} (or perhaps use +\sty{polyglossia} instead). + +The \sty{glossaries} package loads \sty{tracklang}~\cite{tracklang}, +which provides: +\nosecformatdef{GetTrackedDialectFromLanguageTag} +If the given language tag matches a document dialect that's been +tracked (by \sty{tracklang}), this stores the \emph{\sty{tracklang} +dialect label} in the control sequence \meta{cs} otherwise it sets +that control sequence to empty. The match requires that five +properties of the language tag and \sty{tracklang}'s dialect label +are the same: root language, region, sub-language, variant and +script. Some of these elements may be empty, in which case those +elements must be empty for both. If the script is missing in either +case, the default script for the given root language is assumed. For +example, \code{Latn} for \code{en} (English). + +\begin{important} +The \sty{tracklang} dialect label isn't always the same as +\sty{babel}'s dialect label. +\end{important} + +The simplest way to test if the \sty{tracklang} label matches the +\sty{babel} label is to test for the existence of +\csfmt{captions}\meta{label}. For example, using \sty{etoolbox}'s +\gls{ifcsundef}: +\begin{codeenv} +\gls{GetTrackedDialectFromLanguageTag}\marg{pt-BR}\marg{\cmd{dialectlabel}} +\gls{ifdefempty}\cmd{dialectlabel} +\marg{}\comment{no exact match found} +\marg{\comment{exact match found} + \gls{ifcsundef}\marg{captions\cmd{dialectlabel}} + \marg{}\comment{not a recognised \sty{babel} label} + \marg{}\comment{recognised \sty{babel} label} +} +\end{codeenv} +In the \qt{not a recognised \sty{babel} label} argument, you can +find out if the \sty{tracklang} dialect label has a mapping to the +closest known \sty{babel} dialect label with: +\nosecformatdef{IfTrackedDialectHasMapping} +If true, you can fetch the corresponding \sty{babel} label with: +\nosecformatdef{GetTrackedDialectToMapping} +If false, you can try the root language label instead, which can be +obtained with: +\nosecformatdef{TrackedLanguageFromDialect} +For example: +\begin{codeenv} +\gls{GetTrackedDialectFromLanguageTag}\marg{pt-BR}\marg{\cmd{dialectlabel}} +\gls{ifdefempty}\cmd{dialectlabel} +\marg{}\comment{no exact match found} +\marg{\comment{exact match found} + \gls{ifcsundef}\marg{captions\cmd{dialectlabel}} + \marg{\comment{not a recognised \sty{babel} label, use root language} + \cmd{edef}\cmd{dialectlabel}\marg{\gls{TrackedLanguageFromDialect}\cmd{dialectlabel}}\comment{} + }\comment{} + \marg{}\comment{recognised \sty{babel} label} +} +\end{codeenv} + +Consider the following document: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[british]\marg{babel} +\cmd{usepackage}\marg{tracklang} +\strut +\cmd{begin}\marg{document} +\gls{GetTrackedDialectFromLanguageTag}\marg{en-GB}\marg{\cmd{trackeddialect}}\comment{} +Tracked dialect label: \cmd{trackeddialect}. +\gls{IfTrackedDialectHasMapping}\marg{\cmd{trackeddialect}}\comment{} +\marg{Has mapping: \gls{GetTrackedDialectToMapping}\marg{\cmd{trackeddialect}}}\comment{} +\marg{No mapping}. +Root language: \gls{TrackedLanguageFromDialect}\marg{\cmd{trackeddialect}}. +\cmd{end}\marg{document} +\end{codeenv} +In this case the \sty{tracklang} dialect label is the same as +\sty{babel}'s dialect label. The above produces: +\begin{result} +Tracked dialect label: british. No mapping. Root language: english. +\end{result} +Now consider this document: +\begin{codeenv} +\cmd{documentclass}[en-MT]\marg{article} +\strut +\cmd{usepackage}[british]\oarg{babel} +\cmd{usepackage}\marg{tracklang} +\strut +\cmd{begin}\marg{document} +en-GB: \gls{GetTrackedDialectFromLanguageTag}\marg{en-GB}\marg{\cmd{trackeddialect}}\comment{} Tracked dialect label: \cmd{trackeddialect}. +\gls{IfTrackedDialectHasMapping}\marg{\cmd{trackeddialect}}\comment{} +\marg{Has mapping: \gls{GetTrackedDialectToMapping}\marg{\cmd{trackeddialect}}}\comment{} +\marg{No mapping}. +Root language: \gls{TrackedLanguageFromDialect}\marg{\cmd{trackeddialect}}. +\strut +en-MT: \gls{GetTrackedDialectFromLanguageTag}\marg{en-MT}\marg{\cmd{trackeddialect}}\comment{} Tracked dialect label: \cmd{trackeddialect}. +\gls{IfTrackedDialectHasMapping}\marg{\cmd{trackeddialect}}\comment{} +\marg{Has mapping: \gls{GetTrackedDialectToMapping}\marg{\cmd{trackeddialect}}}\comment{} +\marg{No mapping}. +Root language: \gls{TrackedLanguageFromDialect}\marg{\cmd{trackeddialect}}. +\cmd{end}\marg{document} +\end{codeenv} +In this case the document requires Maltese English but \sty{babel} +doesn't have an associated dialect so \code{british} is used +instead in \sty{babel}'s options list. However, \sty{tracklang} does +recognise \code{en-MT} as a document class option, which allows +extra localisation from other locale-sensitive packages. (For +example, \sty{datetime2} will use different time zone abbreviations.) If +\sty{tracklang} picks up document class options, these override any +\sty{babel} settings, but the mapping allows a way of accessing the +captions hook provided by \sty{babel}. + +The above document produces: +\begin{result} +en-GB: Tracked dialect label: . No mapping. Root language: . + +en-MT: Tracked dialect label: maltaenglish. Has mapping: british. +Root language: english. +\end{result} +So now, even though \sty{babel}'s \code{british} option has been +used, en-GB isn't recognised as a tracked locale. Things are a +little more complicated if the language tag is too specific compared +to the \sty{babel} dialect label. For example, while the dialect +label \code{nswissgerman} identifies the region, the \code{ngerman} +label doesn't. +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[ngerman]\marg{babel} +\cmd{usepackage}\marg{tracklang} +\strut +\cmd{begin}\marg{document} +\gls{GetTrackedDialectFromLanguageTag}\marg{de-DE-1996}\marg{\cmd{trackeddialect}}\comment{} +Tracked dialect label: \cmd{trackeddialect}. +\gls{IfTrackedDialectHasMapping}\marg{\cmd{trackeddialect}}\comment{} +\marg{Has mapping: \gls{GetTrackedDialectToMapping}\marg{\cmd{trackeddialect}}}\comment{} +\marg{No mapping}. +\end{codeenv} +In this case no dialect label is found. The result is: +\begin{result} +Tracked dialect label: . No mapping. +\end{result} +This is because the document doesn't have a dialect that matches +both the language \emph{and} region. As from \sty{tracklang} version +1.3.6, \gls{GetTrackedDialectToMapping} sets: +\nosecformatdef{TrackedDialectClosestSubMatch} +to the closest dialect label that has the same root language if the +exact match isn't found. This will be empty if there's no tracked +dialect with the given root language (and may also be empty if an +exact match is found). + +Returning to \sty{glossaries-extra} with the original text stored in +the \field{user1} field (identified by \gls{glsxtruserfield} in the +\abbrstyle{long-short-user} style) and the language tag stored in +the \field{user2} field, then if you have at least version 1.32 of +\sty{glossaries-extra} and version 1.3.6 of \sty{tracklang} you +can use: +\nosecformatdef{GlsXtrForeignText} +to encapsulate \meta{text} with: +\nosecformatdef{foreignlanguage} +where the field containing the appropriate locale tag is stored in +the field given by: +\nosecformatdef{GlsXtrForeignTextField} +which defaults to the \field{userii} internal field for the entry +identified by \meta{label} (corresponding to the \field{user2} field). +For example: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[main=british,brazilian,ngerman]\marg{babel} +\cmd{usepackage}[\styopt{record}]\marg{glossaries-extra} +\strut +\gls{setabbreviationstyle}\oarg{foreignabbreviation}\marg{long-short-user} +\strut +\gls{newabbreviation}\marg{iso}\marg{ISO}\marg{International Organization for Standardization} +\strut +\gls{newabbreviation}\oarg{ + \field{user1} = \marg{Associa\gls{c}\marg{c}\gls{cs.tilde}ao Brasileria de Normas T\cs{acute}ecnicas}, + \field{user2} = \marg{pt-BR}, + \field{category} = \marg{foreignabbreviation} +} +\marg{abnt}\marg{ABNT}\marg{Brazilian National Standards Organization} +\strut +\gls{newabbreviation}\oarg{ + \field{user1} = \marg{Deutsches Institut f\gls{umlaut}ur Normung e.V.}, + \field{user2} = \marg{de-1996}, + \field{category} = \marg{foreignabbreviation} +}\marg{din}\marg{DIN}\marg{German Institute for Standardization} +\strut +\cmd{renewcommand}*\marg{\gls{glsxtruserparen}}[2]\marg{\comment{} + \gls[noindex=false]{glsxtrfullsep}\marg{\gls{param}2}\comment{} + \gls[noindex=false]{glsxtrparen} + \marg{\gls{param}1\comment{} + \gls{ifglshasfield}\marg{\gls{glsxtruserfield}}\marg{\gls{param}2}\comment{} + \marg{, \gls{emph}\marg{\gls{GlsXtrForeignText}\marg{\gls{param}2}\marg{\gls{glscurrentfieldvalue}}}}\comment{} + \marg{}\comment{} + }\comment{} +} +\strut +\cmd{begin}\marg{document} +\gls{gls}\marg{abnt}, \gls{gls}\marg{din}. +\cmd{end}\marg{document} +\end{codeenv} +This essentially uses the earlier \sty{tracklang} code where an +extra \gls{ifdefempty} is inserted, which sets the equivalent of +\csfmt{trackeddialect} in the above to \gls{TrackedDialectClosestSubMatch}. If +the test for the captions hook is false, then \gls{foreignlanguage} +isn't used. + + +\chapter{Symbols} +\label{sec:symbols} + +\Sectionref{sec:userkeys} described the \field{symbol} key, which can +be used to additionally provide a symbol. For example: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\marg{\gls[noindex=false]{siunitx}}\comment{provides \gls{si}} +\cmd{usepackage}\marg{glossaries} +\strut +\gls{newglossaryentry}\marg{length}\comment{label} +\marg{\comment{settings:} + \field{name} = \marg{length}, + \field{symbol} = \marg{\gls{si}\marg{\cmd{metre}}}, + \field{description} = \marg{measurement between two points} +} +\strut +\gls{newglossaryentry}\marg{area}\comment{label} +\marg{\comment{settings:} + \field{name} = \marg{area}, + \field{symbol} = \marg{\gls[noindex=false]{si}\marg{\cmd{metre}\cmd{squared}}}, + \field{description} = \marg{measurement of a surface} +} +\strut +\cmd{begin}\marg{document} +Measurements: \gls{gls}\marg{length} (\gls{glssymbol}\marg{length}) and +\gls{gls}\marg{area} (\gls{glssymbol}\marg{area}). +\cmd{end}\marg{document} +\end{codeenv} +This produces: +\begin{result} +Measurements: \gls{ex.length} (\glssymbol{ex.length}) and +\gls{ex.area} (\glssymbol{ex.area}). +\end{result} + +It may be that you prefer to have the symbol in the \field{name} +field instead. The example document below is a modification of the +above and uses the \idx{postlinkhook} to append the description on +\idx{firstuse} (see \sectionref{sec:postlinkhooks}). +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\marg{siunitx} +\cmd{usepackage}\marg{glossaries-extra} +\strut +\gls[noindex=false]{glsnoexpandfields} \comment{name field contains \gls{si}} +\strut +\gls{glsdefpostlink}\marg{symbol}\marg{\gls{glsxtrpostlinkAddDescOnFirstUse}} +\strut +\gls{newglossaryentry}\marg{length}\comment{label} +\marg{\comment{settings:} + \field{name} = \marg{\gls{si}\marg{\cmd{metre}}}, + \field{description} = \marg{length}, + \field{category} = \marg{symbol} +} +\strut +\gls{newglossaryentry}\marg{area}\comment{label} +\marg{\comment{settings:} + \field{name} = \marg{\gls{si}\marg{\cmd{metre}\cmd{squared}}}, + \field{description} = \marg{area}, + \field{category} = \marg{symbol} +} +\strut +\cmd{begin}\marg{document} +First use: \gls{gls}\marg{length} and \gls{gls}\marg{area}. +Next use: \gls{gls}\marg{length} and \gls{gls}\marg{area}. +\cmd{end}\marg{document} +\end{codeenv} +Note the need for \gls{glsnoexpandfields} (described in +\sectionref{sec:robust}). This wasn't required in the previous +example because the \sty{siunitx} commands were in the +\field{symbol} field, which isn't expanded by default. The +\field{name} field also isn't expanded by default, but its value is +copied to the \field{text} and \field{first} fields, which are +expanded by default. If \gls{glsnoexpandfields} is omitted from the +above document, the following error would occur: +\begin{verbatim} +! Undefined control sequence. +\@glo@name ->\si {\metre + } +\end{verbatim} +Although \gls{si} is robust, commands like \csfmt{metre} and +\csfmt{squared} are only available within the argument of \gls{si} +(and other similar commands provided by \sty{siunitx}) and so break +in expandable contexts. +With \gls{glsnoexpandfields}, the document compiles correctly and +produces: +\begin{result} +\glsdefpostlink{symbol}{\glsxtrpostlinkAddDescOnFirstUse}% +First use: \gls{ex2.length} and \gls{ex2.area}. +Next use: \gls{ex2.length} and \gls{ex2.area}. +\end{result} + +The \sty{glossaries-extra}['s] \styopt{symbols} package option +provides the command +\nosecformatdef{glsxtrnewsymbol} +which is a shortcut for +\begin{codeenv} +\gls{newglossaryentry}\margm{label}\marg{\field{name}=\margm{symbol},\field{category}=\marg{symbol},\gls[noindex=false]{field.sort}=\margm{label}, +\gls[noindex=false]{field.type}=\marg{symbols},\meta{\keyvallist}} +\end{codeenv} +So the above document can be changed to: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\marg{siunitx} +\cmd{usepackage}[\styopt{symbols}]\marg{glossaries-extra} +\strut +\gls{glsnoexpandfields} +\strut +\gls{glsdefpostlink}\marg{symbol}\marg{\gls{glsxtrpostlinkAddDescOnFirstUse}} +\strut +\gls{glsxtrnewsymbol}\oarg{\field{description} = \marg{length}}\marg{length}\marg{\gls{si}\marg{\cmd{metre}}} +\strut +\gls{glsxtrnewsymbol}\oarg{\field{description} = \marg{area}}\marg{area}\marg{\gls{si}\marg{\cmd{metre}\cmd{squared}}} +\strut +\cmd{begin}{document} +First use: \gls{gls}\marg{length} and \gls{gls}\marg{area}. +Next use: \gls{gls}\marg{length} and \gls{gls}\marg{area}. +\cmd{end}\marg{document} +\end{codeenv} +The result is the same. + +\section{Functions} +\label{sec:functions} + +Some symbols may represent functions. For example: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[\styopt{symbols}]\marg{glossaries-extra} +\strut +\gls{glsnoexpandfields} +\strut +\gls{glsxtrnewsymbol} + \oarg{\field{description} = \marg{derivative}} + \marg{deriv}\comment{label} + \marg{\gls{ensuremath}\marg{f'(x)}}\comment{symbol} +\strut +\cmd{begin}\marg{document} +The derivative is denoted \gls{gls}\marg{deriv}. +\cmd{end}\marg{document} +\end{codeenv} +This produces: +\begin{result} +The derivative is denoted \gls{ex.deriv}. +\end{result} +What if I need to change the variable for a specific instance, for +example, if I want $f'(x_i)$ instead of $f'(x)$? I can just use: +\begin{codeenv} +The gradient at \gls{mshiftchar}x\gls{sbchar}i\gls{mshiftchar} is \gls{mshiftchar}f'(x\gls{sbchar}i)\gls{mshiftchar}. +\end{codeenv} +So far, none of the example documents have a glossary or list of +terms. The ultimate aim when using the \styfmt{glossaries} package +is to ensure consistent formatting and notation, and, where +applicable, include a list of all terms referenced in the document. +The use of commands like \gls{gls} helps to achieve this. If the +notation needs to be changed, only the entry definition (and +associated formatting commands) should need to be redefined without +having to go through the whole document changing the code. Using +commands like \gls{gls} also identifies which entries need to be +included in the list of terms and, if \sty{hyperref} is loaded, can +be hyperlinked to the relevant place in that list (see +\sectionref{sec:displaygloss}). + +So explicitly using \verb|f'(x_i)| won't index the \code{deriv} entry +or mark it has having been used or create a hyperlink. One +possibility is to use one of the following commands: +\nosecformatdef{glslink} +\nosecformatdef{glsdisp} +They both work in much the same way, indexing the entry and +displaying \meta{text} as the \idx{link-text}. The only difference is +that \gls{glsdisp} also unsets the \idx{firstuseflag}, which marks the entry +as having been used. For example: +\begin{codeenv} +The gradient at \gls{mshiftchar}x\gls{sbchar}i\gls{mshiftchar} is \gls{glslink}\marg{deriv}\marg{\gls{mshiftchar}f'(x\gls{sbchar}i)\gls{mshiftchar}}. +\end{codeenv} +This solves the problem of ensuring that the \code{deriv} entry is +indexed and, if \sty{hyperref} is loaded, ensures that the +\idx{link-text} has a hyperlink to the relevant place in the list of +notation, but it doesn't solve the problem of consistent formatting. + +One way of ensuring consistent formatting is to define a semantic +command. For example: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[\styopt{symbols}]\marg{glossaries-extra} +\strut +\gls{glsnoexpandfields} +\strut +\cmd{newcommand}\marg{\cmd{derivfn}}[1]\marg{f'(\gls{param}1)} +\strut +\gls{glsxtrnewsymbol} + \oarg{\field{description} = \marg{derivative}} + \marg{deriv}\comment{label} + \marg{\gls{ensuremath}\marg{\cmd{derivfn}\marg{x}}}\comment{symbol} +\strut +\cmd{begin}\marg{document} +The derivative is denoted \gls{gls}\marg{deriv}. +The gradient at \gls{mshiftchar}x\gls{sbchar}i\gls{mshiftchar} is \gls{glslink}\marg{deriv}\marg{\gls{mshiftchar}\cmd{derivfn}\marg{x\gls{sbchar}i}\gls{mshiftchar}}. +\cmd{end}\marg{document} +\end{codeenv} +This produces: +\begin{result} +\providecommand{\derivfn}[1]{f'(#1)} +The derivative is denoted \gls{ex.deriv}. +The gradient at $x_i$ is \glslink{ex.deriv}{$\derivfn{x_i}$}. +\end{result} +Now only \csfmt{derivfn} needs modifying if the notation must change. +This requires remembering both the entry label (\code{deriv} in this +case) and the associated formatting command (\csfmt{derivfn} in this +case). The \sty{glossaries-extra} package provides a way of storing +the associated formatting command in one of the additional keys (see +\sectionref{sec:userkeys}). The field is identified by: +\nosecformatdef{GlsXtrFmtField} +which defaults to \field{useri} (the internal representation of the +\field{user1} key). The value must be the name (without the leading +backslash) of a control sequence that takes a \emph{single} +mandatory argument. The above custom command \code{derivfn} +satisfies this requirement, so the entry can be defined as: +\begin{codeenv} +\gls{glsxtrnewsymbol} + \oarg{\comment{settings:} + \field{description} = \marg{derivative}, + \field{user1} = \marg{derivfn} + } + \marg{deriv}\comment{label} + \marg{\gls{ensuremath}\marg{\cmd{derivfn}\marg{x}}}\comment{symbol} +\end{codeenv} +The formatting command can now be applied using one of the +following: +\nosecformatdef{glsxtrfmt} +\nosecformatdef{glsxtrfmt*} +which internally use \gls{glslink} or: +\nosecformatdef{glsxtrentryfmt} +which doesn't (and so is more like using \gls{glsentryname}). + +So an alternative approach is: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[\styopt{symbols}]\marg{glossaries-extra} +\strut +\gls{glsnoexpandfields} +\strut +\cmd{newcommand}\marg{\cmd{derivfn}}[1]\marg{f'(\gls{param}1)} +\strut +\gls{glsxtrnewsymbol} + \oarg{\comment{settings:} + \field{description} = \marg{derivative}, + \field{user1} = \marg{derivfn} + } + \marg{deriv}\comment{label} + \marg{\gls{ensuremath}\marg{\cmd{derivfn}\marg{x}}}\comment{symbol} +\strut +\cmd{begin}\marg{document} +The derivative is denoted \gls{gls}\marg{deriv}. +The gradient at \gls{mshiftchar}x\gls{sbchar}i\gls{mshiftchar} is \gls{mshiftchar}\gls{glsxtrfmt}\marg{deriv}\marg{x\gls{sbchar}i}\gls{mshiftchar}. +\cmd{end}\marg{document} +\end{codeenv} +This again produces: +\begin{result} +The derivative is denoted \gls{ex.deriv}. +The gradient at $x_i$ is $\glsxtrfmt{ex.deriv}{x_i}$. +\end{result} + +Both the starred \gls{glsxtrfmt*} and unstarred \gls{glsxtrfmt} +format the \meta{text} argument using: +\nosecformatdef{glsxtrfmtdisplay} +where \meta{cs-name} is the control sequence name stored in the +field identified by \gls{GlsXtrFmtField} and the \meta{insert} part +is the final optional argument for the starred \gls{glsxtrfmt*} (if +provided) otherwise it's empty. If the command identified by +\meta{cs-name} doesn't exist (or if the field providing it isn't +set) then just \meta{text}\meta{insert} is done. + +\begin{important} +Nested \idx{link-text} causes problems so don't use \gls{glsxtrfmt} +in the optional part of commands like \gls{gls} or \gls{glssymbol} +or in field values that are used by those types of command. Also +don't use \gls{glsxtrfmt} within the \meta{text} or \meta{insert} +part of another instance of \gls{glsxtrfmt} or in \gls{glslink} or +\gls{glsdisp}. Use \gls{glsxtrentryfmt} instead. +\end{important} + +If more than one argument is required, then a helper macro is +needed. For example: +\begin{verbatim} +\newcommand{\iderivfn}[2][f]{#1'(#2)} +\newcommand{\derivfn}[1]{\iderivfn#1} +\end{verbatim} +Now to obtain $g'(x_i)$: +\begin{codeenv} +\gls{mshiftchar}\gls{glsxtrfmt}\marg{deriv}\marg{[g]\marg{x\gls{sbchar}i}}\gls{mshiftchar} +\end{codeenv} +Note that for this simplistic helper macro, the mandatory inner +argument needs extra braces if it consists of more than a single +token. For example: +\begin{codeenv} +\gls{mshiftchar}\gls{glsxtrfmt}\marg{deriv}\marg{\marg{x\gls{sbchar}i}}\gls{mshiftchar} +\end{codeenv} + +\section{Dealing with Automated Case-Changing} +\label{sec:symfirstuc} + +Commands like \gls{Gls} don't usually make much sense for symbols as +a change in case can cause a change in meaning. For example, +$\boldsymbol{x}$ might denote a vector and $\boldsymbol{X}$ might +denote a matrix. However, you may have a mixed list of terms +containing both symbols and words, and if you set the +\catattr{glossname} attribute to \code{firstuc}, which automatically +converts the first letter of each \field{name} to \idx{uppercase} in the +glossary, then this can cause a problem for entries where the +\field{name} starts with a symbol. The simplest solution is to +insert an empty group at the start of the \field{name} field for +such entries. For example: +\begin{codeenv} +\gls{glsxtrnewsymbol} + \oarg{\field{description} = \marg{length}}\comment{settings} + \marg{length}\comment{label} + \marg{\marg{}\gls{si}\marg{\cmd{metre}}}\comment{name} +\end{codeenv} +This is done automatically by \bibgls, but if it causes any +interference you can switch off the behaviour with +\longarg{no-mfirstuc-math-protection}. + +\chapter{Displaying the Definition} +\label{sec:displaygloss} + +The examples so far only use the defined entries in the documents +with commands like \gls{gls} or \gls{glssymbol} or +\gls{glsentrydesc}. These are useful for ensuring consistent +formatting, but it's also helpful to have a place in the document +where the term is formally defined. This can be partially solved +by including the description in parentheses on \idx{firstuse}, +either by explicitly including the description in the \field{first} +field or with the use of the \idx{postlinkhook}, but the +\idx{firstuse} might not be the most appropriate place for the +description. + +\section{Listing the Terms (Glossary)} +\label{sec:printgloss} + +If you want a complete list of all defined terms, you can use: +\nosecformatdef{printunsrtglossary} +This lists all the terms for the given glossary (identified by the +\printglossopt{type} key in \meta{options}, see +\sectionref{sec:multigloss}) according to the order of the +glossary's internal list of labels, which is typically in the order of +definition. (As each entry is defined, its label is appended to the +internal list of the associated glossary.) + +You can change the default title with the \printglossopt{title} option. For +example: +\begin{codeenv} +\gls{printunsrtglossary}\oarg{\printglossopt[Nomenclature]{title}} +\end{codeenv} +The title used in the \gls{toc} is assumed to be the same, +but you can change it with \printglossopt{toctitle}. For example: +\begin{codeenv} +\gls{printunsrtglossary}\oarg{ + \printglossopt[List of Terms and Notation]{title}, + \printglossopt[Notation]{toctitle} +} +\end{codeenv} + +The glossary style can be set with the \printglossopt{style} key +in \meta{options}. Alternatively, you can set a default style with the +\styopt{style} package option. There are many predefined styles to +choose from (see the +\href{https://www.dickimaw-books.com/gallery/glossaries-styles/}{\styfmt{glossaries} +gallery}~\cite{glossarystylesgallery}). The styles are provided in supplementary packages, some +of which are automatically loaded. Since each package adds to the +document overhead, and some require additional packages to be +loaded, when using \sty{glossaries-extra}, it's a good idea to +disable the automatic loading of all styles with \styopt{nostyles} +and then use \styopt{stylemods} to load the specific packages (along +with the \sty{glossaries-extra-stylemods} package, which patches +some of the predefined styles). For example, the +\glostyle{index} style is provided by the \styfmt{glossary-tree} +package, so \styopt[tree]{stylemods} will automatically load +\styfmt{glossary-tree} and provide all the tree-like styles, +including \glostyle{index}. The \styopt{stylemods} value may be a +comma-separated list, so to load both \styfmt{glossary-tree} and +\styfmt{glossary-long}, use \styopt[tree,long]{stylemods}. +For example: +\begin{codeenv} +\cmd{documentclass}\marg{scrartcl} +\cmd{usepackage}\marg{\gls[noindex=false]{mhchem}}\comment{provides \gls{ce}} +\cmd{usepackage}[\styopt[dot]{postpunc},\comment{full stop after description} + \styopt{nostyles},\comment{don't load default style packages} +\comment{load glossaries-extra-stylemods.sty and glossary-tree.sty:} + \styopt[tree]{stylemods} +]\marg{glossaries-extra} +\strut +\gls{newglossaryentry}\marg{area} +\marg{ + \field{name} = \marg{\gls{ensuremath}\marg{A}}, + \field{description} = \marg{area} +} +\strut +\gls{newglossaryentry}\marg{amethyst} +\marg{ + \field{name} = \marg{amethyst}, + \field{description} = \marg{a purple type of quartz}, + \field{symbol} = \marg{\gls[noindex=false]{ce}\marg{SiO2}} +} +\strut +\gls{newglossaryentry}\marg{circumference} +\marg{ + \field{name} = \marg{\gls{ensuremath}\marg{C}}, + \field{description} = \marg{circumference} +} +\strut +\gls{newglossaryentry}\marg{duck} +\marg{ + \field{name} = \marg{duck}, + \field{description} = \marg{a waterbird with webbed feet} +} +\gls{newglossaryentry}\marg{goose} +\marg{ + \field{name} = \marg{goose}, + \field{description} = \marg{a large waterbird with a long neck, short legs, +webbed feet and a short broad bill} +} +\strut +\gls{newglossaryentry}\marg{radius} +\marg{ + \field{name} = \marg{\gls{ensuremath}\marg{r}}, + \field{description} = \marg{radius} +} +\strut +\gls{newglossaryentry}\marg{pi} +\marg{ + \field{name} = \marg{\gls{ensuremath}\marg{\cmd{pi}}}, + \field{description} = \marg{Archimedes' constant} +} +\strut +\cmd{begin}\marg{document} +\gls{printunsrtglossary}\oarg{\printglossopt[index]{style}} +\cmd{end}\marg{document} +\end{codeenv} +This produces: +\begin{result} +\glsaddeach{ex3.goose,ex3.duck,ex2.amethyst,standalone.pi,% +standalone.circumference,standalone.area,standalone.radius}% +\setupglossaries{toc=false,section}% +\glossariesextrasetup{postpunc=dot}% +\renewcommand{\glsxtrgroupfield}{useriii}% +\renewcommand*{\printunsrtglossaryentryprocesshook}[1]{% + \glsifcategory{#1}{standalone}{}{\printunsrtglossaryskipentry}% +}% +\printunsrtglossary[style=index,title=Glossary,nonumberlist,target=false] +\end{result} +The \glostyle{index} glossary style checks if the \field{symbol} +field has been set. If it has, then the symbol is added in +parentheses (as in the amethyst example). Only some of the styles +include the \field{symbol} field. (Table~15.1 in the +\sty{glossaries} user manual~\cite{glossaries} gives an overview of +the features supported by the predefined styles.) + +The \glostyle{bookindex} style is provided by the +\isty{glossary-bookindex} package, which is distributed with +\sty{glossaries-extra}. This style is designed for indexes +and omits both the description and the symbol by default. It's +customized specifically for use with \bibgls. Without the +\idxpl{locationlist} obtained by \bibgls, this simply becomes a list +of the \field{name} values for each term. + +The glossary is sub-divided into letter groups. By default, these +sub-groups are separated with a vertical gap (for example, between +duck and goose above). In the above example, the letter group is +determined by the first character of the \field{sort} field. Since the +default behaviour of both \sty{glossaries} and +\sty{glossaries-extra} is to use \idx{makeindex}, the \field{sort} +field (which is used by \idx{makeindex}) is set to the value of the +\field{name} field (unless explicitly set) and then sanitized. + +When using \gls{printunsrtglossary}, the \field{sort} field is +irrelevant except to determine the letter group (unless the +\field{group} field has been defined). The sub-group +heading is displayed by some styles, such as the +\glostyle{indexgroup} and \glostyle{bookindex} styles. For example, with: +\begin{codeenv} +\gls{printunsrtglossary}\oarg{\printglossopt[indexgroup]{style}} +\end{codeenv} +The glossary is now: +\begin{result} +\setupglossaries{toc=false,section}% +\glossariesextrasetup{postpunc=dot}% +\renewcommand{\glsxtrgroupfield}{useriii}% +\renewcommand*{\printunsrtglossaryentryprocesshook}[1]{% + \glsifcategory{#1}{standalone}{}{\printunsrtglossaryskipentry}% +}% +\printunsrtglossary[style=indexgroup,title=Glossary,nonumberlist,target=false] +\end{result} +This explains why there's a gap between $A$ (area) and amethyst as +they don't belong to the same letter group. The \field{sort} field +for the \code{area} entry is \verb|\ensuremath{A}| which has been +sanitized, so it starts with a literal backslash (\idx{backslashchar}). +This means that \code{area} is assigned to the symbols letter group. The +symbols group occurs three times, because the list is following the +order of definition. + +\subsection{Groups and Locations} +\label{sec:group} + +\begin{important} +The \field{group} and \field{location} fields are considered +internal fields by \bibgls. They may be referenced within the +document, but they should not be assigned in the \ext{bib} file. +\bibgls\ assigns these fields according to the resource options and +command line switches. Explicitly assigning them can cause +unexpected results. See also \sectionref{sec:logicaldivisions} of +the \bibgls\ manual. +\end{important} + +The \field{group} key isn't defined by default, but if it is defined +then \gls{printunsrtglossary} will use the \field{group} field +instead of trying to determine the group from the first character of +the \field{sort} field (as in the example above). The value of the +\field{group} field must be a label (see \sectionref{sec:labels}). +A title may be assigned to a group with: +\nosecformatdef{glsxtrsetgrouptitle} +If a title hasn't been assigned, the label is used as the title. +The above command is the preferred form, but the base +\sty{glossaries} package checks for a control sequence in the form +\csfmt{\meta{label}groupname} where \meta{label} is the group label. +The \sty{glossaries-extra} package also recognises this form to +ensure backward-compatibility. If the \field{group} field is empty +the sub-group won't have a title. + +For example, the following defines the \field{group} field with a +custom command \csfmt{grouplabel} (that's not needed, but it's +required by the \gls{glsaddstoragekey} syntax): +\begin{codeenv} +\cmd{documentclass}\marg{scrartcl} +\cmd{usepackage}\marg{mhchem} +\cmd{usepackage}[\styopt[dot]{postpunc},\comment{full stop after description} + \styopt{nostyles},\comment{don't load default style packages} + \styopt[tree]{stylemods}\comment{load glossary-tree.sty and patch styles} +]\marg{glossaries-extra} +\strut +\gls{glsaddstoragekey}\marg{group}\marg{}\marg{\cmd{grouplabel}} +\gls{glsxtrsetgrouptitle}\marg{greek}\marg{Greek Symbols} +\strut +\gls{newglossaryentry}\marg{area} +\marg{ + \field{name} = \marg{\gls{ensuremath}\marg{A}}, + \field{description} = \marg{area}, + \field{group} = \marg{A} +} +\strut +\gls{newglossaryentry}\marg{amethyst} +\marg{ + \field{name} = \marg{amethyst}, + \field{description} = \marg{a purple type of quartz}, + \field{symbol} = \marg{\gls{ce}\marg{SiO2}}, + \field{group} = \marg{A} +} +\strut +\gls{newglossaryentry}\marg{circumference} +\marg{ + \field{name} = \marg{\gls{ensuremath}\marg{C}}, + \field{description} = \marg{circumference}, + \field{group} = \marg{C} +} +\strut +\gls{newglossaryentry}\marg{duck} +\marg{ + \field{name} = \marg{duck}, + \field{description} = \marg{a waterbird with webbed feet}, + \field{group} = \marg{D} +} +\strut +\gls{newglossaryentry}\marg{goose} +\marg{ + \field{name} = \marg{goose}, + \field{description} = \marg{a large waterbird with a long neck, short legs, + webbed feet and a short broad bill}, + \field{group} = \marg{G} +} +\strut +\gls{newglossaryentry}\marg{radius} +\marg{ + \field{name} = \marg{\gls{ensuremath}\marg{r}}, + \field{description} = \marg{radius}, + \field{group} = \marg{R} +} +\strut +\gls{newglossaryentry}\marg{pi} +\marg{ + \field{name} = \marg{\gls{ensuremath}\marg{\cmd{pi}}}, + \field{description} = \marg{Archimedes' constant}, + \field{group} = \marg{greek} +} +\strut +\cmd{begin}\marg{document} +\gls{printunsrtglossary}\oarg{\printglossopt[indexgroup]{style}} +\cmd{end}\marg{document} +\end{codeenv} +This produces: +\begin{result} +\setupglossaries{toc=false,section}% +\glossariesextrasetup{postpunc=dot}% +\renewcommand{\glsxtrgroupfield}{useriv}% +\glsxtrsetgrouptitle{greek}{Greek Symbols}% +\renewcommand*{\printunsrtglossaryentryprocesshook}[1]{% + \glsifcategory{#1}{standalone}{}{\printunsrtglossaryskipentry}% +}% +\printunsrtglossary[style=indexgroup,title=Glossary,nonumberlist,target=false] +\end{result} +Note that with this method \emph{every} entry must be assigned a +group or it will be assigned to the empty group. + +Similarly, if the \field{location} field is defined, you can use it +to provide a \idx{locationlist}. The \styopt{record} package option +conveniently defines both \field{group} and \field{location}, so the +following can be used instead: +\begin{codeenv} +\cmd{usepackage}[ + \styopt{record},\comment{provides group and location fields (and other stuff)} + postpunc=dot,nostyles,stylemods={tree}]\marg{glossaries-extra} +\strut +\gls{newglossaryentry}\marg{area} +\marg{ + \field{name} = \marg{\gls{ensuremath}\marg{A}}, + \field{description} = \marg{area}, + \field{group} = \marg{A}, + \field{location} = \marg{page 1} +} +\end{codeenv} +This very quickly becomes tedious and prone to errors as the entries +have to be ordered manually, and every entry must be assigned the +group and location (if required). Every time the location changes +through edits to the document, the locations must be updated. +However, this is exactly the method that \bibgls\ uses, but it does +it automatically for you by selecting the required data from one or +more \ext{bib} files and then creating a file containing all the +glossary entry definitions with the fields set appropriately. The \ext{aux} +file provides \bibgls\ with the indexing information so that it +knows which entries to select and what the locations are, and how to +order the definitions. See \sectionref{sec:bib2gls} for further +information. + +\subsection{Homographs and Hierarchical Terms} +\label{sec:parent} + +An entry may be assigned a parent with the \field{parent} key. The +value must be the label of an entry that's already defined. You can +test if an entry has the \field{parent} field set with: +\nosecformatdef{ifglshasparent} +If the \field{name} key is omitted, the value is assumed to be the same as +the parent's \field{name}. +For example: +\begin{codeenv} +\comment{parent:} +\gls{newglossaryentry}\marg{glossary}\marg{\field{name}=\marg{glossary},\field{description}=\marg{}} +\comment{children:} +\gls{newglossaryentry}\marg{glossarycol} +\marg{\comment{settings:} + \field{parent} = \marg{glossary},\comment{parent label} + \field{description} = \marg{collection of glosses} +} +\gls{newglossaryentry}\marg{glossarylist} +\marg{\comment{settings:} + \field{parent} = \marg{glossary},\comment{parent label} + \field{description} = \marg{list of technical words} +} +\end{codeenv} +In this case the entry with the label \code{glossary} is the +\pidx{parent-entry}, and the entries with +the labels \code{glossarycol} and \code{glossarylist} are +\pidxpl{child-entry} (or sub-items). An entry that doesn't have a +parent is a main or top-level or level~0 item. In this case, the +\idxpl{child-entry} don't have the \field{name} key, so the name is +obtained from the parent's name. This is an example of a +\pidx{homograph}, where two words with different meanings +have the same spelling. The parent entry has an empty description. + +Here's another example: +\begin{codeenv} +\comment{parent:} +\gls{newglossaryentry}\marg{mineral}\comment{label} +\marg{\comment{settings:} + \field{name} = \marg{mineral}, + \field{description} = \marg{natural inorganic substance} +} +\comment{sub-entries:} +\gls{newglossaryentry}\marg{quartz}\comment{label} +\marg{ + \field{parent} = \marg{mineral},\comment{parent label} + \field{name} = \marg{quartz}, + \field{description} = \marg{hard mineral consisting of silica} +} +\gls{newglossaryentry}\marg{amethyst}\comment{label} +\marg{ + \field{parent} = \marg{quartz},\comment{parent label} + \field{name} = \marg{amethyst}, + \field{description} = \marg{a purple type of quartz} +} +\end{codeenv} +In this case, the \idxpl{child-entry} have the \field{name} key +set. This is an example of a set of \pidxpl{hierarchical-entry}, +where each \idx{child-entry} is a sub-category of the parent. +Some glossary styles are appropriate for \idxpl{homograph} and some +are appropriate for \idxpl{hierarchical-entry} and some are only +appropriate for flat glossaries (no child entries). +For example, the \glostyle{index}, \glostyle{indexgroup}, +\glostyle{tree} and \glostyle{treegroup} styles are appropriate +for \idxpl{hierarchical-entry}: +\begin{codeenv} +\cmd{documentclass}\marg{scrartcl} +\strut +\cmd{usepackage}[\styopt{nostyles},\styopt[dot]{postpunc},\styopt[tree]{stylemods}]\marg{glossaries-extra} +\strut +\gls{newglossaryentry}\marg{animal} +\marg{ + \field{name} = \marg{animal}, + \field{description} = \marg{living organism with a nervous system and sense organs + that can move independently} +} +\strut +\gls{newglossaryentry}\marg{bird} +\marg{ + \field{parent} = \marg{animal}, + \field{name} = \marg{bird}, + \field{description} = \marg{warm-blooded egg-laying animal with feathers, wings + and a beak} +} +\strut +\gls{newglossaryentry}\marg{duck} +\marg{ + \field{parent} = \marg{bird}, + \field{name} = \marg{duck}, + \field{description} = \marg{a waterbird with webbed feet} +} +\strut +\gls{newglossaryentry}\marg{goose} +\marg{ + \field{parent} = \marg{bird}, + \field{name} = \marg{goose}, + \field{description} = \marg{a large waterbird with a long neck, short legs, + webbed feet and a short broad bill} +} +\strut +\gls{newglossaryentry}\marg{mineral} +\marg{ + \field{name} = \marg{mineral}, + \field{description} = \marg{natural inorganic substance} +} +\strut +\gls{newglossaryentry}\marg{calcite}\comment{label} +\marg{ + \field{parent} = \marg{mineral},\comment{parent label} + \field{name} = \marg{calcite}, + \field{description} = \marg{a carbonate mineral} +} +\strut +\gls{newglossaryentry}\marg{quartz} +\marg{ + \field{parent} = \marg{mineral}, + \field{name} = \marg{quartz}, + \field{description} = \marg{hard mineral consisting of silica} +} +\strut +\gls{newglossaryentry}\marg{amethyst} +\marg{ + \field{parent} = \marg{quartz}, + \field{name} = \marg{amethyst}, + \field{description} = \marg{a purple type of quartz}, +} +\strut +\gls{newglossaryentry}\marg{citrine} +\marg{ + \field{parent} = \marg{quartz}, + \field{name} = \marg{citrine}, + \field{description} = \marg{a form of quartz with a colour ranging + from pale yellow to brown due to ferric impurities} +} +\strut +\cmd{begin}\marg{document} +\gls{printunsrtglossary}\oarg{style=indexgroup} +\cmd{end}\marg{document} +\end{codeenv} +This produces: +\begin{result} +\glsaddeach{hier.animal,hier.bird,hier.duck,hier.goose,hier.mineral,% +hier.calcite,hier.quartz,hier.amethyst,hier.citrine}% +\setupglossaries{toc=false,section}% +\glossariesextrasetup{postpunc=dot}% +\renewcommand*{\printunsrtglossaryentryprocesshook}[1]{% + \glsifcategory{#1}{hierarchical}{}{\printunsrtglossaryskipentry}% +}% +\printunsrtglossary[style=indexgroup,title=Glossary,nonumberlist,target=false] +\end{result} + +The \glostyle{treenoname} and \glostyle{treenonamegroup} styles are +appropriate for \idxpl{homograph}. These are usually best with the +\styopt{subentrycounter} package option, which defines the +\counter{glossarysubentry} counter that's incremented and +displayed for every level~1 entry (that is, an entry with a parent +but not a grandparent). If the \styopt{entrycounter} option is also +used, \counter{glossaryentry} is set as the master counter for +\counter{glossarysubentry} (although it's not included in the +display form of that counter), but \styopt{subentrycounter} may be used +without \styopt{entrycounter}, in which case +\counter{glossarysubentry} has no master counter. If +\styopt{subentrycounter} is used as a package option and +\styopt{entrycounter} is later switched on outside of the package +option list (through \gls{setupglossaries} or in the optional argument of +\gls{printunsrtglossary}) then it won't be made the master counter. + +For example: +\begin{codeenv} +\cmd{documentclass}\marg{scrartcl} +\strut +\cmd{usepackage}[\styopt{subentrycounter},\comment{create glossarysubentry counter} + \styopt[dot]{postpunc},\comment{append full stop after description} + \styopt{nostyles},\styopt[tree]{stylemods}]\marg{glossaries-extra} +\strut +\gls{newglossaryentry}\marg{bow1} +\marg{ + \field{name}=\marg{bow}, + \field{description}=\marg{(rhymes with toe)} +} +\strut +\gls{newglossaryentry}\marg{bowknot} +\marg{ + \field{parent} = \marg{bow1}, + \field{description} = \marg{a knot tied with two loops and loose ends} +} +\strut +\gls{newglossaryentry}\marg{bowweapon} +\marg{ + \field{parent} = \marg{bow1}, + \field{description} = \marg{a weapon for shooting arrows, made of curved wood + joined at both ends with taut string} +} +\strut +\gls{newglossaryentry}\marg{bow2} +\marg{ + \field{name}=\marg{bow}, + \field{description}=\marg{(rhymes with cow)} +} +\strut +\gls{newglossaryentry}\marg{bowbend} +\marg{ + \field{parent} = \marg{bow2}, + \field{description} = \marg{bend head or upper body} +} +\strut +\gls{newglossaryentry}\marg{bowpressure} +\marg{ + \field{parent} = \marg{bow2}, + \field{description} = \marg{give in to pressure} +} +\strut +\gls{newglossaryentry}\marg{bow3} +\marg{ + \field{name}=\marg{bow}, + \field{description}=\marg{(also bows) the front end of a ship} +} +\strut +\gls{newglossaryentry}\marg{glossary}\marg{\field{name}=\marg{glossary},\field{description}=\marg{}} +\strut +\gls{newglossaryentry}\marg{glossarycol} +\marg{ + \field{parent} = \marg{glossary}, + \field{description} = \marg{collection of glosses} +} +\strut +\gls{newglossaryentry}\marg{glossarylist} +\marg{ + \field{parent} = \marg{glossary}, + \field{description} = \marg{list of technical words} +} +\strut +\cmd{begin}\marg{document} +\gls{printunsrtglossary}\oarg{style=treenoname} +\cmd{end}\marg{document} +\end{codeenv} +This produces +\begin{result} +\glsaddeach{hom.bow1,hom.bowknot,hom.bowweapon,% +hom.bow2,hom.bowbend,hom.bowpressure,hom.bow3,% +hom.glossary,hom.glossarycol,hom.glossarylist}% +\setupglossaries{toc=false,section,subentrycounter}% +\glossariesextrasetup{postpunc=dot}% +\renewcommand*{\printunsrtglossaryentryprocesshook}[1]{% + \glsifcategory{#1}{homograph}{}{\printunsrtglossaryskipentry}% +}% +\printunsrtglossary[style=treenoname,title=Glossary,nonumberlist,target=false] +\end{result} +The empty description for the top-level \code{glossary} entry has +caused an odd effect with a space occurring between the name and the +post-description punctuation. This can be removed by redefining: +\nosecformatdef{glstreenonamedesc} +so that it checks if the \field{description} field has been set with: +\nosecformatdef{ifglshasdesc} +For example: +\begin{codeenv} +\cmd{renewcommand}\marg{\gls{glstreenonamedesc}}[1]\marg{\comment{} + \gls{ifglshasdesc}\marg{\gls{param}1} + \marg{\gls[noindex=false]{glstreepredesc}\gls{glossentrydesc}\marg{\gls{param}1}\gls{glspostdescription}} + \marg{}\comment{do nothing, description field is empty} +} +\end{codeenv} +Another variation is to check if the entry has children add use a +colon instead of a \idx{full-stop}. The base \sty{glossaries} +package provides: +\nosecformatdef{ifglshaschildren} +However this method is very inefficient as it has to iterate over +all defined entries and check if any have the \field{parent} field +set to \meta{entry label}. A more efficient method can be obtained +with \bibgls\ and the \csopt{save-child-count} resource option, +which will save the number of child entries that have been indexed +in an internal field labelled \field{childcount} and a list of child +entry labels is stored in the internal field labelled +\field{childlist}. In this case, a more efficient method is to use: +\nosecformatdef{GlsXtrIfHasNonZeroChildCount} +which checks the \field{childcount} field for a non-zero value. +If you don't use \bibgls, this command will always do \meta{false} +(unless you explicitly set the internal fields to the correct +values, which is tedious and has to be updated whenever +definitions are added, deleted or have the \field{parent} field +changed). + +Another variation could use custom fields (see +\sectionref{sec:userkeys}) to store the pronunciation guide (\qt{rhymes +with \ldots}) and the alternative version (\qt{also \ldots}) as well +as other information, such as whether the word is a noun or verb. + +\subsection{Multiple Glossaries} +\label{sec:multigloss} + +The default glossary has the label \code{main}, but it can also be referenced +with: +\nosecformatdef{glsdefaulttype} +The \styopt{nomain} package option suppresses the creation of the +\code{main} glossary, in which case \gls{glsdefaulttype} will be set to +the first glossary to be defined. (There must be at least one +glossary defined, so if you use \styopt{nomain} you must provide +another default.) If you use the \styopt{entrycounter} package +option, the associated counter isn't reset at the start of the +glossary. If you have multiple glossaries and you need it to be reset, add: +\nosecformatdef{glsresetentrycounter} +before the start of the appropriate glossary. + +Abbreviations defined with \gls{newabbreviation} +(see \sectionref{sec:abbreviations}) are, by default, assigned to the glossary +given by: +\nosecformatdef{glsxtrabbrvtype} +This initially expands to \gls{glsdefaulttype}, but the +\styopt{abbreviations} option redefines this to \code{abbreviations} +and creates a glossary with that label. + +Abbreviations defined with \gls{newacronym} are, by default, +assigned to the glossary given by: +\nosecformatdef{acronymtype} +This initially expands to \gls{glsdefaulttype}, but the +\styopt{abbreviations} option redefines this to +\gls{glsxtrabbrvtype}. However, the \styopt{acronyms} option +redefines \gls{acronymtype} to \code{acronym} and creates a glossary +with that label. So if you use both the \styopt{abbreviations} and +\styopt{acronyms} package options, you will have two extra +glossaries created, one as the default for \gls{newabbreviation} and +the other as the default for \gls{newacronym}. + +The \styopt{symbols} package option creates a glossary with the +label \code{symbols} and defines \gls{glsxtrnewsymbol} (see +\sectionref{sec:symbols}) which sets the \field{type} to +\code{symbols}. There are also similar package options +\styopt{numbers} and \styopt{index}, which create the \code{numbers} +glossary (and \gls{glsxtrnewnumber}) and the \code{index} glossary +(and \gls{newterm}). + +In each case, the default type can be overridden when defining an +entry by using the \field{type} key in the assignment list. The +value must be the label identifying a defined glossary. + +You can provide your own custom glossary using: +\nosecformatdef{newglossary*} +where \meta{type} is the label used to identify the glossary and +\meta{title} is the default title used by \gls{printunsrtglossary}. +(The unstarred version has a different syntax and is only applicable +with \gls{makeindex} or \gls{xindy}.) For example: +\begin{codeenv} +\gls{newglossary*}\marg{measurements}\marg{SI Units} +\gls{newglossaryentry}\marg{length} +\marg{\comment{settings:} + \field{name} = \marg{\gls{si}\marg{\cmd{metre}}}, + \field{description} = \marg{length}, + \field{type} = \marg{measurements}\comment{glossary label} +} +\end{codeenv} +In this case, the label identifying the new glossary is +\code{measurements} and the title is \qt{SI Units}. + +You can specify the glossary using the \printglossopt{type} setting +in the optional argument of \gls{printunsrtglossary}. For example, +the above \code{measurements} glossary can be displayed with: +\begin{codeenv} +\gls{printunsrtglossary}\oarg{\printglossopt[measurements]{type}} +\end{codeenv} +For convenience, there's a command that iterates over all defined +glossaries (in the order of definition) and does +\gls{printunsrtglossary}\oarg{\printglossopt[\meta{label}]{type}} +for each glossary: +\nosecformatdef{printunsrtglossaries} +There's no optional argument for this command. When creating +glossaries with package options, such as \styopt{abbreviations}, you +may find an unexpected order as the options aren't always processed +in the order in which they were specified. (Some +\sty{glossaries-extra} options are passed to the base +\sty{glossaries} package and are processed when that package is +internally loaded not when the extension options are processed.) In +which case you need to use \gls{printunsrtglossary} for each +glossary in the required order. You will also need to do this if the +glossary settings are different. (For example, if one glossary needs +to use the \glostyle{tree} style and another needs to use the +\glostyle{treenoname} style.) + +You can also define an \pidx{ignoredglossary}, which is ignored by +\gls{printunsrtglossaries}. This is a useful way of creating a +glossary for common terms that shouldn't appear in a list or for +stand-alone entries (see \sectionref{sec:standalone}). The unstarred +form: +\nosecformatdef{newignoredglossary} +is useful for common terms where the list won't be displayed as it +automatically suppresses hyperlinks for entries assigned to that +glossary. The starred form: +\nosecformatdef{newignoredglossary*} +is useful for stand-alone entries as it doesn't automatically +suppress the hyperlinks. +Although \gls{printunsrtglossaries} skips \idxpl{ignoredglossary}, +it's still possible to display an \idx{ignoredglossary} with +\gls{printunsrtglossary} but you'll need to use the +\printglossopt{title} option to override the default title. + +\subsection{Redisplaying or Filtering a Glossary} +\label{sec:printglossagain} + +It's possible to use \gls{printunsrtglossary} multiple times for the +same glossary, but if you have hyperlinks you will need to either +suppress the targets with \printglossopt[false]{target} or change +the target name (see \sectionref{sec:targetnames}). + +The starred form of \gls{printunsrtglossary} has an extra +argument: +\nosecformatdef{printunsrtglossary*} +This may be used to make local assignments. It's equivalent to: +\begin{codeenv} +\cmd{begingroup} \meta{code}\gls{printunsrtglossary}\oargm{options}\cmd{endgroup} +\end{codeenv} +For example, if the \field{group} key has been defined (see +\sectionref{sec:group}) you can locally switch to a different field +for the group label by redefining: +\nosecformatdef{glsxtrgroupfield} +within \meta{code}. +For example, if the \field{secondarygroup} field has been defined: +\begin{codeenv} +\gls{printunsrtglossary*}\marg{\comment{} + \cmd{renewcommand}\marg{\gls{glsxtrgroupfield}}\marg{secondarygroup}\comment{} +} +\end{codeenv} +Note that this just changes the group labels. The order is still +according to the glossary's internal list of labels. + +Unlike \gls{printglossary} (used with \gls{makeindex} and +\gls{xindy}) which inputs a file containing the code to typeset the glossary, +\gls{printunsrtglossary} iterates over the labels defined in the +given glossary and adds the appropriate code to an internal command. +Once the construction of the internal command is completed, it's +then performed. (The construction of this internal command is done +to avoid complications when iterating within \env{tabular}-like +environments, as some of the styles use \env{longtable} or +\env{supertabular}.) There's a hook just before the internal command is +expanded: +\nosecformatdef{printunsrtglossarypredoglossary} +The glossary header and preamble are displayed before +the loop starts, so this hook won't change them (but you can make +local changes in \meta{code} outside of the hook). +The style is also set before the loop, but the start +and end of the \env{theglossary} environment (which is defined by +the glossary styles) is included in the internal command, so minor +adjustments to the style can be made in this hook. + +There's another hook that's performed at each iteration: +\nosecformatdef{printunsrtglossaryentryprocesshook} +where \meta{label} is the current entry label. For example, the +\glostyle{alttree} style needs to know the widest entry name in +order to set up the correct indentation. The widest name is set +using: +\nosecformatdef{glssetwidest} +but this requires knowing which entry has the widest name. There are +some commands provided by the \sty{glossary-tree} and +\sty{glossaries-extra-stylemods} packages that iterate over all +entries, measuring each name, in order to find the widest, but since +\gls{printunsrtglossary} already has to iterate over the list before +typesetting it, this hook can be used to update the widest name at +the same time. You can update the value with: +\nosecformatdef{glsupdatewidest} +which computes the width of \meta{text} and, if it's wider than the +current widest name for the given level, sets the widest value to +\meta{text} (without expanding it). If \meta{text} needs expanding +you need to use: +\nosecformatdef{eglsupdatewidest} +The \meta{level} refers to the entry's hierarchical level with a +value of~0 indicating top-level (that is, an entry without a parent). +The level is stored in the internal \field{level} field and can only +be accessed with \gls{glsxtrusefield} or similar commands +(see \sectionref{sec:userkeys}). + +You can also redefine this hook to filter the glossary list. +If an entry shouldn't appear in the list, use: +\nosecformatdef{printunsrtglossaryskipentry} +For example, to only include entries that have the \field{category} +set to \code{formula}: +\begin{codeenv} +\gls{printunsrtglossary*}\oarg{\printglossopt{target}=false,\printglossopt{title}=\marg{Formula}} +\marg{\comment{local code:} + \cmd{renewcommand}\marg{\gls{printunsrtglossaryentryprocesshook}}[1]\marg{\comment{} + \gls{glsifcategory}\marg{\gls{param}1}\marg{formula} + \marg{}\comment{category = formula} + \marg{\gls{printunsrtglossaryskipentry}}\comment{} + }\comment{} +} +\end{codeenv} +This uses \gls{glsifcategory} to check the value of the entry's +\field{category} field (see \sectionref{sec:categories}). Another +conditional you might find useful is: +\nosecformatdef{glsxtriflabelinlist} +which tests if the given \meta{label} is in the comma-separated +\meta{list} of labels. Both \meta{label} and \meta{list} are fully +expanded before testing. This command is only intended for labels, +which must be fully expandable. +For example, the following excludes any entries that have the +\field{category} set to \code{abbreviation} or \code{acronym}: +\begin{codeenv} +\gls{printunsrtglossary*}\oarg{\printglossopt{target}=false,\printglossopt{title}=\marg{Formula}} +\marg{\comment{local code:} + \cmd{renewcommand}\marg{\gls{printunsrtglossaryentryprocesshook}}[1]\marg{\comment{} + \gls{glsxtriflabelinlist} + \marg{\gls{glscategory}\marg{\gls{param}1}}\comment{category label for this entry} + \marg{abbreviation,acronym}\comment{exclusion list} + \marg{\gls{printunsrtglossaryskipentry}}\comment{skip (exclude)} + \marg{}\comment{don't skip (include)} + }\comment{} +} +\end{codeenv} + +\subsection{Hyperlink Targets} +\label{sec:targetnames} + +The naming system used for the hyperlinks from commands like +\gls{gls} and \gls{glssymbol} to the corresponding definition in the +glossary is given by \meta{prefix}\meta{label} where \meta{label} is +the entry's label and \meta{prefix} is given by: +\nosecformatdef{glolinkprefix} +This can locally be changed within commands like \gls{gls} and +\gls{glssymbol} with the \glsopt{prefix} option. There is a matching +\printglossopt{prefix} option for \gls{printunsrtglossary}. +You can set an additional prefix in the glossary with +\printglossopt[\meta{extra}]{targetnameprefix}, which means that the +target name in the glossary is now +\code{\meta{extra}\gls{glolinkprefix}\meta{label}} (so +\printglossopt{targetnameprefix} doesn't modify \gls{glolinkprefix} +but prepends an extra prefix). + +If you change the prefix either by using the above options or by +redefining \gls{glolinkprefix}, you need to make sure that the +target names match for the links to work correctly. +The \styopt[showtargets]{debug} package option can be used to show +the target names in the document. The target is displayed in the +document using: +\nosecformatdef{glsshowtarget} +which may be redefined as appropriate. For example: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\marg{hyperref} +\cmd{usepackage}[\styopt{debug}=showtargets]\marg{glossaries-extra} +\strut +\gls{newglossaryentry}\marg{sample}\marg{\field{name}=\marg{sample},\field{description}=\marg{an example}} +\strut +\cmd{begin}\marg{document} +\gls{gls}\oarg{\glsopt{prefix}=\marg{TARGET.}}\marg{sample}. +\strut +\gls{printunsrtglossary}\oarg{\printglossopt{prefix}=\marg{TARGET.}} +\gls{printunsrtglossary}\oarg{\printglossopt{prefix}=\marg{TARGET.},\printglossopt{targetnameprefix}=\marg{EXTRA.}} +\cmd{end}\marg{document} +\end{codeenv} + +\section{Stand-alone Definitions} +\label{sec:standalone} + +The \sty{glossaries-extra} package provides: +\nosecformatdef{glsxtrglossentry} +which may be used to create a target for a particular entry (identified by +\meta{label}). This displays the value of the \field{name} field, +but it also obeys the \idx{postnamehook} (see +\sectionref{sec:postfieldhooks}), the \catattr{glossname} +and \catattr{glossnamefont} attributes (see +\sectionref{sec:glossname}), and provides accessibility support if +the \field{access} field is set (see \sectionref{sec:accsupp}). +This command may be used for both top-level and child entries, and +will obey the \styopt{entrycounter} (see below) and \styopt{subentrycounter} +(see \sectionref{sec:parent}) package options according to the +entry's hierarchical level. + +This command doesn't display any of the other field values. +If any are required, you need to add them afterwards. +For the description, you can use \gls{glsentrydesc}, but it's better +to use: +\nosecformatdef{glossentrydesc} +Unlike \gls{glsentrydesc}, which just displays the value of the +\field{description} field, \gls{glossentrydesc} obeys the +\catattr{glossdesc} and \catattr{glossdescfont} attributes +(\sectionref{sec:glossname}). Alternatively, you can use: +\nosecformatdef{Glossentrydesc} +which converts the first letter of the description to +\idx{uppercase}. +To pick up the \styopt{postpunc} setting and the +\glslink{postdescriptionhook}{post-description category hook}, +append \gls{glspostdescription} +after the description (see \sectionref{sec:postfieldhooks}). + +There's a similar command for symbols: +\nosecformatdef{glossentrysymbol} +There are currently no category attributes governing this +command, but it does check for the \field{symbolaccess} field if +accessibility support has been added (see \sectionref{sec:accsupp}). +For other fields, you can use the commands described in +\sectionref{sec:userkeys}. + +If you need to substitute the \field{name} for another field in the +target, you can use: +\nosecformatdef{glsxtrglossentryother} +instead of \code{\gls{glsxtrglossentry}\margm{label}}, +where \meta{label} identifies the entry and \meta{field} is the +internal field label to use instead of the \field{name}. The +\meta{header} argument is the code to use in the header (which +should be left empty for the default value\footnote{The +\meta{header} argument doesn't use standard \LaTeX\ optional syntax +\code{\oargm{option}} because \gls{glsxtrglossentryother} has to be +expandable in order for it to work correctly in section arguments.})\ if +\gls{glsxtrglossentryother} is used in a sectioning command. This +command obeys the \catattr{glossname} and \catattr{glossnamefont} +attributes and the \idx{postnamehook}, even though it's not actually +displaying the name. For example, +\begin{codeenv} +\cmd{section}\marg{\gls{glsxtrglossentryother}\marg{}\marg{duck}\marg{\field{plural}}} +\end{codeenv} + +Here's a complete example that uses \gls{glsxtrglossentry} after an +equation to describe the notation: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\marg{\gls[noindex=false]{xcolor}}\comment{provides colour} +\cmd{usepackage}[colorlinks,linkcolor=purple]\marg{\gls[noindex=false]{hyperref}} +\cmd{usepackage}[\styopt[dot]{postpunc}]\marg{glossaries-extra} +\strut +\gls{newglossaryentry}\marg{pi} +\marg{ + \field{name} = \marg{\gls{ensuremath}\marg{\cmd{pi}}}, + \field{description} = \marg{Archimedes' constant} +} +\strut +\gls{newglossaryentry}\marg{radius} +\marg{ + \field{name} = \marg{\gls{ensuremath}\marg{r}}, + \field{description} = \marg{radius} +} +\strut +\gls{newglossaryentry}\marg{area} +\marg{ + \field{name} = \marg{\gls{ensuremath}\marg{A}}, + \field{description} = \marg{area} +} +\strut +\cmd{begin}\marg{document} +\cmd{begin}\marg{equation} +\gls{gls}\marg{area} = \gls{gls}\marg{pi}\gls{gls}\marg{radius}[\gls{spchar}2] +\cmd{end}\marg{equation} +\cmd{begin}\marg{tabular}\marg{ll} +\gls{glsxtrglossentry}\marg{area} \gls[noindex=false]{colsep} \gls{glossentrydesc}\marg{area}\gls{glspostdescription}\gls[noindex=false]{cs.backslash} +\gls{glsxtrglossentry}\marg{pi} \gls{colsep} \gls{glossentrydesc}\marg{pi}\gls{glspostdescription}\gls{cs.backslash} +\gls{glsxtrglossentry}\marg{radius} \gls{colsep} \gls{glossentrydesc}\marg{radius}\gls{glspostdescription} +\cmd{end}\marg{tabular} +\cmd{end}\marg{document} +\end{codeenv} +This produces: +\begin{result} +\setcounter{equation}{0}% +\renewcommand{\theequation}{\arabic{equation}}% +\renewcommand{\theHequation}{\thechapter.standalone1.\arabic{equation}}% +\renewcommand{\glolinkprefix}{standalone1}% +\renewcommand{\glstextformat}[1]{\textcolor{purple}{#1}}% +\renewcommand{\glslinkpresetkeys}{\setkeys{glslink}{local}}% +\glossariesextrasetup{postdot}% +\begin{equation} +\gls{standalone.area} = \gls{standalone.pi}\gls{standalone.radius}[^2] +\end{equation} +\begin{tabular}{ll} +\glsxtrglossentry{standalone.area} & \glossentrydesc{standalone.area}\glspostdescription\\ +\glsxtrglossentry{standalone.pi} & \glossentrydesc{standalone.pi}\glspostdescription\\ +\glsxtrglossentry{standalone.radius} & \glossentrydesc{standalone.radius}\glspostdescription +\end{tabular} +\end{result} +The purple text shows the hyperlinks to the relevant definition. As +with \gls{printunsrtglossary}, the hypertargets are prefixed with +\gls{glolinkprefix} (see \sectionref{sec:printglossagain}). This +can be locally changed to avoid clashes if the definition needs to +be reproduced later. + +A more convenient approach to the above is to define an environment that can +list all the referenced entries automatically. The +\sty{glossaries-extra} package provides a way of buffering the +boolean switch performed by \gls{gls} that ensures that the +\idx{firstuseflag} is unset (see \sectionref{sec:buffering}). +This is intended for use where the switch causes a problem, but it +can also be used in this case to store a list of used entries (since +there's no difference between \idx{firstuse} and subsequent use in +this case, it won't affect the \idx{link-text}). + +Here's a modified version of the above document: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\marg{xcolor} +\cmd{usepackage}[colorlinks,linkcolor=purple]\marg{hyperref} +\cmd{usepackage}[\styopt[dot]{postpunc}]\marg{glossaries-extra} +\strut +\gls{newglossaryentry}\marg{pi} +\marg{ + \field{name} = \marg{\gls{ensuremath}\marg{\cmd{pi}}}, + \field{description} = \marg{Archimedes' constant} +} +\strut +\gls{newglossaryentry}\marg{radius} +\marg{ + \field{name} = \marg{\gls{ensuremath}\marg{r}}, + \field{description} = \marg{radius} +} +\strut +\gls{newglossaryentry}\marg{area} +\marg{ + \field{name} = \marg{\gls{ensuremath}\marg{A}}, + \field{description} = \marg{area} +} +\strut +\gls{newglossaryentry}\marg{circumference} +\marg{ + \field{name} = \marg{\gls{ensuremath}\marg{C}}, + \field{description} = \marg{circumference} +} +\strut +\cmd{newcommand}\marg{\cmd{doglossaryentry}}[1]\marg{\comment{handler macro} + \gls{glsxtrglossentry}\marg{\gls{param}1} \gls{colsep} \gls{glossentrydesc}\marg{\gls{param}1}\gls{glspostdescription}\gls{cs.backslash}\comment{} +} +\strut +\cmd{newcounter}\marg{localglossary} +\strut +\cmd{newenvironment}\marg{localglossary} +\marg{\comment{} + \cmd{stepcounter}\marg{localglossary}\comment{} + \cmd{renewcommand}\marg{\gls{glolinkprefix}}\marg{\cmd{thelocalglossary}.}\comment{} + \gls{GlsXtrStartUnsetBuffering}* +} +\marg{\comment{} + \cmd{par} + \cmd{begin}\marg{tabular}\marg{ll} + \gls{GlsXtrForUnsetBufferedList}\cmd{doglossaryentry} + \cmd{end}\marg{tabular} + \gls{GlsXtrStopUnsetBuffering} + \cmd{par} +} +\strut +\cmd{begin}\marg{document} +The area of a circle is given by: +\cmd{begin}\marg{localglossary} +\cmd{begin}\marg{equation} +\gls{gls}\marg{area} = \gls{gls}\marg{pi}\gls{gls}\marg{radius}[\gls{spchar}2] +\cmd{end}\marg{equation} +\cmd{end}\marg{localglossary} +The circumference of a circle is given by: +\cmd{begin}\marg{localglossary} +\cmd{begin}\marg{equation} +\gls{gls}\marg{circumference} = 2\gls{gls}\marg{pi}\gls{gls}\marg{radius} +\cmd{end}\marg{equation} +\cmd{end}\marg{localglossary} +\cmd{end}\marg{document} +\end{codeenv} +This produces: +\begin{result} +\setcounter{equation}{0}% +\renewcommand{\theequation}{\arabic{equation}}% +\renewcommand{\theHequation}{\thechapter.standalone2.\arabic{equation}}% +\renewcommand{\glolinkprefix}{standalone2}% +\renewcommand{\glstextformat}[1]{\textcolor{purple}{#1}}% +\renewcommand{\glslinkpresetkeys}{}% +\glossariesextrasetup{postdot}% +The area of a circle is given by: +\begin{localglossary} +\begin{equation} +\gls{standalone.area} = \gls{standalone.pi}\gls{standalone.radius}[^2] +\end{equation} +\end{localglossary} +The circumference of a circle is given by: +\begin{localglossary} +\begin{equation} +\gls{standalone.circumference} = 2\gls{standalone.pi}\gls{standalone.radius} +\end{equation} +\end{localglossary} +\end{result} +The custom \counterfmt{localglossary} counter is defined and incremented to +ensure that the target prefix \gls{glolinkprefix} is unique for each +environment. This definition of the custom \envfmt{localglossary} +environment is intentionally kept trivial since the main point here is +the demonstration of \gls{glsxtrglossentry} and the buffering rather +than the actual formatting of the entries. Additional vertical +spacing, appropriate alignment and a paragraph column specifier are +left as an exercise for the reader. + +\subsection{Numbering Top-Level Entries} +\label{sec:entrycounter} + +The \styopt{entrycounter} package option creates a new counter +called \counter{glossaryentry}, which will automatically be +incremented and displayed at the start of \gls{glsxtrglossentry} +for top-level entries. (The \counter{glossarysubentry} counter created with the +\styopt{subentrycounter} option, described in \sectionref{sec:parent}, +may be used independently of the \styopt{entrycounter} package option.) In +the above example, this counter will need to depend on the custom +\counterfmt{localglossary} counter to ensure that it's reset at the +start of each \envfmt{localglossary} environment. This can easily be +done by using the name of the master counter as the value of +\styopt{counterwithin} (which automatically implements +\styopt{entrycounter}), but the master counter must be defined +first: +\begin{codeenv} +\cmd{newcounter}\marg{localglossary} +\cmd{usepackage}[\styopt[localglossary]{counterwithin}]\marg{glossaries-extra} +\end{codeenv} +The default definition of \gls{theHglossaryentry} is: +\begin{codeenv} +\gls{currentglossary}.\gls[noindex=false]{theglossaryentry} +\end{codeenv} +The prefix \gls{currentglossary} is set by both +\gls{printunsrtglossary} and \gls{glsxtrglossentry} to the current +glossary label (given by the \printglossopt{type} option in +\gls{printunsrtglossary} and by the entry's \field{type} field for +\gls{glsxtrglossentry}). In the case of \gls{glsxtrglossentry} +(and \gls{glsxtrglossentryother}), the value of +\gls{currentglossary} is obtained from: +\nosecformatdef{GlsXtrStandaloneGlossaryType} +which defaults to the value of the \field{type} field for the +current entry. + +Since this example is using multiple stand-alone definitions that +may repeat the same entry, this definition isn't appropriate and will +cause duplicate destination warnings. The simplest solution is to redefine +\gls{GlsXtrStandaloneGlossaryType} in terms of the custom +\counterfmt{localglossary} counter value: +\begin{codeenv} +\cmd{renewcommand}\marg{\cmd{GlsXtrStandaloneGlossaryType}}\marg{\comment{} + standalone.\cmd{thelocalglossary}.\cmd{arabic}\marg{\counter{glossaryentry}}\comment{} +} +\end{codeenv} + +Unlike commands such as \gls{gls}, which can be problematic in moving +arguments, \gls{glsxtrglossentry} is designed to work in section +headings. For example: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\marg{mhchem} +\cmd{usepackage}[colorlinks,linkcolor=magenta]\marg{hyperref} +\cmd{usepackage}[\styopt[dot]{postpunc}]\marg{glossaries-extra} +\strut +\gls{newglossaryentry}\marg{amethyst} +\marg{ + \field{name} = \marg{amethyst}, + \field{description} = \marg{a purple type of quartz}, + \field{symbol} = \marg{\gls{ce}\marg{SiO2}}, + \field{category} = \marg{mineral} +} +\strut +\gls{glssetcategoryattribute}\marg{mineral}\marg{glossname}\marg{firstuc} +\strut +\cmd{newcommand}\marg{\cmd{displayterm}}[1]\marg{\comment{} + \cmd{subsection}\marg{\gls{glsxtrglossentry}\marg{\gls{param}1}}\comment{} + Chemical formula: \gls{glossentrysymbol}\marg{\gls{param}1}. + \gls{Glossentrydesc}\marg{\gls{param}1}\gls{glspostdescription}\cmd{par} +} +\cmd{begin}\marg{document} +\gls{tableofcontents} +\cmd{section}\marg{Types of Quartz} +A reference to \gls{gls}\marg{amethyst}. +\strut +\cmd{displayterm}\marg{amethyst} +\cmd{end}\marg{document} +\end{codeenv} +(Again, improvements to the actual formatting of the custom +\csfmt{displayterm} is left as an exercise to the reader. Additional +fields could contain, for example, the name of an image file to +illustrated the entry. See the +\href{https://www.dickimaw-books.com/gallery/}{\styfmt{glossaries} +gallery}~\cite{gallery} for further ideas.) + +The above example uses the \catattr{glossname} attribute to convert the first +letter of the \field{name} to \idx{uppercase}. Unfortunately this can't be +applied to the PDF bookmark or \gls{toc}. A solution to this +would be to explicitly set the \field{name} with the first letter as +an \idx{uppercase} character and the \field{text} field in +\idx{lowercase}. For example: +\begin{codeenv} +\gls{newglossaryentry}\marg{amethyst} +\marg{ + \field{name} = \marg{Amethyst}, + \field{text} = \marg{amethyst}, + \field{description} = \marg{a purple type of quartz}, + \field{symbol} = \marg{\gls{ce}\marg{SiO2}}, + \field{category} = \marg{mineral} +} +\end{codeenv} +The \catattr{glossname} attribute can then be omitted. This is a bit +inconvenient, but if you use \bibgls\ (see \sectionref{sec:bib2gls}) +this can be performed automatically with the +\csopt{name-case-change} resource option. + +\subsection{Stand-alone Hierarchical Entries} +\label{sec:standalonehierarchy} + +Sub-entries can also be displayed with \gls{glsxtrglossentry} or +\gls{glsxtrglossentryother}. These check if the entry has a parent +(with \gls{ifglshasparent}). If it doesn't, then it will display +the \counter{glossaryentry} counter label if the +\styopt{entrycounter} package option has been used. If the entry +does have a parent, it uses: +\nosecformatdef{GlsXtrStandaloneSubEntryItem} +which checks the internal \field{level} field to +determine the hierarchical level. If the \field{level} is~1 (that +is, the entry has a parent but not a grandparent) then it will +display the \counter{glossarysubentry} label if that counter has +been defined, otherwise it does nothing. + +Here's an example document with a top-level entry (\code{mineral}), +a level~1 entry (\code{quartz}) and a level~2 entry (\code{amethyst}). +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\marg{xcolor}\comment{provides colour} +\cmd{usepackage}[colorlinks,linkcolor=magenta]\marg{hyperref} +\cmd{usepackage}[ + \styopt{entrycounter},\comment{enable top-level counter} + \styopt{subentrycounter},\comment{enable level 1 counter} + \styopt{postpunc}=\marg{dot},\comment{put full-stop after description} + \styopt{nostyles},\comment{suppress automatic loading of default styles} + \styopt[tree]{stylemods}\comment{load glossary-tree.sty} +]\marg{glossaries-extra} +\strut +\gls{newglossaryentry}\marg{mineral} +\marg{ + \field{name} = \marg{mineral}, + \field{description} = \marg{natural inorganic substance}, + \field{category} = \marg{mineral} +} +\strut +\gls{newglossaryentry}\marg{calcite} +\marg{ + \field{parent} = \marg{mineral}, + \field{name} = \marg{calcite}, + \field{description} = \marg{a carbonate mineral}, + \field{category} = \marg{mineral} +} +\strut +\gls{newglossaryentry}\marg{quartz} +\marg{ + \field{parent} = \marg{mineral}, + \field{name} = \marg{quartz}, + \field{description} = \marg{hard mineral consisting of silica}, + \field{category} = \marg{mineral} +} +\strut +\gls{newglossaryentry}\marg{amethyst} +\marg{ + \field{parent} = \marg{quartz}, + \field{name} = \marg{amethyst}, + \field{description} = \marg{a purple type of quartz}, + \field{category} = \marg{mineral} +} +\strut +\gls{glssetcategoryattribute}\marg{mineral}\marg{glossname}\marg{firstuc} +\strut +\cmd{renewcommand}\marg{\gls[noindex=false]{GlsXtrStandaloneGlossaryType}}\marg{standalone} +\strut +\cmd{newcommand}\marg{\cmd{displayterm}}\oarg{1}\marg{\comment{} + \cmd{par} + Definition \gls{glsxtrglossentry}\marg{\gls{param}1}: + \gls{glossentrydesc}\marg{\gls{param}1}\gls{glspostdescription}\cmd{par} +} +\strut +\cmd{begin}\marg{document} +\cmd{displayterm}\marg{mineral} +\cmd{displayterm}\marg{calcite} +\cmd{displayterm}\marg{quartz} +\cmd{displayterm}\marg{amethyst} +\strut +A reference to \gls{gls}\marg{mineral}. +A reference to \gls{gls}\oarg{\printglossopt{prefix}={main.}}\marg{amethyst}. +\strut +\cmd{renewcommand}\marg{\gls[noindex=false]{GlsEntryCounterLabelPrefix}}\marg{main.glsentry-} +\gls{glsresetentrycounter} +\gls{printunsrtglossary}\oarg{\printglossopt{prefix}=\marg{main.},\printglossopt{style}=tree} +\cmd{end}\marg{document} +\end{codeenv} +This produces: +\begin{result} +\renewcommand{\glslinkpresetkeys}{\setkeys{glslink}{local}}% +\def\glolinkprefix{standalone.hier.}% +\renewcommand{\glstextformat}[1]{\textcolor{magenta}{#1}}% +\setupglossaries{entrycounter,subentrycounter,section,toc=false}% +\glossariesextrasetup{postdot}% +\glssetcategoryattribute{hierarchical}{glossname}{firstuc}% +\renewcommand{\GlsXtrStandaloneGlossaryType}{standalone}% +\newcommand{\displayterm}[1]{% + \par + \begingroup + Definition \glsxtrglossentry{#1}: + \glossentrydesc{#1}\glspostdescription\par + \endgroup +}% +\displayterm{hier.mineral} +\displayterm{hier.calcite} +\displayterm{hier.quartz} +\displayterm{hier.amethyst} + +A reference to \gls{hier.mineral}. +A reference to \gls[prefix={hierarchical.main.}]{hier.amethyst}. + +\printunsrtglossary*[prefix={hierarchical.main.},style=tree,nonumberlist] +{% + \glsresetentrycounter + \renewcommand{\GlsEntryCounterLabelPrefix}{main.glsentry-}% + \renewcommand*{\printunsrtglossaryentryprocesshook}[1]{% + \glsxtriflabelinlist{#1}{hier.mineral,hier.calcite,hier.quartz,hier.amethyst}% + {}{\printunsrtglossaryskipentry}% + }% +} +\end{result} +Note the need to reset the \counter{glossaryentry} counter with +\gls{glsresetentrycounter} before the main glossary. The top-level +entry (\code{mineral}) has the label formatted as +\qt{1.\textvisiblespace} and the level~1 entries (\code{calcite} +and \code{quartz}) have their labels formatted as +\qt{1)\textvisiblespace} and \qt{2)\textvisiblespace} but the +level~2 entry (\code{amethyst}) doesn't have an associated number. +If you want to number levels deeper than 1, you will have to provide +your own custom counters. (If the stand-alone level~2 entry shows a +number when you try this, then you've encountered a bug that's been +fixed in \sty{glossaries-extra} version~1.31.) + +The hyperlinks are shown in magenta. The first (\code{mineral}) links to the +stand-alone target, and the second (\code{amethyst}) links to the entry in +the main glossary. + +\chapter{Changing the Formatting} +\label{sec:glsformats} + +All commands like \gls{gls} and \gls{glssymbol} by default +encapsulate the \idx{link-text} within the argument of: +\nosecformatdef{glstextformat} +For example: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\marg{xcolor}\comment{provides colour} +\cmd{usepackage}\marg{pifont}\comment{provides \gls{ding}} +\cmd{usepackage}\marg{glossaries-extra} +\strut +\gls{newglossaryentry}\marg{duck}\comment{label} +\marg{ + \field{name} = \marg{duck}, + \field{description} = \marg{a waterbird with webbed feet} +} +\strut +\gls{newglossaryentry}\marg{fleuron}\comment{label} +\marg{ + \field{name} = \marg{fleuron}, + \field{symbol} = \marg{\gls[noindex=false]{ding}\marg{167}}, + \field{category} = \marg{ornament}, + \field{description} = \marg{typographic ornament} +} +\strut +\gls{newabbreviation}\marg{tug}\marg{TUG}\marg{\cmd{TeX}\gls{cs.space}Users Group} +\strut +\cmd{renewcommand}\marg{\gls{glstextformat}}[1]\marg{\cmd{textcolor}\marg{violet}\marg{\gls{param}1}} +\strut +\cmd{begin}\marg{document} +A \gls{gls}\marg{duck}, a \gls{gls}\marg{fleuron} (\gls{glssymbol}\marg{fleuron}, +\gls{glsentrydesc}\marg{fleuron}) and \gls{gls}\marg{tug}. +\cmd{end}\marg{document} +\end{codeenv} +This produces: +\begin{result}% +\renewcommand{\glstextformat}[1]{\textcolor{violet}{#1}}% +A \gls{ex1.duck}, a \gls{ex.fleuron} (\glssymbol{ex.fleuron}, +\glsentrydesc{ex.fleuron}) and \gls{TUG}. +\end{result} +Note that this has affected \gls{gls} and \gls{glssymbol} but not +\gls{glsentrydesc}. + +A distinction can be made between abbreviations (\idx{non-regular} +terms) and \idx{regular} terms (non-abbreviations or abbreviations +that are considered \idx{regular} entries). +A \idx{regular} term is encapsulated with +\nosecformatdef{glsxtrregularfont} +and an abbreviation is encapsulated with +\nosecformatdef{glsxtrabbreviationfont} +For example: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\marg{xcolor}\comment{provides colour} +\cmd{usepackage}\marg{pifont}\comment{provides \gls{ding}} +\cmd{usepackage}\marg{glossaries-extra} +\strut +\gls{newglossaryentry}\marg{duck}\comment{label} +\marg{ + \field{name} = \marg{duck}, + \field{description} = \marg{a waterbird with webbed feet} +} +\strut +\gls{newglossaryentry}\marg{fleuron}\comment{label} +\marg{ + \field{name} = \marg{fleuron}, + \field{symbol} = \marg{\gls{ding}\marg{167}}, + \field{category} = \marg{ornament}, + \field{description} = \marg{typographic ornament} +} +\strut +\gls{newabbreviation}\marg{tug}\marg{TUG}\marg{\cmd{TeX}\gls{cs.space}Users Group} +\gls{newacronym}\marg{ascii}\marg{ASCII}\marg{American Standard Code for +Information Interchange} +\strut +\cmd{renewcommand}\marg{\gls{glstextformat}}[1]\marg{\cmd{textcolor}\marg{violet}\marg{\gls{param}1}} +\cmd{renewcommand}\marg{\gls{glsxtrregularfont}}[1]\marg{\cmd{underline}\marg{\gls{param}1}} +\cmd{renewcommand}\marg{\gls{glsxtrabbreviationfont}}[1]\marg{\gls{emph}\marg{\gls{param}1}} +\strut +\cmd{begin}\marg{document} +Two \gls{glspl}\marg{duck}, a \gls{gls}\marg{fleuron} (\gls{glssymbol}\marg{fleuron}, +\gls{glsentrydesc}\marg{fleuron}), \gls{gls}\marg{tug} and \gls{gls}\marg{ascii}. +\cmd{end}\marg{document} +\end{codeenv} +This now produces: +\begin{result}% +\renewcommand{\glstextformat}[1]{\textcolor{violet}{#1}}% +\renewcommand{\glsxtrregularfont}[1]{\underline{#1}}% +\renewcommand{\glsxtrabbreviationfont}[1]{\emph{#1}}% +Two \glspl{ex1.duck}, a \gls{ex.fleuron} (\glssymbol{ex.fleuron}, +\glsentrydesc{ex.fleuron}), \gls{TUG} and \gls{ASCII}. +\end{result} +Note the difference between the abbreviation defined with +\gls{newabbreviation} and the one defined with \gls{newacronym}. +The above example document is using the default styles, which is +\abbrstyle{long-short} for the \code{abbreviation} category +and \abbrstyle{short-nolong} for the \code{acronym} category. +The \abbrstyle{short-nolong} style makes the abbreviation behave +like a \idx{regular} entry and so it's governed by \gls{glsxtrregularfont} +not by \gls{glsxtrabbreviationfont}. + +The \gls{glstextformat} command is overridden by the +\catattr{textformat} attribute. The value of this attribute must be +the name (without the leading backslash) of a command that takes a +single argument, which will be used instead of \gls{glstextformat} +for any entry that has this attribute set for its category. +For example: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\marg{xcolor}\comment{provides colour} +\cmd{usepackage}\marg{pifont}\comment{provides \gls{ding}} +\cmd{usepackage}\marg{glossaries-extra} +\strut +\cmd{newcommand}\marg{\cmd{ornamentfmt}}[1]\marg{\cmd{textcolor}\marg{cyan}\marg{\gls{param}1}} +\strut +\gls{glssetcategoryattribute}\marg{ornament}\marg{\catattr{textformat}}\marg{ornamentfmt} +\strut +\gls{setabbreviationstyle}\marg{\abbrstyle[noindex=false]{long-short-em}} +\gls{setabbreviationstyle}\oarg{acronym}\marg{\abbrstyle[noindex=false]{short-sc-nolong}} +\strut +\gls{newglossaryentry}\marg{duck}\comment{label} +\marg{ + \field{name} = \marg{duck}, + \field{description} = \marg{a waterbird with webbed feet} +} +\strut +\gls{newglossaryentry}\marg{fleuron}\comment{label} +\marg{ + \field{name} = \marg{fleuron}, + \field{symbol} = \marg{\gls{ding}\marg{167}}, + \field{category} = \marg{ornament}, + \field{description} = \marg{typographic ornament} +} +\strut +\gls{newabbreviation}\marg{tug}\marg{TUG}\marg{\cmd{TeX}\gls{cs.space}Users Group} +\gls{newacronym}\marg{ascii}\comment{label} +\marg{ascii}\comment{short form needs to be in lower case with sc styles} +\marg{American Standard Code for Information Interchange} +\strut +\cmd{renewcommand}\marg{\gls{glstextformat}}[1]\marg{\cmd{textcolor}\marg{violet}\marg{\gls{param}1}} +\cmd{renewcommand}\marg{\gls{glsxtrregularfont}}[1]\marg{\cmd{underline}\marg{\gls{param}1}} +\cmd{renewcommand}\marg{\gls{glsxtrabbreviationfont}}[1]\marg{\gls{textbf}\marg{\gls{param}1}} +\strut +\cmd{begin}\marg{document} +Two \gls{glspl}\marg{duck}, a \gls{gls}\marg{fleuron} (\gls{glssymbol}\marg{fleuron}, +\gls{glsentrydesc}\marg{fleuron}), \gls{gls}\marg{tug} and \gls{gls}\marg{ascii}. +\cmd{end}\marg{document} +\end{codeenv} +This produces: +\begin{result} +\renewcommand{\glstextformat}[1]{\textcolor{violet}{#1}}% +\renewcommand{\glsxtrregularfont}[1]{\underline{#1}}% +\renewcommand{\glsxtrabbreviationfont}[1]{\textbf{#1}}% +\newcommand{\ornamentfmt}[1]{\textcolor{cyan}{#1}}% +\glssetcategoryattribute{ornament}{textformat}{ornamentfmt}% +Two \glspl{ex1.duck}, a \gls{ex.fleuron} (\glssymbol{ex.fleuron}, +\glsentrydesc{ex.fleuron}), \gls{ex.tug} and \gls{ex.ascii}. +\end{result} +So \code{\gls{gls}\marg{fleuron}} and \code{\gls{glssymbol}\marg{fleuron}} are now +formatted according to the custom command \csfmt{ornamentfmt} (cyan) +not by \gls{glstextformat} (violet), but they are still affected by +\gls{glsxtrregularfont} (underline). + +The \code{tug} abbreviation has been assigned the +\abbrstyle{long-short-em} style which encapsulates the short form +with \gls{emph}, but it also obeys \gls{glsxtrabbreviationfont} +(bold) and it's encapsulated by \gls{glstextformat} (violet), so the +full form on \idx{firstuse} is all violet and bold with the short +form in italics. + +The \code{ascii} entry (which has the \field{category} set to +\code{acronym}) has been assigned the \abbrstyle{short-sc-nolong} +style, which encapsulates the short form with \gls{textsc} (so the +short form must be converted to \idx{lowercase}) and identifies the +entry as a \idx{regular} term, so it obeys \gls{glsxtrregularfont} +(underline). Again, the \idx{link-text} is encapsulated with +\gls{glstextformat} (violet) so the abbreviation is violet, +underlined and in small-caps. + +You can override a specific instance with the \glsopt{textformat} +setting in the first optional argument of commands like \gls{gls}. +For example, if the above is modified to: +\begin{codeenv} +Two \gls{glspl}\marg{duck}, a \gls{gls}\oarg{\glsopt{textformat}=textbf}\marg{fleuron} +(\gls{glssymbol}\marg{fleuron}, \gls{glsentrydesc}\marg{fleuron}), \gls{gls}\marg{tug} +and \gls{gls}\marg{ascii}. +\end{codeenv} +then the result is now: +\begin{result} +\renewcommand{\glstextformat}[1]{\textcolor{violet}{#1}}% +\renewcommand{\glsxtrregularfont}[1]{\underline{#1}}% +\renewcommand{\glsxtrabbreviationfont}[1]{\textbf{#1}}% +\newcommand{\ornamentfmt}[1]{\textcolor{cyan}{#1}}% +\glssetcategoryattribute{ornament}{textformat}{ornamentfmt}% +Two \glspl{ex1.duck}, a \gls[textformat=textbf]{ex.fleuron} +(\glssymbol{ex.fleuron}, \glsentrydesc{ex.fleuron}), +\gls{ex.tug} and \gls{ex.ascii}. +\end{result} +In this case, only that specific instance is changed. + +Take care if the formatting command needs to parse its argument as +the argument won't be the actual text but consists of intermediary commands +that determine the required text and any inner formatting, such as +the formatting applied by abbreviation styles. See +\sectionref{sec:expandedfmt} for further details. + +\section{Post-Link Category Hooks} +\label{sec:postlinkhooks} + +Extra information can be appended after commands such as \gls{gls} +by defining a \pidx{postlinkhook} for the given category. You can +obtain the label of the entry that's just been referenced with: +\nosecformatdef{glslabel} +The \idx{postlinkhook} is a command in the form +\nosecformatdef{glsxtrpostlinkcategory} +where \meta{category} is the category label. This hook is +implemented after any instances of commands such as \gls{gls} or +\gls{glssymbol} (but not after commands like \gls{glsentryname}, +\gls{glsentrydesc} or \gls{glsentryname}, which may be used in the +hook). + +Consider the following document: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\marg{pifont}\comment{provides \gls{ding}} +\cmd{usepackage}\marg{glossaries-extra} +\strut +\gls{newglossaryentry}\marg{fleuron}\comment{label} +\marg{ + \field{name} = \marg{fleuron}, + \field{symbol} = \marg{\gls{ding}\marg{167}}, + \field{description} = \marg{typographic ornament} +} +\strut +\gls{newglossaryentry}\marg{pi}\comment{label} +\marg{ + \field{name} = \marg{Archimedes' constant}, + \field{symbol} = \marg{\gls{ensuremath}\marg{\cmd{pi}}}, + \field{category} = \marg{constant}, + \field{description} = \marg{Archimedes' constant} +} +\strut +\comment{post-link hook for 'constant' category:} +\cmd{newcommand}\marg{\csfmt{glsxtrpostlinkconstant}}\marg{\comment{} + \cmd{space} (\gls{glsentrysymbol}\marg{\gls{glslabel}})} +\strut +\cmd{begin}\marg{document} +A \gls{gls}\marg{fleuron} and \gls{gls}\marg{pi}. +\cmd{end}\marg{document} +\end{codeenv} +This produces: +\begin{result} +\newcommand{\glsxtrpostlinkconstant}{\space (\glsentrysymbol{\glslabel})}% +A \gls{ex.fleuron} and \gls{ex.pi}. +\end{result} +The \code{fleuron} entry doesn't have the \field{category} key +explicitly set, so it defaults to \code{general}, but the \code{pi} +entry has the \field{category} set to \code{constant}, so it's +affected by the \idx{postlinkhook} for that category, which in this +case is given by \csfmt{glsxtrpostlinkconstant}. This hook is +defined to use \gls{glsentrysymbol} where the entry label is obtained +from \gls{glslabel}, which is set by \gls{gls} and similar commands. + +\begin{important} +If \code{\gls{glssymbol}\marg{\gls{glslabel}}} had been used instead of +\code{\gls{glsentrysymbol}\marg{\gls{glslabel}}} it would've caused infinite +recursion! Don't use commands like \gls{glssymbol}, \gls{glsdesc} or +\gls{gls} in \idxpl{postlinkhook}. +\end{important} + +This means that \code{\gls{gls}\marg{pi}} is automatically followed by the +symbol in parentheses, but \code{\gls{gls}\marg{fleuron}} isn't because it's +governed by the \code{general} \idx{postlinkhook} instead. Note that +the above is a simple example to demonstrate one of the uses of the +\field{category} field. + +Here's a minor modification that sets the category for the +\code{fleuron} entry to \code{ornament} and creates another hook for +that. +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\marg{pifont}\comment{provides \gls{ding}} +\cmd{usepackage}\marg{glossaries-extra} +\strut +\gls{newglossaryentry}\marg{fleuron}\comment{label} +\marg{ + \field{name} = \marg{fleuron}, + \field{symbol} = \marg{\gls{ding}\marg{167}}, + \field{category} = \marg{ornament}, + \field{description} = \marg{typographic ornament} +} +\strut +\gls{newglossaryentry}\marg{pi}\comment{label} +\marg{ + \field{name} = \marg{pi}, + \field{symbol} = \marg{\gls{ensuremath}\marg{\cmd{pi}}}, + \field{category} = \marg{constant}, + \field{description} = \marg{Archimedes' constant} +} +\strut +\comment{post-link hook for 'ornament' category:} +\cmd{newcommand}\marg{\csfmt{glsxtrpostlinkornament}}\marg{\comment{} + \cmd{space} (\gls{glsentrydesc}\marg{\gls{glslabel}})} +\strut +\comment{post-link hook for 'constant' category:} +\cmd{newcommand}\marg{\csfmt{glsxtrpostlinkconstant}}{\comment{} + \cmd{space} (\gls{glsentrysymbol}\marg{\gls{glslabel}})} +\strut +\cmd{begin}\marg{document} +A \gls{gls}\marg{fleuron} and \gls{gls}\marg{pi}. Another \gls{gls}\marg{fleuron} and +\gls{gls}\marg{pi}. Symbols: \gls{glssymbol}\marg{fleuron} and \gls{glssymbol}\marg{pi}. +\cmd{end}\marg{document} +\end{codeenv} +This produces: +\begin{result} +\newcommand{\glsxtrpostlinkornament}{\space (\glsentrydesc{\glslabel})}% +\newcommand{\glsxtrpostlinkconstant}{\space (\glsentrysymbol{\glslabel})}% +A \gls{ex.fleuron} and \gls{ex.pi}. Another \gls{ex.fleuron} and +\gls{ex.pi}. Symbols: \glssymbol{ex.fleuron} and \glssymbol{ex.pi}.\incorrect +\end{result} +The \idx{postlinkhook} is repeated after every instance of \gls{gls} +or \gls{glssymbol} etc. In the case of the \code{ornament} category, +the description is appended in parentheses and in the case of the +\code{constant} category the symbol is appended. This results in +redundant repetition, especially with \verb|\glssymbol{pi}| which +displays the symbol followed by the symbol in parentheses. + +It's more likely that the information only needs to be appended +after the \idx{firstuse}. You can determine if the +\idx{postlinkhook} follows the \idx{firstuse} of the entry using: +\nosecformatdef{glsxtrifwasfirstuse} +For example: +\begin{codeenv} +\cmd{newcommand}\marg{\csfmt{glsxtrpostlinkconstant}}\marg{\comment{} + \gls{glsxtrifwasfirstuse}\marg{\cmd{space} (\gls{glsentrysymbol}\marg{\gls{glslabel}})}\marg{}\comment{} +} +\end{codeenv} +Commands that don't check or modify the \idx{firstuseflag}, such as +\gls{glssymbol}, always set \gls{glsxtrifwasfirstuse} so that it +expands to \meta{false}. This means that even if +\code{\gls{glssymbol}\marg{pi}} +is placed before the first instance of \code{\gls{gls}\marg{pi}} it still +won't be treated as the first use of that entry. + +For convenience, there's a shortcut command: +\nosecformatdef{glsxtrpostlinkAddSymbolOnFirstUse} +So an alternative definition is: +\begin{codeenv} +\cmd{newcommand}\marg{\csfmt{glsxtrpostlinkconstant}}\marg{\comment{} + \gls{glsxtrpostlinkAddSymbolOnFirstUse} +} +\end{codeenv} +This does nothing if the \field{symbol} field hasn't been set. + +Similarly, there's a shortcut command for the description: +\nosecformatdef{glsxtrpostlinkAddDescOnFirstUse} +Version 1.31+ provides a combination: +\nosecformatdef{glsxtrpostlinkAddSymbolDescOnFirstUse} +If the \field{symbol} field is set, this displays the symbol +followed by a comma and space. The description is always displayed +at the end of the parenthetical material. + +Also from \sty{glossaries-extra} v1.31, there's a shortcut +command that you can use to define the \idx{postlinkhook}: +\nosecformatdef{glsdefpostlink} +This is just a shortcut for: +\begin{codeenv} +\csfmt{csdef}\marg{glsxtrpostlink\meta{category}}\margm{definition} +\end{codeenv} +So the above document can be changed to: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\marg{pifont}\comment{provides \gls{ding}} +\cmd{usepackage}\marg{glossaries-extra} +\strut +\gls{newglossaryentry}\marg{fleuron}\comment{label} +\marg{ + \field{name} = \marg{fleuron}, + \field{symbol} = \marg{\gls{ding}\marg{167}}, + \field{category} = \marg{ornament}, + \field{description} = \marg{typographic ornament} +} +\strut +\gls{newglossaryentry}\marg{pi}\comment{label} +\marg{ + \field{name} = \marg{pi}, + \field{symbol} = \marg{\gls{ensuremath}\marg{\cmd{pi}}}, + \field{category} = \marg{constant}, + \field{description} = \marg{Archimedes' constant} +} +\strut +\comment{post-link hook for 'ornament' category:} +\gls{glsdefpostlink}\marg{ornament}\marg{\comment{} + \gls{glsxtrpostlinkAddSymbolDescOnFirstUse} +} +\strut +\comment{post-link hook for 'constant' category:} +\gls{glsdefpostlink}\marg{constant}\marg{\comment{} + \gls{glsxtrpostlinkAddSymbolOnFirstUse} +} +\strut +\cmd{begin}\marg{document} +Symbols: \gls{glssymbol}\marg{fleuron} and \gls{glssymbol}\marg{pi}. +A \gls{gls}\marg{fleuron} and \gls{gls}\marg{pi}. Another \gls{gls}\marg{fleuron} and +\gls{gls}\marg{pi}. +\cmd{end}\marg{document} +\end{codeenv} +The result is now: +\begin{result}% +\glsdefpostlink{ornament}{\glsxtrpostlinkAddSymbolDescOnFirstUse}% +\glsdefpostlink{constant}{\glsxtrpostlinkAddSymbolOnFirstUse}% +Symbols: \glssymbol{ex.fleuron} and \glssymbol{ex.pi}. +A \gls{ex.fleuron} and \gls{ex.pi}. Another \gls{ex.fleuron} and +\gls{ex.pi}. +\end{result} + +\section{Glossary Name and Description Formatting} +\label{sec:glossname} + +When an entry's definition is displayed within +\gls{printunsrtglossary} or \gls{glsxtrglossentry} (see +\sectionref{sec:displaygloss}), the value of the \field{name} field +is encapsulated by +\nosecformatdef{glsnamefont} +This may be overridden with the \catattr{glossnamefont} attribute +whose value must be the name (without the leading backslash) of a +control sequence that takes a single argument. If set, this control +sequence is used instead of \gls{glsnamefont}. + +By default \gls{glsnamefont} simply does its argument, but the +glossary style may apply additional formatting. For example, the +\glostyle{list} styles place the name in the optional argument of +\csfmt{item} within the \envfmt{description} environment. With the +standard document classes, this renders the name in bold, but other +classes may apply different formatting. + +The \glostyle{tree} styles defined by the \sty{glossary-tree} style +encapsulate the name within: +\nosecformatdef{glstreenamefmt} +which does \code{\gls{textbf}\margm{text}} by default. So, for +example, if \gls{glsnamefont} is redefined to use \gls{textit} and +the \glostyle{tree} style is used, then the name will appear in +italic bold. The letter group headings are encapsulated within: +\nosecformatdef{glstreegroupheaderfmt} +which defaults to \code{\gls{glstreenamefmt}\margm{text}}, so if you +need to redefine \gls{glstreenamefmt} you may also need to redefine +\gls{glstreegroupheaderfmt} if the headers should have different formatting. +The \sty{glossaries-extra-stylemods} package (as from v1.31) now +redefine both \gls{glstreenamefmt} and \gls{glstreegroupheaderfmt} +to use: +\nosecformatdef{glstreedefaultnamefmt} +which does \code{\gls{textbf}\margm{text}} by default. This means +that if you want to change both the header and name to a different +font, you can just redefine \gls{glstreedefaultnamefmt}, and if you +want to change only the font used for the name, then now you only +need to redefine \gls{glstreenamefmt}, without also having to +redefine \gls{glstreegroupheaderfmt}. + +Case-changing can be automatically applied to the name with the +\catattr{glossname} attribute, which may take one of the values: +\code{firstuc} (convert the first letter to \idx{uppercase}), \code{title} +(convert to title case) or \code{uc} (convert to all capitals). +Alternatively, if you're using \bibgls, you can use the +\csopt{name-case-change} resource option. + +The description is similarly governed by the +\catattr{glossdescfont}, which again should have the name (without +the leading backslash) of a control sequence that takes a single +argument. There's no equivalent of \gls{glsnamefont} for the +description but the glossary or abbreviation style may apply +particular formatting, which will be in addition to the formatting +command given by \catattr{glossdescfont} (if set). + +Case-changing is also available for descriptions with the +\catattr{glossdesc} attribute, but this only has two allowed values: +\code{firstuc} (convert the first letter to \idx{uppercase}) and +\code{title} (convert to title case). +Alternatively, if you're using \bibgls, you can use the +\csopt{description-case-change} resource option. + +\section{Post-Name and Post-Description Hooks} +\label{sec:postfieldhooks} + +Information can be appended to the \field{name} in the glossary for +a particular category using the \pidx{postnamehook}, which is given +by the command: +\nosecformatdef{glsxtrpostnamecategory} +The current entry's label can be referenced with: +\nosecformatdef{glscurrententrylabel} +For example, if the preferred glossary style doesn't include the +\field{symbol} field, but you want the symbol displayed after the +name for entries with the \field{category} field set to \code{symbol}: +\begin{codeenv} +\cmd{newcommand}\marg{\cmd{glsxtrpostnamesymbol}}\marg{\cmd{space} + (\gls{glsentrysymbol}\marg{\gls{glscurrententrylabel}})} +\end{codeenv} +There's a convenient shortcut: +\nosecformatdef{glsdefpostname} +which defines \gls{glsxtrpostnamecategory} to \meta{definition} +(using \gls{csdef}). There's also a more general purpose \idx{postnamehook} +used regardless of the category: +\nosecformatdef{glsextrapostnamehook} + +The \idx{postnamehook} is placed inside the formatting command used +for the \field{name} field in the glossary. It's only present in the +glossary (see \sectionref{sec:printgloss}) or stand-alone entries +(see \sectionref{sec:standalone}). + +There is a similar \pidx{postdescriptionhook}. For a particular category, +the hook is given by: +\nosecformatdef{glsxtrpostdesccategory} +There are some categories that have empty hooks already defined, +such as +\nosecformatdef{glsxtrpostdescgeneral} +These will need \csfmt{renewcommand} rather than \csfmt{newcommand}. +Again there's a shortcut command provided: +\nosecformatdef{glsdefpostdesc} +which just uses \gls{csdef}, so there's no check if the command is +already defined. +As with the \idx{postnamehook}, the entry's label can be accessed +with \gls{glscurrententrylabel}. + +Punctuation (such as a \idx{full-stop} or comma) can automatically be +appended to the description in the +glossary with the \styopt{postpunc} option. (Note that the +unstarred form of \gls{longnewglossaryentry} interferes with this +option. Use the starred form \gls{longnewglossaryentry*} instead.) +The post-description punctuation (if set) is placed after the +\glslink{postdescriptionhook}{post-description category hook} (if +provided). Both the post-description category hook and the +post-description punctuation are implemented by +\nosecformatdef{glspostdescription} +The \sty{glossaries-extra-stylemods} +package (which can be loaded with the \styopt{stylemods} option) +patches the predefined styles provided with the base +\sty{glossaries} package to ensure that the standard styles all use +\gls{glspostdescription}. + + +\chapter{Problematic Areas} +\label{sec:problems} + +There are some places where the use of commands like \gls{gls} can +cause problems. Common issues are listed below, with workarounds provided. + +\section{Headings and Captions} +\label{sec:headings} + +The arguments of sectioning commands (such as \gls{chapter} or +\gls{section}) and of captions (\gls{caption}) are +\pidxpl{moving-argument}. The text is not only displayed at the +point in the document where the command occurs, but may also be +copied to the \gls{toc} or list of figures etc. +Additionally, depending on the page style, the section argument may +also be reproduced in the page header. This repeated use of the same +material can cause complications, in particular it can prematurely +triggering the \idx{firstuseflag} switch and cause unwanted +indexing. If the content appears in the page header and the page +styles converts headers to upper case, this can also cause a +problem. + +For example: +\begin{codeenv} +\cmd{documentclass}\marg{book} +\strut +\cmd{usepackage}\marg{lipsum}\comment{provides \cmd{lipsum}} +\cmd{usepackage}\marg{glossaries} +\strut +\gls{newglossaryentry}\marg{sample}\marg{\field{name}=\marg{sample},\field{description}=\marg{an example}} +\strut +\cmd{begin}{document} +\gls{chapter}\marg{A \gls{gls}\marg{sample} chapter} +\cmd{lipsum} \comment{dummy text} +\cmd{end}\marg{document} +\end{codeenv} +I've used \csfmt{lipsum} here to create some dummy text that ensures +a multi-paged document because the problem doesn't occur until the second +page. The error message is: +\begin{verbatim} +Glossary entry `SAMPLE' has not been defined. +\end{verbatim} +The problem here is that the chapter title is copied to the header +(which doesn't appear on the chapter's first page) but the header +uses \gls{MakeUppercase}, which can't expand \gls{gls} but it does +change the label, so \code{\gls{gls}\marg{sample}} is converted to +\code{\gls{gls}\marg{SAMPLE}}, but there's no entry with that label. +(Labels are case-sensitive.) + +Here's an example that doesn't cause an error (because there's not +enough text to trigger a page break) but does cause unexpected output: +\begin{codeenv} +\cmd{documentclass}\marg{book} +\strut +\cmd{usepackage}\marg{glossaries-extra} +\strut +\gls{setabbreviationstyle}\marg{\abbrstyle{long-short-sc}} +\gls{newabbreviation}\marg{html}\marg{html}\marg{hypertext markup language} +\strut +\cmd{begin}\marg{document} +\gls{tableofcontents} +\gls{chapter}\marg{A chapter about \gls{gls}\marg{html}} +Reference \gls{gls}\marg{html}. +\cmd{end}\marg{document} +\end{codeenv} +On the first \LaTeX\ run, the \gls{toc} is empty as the +associated \ext{toc} file didn't exist at the start. The chapter title +appears as \qt{A chapter about hypertext markup language +(\textsc{html})}, which shows the \idx{firstuse} of +\code{\gls{gls}\marg{html}}. The \ext{toc} file (which was created +but not read by \gls{tableofcontents}) now contains: +\begin{codeenv} +\cmd{contentsline} \marg{chapter}\marg{\cmd{numberline} \marg{1}A chapter about \gls{gls} \marg{html}}\marg{3} +\end{codeenv} +This means that on the next \LaTeX\ run, the \gls{toc} now +includes \code{\gls{gls}\marg{html}}. Since the \gls{toc} +occurs at the start of the document, this is now the \idx{firstuse} +of \code{html}, so the full form is shown in the \gls{toc}, +but the chapter title is now \qt{A chapter about \textsc{html}}, which shows +the subsequent use. + +The \sty{glossaries-extra} package provides some commands that are +designed for use in section or caption titles. These include: +\nosecformatdef{glsfmtshort} +which shows the short form of an abbreviation, +\nosecformatdef{glsfmtlong} +which shows the long form of an abbreviation, +\nosecformatdef{glsfmtfull} +which shows the full form of an abbreviation, +\nosecformatdef{glsfmtname} +which shows the entry's name, +\nosecformatdef{glsfmtfirst} +which shows the entry's \field{first} field, and +\nosecformatdef{glsfmttext} +which shows the entry's \field{text} field. + +Here's a modified version of the above: +\begin{codeenv} +\cmd{documentclass}\marg{book} +\strut +\cmd{usepackage}\marg{lipsum}\comment{provides \cmd{lipsum}} +\cmd{usepackage}\marg{glossaries-extra} +\strut +\gls{setabbreviationstyle}\marg{\abbrstyle{long-short-sc}} +\gls{newabbreviation}\marg{html}\marg{html}\marg{hypertext markup language} +\strut +\cmd{begin}\marg{document} +\gls{tableofcontents} +\gls{chapter}\marg{A chapter about \gls{glsfmtlong}\marg{html}} +Reference \gls{gls}\marg{html}. +\cmd{lipsum} \comment{dummy text} +\cmd{end}\marg{document} +\end{codeenv} +This now shows the long form in the \gls{toc} and the +chapter title. Since \gls{glsfmtlong} doesn't affect the +\idx{firstuseflag}, the reference after the chapter title now shows +the \idx{firstuse} full form. There's no longer an error with the +page header on the second page, but it's not quite right as the +case-change hasn't been applied, so the page heading appears as: +\begin{result} +4\hfill \emph{CHAPTER 1. A CHAPTER ABOUT hypertext markup language} +\end{result} +This can be corrected by setting the \catattr{headuc} attribute to +\code{true}: +\begin{codeenv} +\gls{glssetcategoryattribute}\marg{abbreviation}\marg{headuc}\marg{true} +\end{codeenv} +This now makes the page header too long, but remember that you can +use the optional argument of sectioning commands to provide a +shorter form for both the page heading and \gls{toc}: +\begin{codeenv} +\gls{chapter}\oarg{A chapter about \gls{glsfmtshort}\marg{html}}\marg{A chapter about +\gls{glsfmtlong}\marg{html}} +\end{codeenv} +One final problem remains and it's due to the +\abbrstyle{long-short-sc} abbreviation style which uses \gls{textsc} +to display the short form in small capitals. The combination of +italic and small capitals isn't supported with the default fonts and +results in a font substitution. There's a similar problem in the +\gls{toc} which displays the chapter title in bold. There's +a warning at the end of the transcript: +\begin{verbatim} +Some font shapes were not available, defaults substituted. +\end{verbatim} +The conflict between bold and small capitals can be solved by +switching to the T1 font encoding: +\begin{codeenv} +\cmd{usepackage}[T1]\marg{\sty[noindex=false]{fontenc}} +\end{codeenv} +The conflict between italic and small capitals can be solved with +the \sty{slantsc} package. Another possibility is to redefine: +\nosecformatdef{glsabbrvscfont} +which is used by the \qt{sc} abbreviation styles: +\begin{codeenv} +\cmd{renewcommand}\marg{\gls{glsabbrvscfont}}[1]\marg{\comment{} + \gls{glsxtrifinmark}\marg{\gls{MakeTextUppercase}\marg{\gls{param}1}}\marg{\gls{textsc}\marg{\gls{param}1}}\comment{} +} +\end{codeenv} +This uses: +\nosecformatdef{glsxtrifinmark} +which expands to \meta{true} in headings and the \gls{toc}, +otherwise it expands to \meta{false}. This use of +\gls{MakeTextUppercase} replaces the need for the \catattr{headuc} +attribute. Both \catattr{headuc} and the above redefinition of +\gls{glsabbrvscfont} will cause the abbreviation to appear in +\idx{uppercase} in the \gls{toc}. If you don't want this, +you can defer making these modifications until after the +\gls{toc}. Alternatively, use: +\nosecformatdef{glsxtrRevertTocMarks} +which makes \gls{glsxtrifinmark} expand to \meta{false} in the +\gls{toc}. For example: +\begin{codeenv} +\cmd{documentclass}\marg{book} +\strut +\cmd{usepackage}[T1]\marg{fontenc} +\cmd{usepackage}\marg{lipsum} +\cmd{usepackage}\marg{glossaries-extra} +\strut +\cmd{renewcommand}\marg{\gls{glsabbrvscfont}}[1]\marg{\comment{} + \gls{glsxtrifinmark}\marg{\gls{MakeTextUppercase}\marg{\gls{param}1}}\marg{\gls{textsc}{\gls{param}1}}\comment{} +} +\strut +\gls{setabbreviationstyle}\marg{\abbrstyle{long-short-sc}} +\gls{newabbreviation}\marg{html}\marg{html}\marg{hypertext markup language} +\strut +\cmd{begin}\marg{document} +\gls{tableofcontents} +\gls{chapter}\oarg{A chapter about \gls{glsfmtshort}\marg{html}}\marg{A chapter +about \gls{glsfmtlong}\marg{html}} +Reference \gls{gls}\marg{html}. +\cmd{lipsum} \comment{dummy text} +\cmd{end}\marg{document} +\end{codeenv} + + +\section{Nesting} +\label{sec:nested} + +Nesting refers to commands like \gls{gls} and \gls{glssymbol} being +used in the \idx{link-text} of similar commands. This occurs if +these commands are used in fields that form part of the +\idx{link-text} or if they occur in the final \meta{insert} +optional argument (which is included in the \idx{link-text}) or in the +\idx{postlinkhook} (which isn't included in the \idx{link-text} but +is still problematic). + +The most serious problem is when the \idx{postlinkhook} includes one +of these commands that references an entry with the same category +(and therefore the same \idx{postlinkhook} code) as +you can end up with an infinite loop. For example: +\begin{codeenv} +\gls{glsdefpostlink}\marg{symbol}\marg{ (\gls{glssymbol}\marg{\gls{glslabel}})}\comment{infinite loop!}\incorrect +\end{codeenv} +Instead, use \gls{glsentrysymbol}: +\begin{codeenv} +\gls{glsdefpostlink}\marg{symbol}\marg{ (\gls{glsentrysymbol}\marg{\gls{glslabel}})}\correct +\end{codeenv} +Better still, use commands like +\gls{glsxtrpostlinkAddSymbolOnFirstUse} (see \sectionref{sec:postlinkhooks}). + +The next most problematic nesting is the use of \gls{gls} in +abbreviations. It's far more of a problem if you only use the base +\sty{glossaries} package. For example: +\begin{codeenv} +\cmd{documentclass}\marg{book} +\strut +\gls{usepackage}\marg{glossaries} +\strut +\gls{newacronym}\marg{ssi}\marg{SSI}\marg{server-side includes} +\gls{newacronym}\marg{html}\marg{HTML}\marg{hypertext markup language} +\gls{newacronym}\marg{shtml}\marg{SHTML}\marg{\gls{gls}\marg{ssi} enabled \gls{gls}\marg{html}}\incorrect +\strut +\cmd{begin}\marg{document} +\gls{gls}\marg{shtml}. +\cmd{end}\marg{document} +\end{codeenv} +This results in: +\begin{result} +server-side includes (SSI) enabled hypertext markup language (HTML) (SHTML). +\end{result} +The \sty{glossaries-extra} package temporarily changes \gls{gls} +within the \idx{link-text} to avoid this type of problem. +\begin{codeenv} +\cmd{documentclass}\marg{book} +\strut +\cmd{usepackage}\marg{glossaries-extra} +\strut +\gls{newabbreviation}\marg{ssi}\marg{SSI}\marg{server-side includes} +\gls{newabbreviation}\marg{html}\marg{HTML}\marg{hypertext markup language} +\gls{newabbreviation}\marg{shtml}\marg{SHTML}\marg{\gls{gls}\marg{ssi} enabled \gls{gls}\marg{html}} +\strut +\cmd{begin}\marg{document} +\gls{gls}\marg{shtml}. +\cmd{end}\marg{document} +\end{codeenv} +This now produces: +\begin{result} +SSI enabled HTML (SHTML). +\end{result} +This doesn't seem so bad, but now let's see what happens if the +\catattr{glossdesc} is set to \code{firstuc}: +\begin{codeenv} +\cmd{documentclass}\marg{book} +\strut +\cmd{usepackage}\marg{glossaries-extra} +\strut +\gls{glssetcategoryattribute}\marg{abbreviation}\marg{\catattr{glossdesc}}\marg{firstuc} +\gls{newabbreviation}\marg{ssi}\marg{SSI}\marg{server-side includes} +\gls{newabbreviation}\marg{html}\marg{HTML}\marg{hypertext markup language} +\gls{newabbreviation}\marg{shtml}\marg{SHTML}\marg{\gls{gls}\marg{ssi} enabled \gls{gls}\marg{html}}\incorrect +\strut +\cmd{begin}\marg{document} +\gls{gls}\marg{shtml}. +\gls{printunsrtglossary} +\cmd{end}\marg{document} +\end{codeenv} +This now causes an error: +\begin{verbatim} +! Missing \endcsname inserted. +<to be read again> + \protect +\end{verbatim} +The problem here is that the first-letter upper-casing command is +being applied to \code{\gls{gls}\marg{ssi}}. This results in +\code{\gls{gls}\marg{\gls{MakeTextUppercase} ssi}} which has an +invalid label. A workaround is to insert an empty group before +the initial \gls{gls}: +\begin{codeenv} +\gls{newabbreviation}\marg{shtml}\marg{SHTML}\marg{\marg{}\gls{gls}\marg{ssi} enabled \gls{gls}\marg{html}} +\end{codeenv} +However, \gls{gls} functions normally within the glossary, so the +result is: +\begin{result} +\textbf{SSI} Server-side includes + +\textbf{HTML} Hypertext markup language + +\textbf{SHTML} server-side includes (SSI) enabled hypertext markup language (HTML) +\end{result} +Since neither \code{ssi} nor \code{html} have been referenced in the +document, the reference in the \code{shtml} description in the +glossary is the \idx{firstuse} for both of them, so they show the +full form, but the upper-casing can't be applied. This means that +the description for the \code{shtml} entry doesn't start with an +\idx{uppercase} letter. The best solution is to avoid using +\gls{gls} in the \field{long} field: +\begin{codeenv} +\cmd{documentclass}\marg{book} +\strut +\cmd{usepackage}[\styopt{record}]\marg{glossaries-extra} +\strut +\gls{glssetcategoryattribute}\marg{abbreviation}\marg{glossdesc}\marg{firstuc} +\strut +\gls[noindex]{glsdefpostdesc}\marg{abbreviation}\marg{\comment{} + \gls{glsxtrifhasfield}\marg{\field{seealso}}\marg{\gls{glscurrententrylabel}}\comment{} + \marg{ (\gls{emph}\marg{see also} \gls[noindex=false]{glsxtrseelist}\marg{\gls{glscurrentfieldvalue}})}\comment{} + \marg{}\comment{} +} +\strut +\gls{newabbreviation}\marg{ssi}\marg{SSI}\marg{server-side includes} +\gls{newabbreviation}\marg{html}\marg{HTML}\marg{hypertext markup language} +\gls{newabbreviation}\oarg{\field{seealso}=\marg{ssi,html}}\marg{shtml}\marg{SHTML} +\marg{server-side includes enabled hypertext markup language} +\strut +\cmd{begin}\marg{document} +\gls{Gls}\marg{shtml}. +\gls{printunsrtglossary} +\cmd{end}\marg{document} +\end{codeenv} +I've used the \field{seealso} key here. (The value should be a +comma-separated list of labels.) It doesn't show +in the glossary by default as it needs an indexing application to add it +automatically to the \idx{locationlist}, so I've used the +\idx{postdescriptionhook} to append the cross-reference. The +\styopt{record} option is needed, otherwise the default +\gls{makeindex} setting will be assumed and an error will occur as +the associated \gls{makeindex} file hasn't been opened. If \bibgls\ +support is added then the hook won't be needed. + +\section{Shortcut Commands or Active Characters} +\label{sec:activeshortcuts} + +Some packages, such as \sty{babel}, provide shortcut commands or +active characters that can be enabled through a particular setting. +It's best not to use these in entry definitions. +Instead use the full command name. The main problem comes when the +shortcuts aren't enabled until the start of the \envfmt{document} +environment. For example, the \code{ngerman} language setting in +\sty{babel} makes the double quote character (\idx{doublequoteactivechar}) +active and it becomes a shortcut for \gls{umlaut} (the umlaut accent +command): +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[ngerman]\marg{babel} +\cmd{usepackage}\marg{glossaries-extra} +\strut +\gls{newabbreviation}\marg{rna}\marg{RNA}\marg{ribonukleins"aure}\incorrect +\strut +\cmd{begin}\marg{document} +Explicit use: ribonukleins"aure. +Reference: \gls{gls}\marg{rna}. +\cmd{end}\marg{document} +\end{codeenv} +This produces: +\begin{result} +Explicit use: ribonukleins\"aure. Reference: ribonukleins"aure (RNA). +\end{result} +This is because the double quote character still had its normal +meaning when the \code{rna} entry was defined, so the +\idx{doublequotechar} in the long form is an actual double quote +character not a shortcut for \gls{umlaut}. + +Another problem occurs when you have a large file containing entry +definitions that will be shared by multiple documents. If shortcut +commands are used in the entry definitions then every document that +uses those entries must ensure that the appropriate shortcut +commands are set up before use. Also, when using \bibgls, it +recognises commands like \gls{umlaut} but not \sty{babel} +shorthands, so the sorting will be adversely affected if you simply +use \idx{doublequoteactivechar} instead of \gls{umlaut}. + +For large files that are written once (with minor subsequent edits), +but reused many times for multiple documents, it's better to use the +actual command (that simply requires the appropriate package to be +loaded, if applicable, without specific options to enable it). + + +\section{Formatting Commands that Need Direct Access to the Text} +\label{sec:expandedfmt} + +If you want to redefine any of the formatting commands +\gls{glstextformat}, \gls{glsxtrregularfont} or +\gls{glsxtrabbreviationfont}, remember that their argument isn't the +actual text but consists of intermediary commands +that determine the required text and any inner formatting, such as +the formatting applied by abbreviation styles. + +With the \glsopt{hyperoutside} setting on, the outermost level +will be the command to apply the hyperlink with \gls{glstextformat} +(or the equivalent provided by \catattr{textformat}) +inside the hyperlink text. (If hyperlinks aren't enabled the outer +command simply does the hyperlink text.) + +With \glsopt[false]{hyperoutside}, the outermost level will be +\gls{glstextformat} (or equivalent) with the command that applies +the hyperlink inside the formatting argument. + +The next level down sets up the abbreviation styles for the given +category (if appropriate). If the entry isn't an abbreviation or is +an abbreviation classified as regular then +\gls{glsxtrregularfont} is applied to the command that governs how +regular entries are formatted. Otherwise \gls{glsxtrabbreviationfont} +is applied to the command that governs how abbreviations are +formatted. + +Finally, there are tests applied to determine if this is the +\idx{firstuse}, if the plural is required, if any case-changing is +required, if the final optional argument has been given, or if a +command such as \gls{glssymbol} has been used. These tests +determine which field to obtain the \idx{link-text} from. With +abbreviations, any formatting required by the abbreviation style is +finally performed. + +This makes it very difficult to apply a formatting command that +needs direct access to the actual text that needs to be displayed. +One possible method is to use: +\nosecformatdef{GlsXtrExpandedFmt} +which first (protected) fully expands \meta{text} and then performs +\meta{cs}\margm{expanded text} where \meta{cs} is a control +sequence. For example, the \isty{soul} package provides the command +\gls{ul} to underline text, but it needs to be able to parse its +argument to work. If I simply try to change the standard +\gls{underline} to \gls{ul} in the earlier example from +\sectionref{sec:glsformats}: +\begin{codeenv} +\cmd{renewcommand}\marg{\gls{glsxtrregularfont}}[1]\marg{\cmd{ul}\marg{\gls{param}1}} +\end{codeenv} +then this causes the error: +\begin{verbatim} +! Package soul Error: Reconstruction failed. +\end{verbatim} +Instead I need: +\begin{codeenv} +\cmd{renewcommand}\marg{\gls{glsxtrregularfont}}[1]\marg{\gls{GlsXtrExpandedFmt}\cmd{ul}\marg{\gls{param}1}} +\end{codeenv} +\emph{and also} \gls{ding} now needs protection: +\begin{codeenv} +\gls{newglossaryentry}\marg{fleuron}\comment{label} +\marg{ + \field{name} = \marg{fleuron}, + \field{symbol} = \marg{\gls{protect}\gls{ding}\marg{167}}, + \field{category} = \marg{ornament}, + \field{description} = \marg{typographic ornament} +} +\end{codeenv} + +\section{Buffering Changes to the First Use Flag} +\label{sec:buffering} + +The \sty{soul} commands, described above, also have problems if the +\idx{firstuseflag} is switched off within the argument. This can be +demonstrated with the following: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\cmd{usepackage}\marg{soul} +\cmd{usepackage}\marg{glossaries-extra} +\gls{newabbreviation}\marg{ssl}\marg{SSL}\marg{Secure Sockets Layer} +\cmd{begin}\marg{document} +\cmd{ul}\marg{Some text about \gls{gls}\marg{ssl}.} +\cmd{end}\marg{document} +\end{codeenv} +This produces the somewhat confusing error message: +\begin{verbatim} +Glossary entry `{ssl}' has not been defined. +\end{verbatim} +Enclosing \code{\gls{gls}\marg{ssl}} inside the argument of \csfmt{mbox} +changes the error message to: +\begin{verbatim} +! Package soul Error: Reconstruction failed. +\end{verbatim} +The only way to avoid an error is to switch on the \gls{glsunset} +buffering, which modifies the internal command that normally changes +the \idx{firstuseflag}. Instead, the entry label is simply stored in +an internal list. The buffering is switched on with: +\nosecformatdef{GlsXtrStartUnsetBuffering} +The unstarred form of this command may result in multiple +occurrences of an entry in the buffer's internal list. The starred form, +which only adds an entry's label to the list if not already present, +is better if the list needs to contain unique items. + +The current buffer can be iterated over using; +\nosecformatdef{GlsXtrForUnsetBufferedList} +where \meta{cs} is a command that takes a single argument (the +entry's label). Finally, entries in the buffer can be unset and the +buffer cleared with: +\nosecformatdef{GlsXtrStopUnsetBuffering} + +The above example will work if it's changed to: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\cmd{usepackage}\marg{soul} +\cmd{usepackage}\marg{glossaries-extra} +\gls{newabbreviation}\marg{ssl}\marg{SSL}\marg{Secure Sockets Layer} +\cmd{begin}\marg{document} +\gls{GlsXtrStartUnsetBuffering} +\cmd{ul}\marg{Some text about \cmd{mbox}\marg{\gls{gls}\marg{ssl}}.} +\gls{GlsXtrStopUnsetBuffering} +\cmd{end}\marg{document} +\end{codeenv} +Note the need for \csfmt{mbox}, which can cause a problem with +line-breaking. Another problem is that if the entry is referenced +multiple times within the same buffer, each use of \gls{gls} (or its +\idxpl{variant}) will be treated as the \idx{firstuse}. + +Another workaround is to use \glsopt{textformat} with a command that +uses \gls{GlsXtrExpandedFmt} (see \sectionref{sec:expandedfmt}). For +example: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\cmd{usepackage}\marg{soul} +\cmd{usepackage}\marg{glossaries-extra} +\strut +\cmd{newrobustcmd}\marg{\cmd{gul}}[1]\marg{\comment{} + \marg{\comment{} + \cmd{def}\gls{glsxtrabbreviationfont}\gls{param}\gls{param}1\marg{\gls{GlsXtrExpandedFmt}\marg{\cmd{ul}}\marg{\gls{param}\gls{param}1}}\comment{} + \cmd{def}\gls{glsxtrregularfont}\gls{param}\gls{param}1\marg{\gls{GlsXtrExpandedFmt}\marg{\cmd{ul}}\marg{\gls{param}\gls{param}1}}\comment{} + \gls{param}1\comment{} + }% +} +\strut +\gls{newabbreviation}\marg{ssl}\marg{SSL}\marg{Secure Sockets Layer} +\cmd{begin}\marg{document} +\cmd{ul}\marg{Some text about }\gls{gls}\oarg{\glsopt{textformat}=gul}\marg{ssl}. +\cmd{end}\marg{document} +\end{codeenv} + +\chapter{Incorporating \bibgls} +\label{sec:bib2gls} + +So far, the examples haven't actually used \bibgls, so what does it +actually do? Recall the example document in \sectionref{sec:group}, +reproduced below: +\begin{codeenv} +\cmd{documentclass}\marg{scrartcl} +\cmd{usepackage}\marg{mhchem} +\cmd{usepackage}[\styopt[dot]{postpunc},\comment{full stop after description} + \styopt{nostyles},\comment{don't load default style packages} + \styopt[tree]{stylemods}\comment{load glossary-tree.sty and patch styles} +]\marg{glossaries-extra} +\strut +\gls{glsaddstoragekey}\marg{group}\marg{}\marg{\cmd{grouplabel}} +\gls{glsxtrsetgrouptitle}\marg{greek}\marg{Greek Symbols} +\strut +\gls{newglossaryentry}\marg{area} +\marg{ + \field{name} = \marg{\gls{ensuremath}\marg{A}}, + \field{description} = \marg{area}, + \field{group} = \marg{A} +} +\strut +\gls{newglossaryentry}\marg{amethyst} +\marg{ + \field{name} = \marg{amethyst}, + \field{description} = \marg{a purple type of quartz}, + \field{symbol} = \marg{\gls{ce}\marg{SiO2}}, + \field{group} = \marg{A} +} +\strut +\gls{newglossaryentry}\marg{circumference} +\marg{ + \field{name} = \marg{\gls{ensuremath}\marg{C}}, + \field{description} = \marg{circumference}, + \field{group} = \marg{C} +} +\strut +\gls{newglossaryentry}\marg{duck} +\marg{ + \field{name} = \marg{duck}, + \field{description} = \marg{a waterbird with webbed feet}, + \field{group} = \marg{D} +} +\strut +\gls{newglossaryentry}\marg{goose} +\marg{ + \field{name} = \marg{goose}, + \field{description} = \marg{a large waterbird with a long neck, short legs, + webbed feet and a short broad bill}, + \field{group} = \marg{G} +} +\strut +\gls{newglossaryentry}\marg{radius} +\marg{ + \field{name} = \marg{\gls{ensuremath}\marg{r}}, + \field{description} = \marg{radius}, + \field{group} = \marg{R} +} +\strut +\gls{newglossaryentry}\marg{pi} +\marg{ + \field{name} = \marg{\gls{ensuremath}\marg{\cmd{pi}}}, + \field{description} = \marg{Archimedes' constant}, + \field{group} = \marg{greek} +} +\strut +\cmd{begin}\marg{document} +\gls{printunsrtglossary}\oarg{\printglossopt[indexgroup]{style}} +\cmd{end}\marg{document} +\end{codeenv} +The document preamble is quite cluttered. It could be tidied up by +moving all the \gls{newglossaryentry} code into a separate file +called, say, \filefmt{entries.tex}. The main document code can now +be simplified to: +\begin{codeenv} +\cmd{documentclass}\marg{scrartcl} +\cmd{usepackage}\marg{mhchem} +\cmd{usepackage}[ + \styopt{record},\comment{create \field{group} field and other stuff} + \styopt[dot]{postpunc},\comment{full stop after description} + \styopt{nostyles},\comment{don't load default style packages} + \styopt[tree]{stylemods}\comment{load glossary-tree.sty and patch styles} +]\marg{glossaries-extra} +\strut +\gls{glsxtrsetgrouptitle}\marg{greek}\marg{Greek Symbols} +\strut +\gls[noindex=false]{input}\marg{entries}\comment{input entries.tex} +\strut +\cmd{begin}\marg{document} +\gls{printunsrtglossary}\oarg{\printglossopt[indexgroup]{style}} +\cmd{end}\marg{document} +\end{codeenv} +This is much neater, but maintaining the \filefmt{entries.tex} file is +quite troublesome. Each entry must be defined in the correct order +(that matches the desired listing in \gls{printunsrtglossary}) and +only those entries that should appear in \gls{printunsrtglossary} +should be defined (unless you want the laborious task of filtering +them out, as in \sectionref{sec:printglossagain}). The \field{group} +field needs setting for every entry, and if the \field{location} +field also needs setting then the \filefmt{entries.tex} file will +need to be modified every time new document edits cause a shift in +the page numbers. + +With \bibgls, you write all the entry definitions (without the +\field{group} or \field{location} fields set) in one or more +\ext{bib} files. It's then \bibgls\ that creates the equivalent of +the above \filefmt{entries.tex} file with all the entry definitions +in the correct order and with the \field{group} or \field{location} +fields set, if appropriate. To avoid accidentally overwriting an +important document file, \bibgls\ uses the extension \ext{glstex} +rather than \ext{tex} (but it's still a file containing \LaTeX\ code +that defines the entries using \gls{newabbreviation} or +\gls{newglossaryentry}\footnote{Actually it uses +\gls{longnewglossaryentry*} to allow for multi-paragraph descriptions, +and \gls{longnewglossaryentry*} and \gls{newabbreviation} are used +indirectly through helper commands.}). + +Instead of using \gls{input} in the document preamble, you now need +to use: +\nosecformatdef{GlsXtrLoadResources} +The \ext{glstex} file doesn't exist on the first \LaTeX\ run as +\bibgls\ can only create the file once the \ext{aux} file has been +created (since the \ext{aux} file contains all the information about +which entries to select, the name of the \ext{bib} files where their +definitions are stored and how to order them). +So \gls{GlsXtrLoadResources} tests if the \ext{glstex} file exists +before trying to input it. The \styopt{record} option is necessary +because it: +\begin{itemize} +\item enables the \styopt[warn]{undefaction} option (the entries +aren't defined on the first \LaTeX\ run); +\item creates the \field{group} and \field{location} fields; +\item disables the \gls{makeindex}\slash\gls{xindy} indexing and +instead writes the indexing information as a record in the \ext{aux} +file; +\item loads \sty{glossaries-extra-bib2gls} (which provides +extra commands specific to \bibgls). +\end{itemize} +Each time you use a command like \gls{gls} or \gls{glssymbol} (but +not like \gls{glsentrysymbol}) in the document, a record is added to +the \ext{aux} file containing the entry's label, the location (by +default the page number) where the entry was used, and extra +information including how to format the location. The default +behaviour of \bibgls\ is to only select those entries that have +records in the \ext{aux} file and any dependent entries. + +The example above doesn't include any references (commands like +\gls{gls}), so \bibgls\ won't select any entries and the +\ext{glstex} file won't contain any definitions. This means that the +glossary will be empty. If you want all entries from the specified +\ext{bib} files selected then you need to change the \csopt{selection} +setting: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[all]{selection}} +\end{codeenv} +This doesn't explicitly name any \ext{bib} file. The default is +\code{\gls{jobname}\ext{bib}} but you can change this with the +\csopt{src} option. For example, if the entries are defined in +\filefmt{entries.bib} (regular terms), \filefmt{symbols.bib} +(symbols) and \filefmt{abbrvs.bib} (abbreviations) then you need +to use: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries,symbols,abbrvs]{src},\comment{bib files} + \csopt[all]{selection}\comment{select all entries} +} +\end{codeenv} + +You can have multiple instances of \gls{GlsXtrLoadResources}, but +remember that each instance inputs a file containing definitions, and +the glossary produced with \gls{printunsrtglossary} follows the same +order. This means that you can have blocks within the same glossary +that use different sorting methods. For example: +\begin{codeenv}\renewcommand{\glslinkpresetkeys}{}% +\gls{GlsXtrLoadResources}\oarg{ + \csopt[symbols]{src},\comment{bib file} + \csopt[letter-case]{sort},\comment{sort according to character code} + \csopt[symbol]{category},\comment{set this as the \field{category} field} + \csopt[glssymbols]{group}\comment{set this as the \field{group} field} +} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries,abbrvs]{src},\comment{bib files} + \csopt[en-GB]{sort} +} +\end{codeenv} +The first instance fetches the data from \filefmt{symbols.bib}, +sorts the entries according to the character code, sets the +\field{category} field to \code{symbol}, and sets the +\field{group} field to \code{glssymbols} for each definition +written to the \ext{glstex} file. The \code{glssymbols} group label is recognised by +the \sty{glossaries} package, and the title is obtained from the +language-sensitive \gls{glssymbolsgroupname} command (\qt{Symbols} +in English). So the glossary will start with a symbols group +that contains all the entries selected from \filefmt{symbols.bib}. +The rest of the glossary is obtained from the data selected from the +\filefmt{entries.bib} and \filefmt{abbrvs.bib} file sorted according +to the en-GB locale. These entries will have the \field{group} field +set by the locale's sort rule. + +The document build now needs to include a call to \bibgls. For +example, if the main document file is called \filefmt{myDoc.tex} +then the build process is: +\begin{verbatim} +pdflatex myDoc +bib2gls --group myDoc +pdflatex myDoc +\end{verbatim} +Omit the \longarg{group} switch if you want the \field{group} field +left empty, and replace \code{pdflatex} with \code{xelatex} etc, as +appropriate. + +\section{The \extfmt{bib} Format} +\label{sec:bibentries} + +The \ext{bib} files define entry data in the form: +\begin{codeenv} +\gls[noindex=false]{atchar}\meta{entry type}\marg{\meta{id}, + \meta{field$_1$} = \margm{value}, + \ldots + \meta{field$_n$} = \margm{value} +} +\end{codeenv} +where \meta{id} is the entry's label. The most basic entry type is +\atentry{entry}. For example: +\begin{codeenv} +\atentry{entry}\marg{goose, + \field{name} = \marg{goose}, + \field{plural} = \marg{geese}, + \field{description} = \marg{a large waterbird with a long neck, short legs, + webbed feet and a short broad bill} +} +\end{codeenv} +This is analogous to: +\begin{codeenv} +\gls{newglossaryentry}\marg{goose} +\marg{ + \field{name} = \marg{goose}, + \field{plural} = \marg{geese}, + \field{description} = \marg{a large waterbird with a long neck, short legs, + webbed feet and a short broad bill} +} +\end{codeenv} +You can use any of the defined keys, such as \field{symbol}: +\begin{codeenv} +\atentry{entry}\marg{amethyst, + \field{name} = \marg{amethyst}, + \field{description} = \marg{a purple type of quartz}, + \field{symbol} = \marg{\gls{ce}\marg{SiO2}} +} +\end{codeenv} +but avoid using internal fields. If you define custom keys in your +document, make sure you define them all before the first instance of +\gls{GlsXtrLoadResources} as all the recognised keys are written to +the \ext{aux} file for \bibgls\ to detect. Any unrecognised fields +in the \ext{bib} file are ignored. + +\begin{important} +The \atentry{entry} type is intended mainly for words or phrases, +optionally with an associated \field{symbol}. If +the \field{name} field contains symbols or other non-alphabetic +content (such as punctuation that shouldn't be ignored by the sort +comparator) see \sectionref{sec:@symbol}. +\end{important} + +\subsection{Defining Terms with Optional Descriptions} +\label{sec:@index} + +The \atentry{entry} type requires the \field{description} field and +either the \field{name} or \field{parent} field. There's a similar +command that doesn't have any required fields: \atentry{index}. If +the \field{name} isn't supplied, it's assumed to be the same as the +\meta{id}. If the \field{description} isn't supplied it's assumed to +be empty. This type behaves like \atentry{entry}, but it sets the +default \field{category} to \code{index}. So: +\begin{codeenv} +\atentry{index}\marg{duck} +\end{codeenv} +is analogous to: +\begin{codeenv} +\gls{newglossaryentry}\marg{duck} +\marg{ + \field{name}=\marg{duck}, + \field{description}=\marg{}, + \field{category}=\marg{index} +} +\end{codeenv} +and +\begin{codeenv} +\atentry{index}\marg{goose, + \field{plural} = \marg{geese} +} +\end{codeenv} +is analogous to: +\begin{codeenv} +\gls{newglossaryentry}\marg{goose} +\marg{ + \field{name}=\marg{goose}, + \field{plural}=\marg{geese}, + \field{description}=\marg{}, + \field{category}=\marg{index} +} +\end{codeenv} +If the name contains content that can't be used in a label (see +\sectionref{sec:labels}), then +you need the \field{name} field. For example: +\begin{codeenv} +\atentry{index}\marg{chateau, + \field{name} = \marg{ch\gls[noindex=false]{cs.circum}ateau}, + \field{plural} = \marg{ch\gls{cs.circum}ateaux} +} +\end{codeenv} +is analogous to: +\begin{codeenv} +\gls{newglossaryentry}\marg{chateau} +\marg{ + \field{name}=\marg{ch\gls{cs.circum}ateau}, + \field{plural}=\marg{ch\gls{cs.circum}ateaux}, + \field{description}=\marg{}, + \field{category}=\marg{index} +} +\end{codeenv} +There's a similar entry type \atentry{indexplural} that sets the +\field{name} field (if not provided) to the plural form, which is +obtained from the \field{plural} field, if set. Otherwise it's +obtained by appending the plural suffix (\qt{s}) to the \field{text} +field. If the \field{text} field isn't set it's obtained from the label. +The other difference is that it sets the default \field{category} field to +\code{indexplural}. For example, +\begin{codeenv} +\atentry{indexplural}\marg{duck} +\end{codeenv} +is analogous to: +\begin{codeenv} +\gls{newglossaryentry}\marg{duck} +\marg{ + \field{name}=\marg{ducks}, + \field{text}=\marg{duck}, + \field{description}=\marg{}, + \field{category}=\marg{indexplural} +} +\end{codeenv} +and +\begin{codeenv} +\atentry{indexplural}\marg{goose, + \field{plural} = \marg{geese} +} +\end{codeenv} +is analogous to: +\begin{codeenv} +\gls{newglossaryentry}\marg{goose} +\marg{ + \field{name}=\marg{geese}, + \field{text}=\marg{goose}, + \field{plural}=\marg{geese}, + \field{description}=\marg{}, + \field{category}=\marg{indexplural} +} +\end{codeenv} + +The \csopt[firstuc]{name-case-change} resource option converts the +first letter of the \field{name} field to \idx{uppercase}, so with +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[firstuc]{name-case-change}} +\end{codeenv} +then +\begin{codeenv} +\atentry{index}\marg{duck} +\end{codeenv} +is now analogous to: +\begin{codeenv} +\gls{newglossaryentry}\marg{duck} +\marg{ + \field{name}=\marg{Duck}, + \field{text}=\marg{duck}, + \field{description}=\marg{}, + \field{category}=\marg{index} +} +\end{codeenv} +and +\begin{codeenv} +\atentry{indexplural}\marg{goose, + \field{plural} = \marg{geese} +} +\end{codeenv} +is now analogous to: +\begin{codeenv} +\gls{newglossaryentry}\marg{goose} +\marg{ + \field{name}=\marg{Geese}, + \field{text}=\marg{goose}, + \field{plural}=\marg{geese}, + \field{description}=\marg{}, + \field{category}=\marg{indexplural} +} +\end{codeenv} +and +\begin{codeenv} +\atentry{entry}\marg{amethyst, + \field{name} = \marg{amethyst}, + \field{description} = \marg{a purple type of quartz}, + \field{symbol} = \marg{\gls{ce}\marg{SiO2}} +} +\end{codeenv} +is now analogous to: +\begin{codeenv} +\gls{newglossaryentry}\marg{amethyst} +\marg{ + \field{name}=\marg{Amethyst}, + \field{text}=\marg{amethyst}, + \field{description}=\marg{a purple type of quartz}, + \field{symbol} = \marg{\gls{ce}\marg{SiO2}} +} +\end{codeenv} + +\subsection{Defining Abbreviations} +\label{sec:@abbreviation} + +Abbreviations can be defined with \atentry{abbreviation}. For +example: +\begin{codeenv} +\atentry{abbreviation}\marg{html, + \field{short} = \marg{HTML}, + \field{long} = \marg{hypertext markup language} +} +\end{codeenv} +which is analogous to: +\begin{codeenv} +\gls{newabbreviation}\marg{html}\marg{HTML}\marg{hypertext markup language} +\end{codeenv} +(which sets the \field{category} to \code{abbreviation}). +Alternatively, you can use \atentry{acronym}. For example: +\begin{codeenv} +\atentry{acronym}\marg{html, + \field{short} = \marg{HTML}, + \field{long} = \marg{hypertext markup language} +} +\end{codeenv} +which is analogous to: +\begin{codeenv} +\gls{newacronym}\marg{html}\marg{HTML}\marg{hypertext markup language} +\end{codeenv} +(which sets the \field{category} to \code{acronym}). +If you decide to use one of the abbreviation styles that formats the +\field{short} field with \gls{textsc} (for example, +\abbrstyle{long-short-sc}) then the \field{short} value needs to be +in \idx{lowercase}. (Remember that \gls{textsc} only changes +\idx{lowercase} characters to small capitals. For example, +\code{\gls{textsc}\marg{html}} is displayed as \textsc{html} but +\code{\gls{textsc}\marg{HTML}} is displayed as \textsc{HTML}.) +This can easily be accomplished with the +\csopt{short-case-change} resource option. For example: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[lc]{short-case-change}} +\end{codeenv} +Recall from \sectionref{sec:abbreviations} that the abbreviation +style must be set \emph{before} the abbreviations are defined. This +means that if you want to use \gls{setabbreviationstyle} it must +come before \gls{GlsXtrLoadResources}. + +The default sort value used by \bibgls\ is usually taken from the +\field{name} field. This typically isn't supplied with abbreviations. +The actual value depends on the abbreviation style, which \bibgls\ +doesn't know about, so \bibgls\ uses the \field{short} +field instead for abbreviations. If you want to change this, for +example, if you are using the \abbrstyle{long-noshort-desc} style, +then use the \csopt{abbreviation-sort-fallback} option. For example: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[long]{abbreviation-sort-fallback}} +\end{codeenv} + +\subsection{Defining Symbols} +\label{sec:@symbol} + +If the \field{name} field contains the symbol (rather than having a +textual \field{name} and the symbol in \field{symbol}) then the +notation can be defined with \atentry{symbol}. For example: +\begin{codeenv} +\atentry{symbol}\marg{pi, + \field{name} = \marg{\gls{ensuremath}\marg{\cmd{pi}}}, + \field{description} = \marg{Archimedes' constant} +} +\end{codeenv} +This behaves much like \atentry{entry} but there are two significant +differences: the \field{category} defaults to \code{symbol} and the +default value used when sorting is the label not the value of the \field{name} +field. So in this case, the sort value defaults to \code{pi}. +Therefore the above is analogous to: +\begin{codeenv} +\gls{newglossaryentry}\marg{pi} +\marg{ + \field{name} = \marg{\gls{ensuremath}\marg{\cmd{pi}}}, + \field{description} = \marg{Archimedes' constant}, + \field{category} = \marg{symbol}, + \field{sort} = \marg{pi} +} +\end{codeenv} +This is essentially like \gls{glsxtrnewsymbol} but it doesn't set +the \field{type} field. + +You can change the default value used for sorting symbols with the +\csopt{symbol-sort-fallback} option. For example, to sort symbols according +to the \field{name} field: +\begin{codeenv}\renewcommand{\glslinkpresetkeys}{}% +\gls{GlsXtrLoadResources}\oarg{ + \csopt[name]{symbol-sort-fallback}, + \csopt[none]{break-at} +} +\end{codeenv} +This means that the sort value for the above example entry is now +\code{\gls{ensuremath}\marg{\csfmt{pi}}}, which \bibgls's \TeX\ +interpreter converts to the Unicode symbol \hex{1D70B} (mathematical +italic small pi, $\pi$). The interpreter used by \bibgls\ recognises +all the standard mathematical Greek commands, and also the missing +Greek commands \gls{omicron}, \gls{Alpha} etc (which are provided by +\sty{glossaries-extra-bib2gls}). Using these commands rather than +the Latin equivalent ensures correct sorting (\gls{omicron} comes +between \csfmt{xi} and \csfmt{pi}, but \code{o} comes between \code{n} +and \code{p}). See \sectionref{sec:texparserlib} (\TeX\ Parser +Library) in the \bibgls\ user manual for further details. + +\begin{important} +The default sort method is designed for words and phrases, so +non-letters, such as punctuation characters, are discarded. +If your sort values include symbols that need to be taken into +account by the comparator, use \csopt[none]{break-at} to prevent +them from being discarded. +\end{important} + +Alternatively, you may prefer to sort symbols according to the +description: +\begin{codeenv}\renewcommand{\glslinkpresetkeys}{}% +\gls{GlsXtrLoadResources}\oarg{\csopt[description]{symbol-sort-fallback}} +\end{codeenv} + +There's a similar entry type \atentry{number}, which behaves much +like \atentry{symbol} except that it sets the default +\field{category} to \code{number}. It also follows the +\csopt{symbol-sort-fallback} setting. For example, the \code{pi} +entry could be defined as: +\begin{codeenv} +\atentry{symbol}\marg{pi, + \field{name} = \marg{\gls{ensuremath}\marg{\cmd{pi}}}, + \field{description} = \marg{Archimedes' constant}, + \fieldfmt{value} = \marg{3.141592654} +} +\end{codeenv} +I've used a custom field here (\fieldfmt{value}) that \bibgls\ will +ignore by default. I can instruct \bibgls\ to convert this to a +known field with \csopt{field-aliases}. For example: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[value=user1]{field-aliases}} +\end{codeenv} +This makes \bibgls\ treat; +\begin{codeenv} + \fieldfmt{value} = \marg{3.141592654} +\end{codeenv} +as though it had been: +\begin{codeenv} + \fieldfmt{user1} = \marg{3.141592654} +\end{codeenv} +This can now be used in one of the hooks (described in +\sectionref{sec:glsformats}). For example, the +\idx{postdescriptionhook}: +\begin{codeenv}\renewcommand{\glslinkpresetkeys}{}% +\gls{glsdefpostdesc}\marg{number}\marg{\comment{check if \field{user1} field given:} + \gls{glsxtrifhasfield}\marg{\field{useri}}\marg{\gls{glscurrententrylabel}} + \marg{ (\gls{glscurrentfieldvalue})} + \marg{}\comment{not provided} +} +\end{codeenv} +It can also be used if you want to order the entries numerically. +For example: +\begin{codeenv}\renewcommand{\glslinkpresetkeys}{}% +\gls{GlsXtrLoadResources}\oarg{ + \csopt[value=user1]{field-aliases}, + \csopt[double]{sort},\comment{use double-precision numeric comparisons} + \csopt[user1]{sort-field} +} +\end{codeenv} +This uses \csopt{sort-field} to set the field used for sorting. This +affects all entry types. + +There are more examples in \sectionref{sec:examples} of the main +\bibgls\ user manual. + +\section{Indexing} +\label{sec:record} + +By default, \bibgls\ selects entries from the specified \ext{bib} +files that have been directly indexed in the document or that are +dependencies of selected entries. Indexing is performed through +commands like \gls{gls} and \gls{glssymbol} (but not by commands +like \gls{glsentrysymbol}). The \styopt{record} package option +ensures that the indexing is done that matches the requirements of +\bibgls\ (rather than the default \gls{makeindex} syntax). + +Each instance of \gls{gls}, \gls{glssymbol} etc writes a +\pidx{record} to the \ext{aux} file, that includes the entry's +label, the location in the document where the record was triggered +and the associated format to encapsulate the location. For example, +if \code{\gls{gls}\marg{duck}} appears on page~3, the record label +is \code{duck}, the location is~3 and the format is the default +\gls{glsnumberformat}. + +The format can be changed with the \glsopt{format} key. For example: +\begin{codeenv} +\gls{gls}\oarg{\glsopt{format}=hyperbf}\marg{duck} +\end{codeenv} +This sets the format to \code{hyperbf}, which makes a bold +hyperlink, if \sty{hyperref} has been loaded, otherwise it just uses +\gls{textbf}. The value of the \glsopt{format} option should be the +name (without a leading backslash) of a text-block command that +takes a single argument (the location to be formatted). The +\sty{glossaries} package provides some commands like \gls{hyperbf} +that may be used to ensure a hyperlink (if supported). The basic +command is: +\nosecformatdef{glshypernumber} +which provides the hyperlink (if enabled) otherwise it just does its +argument. So, if you want, for example, an underlined hyperlink: +\begin{codeenv} +\cmd{newcommand}\marg{\cmd{hyperul}}[1]\marg{\gls[noindex=false]{underline}\marg{\gls{glshypernumber}\marg{\gls{param}1}}} +\end{codeenv} +Now you can use \glsopt[hyperul]{format}. + +There's a special command \gls{glsignore} that ignores its argument. +With \gls{makeindex} and \gls{xindy}, this can lead to spurious +commas in the \idx{locationlist}, because the location is still +included in the list, even though the location itself isn't +displayed (since it's discarded by \gls{glsignore}). However, \bibgls\ +recognises \glsopt[glsignore]{format} as a special \idx{ignoredrecord}. This +indicates that \bibgls\ should select that particular entry but not +include that record in the \idx{locationlist}. + +If a selected entry depends on another entry that hasn't been +indexed, for example, a parent entry, then the dependent entry will +automatically be selected as well, by default. The dependent entry +won't have a \idx{locationlist} if it hasn't been indexed anywhere. +If you don't want the \idxpl{locationlist} to appear in a particular +glossary, use \printglossopt{nonumberlist} in the optional argument +of \gls{printunsrtglossary}. + +If you want to index an entry without actually displaying any text, +you can use: +\nosecformatdef{glsadd} +where \meta{label} is the entry's label. The \glsaddopt{format} key +is again available in \meta{options}. For example: +\begin{codeenv} +\cmd{renewcommand}\marg{\gls{glsextrapostnamehook}}[1]\marg{\comment + \gls{glsadd}\oarg{\glsaddopt{format}=hyperbf}\marg{\gls{param}1}\comment{} +} +\end{codeenv} +This automatically indexes the given entry in the +\idx{postnamehook}. This is redundant if you only have a single +glossary, but may be useful if the entry is repeated in a later +list. Alternatively, if you are using a dual entry type (see +\sectionref{sec:dualentry} in the main \bibgls\ user manual), the +hook could check for the existence of the dual label (identified by +the \csopt{dual-field} resource option) and use that instead. For +example: +\begin{codeenv}\renewcommand{\glslinkpresetkeys}{}% +\cmd{renewcommand}\marg{\gls{glsextrapostnamehook}}[1]\marg{\comment + \gls{glsxtrifhasfield}\marg{\gls{GlsXtrDualField}}\marg{\gls{param}1} + \marg{\comment{} + \gls{glsadd}\oarg{\glsaddopt{format}=hyperbf}\marg{\gls{glscurrentfieldvalue}}\comment{} + }\comment{} + \marg{}\comment{no dual} +} +\end{codeenv} + +If you want to index multiple entries at the same time with the same +set of options, you can use: +\nosecformatdef{glsaddeach} +This just iterates through the comma-separated list of labels and +performs \gls{glsadd}\oargm{options}\margm{label} for each label in +\meta{label list}. For example, to ensure that \bibgls\ selects the +entries with the labels \code{duck}, \code{goose} and \code{parrot}, +even if they aren't referenced in the document: +\begin{codeenv} +\gls{glsaddeach}\oarg{\glsaddopt[glsignore]{format}}\marg{duck,goose,parrot} +\end{codeenv} +To select all entries, regardless of whether or not they have been +indexed, use the \csopt[all]{selection} resource option. There are +other selection criteria. See the main \bibgls\ user manual for +further details. + +\section{Aliasing Fields and Entry Types} +\label{sec:resourcealias} + +In \sectionref{sec:abbrvtrans}, the \field{user1} key was used to +store a translation: +\begin{codeenv} +\gls{newabbreviation}\oarg{\field{user1}=\marg{ribonucleic acid}} + \marg{rna}\marg{RNA}\marg{ribonukleins\gls{umlaut}aure} +\end{codeenv} +You can also use the generic user fields in \ext{bib} files, but +a more flexible approach is to use a semantic naming scheme in the +\ext{bib} file and use resource aliasing to convert these custom +field names into recognised keys. For example, the above +abbreviation could be written in the \ext{bib} file as: +\begin{codeenv} +\atentry{abbreviation}\marg{rna, + \field{short} = \marg{RNA}, + \field{long} = \marg{ribonukleins\gls{umlaut}aure}, + \fieldfmt{translation} = \marg{ribonucleic acid} +} +\end{codeenv} +The custom \fieldfmt{translation} field will be ignored by \bibgls, +unless it's first defined in the document or aliased in the resource +options: +\begin{codeenv}\renewcommand{\glslinkpresetkeys}{}% +\gls{GlsXtrLoadResources}\oarg{ + \csopt[abbrvs]{src},\comment{entries defined in abbrvs.bib} + \comment{treat \fieldfmt{translation} as though it's \field{user1}:} + \csopt[translation=user1]{field-aliases} +} +\end{codeenv} +This makes \bibgls\ behave as though the entry was defined in the +\bibgls\ file as: +\begin{codeenv} +\atentry{abbreviation}\marg{rna, + \field{short} = \marg{RNA}, + \field{long} = \marg{ribonukleins\gls{umlaut}aure}, + \field{user1} = \marg{ribonucleic acid} +} +\end{codeenv} +The definition is now the same as the above example from +\sectionref{sec:abbrvtrans}. The \ext{bib} entry type can also be +aliased. Here's a modified version: +\begin{codeenv} +\atentryfmt{foreignabbreviation}\marg{rna, + \field{short} = \marg{RNA}, + \fieldfmt{nativelong} = \marg{ribonukleins\gls{umlaut}aure}, + \fieldfmt{foreignlong} = \marg{ribonucleic acid} +} +\end{codeenv} +and here are the aliases: +\begin{codeenv}\renewcommand{\glslinkpresetkeys}{}% +\gls{GlsXtrLoadResources}\oarg{ + \csopt[abbrvs]{src},\comment{entries defined in abbrvs.bib} + \comment{treat \atentryfmt{foreignabbreviation} as though it's \atentry{abbreviation}:} + \csopt[foreignabbreviation=abbreviation]{entry-type-aliases}, + \csopt[nativelong=long,foreignlong=user1]{field-aliases} +} +\end{codeenv} +This has the same result, but suppose another document is in English +rather than German: +\begin{codeenv}\renewcommand{\glslinkpresetkeys}{}% +\gls{GlsXtrLoadResources}\oarg{ + \csopt[abbrvs]{src},\comment{entries defined in abbrvs.bib} + \csopt[foreignabbreviation=abbreviation]{entry-type-aliases}, + \csopt[foreignlong=long]{field-aliases} +} +\end{codeenv} +Now the \field{long} field is set to the English version, and the +German long form is ignored. + +Here's another example where the native language is now English: +\begin{codeenv}\renewcommand{\glslinkpresetkeys}{}% +\atentry{abbreviation}\marg{iso, + \field{short} = \marg{ISO}, + \field{long} = \marg{International Organization for Standardization} +} +\strut +\atentryfmt{foreignabbreviation}\marg{abnt, + \field{short} = \marg{ABNT}, + \fieldfmt{foreignlong} = \marg{Associa\gls{c}\marg{c}\gls{cs.tilde}ao Brasileria de Normas T\cs{acute}ecnicas}, + \fieldfmt{nativelong} = \marg{Brazilian National Standards Organization}, + \fieldfmt{language} = \marg{pt-BR} +} +\strut +\atentryfmt{foreignabbreviation}\marg{din, + \field{short} = \marg{DIN}, + \fieldfmt{foreignlong} = \marg{Deutsches Institut f\gls{umlaut}ur Normung e.V.}, + \fieldfmt{nativelong} = \marg{German Institute for Standardization}, + \fieldfmt{language} = \marg{de-DE-1996} +} +\end{codeenv} +The aliasing is again identified in the resource options: +\begin{codeenv}\renewcommand{\glslinkpresetkeys}{}% +\gls{GlsXtrLoadResources}\oarg{ + \csopt[abbrvs]{src},\comment{entries defined in abbrvs.bib} + \csopt[foreignabbreviation=abbreviation]{entry-type-aliases}, + \csopt[nativelong=long,foreignlong=user1,language=user2]{field-aliases}, + \csopt[same as original entry]{category} +} +\end{codeenv} +This has an extra setting that assigns the \field{category} field to +the original entry type (before any aliasing occurred) without the +leading \gls{atchar} (and converted to \idx{lowercase}). This makes +\bibgls\ act as though the abbreviations had actually been defined +as: +\begin{codeenv} +\atentry{abbreviation}\marg{iso, + \field{short} = \marg{ISO}, + \field{long} = \marg{International Organization for Standardization}, + \field{category} = \marg{abbreviation} +} +\strut +\atentryfmt{abbreviation}\marg{abnt, + \field{short} = \marg{ABNT}, + \field{user1} = \marg{Associa\gls{c}\marg{c}\gls{cs.tilde}ao Brasileria de Normas T\cs{acute}ecnicas}, + \field{long} = \marg{Brazilian National Standards Organization}, + \field{user2} = \marg{pt-BR}, + \field{category} = \marg{foreignabbreviation} +} +\strut +\atentryfmt{abbreviation}\marg{din, + \field{short} = \marg{DIN}, + \field{user1} = \marg{Deutsches Institut f\gls{umlaut}ur Normung e.V.}, + \field{long} = \marg{German Institute for Standardization}, + \field{user2} = \marg{de-1996}, + \field{category} = \marg{foreignabbreviation} +} +\end{codeenv} +which is now the same as an earlier example in +\sectionref{sec:abbrvtrans}. +If I don't need a particular custom field (such as +\fieldfmt{language} in the above), I can simply omit it from the +aliasing, but it's available for other documents if the need arises. +Here's the complete document modified from +\sectionref{sec:abbrvtrans}: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[main=british,brazilian,ngerman]\marg{babel} +\cmd{usepackage}[\styopt{record}]\marg{glossaries-extra} +\strut +\gls{setabbreviationstyle}\oarg{foreignabbreviation}\marg{long-short-user} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[abbrvs]{src},\comment{entries defined in abbrvs.bib} + \csopt[foreignabbreviation=abbreviation]{entry-type-aliases}, + \csopt[nativelong=long,foreignlong=user1,language=user2]{field-aliases}, + \csopt[same as original entry]{category} +} +\strut +\cmd{renewcommand}*\marg{\gls{glsxtruserparen}}[2]\marg{\comment{} + \gls{glsxtrfullsep}\marg{\gls{param}2}\comment{} + \gls{glsxtrparen} + \marg{\gls{param}1\comment{} + \gls{ifglshasfield}\marg{\gls{glsxtruserfield}}\marg{\gls{param}2}\comment{} + \marg{, \gls{emph}\marg{\gls{GlsXtrForeignText}\marg{\gls{param}2}\marg{\gls{glscurrentfieldvalue}}}}\comment{} + \marg{}\comment{} + }\comment{} +} +\strut +\cmd{begin}\marg{document} +\gls{gls}\marg{abnt}, \gls{gls}\marg{din}. +\cmd{end}\marg{document} +\end{codeenv} + +Here's another example where field and entry aliasing can make the +\ext{bib} data more flexible: +\begin{codeenv} +\atentryfmt{mineral}\marg{amethyst, + \fieldfmt{mineralname} = \marg{amethyst}, + \fieldfmt{mineraldescription} = \marg{a purple type of quartz}, + \fieldfmt{mineralformula} = \marg{\gls{ce}\marg{SiO2}} +} +\end{codeenv} +For one document, I might use: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{data in entries.bib} + \csopt[mineral=symbol]{entry-type-aliases}, + \csopt[ + mineralformula=name, + mineralname=description + ]{field-aliases}, + \csopt[same as original entry]{category} +} +\end{codeenv} +This makes the \code{amethyst} entry behave as though it was defined +as: +\begin{codeenv} +\atentry{symbol}\marg{amethyst, + \field{description} = \marg{amethyst}, + \field{name} = \marg{\gls{ce}\marg{SiO2}}, + \field{category} = \marg{mineral} +} +\end{codeenv} +Another document might have: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{data in entries.bib} + \csopt[mineral=entry]{entry-type-aliases}, + \csopt[ + mineralformula=symbol, + mineralname=name + mineraldescription=description + ]{field-aliases}, + \csopt[same as original entry]{category} +} +\end{codeenv} +which now makes the \code{amethyst} entry behave as though it was defined +as: +\begin{codeenv} +\atentry{entry}\marg{amethyst, + \field{name} = \marg{amethyst}, + \field{description} = \marg{a purple type of quartz}, + \field{symbol} = \marg{\gls{ce}\marg{SiO2}}, + \field{category} = \marg{mineral} +} +\end{codeenv} + +See \sectionref{sec:examples} in the main \bibgls\ user manual for +more examples of aliasing fields and entry types. + +\bibliographystyle{plain} +\bibliography{bib2gls-cite} + +\printunsrtglossary* + [style=treegroup,title={Command Summary},nonumberlist] +{% + \renewcommand*{\printunsrtglossaryentryprocesshook}[1]{% + \glsifcategory{#1}{command}{}{\printunsrtglossaryskipentry}% + }% + \glssetcategoryattribute{command}{glossdesc}{firstuc}% + \renewcommand*{\csfmtfont}[1]{\texttt{\color{cs}#1}}% + \renewcommand{\glstreenamefmt}{\texttt}% + \renewcommand{\glstreegroupheaderfmt}{\textbf}% + \renewcommand{\glstreesubitem}{\glspar\parindent=2em\hangindent2em}% + \renewcommand{\glstreepredesc}{\glsadd{\glscurrententrylabel}% + \nopagebreak\glstreesubitem}% + \glsdefpostname{command}{\glsentryuseri{\glscurrententrylabel}}% + \glsdefpostdesc{command}{.\nopagebreak\glstreesubitem + \Glsentryuserii{\glscurrententrylabel}.% + \glspar\medskip}% +} + +\renewcommand*{\glstarget}[2]{% + \glsifcategory{#1}{command}{#2}% + {% + \glsifcategory{#1}{standalone}{#2}% + {\glsdohypertarget{\glolinkprefix#1}{#2}}% + }% +} +\renewcommand{\glstreeitem}{\par\parindent0pt} +\renewcommand*{\glsxtrbookindexprelocation}[1]{% + \glsxtrifhasfield{location}{#1}% + {\enspace + \textcolor{lightgray}{\nolinebreak\cleaders\hbox to .5em{\hss.\hss}\hfill}% + \enspace}% + {}% +} +\renewcommand*{\printunsrtglossaryentryprocesshook}[1]{% + \glsxtriflabelinlist{\glscategory{#1}}{standalone,hierarchical,homograph}% + {\printunsrtglossaryskipentry}{}% +}% +\printunsrtglossary[style=bookindex,title=Index] +\end{document} diff --git a/support/bib2gls/src/bib2gls-cite.bib b/support/bib2gls/src/bib2gls-cite.bib new file mode 100644 index 0000000000..6c57ad1614 --- /dev/null +++ b/support/bib2gls/src/bib2gls-cite.bib @@ -0,0 +1,157 @@ +% Encoding: UTF-8 + +@misc{glossaries, + author = "Nicola Talbot", + title = "The \sty{glossaries} package", + note = {\url{https://ctan.org/pkg/glossaries}}, + year = 2018 +} + +@misc{glossaries-extra, + author = "Nicola Talbot", + title = "The \sty{glossaries-extra} package", + note = {\url{https://ctan.org/pkg/glossaries-extra}}, + year = 2018 +} + +@misc{mfirstuc, + author = "Nicola Talbot", + title = "The \sty{mfirstuc} package", + note = {\url{https://ctan.org/pkg/mfirstuc}}, + year = 2017 +} + +@misc{textcase, + author = "David Carlisle", + title = "The \sty{textcase} package", + note = {\url{https://ctan.org/pkg/textcase}}, + year = 2004 +} + +@misc{tracklang, + author = "Nicola Talbot", + title = "The \sty{tracklang} package", + note = {\url{https://ctan.org/pkg/tracklang}}, + year = 2018 +} + +@misc{accsupp, + author = "Heiko Oberdiek", + title = "The \sty{accsupp} package", + note = {\url{https://ctan.org/pkg/accsupp}}, + year = 2018 +} + +@misc{tex.sx, + title={Is there a program for managing glossary tags?}, + note={\url{https://tex.stackexchange.com/questions/342544}}, + key={TeX on StackExchange}, + year=2016 +} + +@misc{texparser, + author = "Nicola Talbot", + title={\code{texparserlib}: {Java} code for parsing {(La)TeX} files}, + note={\url{https://github.com/nlct/texparser}}, + year=2017 +} + +@misc{collationkey, + author={Oracle}, + title={Java {API}: \code{CollationKey} class}, + note={\url{http://docs.oracle.com/javase/8/docs/api/java/text/CollationKey.html}}, + year=2017 +} + +@misc{pattern, + author={Oracle}, + title={Java {API}: \code{Pattern} class}, + note={\url{http://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html}}, + year=2017 +} + +@misc{rulebasedcollator, + author={Oracle}, + title={Java {API}: \code{RuleBasedCollator} class}, + note={\url{http://docs.oracle.com/javase/8/docs/api/java/text/RuleBasedCollator.html}}, + year=2017 +} + +@misc{collator, + author={Oracle}, + title={Java {API}: \code{Collator} class}, + note={\url{http://docs.oracle.com/javase/8/docs/api/java/text/Collator.html}}, + year=2017 +} + +@misc{decimalformat, + author={Oracle}, + title={Java {API}: \code{DecimalFormat} class}, + note={\url{http://docs.oracle.com/javase/8/docs/api/java/text/DecimalFormat.html}}, + year=2017 +} + +@misc{simpledateformat, + author={Oracle}, + title={Java {API}: \code{SimpleDateFormat} class}, + note={\url{http://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html}}, + year=2017 +} + +@misc{javacldr, + author={Oracle}, + title={Adoption of Unicode CLDR Data and the java.locale.providers +System Property}, + note={\url{https://docs.oracle.com/javase/8/docs/technotes/guides/intl/enhancements.8.html#cldr}}, + year = 2018 +} + +@misc{javaoptions, + author={Oracle}, + title = {The JAVA\_TOOL\_OPTIONS Environment Variable}, + note={\url{https://docs.oracle.com/javase/8/docs/technotes/guides/troubleshoot/envvars002.html}}, + year = 2018 +} + +@misc{gallery, + author = {Nicola Talbot}, + title = {{Dickimaw Books} Gallery}, + note = {\url{https://www.dickimaw-books.com/gallery/}}, + year = 2019 +} + +@misc{glossarystylesgallery, + author = {Nicola Talbot}, + title = {Gallery (All Styles Provided by \sty{glossaries})}, + note = {\url{https://www.dickimaw-books.com/gallery/glossaries-styles/}}, + year = 2019 +} + +@misc{buildglossaries, + author = {Nicola Talbot}, + title = {Incorporating \idx{makeglossaries} or + \idx{makeglossaries-lite} or \bibgls\ into the document build}, + note = {\url{https://www.dickimaw-books.com/latex/buildglossaries}}, + year = 2018 +} + +@inbook{iterationtips, + author = "Nicola L. C. Talbot", + title = "{\LaTeX} for Administrative Work", + publisher = "Dickimaw Books", + series = "Dickimaw {\LaTeX} Series", + chapter = "2.7.5", + volume = 3, + isbn = "978-1-909440-07-4", + address = "Norfolk, UK", + year = 2015, + note = {\url{http://www.dickimaw-books.com/latex/admin/html/foreachtips.shtml}} +} + +@misc{tugusergroups, + author={{\TeX{} Users Group}}, + title={{\TeX}\ user groups around the world}, + note={\url{http://tug.org/usergroups.html}}, + year=2017 +} + diff --git a/support/bib2gls/src/bib2gls.bib b/support/bib2gls/src/bib2gls.bib new file mode 100644 index 0000000000..ec94ffe5d5 --- /dev/null +++ b/support/bib2gls/src/bib2gls.bib @@ -0,0 +1,16439 @@ +% Encoding: UTF-8 + +% Custom entry types will need aliasing. +% +% @bibglscommand -> \bibgls... command provided by bib2gls +% @glscommand -> command provided by glossaries.sty, +% glossaries-extra.sty or supplemental glossary packages. +% @mainglscommand -> glossary-related command with formal syntax described +% in the main matter. +% @abbrvstylecommand -> command used by abbreviation styles. +% @glostylecommand -> command used by glossary styles. +% @resourceoption -> \GlsXtrLoadResources option +% @command -> command provided by kernel or other package +% @examplecommand -> custom command defined in the examples +% @fileformat -> file format +% @application -> application +% @package -> package +% @specialchar -> special character +% @environment -> environment +% @glsenvironment -> environment provided by glossaries.sty +% @abbreviationstyle -> abbreviation style +% @glossarystyle -> glossary style +% @categoryattribute -> category attribute +% @counter -> counter +% @labelprefix -> label prefix +% @packageoption -> package option +% @field -> field +% @entrytype -> entry type +% @switch -> command line switch +% @xmltag -> tag in XML language resource file +% @unicodecategory -> Unicode category +% @texmfcnf -> texmf.cnf setting +% @file -> file +% @samplefile -> sample file +% @printglossoption -> \printunsrtglossary option +% @glslinkoption -> \glslink option +% @glsaddoption -> \glsadd option +% @exampleentry -> example entry +% @examplesymbol -> example symbol +% @exampleindex -> example term +% @exampleabbreviation -> example abbreviation +% @topic -> topic + +@preamble{"\providecommand{\dhyphen}{-} +\providecommand{\csfmt}[1]{\texttt{\glsbackslash #1}} +\providecommand{\derivfn}[1]{f'(#1)} +\providecommand{\rangestartmark}{\symbol{40}} +\providecommand{\rangeendmark}{\symbol{41}} +\providecommand{\abbrvword}[1]{\textup{#1}}"} + +@abbreviation{IETF, + short = {IETF}, + long = {Internet Engineering Task Force} +} + +@abbreviation{JVM, + short = {JVM}, + long = {Java Virtual Machine} +} + +@abbreviation{JRE, + short = {JRE}, + long = {Java Runtime Environment} +} + +@abbreviation{TUG, + short = {TUG}, + long = {{}\TeX\ Users Group} +} + +@abbreviation{CLDR, + short = {CLDR}, + long = {Unicode Common Locale Data Repository} +} + +@abbreviation{SIunit, + short = {SI \abbrvword{unit}}, + long = {International System of Units}, + longplural = {International System of Units}, + category={common} +} + +@abbreviation{ASCII, + short = {ASCII}, + long = {American Standard Code for Information Interchange}, + category={common} +} + +@abbreviation{CJK, + short = {CJK}, + long = {Chinese, Japanese, Korean languages}, + category={common} +} + +@abbreviation{encap, + short = {encap}, + long = {encapsulating command} +} + +@abbreviation{toc, + short = {TOC}, + long = {table of contents} +} + +@topic{definingterms, + name={defining terms} +} + +@topic{formattingcommands, + name={formatting commands}, + text={formatting command} +} + +@topic{abbreviationcommands, + name={abbreviation commands (general)}, + text={abbreviation command}, + seealso={abbreviationstyles} +} + +@topic{glossarystylecommands, + name={glossary style commands (general)}, + text={glossary style command}, + seealso={glossarystyle} +} + +@topic{separatorcommands, + name={separator commands} +} + +@topic{crossrefcommands, + name={cross-referencing commands} +} + +@topic{loclistcommands, + name={location list commands (records)} +} + +@topic{fixedtextcommands, + name={fixed text commands} +} + +@topic{fieldrefcommands, + name={field reference commands} +} + +@topic{entryrefcommands, + name={entry reference commands} +} + +@topic{glossrefs, + name={glossary lists (\fieldfmt{type})} +} + +@topic{standalonestyles, + name={standalone styles} +} + +@topic{providingcommands, + name={defining or redefining commands} +} + +@topic{linkcommands, + name={hyperlink-capable commands or targets} +} + +@topic{supplementalrefs, + name={supplemental document references} +} + +@topic{assigncommands, + name={assignment commands}, + text={assignment command} +} + +@topic{groupcommands, + name={glossary group commands} +} + +@topic{charcommands, + name={character or symbol commands} +} + +@topic{casecommands, + name={case-changing commands}, + text={case-changing command} +} + +@topic{internalcommands, + name={internal commands} +} + +@topic{auxcommands, + name={auxiliary file commands}, + text={auxiliary file command} +} + +@topic{capheadcommands, + name={caption or heading commands}, + text={caption or heading command} +} + +@topic{listcommands, + name={list commands (internal or comma-separated)}, + text={list command} +} + +@topic{collationsubrules, + name={collation sub-rules} +} + +@topic{catattrcommands, + name={categories and attributes} +} + +@topic{regex, + name={regular expressions}, + text={regular expression}, +} + +@topic{access-support, + name={accessibility support} +} + +@topic{conditionals, + name={conditionals and boolean values}, + text={conditional}, + plural={conditionals} +} +@indexplural{booleanvals, + text={boolean value}, + alias={conditionals} +} + +@topic{debugging, + name={debugging commands}, + text={debugging command} +} + +@topic{shortcutcommands, + name={shortcut commands}, + text={shortcut command} +} + +@topic{hooks,name={hooks},text={hook}} +@topic{loops,name={loops},text={loop}} +@index{iteration,see={loops}} +@indexplural{handler,seealso={loops}} +@topic{indexing} + +@bibglscommand{bibglsnewentry, + name={\csfmt{bib\-gls\-new\-entry}}, + user1={\margm{label}\margm{options}\margm{name}\margm{description}}, + description={defines terms provided with \atentry{entry}}, + note={\bibgls}, + topics={definingterms}, + category={command} +} + +@bibglscommand{bibglsnewsymbol, + name={\csfmt{bib\-gls\-new\-symbol}}, + user1={\margm{label}\margm{options}\margm{name}\margm{description}}, + description={defines terms provided with \atentry{symbol}}, + topics={definingterms}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglsnewnumber, + name={\csfmt{bib\-gls\-new\-number}}, + user1={\margm{label}\margm{options}\margm{name}\margm{description}}, + description={defines terms provided with \atentry{number}}, + note={\bibgls}, + topics={definingterms}, + category={command} +} + +@bibglscommand{bibglsnewindex, + name={\csfmt{bib\-gls\-new\-index}}, + user1={\margm{label}\margm{options}}, + description={defines terms provided with \atentry{index}}, + note={\bibgls}, + topics={definingterms}, + category={command} +} + +@bibglscommand{bibglsnewindexplural, + name={\csfmt{bib\-gls\-new\-index\-plural}}, + user1={\margm{label}\margm{options}\margm{name}}, + description={defines terms provided with \atentry{index}}, + note={\bibgls}, + topics={definingterms}, + category={command} +} + +@bibglscommand{bibglsnewabbreviation, + name={\csfmt{bib\-gls\-new\-abbreviation}}, + user1={\margm{label}\margm{options}\margm{short}\margm{long}}, + description={defines terms provided with \atentry{abbreviation}}, + note={\bibgls}, + topics={definingterms}, + category={command} +} + +@bibglscommand{bibglsnewacronym, + name={\csfmt{bib\-gls\-new\-acronym}}, + user1={\margm{label}\margm{options}\margm{short}\margm{long}}, + description={defines terms provided with \atentry{acronym}}, + topics={definingterms}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglsnewdualentry, + name={\csfmt{bib\-gls\-new\-dual\-entry}}, + user1={\margm{label}\margm{options}\margm{name}\margm{description}}, + description={defines terms provided with \atentry{dualentry}}, + topics={definingterms}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglsnewdualindexentry, + name={\csfmt{bib\-gls\-new\-dual\-index\-entry}}, + user1={\margm{label}\margm{options}\margm{name}\margm{description}}, + description={defines primary terms provided with +\atentry{dualindexentry}}, + note={\bibgls}, + topics={definingterms}, + category={command} +} + +@bibglscommand{bibglsnewdualindexentrysecondary, + name={\csfmt{bib\-gls\-new\-dual\-index\-entry\-secondary}}, + user1={\margm{label}\margm{options}\margm{name}\margm{description}}, + description={defines secondary terms provided with +\atentry{dualindexentry}}, + note={\bibgls}, + topics={definingterms}, + category={command} +} + +@bibglscommand{bibglsnewdualindexsymbol, + name={\csfmt{bib\-gls\-new\-dual\-index\-symbol}}, + user1={\margm{label}\margm{options}\margm{name}\margm{symbol}\margm{description}}, + description={defines primary terms provided with +\atentry{dualindexsymbol}}, + topics={definingterms}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglsnewdualindexsymbolsecondary, + name={\csfmt{bib\-gls\-new\-dual\-index\-symbol\-secondary}}, + user1={\margm{label}\margm{options}\margm{name}\margm{description}}, + description={defines secondary terms provided with +\atentry{dualindexsymbol}}, + note={\bibgls}, + topics={definingterms}, + category={command} +} + +@bibglscommand{bibglsnewdualindexnumber, + name={\csfmt{bib\-gls\-new\-dual\-index\-number}}, + user1={\margm{label}\margm{options}\margm{name}\margm{symbol}\margm{description}}, + description={defines primary terms provided with +\atentry{dualindexnumber}}, + note={\bibgls}, + topics={definingterms}, + category={command} +} + +@bibglscommand{bibglsnewdualindexnumbersecondary, + name={\csfmt{bib\-gls\-new\-dual\-index\-number\-secondary}}, + user1={\margm{label}\margm{options}\margm{name}\margm{description}}, + description={defines secondary terms provided with +\atentry{dualindexnumber}}, + note={\bibgls}, + topics={definingterms}, + category={command} +} + +@bibglscommand{bibglsnewdualindexabbreviation, + name={\csfmt{bib\-gls\-new\-dual\-index\-abbre\-via\-tion}}, + user1={\margm{label}\margm{dual-label}\margm{options}\margm{name}\margm{short}\margm{long}\margm{description}}, + description={defines primary terms provided with +\atentry{dualindexabbreviation}}, + note={\bibgls}, + topics={definingterms}, + category={command} +} + +@bibglscommand{bibglsnewdualindexabbreviationsecondary, + name={\csfmt{bib\-gls\-new\-dual\-index\-abbre\-via\-tion\-sec\-ond\-ary}}, + user1={\margm{label}\margm{options}\margm{name}\margm{short}\margm{long}\margm{description}}, + description={defines secondary terms provided with +\atentry{dualindexabbreviation}}, + note={\bibgls}, + topics={definingterms}, + category={command} +} + +@bibglscommand{bibglsnewdualabbreviationentry, + name={\csfmt{bib\-gls\-new\-dual\-abbre\-via\-tion\-entry}}, + user1={\margm{label}\margm{options}\margm{short}\margm{long}\margm{description}}, + description={defines primary terms provided with +\atentry{dualabbreviationentry}}, + note={\bibgls}, + topics={definingterms}, + category={command} +} + +@bibglscommand{bibglsnewdualabbreviationentrysecondary, + name={\csfmt{bib\-gls\-new\-dual\-abbre\-via\-tion\-entry\-sec\-ond\-ary}}, + user1={\margm{label}\margm{options}\margm{short}\margm{long}\margm{description}}, + description={defines secondary terms provided with +\atentry{dualabbreviationentry}}, + note={\bibgls}, + topics={definingterms}, + category={command} +} + +@bibglscommand{bibglsnewdualentryabbreviation, + name={\csfmt{bib\-gls\-new\-dual\-entry\-abbre\-via\-tion}}, + user1={\margm{label}\margm{options}\margm{short}\margm{long}\margm{description}}, + description={defines primary terms provided with (deprecated) +\atentry{dualentryabbreviation}}, + note={\bibgls}, + topics={definingterms}, + category={command} +} + +@bibglscommand{bibglsnewdualentryabbreviationsecondary, + name={\csfmt{bib\-gls\-new\-dual\-entry\-abbre\-via\-tion\-sec\-ond\-ary}}, + user1={\margm{label}\margm{options}\margm{short}\margm{long}\margm{description}}, + description={defines secondary terms provided with (deprecated) +\atentry{dualentryabbreviation}}, + topics={definingterms}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglsnewdualsymbol, + name={\csfmt{bib\-gls\-new\-dual\-symbol}}, + user1={\margm{label}\margm{options}\margm{name}\margm{description}}, + description={defines terms provided with \atentry{dualsymbol}}, + note={\bibgls}, + topics={definingterms}, + category={command} +} + +@bibglscommand{bibglsnewdualnumber, + name={\csfmt{bib\-gls\-new\-dual\-number}}, + user1={\margm{label}\margm{options}\margm{name}\margm{description}}, + description={defines terms provided with \atentry{dualnumber}}, + note={\bibgls}, + topics={definingterms}, + category={command} +} + +@bibglscommand{bibglsnewdualabbreviation, + name={\csfmt{bib\-gls\-new\-dual\-abbre\-via\-tion}}, + user1={\margm{label}\margm{options}\margm{short}\margm{long}}, + description={defines terms provided with +\atentry{dualabbreviation}}, + topics={definingterms}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglsnewdualacronym, + name={\csfmt{bib\-gls\-new\-dual\-acronym}}, + user1={\margm{label}\margm{options}\margm{short}\margm{long}}, + description={defines terms provided with \atentry{dualacronym}}, + note={\bibgls}, + topics={definingterms}, + category={command} +} + +@bibglscommand{bibglsnewtertiaryindexabbreviationentry, + name={\csfmt{bib\-gls\-new\-tert\-iary\-index\-abbre\-via\-tion\-entry}}, + user1={\margm{label}\margm{dual-label}\margm{options}\margm{name}\margm{short}\margm{long}\margm{description}}, + description={defines primary terms provided with +\atentry{tertiaryindexabbreviationentry}}, + note={\bibgls}, + topics={definingterms}, + category={command} +} + +@bibglscommand{bibglsnewtertiaryindexabbreviationentrysecondary, + name={\csfmt{bib\-gls\-new\-tert\-iary\-index\-abbre\-via\-tion\-entry\-sec\-ond\-ary}}, + user1={\margm{label}\margm{tertiary-label}\margm{options}\margm{tertiary-opts}\margm{primary-name}\margm{short}\margm{long}\margm{description}}, + description={defines secondary and tertiary terms provided with +\atentry{tertiaryindexabbreviationentry}}, + note={\bibgls}, + topics={definingterms}, + category={command} +} + +@bibglscommand{bibglsnewbibtexentry, + name={\csfmt{bib\-gls\-new\-bib\-tex\-entry}}, + user1={\margm{label}\margm{options}\margm{name}\margm{description}}, + description={defines terms provided with \atentry{bibtexentry}}, + note={\bibgls}, + topics={definingterms}, + category={command} +} + +@bibglscommand{bibglsnewcontributor, + name={\csfmt{bib\-gls\-new\-con\-trib\-u\-tor}}, + user1={\margm{label}\margm{options}\margm{name}\margm{description}}, + description={defines terms provided with + \atentry{contributor}}, + note={\bibgls}, + topics={definingterms}, + category={command} +} + +@bibglscommand{bibglsnewprogenitor, + name={\csfmt{bib\-gls\-new\-progenitor}}, + user1={\margm{label}\margm{options}\margm{name}\margm{description}}, + description={defines terms provided with \atentry{progenitor}}, + note={\bibgls}, + topics={definingterms}, + category={command} +} + +@bibglscommand{bibglsnewspawnindex, + name={\csfmt{bib\-gls\-new\-spawn\-index}}, + user1={\margm{label}\margm{options}\margm{name}\margm{description}}, + description={defines terms provided with \atentry{spawnindex}}, + note={\bibgls}, + topics={definingterms}, + category={command} +} + +@bibglscommand{bibglsnewspawndualindexentry, + name={\csfmt{bib\-gls\-new\-spawn\-dual\-index\-entry}}, + user1={\margm{label}\margm{options}\margm{name}\margm{description}}, + description={defines terms provided with \atentry{spawndualindexentry}}, + note={\bibgls}, + topics={definingterms}, + category={command} +} + +@bibglscommand{bibglsnewspawndualindexentrysecondary, + name={\csfmt{bib\-gls\-new\-spawn\-dual\-index\-entry\-secondary}}, + user1={\margm{label}\margm{options}\margm{name}\margm{description}}, + description={defines secondary terms provided with \atentry{spawndualindexentry}}, + note={\bibgls}, + topics={definingterms}, + category={command} +} + +@bibglscommand{bibglsnewspawnedindex, + name={\csfmt{bib\-gls\-new\-spawned\-index}}, + user1={\margm{label}\margm{options}}, + description={defines terms spawned from \atentry{progenitor} + or \atentry{spawnindex}}, + note={\bibgls}, + topics={definingterms}, + category={command} +} + +@bibglscommand{bibglsnewspawnindexplural, + name={\csfmt{bib\-gls\-new\-spawn\-index\-plural}}, + user1={\margm{label}\margm{options}\margm{name}\margm{description}}, + description={defines terms provided with \atentry{spawnindexplural}}, + note={\bibgls}, + topics={definingterms}, + category={command} +} + +@bibglscommand{bibglsnewspawnedindexplural, + name={\csfmt{bib\-gls\-new\-spawned\-index\-plural}}, + user1={\margm{label}\margm{options}\margm{name}}, + description={defines terms spawned from \atentry{spawnindexplural}}, + note={\bibgls}, + topics={definingterms}, + category={command} +} + +@bibglscommand{bibglsnewspawnentry, + name={\csfmt{bib\-gls\-new\-spawn\-entry}}, + user1={\margm{label}\margm{options}\margm{name}\margm{description}}, + description={defines terms provided with \atentry{spawnentry}}, + note={\bibgls}, + topics={definingterms}, + category={command} +} + +@bibglscommand{bibglsnewspawnedentry, + name={\csfmt{bib\-gls\-new\-spawned\-entry}}, + user1={\margm{label}\margm{options}}, + description={defines terms spawned from \atentry{spawnentry}}, + note={\bibgls}, + topics={definingterms}, + category={command} +} + +@bibglscommand{bibglsnewspawnabbreviation, + name={\csfmt{bib\-gls\-new\-spawn\-abbreviation}}, + user1={\margm{label}\margm{options}\margm{short}\margm{long}}, + description={defines terms provided with \atentry{spawnabbreviation}}, + note={\bibgls}, + topics={definingterms}, + category={command} +} + +@bibglscommand{bibglsnewspawnedabbreviation, + name={\csfmt{bib\-gls\-new\-spawned\-abbreviation}}, + user1={\margm{label}\margm{options}\margm{short}\margm{long}}, + description={defines terms spawned from \atentry{spawnabbreviation}}, + note={\bibgls}, + topics={definingterms}, + category={command} +} + +@bibglscommand{bibglsnewspawnacronym, + name={\csfmt{bib\-gls\-new\-spawn\-acronym}}, + user1={\margm{label}\margm{options}\margm{short}\margm{long}}, + description={defines terms provided with \atentry{spawnacronym}}, + note={\bibgls}, + topics={definingterms}, + category={command} +} + +@bibglscommand{bibglsnewspawnedacronym, + name={\csfmt{bib\-gls\-new\-spawned\-acronym}}, + user1={\margm{label}\margm{options}\margm{short}\margm{long}}, + description={defines terms spawned from \atentry{spawnacronym}}, + note={\bibgls}, + topics={definingterms}, + category={command} +} + +@bibglscommand{bibglsnewspawnsymbol, + name={\csfmt{bib\-gls\-new\-spawn\-symbol}}, + user1={\margm{label}\margm{options}\margm{name}\margm{description}}, + description={defines terms provided with \atentry{spawnsymbol}}, + note={\bibgls}, + topics={definingterms}, + category={command} +} + +@bibglscommand{bibglsnewspawnedsymbol, + name={\csfmt{bib\-gls\-new\-spawned\-symbol}}, + user1={\margm{label}\margm{options}\margm{name}\margm{description}}, + description={defines terms spawned from \atentry{spawnsymbol}}, + note={\bibgls}, + topics={definingterms}, + category={command} +} + +@bibglscommand{bibglsnewspawnnumber, + name={\csfmt{bib\-gls\-new\-spawn\-number}}, + user1={\margm{label}\margm{options}\margm{name}\margm{description}}, + description={defines terms provided with \atentry{spawnnumber}}, + note={\bibgls}, + topics={definingterms}, + category={command} +} + +@bibglscommand{bibglsnewspawnednumber, + name={\csfmt{bib\-gls\-new\-spawned\-number}}, + user1={\margm{label}\margm{options}\margm{name}\margm{description}}, + description={defines terms spawned from \atentry{spawnnumber}}, + note={\bibgls}, + topics={definingterms}, + category={command} +} + +@bibglscommand{bibglsuselongfont, + name={\csfmt{bib\-gls\-use\-long\-font}}, + user1={\margm{text}\margm{category}}, + description={ensures that the given text is formatted according to + the given category's long format}, + note={\bibgls}, + topics={definingterms}, + category={command} +} + +@glscommand{glsuselongfont, + name={\csfmt{gls\-use\-long\-font}}, + user1={\margm{text}\margm{category}}, + description={applies the formatting command used for the long + form for the abbreviation style associated with the given category}, + note={\styfmt{glossaries-extra} v1.21+}, + topics={formattingcommands,abbreviationcommands}, + category={command} +} + +@glscommand{ifglsxtrinsertinside, + name={\csfmt{if\-gls\-xtr\-insert\-inside}}, + description={switch that determines whether or not inserted text + (provided in the final optional argument of commands like \cs{gls}) + is inside or outside of the font changing commands in the predefined + abbreviation styles. The default is \optfmt{false}}, + topics={abbreviationcommands,conditionals}, + note={\styfmt{glossaries-extra} v1.02+}, + category={command} +} + +@glscommand{glsxtrinsertinsidefalse, + name={\csfmt{gls\-xtr\-insert\-inside\-false}}, + description={sets the \cs{ifglsxtrinsertinside} switch to \optfmt{false}}, + topics={abbreviationcommands,conditionals}, + note={\styfmt{glossaries-extra} v1.02+}, + category={command} +} + +@glscommand{glsxtrinsertinsidetrue, + name={\csfmt{gls\-xtr\-insert\-inside\-true}}, + description={sets the \cs{ifglsxtrinsertinside} switch to \optfmt{true}}, + topics={abbreviationcommands,conditionals}, + note={\styfmt{glossaries-extra} v1.02+}, + category={command} +} + +@glscommand{glsxtrfullsep, + name={\csfmt{gls\-xtr\-full\-sep}}, + user1={\margm{label}}, + description={the separator used in the full format for the + parenthetical abbreviation styles or for inline parenthetical + styles. This just does a space by default}, + topics={formattingcommands,abbreviationcommands}, + note={\styfmt{glossaries-extra}}, + category={command} +} + +@glscommand{GlsXtrAutoAddOnFormat, + name={\csfmt{GlsXtrAutoAddOnFormat}}, + user1={\oargm{label}\margm{format list}\margm{glsadd options}}, + description={makes commands like \cs{gls} and \cs{glslink} + (but not \cs{glsadd}) automatically insert \cs{glsadd}\oargm{glsadd + options}\margm{label} if the format (supplied in the optional + argument of the invoking \cs{gls}, \cs{glslink} etc) matches any in the given + comma-separated elements of \meta{format list}. The format isn't automatically + applied to the \cs{glsadd} options}, + note={\styfmt{glossaries-extra} v1.37+}, + topics={hooks,indexing}, + category={command} +} + +@bibglscommand{bibglsuseabbrvfont, + name={\csfmt{bib\-gls\-use\-abbrv\-font}}, + user1={\margm{text}\margm{category}}, + description={ensures that the given text is formatted according to + the given category's short format}, + note={\bibgls}, + topics={formattingcommands,abbreviationcommands}, + category={command} +} + +@glscommand{glsuseabbrvfont, + name={\csfmt{gls\-use\-abbrv\-font}}, + user1={\margm{text}\margm{category}}, + description={applies the formatting command used for the short + form for the abbreviation style associated with the given category}, + note={\styfmt{glossaries-extra} v1.21+}, + topics={formattingcommands,abbreviationcommands}, + category={command} +} + +@bibglscommand{bibglsseesep, + name={\csfmt{bib\-gls\-see\-sep}}, + user1={}, + description={separator between \field{see} + cross-references and location list}, + note={\bibgls}, + topics={glossarystylecommands,separatorcommands,crossrefcommands,loclistcommands}, + category={command} +} + +@bibglscommand{bibglsaliassep, + name={\csfmt{bib\-gls\-alias\-sep}}, + user1={}, + description={separator between \field{alias} + cross-reference and location list}, + note={\bibgls}, + topics={glossarystylecommands,separatorcommands,crossrefcommands,loclistcommands}, + category={command} +} + +@bibglscommand{bibglsseealsosep, + name={\csfmt{bib\-gls\-see\-also\-sep}}, + user1={}, + description={separator between \field{seealso} + cross-references and location list}, + note={\bibgls}, + topics={glossarystylecommands,separatorcommands,crossrefcommands,loclistcommands}, + category={command} +} + +@bibglscommand{bibglscompact, + name={\csfmt{bib\-gls\-compact}}, + user1={\margm{pattern}\margm{part1}\margm{part2}}, + description={compaction used on the end range location}, + note={\bibgls}, + topics={glossarystylecommands,loclistcommands}, + category={command} +} + +@bibglscommand{bibglspassim, + name={\csfmt{bib\-gls\-passim}}, + user1={}, + description={passim range suffix}, + note={\bibgls}, + topics={glossarystylecommands,loclistcommands}, + category={command} +} + +@bibglscommand{bibglspassimname, + name={\csfmt{bib\-gls\-passim\-name}}, + user1={}, + description={name used by passim range suffix}, + note={\bibgls}, + topics={glossarystylecommands,loclistcommands,fixedtextcommands}, + category={command} +} + +@bibglscommand{bibglsusesee, + name={\csfmt{bib\-gls\-use\-see}}, + user1={\margm{label}}, + description={display \field{see} cross-reference list for given entry}, + note={\bibgls}, + topics={glossarystylecommands,crossrefcommands,loclistcommands,fieldrefcommands}, + category={command} +} + +@bibglscommand{bibglsusealias, + name={\csfmt{bib\-gls\-use\-alias}}, + user1={\margm{label}}, + description={display the \field{alias} cross-reference for given entry}, + topics={glossarystylecommands,crossrefcommands,loclistcommands,fieldrefcommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglsuseseealso, + name={\csfmt{bib\-gls\-use\-see\-also}}, + user1={\margm{label}}, + description={display the \field{seealso} cross-reference list for given entry}, + topics={glossarystylecommands,crossrefcommands,loclistcommands,fieldrefcommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglsdelimN, + name={\csfmt{bib\-gls\-delimN}}, + user1={}, + description={separator for individual locations (except last)}, + seealso={bibglslastDelimN}, + note={\bibgls}, + topics={glossarystylecommands,loclistcommands,separatorcommands}, + category={command} +} + +@bibglscommand{bibglslastDelimN, + name={\csfmt{bib\-gls\-last\-DelimN}}, + user1={}, + description={separator before the last location (where there is + more than one location)}, + seealso={bibglsdelimN}, + topics={glossarystylecommands,loclistcommands,separatorcommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglsrange, + name={\csfmt{bib\-gls\-range}}, + user1={\marg{\meta{start}\cs{delimR} \meta{end}}}, + description={Explicit range format}, + note={\bibgls}, + topics={glossarystylecommands,loclistcommands}, + category={command} +} + +@bibglscommand{bibglsinterloper, + name={\csfmt{bib\-gls\-inter\-loper}}, + user1={\margm{location}}, + description={interloper location format}, + note={\bibgls}, + topics={glossarystylecommands,loclistcommands}, + category={command} +} + +@bibglscommand{bibglspostlocprefix, + name={\csfmt{bib\-gls\-post\-loc\-prefix}}, + user1={}, + description={location list post prefix}, + note={\bibgls}, + topics={glossarystylecommands,loclistcommands}, + category={command} +} + +@bibglscommand{bibglslocprefix, + name={\csfmt{bib\-gls\-loc\-prefix}}, + user1={\margm{n}}, + description={location list prefix}, + topics={glossarystylecommands,loclistcommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglsprimary, + name={\csfmt{bib\-gls\-primary}}, + user1={\margm{n}\margm{locations}}, + description={location list encapsulator used in the +\field{primarylocations} field}, + topics={loclistcommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglspagename, + name={\csfmt{bib\-gls\-page\-name}}, + user1={}, + description={name used for single page}, + topics={glossarystylecommands,loclistcommands,fixedtextcommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglspagesname, + name={\csfmt{bib\-gls\-pages\-name}}, + user1={}, + description={name used for multiple pages}, + topics={glossarystylecommands,loclistcommands,fixedtextcommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglslocsuffix, + name={\csfmt{bib\-gls\-loc\-suffix}}, + user1={\margm{n}}, + description={location list suffix}, + topics={glossarystylecommands,loclistcommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglshyperlink, + name={\csfmt{bib\-gls\-hyper\-link}}, + user1={\margm{text}\margm{label}}, + description={displays \meta{text} with a hyperlink to the entry + given by \meta{label}, if supported}, + topics={linkcommands,fieldrefcommands}, + note={\bibgls\texparserdefnote}, + category={command} +} + +@bibglscommand{bibglslocationgroup, + name={\csfmt{bib\-gls\-location\-group}}, + user1={\margm{n}\margm{counter}\margm{list}}, + description={location group encapsulator}, + topics={glossarystylecommands,loclistcommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglslocationgroupsep, + name={\csfmt{bib\-gls\-location\-group\-sep}}, + user1={}, + description={location group separator}, + topics={glossarystylecommands,loclistcommands,separatorcommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglssupplemental, + name={\csfmt{bib\-gls\-supple\-mental}}, + user1={\margm{n}\margm{list}}, + description={supplemental list encapsulator}, + note={\bibgls}, + topics={glossarystylecommands,loclistcommands,supplementalrefs}, + category={command} +} + +@bibglscommand{bibglssupplementalsep, + name={\csfmt{bib\-gls\-supple\-mental\-sep}}, + user1={}, + description={separator between main and supplementary locations}, + topics={glossarystylecommands,loclistcommands,supplementalrefs,separatorcommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglssupplementalsublist, + name={\csfmt{bib\-gls\-supple\-mental\-sub\-list}}, + user1={\margm{n}\margm{external document}\margm{list}}, + description={supplemental sub-list encapsulator}, + topics={glossarystylecommands,loclistcommands,supplementalrefs}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglssupplementalsubsep, + name={\csfmt{bib\-gls\-supple\-mental\-sub\-sep}}, + user1={}, + description={separator between supplementary sub-lists}, + topics={glossarystylecommands,loclistcommands,supplementalrefs,separatorcommands}, + note={\bibgls}, + category={command} +} + +@mainglscommand{glsgroupheading, + name={\csfmt{gls\-group\-heading}}, + user1={\margm{label}}, + description={formats the heading for the group identified by the +given label}, + topics={glossarystylecommands,formattingcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@bibglscommand{bibglssetlastgrouptitle, + name={\csfmt{bib\-gls\-set\-last\-group\-title}}, + user1={\margm{cs}\margm{specs}}, + description={sets the last group title}, + topics={glossarystylecommands,assigncommands,groupcommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglssetlettergrouptitle, + name={\csfmt{bib\-gls\-set\-letter\-group\-title}}, + user1={\marg{\margm{title}\margm{letter}\margm{id}\margm{type}}}, + description={sets the letter group title}, + topics={glossarystylecommands,assigncommands,groupcommands}, + note={\bibgls}, + category={command} +} + +@mainglscommand{glsxtrsetgrouptitle, + name={\csfmt{gls\-xtr\-set\-group\-title}}, + user1={\margm{group label}\margm{group title}}, + description={globally sets the title for the group identified by the given label}, + topics={glossarystylecommands,assigncommands,groupcommands}, + note={\styfmt{glossaries-extra} v1.14+}, + category={command} +} + +@glscommand{glsxtrlocalsetgrouptitle, + name={\csfmt{gls\-xtr\-local\-set\-group\-title}}, + user1={\margm{group label}\margm{group title}}, + description={locally sets the title for the group identified by the given label}, + topics={glossarystylecommands,assigncommands,groupcommands}, + note={\styfmt{glossaries-extra} v1.24+}, + category={command} +} + +@bibglscommand{bibglslettergroup, + name={\csfmt{bib\-gls\-letter\-group}}, + user1={\margm{title}\margm{letter}\margm{id}\margm{type}}, + description={expands to the letter group label}, + topics={glossarystylecommands,groupcommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglslettergrouptitle, + name={\csfmt{bib\-gls\-letter\-group\-title}}, + user1={\margm{title}\margm{letter}\margm{id}\margm{type}}, + description={expands to the letter group title}, + topics={glossarystylecommands,groupcommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglssetothergrouptitle, + name={\csfmt{bib\-gls\-set\-other\-group\-title}}, + user1={\marg{\margm{character}\margm{id}\margm{type}}}, + description={sets the non-letter group title}, + topics={glossarystylecommands,assigncommands,groupcommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglsothergroup, + name={\csfmt{bib\-gls\-other\-group}}, + user1={\margm{character}\margm{id}\margm{type}}, + description={expands to the non-letter group label}, + topics={glossarystylecommands,groupcommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglsothergrouptitle, + name={\csfmt{bib\-gls\-other\-group\-title}}, + user1={\margm{character}\margm{id}\margm{type}}, + description={expands to the non-letter group title}, + topics={glossarystylecommands,groupcommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglssetemptygrouptitle, + name={\csfmt{bib\-gls\-set\-empty\-group\-title}}, + user1={\marg{\margm{type}}}, + description={sets the empty group title}, + topics={glossarystylecommands,assigncommands,groupcommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglsemptygroup, + name={\csfmt{bib\-gls\-empty\-group}}, + user1={\margm{type}}, + description={expands to the empty group label}, + topics={glossarystylecommands,groupcommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglsemptygrouptitle, + name={\csfmt{bib\-gls\-empty\-group\-title}}, + user1={\margm{type}}, + description={expands to the empty group title}, + topics={glossarystylecommands,groupcommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglssetunicodegrouptitle, + name={\csfmt{bib\-gls\-set\-unicode\-group\-title}}, + user1={\marg{\margm{label}\margm{character}\margm{id}\margm{type}}}, + description={sets the Unicode script, category or character code +title}, + topics={glossarystylecommands,assigncommands,groupcommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglsunicodegroup, + name={\csfmt{bib\-gls\-unicode\-group}}, + user1={\margm{label}\margm{character}\margm{id}\margm{type}}, + description={expands to the Unicode script or category label or +character code}, + note={\bibgls}, + topics={glossarystylecommands,groupcommands}, + category={command} +} + +@bibglscommand{bibglsunicodegrouptitle, + name={\csfmt{bib\-gls\-unicode\-group\-title}}, + user1={\margm{label}\margm{character}\margm{id}\margm{type}}, + description={expands to the Unicode script or category label or +character code}, + topics={glossarystylecommands,groupcommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglssetnumbergrouptitle, + name={\csfmt{bib\-gls\-set\-number\-group\-title}}, + user1={\marg{\margm{value}\margm{id}\margm{type}}}, + description={sets the number group title}, + topics={glossarystylecommands,assigncommands,groupcommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglsnumbergroup, + name={\csfmt{bib\-gls\-number\-group}}, + user1={\margm{value}\margm{id}\margm{type}}, + description={expands to the number group label}, + topics={glossarystylecommands,groupcommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglsnumbergrouptitle, + name={\csfmt{bib\-gls\-number\-group\-title}}, + user1={\margm{value}\margm{id}\margm{type}}, + description={expands to the number group title}, + topics={glossarystylecommands,groupcommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglssetdatetimegrouptitle, + name={\csfmt{bib\-gls\-set\-date\-time\-group\-title}}, + user1={\marg{\margm{YYYY}\margm{MM}\margm{DD}\margm{hh}\margm{mm}\margm{ss}\margm{zone}\margm{title}\margm{group\dhyphen id}\margm{type}}}, + description={sets the date-time group title}, + topics={glossarystylecommands,assigncommands,groupcommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglsdatetimegroup, + name={\csfmt{bib\-gls\-date\-time\-group}}, + user1={\margm{YYYY}\margm{MM}\margm{DD}\margm{hh}\margm{mm}\margm{ss}\margm{zone}\margm{title}\margm{group\dhyphen id}\margm{type}}, + description={expands to the date-time group label}, + topics={glossarystylecommands,groupcommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglsdatetimegrouptitle, + name={\csfmt{bib\-gls\-date\-time\-group\-title}}, + user1={\margm{YYYY}\margm{MM}\margm{DD}\margm{hh}\margm{mm}\margm{ss}\margm{zone}\margm{title}\margm{group\dhyphen id}\margm{type}}, + description={expands to the date-time group title}, + topics={glossarystylecommands,groupcommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglssetdategrouptitle, + name={\csfmt{bib\-gls\-set\-date\-group\-title}}, + user1={\marg{\margm{YYYY}\margm{MM}\margm{DD}\margm{G}\margm{title}\margm{group\dhyphen id}\margm{type}}}, + description={sets the date (no time) group title}, + topics={glossarystylecommands,assigncommands,groupcommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglsdategroup, + name={\csfmt{bib\-gls\-date\-group}}, + user1={\margm{YYYY}\margm{MM}\margm{DD}\margm{G}\margm{title}\margm{group\dhyphen id}\margm{type}}, + description={expands to the date group label}, + topics={glossarystylecommands,groupcommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglsdategrouptitle, + name={\csfmt{bib\-gls\-date\-group\-title}}, + user1={\margm{YYYY}\margm{MM}\margm{DD}\margm{G}\margm{title}\margm{group\dhyphen id}\margm{type}}, + description={expands to the date group title}, + topics={glossarystylecommands,groupcommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglssettimegrouptitle, + name={\csfmt{bib\-gls\-set\-time\-group\-title}}, + user1={\marg{\margm{hh}\margm{mm}\margm{ss}\margm{zone}\margm{title}\margm{group\dhyphen id}\margm{type}}}, + description={sets the time (no date) group title}, + topics={glossarystylecommands,assigncommands,groupcommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglstimegroup, + name={\csfmt{bib\-gls\-time\-group}}, + user1={\margm{hh}\margm{mm}\margm{ss}\margm{zone}\margm{title}\margm{group\dhyphen id}\margm{type}}, + description={expands to the time group label}, + topics={glossarystylecommands,groupcommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglstimegrouptitle, + name={\csfmt{bib\-gls\-time\-group\-title}}, + user1={\margm{hh}\margm{mm}\margm{ss}\margm{zone}\margm{title}\margm{group\dhyphen id}\margm{type}}, + description={expands to the time group title}, + topics={glossarystylecommands,groupcommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglshypergroup, + name={\csfmt{bib\-gls\-hyper\-group}}, + user1={\margm{type}\margm{group\dhyphen id}}, + description={creates group navigation information}, + topics={glossarystylecommands,groupcommands,linkcommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglsflattenedhomograph, + name={\csfmt{bib\-gls\-flattened\-homograph}}, + user1={\margm{name}\margm{parent label}}, + description={expands to the flattened entry's new name}, + topics={glossarystylecommands,formattingcommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglsflattenedchildpresort, + name={\csfmt{bib\-gls\-flattened\-child\-pre\-sort}}, + user1={\margm{child name}\margm{parent name}}, + description={expands to the pre-sort flattened child entry's new name}, + topics={glossarystylecommands,formattingcommands}, + note={\bibgls\texparserdefnote}, + category={command} +} + +@bibglscommand{bibglsflattenedchildpostsort, + name={\csfmt{bib\-gls\-flattened\-child\-post\-sort}}, + user1={\margm{parent name}\margm{child name}}, + description={expands to the post-sort flattened child entry's new +name}, + topics={glossarystylecommands,formattingcommands}, + note={\bibgls\texparserdefnote}, + category={command} +} + +@bibglscommand{bibglssetwidest, + name={\csfmt{bib\-gls\-set\-widest}}, + user1={\margm{level}\margm{name}}, + description={sets the widest name}, + topics={glossarystylecommands,assigncommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglssetwidestfortype, + name={\csfmt{bib\-gls\-set\-widest\-for\-type}}, + user1={\margm{type}\margm{level}\margm{name}}, + description={sets the widest name for the given glossary type}, + topics={glossarystylecommands,assigncommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglssetwidesttoplevelfallback, + name={\csfmt{bib\-gls\-set\-widest\-top\-level\-fallback}}, + user1={\margm{glossary list}}, + description={fallback used instead of \csref{bibglssetwidest} + in the event that \bibgls\ can't determine the widest name + where there are only top level entries, + where \meta{glossary list} is a comma-separated list + of glossary labels}, + topics={glossarystylecommands,assigncommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglssetwidestfallback, + name={\csfmt{bib\-gls\-set\-widest\-fallback}}, + user1={\margm{glossary list}}, + description={fallback used instead of \csref{bibglssetwidest} + in the event that \bibgls\ can't determine the widest name, + where \meta{glossary list} is a comma-separated list + of glossary labels}, + topics={glossarystylecommands,assigncommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglssetwidestfortypefallback, + name={\csfmt{bib\-gls\-set\-widest\-for\-type\-fallback}}, + user1={\margm{type}}, + description={fallback used instead of \csref{bibglssetwidestfortype} + in the event that \bibgls\ can't determine the widest name}, + topics={glossarystylecommands,assigncommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglssetwidesttoplevelfortypefallback, + name={\csfmt{bib\-gls\-set\-widest\-top\-level\-for\-type\-fallback}}, + user1={\margm{type}}, + description={fallback used instead of \csref{bibglssetwidestfortype} + in the event that \bibgls\ can't determine the widest name + where there are only top-level entries}, + topics={glossarystylecommands,assigncommands}, + note={\bibgls}, + category={command} +} + + +@bibglscommand{bibglscontributorlist, + name={\csfmt{bib\-gls\-contributor\-list}}, + user1={\margm{list}\margm{number}}, + description={used to markup a list of names from a field + that was converted from \BibTeX's contributor syntax}, + topics={formattingcommands}, + note={\bibgls\texparserdefnote}, + category={command} +} + +@bibglscommand{bibglscontributor, + name={\csfmt{bib\-gls\-contributor}}, + user1={\margm{forenames}\margm{von-part}\margm{surname}\margm{suffix}}, + description={used to markup a contributor's name that was converted from + \BibTeX's contributor syntax}, + topics={formattingcommands}, + note={\bibgls\texparserdefnote}, + category={command} +} + +@bibglscommand{bibglsdate, + name={\csfmt{bib\-gls\-date}}, + user1={\margm{year}\margm{month}\margm{day-of-month}\margm{day-of-week}\margm{day-of-year}\margm{era}\margm{original}}, + description={used to markup a date converted from a field value}, + topics={formattingcommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglsdatetime, + name={\csfmt{bib\-gls\-date\-time}}, + user1={\margm{year}\margm{month}\margm{day-of-month}\margm{day-of-week}\margm{day-of-year}\margm{era}\margm{hour}\margm{minute}\margm{second}\margm{millisec}\margm{dst}\margm{zone}\margm{original}}, + description={used to markup a date-time instance converted from a field value}, + topics={formattingcommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglsdatetimeremainder, + name={\csfmt{bib\-gls\-date\-time\-remainder}}, + user1={\margm{millisec}\margm{dst}\margm{zone}\margm{original}}, + description={used internally to pick up the final four arguments of + \csref{bibglsdatetime}}, + topics={formattingcommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglstime, + name={\csfmt{bib\-gls\-time}}, + user1={\margm{hour}\margm{minute}\margm{second}\margm{millisec}\margm{dst}\margm{zone}\margm{original}}, + description={used to markup a time converted from a field value}, + topics={formattingcommands}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglshashchar, + name={\csfmt{bib\-gls\-hash\-char}}, + user1={}, + description={expands to a literal hash character}, + topics={charcommands}, + note={\bibgls\texparserdefnote}, + category={command} +} + +@bibglscommand{bibglsunderscorechar, + name={\csfmt{bib\-gls\-under\-score\-char}}, + user1={}, + description={expands to a literal underscore character}, + topics={charcommands}, + note={\bibgls\texparserdefnote}, + category={command} +} + +@bibglscommand{bibglsdollarchar, + name={\csfmt{bib\-gls\-dollar\-char}}, + user1={}, + description={expands to a literal dollar character}, + topics={charcommands}, + note={\bibgls\texparserdefnote}, + category={command} +} + +@bibglscommand{bibglsampersandchar, + name={\csfmt{bib\-gls\-amper\-sand\-char}}, + user1={}, + description={expands to a literal ampersand character}, + topics={charcommands}, + note={\bibgls\texparserdefnote}, + category={command} +} + +@bibglscommand{bibglscircumchar, + name={\csfmt{bib\-gls\-circum\-char}}, + user1={}, + description={expands to a literal circumflex character}, + topics={charcommands}, + note={\bibgls\texparserdefnote}, + category={command} +} + +@bibglscommand{bibglshrefchar, + name={\csfmt{bib\-gls\-href\-char}}, + user1={\margm{hex}\margm{char}}, + description={expands to a literal percent character followed by +\meta{hex}}, + topics={charcommands}, + note={\bibgls\texparserdefnote}, + category={command} +} + +@bibglscommand{bibglshrefunicode, + name={\csfmt{bib\-gls\-href\-unicode}}, + user1={\margm{hex}\margm{char}}, + description={expands to \meta{char} by default}, + topics={charcommands}, + note={\bibgls\texparserdefnote}, + category={command} +} + +@bibglscommand{bibglsprimaryprefixlabel, + name={\csfmt{bib\-gls\-primary\-prefix\-label}}, + user1={\margm{prefix}}, + description={hook provided to pick up the primary prefix, if + required}, + topics={hooks}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglsdualprefixlabel, + name={\csfmt{bib\-gls\-dual\-prefix\-label}}, + user1={\margm{prefix}}, + description={hook provided to pick up the dual prefix, if + required}, + topics={hooks}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglstertiaryprefixlabel, + name={\csfmt{bib\-gls\-tertiary\-prefix\-label}}, + user1={\margm{prefix}}, + description={hook provided to pick up the tertiary prefix, if + required}, + topics={hooks}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglsexternalprefixlabel, + name={\csfmt{bib\-gls\-external\-prefix\-label}}, + user1={\margm{n}\margm{prefix}}, + description={hook provided to pick up the \meta{n}th external prefix, if + required}, + topics={hooks}, + note={\bibgls}, + category={command} +} + +@bibglscommand{bibglsuppercase, + name={\csfmt{bib\-gls\-upper\-case}}, + user1={\margm{text}}, + description={converts \meta{text} to \idx{uppercase}}, + topics={formattingcommands,casecommands}, + note={\bibgls\texparserdefnote}, + category={command} +} + +@bibglscommand{bibglslowercase, + name={\csfmt{bib\-gls\-lower\-case}}, + user1={\margm{text}}, + description={converts \meta{text} to \idx{lowercase}}, + topics={formattingcommands,casecommands}, + note={\bibgls\texparserdefnote}, + category={command} +} + +@bibglscommand{bibglstitlecase, + name={\csfmt{bib\-gls\-title\-case}}, + user1={\margm{text}}, + description={converts \meta{text} to \idx{titlecase}}, + topics={formattingcommands,casecommands}, + note={\bibgls\texparserdefnote}, + category={command} +} + +@bibglscommand{bibglsfirstuc, + name={\csfmt{bib\-gls\-first\-uc}}, + user1={\margm{text}}, + description={converts the first letter of \meta{text} to \idx{uppercase}}, + topics={formattingcommands,casecommands}, + note={\bibgls}, + category={command} +} + +@mainglscommand{glsexpandfields, + name={\csfmt{gls\-expand\-fields}}, + user1={}, + description={switches on field expansion}, + topics={assigncommands,definingterms}, + note={\styfmt{glossaries}}, + category={command} +} + +@mainglscommand{glsnoexpandfields, + name={\csfmt{gls\-no\-expand\-fields}}, + user1={}, + description={switches off field expansion}, + topics={assigncommands,definingterms}, + note={\styfmt{glossaries}}, + category={command} +} + +@mainglscommand{glssetexpandfield, + name={\csfmt{gls\-set\-expand\-field}}, + user1={\margm{field}}, + description={switches on field expansion for the given field}, + topics={assigncommands,definingterms}, + note={\styfmt{glossaries}}, + category={command} +} + +@mainglscommand{glssetnoexpandfield, + name={\csfmt{gls\-set\-no\-expand\-field}}, + user1={\margm{field}}, + description={switches off field expansion for the given field}, + topics={assigncommands,definingterms}, + note={\styfmt{glossaries}}, + category={command} +} + +@mainglscommand{newglossaryentry, + name={\csfmt{new\-glossary\-entry}}, + user1={\margm{label}\margm{\keyvallist}}, + description={defines a new glossary entry}, + topics={definingterms}, + note={\styfmt{glossaries}}, + category={command} +} + +@mainglscommand{longnewglossaryentry, + name={\csfmt{long\-new\-glossary\-entry}}, + user1={\margm{label}\margm{\keyvallist}\margm{description}}, + description={defines a new glossary entry and appends + \csfmt{leavemode}\csfmt{unskip}\cs{nopostdesc} at the end of +\meta{description}}, + topics={definingterms}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{longnewglossaryentry*, + name={\csfmt{long\-new\-glossary\-entry*}}, + user1={\margm{label}\margm{\keyvallist}\margm{description}}, + description={defines a new glossary entry without appending any +extra code to the end of \meta{description}}, + topics={definingterms}, + note={\styfmt{glossaries-extra} v1.12+}, + category={command} +} + +@mainglscommand{provideglossaryentry, + name={\csfmt{provide\-glossary\-entry}}, + user1={\margm{label}\margm{\keyvallist}}, + description={defines a new glossary entry if one doesn't + already exist with the given label}, + topics={definingterms}, + note={\styfmt{glossaries}}, + category={command} +} + +@mainglscommand{longprovideglossaryentry, + name={\csfmt{long\-provide\-glossary\-entry}}, + user1={\margm{label}\margm{\keyvallist}\margm{description}}, + description={defines a new glossary entry if one doesn't + already exist with the given label}, + topics={definingterms}, + note={\styfmt{glossaries}}, + category={command} +} + +@mainglscommand{newterm, + name={\csfmt{new\-term}}, + user1={\oargm{\keyvallist}\margm{label}}, + description={defines a new glossary entry where the + \field{description} field defaults to empty}, + topics={definingterms}, + note={\styfmt{glossaries}'s \styopt{index} package option}, + category={command} +} + +@mainglscommand{newabbreviation, + name={\csfmt{new\-abbre\-vi\-a\-tion}}, + user1={\oargm{\keyvallist}\margm{label}\margm{short}\margm{long}}, + description={defines a new abbreviation}, + topics={definingterms}, + note={\styfmt{glossaries-extra}}, + category={command} +} + +@mainglscommand{newacronym, + name={\csfmt{new\-acronym}}, + user1={\oargm{\keyvallist}\margm{label}\margm{short}\margm{long}}, + description={defines a new abbreviation. The + \styfmt{glossaries-extra} package redefines this to use + \csref{newabbreviation} with the \field{category} set to + \code{acronym}}, + topics={definingterms}, + note={\styfmt{glossaries}}, + category={command} +} + +@mainglscommand{glsxtrnewsymbol, + name={\csfmt{gls\-xtr\-new\-symbol}}, + user1={\oargm{\keyvallist}\margm{label}\margm{symbol}}, + description={defines a new symbol}, + topics={definingterms}, + note={\styfmt{glossaries-extra} \styopt{symbols}}, + category={command} +} + +@mainglscommand{glsxtrnewnumber, + name={\csfmt{gls\-xtr\-new\-number}}, + user1={\oargm{\keyvallist}\margm{label}}, + description={defines a new number}, + topics={definingterms}, + note={\styfmt{glossaries-extra} \styopt{numbers}}, + category={command} +} + +@mainglscommand{newdualentry, + name={\csfmt{new\-dual\-entry}}, + user1={\oargm{\keyvallist}\margm{label}\margm{short}\margm{long}\margm{description}}, + description={example given in \styfmt{glossaries} user manual}, + topics={definingterms}, + category={command} +} + +@mainglscommand{@gls@hypergroup, + name={\csfmt{@gls@hypergroup}}, + user1={\margm{type}\margm{group id}}, + description={command written to the \ext{aux} file that identifies that the given group was used in the + glossary on the previous run}, + topics={groupcommands,internalcommands,auxcommands}, + note={\styfmt{glossary-hypernav}}, + category={command} +} + +@mainglscommand{glsxtr@resource, + name={\csfmt{glsxtr@resource}}, + user1={\margm{options}\margm{filename}}, + description={this internal command is written to the \ext{aux} +file by \csref{glsxtrresourcefile} + to provide \bibgls\ with the resource information}, + topics={internalcommands,auxcommands}, + note={\styfmt{glossaries-extra} v1.08+}, + category={command} +} + +@mainglscommand{glsxtr@wrglossarylocation, + name={\csfmt{gls\-xtr\-@wr\-glossary\-location}}, + user1={\margm{n}\margm{page}}, + description={This command simply expands to \meta{n}, the value of +the \counter{wrglossary} counter for the given page}, + topics={internalcommands,loclistcommands}, + note={\styfmt{glossaries-extra-bib2gls} v1.29+}, + category={command} +} + +@mainglscommand{GlsXtrIndexCounterLink, + name={\csfmt{Gls\-Xtr\-Index\-Counter\-Link}}, + user1={\margm{text}\margm{label}}, + description={Creates a hyperlink to the \counter{wrglossary} +location obtained from the \field{indexcounter} field}, + topics={linkcommands,loclistcommands}, + note={\styfmt{glossaries-extra-bib2gls} v1.29+}, + category={command} +} + +@mainglscommand{GlsXtrDualBackLink, + name={\csfmt{Gls\-Xtr\-Dual\-Back\-Link}}, + user1={\margm{text}\margm{label}}, + description={Creates a hyperlink to the dual entry whose label is + obtained from the field given by \csref{GlsXtrDualField}}, + topics={linkcommands,fieldrefcommands}, + note={\styfmt{glossaries-extra-bib2gls} v1.30+}, + category={command} +} + +@mainglscommand{GlsXtrDualField, + name={\csfmt{Gls\-Xtr\-Dual\-Field}}, + user1={}, + description={The field used to store the dual label. This defaults + to \field{dual} but will need to be redefined if a different + value is given by \csopt{dual-field}}, + topics={fieldrefcommands}, + note={\styfmt{glossaries-extra-bib2gls} v1.30+}, + category={command} +} + +@mainglscommand{glsxtrfmt, + name={\csfmt{gls\-xtr\-fmt}}, + user1={\oargm{options}\margm{label}\margm{text}}, + description={formats the given text according to the formatting + command identified by the value of the field obtained + from \cs{GlsXtrFmtField}}, + topics={fieldrefcommands,linkcommands,formattingcommands}, + note={\styfmt{glossaries-extra} v1.12+}, + seealso={glsxtrfmtdisplay}, + category={command} +} + +@mainglscommand{glsxtrfmt*, + name={\csfmt{gls\-xtr\-fmt*}}, + user1={\oargm{options}\margm{label}\margm{text}\oargm{insert}}, + description={like \csref{glsxtrfmt} but inserts extra + material into the link text but outside of the formatting command}, + topics={fieldrefcommands,linkcommands,formattingcommands}, + seealso={glsxtrfmtdisplay}, + note={\styfmt{glossaries-extra} v1.23+}, + category={command} +} + +@mainglscommand{glsxtrentryfmt, + name={\csfmt{gls\-xtr\-entry\-fmt}}, + user1={\margm{label}\margm{text}}, + description={alternative to \csref{glsxtrfmt} for use in + section headings}, + topics={fieldrefcommands,formattingcommands}, + note={\styfmt{glossaries-extra} v1.12+}, + category={command} +} + +@glscommand{glsxtrfmtdisplay, + name={\csfmt{gls\-xtr\-fmt\-display}}, + user1={\margm{cs-name}\margm{text}\margm{insert}}, + description={used by \csref{glsxtrfmt} to format the given +\meta{text} where \meta{cs-name} is obtained from the field +identified by \cs{GlsXtrFmtField} and \meta{insert} is empty for the +unstarred \csref{glsxtrfmt} and the final optional argument of the +starred version \csref{glsxtrfmt*}}, + topics={formattingcommands}, + note={\styfmt{glossaries-extra}}, + category={command} +} + +@mainglscommand{glsxtrresourcefile, + name={\csfmt{gls\-xtr\-resource\-file}}, + user1={\oargm{options}\margm{filename}}, + description={input the \ext{glstex} file created by \bibgls\ and + write resource instructions to the \ext{aux} file}, + topics={indexing}, + note={\styfmt{glossaries-extra} v1.08+}, + seealso={resourceoptions,GlsXtrLoadResources}, + category={command} +} + + +@index{resourceoptions, + name={resource options}, + text={resource option} +} + +@resourceoption{opt.charset, + name={\csoptfmt{charset}}, + user1={\meta{encoding-name}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.interpret-preamble, + name={\csoptfmt{interpret\dhyphen preamble}}, + user1={\meta{boolean}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.interpret-label-fields, + name={\csoptfmt{interpret\dhyphen label\dhyphen fields}}, + user1={\meta{boolean}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.primary-dual-dependency, + name={\csoptfmt{primary\dhyphen dual\dhyphen dependency}}, + user1={\meta{boolean}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.strip-missing-parents, + name={\csoptfmt{strip\dhyphen missing\dhyphen parents}}, + user1={\meta{boolean}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.missing-parents, + name={\csoptfmt{missing\dhyphen parents}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.missing-parent-category, + name={\csoptfmt{missing\dhyphen parent\dhyphen category}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.copy-alias-to-see, + name={\csoptfmt{copy\dhyphen alias\dhyphen to\dhyphen see}}, + user1={\meta{boolean}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.write-preamble, + name={\csoptfmt{write\dhyphen preamble}}, + user1={\meta{boolean}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.set-widest, + name={\csoptfmt{set\dhyphen widest}}, + user1={\meta{boolean}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.duplicate-label-suffix, + name={\csoptfmt{duplicate\dhyphen label\dhyphen suffix}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.entry-type-aliases, + name={\csoptfmt{entry\dhyphen type\dhyphen aliases}}, + user1={\meta{\keyvallist}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.unknown-entry-alias, + name={\csoptfmt{unknown\dhyphen entry\dhyphen alias}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.field-aliases, + name={\csoptfmt{field\dhyphen aliases}}, + user1={\meta{\keyvallist}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.replicate-fields, + name={\csoptfmt{replicate\dhyphen fields}}, + user1={\meta{\keyvallist}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.replicate-override, + name={\csoptfmt{replicate\dhyphen override}}, + user1={\margm{boolean}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.replicate-missing-field-action, + name={\csoptfmt{replicate\dhyphen missing\dhyphen field\dhyphen action}}, + user1={\margm{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.labelify, + name={\csoptfmt{labelify}}, + user1={\meta{list}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.labelify-list, + name={\csoptfmt{labelify\dhyphen list}}, + user1={\meta{list}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dependency-fields, + name={\csoptfmt{dependency\dhyphen fields}}, + user1={\meta{list}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.labelify-replace, + name={\csoptfmt{labelify\dhyphen replace}}, + user1={\meta{list}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.sort-replace, + name={\csoptfmt{sort\dhyphen replace}}, + user1={\meta{list}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-sort-replace, + name={\csoptfmt{dual\dhyphen sort\dhyphen replace}}, + user1={\meta{list}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.secondary-sort-replace, + name={\csoptfmt{secondary\dhyphen sort\dhyphen replace}}, + user1={\meta{list}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.action, + name={\csoptfmt{action}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.copy-action-group-field, + name={\csoptfmt{copy\dhyphen action\dhyphen group\dhyphen field}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.src, + name={\csoptfmt{src}}, + user1={\meta{list}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.selection, + name={\csoptfmt{selection}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.match, + name={\csoptfmt{match}}, + user1={\meta{\keyvallist}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.match-op, + name={\csoptfmt{match\dhyphen op}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.match-action, + name={\csoptfmt{match\dhyphen action}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.not-match, + name={\csoptfmt{not\dhyphen match}}, + user1={\meta{\keyvallist}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.limit, + name={\csoptfmt{limit}}, + user1={\meta{number}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.flatten, + name={\csoptfmt{flatten}}, + user1={\meta{boolean}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.flatten-lonely, + name={\csoptfmt{flatten\dhyphen lonely}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.flatten-lonely-rule, + name={\csoptfmt{flatten\dhyphen lonely\dhyphen rule}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.master, + name={\csoptfmt{master}}, + user1={\meta{name}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.master-resources, + name={\csoptfmt{master\dhyphen resources}}, + user1={\meta{list}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.ignore-fields, + name={\csoptfmt{ignore\dhyphen fields}}, + user1={\meta{list}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.date-time-fields, + name={\csoptfmt{date\dhyphen time\dhyphen fields}}, + user1={\meta{list}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.date-fields, + name={\csoptfmt{date\dhyphen fields}}, + user1={\meta{list}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.time-fields, + name={\csoptfmt{time\dhyphen fields}}, + user1={\meta{list}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.date-time-field-format, + name={\csoptfmt{date\dhyphen time\dhyphen field\dhyphen format}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-date-time-field-format, + name={\csoptfmt{dual\dhyphen date\dhyphen time\dhyphen field\dhyphen format}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.date-field-format, + name={\csoptfmt{date\dhyphen field\dhyphen format}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-date-field-format, + name={\csoptfmt{dual\dhyphen date\dhyphen field\dhyphen format}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.time-field-format, + name={\csoptfmt{time\dhyphen field\dhyphen format}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-time-field-format, + name={\csoptfmt{dual\dhyphen time\dhyphen field\dhyphen format}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.date-time-field-locale, + name={\csoptfmt{date\dhyphen time\dhyphen field\dhyphen locale}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-date-time-field-locale, + name={\csoptfmt{dual\dhyphen date\dhyphen time\dhyphen +field\dhyphen locale}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.date-field-locale, + name={\csoptfmt{date\dhyphen field\dhyphen locale}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-date-field-locale, + name={\csoptfmt{dual\dhyphen date\dhyphen field\dhyphen locale}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.time-field-locale, + name={\csoptfmt{time\dhyphen field\dhyphen locale}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-time-field-locale, + name={\csoptfmt{date\dhyphen time\dhyphen field\dhyphen locale}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.bibtex-contributor-fields, + name={\csoptfmt{bibtex\dhyphen contributor\dhyphen fields}}, + user1={\meta{list}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.contributor-order, + name={\csoptfmt{contributor\dhyphen order}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.category, + name={\csoptfmt{category}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.type, + name={\csoptfmt{type}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.counter, + name={\csoptfmt{counter}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.label-prefix, + name={\csoptfmt{label\dhyphen prefix}}, + user1={\meta{tag}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.cs-label-prefix, + name={\csoptfmt{cs\dhyphen label\dhyphen prefix}}, + user1={\meta{tag}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.record-label-prefix, + name={\csoptfmt{record\dhyphen label\dhyphen prefix}}, + user1={\meta{tag}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.ext-prefixes, + name={\csoptfmt{ext\dhyphen prefixes}}, + user1={\meta{list}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.save-original-id, + name={\csoptfmt{save\dhyphen original\dhyphen id}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.short-case-change, + name={\csoptfmt{short\dhyphen case\dhyphen change}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.long-case-change, + name={\csoptfmt{long\dhyphen case\dhyphen change}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.name-case-change, + name={\csoptfmt{name\dhyphen case\dhyphen change}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.description-case-change, + name={\csoptfmt{description\dhyphen case\dhyphen change}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.field-case-change, + name={\csoptfmt{field\dhyphen case\dhyphen change}}, + user1={\margm{\keyvallist}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.word-boundaries, + name={\csoptfmt{word\dhyphen boundaries}}, + user1={\meta{list}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.no-case-change-cs, + name={\csoptfmt{no\dhyphen case\dhyphen change\dhyphen cs}}, + user1={\meta{list}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.encapsulate-fields, + name={\csoptfmt{encapsulate\dhyphen fields}}, + user1={\margm{\keyvallist}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.encapsulate-fields*, + name={\csoptfmt{encapsulate\dhyphen fields*}}, + user1={\margm{\keyvallist}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.interpret-fields, + name={\csoptfmt{interpret\dhyphen fields}}, + user1={\margm{list}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.post-description-dot, + name={\csoptfmt{post\dhyphen description\dhyphen dot}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.strip-trailing-nopost, + name={\csoptfmt{strip\dhyphen trailing\dhyphen nopost}}, + user1={\meta{boolean}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.check-end-punctuation, + name={\csoptfmt{check\dhyphen end\dhyphen punctuation}}, + user1={\meta{list}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.sort-label-list, + name={\csoptfmt{sort\dhyphen label\dhyphen list}}, + user1={\meta{list}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.group, + name={\csoptfmt{group}}, + user1={\meta{label}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.group-formation, + name={\csoptfmt{group\dhyphen formation}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.secondary-group-formation, + name={\csoptfmt{secondary\dhyphen group\dhyphen formation}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-group-formation, + name={\csoptfmt{dual\dhyphen group\dhyphen formation}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.save-child-count, + name={\csoptfmt{save\dhyphen child\dhyphen count}}, + user1={\meta{boolean}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.save-original-entrytype, + name={\csoptfmt{save\dhyphen original\dhyphen entrytype}}, + user1={\meta{boolean}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.short-plural-suffix, + name={\csoptfmt{short\dhyphen plural\dhyphen suffix}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-short-plural-suffix, + name={\csoptfmt{dual\dhyphen short\dhyphen plural\dhyphen suffix}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.save-locations, + name={\csoptfmt{save\dhyphen locations}}, + user1={\meta{boolean}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.save-loclist, + name={\csoptfmt{save\dhyphen loclist}}, + user1={\meta{boolean}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.save-primary-locations, + name={\csoptfmt{save\dhyphen primary\dhyphen locations}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.primary-location-formats, + name={\csoptfmt{primary\dhyphen location\dhyphen formats}}, + user1={\meta{list}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.min-loc-range, + name={\csoptfmt{min\dhyphen loc\dhyphen range}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.max-loc-diff, + name={\csoptfmt{max\dhyphen loc\dhyphen diff}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.suffixF, + name={\csoptfmt{suffixF}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.suffixFF, + name={\csoptfmt{suffixFF}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.compact-ranges, + name={\csoptfmt{compact-ranges}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.see, + name={\csoptfmt{see}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.seealso, + name={\csoptfmt{seealso}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.alias, + name={\csoptfmt{alias}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.alias-loc, + name={\csoptfmt{alias\dhyphen loc}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.loc-prefix, + name={\csoptfmt{loc\dhyphen prefix}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.loc-suffix, + name={\csoptfmt{loc\dhyphen suffix}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.loc-counters, + name={\csoptfmt{loc\dhyphen counters}}, + user1={\meta{list}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.save-index-counter, + name={\csoptfmt{save\dhyphen index\dhyphen counter}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.supplemental-locations, + name={\csoptfmt{supplemental\dhyphen locations}}, + user1={\meta{basename}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.supplemental-selection, + name={\csoptfmt{supplemental\dhyphen selection}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.supplemental-category, + name={\csoptfmt{supplemental\dhyphen category}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.sort, + name={\csoptfmt{sort}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.shuffle, + name={\csoptfmt{shuffle}}, + user1={\meta{seed}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.sort-field, + name={\csoptfmt{sort\dhyphen field}}, + user1={\meta{field}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.entry-sort-fallback, + name={\csoptfmt{entry\dhyphen sort\dhyphen fallback}}, + user1={\meta{field}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.symbol-sort-fallback, + name={\csoptfmt{symbol\dhyphen sort\dhyphen fallback}}, + user1={\meta{field}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.abbreviation-sort-fallback, + name={\csoptfmt{abbreviation\dhyphen sort\dhyphen fallback}}, + user1={\meta{field}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.abbreviation-name-fallback, + name={\csoptfmt{abbreviation\dhyphen name\dhyphen fallback}}, + user1={\meta{field}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.bibtexentry-sort-fallback, + name={\csoptfmt{bibtexentry\dhyphen sort\dhyphen fallback}}, + user1={\meta{field}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.trim-sort, + name={\csoptfmt{trim\dhyphen sort}}, + user1={\meta{boolean}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.missing-sort-fallback, + name={\csoptfmt{missing\dhyphen sort\dhyphen fallback}}, + user1={\meta{field}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-missing-sort-fallback, + name={\csoptfmt{dual\dhyphen missing\dhyphen sort\dhyphen fallback}}, + user1={\meta{field}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.secondary-missing-sort-fallback, + name={\csoptfmt{secondary\dhyphen missing\dhyphen sort\dhyphen fallback}}, + user1={\meta{field}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.sort-rule, + name={\csoptfmt{sort\dhyphen rule}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.break-at, + name={\csoptfmt{break\dhyphen at}}, + user1={\meta{option}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.break-marker, + name={\csoptfmt{break\dhyphen marker}}, + user1={\meta{marker}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.identical-sort-action, + name={\csoptfmt{identical\dhyphen sort\dhyphen action}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-identical-sort-action, + name={\csoptfmt{dual\dhyphen identical\dhyphen sort\dhyphen action}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.secondary-identical-sort-action, + name={\csoptfmt{secondary\dhyphen identical\dhyphen sort\dhyphen action}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.sort-suffix, + name={\csoptfmt{sort\dhyphen suffix}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.sort-suffix-marker, + name={\csoptfmt{sort\dhyphen suffix\dhyphen marker}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.strength, + name={\csoptfmt{strength}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.decomposition, + name={\csoptfmt{decomposition}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.letter-number-rule, + name={\csoptfmt{letter\dhyphen number\dhyphen rule}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.letter-number-punc-rule, + name={\csoptfmt{letter\dhyphen number\dhyphen punc\dhyphen rule}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.numeric-sort-pattern, + name={\csoptfmt{numeric\dhyphen sort\dhyphen pattern}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.numeric-locale, + name={\csoptfmt{numeric\dhyphen locale}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.date-sort-locale, + name={\csoptfmt{date\dhyphen sort\dhyphen locale}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.date-sort-format, + name={\csoptfmt{date\dhyphen sort\dhyphen format}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.trigger-type, + name={\csoptfmt{trigger\dhyphen type}}, + user1={\meta{type}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.progenitor-type, + name={\csoptfmt{progenitor\dhyphen type}}, + user1={\meta{type}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.progeny-type, + name={\csoptfmt{progeny\dhyphen type}}, + user1={\meta{type}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.adopted-parent-field, + name={\csoptfmt{adopted\dhyphen parent\dhyphen field}}, + user1={\meta{type}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.secondary, + name={\csoptfmt{secondary}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.secondary-trim-sort, + name={\csoptfmt{secondary\dhyphen trim\dhyphen sort}}, + user1={\meta{boolean}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.secondary-sort-rule, + name={\csoptfmt{secondary\dhyphen sort\dhyphen rule}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.secondary-break-at, + name={\csoptfmt{secondary\dhyphen break\dhyphen at}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.secondary-break-marker, + name={\csoptfmt{secondary\dhyphen break\dhyphen marker}}, + user1={\meta{marker}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.secondary-sort-suffix, + name={\csoptfmt{secondary\dhyphen sort\dhyphen suffix}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.secondary-sort-suffix-marker, + name={\csoptfmt{secondary\dhyphen sort\dhyphen suffix\dhyphen +marker}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.secondary-strength, + name={\csoptfmt{secondary\dhyphen strength}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.secondary-decomposition, + name={\csoptfmt{secondary\dhyphen decomposition}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.secondary-letter-number-rule, + name={\csoptfmt{secondary\dhyphen letter\dhyphen number\dhyphen +rule}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.secondary-letter-number-punc-rule, + name={\csoptfmt{secondary\dhyphen letter\dhyphen number\dhyphen +punc\dhyphen rule}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.secondary-numeric-sort-pattern, + name={\csoptfmt{secondary\dhyphen numeric\dhyphen sort\dhyphen +pattern}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.secondary-numeric-locale, + name={\csoptfmt{secondary\dhyphen numeric\dhyphen locale}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.secondary-date-sort-locale, + name={\csoptfmt{secondary\dhyphen date\dhyphen sort\dhyphen +locale}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.secondary-date-sort-format, + name={\csoptfmt{secondary\dhyphen date\dhyphen sort\dhyphen +format}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-prefix, + name={\csoptfmt{dual\dhyphen prefix}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.combine-dual-locations, + name={\csoptfmt{combine\dhyphen dual\dhyphen locations}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-type, + name={\csoptfmt{dual\dhyphen type}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-category, + name={\csoptfmt{dual\dhyphen category}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-counter, + name={\csoptfmt{dual\dhyphen counter}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-short-case-change, + name={\csoptfmt{dual\dhyphen short\dhyphen case\dhyphen change}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-long-case-change, + name={\csoptfmt{dual\dhyphen long\dhyphen case\dhyphen change}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-field, + name={\csoptfmt{dual\dhyphen field}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-sort, + name={\csoptfmt{dual\dhyphen sort}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-sort-field, + name={\csoptfmt{dual\dhyphen sort\dhyphen field}}, + user1={\meta{field}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-trim-sort, + name={\csoptfmt{dual\dhyphen trim\dhyphen sort}}, + user1={\meta{boolean}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-sort-rule, + name={\csoptfmt{dual\dhyphen sort\dhyphen rule}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-break-at, + name={\csoptfmt{dual\dhyphen break\dhyphen at}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-break-marker, + name={\csoptfmt{dual\dhyphen break\dhyphen marker}}, + user1={\meta{marker}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-sort-suffix, + name={\csoptfmt{dual\dhyphen sort\dhyphen suffix}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-sort-suffix-marker, + name={\csoptfmt{dual\dhyphen sort\dhyphen suffix\dhyphen marker}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-strength, + name={\csoptfmt{dual\dhyphen strength}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-decomposition, + name={\csoptfmt{dual\dhyphen decomposition}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-letter-number-rule, + name={\csoptfmt{dual\dhyphen letter\dhyphen number\dhyphen rule}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-letter-number-punc-rule, + name={\csoptfmt{dual\dhyphen letter\dhyphen number\dhyphen punc\dhyphen rule}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-numeric-sort-pattern, + name={\csoptfmt{dual\dhyphen numeric\dhyphen sort\dhyphen +pattern}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-numeric-locale, + name={\csoptfmt{dual\dhyphen numeric\dhyphen locale}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-date-sort-locale, + name={\csoptfmt{dual\dhyphen date\dhyphen sort\dhyphen locale}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-date-sort-format, + name={\csoptfmt{dual\dhyphen date\dhyphen sort\dhyphen format}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-entry-map, + name={\csoptfmt{dual\dhyphen entry\dhyphen map}}, + user1={\marg{\margm{list1},\margm{list2}}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-abbrv-map, + name={\csoptfmt{dual\dhyphen abbrv\dhyphen map}}, + user1={\marg{\margm{list1},\margm{list2}}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-abbrventry-map, + name={\csoptfmt{dual\dhyphen abbrventry\dhyphen map}}, + user1={\marg{\margm{list1},\margm{list2}}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-symbol-map, + name={\csoptfmt{dual\dhyphen symbol\dhyphen map}}, + user1={\marg{\margm{list1},\margm{list2}}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-indexentry-map, + name={\csoptfmt{dual\dhyphen indexentry\dhyphen map}}, + user1={\marg{\margm{list1},\margm{list2}}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-indexsymbol-map, + name={\csoptfmt{dual\dhyphen indexsymbol\dhyphen map}}, + user1={\marg{\margm{list1},\margm{list2}}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-indexabbrv-map, + name={\csoptfmt{dual\dhyphen indexabbrv\dhyphen map}}, + user1={\marg{\margm{list1},\margm{list2}}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-entry-backlink, + name={\csoptfmt{dual\dhyphen entry\dhyphen backlink}}, + user1={\margm{boolean}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-abbrv-backlink, + name={\csoptfmt{dual\dhyphen abbrv\dhyphen backlink}}, + user1={\margm{boolean}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-entryabbrv-backlink, + name={\csoptfmt{dual\dhyphen entryabbrv\dhyphen backlink}}, + user1={\margm{boolean}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-abbrventry-backlink, + name={\csoptfmt{dual\dhyphen abbrventry\dhyphen backlink}}, + user1={\margm{boolean}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-symbol-backlink, + name={\csoptfmt{dual\dhyphen symbol\dhyphen backlink}}, + user1={\margm{boolean}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-indexentry-backlink, + name={\csoptfmt{dual\dhyphen indexentry\dhyphen backlink}}, + user1={\margm{boolean}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-indexsymbol-backlink, + name={\csoptfmt{dual\dhyphen indexsymbol\dhyphen backlink}}, + user1={\margm{boolean}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-indexabbrv-backlink, + name={\csoptfmt{dual\dhyphen indexabbrv\dhyphen backlink}}, + user1={\margm{boolean}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-backlink, + name={\csoptfmt{dual\dhyphen backlink}}, + user1={\margm{boolean}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.tertiary-prefix, + name={\csoptfmt{tertiary\dhyphen prefix}}, + user1={\margm{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.tertiary-type, + name={\csoptfmt{tertiary\dhyphen type}}, + user1={\margm{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.tertiary-category, + name={\csoptfmt{tertiary\dhyphen category}}, + user1={\margm{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.sort-number-pad, + name={\csoptfmt{sort\dhyphen number\dhyphen pad}}, + user1={\meta{number}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-sort-number-pad, + name={\csoptfmt{dual\dhyphen sort\dhyphen number\dhyphen pad}}, + user1={\meta{number}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.secondary-sort-number-pad, + name={\csoptfmt{secondary\dhyphen sort\dhyphen number\dhyphen pad}}, + user1={\meta{number}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.sort-pad-plus, + name={\csoptfmt{sort\dhyphen pad\dhyphen plus}}, + user1={\meta{marker}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-sort-pad-plus, + name={\csoptfmt{dual\dhyphen sort\dhyphen pad\dhyphen plus}}, + user1={\meta{marker}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.secondary-sort-pad-plus, + name={\csoptfmt{secondary\dhyphen sort\dhyphen pad\dhyphen plus}}, + user1={\meta{marker}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.sort-pad-minus, + name={\csoptfmt{sort\dhyphen pad\dhyphen minus}}, + user1={\meta{marker}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.dual-sort-pad-minus, + name={\csoptfmt{dual\dhyphen sort\dhyphen pad\dhyphen minus}}, + user1={\meta{marker}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.secondary-sort-pad-minus, + name={\csoptfmt{secondary\dhyphen sort\dhyphen pad\dhyphen minus}}, + user1={\meta{marker}}, + category={resourceoption}, + parent={resourceoptions} +} + +@mainglscommand{GlsXtrLoadResources, + name={\csfmt{Gls\-Xtr\-Load\-Resources}}, + user1={\oargm{options}}, + description={a shortcut command that uses \csref{glsxtrresourcefile}}, + topics={indexing,shortcutcommands}, + note={\styfmt{glossaries-extra} v1.11+}, + seealso={resourceoptions,glsxtrresourcefile}, + category={command} +} + +@mainglscommand{glsxtrcopytoglossary, + name={\csfmt{gls\-xtr\-copy\-to\-glossary}}, + user1={\margm{label}\margm{type}}, + description={copies the entry given by \meta{label} to the +glossary given by \meta{type}}, + topics={assigncommands,definingterms}, + note={\styfmt{glossaries-extra} v1.12+}, + category={command} +} + +@mainglscommand{glsxtrnewglslike, + name={\csfmt{gls\-xtr\-new\-gls\-like}}, + user1={\oargm{options}\margm{prefix}\margm{gls-like +cs}\margm{glspl-like cs}\margm{Gls-like +cs}\margm{Glspl-like cs}}, + description={defines commands to behave like \ics{gls}, \ics{glspl}, + \ics{Gls} and \ics{Glspl} with the given label prefix}, + topics={entryrefcommands,providingcommands}, + note={\styfmt{glossaries-extra} v1.21+}, + seealso={glsxtrnewgls}, + category={command} +} + +@mainglscommand{glsxtrnewgls, + name={\csfmt{gls\-xtr\-new\-gls}}, + user1={\oargm{options}\margm{prefix}\margm{cs}}, + description={defines the command \meta{cs} to behave like + \ics{gls} with the given label prefix}, + topics={entryrefcommands,providingcommands}, + note={\styfmt{glossaries-extra} v1.21+}, + seealso={gls}, + category={command} +} + +@mainglscommand{glsnoidxdisplayloc, + name={\csfmt{gls\-no\-idx\-display\-loc}}, + user1={\margm{prefix}\margm{counter}\margm{format}\margm{location}}, + description={used to display a regular location in the + \field{location} field (with a hyperlink, if enabled)}, + topics={loclistcommands,linkcommands}, + note={\styfmt{glossaries} v4.04+}, + category={command} +} + +@mainglscommand{glsxtrdisplaylocnameref, + name={\csfmt{gls\-xtr\-display\-loc\-name\-ref}}, + user1={\margm{prefix}\margm{counter}\margm{format}\margm{location}\margm{title}\margm{href}\margm{hcounter}\margm{file}}, + description={used to display a \code{nameref} location in the + \field{location} field (with a hyperlink, if enabled)}, + topics={loclistcommands,linkcommands}, + note={\styfmt{glossaries-extra-bib2gls} v1.37+}, + category={command} +} + +@mainglscommand{glsxtrdisplaysupploc, + name={\csfmt{gls\-xtr\-display\-supp\-loc}}, + user1={\margm{prefix}\margm{counter}\margm{format}\margm{src}\margm{location}}, + description={used to display an external location in the + supplementary list (with a hyperlink, if enabled)}, + topics={loclistcommands,linkcommands,supplementalrefs}, + note={\styfmt{glossaries-extra-bib2gls} v1.36+}, + category={command} +} + +@mainglscommand{glsxtrmultisupplocation, + name={\csfmt{gls\-xtr\-multi\-supp\-location}}, + user1={\margm{location}\margm{src}\margm{format}}, + description={used by \csref{glsxtrdisplaysupploc} to format the + external location (with a hyperlink, if enabled)}, + topics={loclistcommands,linkcommands,formattingcommands,supplementalrefs}, + note={\styfmt{glossaries-extra-bib2gls} v1.36+}, + category={command} +} + +@glscommand{glsxtrsupplocationurl, + name={\csfmt{gls\-xtr\-supp\-loc\-a\-tion\-url}}, + description={set by \cs{glsxtrsupphypernumber} + and \csref{glsxtrmultisupplocation} to the + URL of the supplemental document for use by + \cs{glshypernumber}}, + topics={loclistcommands,supplementalrefs}, + note={\styfmt{glossaries-extra} v1.14+}, + seealso={glshypernumber,glsxtrsupphypernumber,glsxtrmultisupplocation,glsxtrlocationhyperlink}, + category={command} +} + +@glscommand{glsxtrlocationhyperlink, + name={\csfmt{gls\-xtr\-loc\-a\-tion\-hyper\-link}}, + user1={\margm{counter}\margm{prefix}\margm{location}}, + description={used to create the location hyperlink, + this tests if an internal or external link is required + depending on the definition of \cs{glsxtrsupplocationurl}}, + topics={loclistcommands,linkcommands,supplementalrefs}, + note={\styfmt{glossaries-extra} v1.14+}, + seealso={glsxtrsupphypernumber,glsxtrsupplocationurl}, + category={command} +} + +@glscommand{glsxtrsupphypernumber, + name={\csfmt{gls\-xtr\-supp\-hyper\-num\-ber}}, + user1={\margm{location}}, + description={uses \cs{glshypernumber} to create a hyperlink + to the given location (if hyperlinks are supported) but + first checks the \catattr{externallocation} attribute to determine + if an external link is required}, + topics={loclistcommands,linkcommands,supplementalrefs}, + note={\styfmt{glossaries-extra} v1.14+}, + seealso={glsxtrlocationhyperlink,glsxtrsupplocationurl}, + category={command} +} + +@mainglscommand{glsxtr@record, + name={\csfmt{glsxtr@record}}, + user1={\margm{label}\margm{prefix}\margm{counter}\margm{format}\margm{location}}, + description={this command is written to the \ext{aux} file each + time an entry is indexed to provide \bibgls\ with the record information}, + topics={internalcommands,auxcommands,indexing}, + note={\styfmt{glossaries-extra} v1.08+}, + category={command} +} + +@mainglscommand{glsxtr@record@nameref, + name={\csfmt{glsxtr@record@name\-ref}}, + user1={\margm{label}\margm{prefix}\margm{counter}\margm{format}\margm{location}\margm{title}\margm{href}\margm{hcounter}}, + description={used instead of \csref{glsxtr@record} when the + \styopt[nameref]{record} option is used}, + topics={internalcommands,auxcommands,indexing}, + note={\styfmt{glossaries-extra} v1.37+}, + category={command} +} + +@mainglscommand{glsxtrfieldlistadd, + name={\csfmt{gls\-xtr\-field\-list\-add}}, + user1={\margm{label}\margm{field}\margm{item}}, + description={adds the given item to the given field that contains + an \styfmt{etoolbox} internal list}, + topics={listcommands,assigncommands,fieldrefcommands}, + note={\styfmt{glossaries-extra} v1.12+}, + seealso={glsxtrfieldifinlist,glsxtrfieldforlistloop,glsxtrfielddolistloop}, + category={command} +} + +@glscommand{glsxtrfieldifinlist, + name={\csfmt{gls\-xtr\-field\-if\-in\-list}}, + user1={\margm{label}\margm{field}\margm{item}\margm{true}\margm{false}}, + description={tests if the given item is in the given field that contains + an \styfmt{etoolbox} internal list}, + topics={listcommands,conditionals,fieldrefcommands}, + note={\styfmt{glossaries-extra} v1.12+}, + seealso={glsxtrfieldxifinlist,glsxtrfieldlistadd,glsxtrfieldforlistloop,glsxtrfielddolistloop}, + category={command} +} + +@glscommand{glsxtrfieldxifinlist, + name={\csfmt{gls\-xtr\-field\-x\-if\-in\-list}}, + user1={\margm{label}\margm{field}\margm{item}\margm{true}\margm{false}}, + description={tests if the expansion of the given item is in the given field that contains + an \styfmt{etoolbox} internal list}, + topics={listcommands,conditionals,fieldrefcommands}, + note={\styfmt{glossaries-extra} v1.12+}, + seealso={glsxtrfieldifinlist}, + category={command} +} + +@glscommand{glsxtrcontrolrules, + name={\csfmt{gls\-xtr\-control\-rules}}, + user1={}, + description={collation sub-rule for control characters usually +placed at the start of a rule in the \qt{ignored characters} section +(although there typically won't be any control codes in sort fields)}, + topics={collationsubrules}, + note={\styfmt{glossaries-extra-bib2gls} v1.27+}, + category={command} +} + +@glscommand{glsxtrspacerules, + name={\csfmt{gls\-xtr\-space\-rules}}, + user1={}, + description={collation sub-rule for space characters}, + topics={collationsubrules}, + note={\styfmt{glossaries-extra-bib2gls} v1.27+}, + category={command} +} + +@glscommand{glsxtrnonprintablerules, + name={\csfmt{gls\-xtr\-non\-printable\-rules}}, + user1={}, + description={collation sub-rule for non-printable characters}, + topics={collationsubrules}, + note={\styfmt{glossaries-extra-bib2gls} v1.27+}, + category={command} +} + +@glscommand{glsxtrcombiningdiacriticrules, + name={\csfmt{gls\-xtr\-combining\-diacritic\-rules}}, + user1={}, + description={collation sub-rule for combining diacritic characters}, + topics={collationsubrules}, + note={\styfmt{glossaries-extra-bib2gls} v1.27+}, + category={command} +} + +@glscommand{glsxtrhyphenrules, + name={\csfmt{gls\-xtr\-hyphen\-rules}}, + user1={}, + description={collation sub-rule for hyphen characters}, + topics={collationsubrules}, + note={\styfmt{glossaries-extra-bib2gls} v1.27+}, + category={command} +} + +@glscommand{glsxtrgeneralpuncrules, + name={\csfmt{gls\-xtr\-general\-punc\-rules}}, + user1={}, + description={collation sub-rule for general punctuation characters}, + topics={collationsubrules}, + note={\styfmt{glossaries-extra-bib2gls} v1.27+}, + category={command} +} + +@glscommand{glsxtrdigitrules, + name={\csfmt{gls\-xtr\-digit\-rules}}, + user1={}, + description={collation sub-rule for digits from the basic Latin +set (0, \ldots, 9) as well as their subscript and superscript variants}, + topics={collationsubrules}, + note={\styfmt{glossaries-extra-bib2gls} v1.27+}, + category={command} +} + +@glscommand{glsxtrfractionrules, + name={\csfmt{gls\-xtr\-fraction\-rules}}, + user1={}, + description={collation sub-rule for vulgar fraction characters}, + topics={collationsubrules}, + note={\styfmt{glossaries-extra-bib2gls} v1.27+}, + category={command} +} + +@glscommand{glsxtrMathItalicGreekIrules, + name={\csfmt{gls\-xtr\-Math\-Italic\-Greek\-I\-rules}}, + user1={}, + description={collation sub-rule for math-Greek characters +(includes upright digamma between epsilon and zeta)}, + topics={collationsubrules}, + note={\styfmt{glossaries-extra-bib2gls} v1.27+}, + category={command} +} + +@glscommand{glsxtrGeneralLatinIrules, + name={\csfmt{gls\-xtr\-General\-Latin\-I\-rules}}, + user1={}, + description={collation sub-rule for Latin characters +(basic Latin set plus subscript and superscript Latin +characters)}, + topics={collationsubrules}, + note={\styfmt{glossaries-extra-bib2gls} v1.27+}, + seealso={glsxtrGeneralLatinIIrules,glsxtrGeneralLatinIIIrules,glsxtrGeneralLatinIVrules,glsxtrGeneralLatinVrules,glsxtrGeneralLatinVIrules,glsxtrGeneralLatinVIIrules,glsxtrGeneralLatinVIIIrules}, + category={command} +} + +@glscommand{glsxtrGeneralLatinIIrules, + name={\csfmt{gls\-xtr\-General\-Latin\-II\-rules}}, + user1={}, + description={collation sub-rule for Latin characters +(as \cs{glsxtrGeneralLatinIrules} but includes \DH/\dh\ between D/d +and E/e +and \ss\ treated as \qt{ss})}, + topics={collationsubrules}, + note={\styfmt{glossaries-extra-bib2gls} v1.27+}, + category={command} +} + +@glscommand{glsxtrGeneralLatinIIIrules, + name={\csfmt{gls\-xtr\-General\-Latin\-III\-rules}}, + user1={}, + description={collation sub-rule for Latin characters +(as \cs{glsxtrGeneralLatinIrules} but includes \DH/\dh\ between D/d +and E/e +and \ss\ treated as \qt{sz})}, + topics={collationsubrules}, + note={\styfmt{glossaries-extra-bib2gls} v1.27+}, + category={command} +} + +@glscommand{glsxtrGeneralLatinIVrules, + name={\csfmt{gls\-xtr\-General\-Latin\-IV\-rules}}, + user1={}, + description={collation sub-rule for Latin characters +(as \cs{glsxtrGeneralLatinIrules} but includes \DH/\dh\ between D/d +and E/e +and \AE/\ae\ treated as AE/ae, \OE/\oe\ treated +as OE/oe, \TH/\th\ treated as TH/th and \ss\ treated as \qt{ss})}, + topics={collationsubrules}, + note={\styfmt{glossaries-extra-bib2gls} v1.27+}, + category={command} +} + +@glscommand{glsxtrGeneralLatinVrules, + name={\csfmt{gls\-xtr\-General\-Latin\-V\-rules}}, + user1={}, + description={collation sub-rule for Latin characters +(as \cs{glsxtrGeneralLatinIrules} but includes \DH/\dh\ between D/d +and E/e +and \TH/\th\ treated as TH/th and \ss\ treated as \qt{ss})}, + topics={collationsubrules}, + note={\styfmt{glossaries-extra-bib2gls} v1.27+}, + category={command} +} + +@glscommand{glsxtrGeneralLatinVIrules, + name={\csfmt{gls\-xtr\-General\-Latin\-VI\-rules}}, + user1={}, + description={collation sub-rule for Latin characters +(as \cs{glsxtrGeneralLatinIrules} but includes \DH/\dh\ between D/d +and E/e +and \TH/\th\ treated as TH/th and \ss\ treated as \qt{sz})}, + topics={collationsubrules}, + note={\styfmt{glossaries-extra-bib2gls} v1.27+}, + category={command} +} + +@glscommand{glsxtrGeneralLatinVIIrules, + name={\csfmt{gls\-xtr\-General\-Latin\-VII\-rules}}, + user1={}, + description={collation sub-rule for Latin characters: +as \cs{glsxtrGeneralLatinIrules} but includes \AE/\ae\ between A/a +and B/b, +\DH/\dh\ between D/d and E/e, \insularG/\insularg\ (insular G) as +G/g, \OE/\oe\ +between O/o and P/p, \longs\ (long S) +equivalent to S/s, \TH/\th\ between T/t and U/u and \Wynn/\wynn\ +(wynn) as W/w}, + topics={collationsubrules}, + note={\styfmt{glossaries-extra-bib2gls} v1.27+}, + category={command} +} + +@glscommand{glsxtrGeneralLatinVIIIrules, + name={\csfmt{gls\-xtr\-General\-Latin\-VIII\-rules}}, + user1={}, + description={collation sub-rule for Latin characters: +as \cs{glsxtrGeneralLatinIrules} but includes \AE/\ae\ treated as +A/a, \OE/\oe\ treated as OE/oe, \TH/\th\ treated as TH/th, \ss\ +treated as \qt{ss}, \DH/\dh\ treated as D/d, \O/\o\ treated as O/o +and \L/\l\ treated as L/l}, + topics={collationsubrules}, + note={\styfmt{glossaries-extra-bib2gls} v1.27+}, + category={command} +} + +@glscommand{glsxtrLatinAA, + name={\csfmt{gls\-xtr\-Latin\-AA}}, + user1={}, + description={collation sub-rule for \AA/\aa}, + topics={collationsubrules}, + note={\styfmt{glossaries-extra-bib2gls} v1.27+}, + category={command} +} + +@glscommand{glsxtrLatinOslash, + name={\csfmt{gls\-xtr\-Latin\-O\-slash}}, + user1={}, + description={collation sub-rule for \O/\o}, + topics={collationsubrules}, + note={\styfmt{glossaries-extra-bib2gls} v1.27+}, + category={command} +} + +@command{alpha, + name={\csfmt{alpha}}, + user1={}, + description={Greek letter alpha $\alpha$}, + note={kernel command\texparserdefnote\ (maths mode)}, + category={command} +} + +@command{pi, + name={\csfmt{pi}}, + user1={}, + description={Greek letter pi $\pi$}, + note={kernel command\texparserdefnote\ (maths mode)}, + category={command} +} + +@command{sigma, + name={\csfmt{sigma}}, + user1={}, + description={Greek letter sigma $\sigma$}, + note={kernel command\texparserdefnote\ (maths mode)}, + category={command} +} + +@glscommand{omicron, + name={\csfmt{omicron}}, + user1={}, + description={Greek letter omicron $\omicron$}, + topics={charcommands}, + note={\styfmt{glossaries-extra-bib2gls}\texparserdefnote}, + category={command} +} + +@glscommand{Alpha, + name={\csfmt{Alpha}}, + user1={}, + description={Greek letter alpha $\Alpha$}, + topics={charcommands}, + note={\styfmt{glossaries-extra-bib2gls}\texparserdefnote}, + category={command} +} + +@command{approx, + name={\csfmt{approx}}, + user1={}, + description={approximate symbol $\approx$}, + note={kernel command\texparserdefnote\ (maths mode)}, + category={command} +} + +@command{surd, + name={\csfmt{surd}}, + user1={}, + description={surd symbol $\surd$}, + note={kernel command\texparserdefnote\ (maths mode)}, + category={command} +} + +@command{triangleright, + name={\csfmt{triangle\-right}}, + user1={}, + description={right-pointing triangle $\triangleright$}, + note={kernel command\texparserdefnote\ (maths mode)}, + category={command} +} + +@command{vert, + name={\csfmt{vert}}, + user1={}, + description={vertical bar delimiter $\vert$}, + note={kernel command\texparserdefnote\ (maths mode)}, + category={command} +} + +@command{Vert, + name={\csfmt{Vert}}, + user1={}, + description={double vertical bar delimiter $\Vert$}, + note={kernel command\texparserdefnote\ (maths mode)}, + category={command} +} + +@command{lvert, + name={\csfmt{lvert}}, + user1={}, + description={left vertical bar delimiter $\lvert$}, + note={\styfmt{amsmath}\texparserdefnote\ (maths mode)}, + category={command} +} + +@command{rvert, + name={\csfmt{rvert}}, + user1={}, + description={right vertical bar delimiter $\rvert$}, + note={\styfmt{amsmath}\texparserdefnote\ (maths mode)}, + category={command} +} + +@command{lVert, + name={\csfmt{lVert}}, + user1={}, + description={left double vertical bar delimiter $\lVert$}, + note={\styfmt{amsmath}\texparserdefnote\ (maths mode)}, + category={command} +} + +@command{rVert, + name={\csfmt{rVert}}, + user1={}, + description={right double vertical bar delimiter $\rVert$}, + note={\styfmt{amsmath}\texparserdefnote\ (maths mode)}, + category={command} +} + +@command{textstyle, + name={\csfmt{text\-style}}, + user1={}, + description={switch to in-line maths style (vertically compact)}, + note={kernel command (maths mode)}, + category={command} +} + +@command{displaystyle, + name={\csfmt{display\-style}}, + user1={}, + description={switch to display maths style}, + note={kernel command (maths mode)}, + category={command} +} + +@examplecommand{bigoperatornamefmt, + name={\csfmt{big\-operator\-name\-fmt}}, + user1={\margm{text}}, + description={example command}, + category={command} +} + +@examplecommand{nary, + name={\csfmt{nary}}, + user1={\margm{text}}, + description={example command}, + category={command} +} + +@examplecommand{strong, + name={\csfmt{strong}}, + user1={\margm{text}}, + description={example command}, + category={command} +} + +@examplecommand{parenswap, + name={\csfmt{parenswap}}, + user1={\margm{text1}\margm{text2}}, + description={example command}, + category={command} +} + +@examplecommand{sortop, + name={\csfmt{sortop}}, + user1={\margm{text1}\margm{text2}}, + description={example command}, + category={command} +} + +@examplecommand{sortname, + name={\csfmt{sortname}}, + user1={\margm{first name(s)}\margm{surname}}, + description={example command}, + category={command} +} + +@examplecommand{sortvonname, + name={\csfmt{sort\-von\-name}}, + user1={\margm{first name(s)}\margm{von}\margm{surname}}, + description={example command}, + category={command} +} + +@examplecommand{sortart, + name={\csfmt{sortart}}, + user1={\margm{article}\margm{text}}, + description={example command}, + category={command} +} + +@examplecommand{sortmediacreator, + name={\csfmt{sort\-media\-creator}}, + user1={\margm{first name(s)}\margm{surname}}, + description={example command}, + category={command} +} + +@examplecommand{setfmt, + name={\csfmt{setfmt}}, + user1={\margm{symbol}}, + description={example command}, + category={command} +} + +@examplecommand{setcontentsfmt, + name={\csfmt{setcontentsfmt}}, + user1={\margm{contents}}, + description={example command}, + category={command} +} + +@examplecommand{setmembershipfmt, + name={\csfmt{setmembershipfmt}}, + user1={\margm{variable(s)}\margm{condition}}, + description={example command}, + category={command} +} + +@examplecommand{setmembershiponeargfmt, + name={\csfmt{setmembershiponeargfmt}}, + user1={\marg{\margm{variable(s)}\margm{condition}}}, + description={example command}, + category={command} +} + +@examplecommand{setcardfmt, + name={\csfmt{setcardfmt}}, + user1={\margm{maths}}, + description={example command}, + category={command} +} + +@examplecommand{numspacefmt, + name={\csfmt{numspacefmt}}, + user1={\margm{symbol}}, + description={example command}, + category={command} +} + +@examplecommand{transposefmt, + name={\csfmt{transposefmt}}, + user1={\margm{maths}}, + description={example command}, + category={command} +} + +@examplecommand{invfmt, + name={\csfmt{invfmt}}, + user1={\margm{maths}}, + description={example command}, + category={command} +} + +@examplecommand{vecfmt, + name={\csfmt{vecfmt}}, + user1={\margm{symbol}}, + description={example command}, + category={command} +} + +@examplecommand{mtxfmt, + name={\csfmt{mtxfmt}}, + user1={\margm{symbol}}, + description={example command}, + category={command} +} + +@index{fileformats, + name={file formats}, + text={file format} +} + +@fileformat{ext.tex, + name={\extfmt{tex}}, + category={fileformat}, + parent={fileformats} +} + +@fileformat{ext.bib, + name={\extfmt{bib}}, + category={fileformat}, + parent={fileformats} +} + +@fileformat{ext.aux, + name={\extfmt{aux}}, + category={fileformat}, + parent={fileformats} +} + +@fileformat{ext.out, + name={\extfmt{out}}, + category={fileformat}, + parent={fileformats} +} + +@fileformat{ext.sh, + name={\extfmt{sh}}, + category={fileformat}, + parent={fileformats} +} + +@fileformat{ext.bat, + name={\extfmt{bat}}, + category={fileformat}, + parent={fileformats} +} + +@fileformat{ext.jar, + name={\extfmt{jar}}, + category={fileformat}, + parent={fileformats} +} + +@fileformat{ext.glg, + name={\extfmt{glg}}, + category={fileformat}, + parent={fileformats} +} + +@fileformat{ext.log, + name={\extfmt{log}}, + category={fileformat}, + parent={fileformats} +} + +@fileformat{ext.toc, + name={\extfmt{toc}}, + category={fileformat}, + parent={fileformats} +} + +@fileformat{ext.glstex, + name={\extfmt{glstex}}, + category={fileformat}, + parent={fileformats} +} + +@fileformat{ext.gls, + name={\extfmt{gls}}, + category={fileformat}, + parent={fileformats} +} + +@fileformat{ext.bbl, + name={\extfmt{bbl}}, + category={fileformat}, + parent={fileformats} +} + +@index{applications, + name={applications}, + text={applications} +} + +@application{bibtex, + name={\appfmt{bibtex}}, + category={application}, + parent={applications} +} + +@application{biber, + name={\appfmt{biber}}, + category={application}, + parent={applications} +} + +@application{makeindex, + name={\appfmt{make\-index}}, + category={application}, + parent={applications} +} + +@application{xindy, + name={\appfmt{xindy}}, + category={application}, + parent={applications} +} + +@application{makeglossaries, + name={\appfmt{make\-glos\-saries}}, + category={application}, + parent={applications} +} + +@application{makeglossaries-lite, + name={\appfmt{make\-glos\-saries\dhyphen lite}}, + category={application}, + parent={applications} +} + +@application{kpsewhich, + name={\appfmt{kpsewhich}}, + category={application}, + parent={applications} +} + +@application{arara, + name={\appfmt{arara}}, + category={application}, + parent={applications} +} + +@application{convertgls2bib, + name={\appfmt{convert\-gls2bib}}, + category={application}, + parent={applications} +} + +@index{packages, + name={packages}, + text={package} +} + +@package{glossaries, + name={\styfmt{glossaries}}, + category={package}, + parent={packages} +} + +@package{glossaries-extra, + name={\styfmt{glossaries-extra}}, + category={package}, + parent={packages} +} + +@package{pifont, + name={\styfmt{pifont}}, + category={package}, + parent={packages} +} + +@package{upgreek, + name={\styfmt{upgreek}}, + category={package}, + parent={packages} +} + +@package{xspace, + name={\styfmt{xspace}}, + category={package}, + parent={packages} +} + +@package{fourier, + name={\styfmt{fourier}}, + category={package}, + parent={packages} +} + +@package{lipsum, + name={\styfmt{lipsum}}, + category={package}, + parent={packages} +} + +@package{natbib, + name={\styfmt{natbib}}, + category={package}, + parent={packages} +} + +@package{textcomp, + name={\styfmt{textcomp}}, + category={package}, + parent={packages} +} + +@package{MnSymbol, + name={\styfmt{MnSymbol}}, + category={package}, + parent={packages} +} + +@package{wasysym, + name={\styfmt{wasysym}}, + category={package}, + parent={packages} +} + +@package{amssymb, + name={\styfmt{amssymb}}, + category={package}, + parent={packages} +} + +@package{stix, + name={\styfmt{stix}}, + category={package}, + parent={packages} +} + +@package{mhchem, + name={\styfmt{mhchem}}, + category={package}, + parent={packages} +} + +@package{bpchem, + name={\styfmt{bpchem}}, + category={package}, + parent={packages} +} + +@package{siunitx, + name={\styfmt{siunitx}}, + category={package}, + parent={packages} +} + +@package{tipa, + name={\styfmt{tipa}}, + category={package}, + parent={packages} +} + +@package{mfirstuc, + name={\styfmt{mfirstuc}}, + category={package}, + parent={packages} +} + +@package{mfirstuc-english, + name={\styfmt{mfirstuc-english}}, + category={package}, + parent={packages} +} + +@package{hyperref, + name={\styfmt{hyperref}}, + category={package}, + parent={packages} +} + +@package{glossary-hypernav, + name={\styfmt{glossary\dhyphen hypernav}}, + category={package}, + parent={packages} +} + +@package{glossaries-prefix, + name={\styfmt{glossaries\dhyphen prefix}}, + category={package}, + parent={packages} +} + +@package{glossaries-accsupp, + name={\styfmt{glossaries\dhyphen accsupp}}, + category={package}, + parent={packages} +} + +@package{glossaries-extra-stylemods, + name={\styfmt{glossaries\dhyphen extra\dhyphen stylemods}}, + category={package}, + parent={packages} +} + +@package{glossaries-extra-bib2gls, + name={\styfmt{glossaries\dhyphen extra\dhyphen bib2gls}}, + category={package}, + parent={packages} +} + +@package{glossary-list, + name={\styfmt{glossary\dhyphen list}}, + category={package}, + parent={packages} +} + +@package{glossary-tree, + name={\styfmt{glossary\dhyphen tree}}, + category={package}, + parent={packages} +} + +@package{glossary-topic, + name={\styfmt{glossary\dhyphen topic}}, + category={package}, + parent={packages} +} + +@package{glossary-mcols, + name={\styfmt{glossary\dhyphen mcols}}, + category={package}, + parent={packages} +} + +@package{glossary-long, + name={\styfmt{glossary\dhyphen long}}, + category={package}, + parent={packages} +} + +@package{glossary-super, + name={\styfmt{glossary\dhyphen super}}, + category={package}, + parent={packages} +} + +@package{glossary-longbooktabs, + name={\styfmt{glossary\dhyphen longbooktabs}}, + category={package}, + parent={packages} +} + +@package{glossary-bookindex, + name={\styfmt{glossary\dhyphen bookindex}}, + category={package}, + parent={packages} +} + +@package{glossary-longextra, + name={\styfmt{glossary\dhyphen longextra}}, + category={package}, + parent={packages} +} + +@package{booktabs, + name={\styfmt{booktabs}}, + category={package}, + parent={packages} +} + +@package{color, + name={\styfmt{color}}, + category={package}, + parent={packages} +} + +@package{graphics, + name={\styfmt{graphics}}, + category={package}, + parent={packages} +} + +@package{graphicx, + name={\styfmt{graphicx}}, + category={package}, + parent={packages} +} + +@package{ifthen, + name={\styfmt{ifthen}}, + category={package}, + parent={packages} +} + +@package{probsoln, + name={\styfmt{probsoln}}, + category={package}, + parent={packages} +} + +@package{shortvrb, + name={\styfmt{shortvrb}}, + category={package}, + parent={packages} +} + +@package{jmlrutils, + name={\styfmt{jmlrutils}}, + category={package}, + parent={packages} +} + +@package{inputenc, + name={\styfmt{inputenc}}, + category={package}, + parent={packages} +} + +@package{fontenc, + name={\styfmt{fontenc}}, + category={package}, + parent={packages} +} + +@package{slantsc, + name={\styfmt{slantsc}}, + category={package}, + parent={packages} +} + +@package{relsize, + name={\styfmt{relsize}}, + category={package}, + parent={packages} +} + +@package{babel, + name={\styfmt{babel}}, + category={package}, + parent={packages} +} + +@package{polyglossia, + name={\styfmt{polyglossia}}, + category={package}, + parent={packages} +} + +@package{fontspec, + name={\styfmt{fontspec}}, + category={package}, + parent={packages} +} + +@package{amsmath, + name={\styfmt{amsmath}}, + category={package}, + parent={packages} +} + +@package{textcase, + name={\styfmt{textcase}}, + category={package}, + parent={packages} +} + +@package{datetime2, + name={\styfmt{datetime2}}, + category={package}, + parent={packages} +} + +@package{datatool-base, + name={\styfmt{datatool\dhyphen base}}, + category={package}, + parent={packages} +} + +@package{datatool, + name={\styfmt{datatool}}, + category={package}, + parent={packages} +} + +@package{etoolbox, + name={\styfmt{etoolbox}}, + category={package}, + parent={packages} +} + +@package{soul, + name={\styfmt{soul}}, + category={package}, + parent={packages} +} + +@package{xcolor, + name={\styfmt{xcolor}}, + category={package}, + parent={packages} +} + +@package{tracklang, + name={\styfmt{tracklang}}, + category={package}, + parent={packages} +} + +@package{accsupp, + name={\styfmt{accsupp}}, + category={package}, + parent={packages} +} + +@symbol{stringconcat, + name={\code{\#} (string concatenation)}, + text={\code{\#}} +} + +@symbol{atchar, + name={\code{@} (bib entry identifier)}, + text={\code{@}} +} + +@specialchar{param, + name={\code{\#} (parameter)}, + text={\code{\#}} +} + +@symbol{hashchar, + name={\code{\#} (literal)}, + text={\code{\#}} +} + +@command{cs.hash, + name={\csfmt{\#}}, + description={produces the hash symbol \#}, + note={kernel command\texparserdefnote}, + category={command} +} + +@specialchar{colsep, + name={\code{\&} (alignment)}, + text={\code{\&}} +} + +@symbol{ampchar, + name={\code{\&} (literal)}, + text={\code{\&}} +} + +@command{cs.amp, + name={\csfmt{\&}}, + description={produces the ampersand symbol \&}, + note={kernel command\texparserdefnote}, + category={command} +} + +@specialchar{bgroupchar, + name={\code{\glsopenbrace} (begin group)}, + text={\code{\glsopenbrace}} +} + +@symbol{openbracechar, + name={\code{\glsopenbrace} (literal)}, + text={\code{\glsopenbrace}} +} + +@command{cs.openbrace, + name={\csfmt{\glsopenbrace}}, + description={produces the open brace symbol \glsopenbrace}, + note={kernel command\texparserdefnote}, + category={command} +} + +@specialchar{egroupchar, + name={\code{\glsclosebrace} (end group)}, + text={\code{\glsclosebrace}} +} + +@symbol{closebracechar, + name={\code{\glsclosebrace} (literal)}, + text={\code{\glsclosebrace}} +} + +@command{cs.closebrace, + name={\csfmt{\glsclosebrace}}, + description={produces the close brace symbol \glsclosebrace}, + note={kernel command\texparserdefnote}, + category={command} +} + +@specialchar{commentchar, + name={\code{\%} (comment)}, + text={\code{\%}} +} + +@symbol{percentchar, + name={\code{\%} (literal)}, + text={\code{\%}} +} + +@command{cs.percent, + name={\csfmt{\%}}, + description={produces the percent symbol \%}, + note={kernel command\texparserdefnote}, + category={command} +} + +@specialchar{sbchar, + name={\code{\_} (subscript)}, + text={\code{\_}} +} + +@symbol{underscorechar, + name={\code{\_} (literal)}, + text={\code{\_}} +} + +@command{cs.underscore, + name={\csfmt{\_}}, + description={produces the underscore symbol \_}, + note={kernel command\texparserdefnote}, + category={command} +} + +@specialchar{spchar, + name={\code{\char`\^} (superscript)}, + text={\code{\char`\^}} +} + +@symbol{circumchar, + name={\code{\char`\^} (literal)}, + text={\code{\char`\^}} +} + +@command{cs.circum, + name={\csfmt{\char`\^}}, + user1={\margm{character}}, + description={puts a circumflex accent over \meta{character}}, + note={kernel command\texparserdefnote}, + category={command} +} + +@specialchar{mshiftchar, + name={\code{\$} (maths shift)}, + text={\code{\$}} +} + +@symbol{dollarchar, + name={\code{\$} (literal)}, + text={\code{\$}} +} + +@command{cs.dollar, + name={\csfmt{\$}}, + description={produces the dollar symbol \$}, + note={kernel command\texparserdefnote}, + category={command} +} + +@specialchar{escchar, + name={\code{\glsbackslash} (escape)}, + text={\code{\glsbackslash}} +} + +@symbol{backslashchar, + name={\code{\glsbackslash} (literal)}, + text={\code{\glsbackslash}} +} + +@command{cs.backslash, + name={\csfmt{\glsbackslash}}, + user1={\oargm{len}}, + description={starts a new row in a tabular or array context +with an extra vertical space of length \meta{len} above it +(starred form prohibits a page break)}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{tabularnewline, + name={\csfmt{tabular\-new\-line}}, + user1={\oargm{len}}, + description={tabular version of \idx{cs.backslash} (avoids conflict +with forced line breaks in paragraph column formats)}, + note={kernel command}, + category={command} +} + +@specialchar{nbspchar, + name={\code{\glstildechar} (non-breakable space)}, + text={\code{\glstildechar}} +} + +@symbol{tildechar, + name={\code{\glstildechar} (literal)}, + text={\code{\glstildechar}} +} + +@symbol{doublequotechardelim, + name = {\code{"} (delimiter)}, + text = {\code{"}} +} + +@symbol{doublequotecharhex, + name = {\code{"} (hexadecimal identifier)}, + text = {\code{"}} +} + +@specialchar{doublequoteactivechar, + name = {\code{"} (active)}, + text = {\code{"}} +} + +@symbol{doublequotechar, + name = {\code{"} (literal)}, + text = {\code{"}} +} + +@symbol{openrange, + name = {\code{\rangestartmark} (start range)}, + text = {\code{\rangestartmark}} +} + +@symbol{closerange, + name = {\code{\rangeendmark} (end range)}, + text = {\code{\rangeendmark}} +} + +@command{cs.tilde, + name={\csfmt{\glstildechar}}, + user1={\margm{character}}, + description={puts tilde accent over \meta{character}}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{comma, + name={\csfmt{,}}, + description={thin space}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{vec, + name={\csfmt{vec}}, + user1={\margm{character}}, + description={puts right arrow accent over \meta{character}}, + note={kernel command\texparserdefnote\ (maths mode)}, + category={command} +} + +@symbol{zeroormore, + name={\code{*} (regular expression, zero or more)}, + text={\code{*}} +} + +@symbol{matchanydot, + name={\code{.}\ (regular expression, match any)}, + text={\code{.}} +} + +@symbol{periodchar, + name={\code{.}\ (end of sentence)}, + text={\code{.}}, + alias={full-stop} +} + +@command{cs.period, + name={\csfmt{.}}, + user1={\margm{character}}, + description={puts a dot accent over \meta{character}}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{cs.space, + name={\csfmt{\textvisiblespace}}, + description={produces an inter-word space}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{space, + name={\csfmt{space}}, + description={produces a space}, + note={kernel command\texparserdefnote}, + category={command} +} + +@symbol{aposchar, + name={\code{'} (apostrophe)}, + text={\code{'}}, + alias={apostrophe} +} + +@command{def, + name={\csfmt{def}}, + user1={\margm{cs}\meta{syntax}\margm{definition}}, + description={defines the control sequence \meta{cs}, without checking if the command + already exists}, + note={\TeX\ primitive\texparserdefnote}, + category={command} +} + +@command{edef, + name={\csfmt{edef}}, + user1={\margm{cs}\meta{syntax}\margm{definition}}, + description={defines the control sequence \meta{cs} to the full +expansion of \meta{definition}, without checking if the command + already exists}, + note={\TeX\ primitive\texparserdefnote}, + category={command} +} + +@command{ifstrempty, + name={\csfmt{if\-str\-empty}}, + user1={\margm{string}\margm{true}\margm{false}}, + description={tests if \meta{string} is empty}, + note={\styfmt{etoolbox}}, + category={command} +} + +@command{ifstrequal, + name={\csfmt{if\-str\-equal}}, + user1={\margm{string1}\margm{string2}\margm{true}\margm{false}}, + description={tests if \meta{string1} equals \meta{string2}}, + note={\styfmt{etoolbox}}, + category={command} +} + +@command{ifcsstring, + name={\csfmt{if\-cs\-string}}, + user1={\margm{cs-name}\margm{string}\margm{true}\margm{false}}, + description={tests if the replacement text of the command + given by the control sequence name \meta{cs-name} equals \meta{string}}, + note={\styfmt{etoolbox}}, + category={command} +} + +@command{ifdefstrequal, + name={\csfmt{if\-def\-str\-equal}}, + user1={\margm{cs1}\margm{cs2}\margm{true}\margm{false}}, + description={tests if the replacement text of the command + \meta{cs1} equals the replacement text of the command \meta{cs2}}, + note={\styfmt{etoolbox}}, + category={command} +} + +@command{ifcsstrequal, + name={\csfmt{if\-cs\-str\-equal}}, + user1={\margm{cs-name1}\margm{cs-name2}\margm{true}\margm{false}}, + description={tests if the replacement text of the command given by + the control sequence name \meta{cs-name1} equals the replacement text + of the command given by the control sequence name \meta{cs-name2}}, + note={\styfmt{etoolbox}}, + category={command} +} + +@command{undef, + name={\csfmt{undef}}, + user1={\meta{cs}}, + description={undefines the control sequence \meta{cs}}, + note={\styfmt{etoolbox}\texparserdefnote}, + category={command} +} + +@command{csdef, + name={\csfmt{csdef}}, + user1={\margm{cs-name}\meta{syntax}\margm{definition}}, + description={defines the control sequence whose name + is given by \meta{cs-name}, without checking if the command + already exists}, + note={\styfmt{etoolbox}\texparserdefnote}, + category={command} +} + +@command{csuse, + name={\csfmt{csuse}}, + user1={\margm{cs-name}}, + description={uses the control sequence whose name + is given by \meta{cs-name} or does nothing if the command + isn't defined}, + note={\styfmt{etoolbox}\texparserdefnote}, + category={command} +} + +@command{newrobustcmd, + name={\csfmt{new\-robust\-cmd}}, + user1={\margm{cs}\oargm{n}\oargm{def}\margm{code}}, + description={behaves like \cs{newcommand} but the newly defined +command will be robust}, + note={\styfmt{etoolbox}}, + category={command} +} + +@command{ifdefempty, + name={\csfmt{if\-def\-empty}}, + user1={\margm{cs}\margm{true}\margm{false}}, + description={tests if the control sequence \meta{cs} is empty}, + note={\styfmt{etoolbox}\texparserdefnote}, + category={command} +} + +@command{ifcsundef, + name={\csfmt{if\-cs\-un\-def}}, + user1={\margm{cs-name}\margm{true}\margm{false}}, + description={tests if the control sequence given by \meta{cs-name} +is undefined}, + note={\styfmt{etoolbox}}, + category={command} +} + +@command{ifcsdef, + name={\csfmt{if\-cs\-def}}, + user1={\margm{cs-name}\margm{true}\margm{false}}, + description={tests if the control sequence given by \meta{cs-name} +is defined}, + note={\styfmt{etoolbox}}, + category={command} +} + +@command{ifdef, + name={\csfmt{if\-def}}, + user1={\margm{cs}\margm{true}\margm{false}}, + description={tests if the control sequence \meta{cs} is defined}, + note={\styfmt{etoolbox}\texparserdefnote}, + category={command} +} + +@command{xifinlist, + name={\csfmt{xifinlist}}, + user1={\margm{element}\margm{list cs}\margm{true}\margm{false}}, + description={tests if the expansion of \meta{element} is in the list stored + in the control sequence \meta{list cs}}, + note={\styfmt{etoolbox}}, + category={command} +} + +@command{ifinlist, + name={\csfmt{ifinlist}}, + user1={\margm{element}\margm{list cs}\margm{true}\margm{false}}, + description={tests if \meta{element} is in the list stored + in the control sequence \meta{list cs}}, + note={\styfmt{etoolbox}}, + category={command} +} + +@command{listxadd, + name={\csfmt{listxadd}}, + user1={\margm{list cs}\margm{element}}, + description={globally adds (expanded) \meta{element} to the list stored + in the control sequence \meta{list cs}}, + note={\styfmt{etoolbox}}, + category={command} +} + +@command{listgadd, + name={\csfmt{listgadd}}, + user1={\margm{list cs}\margm{element}}, + description={globally adds \meta{element} to the list stored + in the control sequence \meta{list cs}}, + note={\styfmt{etoolbox}}, + category={command} +} + +@command{appto, + name={\csfmt{appto}}, + user1={\margm{cs}\margm{code}}, + description={appends \meta{code} to the definition of + the control sequence \meta{cs}}, + note={\styfmt{etoolbox}\texparserdefnote}, + category={command} +} + +@command{forlistloop, + name={\csfmt{for\-list\-loop}}, + user1={\margm{handler cs}\margm{list cs}}, + description={iterates over the internal list given by the command + \meta{list cs} and performs \meta{handler cs}\margm{element} for + each element}, + note={\styfmt{etoolbox}}, + category={command} +} + +@command{foreignlanguage, + name={\csfmt{foreign\-language}}, + user1={\margm{language name}\margm{text}}, + description={typesets \meta{text} according to the rules of the +given language}, + note={\styfmt{babel}}, + category={command} +} + +@command{selectlanguage, + name={\csfmt{select\-language}}, + user1={\margm{language name}}, + description={switch to the rules of the given language}, + note={\styfmt{babel} and \styfmt{polyglossia}}, + category={command} +} + +@command{setmainlanguage, + name={\csfmt{set\-main\-language}}, + user1={\oargm{options}\margm{language name}}, + description={load the main document language}, + note={\styfmt{polyglossia}}, + category={command} +} + +@command{setotherlanguage, + name={\csfmt{set\-other\-language}}, + user1={\oargm{options}\margm{language name}}, + description={load a secondary document language}, + note={\styfmt{polyglossia}}, + category={command} +} + +@command{textlanguage, + name={\csfmt{text\-\meta{language}}}, + user1={\oargm{options}\margm{text}}, + description={typeset \meta{text} according to \meta{language}}, + note={\styfmt{polyglossia}}, + category={command} +} + +@package{marvosym, + name={\styfmt{marvosym}}, + category={package}, + parent={packages} +} + +@package{ifsym, + name={\styfmt{ifsym}}, + category={package}, + parent={packages} +} + +@package{CJKutf8, + name={\styfmt{CJKutf8}}, + category={package}, + parent={packages} +} + +@environment{env.CJK, + name={\envfmt{CJK}}, + user1={\oargm{font encoding}\margm{encoding}\margm{family}}, + description={sets up support for \idx{CJK} content}, + note={\styfmt{CJK}}, + category={environment} +} + +@environment{env.description, + name={\envfmt{description}}, + description={list-like environment}, + note={provided by most classes}, + category={environment} +} + +@package{longtable, + name={\styfmt{longtable}}, + category={package}, + parent={packages} +} + +@environment{env.longtable, + name={\envfmt{longtable}}, + user1={\oargm{halign}\margm{column specs}}, + description={a tabular-like environment that can span multiple +pages (not available in multi-column or certain other contexts)}, + note={\styfmt{longtable}}, + category={environment} +} + +@environment{env.tabular, + name={\envfmt{tabular}}, + user1={\oargm{valign}\margm{column specs}}, + description={aligns material in rows and columns with \idx{colsep} +to separate columns and \cs{cs.backslash} to separate rows}, + note={kernel environment}, + category={environment} +} + +@package{tabularx, + name={\styfmt{tabularx}}, + category={package}, + parent={packages} +} + +@environment{env.tabularx, + name={\envfmt{tabularx}}, + user1={\margm{width}\oargm{valign}\margm{column specs}}, + description={a tabular-like environment that's designed to fit the + given \meta{width})}, + note={\styfmt{tabularx}}, + category={environment} +} + +@package{supertabular, + name={\styfmt{supertabular}}, + category={package}, + parent={packages} +} + +@index{env.supertabular, + name={\envfmt{supertabular}}, + user1={\margm{column specs}}, + description={a tabular-like environment that can span multiple +pages (not available in multi-column or certain other contexts)}, + note={\styfmt{supertabular}}, + category={environment} +} + +@glsenvironment{env.theglossary, + name={\envfmt{theglossary}}, + category={environment} +} + +@topic{abbreviationstyles, + name={abbreviation styles}, + text={abbreviation style}, + description={abbreviation styles are set using + \ics{newabbreviation} and govern the format of commands like \ics{gls} + (display style) and \ics{glsxtrfull} (inline style). The inline + style may or may not match the first use format of the display + style. To allow for greater flexibility in abbreviation styles, + \cs{gls} (and its variants) normally treat abbreviations + differently to other terms, but some abbreviation styles can work better + if the abbreviation is treated as a general term so in those cases the + style sets the \catattr{regular} attribute to \qt{true} for + the entry's category. The \styfmt{glossaries-extra} package comes with the file +\href{http://mirrors.ctan.org/macros/latex/contrib/glossaries-extra/samples/sample-abbr-styles.pdf}{\filefmt{sample-abbr-styles.pdf}} + that demonstrates all predefined styles} +} + +@abbreviationstyle{abbrstyle.long-short, + name={\abbrstylefmt{long\dhyphen short}}, + description={this abbreviation style displays the long form on + \idx{firstuse} of the \cs{gls}-like commands followed by the + short form in parentheses (formatted with \cs{glsxtrparen}). + Only the short form is shown on subsequent use. The + \field{description} field is set to the long form}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra}}, + parent={abbreviationstyles} +} + +@abbrvstylecommand{glsxtrlongshortname, + name={\csfmt{gls\-xtr\-long\-short\-name}}, + description={hook for the \abbrstyle{long-short} abbreviation + styles that expands to the value that the \field{name} field is + assigned to when the abbreviation is defined with + \cs{newabbreviation} (defaults to the short form)}, + topics={abbrstyle.long-short,abbrstyle.long-short-sc,abbrstyle.long-short-sm,abbrstyle.long-short-em,abbrstyle.long-em-short-em,abbrstyle.long-short-user,abbrstyle.long-postshort-user,abbrstyle.long-hyphen-short-hyphen,abbrstyle.long-hyphen-postshort-hyphen}, + note={\styfmt{glossaries-extra} v1.25+}, + category={command} +} + +@abbrvstylecommand{glslongdefaultfont, + name={\csfmt{gls\-long\-default\-font}}, + user1={\margm{text}}, + description={used by the abbreviation styles that don't have a + specific font to format the long form. The default definition +just does its argument without any formatting}, + topics={abbrstyle.long-short,abbrstyle.short-long,abbrstyle.short-nolong,abbrstyle.nolong-short,abbrstyle.nolong-short-noreg,abbrstyle.short-nolong-desc,abbrstyle.long-noshort-desc,abbrstyle.long-noshort-desc-noreg,abbrstyle.long-short-sc,abbrstyle.long-short-sc-desc,abbrstyle.short-sc-long,abbrstyle.short-sc-long-desc,abbrstyle.short-sc-nolong,abbrstyle.short-sc-nolong-desc,abbrstyle.nolong-short-sc,abbrstyle.long-noshort-sc,abbrstyle.long-noshort-sc-desc,abbrstyle.long-short-sm,abbrstyle.long-short-sm-desc,abbrstyle.short-sm-long,abbrstyle.short-sm-long-desc,abbrstyle.short-sm-nolong,abbrstyle.short-sm-nolong-desc,abbrstyle.nolong-short-sm,abbrstyle.long-noshort-sm,abbrstyle.long-noshort-sm-desc,abbrstyle.long-short-em,abbrstyle.long-short-em-desc,abbrstyle.short-em-long,abbrstyle.short-em-long-desc,abbrstyle.short-em-nolong,abbrstyle.short-em-nolong-desc,abbrstyle.nolong-short-em,abbrstyle.long-noshort-em,abbrstyle.long-noshort-em-desc,abbrstyle.long-noshort,abbrstyle.long-noshort-noreg,abbrstyle.long-short-desc}, + note={\styfmt{glossaries-extra} v1.04+}, + category={command} +} + +@abbrvstylecommand{glsfirstlongdefaultfont, + name={\csfmt{gls\-first\-long\-default\-font}}, + user1={\margm{text}}, + description={used by the abbreviation styles that don't have a + specific font to format the long form on \idx{firstuse}. The + default definition uses \cs{glslongdefaultfont}}, + topics={abbrstyle.long-short,abbrstyle.short-long,abbrstyle.short-nolong,abbrstyle.nolong-short,abbrstyle.nolong-short-noreg,abbrstyle.short-nolong-desc,abbrstyle.long-noshort-desc,abbrstyle.long-noshort-desc-noreg,abbrstyle.long-short-sc,abbrstyle.long-short-sc-desc,abbrstyle.short-sc-long,abbrstyle.short-sc-long-desc,abbrstyle.short-sc-nolong,abbrstyle.short-sc-nolong-desc,abbrstyle.nolong-short-sc,abbrstyle.long-noshort-sc,abbrstyle.long-noshort-sc-desc,abbrstyle.long-short-sm,abbrstyle.long-short-sm-desc,abbrstyle.short-sm-long,abbrstyle.short-sm-long-desc,abbrstyle.short-sm-nolong,abbrstyle.short-sm-nolong-desc,abbrstyle.nolong-short-sm,abbrstyle.long-noshort-sm,abbrstyle.long-noshort-sm-desc,abbrstyle.long-short-em,abbrstyle.long-short-em-desc,abbrstyle.short-em-long,abbrstyle.short-em-long-desc,abbrstyle.short-em-nolong,abbrstyle.short-em-nolong-desc,abbrstyle.nolong-short-em,abbrstyle.long-noshort-em,abbrstyle.long-noshort-em-desc,abbrstyle.long-noshort,abbrstyle.long-noshort-noreg,abbrstyle.long-short-desc}, + note={\styfmt{glossaries-extra}}, + category={command} +} + +@abbrvstylecommand{glsabbrvdefaultfont, + name={\csfmt{gls\-abbrv\-default\-font}}, + user1={\margm{text}}, + description={used by the abbreviation styles that don't have a + specific font to format the short form. The default definition +just does its argument without any formatting}, + topics={abbrstyle.long-short,abbrstyle.short-long,abbrstyle.short-footnote,abbrstyle.short-postfootnote,abbrstyle.short-nolong,abbrstyle.nolong-short,abbrstyle.nolong-short-noreg,abbrstyle.short-nolong-desc,abbrstyle.long-noshort-desc,abbrstyle.long-noshort-desc-noreg,abbrstyle.long-hyphen-noshort-desc-noreg,abbrstyle.long-hyphen-noshort-noreg,abbrstyle.long-noshort,abbrstyle.long-noshort-noreg,abbrstyle.long-short-desc}, + note={\styfmt{glossaries-extra}}, + category={command} +} + +@abbrvstylecommand{glsfirstabbrvdefaultfont, + name={\csfmt{gls\-first\-abbrv\-default\-font}}, + user1={\margm{text}}, + description={used by the abbreviation styles that don't have a + specific font to format the short form on \idx{firstuse}. The + default definition uses \cs{glsabbrvdefaultfont}}, + topics={abbrstyle.long-short,abbrstyle.short-long,abbrstyle.short-footnote,abbrstyle.short-postfootnote,abbrstyle.short-nolong,abbrstyle.nolong-short,abbrstyle.nolong-short-noreg,abbrstyle.short-nolong-desc,abbrstyle.long-noshort-desc,abbrstyle.long-noshort-desc-noreg,abbrstyle.long-hyphen-noshort-desc-noreg,abbrstyle.long-hyphen-noshort-noreg,abbrstyle.long-noshort,abbrstyle.long-noshort-noreg,abbrstyle.long-short-desc}, + note={\styfmt{glossaries-extra}}, + category={command} +} + +@abbreviationstyle{abbrstyle.long-short-desc, + name={\abbrstylefmt{long\dhyphen short\dhyphen desc}}, + description={this abbreviation style is like the + \abbrstyle{long-short} style but the \field{description} + field must be provided in the entry definition}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra}}, + parent={abbreviationstyles} +} + +@abbrvstylecommand{glsxtrlongshortdescname, + name={\csfmt{gls\-xtr\-long\-short\-desc\-name}}, + description={hook for the \abbrstyle{long-short-desc} abbreviation + styles that expands to the value that the \field{name} field is + assigned to when the abbreviation is defined with + \cs{newabbreviation} (defaults to the long form followed by the + short form in parentheses)}, + topics={abbrstyle.long-short-desc,abbrstyle.long-short-sc-desc,abbrstyle.long-short-sm-desc,abbrstyle.long-short-em-desc,abbrstyle.long-em-short-em-desc,abbrstyle.long-hyphen-short-hyphen-desc,abbrstyle.long-hyphen-postshort-hyphen-desc}, + note={\styfmt{glossaries-extra} v1.17+}, + category={command} +} + +@abbreviationstyle{abbrstyle.short-long, + name={\abbrstylefmt{short\dhyphen long}}, + description={this abbreviation style displays the short form on + \idx{firstuse} of the \cs{gls}-like commands followed by the + long form in parentheses (formatted with \cs{glsxtrparen}). + Only the short form is shown on subsequent use. The + \field{description} field is set to the long form}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra}}, + parent={abbreviationstyles} +} + +@abbrvstylecommand{glsxtrshortlongname, + name={\csfmt{gls\-xtr\-short\-long\-name}}, + description={hook for the \abbrstyle{short-long} abbreviation styles + that expands to the value that the \field{name} field is assigned + to when the abbreviation is defined with \cs{newabbreviation} + (defaults to the short form)}, + topics={abbrstyle.short-long,abbrstyle.short-sc-long,abbrstyle.short-sm-long,abbrstyle.short-em-long,abbrstyle.short-em-long-em,abbrstyle.short-postlong-user,abbrstyle.short-long-user,abbrstyle.short-hyphen-long-hyphen,abbrstyle.short-hyphen-postlong-hyphen}, + note={\styfmt{glossaries-extra} v1.25+}, + category={command} +} + +@abbreviationstyle{abbrstyle.short-long-desc, + name={\abbrstylefmt{short\dhyphen long\dhyphen desc}}, + description={this abbreviation style is like the + \abbrstyle{short-long} style but the \field{description} + field must be provided in the entry definition}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra}}, + parent={abbreviationstyles} +} + +@abbrvstylecommand{glsxtrshortlongdescname, + name={\csfmt{gls\-xtr\-short\-long\-desc\-name}}, + description={hook for the \abbrstyle{short-long-desc} abbreviation + styles that expands to the value that the \field{name} field is + assigned to when the abbreviation is defined with + \cs{newabbreviation} (defaults to the long form followed by the + short form in parentheses)}, + topics={abbrstyle.short-long-desc,abbrstyle.short-sc-long-desc,abbrstyle.short-sm-long-desc,abbrstyle.short-em-long-desc,abbrstyle.short-em-long-em-desc,abbrstyle.short-hyphen-long-hyphen-desc,abbrstyle.short-hyphen-postlong-hyphen-desc}, + note={\styfmt{glossaries-extra} v1.17+}, + category={command} +} + +@abbreviationstyle{abbrstyle.short-footnote, + name={\abbrstylefmt{short\dhyphen footnote}}, + description={this abbreviation style displays the short form on + \idx{firstuse} of the \cs{gls}-like commands with the long form as + a footnote. Only the short form is shown on subsequent use. The + \field{description} field is set to the long form. The inline full + form obtained with commands like \cs{glsxtrfull} uses a + parenthetical style. Since this can result in nested hyperlinks + (from the \idx{link-text} to the glossary and from the footnote + marker to the footnote) this style automatically sets the + \catattr{nohyperfirst} category attribute to \optfmt{true} for + the entry's category}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.04+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.footnote, + name={\abbrstylefmt{footnote}}, + description={an alias for \abbrstyle{short-footnote}}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra}}, + parent={abbreviationstyles} +} + +@abbrvstylecommand{glslongfootnotefont, + name={\csfmt{gls\-long\-foot\-note\-font}}, + user1={\margm{text}}, + description={used with the \qt{footnote} abbreviation styles to + format the long form}, + topics={abbrstyle.short-footnote,abbrstyle.short-postfootnote,abbrstyle.short-sc-footnote,abbrstyle.short-sc-postfootnote,abbrstyle.short-sm-footnote,abbrstyle.short-sm-postfootnote,abbrstyle.short-em-footnote,abbrstyle.short-em-postfootnote}, + note={\styfmt{glossaries-extra} v1.05+}, + category={command} +} + +@abbrvstylecommand{glsfirstlongfootnotefont, + name={\csfmt{gls\-first\-long\-foot\-note\-font}}, + user1={\margm{text}}, + description={used with the \qt{footnote} abbreviation styles to + format the long form on first use}, + topics={abbrstyle.short-footnote,abbrstyle.short-postfootnote,abbrstyle.short-sc-footnote,abbrstyle.short-sc-postfootnote,abbrstyle.short-sm-footnote,abbrstyle.short-sm-postfootnote,abbrstyle.short-em-footnote,abbrstyle.short-em-postfootnote}, + note={\styfmt{glossaries-extra} v1.05+}, + category={command} +} + +@abbrvstylecommand{glsxtrabbrvfootnote, + name={\csfmt{gls\-xtr\-abbrv\-foot\-note}}, + user1={\margm{label}\margm{long form}}, + description={used with the \qt{footnote} abbreviation styles to + do the footnote. The \meta{label} is ignored by default. The + \meta{long form} includes the font changing command. This just + does \code{\cs{footnote}\margm{long form}}}, + topics={abbrstyle.short-footnote,abbrstyle.short-postfootnote,abbrstyle.short-sc-footnote,abbrstyle.short-sc-postfootnote,abbrstyle.short-sm-footnote,abbrstyle.short-sm-postfootnote,abbrstyle.short-em-footnote,abbrstyle.short-em-postfootnote}, + note={\styfmt{glossaries-extra} v1.07+}, + category={command} +} + +@abbrvstylecommand{glsxtrfootnotename, + name={\csfmt{gls\-xtr\-foot\-note\-name}}, + description={hook for the \qt{footnote} abbreviation styles + that expands to the value that the \field{name} field is assigned + to when the abbreviation is defined with \cs{newabbreviation} + (defaults to the short form)}, + topics={abbrstyle.short-footnote,abbrstyle.short-postfootnote,abbrstyle.short-sc-footnote,abbrstyle.short-sc-postfootnote,abbrstyle.short-sm-footnote,abbrstyle.short-sm-postfootnote,abbrstyle.short-em-footnote,abbrstyle.short-em-postfootnote}, + note={\styfmt{glossaries-extra} v1.25+}, + category={command} +} + +@abbreviationstyle{abbrstyle.short-postfootnote, + name={\abbrstylefmt{short\dhyphen postfootnote}}, + description={this abbreviation style is like + \abbrstyle{short-footnote} but the footnote is moved to the + \idx{postlinkhook} (outside of the hyperlink, if enabled) to + prevent nested hyperlinks. This means that, unlike + \abbrstyle{short-footnote} the \catattr{nohyperfirst} attribute + isn't changed}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.04}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.postfootnote, + name={\abbrstylefmt{postfootnote}}, + description={an alias for \abbrstyle{short-postfootnote}}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra}}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.short-nolong, + name={\abbrstylefmt{short\dhyphen nolong}}, + description={this abbreviation style only displays the \field{short} form + with the \cs{gls}-like commands (regardless of the \idx{firstuseflag}). + The \field{long} form can be accessed with \cs{glsxtrlong}. + The \field{name} field is set to \cs{glsxtrshortnolongname} and the + \field{description} field is set to the \field{long} form (unless + overridden in the entry definition). The inline full form + displays the short form followed by the long form in parentheses. + This style sets the \catattr{regular} attribute to \optfmt{true} + for the entry's category}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.04}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.short, + name={\abbrstylefmt{short}}, + description={an alias for \abbrstyle{short-nolong}}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra}}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.short-nolong-noreg, + name={\abbrstylefmt{short\dhyphen nolong\dhyphen noreg}}, + description={this abbreviation style is like \abbrstyle{short-nolong} + but doesn't set the \catattr{regular} attribute to \optfmt{true}}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.17+}, + parent={abbreviationstyles} +} + +@abbrvstylecommand{glsxtrshortnolongname, + name={\csfmt{gls\-xtr\-short\-no\-long\-name}}, + description={hook for the \abbrstyle{short-nolong} abbreviation styles + that expands to the value that the \field{name} field is assigned + to when the abbreviation is defined with \cs{newabbreviation} + (defaults to the short form)}, + topics={abbrstyle.short-nolong,abbrstyle.short-nolong-noreg,abbrstyle.short-sc-nolong,abbrstyle.short-sm-nolong,abbrstyle.short-em-nolong}, + note={\styfmt{glossaries-extra} v1.25+}, + category={command} +} + +@abbreviationstyle{abbrstyle.short-nolong-desc, + name={\abbrstylefmt{short\dhyphen nolong\dhyphen desc}}, + description={this abbreviation style is like the + \abbrstyle{short-nolong} style but the \field{description} + field must be provided in the entry definition. This style sets + the \catattr{regular} attribute to \optfmt{true} for the entry's + category}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.04+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.short-desc, + name={\abbrstylefmt{short-desc}}, + description={an alias for \abbrstyle{short-nolong-desc}}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra}}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.short-nolong-desc-noreg, + name={\abbrstylefmt{short\dhyphen nolong\dhyphen desc\dhyphen noreg}}, + description={this abbreviation style is like \abbrstyle{short-nolong-desc} + but doesn't set the \catattr{regular} attribute to \optfmt{true}}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.17+}, + parent={abbreviationstyles} +} + +@abbrvstylecommand{glsxtrshortdescname, + name={\csfmt{gls\-xtr\-short\-desc\-name}}, + description={hook for the \abbrstyle{short-nolong-desc} abbreviation styles + that expands to the value that the \field{name} field is assigned + to when the abbreviation is defined with \cs{newabbreviation} + (defaults to the short form followed by long form in parentheses)}, + topics={abbrstyle.short-nolong-desc,abbrstyle.short-nolong-desc-noreg,abbrstyle.short-sc-nolong-desc,abbrstyle.short-sm-nolong-desc,abbrstyle.short-em-nolong-desc}, + note={\styfmt{glossaries-extra} v1.17+}, + category={command} +} + +@abbreviationstyle{abbrstyle.nolong-short, + name={\abbrstylefmt{nolong\dhyphen short}}, + description={this abbreviation style only displays the \field{short} form + with the \cs{gls}-like commands (regardless of the \idx{firstuseflag}). + The \field{long} form can be accessed with \cs{glsxtrlong}. + The \field{name} field is set to \cs{glsxtrshortnolongname} and the + \field{description} field is set to the \field{long} form (unless + overridden in the entry definition). The inline full form + displays the long form followed by the short form in parentheses. + This style sets the \catattr{regular} attribute to \optfmt{true} + for the entry's category}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.21+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.nolong-short-noreg, + name={\abbrstylefmt{nolong\dhyphen short\dhyphen noreg}}, + description={this abbreviation style is like \abbrstyle{nolong-short} + but doesn't set the \catattr{regular} attribute to \optfmt{true}}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.21+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.long-noshort-desc, + name={\abbrstylefmt{long\dhyphen noshort\dhyphen desc}}, + description={this abbreviation style only displays the \field{long} + form with the \cs{gls}-like commands (regardless of the + \idx{firstuseflag}). The \field{short} + form can be accessed with \cs{glsxtrshort}. The \field{name} + field is set to \cs{glsxtrlongnoshortdescname} and the \field{description} + field must be provided in the entry definition. The inline full + form displays the long form followed by the short form in + parentheses. This style sets the \catattr{regular} attribute to + \optfmt{true} for the entry's category}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.04+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.long-desc, + name={\abbrstylefmt{long-desc}}, + description={an alias for \abbrstyle{long-noshort-desc}}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra}}, + parent={abbreviationstyles} +} + +@abbrvstylecommand{glsxtrlongnoshortdescname, + name={\csfmt{gls\-xtr\-long\-no\-short\-desc\-name}}, + description={hook for the \abbrstyle{long-noshort-desc} abbreviation styles + that expands to the value that the \field{name} field is assigned + to when the abbreviation is defined with \cs{newabbreviation} + (defaults to the long form)}, + topics={abbrstyle.long-noshort-desc,abbrstyle.long-noshort-desc-noreg,abbrstyle.long-em-noshort-em-desc,abbrstyle.long-hyphen-noshort-desc-noreg,abbrstyle.long-noshort-sc-desc,abbrstyle.long-noshort-sm-desc,abbrstyle.long-noshort-em-desc,abbrstyle.long-em-noshort-em-desc-noreg}, + note={\styfmt{glossaries-extra} v1.25+}, + category={command} +} + +@abbreviationstyle{abbrstyle.long-noshort-desc-noreg, + name={\abbrstylefmt{long\dhyphen noshort\dhyphen desc\dhyphen noreg}}, + description={this abbreviation style is like \abbrstyle{long-noshort-desc} + but doesn't set the \catattr{regular} attribute to \optfmt{true}}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.17+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.long-noshort, + name={\abbrstylefmt{long\dhyphen noshort}}, + description={this abbreviation style only displays the \field{long} form + with the \cs{gls}-like commands (regardless of the \idx{firstuseflag}). + The \field{short} form can be accessed with \cs{glsxtrshort}. + The \field{name} field is set to \cs{glsxtrlongnoshortname} and the + \field{description} field is set to the \field{long} form (unless + overridden in the entry definition). The inline full form + displays the long form followed by the short form in parentheses. + This style sets the \catattr{regular} attribute to \optfmt{true} + for the entry's category}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.04+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.long, + name={\abbrstylefmt{long}}, + description={an alias for \abbrstyle{long-noshort}}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra}}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.long-noshort-noreg, + name={\abbrstylefmt{long\dhyphen noshort\dhyphen noreg}}, + description={this abbreviation style is like \abbrstyle{long-noshort} + but doesn't set the \catattr{regular} attribute to \optfmt{true}}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.17+}, + parent={abbreviationstyles} +} + +@abbrvstylecommand{glsxtrlongnoshortname, + name={\csfmt{gls\-xtr\-long\-no\-short\-name}}, + description={hook for the \abbrstyle{long-noshort} abbreviation styles + that expands to the value that the \field{name} field is assigned + to when the abbreviation is defined with \cs{newabbreviation} + (defaults to the short form)}, + topics={abbrstyle.long-noshort,abbrstyle.long-noshort-noreg,abbrstyle.long-noshort-sc,abbrstyle.long-noshort-sm,abbrstyle.long-noshort-em,abbrstyle.long-em-noshort-em,abbrstyle.long-em-noshort-em-noreg,abbrstyle.long-hyphen-noshort-noreg}, + note={\styfmt{glossaries-extra} v1.25+}, + category={command} +} + +@abbreviationstyle{abbrstyle.long-short-sc, + name={\abbrstylefmt{long\dhyphen short\dhyphen sc}}, + description={this abbreviation style is like \abbrstyle{long-short} + but the short form is displayed in small-caps (so it needs to be + in \idx{lowercase})}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra}}, + parent={abbreviationstyles} +} + +@abbrvstylecommand{glsxtrscsuffix, + name={\csfmt{gls\-xtr\-sc\-suffix}}, + user1={}, + description={the suffix used to construct the plural for + the short form of abbreviations with the small-cap + \qt{sc} styles. This counteracts the effect of \cs{textsc} + using \ics{glstextup}}, + topics={abbrstyle.long-short-sc,abbrstyle.long-short-sc-desc,abbrstyle.short-sc-long,abbrstyle.short-sc-long-desc,abbrstyle.short-sc-nolong,abbrstyle.short-sc-nolong-desc,abbrstyle.nolong-short-sc,abbrstyle.short-sc-footnote,abbrstyle.short-sc-postfootnote,abbrstyle.long-noshort-sc,abbrstyle.long-noshort-sc-desc}, + note={\styfmt{glossaries-extra}}, + category={command} +} + +@abbrvstylecommand{glsabbrvscfont, + name={\csfmt{gls\-abbrv\-sc\-font}}, + user1={\margm{text}}, + description={used with \qt{sc} abbreviation styles to format the +short form using \cs{textsc}}, + topics={abbrstyle.long-short-sc,abbrstyle.long-short-sc-desc,abbrstyle.short-sc-long,abbrstyle.short-sc-long-desc,abbrstyle.short-sc-nolong,abbrstyle.short-sc-nolong-desc,abbrstyle.nolong-short-sc,abbrstyle.short-sc-footnote,abbrstyle.short-sc-postfootnote,abbrstyle.long-noshort-sc,abbrstyle.long-noshort-sc-desc}, + note={\styfmt{glossaries-extra} v1.17+}, + category={command} +} + +@abbrvstylecommand{glsfirstabbrvscfont, + name={\csfmt{gls\-first\-abbrv\-sc\-font}}, + user1={\margm{text}}, + description={used with \qt{sc} abbreviation styles to format the + short form on \idx{firstuse}. This defaults to \cs{glsabbrvscfont}}, + topics={abbrstyle.long-short-sc,abbrstyle.long-short-sc-desc,abbrstyle.short-sc-long,abbrstyle.short-sc-long-desc,abbrstyle.short-sc-nolong,abbrstyle.short-sc-nolong-desc,abbrstyle.nolong-short-sc,abbrstyle.short-sc-footnote,abbrstyle.short-sc-postfootnote,abbrstyle.long-noshort-sc,abbrstyle.long-noshort-sc-desc}, + note={\styfmt{glossaries-extra} v1.17+}, + category={command} +} + +@abbreviationstyle{abbrstyle.long-short-sc-desc, + name={\abbrstylefmt{long\dhyphen short\dhyphen sc\dhyphen desc}}, + description={this abbreviation style is like the + \abbrstyle{long-short-sc} style but the \field{description} + field must be provided in the entry definition}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra}}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.short-sc-long, + name={\abbrstylefmt{short\dhyphen sc\dhyphen long}}, + description={this abbreviation style is like \abbrstyle{short-long} + but the short form is displayed in small-caps (so it needs to be + in \idx{lowercase})}, + category={abbreviationstyle}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.short-sc-long-desc, + name={\abbrstylefmt{short\dhyphen sc\dhyphen long\dhyphen desc}}, + description={this abbreviation style is like the + \abbrstyle{short-sc-long} style but the \field{description} + field must be provided in the entry definition}, + category={abbreviationstyle}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.short-sc-nolong, + name={\abbrstylefmt{short\dhyphen sc\dhyphen nolong}}, + description={this abbreviation style is like \abbrstyle{short-nolong} + but the short form is displayed in small-caps (so it needs to be + in \idx{lowercase}). This style sets the \catattr{regular} + attribute to \optfmt{true} for the entry's category}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.04+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.short-sc, + name={\abbrstylefmt{short\dhyphen sc}}, + description={an alias for \abbrstyle{short-sc-nolong}}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra}}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.short-sc-nolong-desc, + name={\abbrstylefmt{short\dhyphen sc\dhyphen nolong\dhyphen desc}}, + description={this abbreviation style is like the + \abbrstyle{short-sc-nolong} style but the \field{description} + field must be provided in the entry definition. This style + sets the \catattr{regular} attribute to \optfmt{true} for the + entry's category}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.04+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.short-sc-desc, + name={\abbrstylefmt{short\dhyphen sc\dhyphen desc}}, + description={an alias for \abbrstyle{short-sc-nolong-desc}}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra}}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.nolong-short-sc, + name={\abbrstylefmt{nolong\dhyphen short\dhyphen sc}}, + description={this abbreviation style is like \abbrstyle{nolong-short} + but the short form is displayed in small-caps (so it needs to be + in \idx{lowercase}). This style + sets the \catattr{regular} attribute to \optfmt{true} for the + entry's category}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.21+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.long-noshort-sc, + name={\abbrstylefmt{long\dhyphen noshort\dhyphen sc}}, + description={this abbreviation style is like \abbrstyle{long-noshort} + but the short form is displayed in small-caps (so it needs to be + in \idx{lowercase}). This style + sets the \catattr{regular} attribute to \optfmt{true} for the + entry's category}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.04+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.long-noshort-sc-desc, + name={\abbrstylefmt{long\dhyphen noshort\dhyphen sc\dhyphen desc}}, + description={this abbreviation style is like the + \abbrstyle{long-noshort-sc} style but the \field{description} + field must be provided in the entry definition. This style + sets the \catattr{regular} attribute to \optfmt{true} for the + entry's category}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.04+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.short-sc-footnote, + name={\abbrstylefmt{short\dhyphen sc\dhyphen footnote}}, + description={this abbreviation style is like \abbrstyle{short-footnote} + but the short form is displayed in small-caps (so it needs to be + in \idx{lowercase})}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.04+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.short-sc-postfootnote, + name={\abbrstylefmt{short\dhyphen sc\dhyphen postfootnote}}, + description={this abbreviation style is like \abbrstyle{short-postfootnote} + but the short form is displayed in small-caps (so it needs to be + in \idx{lowercase})}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.04+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.long-short-sm, + name={\abbrstylefmt{long\dhyphen short\dhyphen sm}}, + description={this abbreviation style is like \abbrstyle{long-short} + but the short form is displayed using a smaller font. The + \sty{relsize} package is required with this style}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra}}, + parent={abbreviationstyles} +} + +@abbrvstylecommand{glsabbrvsmfont, + name={\csfmt{gls\-abbrv\-sm\-font}}, + user1={\margm{text}}, + description={used with \qt{sm} abbreviation styles to format the +short form using \ics{textsmaller}}, + topics={abbrstyle.long-short-sm,abbrstyle.long-short-sm-desc,abbrstyle.short-sm-long,abbrstyle.short-sm-long-desc,abbrstyle.short-sm-nolong,abbrstyle.short-sm-nolong-desc,abbrstyle.nolong-short-sm,abbrstyle.short-sm-footnote,abbrstyle.short-sm-postfootnote,abbrstyle.long-noshort-sm,abbrstyle.long-noshort-sm-desc}, + note={\styfmt{glossaries-extra} v1.17+}, + category={command} +} + +@abbrvstylecommand{glsfirstabbrvsmfont, + name={\csfmt{gls\-first\-abbrv\-sm\-font}}, + user1={\margm{text}}, + description={used with \qt{sm} abbreviation styles to format the + short form on \idx{firstuse}. This defaults to \cs{glsabbrvsmfont}}, + topics={abbrstyle.long-short-sm,abbrstyle.long-short-sm-desc,abbrstyle.short-sm-long,abbrstyle.short-sm-long-desc,abbrstyle.short-sm-nolong,abbrstyle.short-sm-nolong-desc,abbrstyle.nolong-short-sm,abbrstyle.short-sm-footnote,abbrstyle.short-sm-postfootnote,abbrstyle.long-noshort-sm,abbrstyle.long-noshort-sm-desc}, + note={\styfmt{glossaries-extra} v1.17+}, + category={command} +} + +@abbrvstylecommand{glsxtrsmsuffix, + name={\csfmt{gls\-xtr\-sm\-suffix}}, + user1={}, + description={the suffix used to construct the plural for + the short form of abbreviations with the \qt{sm} styles. This + defaults to \cs{glsxtrabbrvpluralsuffix}}, + topics={abbrstyle.long-short-sm,abbrstyle.long-short-sm-desc,abbrstyle.short-sm-long,abbrstyle.short-sm-long-desc,abbrstyle.short-sm-nolong,abbrstyle.short-sm-nolong-desc,abbrstyle.nolong-short-sm,abbrstyle.short-sm-footnote,abbrstyle.short-sm-postfootnote,abbrstyle.long-noshort-sm,abbrstyle.long-noshort-sm-desc}, + note={\styfmt{glossaries-extra}}, + category={command} +} + +@abbreviationstyle{abbrstyle.long-short-sm-desc, + name={\abbrstylefmt{long\dhyphen short\dhyphen sm\dhyphen desc}}, + description={this abbreviation style is like the + \abbrstyle{long-short-sm} style but the \field{description} + field must be provided in the entry definition}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra}}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.short-sm-long, + name={\abbrstylefmt{short\dhyphen sm\dhyphen long}}, + description={this abbreviation style is like \abbrstyle{short-long} + but the short form is displayed using a smaller font}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra}}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.short-sm-long-desc, + name={\abbrstylefmt{short\dhyphen sm\dhyphen long\dhyphen desc}}, + description={this abbreviation style is like the + \abbrstyle{long-short-sm} style but the \field{description} + field must be provided in the entry definition}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra}}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.short-sm-nolong, + name={\abbrstylefmt{short\dhyphen sm\dhyphen nolong}}, + description={this abbreviation style is like \abbrstyle{short-nolong} + but the short form is displayed using a smaller font. This style + sets the \catattr{regular} attribute to \optfmt{true} for the + entry's category}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.04+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.short-sm, + name={\abbrstylefmt{short\dhyphen sm}}, + description={an alias for \abbrstyle{short-sm-nolong}}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra}}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.short-sm-nolong-desc, + name={\abbrstylefmt{short\dhyphen sm\dhyphen nolong\dhyphen desc}}, + description={this abbreviation style is like the + \abbrstyle{short-sm-nolong} style but the \field{description} + field must be provided in the entry definition. This style + sets the \catattr{regular} attribute to \optfmt{true} for the + entry's category}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.04+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.short-sm-desc, + name={\abbrstylefmt{short\dhyphen sm\dhyphen desc}}, + description={an alias for \abbrstyle{short-sm-nolong-desc}}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra}}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.nolong-short-sm, + name={\abbrstylefmt{nolong\dhyphen short\dhyphen sm}}, + description={this abbreviation style is like \abbrstyle{nolong-short} + but the short form is displayed using a smaller font. This style + sets the \catattr{regular} attribute to \optfmt{true} for the + entry's category}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.21+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.long-noshort-sm, + name={\abbrstylefmt{long\dhyphen noshort\dhyphen sm}}, + description={this abbreviation style is like \abbrstyle{long-noshort} + but the short form is displayed using a smaller font. This style + sets the \catattr{regular} attribute to \optfmt{true} for the + entry's category}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.04+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.long-noshort-sm-desc, + name={\abbrstylefmt{long\dhyphen noshort\dhyphen sm\dhyphen desc}}, + description={this abbreviation style is like the + \abbrstyle{long-noshort-sm} style but the \field{description} + field must be provided in the entry definition. This style + sets the \catattr{regular} attribute to \optfmt{true} for the + entry's category}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.04+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.short-sm-footnote, + name={\abbrstylefmt{short\dhyphen sm\dhyphen footnote}}, + description={this abbreviation style is like \abbrstyle{short-footnote} + but the short form is displayed in a smaller font}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.04+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.short-sm-postfootnote, + name={\abbrstylefmt{short\dhyphen sm\dhyphen postfootnote}}, + description={this abbreviation style is like \abbrstyle{short-postfootnote} + but the short form is displayed in a smaller font}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.04+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.long-short-em, + name={\abbrstylefmt{long\dhyphen short\dhyphen em}}, + description={this abbreviation style is like \abbrstyle{long-short} + but the short form is displayed using an emphasized font}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra}}, + parent={abbreviationstyles} +} + +@abbrvstylecommand{glsabbrvemfont, + name={\csfmt{gls\-abbrv\-em\-font}}, + user1={\margm{text}}, + description={used with \qt{em} abbreviation styles to format the +short form using \ics{emph}}, + topics={abbrstyle.long-em-short-em,abbrstyle.long-short-em,abbrstyle.long-short-em-desc,abbrstyle.short-em-long,abbrstyle.short-em-long-desc,abbrstyle.short-em-nolong,abbrstyle.short-em-nolong-desc,abbrstyle.nolong-short-em,abbrstyle.short-em-footnote,abbrstyle.short-em-postfootnote,abbrstyle.long-em-noshort-em,abbrstyle.long-em-noshort-em-desc,abbrstyle.long-em-noshort-em-desc-noreg,abbrstyle.long-em-noshort-em-noreg,abbrstyle.long-em-short-em-desc,abbrstyle.long-noshort-em,abbrstyle.long-noshort-em-desc}, + note={\styfmt{glossaries-extra} v1.04+}, + category={command} +} + +@abbrvstylecommand{glsfirstabbrvemfont, + name={\csfmt{gls\-first\-abbrv\-em\-font}}, + user1={\margm{text}}, + description={used with \qt{em} abbreviation styles to format the + short form on \idx{firstuse}. This defaults to \cs{glsabbrvemfont}}, + topics={abbrstyle.long-em-short-em,abbrstyle.long-short-em,abbrstyle.long-short-em-desc,abbrstyle.short-em-long,abbrstyle.short-em-long-desc,abbrstyle.short-em-nolong,abbrstyle.short-em-nolong-desc,abbrstyle.nolong-short-em,abbrstyle.short-em-footnote,abbrstyle.short-em-postfootnote,abbrstyle.long-em-short-em-desc,abbrstyle.long-em-noshort-em,abbrstyle.long-em-noshort-em-desc,abbrstyle.long-em-noshort-em-desc-noreg,abbrstyle.long-em-noshort-em-noreg,abbrstyle.long-noshort-em,abbrstyle.long-noshort-em-desc}, + note={\styfmt{glossaries-extra} v1.04+}, + category={command} +} + +@abbrvstylecommand{glsxtremsuffix, + name={\csfmt{gls\-xtr\-em\-suffix}}, + description={the suffix used to construct the plural for + the short form of abbreviations with the \qt{em} styles. This + defaults to \cs{glsxtrabbrvpluralsuffix}}, + topics={abbrstyle.long-em-short-em,abbrstyle.long-short-em,abbrstyle.long-short-em-desc,abbrstyle.short-em-long,abbrstyle.short-em-long-desc,abbrstyle.short-em-nolong,abbrstyle.short-em-nolong-desc,abbrstyle.nolong-short-em,abbrstyle.short-em-footnote,abbrstyle.short-em-postfootnote,abbrstyle.long-em-noshort-em,abbrstyle.long-em-noshort-em-desc,abbrstyle.long-em-noshort-em-desc-noreg,abbrstyle.long-em-noshort-em-noreg,abbrstyle.long-noshort-em,abbrstyle.long-noshort-em-desc}, + note={\styfmt{glossaries-extra}}, + category={command} +} + +@abbrvstylecommand{glslongemfont, + name={\csfmt{gls\-long\-em\-font}}, + user1={\margm{text}}, + description={used with \qt{long-em} abbreviation styles to format the +long form using \ics{emph}}, + topics={abbrstyle.long-em-short-em,abbrstyle.long-em-short-em-desc,abbrstyle.short-em-long-em,abbrstyle.short-em-long-em-desc,abbrstyle.long-em-noshort-em,abbrstyle.long-em-noshort-em-desc,abbrstyle.long-em-noshort-em-desc-noreg,abbrstyle.long-em-noshort-em-noreg}, + note={\styfmt{glossaries-extra} v1.04+}, + category={command} +} + +@abbrvstylecommand{glsfirstlongemfont, + name={\csfmt{gls\-first\-long\-em\-font}}, + user1={\margm{text}}, + description={used with \qt{long-em} abbreviation styles to format the + long form on \idx{firstuse}. This defaults to \cs{glslongemfont}}, + topics={abbrstyle.long-em-short-em,abbrstyle.long-em-short-em-desc,abbrstyle.short-em-long-em,abbrstyle.short-em-long-em-desc,abbrstyle.long-em-noshort-em,abbrstyle.long-em-noshort-em-desc,abbrstyle.long-em-noshort-em-desc-noreg,abbrstyle.long-em-noshort-em-noreg}, + note={\styfmt{glossaries-extra} v1.04+}, + category={command} +} + +@abbreviationstyle{abbrstyle.long-short-em-desc, + name={\abbrstylefmt{long\dhyphen short\dhyphen em\dhyphen desc}}, + description={this abbreviation style is like the + \abbrstyle{long-short-em} style but the \field{description} + field must be provided in the entry definition}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra}}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.long-em-short-em, + name={\abbrstylefmt{long\dhyphen em\dhyphen short\dhyphen em}}, + description={this abbreviation style is like \abbrstyle{long-short} + but the short and long forms are displayed using an emphasized font}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.04+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.long-em-short-em-desc, + name={\abbrstylefmt{long\dhyphen em\dhyphen short\dhyphen em\dhyphen desc}}, + description={this abbreviation style is like the + \abbrstyle{long-em-short-em} style but the \field{description} + field must be provided in the entry definition}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.04+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.short-em-long, + name={\abbrstylefmt{short\dhyphen em\dhyphen long}}, + description={this abbreviation style is like \abbrstyle{short-long} + but the short form is displayed using an emphasized font}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra}}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.short-em-long-desc, + name={\abbrstylefmt{short\dhyphen em\dhyphen long\dhyphen desc}}, + description={this abbreviation style is like the + \abbrstyle{short-em-long} style but the \field{description} + field must be provided in the entry definition}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra}}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.short-em-long-em, + name={\abbrstylefmt{short\dhyphen em\dhyphen long\dhyphen em}}, + description={this abbreviation style is like \abbrstyle{short-long} + but the short and long forms are displayed using an emphasized font}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.04+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.short-em-long-em-desc, + name={\abbrstylefmt{short\dhyphen em\dhyphen long\dhyphen em\dhyphen desc}}, + description={this abbreviation style is like the + \abbrstyle{short-em-long-em} style but the \field{description} + field must be provided in the entry definition}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.04+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.short-em-nolong, + name={\abbrstylefmt{short\dhyphen em\dhyphen nolong}}, + description={this abbreviation style is like \abbrstyle{short-nolong} + but the short form is displayed using an emphasized font. This style + sets the \catattr{regular} attribute to \optfmt{true} for the + entry's category}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.04+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.short-em, + name={\abbrstylefmt{short\dhyphen em}}, + description={an alias for \abbrstyle{short-em-nolong}}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra}}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.short-em-nolong-desc, + name={\abbrstylefmt{short\dhyphen em\dhyphen nolong\dhyphen desc}}, + description={this abbreviation style is like the + \abbrstyle{short-em-nolong} style but the \field{description} + field must be provided in the entry definition. This style + sets the \catattr{regular} attribute to \optfmt{true} for the + entry's category}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.04+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.short-em-desc, + name={\abbrstylefmt{short\dhyphen em\dhyphen desc}}, + description={an alias for \abbrstyle{short-em-nolong-desc}}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra}}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.nolong-short-em, + name={\abbrstylefmt{nolong\dhyphen short\dhyphen em}}, + description={this abbreviation style is like \abbrstyle{nolong-short} + but the short form is displayed using an emphasized font. This style + sets the \catattr{regular} attribute to \optfmt{true} for the + entry's category}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.21+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.long-noshort-em, + name={\abbrstylefmt{long\dhyphen noshort\dhyphen em}}, + description={this abbreviation style is like \abbrstyle{long-noshort} + but the short form is displayed using an emphasized font. This style + sets the \catattr{regular} attribute to \optfmt{true} for the + entry's category}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.04+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.long-em-noshort-em, + name={\abbrstylefmt{long\dhyphen em\dhyphen noshort\dhyphen em}}, + description={this abbreviation style is like \abbrstyle{long-noshort} + but the long and short forms are displayed using an emphasized font. + This style sets the \catattr{regular} attribute to \optfmt{true} for the + entry's category}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.04+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.long-em-noshort-em-noreg, + name={\abbrstylefmt{long\dhyphen em\dhyphen noshort\dhyphen em\dhyphen noreg}}, + description={this abbreviation style is like \abbrstyle{long-noshort-noreg} + but the long and short forms are displayed using an emphasized font}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.17+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.long-noshort-em-desc, + name={\abbrstylefmt{long\dhyphen noshort\dhyphen em\dhyphen desc}}, + description={this abbreviation style is like the + \abbrstyle{long-noshort-em} style but the \field{description} + field must be provided in the entry definition. This style + sets the \catattr{regular} attribute to \optfmt{true} for the + entry's category}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.04+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.long-em-noshort-em-desc, + name={\abbrstylefmt{long\dhyphen em\dhyphen noshort\dhyphen em\dhyphen desc}}, + description={this abbreviation style is like the + \abbrstyle{long-em-noshort-em} style but the \field{description} + field must be provided in the entry definition. This style + sets the \catattr{regular} attribute to \optfmt{true} for the + entry's category}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.04+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.long-em-noshort-em-desc-noreg, + name={\abbrstylefmt{long\dhyphen em\dhyphen noshort\dhyphen em\dhyphen desc\dhyphen noreg}}, + description={this abbreviation style is like the + \abbrstyle{long-em-noshort-em-noreg} style but the \field{description} + field must be provided in the entry definition}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.17+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.short-em-footnote, + name={\abbrstylefmt{short\dhyphen em\dhyphen footnote}}, + description={this abbreviation style is like \abbrstyle{short-footnote} + but the short form is displayed in an emphasized font}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.04+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.short-em-postfootnote, + name={\abbrstylefmt{short\dhyphen em\dhyphen postfootnote}}, + description={this abbreviation style is like \abbrstyle{short-postfootnote} + but the short form is displayed in an emphasized font}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.04+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.long-short-user, + name={\abbrstylefmt{long\dhyphen short\dhyphen user}}, + description={this abbreviation style is like \abbrstyle{long-short} + but the parenthetical material is governed by \cs{glsxtruserparen}}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.04+}, + parent={abbreviationstyles} +} + +@abbrvstylecommand{glsxtruserfield, + name={\csfmt{gls\-xtr\-user\-field}}, + description={used by the parenthetical abbreviation styles, this + expands to the internal label of the field used to store the additional parenthetical + material. The default value is \field{useri}}, + topics={abbrstyle.long-short-user,abbrstyle.short-long-user,abbrstyle.long-postshort-user,abbrstyle.long-postshort-user-desc,abbrstyle.short-postlong-user-desc,abbrstyle.long-short-user-desc,abbrstyle.short-long-user-desc}, + note={\styfmt{glossaries-extra} v1.04+}, + category={command} +} + +@abbrvstylecommand{glsxtruserparen, + name={\csfmt{gls\-xtr\-user\-paren}}, + user1={\margm{text}\margm{label}}, + description={used by the \qt{user} abbreviation styles + to format the parenthetical material where \meta{text} + is the default parenthetical text and \meta{label} + is the entry's label. This checks the field given + by \cs{glsxtruserfield} and, if set, the \meta{text} is + followed by a comma and the user value}, + topics={abbrstyle.long-short-user,abbrstyle.short-long-user,abbrstyle.long-postshort-user,abbrstyle.long-postshort-user-desc,abbrstyle.short-postlong-user-desc,abbrstyle.long-short-user-desc,abbrstyle.short-long-user-desc}, + note={\styfmt{glossaries-extra} v1.04+}, + category={command} +} + +@abbrvstylecommand{glsabbrvuserfont, + name={\csfmt{gls\-abbrv\-user\-font}}, + user1={\margm{text}}, + description={used with \qt{user} abbreviation styles to + format the short form. The default definition just uses \cs{glsabbrvdefaultfont}}, + topics={abbrstyle.long-short-user,abbrstyle.short-long-user,abbrstyle.long-postshort-user,abbrstyle.long-postshort-user-desc,abbrstyle.short-postlong-user-desc,abbrstyle.long-short-user-desc,abbrstyle.short-long-user-desc}, + note={\styfmt{glossaries-extra} v1.04+}, + category={command} +} + +@abbrvstylecommand{glsfirstabbrvuserfont, + name={\csfmt{gls\-first\-abbrv\-user\-font}}, + user1={\margm{text}}, + description={used with \qt{user} abbreviation styles to + format the short form on \idx{firstuse}. The default definition just uses +\cs{glsabbrvuserfont}}, + topics={abbrstyle.long-short-user,abbrstyle.short-long-user,abbrstyle.long-postshort-user,abbrstyle.long-postshort-user-desc,abbrstyle.short-postlong-user-desc,abbrstyle.long-short-user-desc,abbrstyle.short-long-user-desc}, + note={\styfmt{glossaries-extra} v1.04+}, + category={command} +} + +@abbrvstylecommand{glslonguserfont, + name={\csfmt{gls\-long\-user\-font}}, + user1={\margm{text}}, + description={used with \qt{user} abbreviation styles to + format the long form. The default definition just uses \cs{glslongdefaultfont}}, + topics={abbrstyle.long-short-user,abbrstyle.short-long-user,abbrstyle.long-postshort-user,abbrstyle.long-postshort-user-desc,abbrstyle.short-postlong-user-desc,abbrstyle.long-short-user-desc,abbrstyle.short-long-user-desc}, + note={\styfmt{glossaries-extra} v1.04+}, + category={command} +} + +@abbrvstylecommand{glsfirstlonguserfont, + name={\csfmt{gls\-first\-long\-user\-font}}, + user1={\margm{text}}, + description={used with \qt{user} abbreviation styles to + format the long form on first use. The default definition just uses +\cs{glslonguserfont}}, + topics={abbrstyle.long-short-user,abbrstyle.short-long-user,abbrstyle.long-postshort-user,abbrstyle.long-postshort-user-desc,abbrstyle.short-postlong-user-desc,abbrstyle.long-short-user-desc,abbrstyle.short-long-user-desc}, + note={\styfmt{glossaries-extra} v1.04+}, + category={command} +} + +@abbrvstylecommand{glsxtrusersuffix, + name={\csfmt{gls\-xtr\-user\-suffix}}, + description={the suffix used to construct the plural for + the short form of abbreviations with the \qt{user} styles. + The default definition just uses \cs{glsxtrabbrvpluralsuffix}}, + topics={abbrstyle.long-short-user,abbrstyle.short-long-user,abbrstyle.long-postshort-user,abbrstyle.long-postshort-user-desc,abbrstyle.short-postlong-user-desc,abbrstyle.long-short-user-desc,abbrstyle.short-long-user-desc}, + note={\styfmt{glossaries-extra} v1.04+}, + category={command} +} + +@abbrvstylecommand{glsuserdescription, + name={\csfmt{gls\-user\-description}}, + user1={\margm{description}\margm{label}}, + description={used with \qt{user} abbreviation styles to + encapsulate the description. Just does + \code{\cs{glslonguserfont}\margm{description}} by default}, + topics={abbrstyle.long-short-user,abbrstyle.short-long-user,abbrstyle.long-postshort-user,abbrstyle.long-postshort-user-desc,abbrstyle.short-postlong-user-desc,abbrstyle.long-short-user-desc,abbrstyle.short-long-user-desc}, + note={\styfmt{glossaries-extra} v1.30+}, + category={command} +} + +@abbreviationstyle{abbrstyle.long-postshort-user, + name={\abbrstylefmt{long\dhyphen postshort\dhyphen user}}, + description={this abbreviation style is like \abbrstyle{long-short-user} + but the parenthetical material is moved to the \idx{postlinkhook}}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.12+}, + parent={abbreviationstyles} +} + +@abbrvstylecommand{glsxtrlongshortuserdescname, + name={\csfmt{gls\-xtr\-long\-short\-user\-desc\-name}}, + description={hook for the \abbrstyle{long-short-user-desc} abbreviation + styles that expands to the value that the \field{name} field is + assigned to when the abbreviation is defined with + \cs{newabbreviation} (defaults to the long form followed by the + parenthetical material)}, + topics={abbrstyle.long-postshort-user-desc,abbrstyle.long-short-user-desc}, + note={\styfmt{glossaries-extra} v1.25+}, + category={command} +} + +@abbreviationstyle{abbrstyle.long-postshort-user-desc, + name={\abbrstylefmt{long\dhyphen postshort\dhyphen user\dhyphen desc}}, + description={this abbreviation style is like the + \abbrstyle{long-postshort-user} style but the \field{description} + field must be provided in the entry definition}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.12+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.short-postlong-user, + name={\abbrstylefmt{short\dhyphen postlong\dhyphen user}}, + description={this abbreviation style is like \abbrstyle{short-long-user} + but the parenthetical material is moved to the \idx{postlinkhook}}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.12+}, + parent={abbreviationstyles} +} + +@abbrvstylecommand{glsxtrshortlonguserdescname, + name={\csfmt{gls\-xtr\-short\-long\-user\-desc\-name}}, + description={hook for the \abbrstyle{short-long-user-desc} abbreviation + styles that expands to the value that the \field{name} field is + assigned to when the abbreviation is defined with + \cs{newabbreviation} (defaults to the short form followed by the + parenthetical material)}, + topics={abbrstyle.short-postlong-user-desc,abbrstyle.short-long-user-desc}, + note={\styfmt{glossaries-extra} v1.25+}, + category={command} +} + +@abbreviationstyle{abbrstyle.short-postlong-user-desc, + name={\abbrstylefmt{short\dhyphen postlong\dhyphen user\dhyphen desc}}, + description={this abbreviation style is like the + \abbrstyle{short-postlong-user} style but the \field{description} + field must be provided in the entry definition}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.12+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.long-short-user-desc, + name={\abbrstylefmt{long\dhyphen short\dhyphen user\dhyphen desc}}, + description={this abbreviation style is like the + \abbrstyle{long-short-user} style but the \field{description} + field must be provided in the entry definition}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.04+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.short-long-user, + name={\abbrstylefmt{short\dhyphen long\dhyphen user}}, + description={this abbreviation style is like \abbrstyle{short-long} + but the parenthetical material is governed by \cs{glsxtruserparen}}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.04+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.short-long-user-desc, + name={\abbrstylefmt{short\dhyphen long\dhyphen user\dhyphen desc}}, + description={this abbreviation style is like the + \abbrstyle{short-long-user} style but the \field{description} + field must be provided in the entry definition}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.04+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.long-hyphen-short-hyphen, + name={\abbrstylefmt{long\dhyphen hyphen\dhyphen short\dhyphen +hyphen}}, + description={this abbreviation style is like \abbrstyle{long-short} + but is designed to work with the \catattr{markwords} attribute. If + the attribute is set, the style will check if the inserted + material (provided by the final optional argument of commands like + \cs{gls}) starts with a hyphen. If it does, the insert is added to + the parenthetical material}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.17+}, + parent={abbreviationstyles} +} + +@abbrvstylecommand{glsxtrifhyphenstart, + name={\csfmt{gls\-xtr\-if\-hyphen\-start}}, + user1={\margm{text}\margm{true}\margm{false}}, + description={used by the \qt{hyphen} abbreviation styles, this + checks if \meta{text} starts with a hyphen}, + topics={abbrstyle.long-hyphen-short-hyphen,abbrstyle.long-hyphen-short-hyphen-desc,abbrstyle.long-hyphen-noshort-desc-noreg,abbrstyle.long-hyphen-noshort-noreg,abbrstyle.long-hyphen-postshort-hyphen,abbrstyle.long-hyphen-postshort-hyphen-desc,abbrstyle.short-hyphen-long-hyphen,abbrstyle.short-hyphen-long-hyphen-desc,abbrstyle.short-hyphen-postlong-hyphen,abbrstyle.short-hyphen-postlong-hyphen-desc}, + note={\styfmt{glossaries-extra} v1.17+}, + category={command} +} + +@abbrvstylecommand{glsxtrlonghyphenshort, + name={\csfmt{gls\-xtr\-long\-hyphen\-short}}, + user1={\margm{label}\margm{long}\margm{short}\margm{insert}}, + description={used by the \qt{long\dhyphen hyphen\dhyphen + short\dhyphen hyphen} abbreviation styles to format the full form}, + topics={abbrstyle.long-hyphen-short-hyphen,abbrstyle.long-hyphen-short-hyphen-desc}, + note={\styfmt{glossaries-extra} v1.17+}, + category={command} +} + +@abbrvstylecommand{glsabbrvhyphenfont, + name={\csfmt{gls\-abbrv\-hyphen\-font}}, + user1={\margm{text}}, + description={used by the \qt{hyphen} abbreviation styles to format + the short form}, + topics={abbrstyle.long-hyphen-short-hyphen,abbrstyle.long-hyphen-short-hyphen-desc,abbrstyle.long-hyphen-postshort-hyphen,abbrstyle.long-hyphen-postshort-hyphen-desc,abbrstyle.short-hyphen-long-hyphen,abbrstyle.short-hyphen-long-hyphen-desc,abbrstyle.short-hyphen-postlong-hyphen,abbrstyle.short-hyphen-postlong-hyphen-desc}, + note={\styfmt{glossaries-extra} v1.17+}, + category={command} +} + +@abbrvstylecommand{glsfirstabbrvhyphenfont, + name={\csfmt{gls\-first\-abbrv\-hyphen\-font}}, + user1={\margm{text}}, + description={used by the \qt{hyphen} abbreviation styles to format + the short form on \idx{firstuse}}, + topics={abbrstyle.long-hyphen-short-hyphen,abbrstyle.long-hyphen-postshort-hyphen,abbrstyle.long-hyphen-postshort-hyphen-desc,abbrstyle.long-hyphen-short-hyphen-desc}, + note={\styfmt{glossaries-extra} v1.17+}, + category={command} +} + +@abbrvstylecommand{glslonghyphenfont, + name={\csfmt{gls\-long\-hyphen\-font}}, + user1={\margm{text}}, + description={used by the \qt{hyphen} abbreviation styles to format + the long form}, + topics={abbrstyle.long-hyphen-short-hyphen,abbrstyle.long-hyphen-noshort-desc-noreg,abbrstyle.long-hyphen-noshort-noreg,abbrstyle.long-hyphen-postshort-hyphen,abbrstyle.long-hyphen-postshort-hyphen-desc,abbrstyle.long-hyphen-short-hyphen-desc}, + note={\styfmt{glossaries-extra} v1.17+}, + category={command} +} + +@abbrvstylecommand{glsfirstlonghyphenfont, + name={\csfmt{gls\-first\-long\-hyphen\-font}}, + user1={\margm{text}}, + description={used by the \qt{hyphen} abbreviation styles to format + the long form on \idx{firstuse}}, + topics={abbrstyle.long-hyphen-short-hyphen,abbrstyle.long-hyphen-noshort-desc-noreg,abbrstyle.long-hyphen-noshort-noreg,abbrstyle.long-hyphen-postshort-hyphen,abbrstyle.long-hyphen-postshort-hyphen-desc,abbrstyle.long-hyphen-short-hyphen-desc}, + note={\styfmt{glossaries-extra} v1.17+}, + category={command} +} + +@abbrvstylecommand{glsxtrhyphensuffix, + name={\csfmt{gls\-xtr\-hyphen\-suffix}}, + description={the suffix used to construct the plural for + the short form of abbreviations with the \qt{hyphen} styles}, + topics={abbrstyle.long-hyphen-short-hyphen,abbrstyle.long-hyphen-postshort-hyphen,abbrstyle.long-hyphen-postshort-hyphen-desc,abbrstyle.long-hyphen-short-hyphen-desc}, + note={\styfmt{glossaries-extra} v1.17+}, + category={command} +} + +@abbreviationstyle{abbrstyle.long-hyphen-short-hyphen-desc, + name={\abbrstylefmt{long\dhyphen hyphen\dhyphen short\dhyphen +hyphen\dhyphen desc}}, + description={this abbreviation style is like the + \abbrstyle{long-hyphen-short-hyphen} style but the \field{description} + field must be provided in the entry definition}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.17+}, + parent={abbreviationstyles} +} + +@abbrvstylecommand{glsxtrlonghyphennoshort, + name={\csfmt{gls\-xtr\-long\-hyphen\-noshort}}, + user1={\margm{label}\margm{long}\margm{insert}}, + description={used by the \qt{long-hyphen-noshort} styles + to format the \idx{firstuse} form. This checks if the inserted + material starts with a hyphen and makes the appropriate + modifications}, + topics={abbrstyle.long-hyphen-noshort-desc-noreg,abbrstyle.long-hyphen-noshort-noreg}, + note={\styfmt{glossaries-extra} v1.17+}, + category={command} +} + +@abbreviationstyle{abbrstyle.long-hyphen-noshort-desc-noreg, + name={\abbrstylefmt{long\dhyphen hyphen\dhyphen noshort\dhyphen desc\dhyphen noreg}}, + description={this abbreviation style is like the + \abbrstyle{long-hyphen-noshort-noreg} style but the \field{description} + field must be provided in the entry definition. This + style won't work with the \catattr{regular} attribute set, as the + regular form isn't flexible enough}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.17+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.long-hyphen-noshort-noreg, + name={\abbrstylefmt{long\dhyphen hyphen\dhyphen noshort\dhyphen noreg}}, + description={this abbreviation style is like \abbrstyle{long-noshort} + but is designed to work with the \catattr{markwords} attribute and + the \catattr{regular} attribute isn't set to \optfmt{true}. This + style won't work with the \catattr{regular} attribute set, as the + regular form isn't flexible enough}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.17+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.long-hyphen-postshort-hyphen, + name={\abbrstylefmt{long\dhyphen hyphen\dhyphen postshort\dhyphen hyphen}}, + description={this abbreviation style is like the + \abbrstyle{long-hyphen-short-hyphen} style but the insert and + parenthetical material are moved into the \idx{postlinkhook}}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.17+}, + parent={abbreviationstyles} +} + +@abbrvstylecommand{glsxtrlonghyphen, + name={\csfmt{gls\-xtr\-long\-hyphen}}, + user1={\margm{long}\margm{label}\margm{insert}}, + description={used by the \abbrstyle{long-hyphen-postshort-hyphen} abbreviation + to format the long form and check if the \meta{insert} starts with + a hyphen}, + topics={abbrstyle.long-hyphen-postshort-hyphen}, + note={\styfmt{glossaries-extra} v1.17+}, + category={command} +} + +@abbrvstylecommand{glsxtrposthyphenshort, + name={\csfmt{gls\-xtr\-post\-hyphen\-short}}, + user1={\margm{label}\margm{insert}}, + description={used by the \abbrstyle{long-hyphen-postshort-hyphen} + style in the \idx{postlinkhook}}, + topics={abbrstyle.long-hyphen-postshort-hyphen}, + note={\styfmt{glossaries-extra} v1.17+}, + category={command} +} + +@abbrvstylecommand{glsxtrposthyphensubsequent, + name={\csfmt{gls\-xtr\-post\-hyphen\-sub\-sequent}}, + user1={\margm{label}\margm{insert}}, + description={used by the \abbrstyle{long-hyphen-postshort-hyphen} abbreviation + in the \idx{postlinkhook} for subsequent use}, + topics={abbrstyle.long-hyphen-postshort-hyphen}, + note={\styfmt{glossaries-extra} v1.17+}, + category={command} +} + +@abbreviationstyle{abbrstyle.long-hyphen-postshort-hyphen-desc, + name={\abbrstylefmt{long\dhyphen hyphen\dhyphen postshort\dhyphen +hyphen\dhyphen desc}}, + description={this abbreviation style is like the + \abbrstyle{long-hyphen-postshort-hyphen} style but the \field{description} + field must be provided in the entry definition}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.17+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.short-hyphen-long-hyphen, + name={\abbrstylefmt{short\dhyphen hyphen\dhyphen long\dhyphen hyphen}}, + description={this abbreviation style is like \abbrstyle{short-long} + but is designed to work with the \catattr{markwords} attribute. If + the attribute is set, the style will check if the inserted + material (provided by the final optional argument of commands like + \cs{gls}) starts with a hyphen. If it does, the insert is added to + the parenthetical material}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.17+}, + parent={abbreviationstyles} +} + +@abbrvstylecommand{glsxtrshorthyphenlong, + name={\csfmt{gls\-xtr\-short\-hyphen\-long}}, + user1={\margm{label}\margm{short}\margm{long}\margm{insert}}, + description={used by the \abbrstyle{short-hyphen-long-hyphen} style + to format the full form}, + topics={abbrstyle.short-hyphen-long-hyphen,abbrstyle.short-hyphen-long-hyphen-desc}, + note={\styfmt{glossaries-extra} v1.17+}, + category={command} +} + +@abbreviationstyle{abbrstyle.short-hyphen-long-hyphen-desc, + name={\abbrstylefmt{short\dhyphen hyphen\dhyphen long\dhyphen +hyphen\dhyphen desc}}, + description={this abbreviation style is like the + \abbrstyle{short-hyphen-long-hyphen} style but the \field{description} + field must be provided in the entry definition}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.17+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.short-hyphen-postlong-hyphen, + name={\abbrstylefmt{short\dhyphen hyphen\dhyphen postlong\dhyphen hyphen}}, + description={this abbreviation style is like the + \abbrstyle{short-hyphen-long-hyphen} style but the insert and + parenthetical material are moved into the \idx{postlinkhook}}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.17+}, + parent={abbreviationstyles} +} + +@abbrvstylecommand{glsxtrshorthyphen, + name={\csfmt{gls\-xtr\-short\-hyphen}}, + user1={\margm{short}\margm{label}\margm{insert}}, + description={used by the \qt{postlong-hyphen} styles + to format the short form and check if \meta{insert} starts with a hyphen}, + topics={abbrstyle.short-hyphen-postlong-hyphen}, + note={\styfmt{glossaries-extra} v1.17+}, + category={command} +} + +@abbrvstylecommand{glsxtrposthyphenlong, + name={\csfmt{gls\-xtr\-post\-hyphen\-long}}, + user1={\margm{label}\margm{insert}}, + description={used by the \qt{postlong-hyphen} + styles in the \idx{postlinkhook}}, + topics={abbrstyle.short-hyphen-postlong-hyphen}, + note={\styfmt{glossaries-extra} v1.17+}, + category={command} +} + +@abbreviationstyle{abbrstyle.short-hyphen-postlong-hyphen-desc, + name={\abbrstylefmt{short\dhyphen hyphen\dhyphen postlong\dhyphen +hyphen\dhyphen desc}}, + description={this abbreviation style is like the + \abbrstyle{short-hyphen-postlong-hyphen} style but the \field{description} + field must be provided in the entry definition}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.17+}, + parent={abbreviationstyles} +} + +@abbreviationstyle{abbrstyle.long-only-short-only, + name={\abbrstylefmt{long\dhyphen only\dhyphen short\dhyphen only}}, + description={this abbreviation style only displays the long form + on \idx{firstuse} and only the short form on subsequent use. The + inline full form shows the long form followed by the short form in + parentheses}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.17+}, + parent={abbreviationstyles} +} + +@abbrvstylecommand{glsabbrvonlyfont, + name={\csfmt{gls\-abbrv\-only\-font}}, + user1={\margm{text}}, + description={used with \qt{only} abbreviation styles to format the +short form. The default definition just uses \cs{glsabbrvdefaultfont}}, + topics={abbrstyle.long-only-short-only,abbrstyle.long-only-short-only-desc}, + note={\styfmt{glossaries-extra} v1.17+}, + category={command} +} + +@abbrvstylecommand{glsfirstabbrvonlyfont, + name={\csfmt{gls\-first\-abbrv\-only\-font}}, + user1={\margm{text}}, + description={used with \qt{only} abbreviation styles to format the +short form on \idx{firstuse}. The default definition just uses +\cs{glsabbrvonlyfont}}, + topics={abbrstyle.long-only-short-only,abbrstyle.long-only-short-only-desc}, + note={\styfmt{glossaries-extra} v1.17+}, + category={command} +} + +@abbrvstylecommand{glslongonlyfont, + name={\csfmt{gls\-long\-only\-font}}, + user1={\margm{text}}, + description={used with \qt{only} abbreviation styles to format the +long form. The default definition just uses \cs{glslongdefaultfont}}, + topics={abbrstyle.long-only-short-only,abbrstyle.long-only-short-only-desc}, + note={\styfmt{glossaries-extra} v1.17+}, + category={command} +} + +@abbrvstylecommand{glsfirstlongonlyfont, + name={\csfmt{gls\-first\-long\-only\-font}}, + user1={\margm{text}}, + description={used with \qt{only} abbreviation styles to format the +long form on \idx{firstuse}. The default definition just uses +\cs{glslongonlyfont}}, + topics={abbrstyle.long-only-short-only,abbrstyle.long-only-short-only-desc}, + note={\styfmt{glossaries-extra} v1.17+}, + category={command} +} + +@abbrvstylecommand{glsxtronlysuffix, + name={\csfmt{gls\-xtr\-only\-suffix}}, + description={the suffix used to construct the plural for + the short form of abbreviations with the \qt{only} styles. + The default definition just uses \cs{glsxtrabbrvpluralsuffix}}, + topics={abbrstyle.long-only-short-only}, + note={\styfmt{glossaries-extra} v1.17+}, + category={command} +} + +@abbrvstylecommand{glsxtronlyname, + name={\csfmt{gls\-xtr\-only\-name}}, + description={hook for the \abbrstyle{long-only-short-only} style + that expands to the value that the \field{name} field is assigned + to when the abbreviation is defined with \cs{newabbreviation} + (defaults to the short form)}, + topics={abbrstyle.long-only-short-only}, + note={\styfmt{glossaries-extra} v1.25+}, + category={command} +} + +@abbrvstylecommand{glsxtronlydescname, + name={\csfmt{gls\-xtr\-only\-desc\-name}}, + description={hook for the \abbrstyle{long-only-short-only-desc} style + that expands to the value that the \field{name} field is assigned + to when the abbreviation is defined with \cs{newabbreviation} + (defaults to the long form)}, + topics={abbrstyle.long-only-short-only-desc}, + note={\styfmt{glossaries-extra} v1.17+}, + category={command} +} + +@abbreviationstyle{abbrstyle.long-only-short-only-desc, + name={\abbrstylefmt{long\dhyphen only\dhyphen short\dhyphen only\dhyphen desc}}, + description={this abbreviation style is like the + \abbrstyle{long-only-short-only} style but the \field{description} + field must be provided in the entry definition}, + category={abbreviationstyle}, + note={\styfmt{glossaries-extra} v1.17+}, + parent={abbreviationstyles} +} + +@topic{glossarystyle, + name={glossary styles}, + text={glossary style}, + description={glossary styles are set using \ics{setglossarystyle} + or with the \styopt{style} package option or the + \printglossopt{style} option in \cs{printunsrtglossary}. + There are a number of styles provided in the supplementary packages. See the +\href{https://www.dickimaw-books.com/gallery/glossaries-styles/}{\styfmt{glossaries} + gallery of predefined styles}~\cite{glossarystylesgallery} for + samples of each style} +} + +@glossarystyle{glostyle.inline, + name={\glostylefmt{inline}}, + description={this style is designed for inline glossaries. The + \field{symbol}, \idx{locationlist} and child \field{name} are omitted + by default, but associated style commands may be redefined to + change this}, + category={glossarystyle}, + note={\styfmt{glossary-inline} v3.03+}, + parent={glossarystyle} +} + +@glostylecommand{glsinlinedopostchild, + name={\csfmt{gls\-in\-line\-do\-post\-child}}, + description={group headings aren't supported by default, but if + they are required, this command should be added to start of the definition + of \cs{glsgroupheading} in case a heading follows a child entry}, + category={command}, + note={\styfmt{glossary-inline} v3.03+}, + topics={glostyle.inline} +} + +@glostylecommand{glsinlineseparator, + name={\csfmt{gls\-in\-line\-separator}}, + description={separator between entries}, + category={command}, + note={\styfmt{glossary-inline} v3.03+}, + topics={glostyle.inline} +} + +@glostylecommand{glsinlinesubseparator, + name={\csfmt{gls\-in\-line\-sub\-separator}}, + description={separator between sub-entries}, + category={command}, + note={\styfmt{glossary-inline} v3.03+}, + topics={glostyle.inline} +} + +@glostylecommand{glsinlineparentchildseparator, + name={\csfmt{gls\-in\-line\-parent\-child\-separator}}, + description={separator between parent and child entries}, + category={command}, + note={\styfmt{glossary-inline} v3.03+}, + topics={glostyle.inline} +} + +@glostylecommand{glsinlinepostchild, + name={\csfmt{gls\-in\-line\-post\-child}}, + description={hook between child and next entry}, + category={command}, + note={\styfmt{glossary-inline} v3.03+}, + topics={glostyle.inline} +} + +@glostylecommand{glspostinline, + name={\csfmt{gls\-post-in\-line}}, + description={glossary terminator}, + category={command}, + note={\styfmt{glossary-inline} v3.03+}, + topics={glostyle.inline} +} + +@glostylecommand{glsinlinenameformat, + name={\csfmt{gls\-in\-line\-name\-format}}, + user1={\margm{label}\margm{name}}, + description={format's the entry's name including target, if + supported}, + category={command}, + note={\styfmt{glossary-inline} v3.03+}, + topics={glostyle.inline} +} + +@glostylecommand{glsinlinedescformat, + name={\csfmt{gls\-in\-line\-desc\-format}}, + user1={\margm{description}\margm{symbol}\margm{location list}}, + description={format's the entry's description, symbol and location + list. This ignores the symbol and location by default}, + category={command}, + note={\styfmt{glossary-inline} v3.03+}, + topics={glostyle.inline} +} + +@glossarystyle{glostyle.indexgroup, + name={\glostylefmt{indexgroup}}, + description={}, + category={glossarystyle}, + note={\styfmt{glossary-tree}}, + parent={glossarystyle} +} + +@glossarystyle{glostyle.mcolindexgroup, + name={\glostylefmt{mcolindexgroup}}, + category={glossarystyle}, + note={\styfmt{glossary-mcols}}, + parent={glossarystyle} +} + +@glossarystyle{glostyle.indexhypergroup, + name={\glostylefmt{indexhypergroup}}, + category={glossarystyle}, + note={\styfmt{glossary-tree}}, + parent={glossarystyle} +} + +@glossarystyle{glostyle.tree, + name={\glostylefmt{tree}}, + category={glossarystyle}, + note={\styfmt{glossary-tree}}, + parent={glossarystyle} +} + +@glossarystyle{glostyle.treegroup, + name={\glostylefmt{treegroup}}, + category={glossarystyle}, + note={\styfmt{glossary-tree}}, + parent={glossarystyle} +} + +@glossarystyle{glostyle.treenoname, + name={\glostylefmt{treenoname}}, + category={glossarystyle}, + note={\styfmt{glossary-tree}}, + parent={glossarystyle} +} + +@glossarystyle{glostyle.treenonamegroup, + name={\glostylefmt{treenonamegroup}}, + category={glossarystyle}, + note={\styfmt{glossary-tree}}, + parent={glossarystyle} +} + +@glossarystyle{glostyle.alttree, + name={\glostylefmt{alttree}}, + category={glossarystyle}, + note={\styfmt{glossary-tree}}, + parent={glossarystyle} +} + +@glossarystyle{glostyle.alttreegroup, + name={\glostylefmt{alttreegroup}}, + category={glossarystyle}, + note={\styfmt{glossary-tree}}, + parent={glossarystyle} +} + +@glossarystyle{glostyle.mcolalttree, + name={\glostylefmt{mcolalttree}}, + category={glossarystyle}, + note={\styfmt{glossary-mcols}}, + parent={glossarystyle} +} + +@glossarystyle{glostyle.mcolalttreegroup, + name={\glostylefmt{mcolalttreegroup}}, + category={glossarystyle}, + note={\styfmt{glossary-mcols}}, + parent={glossarystyle} +} + +@glossarystyle{glostyle.topic, + name={\glostylefmt{topic}}, + category={glossarystyle}, + note={\styfmt{glossary-topic} v1.40+}, + parent={glossarystyle} +} + +@glossarystyle{glostyle.topicmcols, + name={\glostylefmt{topicmcols}}, + category={glossarystyle}, + note={\styfmt{glossary-topic} v1.40+}, + parent={glossarystyle} +} + +@glossarystyle{glostyle.list, + name={\glostylefmt{list}}, + category={glossarystyle}, + note={\styfmt{glossary-list}}, + parent={glossarystyle} +} + +@glossarystyle{glostyle.altlist, + name={\glostylefmt{altlist}}, + category={glossarystyle}, + note={\styfmt{glossary-list}}, + parent={glossarystyle} +} + +@glossarystyle{glostyle.altlistgroup, + name={\glostylefmt{altlistgroup}}, + category={glossarystyle}, + note={\styfmt{glossary-list}}, + parent={glossarystyle} +} + +@glossarystyle{glostyle.index, + name={\glostylefmt{index}}, + category={glossarystyle}, + note={\styfmt{glossary-tree}}, + parent={glossarystyle} +} + +@glossarystyle{glostyle.bookindex, + name={\glostylefmt{bookindex}}, + category={glossarystyle}, + note={\styfmt{glossary-bookindex}}, + parent={glossarystyle} +} + +@glossarystyle{glostyle.long, + name={\glostylefmt{long}}, + category={glossarystyle}, + note={\styfmt{glossary-long}}, + parent={glossarystyle} +} + +@glossarystyle{glostyle.super, + name={\glostylefmt{super}}, + category={glossarystyle}, + note={\styfmt{glossary-long}}, + parent={glossarystyle} +} + +@glossarystyle{glostyle.long3col, + name={\glostylefmt{long3col}}, + category={glossarystyle}, + note={\styfmt{glossary-long}}, + parent={glossarystyle} +} + +@glossarystyle{glostyle.long3col-booktabs, + name={\glostylefmt{long3col\dhyphen booktabs}}, + category={glossarystyle}, + note={\styfmt{glossary-longbooktabs}}, + parent={glossarystyle} +} + +@index{categoryattribute, + name={category attributes}, + text={category attribute} +} + +@index{attribute, + name = {attributes}, + text = {attribute}, + alias = {categoryattribute} +} + +@categoryattribute{catattr.recordcount, + name={\catattrfmt{record\-count}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@categoryattribute{catattr.glossname, + name={\catattrfmt{gloss\-name}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@categoryattribute{catattr.glossnamefont, + name={\catattrfmt{gloss\-name\-font}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@categoryattribute{catattr.glossdesc, + name={\catattrfmt{gloss\-desc}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@categoryattribute{catattr.glossdescfont, + name={\catattrfmt{gloss\-desc\-font}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@categoryattribute{catattr.textformat, + name={\catattrfmt{text\-format}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@categoryattribute{catattr.headuc, + name={\catattrfmt{headuc}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@categoryattribute{catattr.aposplural, + name={\catattrfmt{apos\-plural}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@categoryattribute{catattr.accessaposplural, + name={\catattrfmt{access\-apos\-plural}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@categoryattribute{catattr.noshortplural, + name={\catattrfmt{no\-short\-plural}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@categoryattribute{catattr.accessnoshortplural, + name={\catattrfmt{access\-no\-short\-plural}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@categoryattribute{catattr.nameshortaccess, + name={\catattrfmt{name\-short\-access}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@categoryattribute{catattr.firstshortaccess, + name={\catattrfmt{first\-short\-access}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@categoryattribute{catattr.textshortaccess, + name={\catattrfmt{text\-short\-access}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@categoryattribute{catattr.markwords, + name={\catattrfmt{mark\-words}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@categoryattribute{catattr.markshortwords, + name={\catattrfmt{mark\-short\-words}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@categoryattribute{catattr.targeturl, + name={\catattrfmt{target\-url}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@categoryattribute{catattr.targetname, + name={\catattrfmt{target\-name}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@categoryattribute{catattr.externallocation, + name={\catattrfmt{external\-location}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@categoryattribute{catattr.discardperiod, + name={\catattrfmt{discard\-period}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@categoryattribute{catattr.pluraldiscardperiod, + name={\catattrfmt{plural\-discard\-period}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@categoryattribute{catattr.retainfirstuseperiod, + name={\catattrfmt{retain\-first\-use\-period}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@categoryattribute{catattr.insertdots, + name={\catattrfmt{insert\-dots}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@categoryattribute{catattr.accessinsertdots, + name={\catattrfmt{access\-insert\-dots}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@categoryattribute{catattr.tagging, + name={\catattrfmt{tagging}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@categoryattribute{catattr.nohyperfirst, + name={\catattrfmt{no\-hyper\-first}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@categoryattribute{catattr.nohyper, + name={\catattrfmt{no\-hyper}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@categoryattribute{catattr.entrycount, + name={\catattrfmt{entry\-count}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@categoryattribute{catattr.hyperoutside, + name={\catattrfmt{hyper\-outside}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@categoryattribute{catattr.regular, + name={\catattrfmt{regular}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@categoryattribute{catattr.wrgloss, + name={\catattrfmt{wrgloss}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@counter{ctr.equation, + name={\counterfmt{equation}}, + category={counter} +} + +@counter{ctr.page, + name={\counterfmt{page}}, + category={counter} +} + +@counter{ctr.section, + name={\counterfmt{section}}, + category={counter} +} + +@counter{ctr.chapter, + name={\counterfmt{chapter}}, + category={counter} +} + +@counter{ctr.wrglossary, + name={\counterfmt{wrglossary}}, + category={counter} +} + +@counter{ctr.glossaryentry, + name={\counterfmt{glossaryentry}}, + category={counter} +} + +@counter{ctr.glossarysubentry, + name={\counterfmt{glossarysubentry}}, + category={counter} +} + +@index{labelprefixes, + name={label prefixes}, + text={label prefix}, + plural={label prefixes} +} + +@labelprefix{idprefix.dual, + name={\idprefixfmt{dual}}, + category={idprefix}, + parent={labelprefixes} +} + +@labelprefix{idprefix.tertiary, + name={\idprefixfmt{tertiary}}, + category={idprefix}, + parent={labelprefixes} +} + +@labelprefix{idprefix.extn, + name={\idprefixfmt{ext\meta{n}}}, + category={idprefix}, + parent={labelprefixes} +} + +@index{packageoptions, + name={package options}, + text={package option} +} + +@packageoption{styopt.record, + name={\styoptfmt{record}}, + user1={\meta{value}}, + description={unless the value is \styoptfmt{off}, this option sets + up \styfmt{glossaries-extra} for use with \bibgls: \styoptfmt{only} + (assumed if no \meta{value} supplied) indexing is performed by + \bibgls; \styoptfmt{nameref} (\sty{glossaries-extra} v1.37+) + like \styoptfmt{only} but includes extra information in the records; + \styoptfmt{alsoindex} (hybrid method) \bibgls\ is used to provide + the entry definitions but \idx{makeindex} or \idx{xindy} is used + for the indexing}, + package={glossaries-extra}, + category={packageoption}, + parent={packageoptions} +} + +@packageoption{styopt.accsupp, + name={\styoptfmt{accsupp}}, + description={load the \sty{glossaries-accsupp} package to provide + accessibility support}, + package={glossaries,glossaries-extra}, + category={packageoption}, + parent={packageoptions} +} + +@packageoption{styopt.abbreviations, + name={\styoptfmt{abbreviations}}, + description={creates the \code{abbreviations} glossary}, + package={glossaries-extra}, + category={packageoption}, + parent={packageoptions} +} + +@packageoption{styopt.symbols, + name={\styoptfmt{symbols}}, + package={glossaries,glossaries-extra}, + description={defines the \code{symbols} glossary; with + \styfmt{glossaries-extra} additionally defines + \csref{glsxtrnewsymbol}}, + category={packageoption}, + parent={packageoptions} +} + +@packageoption{styopt.numbers, + name={\styoptfmt{numbers}}, + package={glossaries,glossaries-extra}, + description={defines the \code{numbers} glossary; with + \styfmt{glossaries-extra} additionally defines + \csref{glsxtrnewnumber}}, + category={packageoption}, + parent={packageoptions} +} + +@packageoption{styopt.undefaction, + name={\styoptfmt{undefaction}}, + user1={\meta{value}}, + description={indicates what to do if an undefined entry is + referenced: \styoptfmt{warn} (generate a warning and show ?? in + the text, default with \styopt{record}), \styoptfmt{error} + (generate an error)}, + package={glossaries-extra}, + category={packageoption}, + parent={packageoptions} +} + +@packageoption{styopt.indexcrossrefs, + name={\styoptfmt{indexcrossrefs}}, + user1={\meta{boolean}}, + package={glossaries-extra}, + category={packageoption}, + parent={packageoptions}, + description={if true, at the end of + the document automatically index cross-referenced entries that + haven't been marked as used}, + note={not relevant with \bibgls} +} + +@packageoption{styopt.autoseeindex, + name={\styoptfmt{autoseeindex}}, + user1={\meta{boolean}}, + package={glossaries-extra}, + category={packageoption}, + parent={packageoptions}, + note={not relevant with \bibgls}, + description={if true, the \field{see} and \field{seealso} keys + automatically indexes the cross-referenced term} +} + +@packageoption{styopt.nopostdot, + name={\styoptfmt{nopostdot}}, + user1={\meta{boolean}}, + package={glossaries,glossaries-extra}, + description={if true, suppresses the automatic post-description + punctuation. With \styfmt{glossaries-extra} you can also use + \styopt[none]{postpunc} instead of \styopt[true]{nopostdot} and + \styopt{postdot} or \styopt[dot]{postpunc} instead of + \styopt[false]{nopostdot}}, + category={packageoption}, + parent={packageoptions} +} + +@packageoption{styopt.postdot, + name={\styoptfmt{postdot}}, + package={glossaries-extra}, + description={equivalent to \styopt[dot]{postpunc}}, + category={packageoption}, + parent={packageoptions} +} + +@packageoption{styopt.postpunc, + name={\styoptfmt{postpunc}}, + user1={\meta{value}}, + package={glossaries-extra}, + category={packageoption}, + parent={packageoptions}, + description={controls the automatic post-description punctuation; + the value may be one of: \styoptfmt{none} (not required, + the \field{description} or glossary style already supplies the + terminating punctuation), \styoptfmt{comma} (use a comma), + \styoptfmt{dot} (use a \idx{full-stop} with the space factor + adjusted), \meta{punctuation} (use \meta{punctuation})} +} + +@packageoption{styopt.indexcounter, + name={\styoptfmt{index\-counter}}, + description={creates the \counter{wrglossary} counter, which is + incremented every time an entry is indexed with that counter, and sets + that as the default location counter}, + package={glossaries-extra}, + category={packageoption}, + parent={packageoptions} +} + +@packageoption{styopt.docdef, + name={\styoptfmt{docdef}}, + user1={\meta{value}}, + package={glossaries-extra}, + category={packageoption}, + parent={packageoptions}, + note={not relevant with \bibgls}, + description={determines whether + entries can be defined in the \envfmt{document} environment; the + \meta{value} may be one of: \styoptfmt{false} (entries must be + defined in the preamble), \styoptfmt{true} (entries may be defined + in the \envfmt{document} environment), \styoptfmt{restricted} + (entries may only be defined in the \envfmt{document} environment + if the definition comes before all glossaries and before any + reference to the entry)} +} + +@packageoption{styopt.nomissingglstext, + name={\styoptfmt{nomissingglstext}}, + user1={\meta{boolean}}, + package={glossaries-extra}, + category={packageoption}, + parent={packageoptions}, + note={not relevant with \bibgls}, + description={if true, suppress the + warning text that appears in the document with \cs{printglossary} + if the associated external file doesn't exist} +} + +@packageoption{styopt.stylemods, + name={\styoptfmt{stylemods}}, + user1={\meta{value}}, + description={load the \sty{glossaries-extra-stylemods} package with the + supplied options (which should be a list of suffix parts + identifying glossary style packages \styfmt{glossary-}\meta{suffix}); + there are two keyword values: \styoptfmt{default} + (equivalent to omitting \meta{value}) and \styoptfmt{all}, which + loads all predefined styles}, + package={glossaries-extra}, + category={packageoption}, + parent={packageoptions} +} + +@packageoption{styopt.nowarn, + name={\styoptfmt{nowarn}}, + package={glossaries}, + category={packageoption}, + parent={packageoptions}, + description={suppresses all \styfmt{glossaries}-related warnings} +} + +@packageoption{styopt.nolangwarn, + name={\styoptfmt{nolangwarn}}, + package={glossaries}, + category={packageoption}, + parent={packageoptions}, + description={suppresses warnings generated by missing language modules} +} + +@packageoption{styopt.noredefwarn, + name={\styoptfmt{noredefwarn}}, + package={glossaries}, + category={packageoption}, + parent={packageoptions}, + description={suppresses warnings if overriding glossary commands + provided by another class or package} +} + +@packageoption{styopt.debug, + name={\styoptfmt{debug}}, + user1={\meta{value}}, + package={glossaries,glossaries-extra}, + category={packageoption}, + parent={packageoptions}, + description={add debugging information; allowed values: + \styoptfmt{false} (default), \styoptfmt{true} (info added to + transcript), \styoptfmt{showtargets} (info added to transcript + and show target name in the document for glossary-related + hyperlinks), \styoptfmt{showwrgloss}\extstyopt\ show mark in + document where indexing occurs and \styoptfmt{all}\extstyopt\ + (implement both \styoptfmt{showtargets} and + \styoptfmt{showwrgloss})} +} + +@packageoption{styopt.seenoindex, + name={\styoptfmt{seenoindex}}, + user1={\meta{value}}, + package={glossaries}, + category={packageoption}, + parent={packageoptions}, + note={not relevant with \bibgls}, + description={determines whether the + \field{see} key automatically indexes the entry using \cs{glsadd}; + allowed values: \styoptfmt{error} (attempts indexing but triggers + an error if used before \cs{cs.makeglossaries}); \styoptfmt{warn} + (attempts indexing but triggers a warning if used before + \cs{cs.makeglossaries}); \styoptfmt{ignore} (attempts indexing but + does nothing if used before \cs{cs.makeglossaries})} +} + +@packageoption{styopt.nomain, + name={\styoptfmt{nomain}}, + package={glossaries}, + category={packageoption}, + parent={packageoptions}, + description={suppresses the creation of the default \code{main} + glossary. If used an alternative glossary must be created} +} + +@packageoption{styopt.sanitizesort, + name={\styoptfmt{sanitizesort}}, + user1={\meta{boolean}}, + package={glossaries}, + category={packageoption}, + parent={packageoptions}, + note={not relevant with \bibgls}, + description={determines whether or not + to sanitize the \field{sort} key (not relevant with \bibgls)} +} + +@packageoption{styopt.savewrites, + name={\styoptfmt{savewrites}}, + user1={\meta{boolean}}, + package={glossaries}, + category={packageoption}, + parent={packageoptions}, + note={not relevant with \bibgls}, + description={if true, indexing + information is stored in token registers that are only written at + the end of the document to save creating a write register per + glossary indexing file} +} + +@packageoption{styopt.translate, + name={\styoptfmt{translate}}, + user1={\meta{value}}, + package={glossaries}, + category={packageoption}, + parent={packageoptions}, + description={determines the multilingual support provided by + \styfmt{glossaries}; allowed values: \styoptfmt{true} (default + with just base \styfmt{glossaries}; if + \styfmt{babel} has been loaded and \styfmt{translator} is + installed, use \styfmt{translator} interface), \styoptfmt{false} + (don't provide translations), \styoptfmt{babel} (default with + \styfmt{glossaries-extra}; don't load the + \styfmt{translator} package, just load \styfmt{glossaries-babel})} +} + +@packageoption{styopt.notranslate, + name={\styoptfmt{notranslate}}, + package={glossaries}, + category={packageoption}, + parent={packageoptions}, + description={equivalent to \styopt[false]{translate}} +} + +@packageoption{styopt.nohypertypes, + name={\styoptfmt{nohypertypes}}, + user1={\meta{list}}, + package={glossaries}, + category={packageoption}, + parent={packageoptions}, + description={suppress hyperlinks for the listed glossary types} +} + +@packageoption{styopt.hyperfirst, + name={\styoptfmt{hyperfirst}}, + user1={\meta{boolean}}, + package={glossaries}, + category={packageoption}, + parent={packageoptions}, + description={if false, terms on first use don't have hyperlinks + unless explicitly set (with \styfmt{glossaries-extra}, the + \catattr{nohyperfirst} category attribute can selectively apply this)} +} + +@packageoption{styopt.indexonlyfirst, + name={\styoptfmt{indexonlyfirst}}, + user1={\meta{boolean}}, + package={glossaries}, + category={packageoption}, + parent={packageoptions}, + description={if true, only performs indexing on first use} +} + +@packageoption{styopt.savenumberlist, + name={\styoptfmt{savenumberlist}}, + user1={\meta{boolean}}, + package={glossaries}, + category={packageoption}, + parent={packageoptions}, + description={if true, stores the number list for each entry (with + \bibgls\ use the \csopt{save-locations} resource option instead)} +} + +@packageoption{styopt.toc, + name={\styoptfmt{toc}}, + user1={\meta{boolean}}, + package={glossaries}, + category={packageoption}, + parent={packageoptions}, + description={if true (default for \styfmt{glossaries-extra}), + automatically add each glossary to the \glsxtrlong{toc}} +} + +@packageoption{styopt.numberline, + name={\styoptfmt{numberline}}, + user1={\meta{boolean}}, + package={glossaries}, + category={packageoption}, + parent={packageoptions}, + description={when used with \styopt[true]{toc}, this will add + \code{\csfmt{numberline}\marg{}} to the start of the \idx{toc} entry} +} + +@packageoption{styopt.section, + name={\styoptfmt{section}}, + user1={\meta{value}}, + package={glossaries}, + category={packageoption}, + parent={packageoptions}, + description={indicates the sectional unit to use for the glossary + heading (the value should be the name of the section command without + the leading backslash, for example \styopt[subsection]{section}). + If no value is supplied then \styopt[section]{section} is assumed. + If this option is omitted, then the default is either + \styopt[chapter]{section} or \styopt[section]{section}, depending + on whether or not \cs{chapter} has been defined. The starred or + unstarred version is determined by \styopt{numberedsection}} +} + +@packageoption{styopt.ucmark, + name={\styoptfmt{ucmark}}, + user1={\meta{boolean}}, + package={glossaries}, + category={packageoption}, + parent={packageoptions}, + description={if true, converts the glossary mark (used in page + headings) to \idx{uppercase} with \cs{MakeTextUppercase}} +} + +@packageoption{styopt.numberedsection, + name={\styoptfmt{numberedsection}}, + user1={\meta{value}}, + package={glossaries}, + category={packageoption}, + parent={packageoptions}, + description={determines whether to use numbered or unnumbered + section units, and whether or not to automatically add + \cs{label}; the value may be one of: \styoptfmt{false} (default, no + numbering and no label), \styoptfmt{nolabel} (numbered but no + label), \styoptfmt{autolabel} (numbered with automatic label), + \styoptfmt{nameref} (unnumbered but labelled). If no value is + given \styoptfmt{nolabel} is assumed} +} + +@packageoption{styopt.entrycounter, + name={\styoptfmt{entrycounter}}, + user1={\meta{boolean}}, + package={glossaries}, + category={packageoption}, + parent={packageoptions}, + description={if true, creates the \counter{glossaryentry} counter + and each main (level 0) glossary entry will be + numbered (which can be referenced with \cs{glsrefentry} or + \cs{glsxtrpageref})} +} + +@packageoption{styopt.counterwithin, + name={\styoptfmt{counterwithin}}, + user1={\meta{counter name}}, + package={glossaries}, + category={packageoption}, + parent={packageoptions}, + description={automatically sets \styopt[true]{entrycounter} and + indicates the master counter for \counter{glossaryentry}} +} + +@packageoption{styopt.subentrycounter, + name={\styoptfmt{subentrycounter}}, + user1={\meta{boolean}}, + package={glossaries}, + category={packageoption}, + parent={packageoptions}, + description={if true, creates the \counter{glossarysubentry} counter + and each level~1 glossary entry will be + numbered (which can be referenced with \cs{glsrefentry} or + \cs{glsxtrpageref}); this option and associated counter are + independent of \styopt{entrycounter} and \counter{glossaryentry}} +} + +@packageoption{styopt.style, + name={\styoptfmt{style}}, + user1={\meta{name}}, + package={glossaries}, + description={sets the default glossary style to \meta{name}}, + category={packageoption}, + parent={packageoptions} +} + +@packageoption{styopt.nolong, + name={\styoptfmt{nolong}}, + package={glossaries}, + description={prevents the \sty{glossary-long} package (which + provides the \glostyle{long} styles) from being + automatically loaded}, + category={packageoption}, + parent={packageoptions} +} + +@packageoption{styopt.nosuper, + name={\styoptfmt{nosuper}}, + package={glossaries}, + description={prevents the \sty{glossary-super} package (which + provides the \glostyle{super} styles) from being + automatically loaded}, + category={packageoption}, + parent={packageoptions} +} + +@packageoption{styopt.nolist, + name={\styoptfmt{nolist}}, + package={glossaries}, + description={prevents the \sty{glossary-list} package (which + provides the \glostyle{list} styles) from being + automatically loaded}, + category={packageoption}, + parent={packageoptions} +} + +@packageoption{styopt.notree, + name={\styoptfmt{notree}}, + package={glossaries}, + category={packageoption}, + parent={packageoptions}, + description={prevents the \sty{glossary-tree} package (which + provides the \glostyle{tree} styles) from being + automatically loaded} +} + +@packageoption{styopt.nostyles, + name={\styoptfmt{nostyles}}, + package={glossaries}, + description={prevents all the default styles from being loaded. If + this option is used a style must be defined in the document or a package + providing a style needs to be loaded (either + through \styopt{stylemods} or with \ics{usepackage})}, + category={packageoption}, + parent={packageoptions} +} + +@packageoption{styopt.esclocations, + name={\styoptfmt{esclocations}}, + user1={\meta{boolean}}, + package={glossaries}, + category={packageoption}, + parent={packageoptions}, + note={not relevant with \bibgls}, + description={if true, + \styfmt{glossaries} tries to escape special characters from the + locations} +} + +@packageoption{styopt.nonumberlist, + name={\styoptfmt{nonumberlist}}, + package={glossaries}, + description={suppresses the location lists from being + displayed in the glossary lists (the package + option isn't boolean, but the option of the same name for + \cs{printglossary}, \cs{printunsrtglossary} and + \cs{printnoidxglossary} is boolean); with \bibgls\ you can use + \csopt[false]{save-locations} instead}, + category={packageoption}, + parent={packageoptions} +} + +@packageoption{styopt.seeautonumberlist, + name={\styoptfmt{seeautonumberlist}}, + package={glossaries}, + category={packageoption}, + parent={packageoptions}, + note={not relevant with \bibgls}, + description={if \styopt{nonumberlist} + is used, this allows the \field{see} key to override the setting + for the associated entry} +} + +@packageoption{styopt.counter, + name={\styoptfmt{counter}}, + user1={\meta{value}}, + description={sets the default location counter to \meta{value} + (which must be the name of a counter). May be overridden on + an individual basis using the + \glsopt{counter} option in commands like \cs{gls} and \cs{glsadd}}, + package={glossaries}, + category={packageoption}, + parent={packageoptions} +} + +@packageoption{styopt.nogroupskip, + name={\styoptfmt{nogroupskip}}, + user1={\meta{boolean}}, + description={if true, suppresses the visual separation between + letter groups in glossary styles that support this option}, + package={glossaries}, + category={packageoption}, + parent={packageoptions} +} + +@packageoption{styopt.sort, + name={\styoptfmt{sort}}, + user1={\meta{value}}, + note={not relevant with \bibgls, use the \csopt{sort} + resource option instead}, + description={indicates how to assign the \field{sort} key if not + explicitly set, the value may be one of: \styoptfmt{none} (don't + automatically assign the \field{sort} field), \styoptfmt{standard} + (obtain the \field{sort} value from the \field{name} field), + \styoptfmt{def} (assign the \field{sort} field to a numerical value + that represents the order of definition), \styoptfmt{user} + (assign the \field{sort} field to a numerical value that + represents the order of first use)}, + package={glossaries}, + category={packageoption}, + parent={packageoptions} +} + +@packageoption{styopt.order, + name={\styoptfmt{order}}, + user1={\meta{value}}, + note={not relevant with \bibgls, use the \csopt{break-at} + resource option instead}, + description={sets whether to use word or letter ordering}, + package={glossaries}, + category={packageoption}, + parent={packageoptions} +} + +@packageoption{styopt.makeindex, + name={\styoptfmt{makeindex}}, + note={not relevant with \bibgls}, + description={write the indexing + information using \idx{makeindex}'s format}, + package={glossaries}, + category={packageoption}, + parent={packageoptions} +} + +@packageoption{styopt.xindy, + name={\styoptfmt{xindy}}, + user1={\meta{settings}}, + note={not relevant with \bibgls}, + description={write the indexing + information using \idx{xindy}'s format where the optional + \meta{settings} may supply the language and code page and whether + or not to define the default number group}, + package={glossaries}, + category={packageoption}, + parent={packageoptions} +} + +@packageoption{styopt.xindygloss, + name={\styoptfmt{xindygloss}}, + package={glossaries}, + category={packageoption}, + parent={packageoptions}, + note={not relevant with \bibgls}, + description={equivalent to \styopt[\empty]{xindy}} +} + +@packageoption{styopt.xindynoglsnumbers, + name={\styoptfmt{xindynoglsnumbers}}, + package={glossaries}, + category={packageoption}, + parent={packageoptions}, + note={not relevant with \bibgls}, + description={equivalent to \styopt[glsnumbers=false]{xindy}} +} + +@packageoption{styopt.automake, + name={\styoptfmt{automake}}, + user1={\meta{boolean}}, + description={if true, tries to use \TeX's shell escape to + automatically run the required indexing application (may not + be permitted by \TeX's security settings)}, + package={glossaries}, + category={packageoption}, + parent={packageoptions} +} + +@packageoption{styopt.acronym, + name={\styoptfmt{acronym}}, + user1={\meta{boolean}}, + package={glossaries}, + category={packageoption}, + parent={packageoptions}, + description={if true, creates a new glossary with the label \code{acronym}} +} + +@packageoption{styopt.acronyms, + name={\styoptfmt{acronyms}}, + package={glossaries}, + category={packageoption}, + parent={packageoptions}, + description={equivalent to \styopt[true]{acronym}} +} + +@packageoption{styopt.acronymlists, + name={\styoptfmt{acronymlists}}, + user1={\meta{list}}, + package={glossaries}, + category={packageoption}, + parent={packageoptions}, + description={identifies the glossaries that are lists of acronyms + (don't use with \sty{glossaries-extra})} +} + +@packageoption{styopt.shortcuts, + name={\styoptfmt{shortcuts}}, + package={glossaries,glossaries-extra}, + user1={\meta{value}}, + description={sets up short cut commands; the value may be one of + \styoptfmt{false} (default), \styoptfmt{true} (assumed if no value + supplied, implements + \styopt[ac]{shortcuts}, \styopt[abbreviations]{shortcuts} and + \styopt[other]{shortcuts}), \styoptfmt{acronyms}\extstyopt\ + (equivalent to base \styopt[true]{shortcuts}, synonym + \styoptfmt{acro}), \styoptfmt{ac}\extstyopt\ (provides \cs{ac} + shortcuts that use \styfmt{glossaries-extra}'s new abbreviation + commands), \styoptfmt{abbreviations}\extstyopt\ (provides \cs{ab} + shortcuts), \styoptfmt{other}\extstyopt\ (provides other shortcut + commands), \styoptfmt{all}\extstyopt\ (synonym for + \styopt[true]{shortcuts}) and \styoptfmt{none}\extstyopt\ (synonym + for \styopt[false]{shortcuts})}, + category={packageoption}, + parent={packageoptions} +} + +@packageoption{styopt.index, + name={\styoptfmt{index}}, + package={glossaries}, + description={defines the \code{index} glossary and \csref{newterm}}, + category={packageoption}, + parent={packageoptions} +} + +@index{fields, + name={fields}, + text={field} +} + +@field{field.alias, + name={\fieldfmt{alias}}, + description={The entry with this field set is a synonym of the + entry whose label is given by this field.}, + note={\styfmt{glossaries-extra}}, + category={extrafield}, + parent={fields} +} + +@field{field.category, + name={\fieldfmt{category}}, + description={The entry's category label.}, + note={\styfmt{glossaries-extra}}, + category={extrafield}, + parent={fields} +} + +@field{field.description, + name={\fieldfmt{description}}, + description={The description displayed in the glossary.}, + note={\styfmt{glossaries}}, + category={basefield}, + parent={fields} +} + +@field{field.descriptionplural, + name={\fieldfmt{descriptionplural}}, + description={The plural form of the description.}, + note={\styfmt{glossaries}}, + category={basefield}, + parent={fields} +} + +@field{field.first, + name={\fieldfmt{first}}, + description={The text to display on first use with \cs{gls}\margm{label}.}, + note={\styfmt{glossaries}}, + category={basefield}, + parent={fields} +} + +@field{field.firstplural, + name={\fieldfmt{firstplural}}, + description={The text to display on first use with \cs{glspl}\margm{label}.}, + note={\styfmt{glossaries}}, + category={basefield}, + parent={fields} +} + +@field{field.long, + name={\fieldfmt{long}}, + description={The long form of an abbreviation. (Set internally + by commands like \csref{newabbreviation}.)}, + note={\styfmt{glossaries}}, + category={basefield}, + parent={fields} +} + +@field{field.longplural, + name={\fieldfmt{longplural}}, + description={The plural long form of an abbreviation.}, + note={\styfmt{glossaries}}, + category={basefield}, + parent={fields} +} + +@field{field.name, + name={\fieldfmt{name}}, + description={The name displayed in the glossary.}, + note={\styfmt{glossaries}}, + category={basefield}, + parent={fields} +} + +@field{field.parent, + name={\fieldfmt{parent}}, + description={The parent entry's label. See + \sectionref{sec:logicaldivisions}.}, + note={\styfmt{glossaries}}, + category={basefield}, + parent={fields} +} + +@field{field.plural, + name={\fieldfmt{plural}}, + description={The text to display on subsequent use of + \cs{glspl}\margm{label}.}, + note={\styfmt{glossaries}}, + category={basefield}, + parent={fields} +} + +@field{field.see, + name={\fieldfmt{see}}, + description={General purpose cross-reference + (syntax: \code{see=\marg{\oargm{tag}\meta{xr-list}}}).}, + note={\styfmt{glossaries}}, + category={basefield}, + parent={fields} +} + +@field{field.seealso, + name={\fieldfmt{seealso}}, + description={Cross-reference related entries + (syntax: \code{seealso=\margm{xr-list}}).}, + note={\styfmt{glossaries-extra}}, + category={extrafield}, + parent={fields} +} + +@field{field.short, + name={\fieldfmt{short}}, + description={The short form of an abbreviation. (Set internally + by commands like \csref{newabbreviation}.)}, + note={\styfmt{glossaries}}, + category={basefield}, + parent={fields} +} + +@field{field.shortplural, + name={\fieldfmt{shortplural}}, + description={The plural short form of an abbreviation.}, + note={\styfmt{glossaries}}, + category={basefield}, + parent={fields} +} + +@field{field.symbol, + name={\fieldfmt{symbol}}, + description={The associated symbol.}, + note={\styfmt{glossaries}}, + category={basefield}, + parent={fields} +} + +@field{field.symbolplural, + name={\fieldfmt{symbolplural}}, + description={The plural form of the associated symbol.}, + note={\styfmt{glossaries}}, + category={basefield}, + parent={fields} +} + +@field{field.text, + name={\fieldfmt{text}}, + description={The text to display on subsequent use of + \cs{gls}\margm{label}.}, + note={\styfmt{glossaries}}, + category={basefield}, + parent={fields} +} + +@field{field.user1, + name={\fieldfmt{user1}}, + description={A general purpose user field.}, + note={\styfmt{glossaries}}, + category={basefield}, + parent={fields} +} + +@field{field.user2, + name={\fieldfmt{user2}}, + description={A general purpose user field.}, + note={\styfmt{glossaries}}, + category={basefield}, + parent={fields} +} + +@field{field.user3, + name={\fieldfmt{user3}}, + description={A general purpose user field.}, + note={\styfmt{glossaries}}, + category={basefield}, + parent={fields} +} + +@field{field.user4, + name={\fieldfmt{user4}}, + description={A general purpose user field.}, + note={\styfmt{glossaries}}, + category={basefield}, + parent={fields} +} + +@field{field.user5, + name={\fieldfmt{user5}}, + description={A general purpose user field.}, + note={\styfmt{glossaries}}, + category={basefield}, + parent={fields} +} + +@field{field.user6, + name={\fieldfmt{user6}}, + description={A general purpose user field.}, + note={\styfmt{glossaries}}, + category={basefield}, + parent={fields} +} + +@field{field.duallong, + name={\fieldfmt{duallong}}, + description={The long form of a dual + abbreviation mapped by \atentry{dualabbreviation}.}, + note={\appfmt{bib2gls}}, + category={bib2glsfield}, + parent={fields} +} + +@field{field.duallongplural, + name={\fieldfmt{dual\-long\-plural}}, + description={The plural long form of a dual + abbreviation mapped by \atentry{dualabbreviation}.}, + note={\appfmt{bib2gls}}, + category={bib2glsfield}, + parent={fields} +} + +@field{field.dualshort, + name={\fieldfmt{dualshort}}, + description={The short form of a dual + abbreviation mapped by \atentry{dualabbreviation}.}, + note={\appfmt{bib2gls}}, + category={bib2glsfield}, + parent={fields} +} + +@field{field.dualshortplural, + name={\fieldfmt{dual\-short\-plural}}, + description={The plural short form of a dual abbreviation + mapped by \atentry{dualabbreviation}.}, + note={\appfmt{bib2gls}}, + category={bib2glsfield}, + parent={fields} +} + +@field{field.adoptparents, + name={\fieldfmt{adopt\-parents}}, + description={The list of adopted parents for entries spawned by + \atentry{progenitor}. (Field only available for use in + \ext{bib} file within \atentry{progenitor}-like entries.)}, + note={\appfmt{bib2gls}}, + category={bib2glsfield}, + parent={fields} +} + +@field{field.prefix, + name={\fieldfmt{prefix}}, + description={The prefix associated with the \field{text} + field.}, + note={\styfmt{glossaries-prefix}}, + category={prefixfield}, + parent={fields} +} + +@field{field.prefixfirst, + name={\fieldfmt{prefixfirst}}, + description={The prefix associated with the \field{first} +field.}, + note={\styfmt{glossaries-prefix}}, + category={prefixfield}, + parent={fields} +} + +@field{field.prefixfirstplural, + name={\fieldfmt{prefixfirstplural}}, + description={The prefix associated with the + \field{firstplural} field.}, + note={\styfmt{glossaries-prefix}}, + category={prefixfield}, + parent={fields} +} + +@field{field.prefixplural, + name={\fieldfmt{prefixplural}}, + description={The prefix associated with the + \field{plural} field.}, + note={\styfmt{glossaries-prefix}}, + category={prefixfield}, + parent={fields} +} + +@field{field.access, + name={\fieldfmt{access}}, + description={The replacement text for the \field{name} field.}, + note={\styfmt{glossaries-accsupp}}, + category={accessfield}, + parent={fields} +} + +@field{field.descriptionaccess, + name={\fieldfmt{descriptionaccess}}, + description={The replacement text for the + \field{description} field.}, + note={\styfmt{glossaries-accsupp}}, + category={accessfield}, + parent={fields} +} + +@field{field.descriptionpluralaccess, + name={\fieldfmt{descriptionpluralaccess}}, + description={The replacement text for the + \field{descriptionplural} field.}, + note={\styfmt{glossaries-accsupp}}, + category={accessfield}, + parent={fields} +} + +@field{field.firstaccess, + name={\fieldfmt{firstaccess}}, + description={The replacement text for the \field{first} field.}, + note={\styfmt{glossaries-accsupp}}, + category={accessfield}, + parent={fields} +} + +@field{field.firstpluralaccess, + name={\fieldfmt{firstpluralaccess}}, + description={The replacement text for the + \field{firstplural} field.}, + note={\styfmt{glossaries-accsupp}}, + category={accessfield}, + parent={fields} +} + +@field{field.longaccess, + name={\fieldfmt{longaccess}}, + description={The replacement text for the \field{long} field.}, + note={\styfmt{glossaries-accsupp}}, + category={accessfield}, + parent={fields} +} + +@field{field.longpluralaccess, + name={\fieldfmt{longpluralaccess}}, + description={The replacement text for the + \field{longplural} field.}, + note={\styfmt{glossaries-accsupp}}, + category={accessfield}, + parent={fields} +} + +@field{field.pluralaccess, + name={\fieldfmt{pluralaccess}}, + description={The replacement text for the \field{plural} field.}, + note={\styfmt{glossaries-accsupp}}, + category={accessfield}, + parent={fields} +} + +@field{field.shortaccess, + name={\fieldfmt{shortaccess}}, + description={The replacement text for the \field{short} field.}, + note={\styfmt{glossaries-accsupp}}, + category={accessfield}, + parent={fields} +} + +@field{field.shortpluralaccess, + name={\fieldfmt{shortpluralaccess}}, + description={The replacement text for the + \field{shortplural} field.}, + note={\styfmt{glossaries-accsupp}}, + category={accessfield}, + parent={fields} +} + +@field{field.symbolaccess, + name={\fieldfmt{symbolaccess}}, + description={The replacement text for the \field{symbol} field.}, + note={\styfmt{glossaries-accsupp}}, + category={accessfield}, + parent={fields} +} + +@field{field.symbolpluralaccess, + name={\fieldfmt{symbolpluralaccess}}, + description={The replacement text for the + \field{symbolplural} field.}, + note={\styfmt{glossaries-accsupp}}, + category={accessfield}, + parent={fields} +} + +@field{field.textaccess, + name={\fieldfmt{textaccess}}, + description={The replacement text for the + \field{text} field.}, + note={\styfmt{glossaries-accsupp}}, + category={accessfield}, + parent={fields} +} + +@index{internalfields, + name={fields, internal}, + text={internal fields} +} + +@field{field.childcount, + name={\fieldfmt{childcount}}, + description={Stores the number of children this entry has + had selected.}, + note={internal field set by \appfmt{bib2gls}}, + category={internalfield}, + parent={internalfields} +} + +@field{field.childlist, + name={\fieldfmt{childlist}}, + description={A list of labels (in \sty{etoolbox}'s internal list + format) of the children this entry has had selected.}, + note={internal field set by \appfmt{bib2gls}}, + category={internalfield}, + parent={internalfields} +} + +@field{field.originalentrytype, + name={\fieldfmt{original\-entry\-type}}, + description={The original entry type before any aliasing was + applied or the actual entry type if no aliasing.}, + note={internal field set by \appfmt{bib2gls}}, + category={internalfield}, + parent={internalfields} +} + +@field{field.primarylocations, + name={\fieldfmt{primarylocations}}, + description={Stores the locations that use one of the designated +primary formats, if enabled.}, + note={internal field set by \appfmt{bib2gls}}, + category={internalfield}, + parent={internalfields} +} + +@field{field.indexcounter, + name={\fieldfmt{index\-counter}}, + description={Stores the location corresponding to the matching +\counter{wrglossary} reference.}, + note={internal field set by \appfmt{bib2gls}}, + category={internalfield}, + parent={internalfields} +} + +@field{field.counter, + name={\fieldfmt{counter}}, + description={The default counter used for indexing (assigned by + the \csopt{counter} option).}, + note={internal field set by \appfmt{bib2gls}}, + category={internalfield}, + parent={internalfields} +} + +@field{field.group, + name={\fieldfmt{group}}, + description={The letter group determined by the comparator + (or assigned by the \csopt{group} option). See + \sectionref{sec:logicaldivisions}.}, + note={internal field set by \appfmt{bib2gls}}, + category={internalfield}, + parent={internalfields} +} + +@field{field.location, + name={\fieldfmt{location}}, + description={The typeset location list.}, + note={internal field set by \appfmt{bib2gls}}, + category={internalfield}, + parent={internalfields} +} + +@field{field.loclist, + name={\fieldfmt{loclist}}, + description={The internal list of locations.}, + note={internal field set by \appfmt{bib2gls}}, + category={internalfield}, + parent={internalfields} +} + +@field{field.recordcount, + name={\fieldfmt{recordcount}}, + description={Used with record counting to store the + total record count.}, + note={internal field set by \appfmt{bib2gls}}, + category={internalfield}, + parent={internalfields} +} + +@field{field.recordcount.counter, + name={\fieldfmt{recordcount.\discretionary{}{}{}\meta{counter}}}, + description={Used with record counting to store the + total number of records for a given counter.}, + note={internal field set by \appfmt{bib2gls}}, + category={internalfield}, + parent={internalfields} +} + +@field{field.recordcount.counter.location, + name={\fieldfmt{recordcount.\discretionary{}{}{}\meta{counter}.\discretionary{}{}{}\meta{location}}}, + description={Used with record counting to store the + total number of records for a given location.}, + note={internal field set by \appfmt{bib2gls}}, + category={internalfield}, + parent={internalfields} +} + +@field{field.secondarygroup, + name={\fieldfmt{secondarygroup}}, + description={The letter group determined by the + comparator used with the \csopt{secondary} sort.}, + note={internal field set by \appfmt{bib2gls}}, + category={internalfield}, + parent={internalfields} +} + +@field{field.secondarysort, + name={\fieldfmt{secondarysort}}, + description={The sort value determined by the + comparator used with the \csopt{secondary} sort.}, + note={internal field set by \appfmt{bib2gls}}, + category={internalfield}, + parent={internalfields} +} + +@field{field.dual, + name={\fieldfmt{dual}}, + description={Created by \csopt{dual-field} if set with no value, + this field is used to store the dual label.}, + note={internal field set by \appfmt{bib2gls}}, + category={internalfield}, + parent={internalfields} +} + +@field{field.sort, + name={\fieldfmt{sort}}, + description={The sort value obtained by the comparator.}, + note={internal field set by \appfmt{bib2gls}}, + category={internalfield}, + parent={internalfields} +} + +@field{field.type, + name={\fieldfmt{type}}, + description={The glossary this entry belongs to (assigned by + the \csopt{type} option). See + \sectionref{sec:logicaldivisions}.}, + note={internal field set by \appfmt{bib2gls}}, + category={internalfield}, + parent={internalfields} +} + +@field{field.fieldendpunc, + name={\meta{field}\fieldfmt{endpunc}}, + description={Used with the \csopt{check-end-punctuation} + option.}, + note={internal field set by \appfmt{bibgls}}, + category={internalfield}, + parent={internalfields} +} + +@field{field.bibtextype, + name={\fieldfmt{bib\-tex\-type}}, + description={Used by \bibgls\ as a substitution for \BibTeX's + \fieldfmt{type} field when parsing \atentry{bibtexentry}. Needs + to be defined or aliased to make it available in the document.}, + note={internal field set by \bibgls}, + category={internalfield}, + parent={internalfields} +} + +@field{field.bibtexcontributor, + name={\fieldfmt{bib\-tex\-con\-trib\-u\-tor}}, + description={An internal list field provided when a + \atentry{contributor} entry is automatically + created by \atentry{bibtexentry}.}, + note={internal field set by \bibgls}, + category={internalfield}, + parent={internalfields} +} + +@field{field.bibtexentry, + name={\fieldfmt{bib\-tex\-entry}}, + description={An internal list field created by \atentry{bibtexentry}.}, + note={internal field set by \bibgls}, + category={internalfield}, + parent={internalfields} +} + +@field{field.bibtexentry@entrytype, + name={\fieldfmt{bib\-tex\-entry\-@\meta{entry-type}}}, + description={An internal list field created by \atentry{bibtexentry}.}, + note={internal field set by \bibgls}, + category={internalfield}, + parent={internalfields} +} + +@field{field.progeny, + name={\fieldfmt{progeny}}, + description={A comma-separated list of labels identifying + the entries spawned by \atentry{progenitor}.}, + note={internal field set by \appfmt{bib2gls}}, + category={internalfield}, + parent={internalfields} +} + +@field{field.progenitor, + name={\fieldfmt{progenitor}}, + description={The label identifying the \atentry{progenitor} + that spawned this entry.}, + note={internal field set by \appfmt{bib2gls}}, + category={internalfield}, + parent={internalfields} +} + +@field{field.currcount, + name={\fieldfmt{currcount}}, + description={Used with entry counting to store the current total.}, + note={internal field set by \styfmt{glossaries}}, + category={baseinternalfield}, + parent={internalfields} +} + +@field{field.currcountunit, + name={\fieldfmt{currcount@}\meta{value}}, + description={Used with unit entry counting (\styfmt{glossaries-extra}).}, + note={internal field set by \styfmt{glossaries-extra}}, + category={baseinternalfield}, + parent={internalfields} +} + +@field{field.desc, + name={\fieldfmt{desc}}, + description={Corresponds to \field{description} key.}, + note={internal field set by \styfmt{glossaries}}, + category={baseinternalfield}, + parent={internalfields} +} + +@field{field.descplural, + name={\fieldfmt{descplural}}, + description={Corresponds to \field{descriptionplural} key.}, + note={internal field set by \styfmt{glossaries}}, + category={baseinternalfield}, + parent={internalfields} +} + +@field{field.firstpl, + name={\fieldfmt{firstpl}}, + description={Corresponds to \field{firstplural} key.}, + note={internal field set by \styfmt{glossaries}}, + category={baseinternalfield}, + parent={internalfields} +} + +@field{field.flag, + name={\fieldfmt{flag}}, + description={Boolean that determines if an entry has been used.}, + note={internal field set by \styfmt{glossaries}}, + category={baseinternalfield}, + parent={internalfields} +} + +@field{field.index, + name={\fieldfmt{index}}, + description={The main part of the indexing code + (\appfmt{makeindex} or \appfmt{xindy}).}, + note={internal field set by \styfmt{glossaries}}, + category={baseinternalfield}, + parent={internalfields} +} + +@field{field.level, + name={\fieldfmt{level}}, + description={Hierarchical level.}, + note={internal field set by \styfmt{glossaries}}, + category={baseinternalfield}, + parent={internalfields} +} + +@field{field.longpl, + name={\fieldfmt{longpl}}, + description={Corresponds to \field{longplural} key.}, + note={internal field set by \styfmt{glossaries}}, + category={baseinternalfield}, + parent={internalfields} +} + +@field{field.nonumberlist, + name={\fieldfmt{nonumberlist}}, + description={Used to suppress the location list for a specific entry.}, + note={internal field set by \styfmt{glossaries}}, + category={baseinternalfield}, + parent={internalfields} +} + +@field{field.prevcount, + name={\fieldfmt{prevcount}}, + description={Used with entry counting to store the total + from the previous run.}, + note={internal field set by \styfmt{glossaries}}, + category={baseinternalfield}, + parent={internalfields} +} + +@field{field.prevcountunit, + name={\fieldfmt{prevcount@}\meta{value}}, + description={Used with unit entry counting + (\styfmt{glossaries-extra}).}, + note={internal field set by \styfmt{glossaries-extra}}, + category={baseinternalfield}, + parent={internalfields} +} + +@field{field.prevunitmax, + name={\fieldfmt{prevunitmax}}, + description={Used with unit entry counting + (\styfmt{glossaries-extra}).}, + note={internal field set by \styfmt{glossaries-extra}}, + category={baseinternalfield}, + parent={internalfields} +} + +@field{field.prevunittotal, + name={\fieldfmt{prevunittotal}}, + description={Used with unit entry counting + (\styfmt{glossaries-extra}).}, + note={internal field set by \styfmt{glossaries-extra}}, + category={baseinternalfield}, + parent={internalfields} +} + +@field{field.shortpl, + name={\fieldfmt{shortpl}}, + description={Corresponds to \field{shortplural} key.}, + note={internal field set by \styfmt{glossaries}}, + category={baseinternalfield}, + parent={internalfields} +} + +@field{field.sortvalue, + name={\fieldfmt{sortvalue}}, + description={Original \field{sort} value + (before sanitizing and escaping special characters).}, + note={internal field set by \styfmt{glossaries}}, + category={baseinternalfield}, + parent={internalfields} +} + +@field{field.unitlist, + name={\fieldfmt{unitlist}}, + description={Used with unit entry counting + (\styfmt{glossaries-extra}).}, + note={internal field set by \styfmt{glossaries-extra}}, + category={baseinternalfield}, + parent={internalfields} +} + +@field{field.useri, + name={\fieldfmt{useri}}, + description={Corresponds to \field{user1} key.}, + note={internal field set by \styfmt{glossaries}}, + category={baseinternalfield}, + parent={internalfields} +} + +@field{field.userii, + name={\fieldfmt{userii}}, + description={Corresponds to \field{user2} key.}, + note={internal field set by \styfmt{glossaries}}, + category={baseinternalfield}, + parent={internalfields} +} + +@field{field.useriii, + name={\fieldfmt{useriii}}, + description={Corresponds to \field{user3} key.}, + note={internal field set by \styfmt{glossaries}}, + category={baseinternalfield}, + parent={internalfields} +} + +@field{field.useriv, + name={\fieldfmt{useriv}}, + description={Corresponds to \field{user4} key.}, + note={internal field set by \styfmt{glossaries}}, + category={baseinternalfield}, + parent={internalfields} +} + +@field{field.userv, + name={\fieldfmt{userv}}, + description={Corresponds to \field{user5} key.}, + note={internal field set by \styfmt{glossaries}}, + category={baseinternalfield}, + parent={internalfields} +} + +@field{field.uservi, + name={\fieldfmt{uservi}}, + description={Corresponds to \field{user6} key.}, + note={internal field set by \styfmt{glossaries}}, + category={baseinternalfield}, + parent={internalfields} +} + +@field{field.bib2gls@sort, + name={\fieldfmt{bib2gls@sort}}, + description={Used by \bibgls\ to store the actual sort value.}, + note={internal field set by \bibgls}, + category={baseinternalfield}, + parent={internalfields} +} + +@field{field.bib2gls@sortfallback, + name={\fieldfmt{bib2gls@sortfallback}}, + description={Used by \bibgls\ to store the sort fallback value.}, + note={internal field set by \bibgls}, + category={baseinternalfield}, + parent={internalfields} +} + +@index{entrytypes, + name={entry types}, + text={entry type} +} + +@entrytype{entry.string, + name={\atentryfmt{string}}, + category={entrytype}, + parent={entrytypes} +} + +@entrytype{entry.preamble, + name={\atentryfmt{preamble}}, + category={entrytype}, + parent={entrytypes} +} + +@entrytype{entry.comment, + name={\atentryfmt{comment}}, + category={entrytype}, + parent={entrytypes} +} + +@entrytype{entry.entry, + name={\atentryfmt{entry}}, + category={entrytype}, + parent={entrytypes} +} + +@entrytype{entry.symbol, + name={\atentryfmt{symbol}}, + category={entrytype}, + parent={entrytypes} +} + +@entrytype{entry.number, + name={\atentryfmt{number}}, + category={entrytype}, + parent={entrytypes} +} + +@entrytype{entry.index, + name={\atentryfmt{index}}, + category={entrytype}, + parent={entrytypes} +} + +@entrytype{entry.indexplural, + name={\atentryfmt{indexplural}}, + category={entrytype}, + parent={entrytypes} +} + +@entrytype{entry.abbreviation, + name={\atentryfmt{abbreviation}}, + category={entrytype}, + parent={entrytypes} +} + +@entrytype{entry.acronym, + name={\atentryfmt{acronym}}, + category={entrytype}, + parent={entrytypes} +} + +@entrytype{entry.dualentry, + name={\atentryfmt{dual\-entry}}, + category={entrytype}, + parent={entrytypes} +} + +@entrytype{entry.dualindexentry, + name={\atentryfmt{dual\-index\-entry}}, + category={entrytype}, + parent={entrytypes} +} + +@entrytype{entry.dualindexabbreviation, + name={\atentryfmt{dual\-index\-abbre\-via\-tion}}, + category={entrytype}, + parent={entrytypes} +} + +@entrytype{entry.dualindexsymbol, + name={\atentryfmt{dual\-index\-symbol}}, + category={entrytype}, + parent={entrytypes} +} + +@entrytype{entry.dualindexnumber, + name={\atentryfmt{dual\-index\-number}}, + category={entrytype}, + parent={entrytypes} +} + +@entrytype{entry.dualabbreviationentry, + name={\atentryfmt{dual\-abbre\-via\-tion\-entry}}, + category={entrytype}, + parent={entrytypes} +} + +@entrytype{entry.dualentryabbreviation, + name={\atentryfmt{dual\-entry\-abbre\-via\-tion}}, + category={entrytype}, + parent={entrytypes} +} + +@entrytype{entry.dualsymbol, + name={\atentryfmt{dual\-symbol}}, + category={entrytype}, + parent={entrytypes} +} + +@entrytype{entry.dualnumber, + name={\atentryfmt{dual\-number}}, + category={entrytype}, + parent={entrytypes} +} + +@entrytype{entry.dualabbreviation, + name={\atentryfmt{dual\-abbre\-via\-tion}}, + category={entrytype}, + parent={entrytypes} +} + +@entrytype{entry.dualacronym, + name={\atentryfmt{dual\-acronym}}, + category={entrytype}, + parent={entrytypes} +} + +@entrytype{entry.tertiaryindexabbreviationentry, + name={\atentryfmt{tert\-iary\-index\-abbre\-via\-tion\-entry}}, + category={entrytype}, + parent={entrytypes} +} + +@entrytype{entry.bibtexentry, + name={\atentryfmt{bib\-tex\-entry}}, + category={entrytype}, + parent={entrytypes} +} + +@entrytype{entry.contributor, + name={\atentryfmt{contributor}}, + category={entrytype}, + parent={entrytypes} +} + +@entrytype{entry.progenitor, + name={\atentryfmt{progenitor}}, + category={entrytype}, + parent={entrytypes} +} + +@entrytype{entry.spawnindex, + name={\atentryfmt{spawn\-index}}, + category={entrytype}, + parent={entrytypes} +} + +@entrytype{entry.spawnindexplural, + name={\atentryfmt{spawn\-index\-plural}}, + category={entrytype}, + parent={entrytypes} +} + +@entrytype{entry.spawnentry, + name={\atentryfmt{spawn\-entry}}, + category={entrytype}, + parent={entrytypes} +} + +@entrytype{entry.spawnsymbol, + name={\atentryfmt{spawn\-symbol}}, + category={entrytype}, + parent={entrytypes} +} + +@entrytype{entry.spawnnumber, + name={\atentryfmt{spawn\-number}}, + category={entrytype}, + parent={entrytypes} +} + +@entrytype{entry.spawnabbreviation, + name={\atentryfmt{spawn\-abbreviation}}, + category={entrytype}, + parent={entrytypes} +} + +@entrytype{entry.spawnacronym, + name={\atentryfmt{spawn\-acronym}}, + category={entrytype}, + parent={entrytypes} +} + +@entrytype{entry.spawndualindexentry, + name={\atentryfmt{spawn\-dual\-index\-entry}}, + category={entrytype}, + parent={entrytypes} +} + +@index{switches, + name={switches}, + text={switch}, + plural={switches}, + see={commandlineoptions} +} + +@index{commandlineoptions, + name={command line options}, + text={command line option} +} + +@switch{switch.help, + name={\longargfmt{help}}, + symbol={\shortargfmt{h}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.version, + name={\longargfmt{version}}, + symbol={\shortargfmt{v}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.debug, + name={\longargfmt{debug}}, + user1={\oargm{n}}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.no-debug, + name={\longargfmt{no\dhyphen debug}}, + symbol={\longargfmt{nodebug}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.verbose, + name={\longargfmt{verbose}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.no-verbose, + name={\longargfmt{no\dhyphen verbose}}, + symbol={\longargfmt{noverbose}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.silent, + name={\longargfmt{silent}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.locale, + name={\longargfmt{locale}}, + symbol={\shortargfmt{l}}, + user1={\meta{lang}}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.log-file, + name={\longargfmt{log\dhyphen file}}, + symbol={\shortargfmt{t}}, + user1={\meta{filename}}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.dir, + name={\longargfmt{dir}}, + symbol={\shortargfmt{d}}, + user1={\meta{dirname}}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.interpret, + name={\longargfmt{interpret}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.no-interpret, + name={\longargfmt{no\dhyphen interpret}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.warn-non-bib-fields, + name={\longargfmt{warn\dhyphen non\dhyphen bib\dhyphen fields}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.no-warn-non-bib-fields, + name={\longargfmt{no\dhyphen warn\dhyphen non\dhyphen bib\dhyphen fields}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.warn-unknown-entry-types, + name={\longargfmt{warn\dhyphen unknown\dhyphen entry\dhyphen types}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.no-warn-unknown-entry-types, + name={\longargfmt{no\dhyphen warn\dhyphen unknown\dhyphen entry\dhyphen types}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.break-space, + name={\longargfmt{break\dhyphen space}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.no-break-space, + name={\longargfmt{no\dhyphen break\dhyphen space}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.cite-as-record, + name={\longargfmt{cite\dhyphen as\dhyphen record}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.no-cite-as-record, + name={\longargfmt{no\dhyphen cite\dhyphen as\dhyphen record}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.merge-wrglossary-records, + name={\longargfmt{merge\dhyphen wrglossary\dhyphen records}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.no-merge-wrglossary-records, + name={\longargfmt{no\dhyphen merge\dhyphen wrglossary\dhyphen records}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.merge-nameref-on, + name={\longargfmt{merge\dhyphen nameref\dhyphen on}}, + user1={\meta{rule}}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.force-cross-resource-refs, + name={\longargfmt{force\dhyphen cross\dhyphen resource\dhyphen refs}}, + symbol={\shortargfmt{x}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.no-force-cross-resource-refs, + name={\longargfmt{no\dhyphen force\dhyphen cross\dhyphen resource\dhyphen refs}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.support-unicode-script, + name={\longargfmt{support\dhyphen unicode\dhyphen script}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.no-support-unicode-script, + name={\longargfmt{no\dhyphen support\dhyphen unicode\dhyphen script}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.packages, + name={\longargfmt{packages}}, + symbol={\shortargfmt{p}}, + user1={\meta{list}}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.ignore-packages, + name={\longargfmt{ignore-packages}}, + symbol={\shortargfmt{k}}, + user1={\meta{list}}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.custom-packages, + name={\longargfmt{custom\dhyphen packages}}, + user1={\meta{list}}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.list-known-packages, + name={\longargfmt{list\dhyphen known\dhyphen packages}}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.mfirstuc-protection, + name={\longargfmt{mfirstuc\dhyphen protection}}, + symbol={\shortargfmt{u}}, + user1={\meta{list}\argor\code{all}}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.no-mfirstuc-protection, + name={\longargfmt{no\dhyphen mfirstuc\dhyphen protection}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.mfirstuc-math-protection, + name={\longargfmt{mfirstuc\dhyphen math\dhyphen protection}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.no-mfirstuc-math-protection, + name={\longargfmt{no\dhyphen mfirstuc\dhyphen math\dhyphen protection}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.nested-link-check, + name={\longargfmt{nested\dhyphen link\dhyphen check}}, + user1={\meta{list}\argor\code{none}}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.no-nested-link-check, + name={\longargfmt{no\dhyphen nested\dhyphen link\dhyphen check}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.shortcuts, + name={\longargfmt{shortcuts}}, + user1={\meta{value}}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.map-format, + name={\longargfmt{map\dhyphen format}}, + symbol={\shortargfmt{m}}, + user1={\meta{map:value list}}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.group, + name={\longargfmt{group}}, + symbol={\shortargfmt{g}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.no-group, + name={\longargfmt{no\dhyphen group}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.tex-encoding, + name={\longargfmt{tex\dhyphen encoding}}, + user1={\meta{name}}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.no-expand-fields, + name={\longargfmt{no\dhyphen expand\dhyphen fields}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.expand-fields, + name={\longargfmt{expand\dhyphen fields}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.record-count, + name={\longargfmt{record\dhyphen count}}, + symbol={\shortargfmt{c}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.no-record-count, + name={\longargfmt{no\dhyphen record\dhyphen count}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.record-count-unit, + name={\longargfmt{record\dhyphen count\dhyphen unit}}, + symbol={\shortargfmt{n}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.no-record-count-unit, + name={\longargfmt{no\dhyphen record\dhyphen count\dhyphen unit}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.trim-fields, + name={\longargfmt{trim\dhyphen fields}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.no-trim-fields, + name={\longargfmt{no\dhyphen trim\dhyphen fields}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + +@index{lettergroup, + name={letter group} +} + +@index{nonlettergroup, + name={non-letter group} +} + +@index{symbolgroup, + name={symbol group}, + alias={nonlettergroup} +} + +@index{emptygroup, + name={empty group (unknown commands)}, + text={empty group} +} + +@index{numbergroup, + name={number group} +} + +@index{datetimegroup, + name={date-time group} +} + +@index{dategroup, + name={date group} +} + +@index{timegroup, + name={time group} +} + +@index{customgroup, + name={custom group} +} + +@index{localeprovider, + name={locale provider} +} + +@index{ignoredglossary, + name={ignored glossary}, + plural={ignored glossaries} +} + +@index{ignoredrecord, + name={ignored record} +} + +@index{record, + seealso={ignoredrecord} +} + +@index{locationlist, + name = {location list} +} + +@index{postlinkhook, + name={post-link hook} +} + +@index{postnamehook, + name={post-name hook} +} + +@index{postdescriptionhook, + name={post-description hook} +} + +@index{languagexml, + name={language resource file (\extfmt{xml})} +} + +@xmltag{tag.page, + name={\xmltagfmt{tag.page}}, + parent={languagexml} +} + +@xmltag{tag.pages, + name={\xmltagfmt{tag.pages}}, + parent={languagexml} +} + +@xmltag{tag.passim, + name={\xmltagfmt{tag.passim}}, + parent={languagexml} +} + +@xmltag{sentence.terminators, + name={\xmltagfmt{sentence.terminators}}, + parent={languagexml} +} + +@xmltag{grouptitle.case.lc, + name={\xmltagfmt{grouptitle.case.}\meta{lc}}, + parent={languagexml} +} + +@index{xmlsee, + name={XML resource file}, + see={languagexml} +} + +@index{encoding} + +@index{digraph} + +@index{trigraph} + +@index{primary} + +@index{dual} + +@index{secondary, + seealso={dual}} + +@index{tertiary} + +@index{non-ASCII} + +@index{full-stop, + name={full stop (\code{.})}, + text={full stop} +} + +@index{period, + alias={full-stop} +} + +@index{apostrophe, + name={apostrophe (\code{'})}, + text={apostrophe} +} + +@index{resourceset, + name={resource set} +} + +@index{crossresourceref, + name={cross-resource reference} +} + +@index{firstuse, + name={first use} +} + +@index{subsequentuse, + name={subsequent use} +} + +@index{firstuseflag, + name={first use flag} +} + +@index{link-text, + name={link text} +} + +@index{parent-entry, + name={parent entry}, + plural={parent entries} +} + +@index{child-entry, + name={child entry}, + plural={child entries} +} + +@index{hierarchical-entry, + name={hierarchical entry}, + plural={hierarchical entries} +} + +@index{robust} +@index{fragile} +@index{expandable} +@index{regular} +@index{non-regular} +@index{variant} +@index{homograph} +@index{progeny} +@index{progenitor} + +@index{StackOverflowError, + name={\code{Stack\-Over\-flow\-Error}} +} + +@index{moving-argument, + name={moving argument} +} + +@index{uppercase, + name={upper case} +} + +@index{lowercase, + name={lower case} +} + +@index{titlecase, + name={title case} +} + +@index{sentencecase, + name={sentence case} +} + +@index{case-change, + name = {case-change}, + seealso = {uppercase,lowercase,titlecase,sentencecase} +} + +@index{unicodecategories, + name={Unicode categories}, + text={Unicode category}, + plural={Unicode categories} +} + +@unicodecategory{numberdecimaldigit, + name={\unicodecategoryfmt{Number, Decimal Digit}}, + parent={unicodecategories} +} + +@unicodecategory{separatorspace, + name={\unicodecategoryfmt{Separator, Space}}, + parent={unicodecategories} +} + +@unicodecategory{letteruppercase, + name={\unicodecategoryfmt{Letter, Uppercase}}, + parent={unicodecategories} +} + +@unicodecategory{letterlowercase, + name={\unicodecategoryfmt{Letter, Lowercase}}, + parent={unicodecategories} +} + +@unicodecategory{lettertitlecase, + name={\unicodecategoryfmt{Letter, Titlecase}}, + parent={unicodecategories} +} + +@unicodecategory{lettermodifier, + name={\unicodecategoryfmt{Letter, Modifier}}, + parent={unicodecategories} +} + +@unicodecategory{letterother, + name={\unicodecategoryfmt{Letter, Other}}, + parent={unicodecategories} +} + +@unicodecategory{punctuationclose, + name={\unicodecategoryfmt{Punctuation, Close}}, + parent={unicodecategories} +} + +@unicodecategory{punctuationfinalquote, + name={\unicodecategoryfmt{Punctuation, Final quote}}, + parent={unicodecategories} +} + +@unicodecategory{punctuationother, + name={\unicodecategoryfmt{Punctuation, Other}}, + parent={unicodecategories} +} + +@unicodecategory{punctuationdash, + name={\unicodecategoryfmt{Punctuation, Dash}}, + parent={unicodecategories} +} + +@texmfcnf{texmfcnf.openinany, + name={\texmfcnffmt{openin\_any}} +} + +@texmfcnf{texmfcnf.openoutany, + name={\texmfcnffmt{openout\_any}} +} + +@file{file.bib2gls-en.xml, + name={\filefmt{bib2gls-en.xml}} +} + +@file{file.bib2gls.sh, + name={\filefmt{bib2gls.sh}} +} + +@file{file.convertgls2bib.sh, + name={\filefmt{convert\-gls2bib.sh}} +} + +@file{file.texparserlib.jar, + name={\filefmt{texparserlib.jar}} +} + +@file{file.bib2gls.jar, + name={\filefmt{bib2gls.jar}} +} + +@file{file.convertgls2bib.jar, + name={\filefmt{convert\-gls2bib.jar}} +} + +@file{file.bib2gls.bat, + name={\filefmt{bib2gls.bat}} +} + +@file{file.xampl.bib, + name={\filefmt{xampl.bib}} +} + +@file{file.sample-dual.tex, + name={\filefmt{sample\dhyphen dual.tex}} +} + +@samplefile{file.no-interpret-preamble.bib, + name={\filefmt{no\dhyphen interpret\dhyphen preamble.bib}} +} + +@samplefile{file.interpret-preamble.bib, + name={\filefmt{interpret\dhyphen preamble.bib}} +} + +@samplefile{file.interpret-preamble2.bib, + name={\filefmt{interpret\dhyphen preamble2.bib}} +} + +@samplefile{file.people.bib, + name={\filefmt{people.bib}} +} + +@samplefile{file.sample-people.tex, + name={\filefmt{sample\dhyphen people.tex}} +} + +@samplefile{file.sample-authors.tex, + name={\filefmt{sample\dhyphen authors.tex}} +} + +@samplefile{file.sample-citations.tex, + name={\filefmt{sample\dhyphen citations.tex}} +} + +@samplefile{file.citations.bib, + name={\filefmt{citations.bib}} +} + +@samplefile{file.bacteria.bib, + name={\filefmt{bacteria.bib}} +} + +@samplefile{file.sample-bacteria.tex, + name={\filefmt{sample\dhyphen bacteria.tex}} +} + +@samplefile{file.chemicalformula.bib, + name={\filefmt{chemicalformula.bib}} +} + +@samplefile{file.sample-chemical.tex, + name={\filefmt{sample\dhyphen chemical.tex}} +} + +@samplefile{file.constants.bib, + name={\filefmt{constants.bib}} +} + +@samplefile{file.sample-constants.tex, + name={\filefmt{sample\dhyphen constants.tex}} +} + +@samplefile{file.baseunits.bib, + name={\filefmt{baseunits.bib}} +} + +@samplefile{file.derivedunits.bib, + name={\filefmt{derivedunits.bib}} +} + +@samplefile{file.sample-units1.tex, + name={\filefmt{sample-units1.tex}} +} + +@samplefile{file.sample-units2.tex, + name={\filefmt{sample-units2.tex}} +} + +@samplefile{file.sample-units3.tex, + name={\filefmt{sample-units3.tex}} +} + +@samplefile{file.books.bib, + name={\filefmt{books.bib}} +} + +@samplefile{file.films.bib, + name={\filefmt{films.bib}} +} + +@samplefile{file.sample-media.tex, + name={\filefmt{sample\dhyphen media.tex}} +} + +@samplefile{file.bigmathsymbols.bib, + name={\filefmt{bigmathsymbols.bib}} +} + +@samplefile{file.mathgreek.bib, + name={\filefmt{mathgreek.bib}} +} + +@samplefile{file.mathsrelations.bib, + name={\filefmt{mathsrelations.bib}} +} + +@samplefile{file.binaryoperators.bib, + name={\filefmt{binaryoperators.bib}} +} + +@samplefile{file.unaryoperators.bib, + name={\filefmt{unaryoperators.bib}} +} + +@samplefile{file.mathsobjects.bib, + name={\filefmt{mathsobjects.bib}} +} + +@samplefile{file.sample-msymbols.tex, + name={\filefmt{sample\dhyphen msymbols.tex}} +} + +@samplefile{file.sample-maths.tex, + name={\filefmt{sample\dhyphen maths.tex}} +} + +@samplefile{file.miscsymbols.bib, + name={\filefmt{miscsymbols.bib}} +} + +@samplefile{file.sample-textsymbols.tex, + name={\filefmt{sample\dhyphen textsymbols.tex}} +} + +@samplefile{file.sample-textsymbols2.tex, + name={\filefmt{sample\dhyphen textsymbols2.tex}} +} + +@samplefile{file.markuplanguages.bib, + name={\filefmt{markuplanguages.bib}} +} + +@samplefile{file.sample-markuplanguages.tex, + name={\filefmt{sample\dhyphen markuplanguages.tex}} +} + +@samplefile{file.usergroups.bib, + name={\filefmt{usergroups.bib}} +} + +@samplefile{file.sample-usergroups.tex, + name={\filefmt{sample\dhyphen usergroups.tex}} +} + +@samplefile{file.animals.bib, + name={\filefmt{animals.bib}} +} + +@samplefile{file.vegetables.bib, + name={\filefmt{vegetables.bib}} +} + +@samplefile{file.minerals.bib, + name={\filefmt{minerals.bib}} +} + +@samplefile{file.terms.bib, + name={\filefmt{terms.bib}} +} + +@samplefile{file.topics.bib, + name={\filefmt{topics.bib}} +} + +@samplefile{file.sample-multi1.tex, + name={\filefmt{sample\dhyphen multi1.tex}} +} + +@samplefile{file.sample-multi2.tex, + name={\filefmt{sample\dhyphen multi2.tex}} +} + +@glscommand{glshyperlink, + name={\csfmt{gls\-hyper\-link}}, + user1={\oargm{link text}\margm{label}}, + description={creates a hyperlink to the entry information in the + glossary}, + topics={linkcommands,entryrefcommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{glsxtrfielddolistloop, + name={\csfmt{gls\-xtr\-field\-do\-list\-loop}}, + user1={\margm{label}\margm{field}}, + description={iterates over the items the given field, which contains + an \styfmt{etoolbox} internal list}, + topics={listcommands,loops,fieldrefcommands}, + note={\styfmt{glossaries-extra} v1.12+}, + seealso={glsxtrfieldforlistloop,glsxtrfieldifinlist,glsxtrfieldlistadd}, + category={command} +} + +@glscommand{glsxtrfieldforlistloop, + name={\csfmt{gls\-xtr\-field\-for\-list\-loop}}, + user1={\margm{label}\margm{field}\margm{handler}}, + description={iterates over the items the given field, which contains + an \styfmt{etoolbox} internal list, using the given handler}, + topics={listcommands,loops,fieldrefcommands}, + note={\styfmt{glossaries-extra} v1.29+}, + seealso={glsxtrfielddolistloop,glsxtrfieldifinlist,glsxtrfieldlistadd}, + category={command} +} + +@glscommand{glsfieldfetch, + name={\csfmt{gls\-field\-fetch}}, + user1={\margm{label}\margm{field}\margm{cs}}, + description={fetches the value of the given field for the given + label and stores it in the command \meta{cs}}, + topics={fieldrefcommands}, + note={\styfmt{glossaries} v4.16+}, + category={command} +} + +@glscommand{glsxtrautoindexassignsort, + name={\csfmt{gls\-xtr\-auto\-index\-assign\-sort}}, + user1={\margm{cs}\margm{label}}, + description={assigns the sort value for \cs{index} when + using auto-indexing}, + topics={hooks,indexing}, + note={\styfmt{glossaries-extra} v1.16+}, + category={command} +} + +@glscommand{glsxtrautoindexentry, + name={\csfmt{gls\-xtr\-auto\-index\-entry}}, + user1={\margm{label}}, + description={used for the actual value in \cs{index} when + using auto-indexing}, + topics={hooks,indexing}, + note={\styfmt{glossaries-extra} v1.16+}, + category={command} +} + +@glscommand{glsseeformat, + name={\csfmt{gls\-see\-format}}, + user1={\margm{tag}\margm{labels}\margm{location (ignored)}}, + description={formats the entries identified in the comma separated + list of labels as a set of cross-references, where each + item in the list is encapsulated with \cs{glsseeitem} and + each element is separated with \cs{glsseesep} or + \cs{glsseelastsep}}, + topics={formattingcommands,crossrefcommands,loclistcommands}, + note={\styfmt{glossaries}}, + seealso={glsseeitem,glsseeitemformat,glsseesep,glsseelastsep}, + category={command} +} + +@glscommand{glsseeitem, + name={\csfmt{gls\-see\-item}}, + user1={\margm{label}}, + description={formats an element of the cross-reference list. + The default behaviour is to create a hyperlink (if enabled) to the + referenced entry with the link text given by + \code{\cs{glsseeitemformat}\margm{label}}}, + topics={formattingcommands,crossrefcommands,loclistcommands,linkcommands}, + note={\styfmt{glossaries}}, + seealso={glsseeformat,glsseeitemformat}, + category={command} +} + +@glscommand{glsseeitemformat, + name={\csfmt{gls\-see\-item\-format}}, + user1={\margm{label}}, + description={formats an element of the cross-reference list. + With the base \styfmt{glossaries} package this just does + \code{\cs{glsentrytext}\margm{label}}. With + \styfmt{glossaries-extra} this uses either \cs{glsentryshort} + or \cs{glsentryname} depending on whether or not the + \field{short} field has been set}, + topics={formattingcommands,crossrefcommands,loclistcommands}, + note={\styfmt{glossaries} v3.0+}, + seealso={glsseeformat,glsseeitem}, + category={command} +} + +@glscommand{glsseesep, + name={\csfmt{gls\-see\-sep}}, + description={the separator used between all but the last + entries of a cross-reference list}, + note={\styfmt{glossaries}}, + topics={separatorcommands,crossrefcommands,loclistcommands}, + seealso={glsseeformat,glsseelastsep}, + category={command} +} + +@glscommand{glsseelastsep, + name={\csfmt{gls\-see\-last\-sep}}, + description={the separator used between the penultimate and + ultimate entries of a cross-reference list}, + topics={separatorcommands,crossrefcommands,loclistcommands}, + note={\styfmt{glossaries}}, + seealso={glsseeformat,glsseesep}, + category={command} +} + +@glscommand{glsxtruseseeformat, + name={\csfmt{gls\-xtr\-use\-see\-format}}, + user1={\margm{tag}\margm{labels}}, + description={formats the entries identified in the comma separated + list of labels as a set of cross-references}, + topics={separatorcommands,crossrefcommands,loclistcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glsxtrhiername, + name={\csfmt{gls\-xtr\-hier\-name}}, + user1={\margm{label}}, + description={Displays the hierarchical name for the entry + identified by \meta{label} with each level separated by + \cs{glsxtrhiernamesep}}, + topics={formattingcommands,entryrefcommands}, + note={\styfmt{glossaries-extra}\texparserdefnote\ v1.37+}, + seealso={glsxtrhiernamesep}, + category={command} +} + +@glscommand{glsxtrhiernamesep, + name={\csfmt{gls\-xtr\-hier\-name\-sep}}, + description={Separator between hierarchical levels displayed with + \cs{glsxtrhiername} (and case-changing variants). This defaults + to \qt{\glsxtrhiernamesep} with the \styfmt{glossaries-extra} + package, but the \bibgls\ interpreter has a different definition + to assist sorting}, + topics={separatorcommands}, + note={\styfmt{glossaries-extra}\texparserdefnote\ v1.37+}, + seealso={glsxtrhiername}, + category={command} +} + +@glscommand{Glsxtrhiername, + name={\csfmt{Gls\-xtr\-hier\-name}}, + user1={\margm{label}}, + description={Displays the hierarchical name for the entry + identified by \meta{label} with each level separated by + \cs{glsxtrhiernamesep} where the top-most name has the + first letter converted to \idx{uppercase}}, + topics={formattingcommands,entryrefcommands,casecommands}, + note={\styfmt{glossaries-extra}\texparserdefnote\ v1.37+}, + seealso={glsxtrhiername,glsxtrhiernamesep}, + category={command} +} + +@glscommand{GlsXtrhiername, + name={\csfmt{Gls\-Xtr\-hier\-name}}, + user1={\margm{label}}, + description={Displays the hierarchical name for the entry + identified by \meta{label} with each level separated by + \cs{glsxtrhiernamesep} where each name has the + first letter converted to \idx{uppercase}}, + topics={formattingcommands,entryrefcommands,casecommands}, + note={\styfmt{glossaries-extra}\texparserdefnote\ v1.37+}, + seealso={glsxtrhiername,glsxtrhiernamesep}, + category={command} +} + +@glscommand{GLSxtrhiername, + name={\csfmt{GLS\-xtr\-hier\-name}}, + user1={\margm{label}}, + description={Displays the hierarchical name for the entry + identified by \meta{label} with each level separated by + \cs{glsxtrhiernamesep} where the top-most name is converted to \idx{uppercase}}, + topics={formattingcommands,entryrefcommands,casecommands}, + note={\styfmt{glossaries-extra}\texparserdefnote\ v1.37+}, + seealso={glsxtrhiername,glsxtrhiernamesep}, + category={command} +} + +@glscommand{GLSXTRhiername, + name={\csfmt{GLS\-XTR\-hier\-name}}, + user1={\margm{label}}, + description={Displays the hierarchical name for the entry + identified by \meta{label} with each level separated by + \cs{glsxtrhiernamesep} where each name is converted + to \idx{uppercase}}, + topics={formattingcommands,entryrefcommands,casecommands}, + note={\styfmt{glossaries-extra}\texparserdefnote\ v1.37+}, + seealso={glsxtrhiername,glsxtrhiernamesep}, + category={command} +} + +@glscommand{glsextrapostnamehook, + name={\csfmt{gls\-extra\-post\-name\-hook}}, + user1={\margm{label}}, + description={additional category-independent code for the +post-name hook}, + topics={hooks}, + note={\styfmt{glossaries-extra} v1.25+}, + category={command} +} + +@glscommand{glsentrytext, + name={\csfmt{gls\-entry\-text}}, + user1={\margm{label}}, + description={expands to the value of the + \field{text} field}, + topics={fieldrefcommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{Glsentrytext, + name={\csfmt{Gls\-entry\-text}}, + user1={\margm{label}}, + description={displays the value of the \field{text} field with + the first letter converted to \idx{uppercase}}, + topics={fieldrefcommands,casecommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{glsentryplural, + name={\csfmt{gls\-entry\-plural}}, + user1={\margm{label}}, + description={expands to the value of the + \field{plural} field}, + topics={fieldrefcommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{Glsentryplural, + name={\csfmt{Gls\-entry\-plural}}, + user1={\margm{label}}, + description={displays the value of the + \field{plural} field with the first letter converted to +\idx{uppercase}}, + topics={fieldrefcommands,casecommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{glsentryfirst, + name={\csfmt{gls\-entry\-first}}, + user1={\margm{label}}, + description={expands to the value of the + \field{first} field}, + topics={fieldrefcommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{Glsentryfirst, + name={\csfmt{Gls\-entry\-first}}, + user1={\margm{label}}, + description={displays the value of the + \field{first} field with the first letter converted to + \idx{uppercase}}, + topics={fieldrefcommands,casecommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{glsentryfirstplural, + name={\csfmt{gls\-entry\-first\-plural}}, + user1={\margm{label}}, + description={expands to the value of the + \field{firstplural} field}, + topics={fieldrefcommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{Glsentryfirstplural, + name={\csfmt{Gls\-entry\-first\-plural}}, + user1={\margm{label}}, + description={displays the value of the + \field{firstplural} field with the first letter converted to + \idx{uppercase}}, + topics={fieldrefcommands,casecommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{glsentryname, + name={\csfmt{gls\-entry\-name}}, + user1={\margm{label}}, + description={expands to the value of the + \field{name} field}, + topics={fieldrefcommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{Glsentryname, + name={\csfmt{Gls\-entry\-name}}, + user1={\margm{label}}, + description={displays the value of the + \field{name} field with the first character + converted to \idx{uppercase}}, + topics={fieldrefcommands,casecommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{glsentrydesc, + name={\csfmt{gls\-entry\-desc}}, + user1={\margm{label}}, + description={expands to the value of the + \field{description} field}, + topics={fieldrefcommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{glsentrydescplural, + name={\csfmt{gls\-entry\-desc\-plural}}, + user1={\margm{label}}, + description={expands to the value of the + \field{descriptionplural} field}, + topics={fieldrefcommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{Glsentrydesc, + name={\csfmt{Gls\-entry\-desc}}, + user1={\margm{label}}, + description={displays the value of the + \field{description} field with the first letter converted to + \idx{uppercase}}, + topics={fieldrefcommands,casecommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{Glsentrydescplural, + name={\csfmt{Gls\-entry\-desc\-plural}}, + user1={\margm{label}}, + description={displays the value of the + \field{descriptionplural} field with the first letter converted to + \idx{uppercase}}, + topics={fieldrefcommands,casecommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{glsentrysymbol, + name={\csfmt{gls\-entry\-symbol}}, + user1={\margm{label}}, + description={expands to the value of the + \field{symbol} field}, + topics={fieldrefcommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{Glsentrysymbol, + name={\csfmt{Gls\-entry\-symbol}}, + user1={\margm{label}}, + description={displays the value of the + \field{symbol} field with the first letter converted to +\idx{uppercase}}, + topics={fieldrefcommands,casecommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{glsentrysymbolplural, + name={\csfmt{gls\-entry\-symbol\-plural}}, + user1={\margm{label}}, + description={expands to the value of the + \field{symbolplural} field}, + topics={fieldrefcommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{Glsentrysymbolplural, + name={\csfmt{Gls\-entry\-symbol\-plural}}, + user1={\margm{label}}, + description={displays the value of the + \field{symbolplural} field with the first letter converted to +\idx{uppercase}}, + topics={fieldrefcommands,casecommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{glsentrylong, + name={\csfmt{gls\-entry\-long}}, + user1={\margm{label}}, + description={expands to the value of the \field{long} field + without any formatting or indexing}, + topics={fieldrefcommands,abbreviationcommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{glsentrylongpl, + name={\csfmt{gls\-entry\-long\-pl}}, + user1={\margm{label}}, + description={expands to the value of the \field{longplural} field + without any formatting or indexing}, + topics={fieldrefcommands,abbreviationcommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{Glsentrylong, + name={\csfmt{Gls\-entry\-long}}, + user1={\margm{label}}, + description={displays the value of the + \field{long} field without any formatting or indexing but + with the first letter converted to \idx{uppercase}}, + topics={fieldrefcommands,abbreviationcommands,casecommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{Glsentrylongpl, + name={\csfmt{Gls\-entry\-long\-pl}}, + user1={\margm{label}}, + description={displays the value of the + \field{longplural} field without any formatting or indexing but + with the first letter converted to \idx{uppercase}}, + topics={fieldrefcommands,abbreviationcommands,casecommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{glsentryshort, + name={\csfmt{gls\-entry\-short}}, + user1={\margm{label}}, + description={expands to the value of the + \field{short} field without any formatting or indexing}, + topics={fieldrefcommands,abbreviationcommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{glsentryshortpl, + name={\csfmt{gls\-entry\-short\-pl}}, + user1={\margm{label}}, + description={expands to the value of the + \field{shortplural} field without any formatting or indexing}, + topics={fieldrefcommands,abbreviationcommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{Glsentryshort, + name={\csfmt{Gls\-entry\-short}}, + user1={\margm{label}}, + description={displays the value of the + \field{short} field without any formatting or indexing but + with the first letter converted to \idx{uppercase}}, + topics={fieldrefcommands,abbreviationcommands,casecommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{Glsentryshortpl, + name={\csfmt{Gls\-entry\-short\-pl}}, + user1={\margm{label}}, + description={displays the value of the + \field{shortplural} field without any formatting or indexing + but with the first letter converted to \idx{uppercase}}, + topics={fieldrefcommands,abbreviationcommands,casecommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{glsentryuseri, + name={\csfmt{gls\-entry\-useri}}, + user1={\margm{label}}, + description={expands to the value of the + \field{user1} field}, + topics={fieldrefcommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{glsentryuserii, + name={\csfmt{gls\-entry\-userii}}, + user1={\margm{label}}, + description={expands to the value of the + \field{user2} field}, + topics={fieldrefcommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{glsentryuseriii, + name={\csfmt{gls\-entry\-useriii}}, + user1={\margm{label}}, + description={expands to the value of the + \field{user3} field}, + topics={fieldrefcommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{glsentryuseriv, + name={\csfmt{gls\-entry\-useriv}}, + user1={\margm{label}}, + description={expands to the value of the + \field{user4} field}, + topics={fieldrefcommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{glsentryuserv, + name={\csfmt{gls\-entry\-userv}}, + user1={\margm{label}}, + description={expands to the value of the + \field{user5} field}, + topics={fieldrefcommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{glsentryuservi, + name={\csfmt{gls\-entry\-uservi}}, + user1={\margm{label}}, + description={expands to the value of the + \field{user6} field}, + topics={fieldrefcommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{Glsentryuseri, + name={\csfmt{Gls\-entry\-useri}}, + user1={\margm{label}}, + description={displays the value of the + \field{user1} field with the first letter converted to +\idx{uppercase}}, + topics={fieldrefcommands,casecommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{Glsentryuserii, + name={\csfmt{Gls\-entry\-userii}}, + user1={\margm{label}}, + description={displays the value of the + \field{user2} field with the first letter converted to +\idx{uppercase}}, + topics={fieldrefcommands,casecommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{Glsentryuseriii, + name={\csfmt{Gls\-entry\-useriii}}, + user1={\margm{label}}, + description={displays the value of the + \field{user3} field with the first letter converted to +\idx{uppercase}}, + topics={fieldrefcommands,casecommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{Glsentryuseriv, + name={\csfmt{Gls\-entry\-useriv}}, + user1={\margm{label}}, + description={displays the value of the + \field{user4} field with the first letter converted to +\idx{uppercase}}, + topics={fieldrefcommands,casecommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{Glsentryuserv, + name={\csfmt{Gls\-entry\-userv}}, + user1={\margm{label}}, + description={displays the value of the + \field{user5} field with the first letter converted to +\idx{uppercase}}, + topics={fieldrefcommands,casecommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{Glsentryuservi, + name={\csfmt{Gls\-entry\-uservi}}, + user1={\margm{label}}, + description={displays the value of the + \field{user6} field with the first letter converted to +\idx{uppercase}}, + topics={fieldrefcommands,casecommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{glsaccessname, + name={\csfmt{gls\-access\-name}}, + user1={\margm{label}}, + description={expands to the value of the + \field{name} field with the accessibility support + for that field, if provided (otherwise behaves the same as + \cs{glsentryname})}, + topics={fieldrefcommands,access-support}, + note={\styfmt{glossaries-extra}\texparserdefnote}, + category={command} +} + +@glscommand{Glsaccessname, + name={\csfmt{Gls\-access\-name}}, + user1={\margm{label}}, + description={expands to the value of the + \field{name} field with the first letter converted to + \idx{uppercase} and with the accessibility support + for that field, if provided (otherwise behaves the same as + \cs{Glsentryname})}, + topics={fieldrefcommands,access-support}, + note={\styfmt{glossaries-extra}\texparserdefnote}, + category={command} +} + +@glscommand{glsaccesstext, + name={\csfmt{gls\-access\-text}}, + user1={\margm{label}}, + description={expands to the value of the + \field{text} field with the accessibility support + for that field, if provided (otherwise behaves the same as + \cs{glsentrytext})}, + topics={fieldrefcommands,access-support}, + note={\styfmt{glossaries-extra}\texparserdefnote}, + category={command} +} + +@glscommand{Glsaccesstext, + name={\csfmt{Gls\-access\-text}}, + user1={\margm{label}}, + description={expands to the value of the + \field{text} field with the first letter converted to + \idx{uppercase} and with the accessibility support + for that field, if provided (otherwise behaves the same as + \cs{Glsentrytext})}, + topics={fieldrefcommands,access-support}, + note={\styfmt{glossaries-extra}\texparserdefnote}, + category={command} +} + +@glscommand{glsaccessplural, + name={\csfmt{gls\-access\-plural}}, + user1={\margm{label}}, + description={expands to the value of the + \field{plural} field with the accessibility support + for that field, if provided (otherwise behaves the same as + \cs{glsentryplural})}, + topics={fieldrefcommands,access-support}, + note={\styfmt{glossaries-extra}\texparserdefnote}, + category={command} +} + +@glscommand{Glsaccessplural, + name={\csfmt{Gls\-access\-plural}}, + user1={\margm{label}}, + description={expands to the value of the + \field{plural} field with the first letter converted to + \idx{uppercase} and with the accessibility support + for that field, if provided (otherwise behaves the same as + \cs{Glsentryplural})}, + topics={fieldrefcommands,access-support}, + note={\styfmt{glossaries-extra}\texparserdefnote}, + category={command} +} + +@glscommand{glsaccessfirst, + name={\csfmt{gls\-access\-first}}, + user1={\margm{label}}, + description={expands to the value of the + \field{first} field with the accessibility support + for that field, if provided (otherwise behaves the same as + \cs{glsentryfirst})}, + topics={fieldrefcommands,access-support}, + note={\styfmt{glossaries-extra}\texparserdefnote}, + category={command} +} + +@glscommand{Glsaccessfirst, + name={\csfmt{Gls\-access\-first}}, + user1={\margm{label}}, + description={expands to the value of the + \field{first} field with the first letter converted to + \idx{uppercase} and with the accessibility support + for that field, if provided (otherwise behaves the same as + \cs{Glsentryfirst})}, + topics={fieldrefcommands,access-support}, + note={\styfmt{glossaries-extra}\texparserdefnote}, + category={command} +} + +@glscommand{glsaccessfirstplural, + name={\csfmt{gls\-access\-first\-plural}}, + user1={\margm{label}}, + description={expands to the value of the + \field{firstplural} field with the accessibility support + for that field, if provided (otherwise behaves the same as + \cs{glsentryfirstplural})}, + topics={fieldrefcommands,access-support}, + note={\styfmt{glossaries-extra}\texparserdefnote}, + category={command} +} + +@glscommand{Glsaccessfirstplural, + name={\csfmt{Gls\-access\-first\-plural}}, + user1={\margm{label}}, + description={expands to the value of the + \field{firstplural} field with the first letter converted to + \idx{uppercase} and with the accessibility support + for that field, if provided (otherwise behaves the same as + \cs{Glsentryfirstplural})}, + topics={fieldrefcommands,access-support}, + note={\styfmt{glossaries-extra}\texparserdefnote}, + category={command} +} + +@glscommand{glsaccesssymbol, + name={\csfmt{gls\-access\-symbol}}, + user1={\margm{label}}, + description={expands to the value of the + \field{symbol} field with the accessibility support + for that field, if provided (otherwise behaves the same as + \cs{glsentrysymbol})}, + topics={fieldrefcommands,access-support}, + note={\styfmt{glossaries-extra}\texparserdefnote}, + category={command} +} + +@glscommand{Glsaccesssymbol, + name={\csfmt{Gls\-access\-symbol}}, + user1={\margm{label}}, + description={expands to the value of the + \field{symbol} field with the first letter converted to + \idx{uppercase} and with the accessibility support + for that field, if provided (otherwise behaves the same as + \cs{Glsentrysymbol})}, + topics={fieldrefcommands,access-support}, + note={\styfmt{glossaries-extra}\texparserdefnote}, + category={command} +} + +@glscommand{glsaccesssymbolplural, + name={\csfmt{gls\-access\-symbol\-plural}}, + user1={\margm{label}}, + description={expands to the value of the + \field{symbolplural} field with the accessibility support + for that field, if provided (otherwise behaves the same as + \cs{glsentrysymbolplural})}, + topics={fieldrefcommands,access-support}, + note={\styfmt{glossaries-extra}\texparserdefnote}, + category={command} +} + +@glscommand{Glsaccesssymbolplural, + name={\csfmt{Gls\-access\-symbol\-plural}}, + user1={\margm{label}}, + description={expands to the value of the + \field{symbolplural} field with the first letter converted to + \idx{uppercase} and with the accessibility support + for that field, if provided (otherwise behaves the same as + \cs{Glsentrysymbolplural})}, + topics={fieldrefcommands,access-support}, + note={\styfmt{glossaries-extra}\texparserdefnote}, + category={command} +} + +@glscommand{glsaccessdesc, + name={\csfmt{gls\-access\-desc}}, + user1={\margm{label}}, + description={expands to the value of the + \field{description} field with the accessibility support + for that field, if provided (otherwise behaves the same as + \cs{glsentrydesc})}, + topics={fieldrefcommands,access-support}, + note={\styfmt{glossaries-extra}\texparserdefnote}, + category={command} +} + +@glscommand{Glsaccessdesc, + name={\csfmt{Gls\-access\-desc}}, + user1={\margm{label}}, + description={expands to the value of the + \field{description} field with the first letter converted to + \idx{uppercase} and with the accessibility support + for that field, if provided (otherwise behaves the same as + \cs{Glsentrydesc})}, + topics={fieldrefcommands,access-support}, + note={\styfmt{glossaries-extra}\texparserdefnote}, + category={command} +} + +@glscommand{glsaccessdescplural, + name={\csfmt{gls\-access\-desc\-plural}}, + user1={\margm{label}}, + description={expands to the value of the + \field{descriptionplural} field with the accessibility support + for that field, if provided (otherwise behaves the same as + \cs{glsentrydescplural})}, + topics={fieldrefcommands,access-support}, + note={\styfmt{glossaries-extra}\texparserdefnote}, + category={command} +} + +@glscommand{Glsaccessdescplural, + name={\csfmt{Gls\-access\-desc\-plural}}, + user1={\margm{label}}, + description={expands to the value of the + \field{descriptionplural} field with the first letter converted to + \idx{uppercase} and with the accessibility support + for that field, if provided (otherwise behaves the same as + \cs{Glsentrydescplural})}, + topics={fieldrefcommands,access-support}, + note={\styfmt{glossaries-extra}\texparserdefnote}, + category={command} +} + +@glscommand{glsaccessshort, + name={\csfmt{gls\-access\-short}}, + user1={\margm{label}}, + description={expands to the value of the + \field{short} field with the accessibility support + for that field, if provided (otherwise behaves the same as + \cs{glsentryshort})}, + topics={fieldrefcommands,access-support,abbreviationcommands}, + note={\styfmt{glossaries-extra}\texparserdefnote}, + category={command} +} + +@glscommand{Glsaccessshort, + name={\csfmt{Gls\-access\-short}}, + user1={\margm{label}}, + description={expands to the value of the + \field{short} field with the first letter converted to + \idx{uppercase} and with the accessibility support + for that field, if provided (otherwise behaves the same as + \cs{Glsentryshort})}, + topics={fieldrefcommands,access-support,abbreviationcommands}, + note={\styfmt{glossaries-extra}\texparserdefnote}, + category={command} +} + +@glscommand{glsaccessshortpl, + name={\csfmt{gls\-access\-shortpl}}, + user1={\margm{label}}, + description={expands to the value of the + \field{shortplural} field with the accessibility support + for that field, if provided (otherwise behaves the same as + \cs{glsentryshortpl})}, + topics={fieldrefcommands,access-support,abbreviationcommands}, + note={\styfmt{glossaries-extra}\texparserdefnote}, + category={command} +} + +@glscommand{Glsaccessshortpl, + name={\csfmt{Gls\-access\-shortpl}}, + user1={\margm{label}}, + description={expands to the value of the + \field{shortplural} field with the first letter converted to + \idx{uppercase} and with the accessibility support + for that field, if provided (otherwise behaves the same as + \cs{Glsentryshortpl})}, + topics={fieldrefcommands,access-support,abbreviationcommands}, + note={\styfmt{glossaries-extra}\texparserdefnote}, + category={command} +} + +@glscommand{glsaccesslong, + name={\csfmt{gls\-access\-long}}, + user1={\margm{label}}, + description={expands to the value of the + \field{long} field with the accessibility support + for that field, if provided (otherwise behaves the same as + \cs{glsentrylong})}, + topics={fieldrefcommands,access-support,abbreviationcommands}, + note={\styfmt{glossaries-extra}\texparserdefnote}, + category={command} +} + +@glscommand{Glsaccesslong, + name={\csfmt{Gls\-access\-long}}, + user1={\margm{label}}, + description={expands to the value of the + \field{long} field with the first letter converted to + \idx{uppercase} and with the accessibility support + for that field, if provided (otherwise behaves the same as + \cs{Glsentrylong})}, + topics={fieldrefcommands,access-support,abbreviationcommands}, + note={\styfmt{glossaries-extra}\texparserdefnote}, + category={command} +} + +@glscommand{glsaccesslongpl, + name={\csfmt{gls\-access\-longpl}}, + user1={\margm{label}}, + description={expands to the value of the + \field{longplural} field with the accessibility support + for that field, if provided (otherwise behaves the same as + \cs{glsentrylongpl})}, + topics={fieldrefcommands,access-support,abbreviationcommands}, + note={\styfmt{glossaries-extra}\texparserdefnote}, + category={command} +} + +@glscommand{Glsaccesslongpl, + name={\csfmt{Gls\-access\-longpl}}, + user1={\margm{label}}, + description={expands to the value of the + \field{longplural} field with the first letter converted to + \idx{uppercase} and with the accessibility support + for that field, if provided (otherwise behaves the same as + \cs{Glsentrylongpl})}, + topics={fieldrefcommands,access-support,abbreviationcommands}, + note={\styfmt{glossaries-extra}\texparserdefnote}, + category={command} +} + +@glscommand{glsxtrentryparentname, + name={\csfmt{gls\-xtr\-entry\-parent\-name}}, + user1={\margm{label}}, + description={expands to the entry's parent's name}, + topics={fieldrefcommands}, + note={\styfmt{glossaries-extra}\texparserdefnote\ v1.39+}, + category={command} +} + +@glscommand{glsentryprefix, + name={\csfmt{gls\-entry\-prefix}}, + user1={\margm{label}}, + description={expands to the value of the \field{prefix} field}, + topics={fieldrefcommands}, + note={\styfmt{glossaries-prefix}}, + category={command} +} + +@glscommand{glsentryprefixplural, + name={\csfmt{gls\-entry\-prefix\-plural}}, + user1={\margm{label}}, + description={expands to the value of the \field{prefixplural} field}, + topics={fieldrefcommands}, + note={\styfmt{glossaries-prefix}}, + category={command} +} + +@glscommand{glsentryprefixfirst, + name={\csfmt{gls\-entry\-prefix\-first}}, + user1={\margm{label}}, + description={expands to the value of the \field{prefixfirst} field}, + topics={fieldrefcommands}, + note={\styfmt{glossaries-prefix}}, + category={command} +} + +@glscommand{glsentryprefixfirstplural, + name={\csfmt{gls\-entry\-prefix\-first\-plural}}, + user1={\margm{label}}, + description={expands to the value of the \field{prefixfirstplural} field}, + topics={fieldrefcommands}, + note={\styfmt{glossaries-prefix}}, + category={command} +} + +@glscommand{Glsentryprefix, + name={\csfmt{Gls\-entry\-prefix}}, + user1={\margm{label}}, + description={expands to the value of the \field{prefix} field + with the first letter converted to \idx{uppercase}}, + topics={fieldrefcommands,casecommands}, + note={\styfmt{glossaries-prefix}}, + category={command} +} + +@glscommand{Glsentryprefixplural, + name={\csfmt{Gls\-entry\-prefix\-plural}}, + user1={\margm{label}}, + description={expands to the value of the \field{prefixplural} field + with the first letter converted to \idx{uppercase}}, + topics={fieldrefcommands,casecommands}, + note={\styfmt{glossaries-prefix}}, + category={command} +} + +@glscommand{Glsentryprefixfirst, + name={\csfmt{Gls\-entry\-prefix\-first}}, + user1={\margm{label}}, + description={expands to the value of the \field{prefixfirst} field + with the first letter converted to \idx{uppercase}}, + topics={fieldrefcommands,casecommands}, + note={\styfmt{glossaries-prefix}}, + category={command} +} + +@glscommand{Glsentryprefixfirstplural, + name={\csfmt{Gls\-entry\-prefix\-first\-plural}}, + user1={\margm{label}}, + description={expands to the value of the \field{prefixfirstplural} field + with the first letter converted to \idx{uppercase}}, + topics={fieldrefcommands,casecommands}, + note={\styfmt{glossaries-prefix}}, + category={command} +} + +@glscommand{glssetcategoryattribute, + name={\csfmt{gls\-set\-cat\-e\-gory\-at\-tribute}}, + user1={\margm{category}\margm{attribute}\margm{value}}, + description={sets the value of the attribute for the given +category}, + topics={assigncommands,catattrcommands}, + note={\styfmt{glossaries-extra}}, + category={command} +} + +@glscommand{glsentryaccess, + name={\csfmt{gls\-entry\-access}}, + user1={\margm{label}}, + description={expands to the value of the \field{access} field}, + topics={fieldrefcommands,access-support}, + note={\styfmt{glossaries-access}}, + category={command} +} + +@glscommand{glsentrytextaccess, + name={\csfmt{gls\-entry\-text\-access}}, + user1={\margm{label}}, + description={expands to the value of the \field{textaccess} field}, + topics={fieldrefcommands,access-support}, + note={\styfmt{glossaries-access}}, + category={command} +} + +@glscommand{glsentryfirstaccess, + name={\csfmt{gls\-entry\-first\-access}}, + user1={\margm{label}}, + description={expands to the value of the \field{firstaccess} field}, + topics={fieldrefcommands,access-support}, + note={\styfmt{glossaries-access}}, + category={command} +} + +@glscommand{glsentrypluralaccess, + name={\csfmt{gls\-entry\-plural\-access}}, + user1={\margm{label}}, + description={expands to the value of the \field{pluralaccess} field}, + topics={fieldrefcommands,access-support}, + note={\styfmt{glossaries-access}}, + category={command} +} + +@glscommand{glsentryfirstpluralaccess, + name={\csfmt{gls\-entry\-first\-plural\-access}}, + user1={\margm{label}}, + description={expands to the value of the \field{firstpluralaccess} field}, + topics={fieldrefcommands,access-support}, + note={\styfmt{glossaries-access}}, + category={command} +} + +@glscommand{glsentrysymbolaccess, + name={\csfmt{gls\-entry\-symbol\-access}}, + user1={\margm{label}}, + description={expands to the value of the \field{symbolaccess} field}, + topics={fieldrefcommands,access-support}, + note={\styfmt{glossaries-access}}, + category={command} +} + +@glscommand{glsentrysymbolpluralaccess, + name={\csfmt{gls\-entry\-symbol\-plural\-access}}, + user1={\margm{label}}, + description={expands to the value of the \field{symbolpluralaccess} field}, + topics={fieldrefcommands,access-support}, + note={\styfmt{glossaries-access}}, + category={command} +} + +@glscommand{glsentrydescaccess, + name={\csfmt{gls\-entry\-desc\-access}}, + user1={\margm{label}}, + description={expands to the value of the \field{descriptionaccess} field}, + topics={fieldrefcommands,access-support}, + note={\styfmt{glossaries-access}}, + category={command} +} + +@glscommand{glsentrydescpluralaccess, + name={\csfmt{gls\-entry\-desc\-plural\-access}}, + user1={\margm{label}}, + description={expands to the value of the \field{descriptionpluralaccess} field}, + topics={fieldrefcommands,access-support}, + note={\styfmt{glossaries-access}}, + category={command} +} + +@glscommand{glsentryshortaccess, + name={\csfmt{gls\-entry\-short\-access}}, + user1={\margm{label}}, + description={expands to the value of the \field{shortaccess} field}, + topics={fieldrefcommands,access-support,abbreviationcommands}, + note={\styfmt{glossaries-access}}, + category={command} +} + +@glscommand{glsentryshortpluralaccess, + name={\csfmt{gls\-entry\-short\-plural\-access}}, + user1={\margm{label}}, + description={expands to the value of the \field{shortpluralaccess} field}, + topics={fieldrefcommands,access-support,abbreviationcommands}, + note={\styfmt{glossaries-access}}, + category={command} +} + +@glscommand{glsentrylongaccess, + name={\csfmt{gls\-entry\-long\-access}}, + user1={\margm{label}}, + description={expands to the value of the \field{longaccess} field}, + topics={fieldrefcommands,access-support,abbreviationcommands}, + note={\styfmt{glossaries-access}}, + category={command} +} + +@glscommand{glsentrylongpluralaccess, + name={\csfmt{gls\-entry\-long\-plural\-access}}, + user1={\margm{label}}, + description={expands to the value of the \field{longpluralaccess} field}, + topics={fieldrefcommands,access-support,abbreviationcommands}, + note={\styfmt{glossaries-access}}, + category={command} +} + +@glscommand{glsnameaccessdisplay, + name={\csfmt{gls\-name\-access\-display}}, + user1={\margm{text}\margm{label}}, + description={displays \meta{text} with the accessibility support + provided by \code{\cs{glsentryaccess}\margm{label}}}, + topics={fieldrefcommands,access-support}, + note={\styfmt{glossaries-access}}, + category={command} +} + +@glscommand{glstextaccessdisplay, + name={\csfmt{gls\-text\-access\-display}}, + user1={\margm{text}\margm{label}}, + description={displays \meta{text} with the accessibility support + provided by \code{\cs{glsentrytextaccess}\margm{label}}}, + topics={fieldrefcommands,access-support}, + note={\styfmt{glossaries-access}}, + category={command} +} + +@glscommand{glspluralaccessdisplay, + name={\csfmt{gls\-plural\-access\-display}}, + user1={\margm{text}\margm{label}}, + description={displays \meta{text} with the accessibility support + provided by \code{\cs{glsentrypluralaccess}\margm{label}}}, + topics={fieldrefcommands,access-support}, + note={\styfmt{glossaries-access}}, + category={command} +} + +@glscommand{glsfirstaccessdisplay, + name={\csfmt{gls\-first\-access\-display}}, + user1={\margm{text}\margm{label}}, + description={displays \meta{text} with the accessibility support + provided by \code{\cs{glsentryfirstaccess}\margm{label}}}, + topics={fieldrefcommands,access-support}, + note={\styfmt{glossaries-access}}, + category={command} +} + +@glscommand{glsfirstpluralaccessdisplay, + name={\csfmt{gls\-first\-plural\-access\-display}}, + user1={\margm{text}\margm{label}}, + description={displays \meta{text} with the accessibility support + provided by \code{\cs{glsentryfirstpluralaccess}\margm{label}}}, + topics={fieldrefcommands,access-support}, + note={\styfmt{glossaries-access}}, + category={command} +} + +@glscommand{glssymbolaccessdisplay, + name={\csfmt{gls\-symbol\-access\-display}}, + user1={\margm{text}\margm{label}}, + description={displays \meta{text} with the accessibility support + provided by \code{\cs{glsentrysymbolaccess}\margm{label}}}, + topics={fieldrefcommands,access-support}, + note={\styfmt{glossaries-access}}, + category={command} +} + +@glscommand{glssymbolpluralaccessdisplay, + name={\csfmt{gls\-symbol\-plural\-access\-display}}, + user1={\margm{text}\margm{label}}, + description={displays \meta{text} with the accessibility support + provided by \code{\cs{glsentrysymbolpluralaccess}\margm{label}}}, + topics={fieldrefcommands,access-support}, + note={\styfmt{glossaries-access}}, + category={command} +} + +@glscommand{glsdescriptionaccessdisplay, + name={\csfmt{gls\-descrip\-tion\-access\-display}}, + user1={\margm{text}\margm{label}}, + description={displays \meta{text} with the accessibility support + provided by \code{\cs{glsentrydescaccess}\margm{label}}}, + topics={fieldrefcommands,access-support}, + note={\styfmt{glossaries-access}}, + category={command} +} + +@glscommand{glsdescriptionpluralaccessdisplay, + name={\csfmt{gls\-descrip\-tion\-plural\-access\-display}}, + user1={\margm{text}\margm{label}}, + description={displays \meta{text} with the accessibility support + provided by \code{\cs{glsentrydescpluralaccess}\margm{label}}}, + topics={fieldrefcommands,access-support}, + note={\styfmt{glossaries-access}}, + category={command} +} + +@glscommand{glsshortaccessdisplay, + name={\csfmt{gls\-short\-access\-display}}, + user1={\margm{text}\margm{label}}, + description={displays \meta{text} with the accessibility support + provided by \code{\cs{glsentryshortaccess}\margm{label}}}, + topics={fieldrefcommands,access-support,abbreviationcommands}, + note={\styfmt{glossaries-access}}, + category={command} +} + +@glscommand{glsshortpluralaccessdisplay, + name={\csfmt{gls\-short\-plural\-access\-display}}, + user1={\margm{text}\margm{label}}, + description={displays \meta{text} with the accessibility support + provided by \code{\cs{glsentryshortpluralaccess}\margm{label}}}, + topics={fieldrefcommands,access-support,abbreviationcommands}, + note={\styfmt{glossaries-access}}, + category={command} +} + +@glscommand{glslongaccessdisplay, + name={\csfmt{gls\-long\-access\-display}}, + user1={\margm{text}\margm{label}}, + description={displays \meta{text} with the accessibility support + provided by \code{\cs{glsentrylongaccess}\margm{label}}}, + topics={fieldrefcommands,access-support,abbreviationcommands}, + note={\styfmt{glossaries-access}}, + category={command} +} + +@glscommand{glslongpluralaccessdisplay, + name={\csfmt{gls\-long\-plural\-access\-display}}, + user1={\margm{text}\margm{label}}, + description={displays \meta{text} with the accessibility support + provided by \code{\cs{glsentrylongpluralaccess}\margm{label}}}, + topics={fieldrefcommands,access-support,abbreviationcommands}, + note={\styfmt{glossaries-access}}, + category={command} +} + +@glscommand{glsaccessdisplay, + name={\csfmt{gls\-access\-display}}, + user1={\margm{field}\margm{text}\margm{label}}, + description={displays \meta{text} with the accessibility support + provided by \code{\csfmt{glsentry\meta{field}access}\margm{label}}}, + topics={fieldrefcommands,access-support}, + note={\styfmt{glossaries-access}}, + category={command} +} + +@glscommand{glsxtrpostlinkAddDescOnFirstUse, + name={\csfmt{gls\-xtr\-post\-link\-Add\-Desc\-On\-First\-Use}}, + description={only for use in the post-link hooks, + this appends a space and the value of the + \field{description} field in parentheses + if the entry that was just referenced was used for the + first time}, + topics={hooks}, + note={\styfmt{glossaries-extra}}, + category={command} +} + +@glscommand{glsxtrpostlinkAddSymbolOnFirstUse, + name={\csfmt{gls\-xtr\-post\-link\-Add\-Symbol\-On\-First\-Use}}, + description={only for use in the post-link hooks, + this appends a space and the value of the + \field{symbol} field in parentheses + if the entry that was just referenced was used for the + first time and has the \field{symbol} field set}, + topics={hooks}, + note={\styfmt{glossaries-extra}}, + category={command} +} + +@glscommand{glsxtrpostlinkAddSymbolDescOnFirstUse, + name={\csfmt{gls\-xtr\-post\-link\-Add\-Symbol\-Desc\-On\-First\-Use}}, + description={only for use in the post-link hooks, if the + entry that was just referenced was used for the first time, + this appends a space and, in parentheses, the value of the + \field{symbol} field (if set) + followed by the value of the \field{description} field}, + topics={hooks}, + note={\styfmt{glossaries-extra} v1.31+}, + category={command} +} + +@glscommand{glspluralsuffix, + name={\csfmt{gls\-plural\-suffix}}, + user1={}, + description={the suffix used to construct the default plural}, + topics={fixedtextcommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{acrpluralsuffix, + name={\csfmt{acr\-plural\-suffix}}, + user1={}, + description={the suffix used to construct the default plural for + the short form of acronyms using the base \sty{glossaries} + package's acronym mechanism (not used with the + \sty{glossaries-extra} enhanced abbreviation mechanism)}, + topics={fixedtextcommands,abbreviationcommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{abbrvpluralsuffix, + name={\csfmt{abbrv\-plural\-suffix}}, + user1={}, + description={the style sensitive suffix used to construct the + default plural for the short form of abbreviations}, + topics={fixedtextcommands,abbreviationcommands}, + note={\styfmt{glossaries-extra}\texparserdefnote}, + seealso={glsxtrabbrvpluralsuffix}, + category={command} +} + +@abbrvstylecommand{glsxtrabbrvpluralsuffix, + name={\csfmt{gls\-xtr\-abbrv\-plural\-suffix}}, + user1={}, + description={the default suffix used to construct the plural for + the short form of abbreviations. This just uses + \cs{glspluralsuffix}. If you don't want a plural suffix, you can + use the \catattr{noshortplural} attribute}, + note={\styfmt{glossaries-extra}\texparserdefnote}, + topics={abbrstyle.long-short,abbrstyle.short-long,abbrstyle.short-footnote,abbrstyle.short-postfootnote,abbrstyle.short-nolong,abbrstyle.nolong-short,abbrstyle.nolong-short-noreg,abbrstyle.short-nolong-desc,abbrstyle.long-noshort-desc,abbrstyle.long-noshort-desc-noreg,abbrstyle.long-hyphen-noshort-desc-noreg,abbrstyle.long-hyphen-noshort-noreg,abbrstyle.long-noshort,abbrstyle.long-noshort-noreg,abbrstyle.long-short-desc}, + category={command} +} + +@glscommand{glsdefpostlink, + name={\csfmt{gls\-def\-post\-link}}, + user1={\margm{category}\margm{definition}}, + description={define the post-link hook + \cs{glsxtrpostlinkcategory} for the given category}, + topics={hooks,providingcommands}, + note={\styfmt{glossaries-extra} v1.31+}, + category={command} +} + +@glscommand{glsdefpostname, + name={\csfmt{gls\-def\-post\-name}}, + user1={\margm{category}\margm{definition}}, + description={define the post-name hook + \cs{glsxtrpostnamecategory} for the given category}, + topics={hooks,providingcommands}, + note={\styfmt{glossaries-extra} v1.31+}, + category={command} +} + +@glscommand{glsdefpostdesc, + name={\csfmt{gls\-def\-post\-desc}}, + user1={\margm{category}\margm{definition}}, + description={define the post-description hook + \csfmt{glsxtrpostdesc}\meta{category} for the given category}, + topics={hooks,providingcommands}, + note={\styfmt{glossaries-extra} v1.31+}, + category={command} +} + +@glscommand{glsxtrifwasfirstuse, + name={\csfmt{glsxtr\-if\-was\-first\-use}}, + user1={\margm{true}\margm{false}}, + description={only for use in the post-link hooks this + tests if the entry just referenced was used for the first time}, + topics={hooks,conditionals}, + note={\styfmt{glossaries-extra}}, + category={command} +} + +@glscommand{ifglsused, + name={\csfmt{if\-gls\-used}}, + user1={\margm{label}\margm{true}\margm{false}}, + description={does \meta{true} if the entry given by \meta{label} has been + used, \meta{false} if the entry hasn't been used and neither + if the entry doesn't exist (an error or warning message will + occur and ?? will appear in the document). + This command is not for use in the post-link hooks}, + topics={conditionals,entryrefcommands}, + note={\styfmt{glossaries}}, + seealso={GlsXtrIfUnusedOrUndefined,glsxtrifwasfirstuse}, + category={command} +} + +@glscommand{GlsXtrIfUnusedOrUndefined, + name={\csfmt{Gls\-Xtr\-If\-Un\-used\-Or\-Un\-defined}}, + user1={\margm{label}\margm{true}\margm{false}}, + description={does \meta{true} if the entry given by \meta{label} +hasn't been + used or is undefined, otherwise it does \meta{false}. + This command is not for use in the post-link hooks}, + topics={conditionals}, + note={\styfmt{glossaries-extra} v1.34+}, + seealso={ifglsused,glsxtrifwasfirstuse}, + category={command} +} + +@glscommand{GlsXtrLocationField, + name={\csfmt{GlsXtrLocationField}}, + user1={}, + description={expands to the internal name of the field storing the +location list, defaulting to \field{location}}, + topics={fieldrefcommands,loclistcommands}, + note={\styfmt{glossaries-extra} v1.37+}, + category={command} +} + +@glscommand{glslabel, + name={\csfmt{glslabel}}, + user1={}, + description={only for use in the post-link hooks, this + expands to the label of the entry that was last referenced}, + topics={hooks}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glscurrententrylabel, + name={\csfmt{gls\-current\-entry\-label}}, + user1={}, + description={only for use in the glossary, such as in the style or +in the post-name or post-description hooks, this expands to the +label of the current entry}, + topics={hooks}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glscurrentfieldvalue, + name={\csfmt{gls\-current\-field\-value}}, + user1={}, + description={only for use in the \meta{true} part of +\cs{ifglshasfield} or \cs{glsxtrifhasfield}, this expands to the +field value}, + topics={conditionals}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glsentrytitlecase, + name={\csfmt{gls\-entry\-title\-case}}, + user1={\margm{entry label}\margm{field label}}, + description={fetches the given field and applies + \ics{capitalisewords} to it}, + topics={casecommands,fieldrefcommands}, + note={\styfmt{glossaries}\texparserdefnote\ v4.22+}, + category={command} +} + +@command{capitalisewords, + name={\csfmt{capitalise\-words}}, + user1={\margm{text}}, + description={converts the first letter of each word to + \idx{uppercase} using \ics{makefirstuc}}, + note={\styfmt{mfirstuc}\texparserdefnote\ v1.06+}, + category={command} +} + +@command{MFUnocap, + name={\csfmt{MFU\-no\-cap}}, + user1={\margm{word}}, + description={identifies \meta{word} as one that + should not have its case-changed by \ics{capitalisewords} + unless it occurs at the start}, + note={\styfmt{mfirstuc}\texparserdefnote\ v1.09+}, + category={command} +} + +@glscommand{glsxtrusefield, + name={\csfmt{gls\-xtr\-use\-field}}, + user1={\margm{entry label}\margm{field label}}, + description={expands to the value of the given field for the given + entry}, + topics={fieldrefcommands}, + note={\styfmt{glossaries-extra}\texparserdefnote\ v1.12+}, + category={command} +} + +@glscommand{Glsxtrusefield, + name={\csfmt{Gls\-xtr\-use\-field}}, + user1={\margm{entry label}\margm{field label}}, + description={like \cs{glsxtrusefield} but converts the first + letter to \idx!{uppercase}}, + topics={fieldrefcommands,casecommands}, + note={\styfmt{glossaries-extra}\texparserdefnote\ v1.12+}, + category={command} +} + +@glscommand{GLSxtrusefield, + name={\csfmt{GLS\-xtr\-use\-field}}, + user1={\margm{entry label}\margm{field label}}, + description={as \cs{glsxtrusefield} but converts the value to + \idx{uppercase}}, + topics={fieldrefcommands,casecommands}, + note={\styfmt{glossaries-extra}\texparserdefnote\ v1.37+}, + category={command} +} + +@glscommand{GlsXtrSetField, + name={\csfmt{Gls\-Xtr\-Set\-Field}}, + user1={\margm{entry label}\margm{field label}\margm{value}}, + description={assigns the given \meta{value} to the field + identified by \meta{field label} for the + entry identified by \meta{entry label}}, + topics={assigncommands}, + note={\styfmt{glossaries-extra} v1.12+}, + category={command} +} + +@glscommand{xGlsXtrSetField, + name={\csfmt{xGls\-Xtr\-Set\-Field}}, + user1={\margm{entry label}\margm{field label}\margm{value}}, + description={globally assigns the (protected) full expansion of the given \meta{value} to the field + identified by \meta{field label} for the + entry identified by \meta{entry label}}, + topics={assigncommands}, + note={\styfmt{glossaries-extra} v1.12+}, + category={command} +} + +@glscommand{glsxtrifhasfield, + name={\csfmt{gls\-xtr\-if\-has\-field}}, + user1={\margm{field label}\margm{entry label}\margm{true}\margm{false}}, + description={tests if the given entry has the given \emph{internal} field set + (defined and not empty) + without testing if the entry exists and adds implicit scoping + to \meta{true} and \meta{false}}, + topics={conditionals,fieldrefcommands}, + note={\styfmt{glossaries-extra} v1.19+}, + seealso={GlsXtrIfFieldUndef}, + category={command} +} + +@glscommand{glsxtrifhasfield*, + name={\csfmt{gls\-xtr\-if\-has\-field*}}, + user1={\margm{field label}\margm{entry label}\margm{true}\margm{false}}, + description={tests if the given entry has the given field set + (defined and not empty) + without testing if the entry exists and without introducing + an implicit scope}, + topics={conditionals,fieldrefcommands}, + note={\styfmt{glossaries-extra} v1.19+}, + seealso={GlsXtrIfFieldUndef}, + category={command} +} + +@glscommand{GlsXtrIfFieldUndef, + name={\csfmt{Gls\-Xtr\-If\-Field\-Undef}}, + user1={\margm{field label}\margm{entry label}\margm{true}\margm{false}}, + description={tests if the given field isn't defined for the given + entry, which may also not exist}, + topics={conditionals,fieldrefcommands}, + note={\styfmt{glossaries-extra} v1.23+}, + category={command} +} + +@glscommand{GlsXtrIfFieldEqStr, + name={\csfmt{Gls\-Xtr\-If\-Field\-Eq\-Str}}, + user1={\margm{field label}\margm{entry label}\margm{text}\margm{true}\margm{false}}, + description={tests if the given field value is the same as + \meta{text} for the given entry, which may not exist. The unstarred +form adds implicit grouping. The starred form (new to v1.39) +doesn't}, + topics={conditionals,fieldrefcommands}, + note={\styfmt{glossaries-extra} v1.21+}, + category={command} +} + +@glscommand{GlsXtrIfFieldEqXpStr, + name={\csfmt{Gls\-Xtr\-If\-Field\-Eq\-Xp\-Str}}, + user1={\margm{field label}\margm{entry label}\margm{text}\margm{true}\margm{false}}, + description={like \cs{GlsXtrIfFieldEqStr} but first (protected) +fully expands \meta{text} (but not the field value). The unstarred +form adds implicit grouping. The starred form (new to v1.39) +doesn't}, + topics={conditionals,fieldrefcommands}, + note={\styfmt{glossaries-extra} v1.31+}, + category={command} +} + +@glscommand{GlsXtrIfXpFieldEqXpStr, + name={\csfmt{Gls\-Xtr\-If\-Xp\-Field\-Eq\-Xp\-Str}}, + user1={\margm{field label}\margm{entry label}\margm{text}\margm{true}\margm{false}}, + description={like \cs{GlsXtrIfFieldEqStr} but first (protected) +fully expands both the field value and \meta{text}. The unstarred +form adds implicit grouping. The starred form (new to v1.39) +doesn't}, + topics={conditionals,fieldrefcommands}, + note={\styfmt{glossaries-extra} v1.31+}, + category={command} +} + +@glscommand{ifglshasfield, + name={\csfmt{if\-gls\-has\-field}}, + user1={\margm{field label}\margm{entry label}\margm{true}\margm{false}}, + description={tests if the given entry, which must be defined, has the + given field set to a non-empty value}, + note={\styfmt{glossaries}}, + topics={conditionals,fieldrefcommands}, + seealso={glsxtrifhasfield,GlsXtrIfFieldUndef}, + category={command} +} + +@glscommand{ifglshassymbol, + name={\csfmt{if\-gls\-has\-symbol}}, + user1={\margm{entry label}\margm{true}\margm{false}}, + description={tests if the given entry, which must be defined, has the + \field{symbol} field set to value that's not empty and not + \csfmt{relax}}, + topics={conditionals,fieldrefcommands}, + note={\styfmt{glossaries}}, + seealso={ifglshasdesc,glsxtrifhasfield,GlsXtrIfFieldUndef}, + category={command} +} + +@glscommand{ifglshasdesc, + name={\csfmt{if\-gls\-has\-desc}}, + user1={\margm{entry label}\margm{true}\margm{false}}, + description={tests if the given entry, which must be defined, has the + \field{description} field set}, + topics={conditionals,fieldrefcommands}, + note={\styfmt{glossaries}}, + seealso={ifglshassymbol,ifglshasdescsuppressed}, + category={command} +} + +@glscommand{ifglshasdescsuppressed, + name={\csfmt{if\-gls\-has\-suppressedesc}}, + user1={\margm{entry label}\margm{true}\margm{false}}, + description={tests if the given entry, which must be defined, has the + \field{description} field set to \cs{nopostdesc}}, + topics={conditionals,fieldrefcommands}, + note={\styfmt{glossaries}}, + seealso={ifglshasdesc}, + category={command} +} + +@glscommand{ifglshasparent, + name={\csfmt{if\-gls\-has\-parent}}, + user1={\margm{entry label}\margm{true}\margm{false}}, + description={tests if the given entry, which must be defined, has the + \field{parent} field set}, + topics={conditionals,fieldrefcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{ifglshaschildren, + name={\csfmt{if\-gls\-has\-children}}, + user1={\margm{entry label}\margm{true}\margm{false}}, + description={tests if the given entry, which must be defined, has + child entries. This method is inefficient as it has to + iterate over all defined entries to determine which ones + have \meta{entry label} as the value of the \field{parent} + field. With \bibgls, a more efficient approach is to + use \csopt{save-child-count} and test the value of + the \field{childcount} field}, + topics={conditionals,fieldrefcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{ifglshasshort, + name={\csfmt{if\-gls\-has\-short}}, + user1={\margm{entry label}\margm{true}\margm{false}}, + description={tests if the given entry, which must be defined, has the + \field{short} field set}, + topics={conditionals,fieldrefcommands,abbreviationcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{ifglshaslong, + name={\csfmt{if\-gls\-has\-long}}, + user1={\margm{entry label}\margm{true}\margm{false}}, + description={tests if the given entry, which must be defined, has the + \field{long} field set}, + topics={conditionals,fieldrefcommands,abbreviationcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{ifglshasprefix, + name={\csfmt{if\-gls\-has\-prefix}}, + user1={\margm{entry label}\margm{true}\margm{false}}, + description={tests if the given entry, which must be defined, has the + \field{prefix} field set to value that's not empty}, + topics={conditionals,fieldrefcommands}, + note={\styfmt{glossaries-prefix}}, + seealso={ifglshasdesc,glsxtrifhasfield,GlsXtrIfFieldUndef}, + category={command} +} + +@glscommand{ifglshasprefixplural, + name={\csfmt{if\-gls\-has\-prefix\-plural}}, + user1={\margm{entry label}\margm{true}\margm{false}}, + description={tests if the given entry, which must be defined, has the + \field{prefixplural} field set to value that's not empty}, + topics={conditionals,fieldrefcommands}, + note={\styfmt{glossaries-prefix}}, + seealso={ifglshasdesc,glsxtrifhasfield,GlsXtrIfFieldUndef}, + category={command} +} + +@glscommand{ifglshasprefixfirst, + name={\csfmt{if\-gls\-has\-prefix\-first}}, + user1={\margm{entry label}\margm{true}\margm{false}}, + description={tests if the given entry, which must be defined, has the + \field{prefixfirst} field set to value that's not empty}, + topics={conditionals,fieldrefcommands}, + note={\styfmt{glossaries-prefix}}, + seealso={ifglshasdesc,glsxtrifhasfield,GlsXtrIfFieldUndef}, + category={command} +} + +@glscommand{ifglshasprefixfirstplural, + name={\csfmt{if\-gls\-has\-prefix\-first\-plural}}, + user1={\margm{entry label}\margm{true}\margm{false}}, + description={tests if the given entry, which must be defined, has the + \field{prefixfirstplural} field set to value that's not empty}, + topics={conditionals,fieldrefcommands}, + note={\styfmt{glossaries-prefix}}, + seealso={ifglshasdesc,glsxtrifhasfield,GlsXtrIfFieldUndef}, + category={command} +} + +@glscommand{ifglsfieldeq, + name={\csfmt{if\-gls\-field\-eq}}, + user1={\margm{entry label}\margm{field label}\margm{string}\margm{true}\margm{false}}, + description={tests if the given entry has the + given field value equal to \meta{string}, where \meta{field label} + is the internal field label (not the key name). No expansion is + performed in the test (which just uses \cs{ifcsstring})}, + topics={conditionals,fieldrefcommands}, + note={\styfmt{glossaries} v4.16+}, + category={command} +} + +@glscommand{ifglsfielddefeq, + name={\csfmt{if\-gls\-field\-def\-eq}}, + user1={\margm{entry label}\margm{field label}\margm{cs}\margm{true}\margm{false}}, + description={tests if the given entry has the + given field value equal to the replacement text of the command + given by \meta{cs}, where \meta{field label} + is the internal field label (not the key name). The test + uses \cs{ifdefstrequal}}, + topics={conditionals,fieldrefcommands}, + note={\styfmt{glossaries} v4.16+}, + category={command} +} + +@glscommand{ifglsfieldcseq, + name={\csfmt{if\-gls\-field\-cs\-eq}}, + user1={\margm{entry label}\margm{field label}\margm{cs-name}\margm{true}\margm{false}}, + description={tests if the given entry has the + given field value equal to the replacement text of the command + given by the control sequence name \meta{cs-name}, where \meta{field label} + is the internal field label (not the key name). The test + uses \cs{ifcsstrequal}}, + topics={conditionals,fieldrefcommands}, + note={\styfmt{glossaries} v4.16+}, + category={command} +} + +@glscommand{glsfielddef, + name={\csfmt{gls\-field\-def}}, + user1={\margm{entry label}\margm{field label}\margm{definition}}, + description={changes the value of the given + entry's field to \meta{definition} (localised by any scope)}, + topics={fieldrefcommands,assigncommands}, + note={\styfmt{glossaries} v4.16+}, + category={command} +} + +@glscommand{glsfieldgdef, + name={\csfmt{gls\-field\-gdef}}, + user1={\margm{entry label}\margm{field label}\margm{definition}}, + description={globally changes the value of the given + entry's field to \meta{definition}}, + topics={fieldrefcommands,assigncommands}, + note={\styfmt{glossaries} v4.16+}, + category={command} +} + +@glscommand{glsfieldedef, + name={\csfmt{gls\-field\-edef}}, + user1={\margm{entry label}\margm{field label}\margm{definition}}, + description={changes the value of the given entry's field to the + full expansion of \meta{definition} (localised by any scope)}, + topics={fieldrefcommands,assigncommands}, + note={\styfmt{glossaries} v4.16+}, + category={command} +} + +@glscommand{glsfieldxdef, + name={\csfmt{gls\-field\-xdef}}, + user1={\margm{entry label}\margm{field label}\margm{definition}}, + description={globally changes the value of the given entry's field to the + full expansion of \meta{definition}}, + topics={fieldrefcommands,assigncommands}, + note={\styfmt{glossaries} v4.16+}, + category={command} +} + +@glscommand{GlsXtrIfFieldNonZero, + name={\csfmt{Gls\-Xtr\-If\-Field\-Non\-Zero}}, + user1={\margm{field}\margm{entry label}\margm{true}\margm{false}}, + description={tests if the given field value expands to a non-zero +integer. If the field is undefined or empty, the value is assumed to +be 0. If the field is set, it must expand to an integer value. +The value can be referenced in \meta{true} or \meta{false} +with \cs{glscurrentfieldvalue}. The unstarred +form adds implicit grouping. The starred form (new to v1.39) +doesn't}, + topics={conditionals,fieldrefcommands}, + note={\styfmt{glossaries-extra} v1.31+}, + seealso={GlsXtrIfFieldEqNum}, + category={command} +} + +@glscommand{GlsXtrIfFieldEqNum, + name={\csfmt{Gls\-Xtr\-If\-Field\-Eq\-Num}}, + user1={\margm{field}\margm{entry label}\margm{number}\margm{true}\margm{false}}, + description={tests if the given field value expands to the given +integer \meta{number}. If the field is undefined or empty, the value is assumed to +be 0. If the field is set, it must expand to an integer value. +The value can be referenced in \meta{true} or \meta{false} +with \cs{glscurrentfieldvalue}. The unstarred +form adds implicit grouping. The starred form (new to v1.39) +doesn't}, + topics={conditionals,fieldrefcommands}, + note={\styfmt{glossaries-extra} v1.31+}, + seealso={GlsXtrIfFieldNonZero,GlsXtrIfFieldCmpNum}, + category={command} +} + +@glscommand{GlsXtrIfFieldCmpNum, + name={\csfmt{Gls\-Xtr\-If\-Field\-Cmp\-Num}}, + user1={\margm{field}\margm{entry label}\margm{comparison}\margm{number}\margm{true}\margm{false}}, + description={compares the given (numerical) field value to the given +integer \meta{number}. The \meta{comparison} may be one of: +\code{=}, \code{<} or \code{>}. If the field is undefined or empty, the value is assumed to +be 0. If the field is set, it must expand to an integer value. +The value can be referenced in \meta{true} or \meta{false} +with \cs{glscurrentfieldvalue}. The unstarred +form adds implicit grouping. The starred form (new to v1.39) +doesn't}, + topics={conditionals,fieldrefcommands}, + note={\styfmt{glossaries-extra} v1.31+}, + seealso={GlsXtrIfFieldNonZero}, + category={command} +} + +@mainglscommand{GlsXtrIfHasNonZeroChildCount, + name={\csfmt{Gls\-Xtr\-If\-Has\-Non\-Zero\-Child\-Count}}, + user1={\margm{entry label}\margm{true}\margm{false}}, + description={for use with the \csopt{save-child-count} resource +option, this uses \cs{GlsXtrIfFieldNonZero} to test if the +\field{childcount} field has a non-zero value. The value +can be referenced in \meta{true} or \meta{false} with +\cs{glscurrentfieldvalue}}, + topics={conditionals,fieldrefcommands}, + note={\styfmt{glossaries-extra-bib2gls} v1.31+}, + seealso={GlsXtrIfFieldNonZero}, + category={command} +} + +@mainglscommand{glsxtrifcustomdiscardperiod, + name={\csfmt{gls\-xtr\-if\-custom\-discard\-period}}, + user1={\margm{true}\margm{false}}, + description={should expand to \meta{true} if the post-link hook + should check for a following full stop (in addition to attribute + checks) otherwise should expand to \meta{false}}, + topics={conditionals,hooks}, + note={\styfmt{glossaries-extra} v1.23+}, + category={command} +} + +@glscommand{glsaddkey, + name={\csfmt{gls\-add\-key}}, + user1={\margm{key}\margm{default value}\margm{no link cs}\margm{no link ucfirst cs}\margm{link cs}\margm{link ucfirst cs}\margm{link allcaps cs}}, + description={adds a new key for use in \csref{newglossaryentry} + and associated commands to access it}, + topics={definingterms,providingcommands,linkcommands,fieldrefcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glsxtrprovidestoragekey, + name={\csfmt{gls\-xtr\-provide\-storage\-key}}, + user1={\margm{key}\margm{default value}\margm{no link cs}}, + description={adds a new key, if not already defined, for use in +\csref{newglossaryentry} + and an associated command + to access it where (unlike \cs{glsaddstoragekey}) + the \meta{no link cs} part may be empty if unrequired}, + topics={definingterms,providingcommands,fieldrefcommands}, + note={\styfmt{glossaries-extra} v1.12+}, + category={command} +} + +@glscommand{glsaddstoragekey, + name={\csfmt{gls\-add\-storage\-key}}, + user1={\margm{key}\margm{default value}\margm{no link cs}}, + description={adds a new key for internal use that can be set in + \csref{newglossaryentry}}, + topics={definingterms,providingcommands,fieldrefcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glsautoprefix, + name={\csfmt{gls\-auto\-prefix}}, + description={prefix used for the automatically labelling triggered + by the \styopt[autolabel]{numberedsection} option}, + topics={hooks,crossrefcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glsenablehyper, + name={\csfmt{gls\-enable\-hyper}}, + description={enables the creation of hyperlinks and targets for + the glossary commands that support them (automatically implemented + if \sty{hyperref} is loaded before \sty{glossaries})}, + topics={linkcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glsdisablehyper, + name={\csfmt{gls\-disable\-hyper}}, + description={disables the creation of hyperlinks and targets for + the glossary commands that support them (automatically implemented + if \sty{hyperref} isn't loaded before \sty{glossaries})}, + topics={linkcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{GlsXtrEnableInitialTagging, + name={\csfmt{Gls\-Xtr\-Enable\-Initial\-Tagging}}, + user1={\margm{category list}\margm{cs}}, + description={defines the control sequence \meta{cs} + to be used with abbreviation tagging + with the given categories}, + topics={abbreviationcommands,formattingcommands}, + note={\styfmt{glossaries-extra}\texparserdefnote}, + category={command} +} + +@glscommand{glsxtrtagfont, + name={\csfmt{gls\-xtr\-tag\-font}}, + user1={\margm{text}}, + description={font used by tagging command defined by + \cs{GlsXtrEnableInitialTagging}}, + note={\styfmt{glossaries-extra}}, + topics={abbreviationcommands,formattingcommands}, + category={command}, + seealso={GlsXtrEnableInitialTagging} +} + +@glscommand{glsnavhypertarget, + name={\csfmt{gls\-nav\-hyper\-target}}, + user1={\oargm{type}\margm{label}\margm{text}}, + description={creates a hyper target for the group given by + \meta{label} for the given glossary type and uses \meta{text} + for the hyperlink text}, + topics={linkcommands,entryrefcommands}, + note={\styfmt{glossary-hypernav}}, + category={command} +} + +@glscommand{newentry, + name={\csfmt{newentry}}, + user1={\margm{label}\margm{\keyvallist}}, + description={equivalent to \csref{newglossaryentry}}, + topics={definingterms,shortcutcommands}, + note={\styfmt{glossaries-extra} \styopt{shortcuts}}, + category={command} +} + +@glscommand{newsym, + name={\csfmt{newsym}}, + user1={\margm{label}\margm{\keyvallist}\margm{symbol}}, + description={equivalent to \csref{glsxtrnewsymbol}}, + note={\styfmt{glossaries-extra} \styopt{shortcuts}}, + topics={definingterms,shortcutcommands}, + category={command} +} + +@glscommand{newnum, + name={\csfmt{newnum}}, + user1={\margm{label}\margm{\keyvallist}}, + description={equivalent to \csref{glsxtrnewnumber}}, + topics={definingterms,shortcutcommands}, + note={\styfmt{glossaries-extra} \styopt{shortcuts}}, + category={command} +} + +@glscommand{acronymtype, + name={\csfmt{acronym\-type}}, + user1={}, + description={expands to the default acronym glossary type when using + \csref{newacronym}}, + topics={glossrefs}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glsxtrabbrvtype, + name={\csfmt{gls\-xtr\-abbrv\-type}}, + user1={}, + description={expands to the default glossary type when using + \csref{newabbreviation}}, + topics={glossrefs}, + note={\styfmt{glossaries-extra}}, + category={command} +} + +@glscommand{nopostdesc, + name={\csfmt{no\-post\-desc}}, + user1={}, + description={suppresses the post-description hook}, + topics={hooks}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glsxtrnopostpunc, + name={\csfmt{gls\-xtr\-no\-post\-punc}}, + user1={}, + description={suppresses the post-description punctuation + without suppressing the post-description hook}, + topics={hooks}, + note={\styfmt{glossaries-extra} v1.22+}, + category={command} +} + +@glscommand{glsxtrrestorepostpunc, + name={\csfmt{gls\-xtr\-restore\-post\-punc}}, + user1={}, + description={used within post-description category hooks, + this restores the post-description punctuation + if it's been suppressed with \cs{glsxtrnopostpunc}}, + topics={hooks}, + note={\styfmt{glossaries-extra} v1.23+}, + category={command} +} + +@glscommand{loadglsentries, + name={\csfmt{load\-gls\-entries}}, + user1={\oargm{type}\margm{file}}, + description={locally redefines \cs{glsdefaulttype} + to \meta{type} and inputs \meta{file}}, + topics={definingterms}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{newglossary, + name={\csfmt{newglossary}}, + user1={\oargm{log}\margm{type}\margm{gls}\margm{glo}\margm{title}}, + description={defines a new glossary identified by \meta{type} + with the given title and associated file extensions used by + \appfmt{makeindex} or \appfmt{xindy}}, + topics={glossrefs}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{newglossary*, + name={\csfmt{newglossary*}}, + user1={\margm{type}\margm{title}}, + description={defines a new glossary identified by \meta{type} + with the given title}, + topics={glossrefs}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{newignoredglossary, + name={\csfmt{new\-ignored\-glossary}}, + user1={\margm{type}}, + description={defines a new ignored glossary (with hyperlinks + suppressed) identified by \meta{type} + that's not included in the list used by commands, such + as \cs{printunsrtglossaries}, that iterate over defined glossaries}, + topics={glossrefs}, + note={\styfmt{glossaries} v4.08+}, + category={command} +} + +@glscommand{newignoredglossary*, + name={\csfmt{new\-ignored\-glossary*}}, + user1={\margm{type}}, + description={defines a new ignored glossary (without + suppressing hyperlinks) identified by \meta{type} + that's not included in the list used by commands, such + as \cs{printunsrtglossaries}, that iterate over defined glossaries}, + topics={glossrefs}, + note={\styfmt{glossaries-extra} v1.11+}, + category={command} +} + +@glscommand{provideignoredglossary, + name={\csfmt{provide\-ignored\-glossary}}, + user1={\margm{type}}, + description={as \cs{newignoredglossary} but does nothing + if a glossary identified by \meta{type} already exists}, + topics={glossrefs}, + note={\styfmt{glossaries-extra} v1.12+}, + category={command} +} + +@glscommand{provideignoredglossary*, + name={\csfmt{provide\-ignored\-glossary*}}, + user1={\margm{type}}, + description={as \ics{provideignoredglossary} but doesn't + suppress hyperlinks}, + topics={glossrefs}, + note={\styfmt{glossaries-extra} v1.12+}, + category={command} +} + +@glscommand{delimN, + name={\csfmt{delimN}}, + user1={}, + description={used to delimited individual locations}, + topics={glossarystylecommands,separatorcommands,loclistcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{delimR, + name={\csfmt{delimR}}, + user1={}, + description={used as a separator between the start and end locations + of a range}, + topics={glossarystylecommands,separatorcommands,loclistcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glsnoidxloclist, + name={\csfmt{gls\-noidx\-loc\-list}}, + user1={\margm{location list cs}}, + description={iterates over the given internal location list using + the \cs{glsnoidxloclisthandler} handler}, + topics={glossarystylecommands,loops,loclistcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glsnoidxloclisthandler, + name={\csfmt{gls\-noidx\-loc\-list\-handler}}, + description={the handler used by the internal list loop function used + in \cs{glsnoidxloclist}}, + topics={glossarystylecommands,loops,loclistcommands}, + user1={\margm{location}}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glossentry, + name={\csfmt{glossentry}}, + user1={\margm{label}\margm{location list}}, + description={used in the glossary to display a top-level entry}, + topics={glossarystylecommands}, + note={\styfmt{glossaries} v3.08a+}, + category={command} +} + +@glscommand{subglossentry, + name={\csfmt{subglossentry}}, + user1={\margm{level}\margm{label}\margm{location list}}, + description={used in the glossary to display a sub-entry}, + topics={glossarystylecommands}, + note={\styfmt{glossaries} v3.08a+}, + category={command} +} + +@glscommand{newglossarystyle, + name={\csfmt{new\-glossary\-style}}, + user1={\margm{name}\margm{definition}}, + description={defines a new glossary style called \meta{name}}, + topics={glossarystylecommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{setglossarystyle, + name={\csfmt{set\-glossary\-style}}, + user1={\margm{name}}, + description={sets the glossary style identified by \meta{name}}, + topics={glossarystylecommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glossaryheader, + name={\csfmt{glossary\-header}}, + description={implemented at the start of a glossary (modified by +glossary styles)}, + topics={glossarystylecommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glsgroupskip, + name={\csfmt{gls\-group\-skip}}, + description={inserted between groups to create some vertical + spacing (this command is modified by + glossary styles, and may be switched off with the + \styopt{nogroupskip} option)}, + topics={glossarystylecommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glsentryitem, + name={\csfmt{gls\-entry\-item}}, + user1={\margm{label}}, + description={increments and displays the \counter{glossaryentry} +counter, if appropriate}, + topics={glossarystylecommands}, + note={\styfmt{glossaries} v3.0+}, + category={command} +} + +@glscommand{glsentrycounterlabel, + name={\csfmt{gls\-entry\-counter\-label}}, + description={governs the way the \counter{glossaryentry} + counter is displayed by \cs{glsentryitem}}, + topics={glossarystylecommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glssubentryitem, + name={\csfmt{gls\-sub\-entry\-item}}, + user1={\margm{label}}, + description={increments and displays the \counter{glossarysubentry} +counter, if appropriate}, + topics={glossarystylecommands}, + note={\styfmt{glossaries} v3.0+}, + category={command} +} + +@glscommand{glssubentrycounterlabel, + name={\csfmt{gls\-sub\-entry\-counter\-label}}, + description={governs the way the \counter{glossarysubentry} + counter is displayed by \cs{glssubentryitem}}, + topics={glossarystylecommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glstarget, + name={\csfmt{gls\-target}}, + user1={\margm{label}\margm{text}}, + description={creates a hypertarget for the entry given by +\meta{label} (the target for commands like \cs{gls}) and displays \meta{text}}, + topics={glossarystylecommands,linkcommands}, + note={\styfmt{glossaries} v1.18+}, + category={command} +} + +@glscommand{glsnamefont, + name={\csfmt{gls\-name\-font}}, + user1={\margm{text}}, + description={used by \cs{glossentryname} to format the name}, + topics={glossarystylecommands,formattingcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glossentryname, + name={\csfmt{gloss\-entry\-name}}, + user1={\margm{label}}, + description={used by glossary styles to display the name}, + topics={glossarystylecommands,fieldrefcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glossentrysymbol, + name={\csfmt{gloss\-entry\-symbol}}, + user1={\margm{label}}, + description={used by glossary styles to display the symbol}, + topics={glossarystylecommands,fieldrefcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glspostdescription, + name={\csfmt{glspostdescription}}, + description={a hook added after the description in some glossary +styles (all if the \sty{glossaries-extra-stylemods} package is +loaded to patch them). This hook is used to reflect the +\styopt{nopostdot} package option for \sty{glossaries} +and the \styopt{postpunc} option for \sty{glossaries-extra}}, + topics={glossarystylecommands,hooks}, + note={\styfmt{glossaries} and modified by +\styfmt{glossaries-extra}}, + category={command} +} + +@glscommand{glossentrynameother, + name={\csfmt{gloss\-entry\-name\-other}}, + user1={\margm{label}\margm{field}}, + description={acts like \ics{glossentryname} (obeys + \catattr{glossname} and \catattr{glossnamefont} + or \cs{glsnamefont} and the post-name hook) but uses + the given \meta{field} instead of the \field{name} field}, + topics={glossarystylecommands,fieldrefcommands}, + note={\styfmt{glossaries-extra} v1.22+}, + category={command} +} + +@glscommand{glossentrydesc, + name={\csfmt{gloss\-entry\-desc}}, + user1={\margm{label}}, + description={used by glossary styles to display the description}, + topics={glossarystylecommands,fieldrefcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{Glossentrydesc, + name={\csfmt{Gloss\-entry\-desc}}, + user1={\margm{label}}, + description={like \cs{glossentrydesc} but converts the first +letter to \idx{uppercase}}, + topics={glossarystylecommands,fieldrefcommands,casecommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{Glossentryname, + name={\csfmt{Gloss\-entry\-name}}, + user1={\margm{label}}, + description={like \cs{glossentryname} but converts the first +letter to \idx{uppercase}}, + topics={glossarystylecommands,fieldrefcommands,casecommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{Glossentrysymbol, + name={\csfmt{Gloss\-entry\-symbol}}, + user1={\margm{label}}, + description={like \cs{glossentrysymbol} but converts the first +letter to \idx{uppercase}}, + topics={glossarystylecommands,fieldrefcommands,casecommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glsaddall, + name={\csfmt{glsaddall}}, + user1={\oargm{options}}, + description={iterates over all entries defined for all glossaries + (or for the sub-list provided by \optfmt{types=\margm{list}} in the options) + and performs \code{\cs{glsadd}\oargm{options}} for each entry. + This command isn't suitable for use with \bibgls. Use the + \csopt{selection} option instead}, + topics={loops,indexing}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glsaddallunused, + name={\csfmt{gls\-add\-all\-unused}}, + user1={\oargm{list}}, + description={iterates over all entries defined for all glossaries + (or for the sub-list provided in the options) and performs + \cs{glsadd} for each entry that hasn't been used with + the \glsaddopt{format} set to \code{glsignore}. + This command isn't suitable for use with \bibgls. Use the + \csopt{selection} option instead}, + topics={loops,indexing}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glsadd, + name={\csfmt{glsadd}}, + user1={\oargm{options}\margm{label}}, + description={indexes the entry without displaying any text}, + topics={indexing}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glsaddeach, + name={\csfmt{gls\-add\-each}}, + user1={\oargm{options}\margm{label list}}, + description={indexes each entry identified in the comma-separated + list of labels without displaying any text}, + topics={indexing}, + note={\styfmt{glossaries-extra} v1.31+}, + category={command} +} + +@glsaddoption{glsadd.thevalue, + name={\csoptfmt{thevalue}}, + user1={\margm{value}}, + description={overrides the record value so that it's the + given \meta{value} not obtained from the associated counter}, + category={commandoption}, + note={\styfmt{glossaries-extra} v1.14+}, + parent={glsadd} +} + +@glsaddoption{glsadd.theHvalue, + name={\csoptfmt{theHvalue}}, + user1={\margm{value}}, + description={the hyperlink target corresponding to the value + of \glsopt{thevalue}, if appropriate}, + category={commandoption}, + note={\styfmt{glossaries-extra} v1.14+}, + parent={glsadd} +} + +@glsaddoption{glsadd.format, + name={\csoptfmt{format}}, + user1={\margm{encap}}, + description={sets the \gls{encap} for the record to + \meta{encap}, optionally with the start or end range markers}, + category={commandoption}, + note={\styfmt{glossaries}}, + parent={glsadd} +} + +@glsaddoption{glsadd.counter, + name={\csoptfmt{counter}}, + user1={\margm{counter-name}}, + description={sets the counter to use for the record}, + category={commandoption}, + note={\styfmt{glossaries}}, + parent={glsadd} +} + +@glscommand{theglossaryentry, + name={\csfmt{theglossaryentry}}, + description={textual representation of the \counter{glossaryentry} +counter, which is defined with the \styopt{entrycounter} option}, + topics={glossarystylecommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{theHglossaryentry, + name={\csfmt{theHglossaryentry}}, + description={hypertarget associated with the \counter{glossaryentry} +counter, which is defined with the \styopt{entrycounter} option}, + topics={glossarystylecommands,linkcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glsstepentry, + name={\csfmt{gls\-step\-entry}}, + user1 = {\margm{label}}, + description={increments the \counter{glossaryentry} counter, which +is defined with the \styopt{entrycounter} option, and automatically +labels it with \cs{label}}, + topics={glossarystylecommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{currentglossary, + name={\csfmt{currentglossary}}, + description={defined within the glossary to the current glossary +type, this has no meaning outside of the glossary list}, + topics={glossarystylecommands,glossrefs}, + note={\styfmt{glossaries}}, + category={command} +} + +@command{frontmatter, + name={\csfmt{front\-matter}}, + user1={}, + description={switches to front matter}, + note={book-like classes}, + category={command} +} + +@command{mainmatter, + name={\csfmt{main\-matter}}, + user1={}, + description={switches to main matter}, + note={book-like classes}, + category={command} +} + +@command{backmatter, + name={\csfmt{back\-matter}}, + user1={}, + description={switches to back matter}, + note={book-like classes}, + category={command} +} + +@glscommand{GlsXtrSetDefaultNumberFormat, + name={\csfmt{Gls\-Xtr\-Set\-Default\-Number\-Format}}, + user1={\margm{format}}, + description={set the default format to use if the + \glsaddopt{format} key isn't set}, + topics={formattingcommands,indexing}, + note={\styfmt{glossaries-extra} v1.19+}, + category={command} +} + +@glscommand{GlsXtrSetDefaultGlsOpts, + name={\csfmt{Gls\-Xtr\-Set\-Default\-Gls\-Opts}}, + user1={\margm{options}}, + description={set the default options for commands like \cs{gls}}, + topics={formattingcommands,indexing}, + seealso={GlsXtrSetDefaultNumberFormat}, + note={\styfmt{glossaries-extra}}, + category={command} +} + +@glscommand{glsnumberformat, + name={\csfmt{gls\-number\-format}}, + user1={\margm{text}}, + description={default location format, uses \cs{glshypernumber} if +hyperlinks enabled otherwise just does \meta{text}}, + topics={formattingcommands,indexing,loclistcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glshypernumber, + name={\csfmt{gls\-hyper\-number}}, + user1={\margm{text}}, + description={a location format that has a hyperlink (if enabled)}, + topics={formattingcommands,indexing,loclistcommands,linkcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{hypersf, + name={\csfmt{hypersf}}, + user1={\margm{text}}, + description={a location format that uses the sans-serif + font that also has a hyperlink (if enabled)}, + topics={formattingcommands,indexing,loclistcommands,linkcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{hyperit, + name={\csfmt{hyperit}}, + user1={\margm{text}}, + description={a location format that uses the italic + font that also has a hyperlink (if enabled)}, + topics={formattingcommands,indexing,loclistcommands,linkcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{hyperbf, + name={\csfmt{hyperbf}}, + user1={\margm{text}}, + description={a location format that uses the bold + font that also has a hyperlink (if enabled)}, + topics={formattingcommands,indexing,loclistcommands,linkcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{hyperemph, + name={\csfmt{hyperemph}}, + user1={\margm{text}}, + description={a location format that uses \ics{emph} to set the + font and also has a hyperlink (if enabled)}, + topics={formattingcommands,indexing,loclistcommands,linkcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{hyperrm, + name={\csfmt{hyperrm}}, + user1={\margm{text}}, + description={a location format that uses the serif (Roman) + font that also has a hyperlink (if enabled)}, + topics={formattingcommands,indexing,loclistcommands,linkcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@command{emph, + name={\csfmt{emph}}, + user1={\margm{text}}, + description={emphasizes the given text (italic or slanted + if the surrounding font is upright, otherwise upright font is + used)}, + note={kernel command}, + category={command} +} + +@command{em, + name={\csfmt{em}}, + description={switch to emphasized font (until end of current scope)}, + note={kernel command}, + category={command} +} + +@command{textsf, + name={\csfmt{textsf}}, + user1={\margm{text}}, + description={displays the given text in sans-serif}, + note={kernel command}, + category={command} +} + +@command{textbf, + name={\csfmt{textbf}}, + user1={\margm{text}}, + description={displays the given text in bold}, + note={kernel command}, + category={command} +} + +@command{bfseries, + name={\csfmt{bfseries}}, + description={switch to bold (until end of current scope)}, + note={kernel command}, + category={command} +} + +@command{textit, + name={\csfmt{textit}}, + user1={\margm{text}}, + description={displays the given text in italic}, + note={kernel command}, + seealso={emph}, + category={command} +} + +@command{texttt, + name={\csfmt{texttt}}, + user1={\margm{text}}, + description={displays the given text in monospaced font}, + note={kernel command}, + category={command} +} + +@command{@firstofone, + name={\csfmt{@first\-of\-one}}, + user1={\margm{code}}, + description={does \meta{code}}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{@gobble, + name={\csfmt{@gobble}}, + user1={\margm{code}}, + description={does nothing (the argument is discarded)}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{@for, + name={\csfmt{@for}}, + user1={\meta{cs}:=\meta{list}\csfmt{do}\margm{code}}, + description={iterates over each item in the comma-separated +\meta{list}, and on each iteration sets \meta{cs} to the current +element and performs \meta{code}}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{alph, + name={\csfmt{alph}}, + user1={\margm{counter}}, + description={displays the given counter as an alphabetic character +from \qt{a} to \qt{z}}, + note={kernel command}, + category={command} +} + +@command{footnote, + name={\csfmt{footnote}}, + user1={\oargm{number}\margm{text}}, + description={displays the given text as a footnote}, + note={kernel command}, + category={command} +} + +@command{index, + name={\csfmt{index}}, + user1={\margm{text}}, + description={indexes the given term by writing the relevant +information to an associated file that can then be processed +by \idx{makeindex} or \idx{xindy}}, + note={kernel command}, + category={command} +} + +@glscommand{glsignore, + name={\csfmt{gls\-ignore}}, + user1={\margm{text}}, + description={does nothing but when used as a location format + \bibgls\ recognises it as an \idx{ignoredrecord}}, + topics={formattingcommands,indexing,loclistcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{@istfilename, + name={\csfmt{@istfilename}}, + user1={\margm{filename}}, + description={identifies the style file in the \ext{aux} + file for the benefit of external tools like + \idx{makeglossaries} and \idx{makeglossaries-lite}}, + topics={internalcommands,auxcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glstriggerrecordformat, + name={\csfmt{gls\-trigger\-record\-format}}, + user1={\margm{text}}, + description={does nothing but when used as a location format + \bibgls\ recognises it as an \idx{ignoredrecord} indexed by + commands like \csref{rgls}}, + topics={formattingcommands,indexing,loclistcommands}, + note={\styfmt{glossaries-extra} v1.21+}, + category={command} +} + +@command{at, + name={\csfmt{@}}, + user1={}, + description={adjusts the space factor to indicate the following + punctuation character marks the end of the sentence}, + note={kernel command}, + category={command} +} + +@command{forall, + name={\csfmt{forall}}, + user1={}, + description={for all symbol ($\forall$)}, + note={kernel command\texparserdefnote\ (maths mode)}, + category={command} +} + +@command{heartsuit, + name={\csfmt{heartsuit}}, + user1={}, + description={heart symbol ($\heartsuit$)}, + note={kernel command\texparserdefnote\ (maths mode)}, + category={command} +} + +@command{diamondsuit, + name={\csfmt{diamondsuit}}, + user1={}, + description={diamond symbol ($\diamondsuit$)}, + note={kernel command\texparserdefnote\ (maths mode)}, + category={command} +} + +@command{ensuremath, + name={\csfmt{ensuremath}}, + user1={\margm{maths}}, + description={ensures the argument is in math mode. As a general +rule this should only be used if you know for certain that +the argument just contains mathematical markup and doesn't cause a +change in mode}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{mathord, + name={\csfmt{mathord}}, + user1={\margm{maths}}, + description={assigns the character or sub-formula in the + argument to class 0, ordinary}, + note={\TeX\ primitive}, + category={command} +} + +@command{mathop, + name={\csfmt{mathop}}, + user1={\margm{maths}}, + description={assigns the character or sub-formula in the + argument to class 1, large operator}, + note={\TeX\ primitive}, + category={command} +} + +@command{mathpunct, + name={\csfmt{mathpunct}}, + user1={\margm{maths}}, + description={assigns the character or sub-formula in the + argument to class 6, punctuation}, + note={\TeX\ primitive}, + category={command} +} + +@command{mathrel, + name={\csfmt{mathrel}}, + user1={\margm{maths}}, + description={assigns the character or sub-formula in the + argument to class 3, relation}, + note={\TeX\ primitive}, + category={command} +} + +@command{write18, + name={\csfmt{write18}}, + user1={\margm{system call}}, + description={perform shell escape if permitted}, + note={kernel command}, + category={command} +} + +@command{immediate, + name={\csfmt{immediate}}, + user1={\meta{file operation}}, + description={perform the file operation immediately instead of the +usual delay}, + note={{}\TeX\ primitive}, + category={command} +} + +@command{AtEndDocument, + name={\csfmt{AtEndDocument}}, + user1={\margm{code}}, + description={perform \meta{code} at the end of the document}, + note={kernel command}, + category={command} +} + +@command{unexpanded, + name={\csfmt{unexpanded}}, + user1={\margm{general text}}, + description={expands to the argument}, + note={{}\eTeX\ primitive\texparserdefnote}, + category={command} +} + +@command{detokenize, + name={\csfmt{detokenize}}, + user1={\margm{general text}}, + description={expands the argument to a list of character tokens}, + note={{}\eTeX\ primitive\texparserdefnote}, + category={command} +} + +@command{input, + name={\csfmt{input}}, + user1={\margm{file}}, + description={input the given file}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{IfFileExists, + name={\csfmt{IfFileExists}}, + user1={\margm{file}\margm{true}\margm{false}}, + description={if the given \meta{file} exists does \meta{true} + otherwise does \meta{false}}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{jobname, + name={\csfmt{jobname}}, + user1={}, + description={the current job name, which is usually the name of + the main \ext{tex} file without the extension}, + note={primitive}, + category={command} +} + +@command{protect, + name={\csfmt{protect}}, + user1={\meta{token}}, + description={protects \meta{token} from expansion}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{ifcase, + name={\csfmt{ifcase}}, + user1={\meta{number}}, + description={case conditional}, + note={\TeX\ primitive\texparserdefnote}, + category={command} +} + +@command{ifnum, + name={\csfmt{ifnum}}, + user1={\meta{number1}\meta{comparison}\meta{number2}}, + description={integer conditional}, + note={\TeX\ primitive\texparserdefnote}, + category={command} +} + +@command{renewcommand, + name={\csfmt{re\-new\-com\-mand}}, + user1={\margm{cs}\oargm{n}\oargm{def}\margm{code}}, + description={redefines an existing command}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{newcommand, + name={\csfmt{new\-com\-mand}}, + user1={\margm{cs}\oargm{n}\oargm{def}\margm{code}}, + description={defines a new command}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{providecommand, + name={\csfmt{pro\-vide\-com\-mand}}, + user1={\margm{cs}\oargm{n}\oargm{def}\margm{code}}, + description={defines a command if it's not already defined}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{section, + name={\csfmt{section}}, + user1={\oargm{\idx{toc} title}\margm{title}}, + description={section heading}, + note={most classes that have a concept of document sections}, + category={command} +} + +@command{section*, + name={\csfmt{section*}}, + user1={\margm{title}}, + description={unnumbered section heading}, + note={most classes that have a concept of document sections}, + category={command} +} + +@command{chapter, + name={\csfmt{chapter}}, + user1={\oargm{\idx{toc} title}\margm{title}}, + description={chapter heading}, + note={book or report classes}, + category={command} +} + +@command{chapter*, + name={\csfmt{chapter*}}, + user1={\margm{title}}, + description={unnumbered chapter heading}, + note={book or report classes}, + category={command} +} + +@command{caption, + name={\csfmt{caption}}, + user1={\oargm{list title}\margm{title}}, + description={caption title}, + note={kernel command}, + category={command} +} + +@command{boldsymbol, + name={\csfmt{boldsymbol}}, + user1={\margm{symbol}}, + description={renders given maths symbol in bold if supported by + the current font}, + note={\styfmt{amsmath}}, + category={command} +} + +@command{mathcal, + name={\csfmt{mathcal}}, + user1={\margm{character}}, + description={renders the given (\idx!{uppercase}) maths character in a calligraphic font}, + note={kernel command (maths mode)}, + category={command} +} + +@glscommand{ifglsentryexists, + name={\csfmt{ifglsentryexists}}, + user1={\margm{label}\margm{true}\margm{false}}, + description={tests if the entry given by \meta{label} exists}, + topics={conditionals,entryrefcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glsdefaulttype, + name={\csfmt{gls\-default\-type}}, + user1={}, + description={the default glossary type}, + topics={glossrefs}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glssymbolsgroupname, + name={\csfmt{gls\-symbols\-group\-name}}, + user1={}, + description={language-sensitive name used for the symbols group and + also used for the title of the glossary created with the \styopt{symbols} + package option}, + topics={fixedtextcommands,glossarystylecommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glsnumbersgroupname, + name={\csfmt{gls\-numbers\-group\-name}}, + user1={}, + description={language-sensitive name used for the numbers group + and also used for the title of the glossary created with the + \styopt{numbers} package option}, + topics={fixedtextcommands,glossarystylecommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{printunsrtglossary, + name={\csfmt{print\-unsrt\-glos\-sary}}, + user1={\oargm{options}}, + description={display a glossary by iterating over all entries + associated with that glossary in the order in which they were + defined (which, with \bibgls, should correspond to the + order obtained from the sort settings given in the + \idx{resourceset} options)}, + topics={glossrefs,loops}, + note={\styfmt{glossaries-extra} v1.08+}, + category={command} +} + +@glscommand{printunsrtglossary*, + name={\csfmt{print\-unsrt\-glos\-sary*}}, + user1={\oargm{options}\margm{code}}, + description={as \cs{printunsrtglossary} but performs + \meta{code} first (scoped to localise any assignments within + \meta{code})}, + topics={glossrefs,loops}, + note={\styfmt{glossaries-extra} v1.12+}, + category={command} +} + +@glscommand{printunsrtglossaries, + name={\csfmt{print\-unsrt\-glos\-saries}}, + user1={}, + description={iterates over all non-ignored defined glossaries + and performs \cs{printunsrtglossary} for each one}, + topics={glossrefs,loops}, + note={\styfmt{glossaries-extra} v1.08+}, + category={command} +} + +@glscommand{printunsrtglossaryentryprocesshook, + name={\csfmt{print\-unsrt\-glos\-sary\-entry\-process\-hook}}, + user1={\margm{label}}, + description={performed at each iteration of the internal loop used +by \cs{printunsrtglossary}}, + topics={glossrefs,loops,hooks}, + note={\styfmt{glossaries-extra} v1.21+}, + category={command} +} + +@glscommand{printunsrtglossaryskipentry, + name={\csfmt{print\-unsrt\-glos\-sary\-skip\-entry}}, + description={only allowed within + \cs{printunsrtglossaryentryprocesshook} this command + indicates that the current entry should be skipped}, + topics={glossrefs,loops,hooks}, + note={\styfmt{glossaries-extra} v1.21+}, + category={command} +} + +@glscommand{printunsrtglossarypredoglossary, + name={\csfmt{print\-unsrt\-glos\-sary\-pre\-do\-glos\-sary}}, + description={hook performed by \cs{printunsrtglossary}}, + topics={glossrefs,hooks}, + note={\styfmt{glossaries-extra} v1.21+}, + category={command} +} + +@glscommand{glscategory, + name={\csfmt{gls\-cat\-e\-gory}}, + user1={\margm{label}}, + description={expands to the value of the \field{category} field +for the entry identified by \meta{label} or nothing if the entry +hasn't been defined}, + topics={fieldrefcommands,catattrcommands}, + note={\styfmt{glossaries-extra}}, + category={command} +} + +@glscommand{glsifcategory, + name={\csfmt{gls\-if\-cat\-e\-gory}}, + user1={\margm{label}\margm{category}\margm{true}\margm{false}}, + description={does \meta{true} if the \field{category} field for + the entry given by \meta{label} is \meta{category}}, + topics={conditionals,fieldrefcommands,catattrcommands}, + note={\styfmt{glossaries-extra}}, + category={command} +} + +@glscommand{glsxtriflabelinlist, + name={\csfmt{gls\-xtr\-if\-label\-in\-list}}, + user1={\margm{label}\margm{list}\margm{true}\margm{false}}, + description={tests if the \meta{label} is contained + in the comma-separated \meta{list}, where both \meta{label} + and \meta{list} are fully expanded before testing. This test + is designed for \emph{labels} that are fully expandable}, + topics={conditionals,listcommands}, + note={\styfmt{glossaries-extra} v1.21+}, + category={command} +} + +@printglossoption{printgloss.type, + parent = {printunsrtglossary}, + name = {\csoptfmt{type}}, + user1 = {\margm{glossary-label}}, + description={identifies the glossary list (\cs{glsdefaulttype}, if + omitted)}, + category={commandoption}, +} + +@printglossoption{printgloss.style, + parent = {printunsrtglossary}, + name = {\csoptfmt{style}}, + user1 = {\margm{style-name}}, + description={use the glossary style identified by \meta{style-name} + (overrides current style setting)}, + category={commandoption}, +} + +@printglossoption{printgloss.entrycounter, + parent = {printunsrtglossary}, + name = {\csoptfmt{entrycounter}}, + user1 = {\margm{boolean}}, + description = {locally enable or disable top-level enumeration + (overrides \styopt{entrycounter} package option)}, + category={commandoption}, +} + +@printglossoption{printgloss.subentrycounter, + parent = {printunsrtglossary}, + name = {\csoptfmt{subentrycounter}}, + user1 = {\margm{boolean}}, + description = {locally enable or disable level~1 enumeration + (overrides \styopt{subentrycounter} package option)}, + category={commandoption}, +} + +@printglossoption{printgloss.nopostdot, + parent = {printunsrtglossary}, + name = {\csoptfmt{nopostdot}}, + user1 = {\margm{boolean}}, + description = {locally omit the post-description punctuation (overrides + \styopt{nopostdot} and related package options)}, + category={commandoption}, +} + +@printglossoption{printgloss.numberedsection, + parent = {printunsrtglossary}, + name = {\csoptfmt{numbered\-section}}, + user1={\margm{value}}, + description={locally change whether or not to use a numbered + sectioning command (overrides \styopt{numberedsection} package + option)}, + category={commandoption}, +} + +@printglossoption{printgloss.title, + parent = {printunsrtglossary}, + name = {\csoptfmt{title}}, + user1={\margm{text}}, + description = {locally sets the title for this glossary}, + category={commandoption}, +} + +@printglossoption{printgloss.toctitle, + parent = {printunsrtglossary}, + name = {\csoptfmt{toctitle}}, + description = {locally sets the \idx{toc} title for this glossary}, + user1={\margm{text}}, + category={commandoption}, +} + +@printglossoption{printgloss.target, + parent = {printunsrtglossary}, + name = {\csoptfmt{target}}, + user1={\margm{boolean}}, + description = {locally enables or disables the hypertargets for + each item}, + category={commandoption}, +} + +@printglossoption{printgloss.targetnameprefix, + parent = {printunsrtglossary}, + name = {\csoptfmt{target\-name\-prefix}}, + user1={\margm{label}}, + description = {locally assign a prefix for the hypertargets + assigned to each item (if \printglossopt[true]{target}) + to avoid duplicate target names}, + category={commandoption}, +} + +@printglossoption{printgloss.prefix, + parent = {printunsrtglossary}, + name = {\csoptfmt{prefix}}, + user1 = {\margm{label}}, + description = {locally redefine \cs{glolinkprefix} for the item + hypertargets and for any entry reference or cross-reference hyperlinks}, + category={commandoption}, +} + +@printglossoption{printgloss.nonumberlist, + parent = {printunsrtglossary}, + name = {\csoptfmt{no\-number\-list}}, + user1 = {\margm{boolean}}, + description={locally change whether or not to display the + \idxpl{locationlist} (overrides \styopt{nonumberlist} package + option)}, + category={commandoption}, +} + +@printglossoption{printgloss.nogroupskip, + parent = {printunsrtglossary}, + name = {\csoptfmt{no\-group\-skip}}, + user1 = {\margm{boolean}}, + description={locally change whether or not to separate groups + with a vertical space if the glossary style that support this option + (overrides \styopt{nogroupskip} package option)}, + category={commandoption}, +} + +@printglossoption{printgloss.label, + parent = {printunsrtglossary}, + name = {\csoptfmt{label}}, + user1 = {\margm{label}}, + description = {creates a label for this glossary by locally + using \code{\ics{glsxtrsetglossarylabel}\margm{label}}}, + category={commandoption}, +} + +@glscommand{glsxtrsetglossarylabel, + name={\csfmt{gls\-xtr\-set\-glos\-sary\-label}}, + user1={\margm{label}}, + description={sets the label for subsequent glossaries + (should be scoped or updated per glossary to prevent + duplicate labels) and defines \ics{@currentlabelname} to the + glossary's \idx{toc} title. This is an alternative to the + \styopt[nameref]{numberedsection} package option or + \printglossopt{label} \ics{printunsrtglossary} option}, + topics={crossrefcommands}, + note={\styfmt{glossaries-extra} v1.39+}, + category={command} +} + +@glscommand{cs.makeglossaries, + name={\csfmt{make\-glos\-saries}}, + user1={}, + description={opens associated glossary files to be processed + by \idx{makeindex} or \idx{xindy}}, + topics={indexing}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{makenoidxglossaries, + name={\csfmt{make\-noidx\-glos\-saries}}, + user1={}, + description={indicates that \TeX\ should be used to sort and + collate the glossary information instead of using an + external application; this command should not be used + with \bibgls}, + topics={indexing}, + note={\styfmt{glossaries} v4.04+}, + category={command} +} + +@glscommand{printglossary, + name={\csfmt{print\-glos\-sary}}, + user1={\oargm{options}}, + description={inputs file created by \idx{makeindex} or \idx{xindy}}, + topics={glossrefs}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{printglossaries, + name={\csfmt{print\-glos\-saries}}, + user1={}, + description={iterates over all non-ignored defined glossaries + and performs \cs{printglossary} for each one}, + topics={glossrefs,loops}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{printnoidxglossary, + name={\csfmt{print\-noidx\-glos\-sary}}, + user1={\oargm{options}}, + description={uses \TeX\ to sort, collate and list the glossary}, + topics={glossrefs}, + note={\styfmt{glossaries} v4.04+}, + category={command} +} + +@glscommand{printnoidxglossaries, + name={\csfmt{print\-noidx\-glos\-saries}}, + user1={}, + description={iterates over all non-ignored defined glossaries + and performs \cs{printnoidxglossary} for each one}, + topics={glossrefs,loops}, + note={\styfmt{glossaries} v4.04+}, + category={command} +} + +@command{makefirstuc, + name={\csfmt{make\-first\-uc}}, + user1={\margm{text}}, + description={converts the first letter of \meta{text} to \idx{uppercase}}, + note={\styfmt{mfirstuc}\texparserdefnote}, + category={command} +} + +@command{xmakefirstuc, + name={\csfmt{xmake\-first\-uc}}, + user1={\margm{text}}, + description={applies \cs{makefirstuc} with one level expansion + of the first token of \meta{text}}, + note={\styfmt{mfirstuc}\texparserdefnote\ v1.01+}, + category={command} +} + +@glscommand{ac, + name={\csfmt{ac}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={equivalent to \cs{gls}}, + topics={entryrefcommands,linkcommands,indexing,abbreviationcommands,shortcutcommands}, + note={\styfmt{glossaries-extra} \styopt{shortcuts}}, + category={command} +} + +@glscommand{ab, + name={\csfmt{ab}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={equivalent to \cs{gls}}, + topics={entryrefcommands,linkcommands,indexing,abbreviationcommands,shortcutcommands}, + note={\styfmt{glossaries-extra} + \styopt[abbreviations]{shortcuts}}, + category={command} +} + +@glscommand{glsxtrp, + name={\csfmt{glsxtrp}}, + user1={\margm{field}\margm{label}}, + description={displays the given \meta{field} value for the entry given by + \meta{label} (no hyperlinks, except in the glossary, and no indexing + by default, but includes formatting, if appropriate)}, + topics={fieldrefcommands}, + note={\styfmt{glossaries-extra} v1.07+}, + category={command} +} + +@glscommand{glsps, + name={\csfmt{glsps}}, + user1={\margm{label}}, + description={shortcut for \code{\cs{glsxtrp}\marg{short}\margm{label}}}, + topics={fieldrefcommands,shortcutcommands}, + note={\styfmt{glossaries-extra} v1.07+}, + category={command} +} + +@glscommand{glspt, + name={\csfmt{glspt}}, + user1={\margm{label}}, + description={shortcut for \code{\cs{glsxtrp}\marg{text}\margm{label}}}, + topics={fieldrefcommands,shortcutcommands}, + note={\styfmt{glossaries-extra} v1.07+}, + category={command} +} + +@glscommand{glsxtrsetpopts, + name={\csfmt{glsxtrsetpopts}}, + user1={\margm{options}}, + description={sets the default options for \cs{glsxtrp}}, + topics={assigncommands}, + note={\styfmt{glossaries-extra} v1.07+}, + category={command} +} + +@glscommand{glossxtrsetpopts, + name={\csfmt{glossxtrsetpopts}}, + description={glossary hook that uses \cs{glsxtrsetpopts} + to enable hyperlinks by default for \cs{glsxtrp}}, + topics={assigncommands,hooks}, + note={\styfmt{glossaries-extra} v1.07+}, + category={command} +} + +@glscommand{GlsXtrFmtField, + name={\csfmt{Gls\-Xtr\-Fmt\-Field}}, + user1={}, + description={expands to the internal label of the field used + to store the control sequence name for use with \csref{glsxtrfmt}}, + topics={fieldrefcommands,formattingcommands}, + note={\styfmt{glossaries-extra} v1.12+}, + category={command} +} + +@glscommand{glsxtrusesee, + name={\csfmt{gls\-xtr\-use\-see}}, + user1={\margm{label}}, + description={applies \cs{glsseeformat} to the entry's + \field{see} field if not empty}, + topics={glossarystylecommands,crossrefcommands,loclistcommands,fieldrefcommands}, + note={\styfmt{glossaries-extra} v1.06+}, + category={command} +} + +@glscommand{glsxtruseseealso, + name={\csfmt{gls\-xtr\-use\-seealso}}, + user1={\margm{label}}, + description={applies \cs{glsseeformat} to the entry's + \field{seealso} field if not empty}, + topics={glossarystylecommands,crossrefcommands,loclistcommands,fieldrefcommands}, + note={\styfmt{glossaries-extra} v1.16+}, + category={command} +} + +@glscommand{glsxtrsetaliasnoindex, + name={\csfmt{gls\-xtr\-set\-alias\-noindex}}, + user1={}, + description={hooks into the alias \glsopt{noindex} setting}, + topics={hooks,crossrefcommands}, + note={\styfmt{glossaries-extra} v1.12+}, + category={command} +} + +@glscommand{glsxtruseseealsoformat, + name={\csfmt{gls\-xtr\-use\-seealso\-format}}, + user1={\margm{xr list}}, + description={used to format the entries whose labels are + given in \meta{xr list} as a list of \qt{see also} +cross-references}, + topics={glossarystylecommands,crossrefcommands,loclistcommands,formattingcommands}, + note={\styfmt{glossaries-extra} v1.16+}, + category={command} +} + +@glscommand{glsxtrindexseealso, + name={\csfmt{gls\-xtr\-index\-seealso}}, + user1={\margm{label}\margm{xr list}}, + description={indexes a \qt{see also} cross-reference}, + topics={indexing,crossrefcommands}, + note={\styfmt{glossaries-extra} v1.16+}, + category={command} +} + +@glscommand{glssee, + name={\csfmt{glssee}}, + user1={\oargm{tag}\margm{label}\margm{xr label list}}, + description={indexes a \qt{see} cross-reference}, + topics={indexing,crossrefcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glsxtrseelist, + name={\csfmt{gls\-xtr\-see\-list}}, + user1={\margm{xr label list}}, + description={formats the list of cross-reference labels, without +the initial \qt{see} tag}, + topics={glossarystylecommands,crossrefcommands,loclistcommands,formattingcommands}, + note={\styfmt{glossaries-extra} v1.16+}, + category={command} +} + +@glscommand{setabbreviationstyle, + name={\csfmt{setabbreviationstyle}}, + user1={\oargm{category}\margm{style-name}}, + description={sets the abbreviation style to \meta{style-name} for the +given \meta{category}, must be used before the abbreviation is +defined}, + topics={abbreviationcommands,assigncommands}, + note={\styfmt{glossaries-extra}}, + category={command} +} + +@glscommand{glshex, + name={\csfmt{glshex}}, + user1={}, + description={expands to \cs{cs.string}\cs{u}}, + topics={charcommands,collationsubrules}, + note={\styfmt{glossaries-extra} v1.21+ (moved to +\styfmt{glossaries-extra-bib2gls} in v1.27)}, + category={command} +} + +@glscommand{glscapturedgroup, + name={\csfmt{glscapturedgroup}}, + description={expands to \cs{cs.string}\idx{dollarchar}}, + topics={charcommands,regex}, + note={\styfmt{glossaries-extra-bib2gls} v1.31+}, + category={command} +} + +@glscommand{GlsXtrBibTeXEntryAliases, + name={\csfmt{Gls\-Xtr\-Bib\-TeX\-Entry\-Aliases}}, + user1={}, + description={expands to the set of common entry aliases for +\atentry{bibtexentry}}, + topics={definingterms}, + note={\styfmt{glossaries-extra-bib2gls} v1.29+}, + category={command} +} + +@glscommand{GlsXtrProvideBibTeXFields, + name={\csfmt{Gls\-Xtr\-Provide\-Bib\-TeX\-Fields}}, + user1={}, + description={defines the standard \BibTeX\ fields using + \cs{glsaddstoragekey}}, + topics={definingterms,fieldrefcommands}, + note={\styfmt{glossaries-extra-bib2gls} v1.29+}, + category={command} +} + +@glscommand{glsxtrprovidecommand, + name={\csfmt{gls\-xtr\-provide\-command}}, + user1={\margm{cs}\oargm{n}\oargm{def}\margm{code}}, + description={behaves like \cs{providecommand} in the document but + like \cs{renewcommand} in \bibgls}, + topics={providingcommands}, + note={\styfmt{glossaries-extra-bib2gls}\texparserdefnote\ v1.27+}, + category={command} +} + +@glscommand{glsrenewcommand, + name={\csfmt{gls\-re\-new\-command}}, + user1={\margm{cs}\oargm{n}\oargm{def}\margm{code}}, + description={behaves like \cs{renewcommand} but only generates a +warning rather than an error if the command isn't already defined}, + topics={providingcommands}, + note={\styfmt{glossaries-extra-bib2gls}\texparserdefnote\ v1.37+}, + category={command} +} + +@glscommand{glsxtrresourceinit, + name={\csfmt{gls\-xtr\-resource\-init}}, + user1={}, + description={provides code that locally redefines commands + during the protected write operation performed by + \csref{glsxtrresourcefile}}, + topics={hooks}, + note={\styfmt{glossaries-extra} v1.21+}, + category={command} +} + +@mainglscommand{GlsXtrDefaultResourceOptions, + name={\csfmt{Gls\-Xtr\-Default\-Resource\-Options}}, + user1={}, + description={provides default options for + \csref{glsxtrresourcefile}}, + topics={hooks}, + note={\styfmt{glossaries-extra} v1.40+}, + category={command} +} + +@glscommand{glsxtrgroupfield, + name={\csfmt{gls\-xtr\-group\-field}}, + user1={}, + description={expands to the field label used to store the + entry group labels}, + topics={fieldrefcommands,groupcommands}, + note={\styfmt{glossaries-extra} v1.21+}, + category={command} +} + +@glscommand{glolinkprefix, + name={\csfmt{glo\-link\-prefix}}, + user1={}, + description={target name prefix used in entry hyperlinks}, + topics={linkcommands,hooks}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{setglossarypreamble, + name={\csfmt{set\-glossary\-preamble}}, + user1={\oargm{type}\margm{code}}, + description={sets \meta{code} as the preamble for the given +glossary (or the default of \meta{type} is omitted)}, + topics={glossrefs,hooks,glossarystylecommands}, + note={\styfmt{glossaries}}, + seealso={glossarypreamble}, + category={command} +} + +@glscommand{apptoglossarypreamble, + name={\csfmt{app\-to\-glossary\-preamble}}, + user1={\oargm{type}\margm{code}}, + description={appends \meta{code} to the preamble for the given +glossary (or the default of \meta{type} is omitted)}, + topics={glossrefs,hooks,glossarystylecommands}, + note={\styfmt{glossaries-extra}}, + seealso={glossarypreamble}, + category={command} +} + +@glscommand{glossarypreamble, + name={\csfmt{glossary\-preamble}}, + description={the preamble for all glossaries except + those that have the preamble explicitly set with + \cs{apptoglossarypreamble}}, + topics={glossrefs,hooks,glossarystylecommands}, + note={\styfmt{glossaries}}, + seealso={apptoglossarypreamble}, + category={command} +} + +@glscommand{glossarypostamble, + name={\csfmt{glossary\-post\-amble}}, + description={the postamble that's placed after each glossary}, + topics={glossrefs,hooks,glossarystylecommands}, + note={\styfmt{glossaries}}, + seealso={apptoglossarypreamble}, + category={command} +} + +@glscommand{glsbackslash, + name={\csfmt{glsbackslash}}, + user1={}, + description={expands to a literal backslash \idx{backslashchar} + character}, + topics={charcommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{glsopenbrace, + name={\csfmt{glsopenbrace}}, + user1={}, + description={expands to a literal open brace \idx{openbracechar} + character}, + topics={charcommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{glsclosebrace, + name={\csfmt{glsclosebrace}}, + user1={}, + description={expands to a literal close brace \idx{closebracechar} + character}, + topics={charcommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{glspercentchar, + name={\csfmt{glspercentchar}}, + user1={}, + description={expands to a literal percent character \idx{percentchar} + character}, + topics={charcommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{glsquote, + name={\csfmt{glsquote}}, + user1={\margm{text}}, + description={encapsulates \meta{text} with literal straight + double-quotes \texttt{\glsquote{\meta{text}}}}, + topics={charcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glstildechar, + name={\csfmt{glstildechar}}, + user1={}, + description={expands to a literal tilde \texttt{\glstildechar} character}, + topics={charcommands}, + note={\styfmt{glossaries}\texparserdefnote}, + category={command} +} + +@glscommand{descriptionname, + name={\csfmt{description\-name}}, + user1={}, + description={language-sensitive name used for the description + header for some glossary styles}, + topics={fixedtextcommands,glossarystylecommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{pagelistname, + name={\csfmt{page\-list\-name}}, + user1={}, + description={language-sensitive name used for the location list + header for some glossary styles}, + topics={fixedtextcommands,glossarystylecommands,loclistcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@command{seealsoname, + name={\csfmt{seealsoname}}, + user1={}, + description={language sensitive \qt{see also} text}, + topics={fixedtextcommands,glossarystylecommands,loclistcommands}, + note={\styfmt{glossaries-extra} or language packages}, + category={command} +} + +@glscommand{glossaryname, + name={\csfmt{glossary\-name}}, + user1={}, + description={language-sensitive name used for the title of the default + \code{main} glossary}, + topics={fixedtextcommands,glossarystylecommands}, + note={\styfmt{glossaries} or language packages}, + category={command} +} + +@glscommand{indexname, + name={\csfmt{index\-name}}, + user1={}, + description={language-sensitive name used for the title of the + glossary created with the \styopt{index} package option}, + topics={fixedtextcommands,glossarystylecommands}, + note={\styfmt{glossaries} or language packages}, + category={command} +} + +@glscommand{acronymname, + name={\csfmt{acronym\-name}}, + user1={}, + description={language-sensitive name used for the title of the + glossary created with the \styopt{acronym} or \styopt{acronyms} + package option}, + topics={fixedtextcommands,glossarystylecommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{abbreviationname, + name={\csfmt{ab\-bre\-vi\-a\-tion\-name}}, + user1={}, + description={language-sensitive name used for the title of the + glossary created with the \styopt{abbreviations} package option}, + topics={fixedtextcommands,glossarystylecommands}, + note={\styfmt{glossaries-extra}}, + category={command} +} + +@glscommand{GlsXtrForeignText, + name={\csfmt{Gls\-Xtr\-Foreign\-Text}}, + user1={\margm{label}\margm{text}}, + description={encapsulates \meta{text} in \csfmt{foreignlanguage} + where the language label is obtained from the locale tag + given in the field identified by \cs{GlsXtrForeignTextField}}, + topics={formattingcommands,fieldrefcommands}, + note={\styfmt{glossaries-extra} v1.32+}, + category={command} +} + +@glscommand{GlsXtrForeignTextField, + name={\csfmt{Gls\-Xtr\-Foreign\-Text\-Field}}, + description={used by \cs{GlsXtrForeignText} to identify + the field containing the locale tag}, + topics={fieldrefcommands}, + note={\styfmt{glossaries-extra} v1.32+}, + category={command} +} + +@glscommand{glsxtrparen, + name={\csfmt{gls\-xtr\-paren}}, + user1={\margm{text}}, + description={used to markup parenthetical material, such as + in \cs{glsxtrpostlinkAddDescOnFirstUse} or in the + \abbrstyle{long-short} and \abbrstyle{short-long} abbreviation + styles}, + topics={formattingcommands}, + note={\styfmt{glossaries-extra} v1.17+}, + category={command} +} + +@glscommand{glsxtrpostdescabbreviation, + name={\csfmt{gls\-xtr\-post\-desc\-abbreviation}}, + user1={}, + description={hook used after the description is displayed in the + glossary for entries that have the + \field{category} set to \code{abbreviation}}, + topics={hooks,abbreviationcommands}, + note={\styfmt{glossaries-extra}}, + category={command} +} + +@glscommand{glsxtrpostdescsymbol, + name={\csfmt{gls\-xtr\-post\-desc\-symbol}}, + user1={}, + description={hook used after the description is displayed in the + glossary for entries that have the + \field{category} set to \code{symbol}}, + topics={hooks}, + note={\styfmt{glossaries-extra}}, + category={command} +} + +@glscommand{glsxtrpostdescgeneral, + name={\csfmt{gls\-xtr\-post\-desc\-general}}, + user1={}, + description={hook used after the description is displayed in the + glossary for entries that have the + \field{category} set to \code{general}}, + topics={hooks}, + note={\styfmt{glossaries-extra}}, + category={command} +} + +@glscommand{glsxtrpostdesccategory, + name={\csfmt{gls\-xtr\-post\-desc\-\meta{category}}}, + user1={}, + description={hook used after the description is displayed in the + glossary for entries that have the + \field{category} set to \meta{category}. Common category hooks + such as \cs{glsxtrpostdescgeneral} are provided by + \styfmt{glossaries-extra}. If required, + this hook can be defined with \cs{glsdefpostdesc}}, + topics={hooks,glossarystylecommands}, + note={\styfmt{glossaries-extra}}, + category={command} +} + +@glscommand{glsxtrpostnamecategory, + name={\csfmt{gls\-xtr\-post\-name\-\meta{category}}}, + user1={}, + description={hook used by \cs{glossentryname} for entries + that have the \field{category} set to \meta{category}. + If required, this hook can be defined with \cs{glsdefpostname}}, + topics={hooks,glossarystylecommands}, + note={\styfmt{glossaries-extra}}, + category={command} +} + +@glscommand{glsxtrpostlinkcategory, + name={\csfmt{gls\-xtr\-post\-link\-\meta{category}}}, + user1={}, + description={hook used after commands like \cs{gls} + for entries that have the + \field{category} set to \meta{category}. If required, + this hook can be defined with \cs{glsdefpostlink}}, + topics={hooks}, + note={\styfmt{glossaries-extra}}, + category={command} +} + +@glscommand{GlsXtrFmtDefaultOptions, + name={\csfmt{Gls\-Xtr\-Fmt\-Default\-Options}}, + user1={}, + description={the default options used by \csref{glsxtrfmt}}, + topics={formattingcommands,indexing}, + note={\styfmt{glossaries-extra} v1.12+}, + category={command} +} + +@glscommand{glslink, + name={\csfmt{glslink}}, + user1={\oargm{options}\margm{label}\margm{text}}, + description={links to the entry's definition in the glossary with + the given link text without altering the first use flag}, + topics={entryrefcommands,linkcommands}, + note={\styfmt{glossaries}}, + seealso={glsdisp}, + category={command} +} + +@glscommand{glsdisp, + name={\csfmt{glsdisp}}, + user1={\oargm{options}\margm{label}\margm{text}}, + description={links to the entry's definition in the glossary with + the given link text and marks the entry as having been used. + The options are the same as for \cs{glslink}}, + topics={entryrefcommands,linkcommands}, + note={\styfmt{glossaries}}, + seealso={glslink}, + category={command} +} + +@glscommand{dglslink, + name={\csfmt{dgls\-link}}, + user1={\oargm{options}\margm{label}\margm{text}}, + description={like \cs{glslink} but tries the prefixes + identified with commands like \cs{glsxtraddlabelprefix}}, + topics={entryrefcommands,linkcommands}, + note={\styfmt{glossaries-extra-bib2gls} v1.37+}, + seealso={dglsdisp}, + category={command} +} + +@glscommand{dglsdisp, + name={\csfmt{dgls\-disp}}, + user1={\oargm{options}\margm{label}\margm{text}}, + description={like \cs{glsdisp} but tries the prefixes + identified with commands like \cs{glsxtraddlabelprefix}}, + topics={entryrefcommands,linkcommands}, + note={\styfmt{glossaries-extra-bib2gls} v1.37+}, + seealso={dglsdisp}, + category={command} +} + +@glscommand{glsxtrshort, + name={\csfmt{glsxtrshort}}, + user1={\oargm{options}\margm{label}}, + description={links to the entry's definition in the glossary with + the link text obtained from the \field{short} field (using the + appropriate abbreviation style) without altering the first use flag}, + topics={entryrefcommands,linkcommands,abbreviationcommands,fieldrefcommands}, + note={\styfmt{glossaries-extra}}, + category={command} +} + +@glscommand{glsxtrlong, + name={\csfmt{glsxtrlong}}, + user1={\oargm{options}\margm{label}}, + description={links to the entry's definition in the glossary with + the link text obtained from the \field{long} field (using the + appropriate abbreviation style) + without altering the first use flag}, + topics={entryrefcommands,linkcommands,abbreviationcommands,fieldrefcommands}, + note={\styfmt{glossaries-extra}}, + category={command} +} + +@glscommand{glsxtrfull, + name={\csfmt{glsxtrfull}}, + user1={\oargm{options}\margm{label}}, + description={links to the entry's definition in the glossary with + the link text obtained from the \field{long} and \field{short} + fields (using the appropriate abbreviation style) + without altering the first use flag}, + topics={entryrefcommands,linkcommands,abbreviationcommands}, + note={\styfmt{glossaries-extra}}, + category={command} +} + +@glscommand{glsxtrword, + name={\csfmt{glsxtrword}}, + user1={\margm{text}}, + description={used to encapsulate each word in the long form of an +abbreviation by the \catattr{markwords} attribute}, + topics={formattingcommands,abbreviationcommands}, + note={\styfmt{glossaries-extra} v1.17+}, + category={command} +} + +@glscommand{glsxtrwordsep, + name={\csfmt{glsxtrwordsep}}, + description={used to mark spaces between each word in the long form of an + abbreviation by the \catattr{markwords} attribute}, + topics={separatorcommands,abbreviationcommands}, + note={\styfmt{glossaries-extra} v1.17+}, + category={command} +} + +@glscommand{glstext, + name={\csfmt{glstext}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={links to the entry's definition in the glossary with + the link text obtained from the \field{text} field + without altering the first use flag}, + topics={entryrefcommands,fieldrefcommands,linkcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{Glstext, + name={\csfmt{Glstext}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={as \cs{glstext} but converts the first letter to + \idx{uppercase}}, + topics={entryrefcommands,fieldrefcommands,linkcommands,casecommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glsname, + name={\csfmt{glsname}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={links to the entry's definition in the glossary with + the link text obtained from the \field{name} field + without altering the first use flag}, + topics={entryrefcommands,fieldrefcommands,linkcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glsfirst, + name={\csfmt{glsfirst}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={links to the entry's definition in the glossary with + the link text obtained from the \field{first} field + without altering the first use flag}, + topics={entryrefcommands,fieldrefcommands,linkcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{Glsfirst, + name={\csfmt{Glsfirst}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={as \cs{glsfirst} but converts the first letter to + \idx{uppercase}}, + topics={entryrefcommands,fieldrefcommands,linkcommands,casecommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glssymbol, + name={\csfmt{glssymbol}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={links to the entry's definition in the glossary with + the link text obtained from the \field{symbol} field + without altering the first use flag}, + topics={entryrefcommands,fieldrefcommands,linkcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glsdesc, + name={\csfmt{glsdesc}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={links to the entry's definition in the glossary with + the link text obtained from the \field{description} field + without altering the first use flag}, + topics={entryrefcommands,fieldrefcommands,linkcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glsuseri, + name={\csfmt{glsuseri}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={links to the entry's definition in the glossary with + the link text obtained from the \field{user1} field + without altering the first use flag}, + topics={entryrefcommands,fieldrefcommands,linkcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glsuserii, + name={\csfmt{glsuserii}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={links to the entry's definition in the glossary with + the link text obtained from the \field{user2} field + without altering the first use flag}, + topics={entryrefcommands,fieldrefcommands,linkcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glsuseriii, + name={\csfmt{glsuseriii}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={links to the entry's definition in the glossary with + the link text obtained from the \field{user3} field + without altering the first use flag}, + topics={entryrefcommands,fieldrefcommands,linkcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glsuseriv, + name={\csfmt{glsuseriv}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={links to the entry's definition in the glossary with + the link text obtained from the \field{user4} field + without altering the first use flag}, + topics={entryrefcommands,fieldrefcommands,linkcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glsuserv, + name={\csfmt{glsuserv}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={links to the entry's definition in the glossary with + the link text obtained from the \field{user5} field + without altering the first use flag}, + topics={entryrefcommands,fieldrefcommands,linkcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glsuservi, + name={\csfmt{glsuservi}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={links to the entry's definition in the glossary with + the link text obtained from the \field{user6} field + without altering the first use flag}, + topics={entryrefcommands,fieldrefcommands,linkcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@mainglscommand{rgls, + name={\csfmt{rgls}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={like \cs{gls} but checks for the record + count trigger setting (the formatting is governed by \cs{rglsformat})}, + topics={entryrefcommands,linkcommands}, + note={\styfmt{glossaries-extra} v1.21+}, + category={command} +} + +@mainglscommand{rglsformat, + name={\csfmt{rglsformat}}, + user1={\margm{label}\oargm{insert}}, + description={used by \csref{rgls} if the record count + switch is triggered}, + topics={formattingcommands}, + note={\styfmt{glossaries-extra} v1.21+}, + category={command} +} + +@glscommand{glsxtrenablerecordcount, + name={\csfmt{glsxtr\-enable\-record\-count}}, + user1={}, + description={redefines \cs{gls} etc to their \csref{rgls} counterpart}, + topics={providingcommands}, + note={\styfmt{glossaries-extra} v1.21+}, + category={command} +} + +@mainglscommand{GlsXtrSetRecordCountAttribute, + name={\csfmt{Gls\-Xtr\-Set\-Record\-Count\-Attribute}}, + user1={\margm{category list}\margm{value}}, + description={sets the \catattr{recordcount} attribute to + \meta{value} for the given categories}, + topics={assigncommands}, + note={\styfmt{glossaries-extra} v1.21+}, + category={command} +} + +@glscommand{gls, + name={\csfmt{gls}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={on first use displays the first use text + (the value of the \field{first} field + for general entries) and on subsequent use displays + the subsequent use text (the value of the \field{text} field + for general entries) where the text is optionally hyperlinked + to the relevant place in the glossary. The options are + the same as for \cs{glslink}}, + topics={entryrefcommands,linkcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glslinkoption{gls.format, + name={\csoptfmt{format}}, + user1={\margm{encap}}, + category={commandoption}, + description={sets the \gls{encap} for the record to + \meta{encap}, optionally with the start or end range markers}, + note={\styfmt{glossaries}}, + parent={glslink} +} + +@glslinkoption{gls.counter, + name={\csoptfmt{counter}}, + user1={\margm{counter-name}}, + description={sets the counter to use for the record}, + category={commandoption}, + note={\styfmt{glossaries}}, + parent={glslink} +} + +@glslinkoption{gls.noindex, + name={\csoptfmt{noindex}}, + user1={\margm{boolean}}, + description={indicates whether or not to suppress indexing}, + category={commandoption}, + note={\styfmt{glossaries-extra}}, + parent={glslink} +} + +@glslinkoption{gls.wrgloss, + name={\csoptfmt{wrgloss}}, + user1={\margm{value}}, + description={indicates whether to write the glossary information + before (\csoptfmt{wrgloss\dequals before}) or after + (\csoptfmt{wrgloss\dequals after}) the link text (default: + \csoptfmt{before})}, + category={commandoption}, + note={\styfmt{glossaries-extra} v1.14+}, + parent={glslink} +} + +@glslinkoption{gls.thevalue, + name={\csoptfmt{thevalue}}, + user1={\margm{value}}, + description={overrides the record value so that it's the + given \meta{value} not obtained from the associated counter}, + category={commandoption}, + note={\styfmt{glossaries-extra} v1.19+}, + parent={glslink} +} + +@glslinkoption{gls.theHvalue, + name={\csoptfmt{theHvalue}}, + user1={\margm{value}}, + description={the hyperlink target corresponding to the value + of \glsopt{thevalue}, if appropriate}, + category={commandoption}, + note={\styfmt{glossaries-extra} v1.19+}, + parent={glslink} +} + +@glslinkoption{gls.hyper, + name={\csoptfmt{hyper}}, + user1={\margm{boolean}}, + description={indicates whether or not to make a hyperlink to the + relevant glossary entry}, + category={commandoption}, + note={\styfmt{glossaries}}, + parent={glslink} +} + +@glslinkoption{gls.local, + name={\csoptfmt{local}}, + user1={\margm{boolean}}, + description={if \csoptfmt{true} indicates to use \ics{glslocalunset} + instead of the default global \cs{glsunset} to unset the + \idx{firstuseflag}}, + category={commandoption}, + note={\styfmt{glossaries}}, + parent={glslink} +} + +@glslinkoption{gls.textformat, + name={\csoptfmt{text\-format}}, + user1={\margm{cs-name}}, + description={if set, replaces \cs{glstextformat} with + the command given by the control sequence name + \meta{cs-name} to format the \idx{link-text}}, + category={commandoption}, + note={\styfmt{glossaries-extra} v1.30+}, + parent={glslink} +} + +@glslinkoption{gls.prefix, + name={\csoptfmt{prefix}}, + user1={\margm{label}}, + description={locally changes \ics{glolinkprefix} to the + given \meta{label}}, + category={commandoption}, + note={\styfmt{glossaries-extra} v1.31+}, + parent={glslink} +} + +@glslinkoption{gls.hyperoutside, + name={\csoptfmt{hyper\-out\-side}}, + user1={\margm{boolean}}, + description={determines whether \cs{hyperlink} should + be outside of \cs{glstextformat} (default + \csoptfmt{hyperoutside\dequals true}) or inside + (\csoptfmt{hyperoutside\dequals false})}, + category={commandoption}, + note={\styfmt{glossaries-extra} v1.21+}, + parent={glslink} +} + +@glscommand{glspl, + name={\csfmt{glspl}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={as \cs{gls} but shows the plural form}, + topics={entryrefcommands,linkcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{Gls, + name={\csfmt{Gls}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={as \cs{gls} but converts the first letter + of the link text to \idx{uppercase}}, + topics={entryrefcommands,linkcommands,casecommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{Glspl, + name={\csfmt{Glspl}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={as \cs{Gls} but shows the plural form}, + topics={entryrefcommands,linkcommands,casecommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{GLS, + name={\csfmt{GLS}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={as \cs{gls} but converts the link text to \idx{uppercase}}, + topics={entryrefcommands,linkcommands,casecommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{GLSpl, + name={\csfmt{GLSpl}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={as \cs{GLS} but shows the plural form}, + topics={entryrefcommands,linkcommands,casecommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{pgls, + name={\csfmt{pgls}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={does \meta{prefix}\cs{gls}\oargm{options}\margm{label}\oargm{insert}, + where the \meta{prefix} is obtained from the appropriate prefix + field}, + topics={entryrefcommands,fieldrefcommands,linkcommands}, + note={\styfmt{glossaries-prefix}}, + category={command} +} + +@glscommand{Pgls, + name={\csfmt{Pgls}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={does \meta{prefix}\cs{gls}\oargm{options}\margm{label}\oargm{insert}, + where the \meta{prefix} is obtained from the appropriate prefix + field with the first letter converted to \idx{uppercase}}, + topics={entryrefcommands,fieldrefcommands,linkcommands,casecommands}, + note={\styfmt{glossaries-prefix}}, + category={command} +} + +@glscommand{PGLS, + name={\csfmt{PGLS}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={does \meta{prefix}\cs{GLS}\oargm{options}\margm{label}\oargm{insert}, + where the \meta{prefix} is obtained from the appropriate prefix + field with the text converted to \idx{uppercase}}, + topics={entryrefcommands,fieldrefcommands,linkcommands,casecommands}, + note={\styfmt{glossaries-prefix}}, + category={command} +} + +@glscommand{pglspl, + name={\csfmt{pglspl}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={does \meta{prefix}\cs{glspl}\oargm{options}\margm{label}\oargm{insert}, + where the \meta{prefix} is obtained from the appropriate prefix + field}, + topics={entryrefcommands,fieldrefcommands,linkcommands}, + note={\styfmt{glossaries-prefix}}, + category={command} +} + +@glscommand{Pglspl, + name={\csfmt{Pglspl}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={does \meta{prefix}\cs{glspl}\oargm{options}\margm{label}\oargm{insert}, + where the \meta{prefix} is obtained from the appropriate prefix + field with the first letter converted to \idx{uppercase}}, + topics={entryrefcommands,fieldrefcommands,linkcommands,casecommands}, + note={\styfmt{glossaries-prefix}}, + category={command} +} + +@glscommand{PGLSpl, + name={\csfmt{PGLSpl}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={does \meta{prefix}\cs{GLSpl}\oargm{options}\margm{label}\oargm{insert}, + where the \meta{prefix} is obtained from the appropriate prefix + field with the text converted to \idx{uppercase}}, + topics={entryrefcommands,fieldrefcommands,linkcommands,casecommands}, + note={\styfmt{glossaries-prefix}}, + category={command} +} + +@glscommand{dgls, + name={\csfmt{dgls}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={intended for documents with a mixture of + single and dual entries, this is like \cs{gls} but tries to + determine the label prefix from the label prefix list}, + topics={entryrefcommands,linkcommands}, + note={\styfmt{glossaries-extra-bib2gls} v1.37+}, + seealso={glsxtraddlabelprefix,glsxtrprependlabelprefix}, + category={command} +} + +@glscommand{dglspl, + name={\csfmt{dglspl}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={intended for documents with a mixture of + single and dual entries, this is like \cs{glspl} but tries to + determine the label prefix from the label prefix list}, + topics={entryrefcommands,linkcommands}, + note={\styfmt{glossaries-extra-bib2gls} v1.37+}, + seealso={glsxtraddlabelprefix,glsxtrprependlabelprefix}, + category={command} +} + +@glscommand{dGls, + name={\csfmt{dGls}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={intended for documents with a mixture of + single and dual entries, this is like \cs{Gls} but tries to + determine the label prefix from the label prefix list}, + topics={entryrefcommands,linkcommands,casecommands}, + note={\styfmt{glossaries-extra-bib2gls} v1.37+}, + seealso={glsxtraddlabelprefix,glsxtrprependlabelprefix}, + category={command} +} + +@glscommand{dGlspl, + name={\csfmt{dGlspl}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={intended for documents with a mixture of + single and dual entries, this is like \cs{Glspl} but tries to + determine the label prefix from the label prefix list}, + topics={entryrefcommands,linkcommands,casecommands}, + note={\styfmt{glossaries-extra-bib2gls} v1.37+}, + seealso={glsxtraddlabelprefix,glsxtrprependlabelprefix}, + category={command} +} + +@glscommand{glsxtraddlabelprefix, + name={\csfmt{gls\-xtr\-add\-label\-prefix}}, + user1={\margm{prefix}}, + description={appends \meta{prefix} to the prefix label list}, + topics={listcommands}, + note={\styfmt{glossaries-extra-bib2gls} v1.37+}, + seealso={dgls,glsxtrprependlabelprefix,glsxtrclearlabelprefixes}, + category={command} +} + +@glscommand{glsxtrprependlabelprefix, + name={\csfmt{gls\-xtr\-prepend\-label\-prefix}}, + user1={\margm{prefix}}, + description={prepends \meta{prefix} to the prefix label list}, + topics={listcommands}, + note={\styfmt{glossaries-extra-bib2gls} v1.37+}, + seealso={dgls,glsxtraddlabelprefix,glsxtrclearlabelprefixes}, + category={command} +} + +@glscommand{glsxtrclearlabelprefixes, + name={\csfmt{gls\-xtr\-clear\-label\-prefixes}}, + user1={\margm{prefix}}, + description={clears the prefix label list}, + topics={listcommands}, + note={\styfmt{glossaries-extra-bib2gls} v1.37+}, + seealso={glsxtraddlabelprefix,glsxtrprependlabelprefix}, + category={command} +} + +@glscommand{glssetwidest, + name={\csfmt{gls\-set\-widest}}, + user1={\oargm{level}\margm{text}}, + description={used with the \glostyle{alttree} style to set the + widest entry name for the given level}, + topics={assigncommands,glossarystylecommands}, + note={\styfmt{glossary-tree}}, + category={command} +} + +@glscommand{glsxtrSetWidest, + name={\csfmt{gls\-xtr\-Set\-Widest}}, + user1={\margm{type}\margm{level}\margm{text}}, + description={used by \csref{bibglssetwidest} to set the + widest entry name for the given level for the \glostyle{alttree} + style and the styles provided by \sty{glossary-longextra}}, + topics={assigncommands,glossarystylecommands}, + note={\styfmt{glossaries-extra-bib2gls} v1.37+}, + seealso={glssetwidest,glslongextraSetWidest}, + category={command} +} + +@glscommand{glsxtrSetWidestFallback, + name={\csfmt{gls\-xtr\-Set\-Widest\-Fallback}}, + user1={\margm{max depth}\margm{list}}, + description={used by \csref{bibglssetwidesttoplevelfallback} and + \csref{bibglssetwidestfallback} to set the + widest entry name for the \glostyle{alttree} + style and the styles provided by \sty{glossary-longextra} + using the commands provided by \sty{glossaries-extra-stylemods}}, + topics={assigncommands,glossarystylecommands}, + note={\styfmt{glossaries-extra-bib2gls} v1.37+}, + seealso={glsFindWidestTopLevelName,glsFindWidestLevelTwo}, + category={command} +} + +@glscommand{glslongextraSetWidest, + name={\csfmt{gls\-long\-extra\-Set\-Widest}}, + user1={\margm{text}}, + description={used with the styles provided by the + \sty{glossary-longextra} package to set the + widest entry name}, + topics={assigncommands,glossarystylecommands}, + note={\styfmt{glossary-longextra} v1.37+}, + seealso={glslongextraUpdateWidest}, + category={command} +} + +@glscommand{glslongextraUpdateWidest, + name={\csfmt{gls\-long\-extra\-Update\-Widest}}, + user1={\margm{text}}, + description={as \cs{glslongextraSetWidest} but only sets if \meta{text} is + wider than the current value}, + topics={assigncommands,glossarystylecommands}, + note={\styfmt{glossary-longextra} v1.37+}, + category={command} +} + +@glscommand{glsupdatewidest, + name={\csfmt{gls\-update\-widest}}, + user1={\oargm{level}\margm{text}}, + description={as \cs{glssetwidest} but only sets if \meta{text} is +wider than the current value}, + topics={assigncommands,glossarystylecommands}, + note={\styfmt{glossaries-extra-stylemods} v1.23+}, + seealso={glssetwidest,eglsupdatewidest}, + category={command} +} + +@glscommand{eglsupdatewidest, + name={\csfmt{egls\-update\-widest}}, + user1={\oargm{level}\margm{text}}, + description={as \cs{glsupdatewidest} but expands \meta{text}}, + topics={assigncommands,glossarystylecommands}, + note={\styfmt{glossaries-extra-stylemods} v1.23+}, + seealso={glssetwidest,glsupdatewidest}, + category={command} +} + +@glscommand{glsFindWidestTopLevelName, + name={\csfmt{gls\-Find\-Widest\-Top\-Level\-Name}}, + user1={\oargm{glossary list}}, + description={CamelCase synonym for \cs{glsfindwidesttoplevelname}}, + topics={assigncommands,glossarystylecommands}, + note={\styfmt{glossaries-extra-stylemods}}, + seealso={glsfindwidesttoplevelname}, + category={command} +} + +@glscommand{glsfindwidesttoplevelname, + name={\csfmt{gls\-find\-widest\-top\-level\-name}}, + user1={\oargm{glossary list}}, + description={finds the widest top-level name in the given +glossaries}, + topics={assigncommands,glossarystylecommands}, + note={\styfmt{glossary-tree}}, + category={command} +} + +@glscommand{glsFindWidestLevelTwo, + name={\csfmt{gls\-Find\-Widest\-Level\-Two}}, + user1={\oargm{glossary list}}, + description={finds the widest name in the given glossaries + for the top level and first two sub-levels}, + topics={assigncommands,glossarystylecommands}, + note={\styfmt{glossaries-extra-stylemods}}, + seealso={glsfindwidesttoplevelname}, + category={command} +} + +@glscommand{glsxtrbookindexname, + name={\csfmt{glsxtr\-book\-index\-name}}, + user1={\margm{label}}, + description={used with the \glostyle{bookindex} style to + format the entry's name}, + topics={formattingcommands,glossarystylecommands}, + note={\styfmt{glossary-bookindex}}, + category={command} +} + +@glscommand{glsxtrbookindexprelocation, + name={\csfmt{glsxtr\-book\-index\-pre\-location}}, + user1={\margm{label}}, + description={used with the \glostyle{bookindex} style before the +location list}, + topics={formattingcommands,separatorcommands,glossarystylecommands}, + note={\styfmt{glossary-bookindex}}, + category={command} +} + +@glscommand{glsxtrprelocation, + name={\csfmt{glsxtr\-pre\-location}}, + user1={}, + description={used before the location list in the + \glostyle{bookindex} style and the styles patched by + \styfmt{glossaries-extra-stylemods}}, + topics={formattingcommands,separatorcommands,glossarystylecommands}, + note={\styfmt{glossary-bookindex} v1.21+ and + \styfmt{glossaries-extra-stylemods} v1.21+}, + category={command} +} + +@glscommand{glsabbrvfont, + name={\csfmt{gls\-abbrv\-font}}, + user1={\margm{text}}, + description={generic abbreviation font command for the short form}, + topics={formattingcommands,abbreviationcommands}, + note={\styfmt{glossaries-extra}}, + category={command} +} + +@glscommand{glslongfont, + name={\csfmt{gls\-long\-font}}, + user1={\margm{text}}, + description={generic abbreviation font command for the long form}, + topics={formattingcommands,abbreviationcommands}, + note={\styfmt{glossaries-extra} v1.04+}, + category={command} +} + +@glscommand{glsshorttok, + name={\csfmt{gls\-short\-tok}}, + description={token register used in the construction of + acronyms or abbreviations to allow the style hooks to access the short form}, + topics={hooks,abbreviationcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glslongtok, + name={\csfmt{gls\-long\-tok}}, + description={token register used in the construction of + acronyms or abbreviations to allow the style hooks to access the long form}, + topics={hooks,abbreviationcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glsxtrifinmark, + name={\csfmt{gls\-xtr\-if\-in\-mark}}, + user1={\margm{true}\margm{true}}, + description={used by commands like \cs{glsfmtshort}, this expands + to \meta{true} in page headings and the table of contents, + otherwise it expands to \meta{false}}, + topics={conditionals}, + note={\styfmt{glossaries-extra} v1.07+}, + category={command} +} + +@glscommand{glsxtrRevertTocMarks, + name={\csfmt{gls\-xtr\-Revert\-Toc\-Marks}}, + description={restores original behaviour of \cs{tableofcontents} + so that \cs{glsxtrifinmark} expands to \meta{false} in the table + of contents}, + topics={providingcommands}, + note={\styfmt{glossaries-extra} v1.07+}, + category={command} +} + +@glscommand{glstreenamefmt, + name={\csfmt{gls\-tree\-name\-fmt}}, + user1={\margm{text}}, + description={used with the tree styles to format the entry's name}, + topics={formattingcommands,glossarystylecommands}, + note={\styfmt{glossary-tree} v4.08+ and +\styfmt{glossaries-extra-stylemods} v1.31+}, + seealso={glstreegroupheaderfmt,glstreenavigationfmt,glstreedefaultnamefmt}, + category={command} +} + +@glscommand{glstreegroupheaderfmt, + name={\csfmt{gls\-tree\-group\-header\-fmt}}, + user1={\margm{text}}, + description={used with the tree styles to format the group headings}, + topics={formattingcommands,glossarystylecommands}, + note={\styfmt{glossary-tree} v4.22+ and + \styfmt{glossaries-extra-stylemods} v1.31+}, + category={command} +} + +@glscommand{glstreenavigationfmt, + name={\csfmt{gls\-tree\-navigation\-fmt}}, + user1={\margm{text}}, + description={used with the tree styles to format the navigation elements}, + topics={formattingcommands,glossarystylecommands}, + note={\styfmt{glossary-tree} v4.22+ and + \styfmt{glossaries-extra-stylemods} v1.31+}, + category={command} +} + +@glscommand{glstreedefaultnamefmt, + name={\csfmt{gls\-tree\-default\-name\-fmt}}, + user1={\margm{text}}, + description={used as the default format for \cs{glstreenamefmt}, + \cs{glstreegroupheaderfmt} and \cs{glstreenavigationfmt}}, + topics={formattingcommands,glossarystylecommands}, + note={\styfmt{glossaries-extra-stylemods} v1.31+}, + category={command} +} + +@glscommand{glstreeprelocation, + name={\csfmt{gls\-tree\-pre\-location}}, + description={inserted before the location list for top-level +entries in the \glostyle{tree}-like styles}, + topics={formattingcommands,separatorcommands,glossarystylecommands}, + note={\styfmt{glossaries-extra-stylemods} v1.21+}, + category={command} +} + +@glscommand{glsdescwidth, + name={\csfmt{gls\-desc\-width}}, + user1={}, + description={length register used by the tabular styles to specify +the width of the description column}, + topics={glossarystylecommands}, + note={\styfmt{glossary-long} and + \styfmt{glossary-super}}, + category={command} +} + +@glscommand{glsxtralttreeSymbolDescLocation, + name={\csfmt{gls\-xtr\-alt\-tree\-Symbol\-Desc\-Location}}, + user1={\margm{label}\margm{location list}}, + description={used by the \glostyle{alttree} styles to format the +symbol, description and location}, + topics={formattingcommands,glossarystylecommands}, + note={\styfmt{glossaries-extra-stylemods} v1.05+}, + category={command} +} + +@glscommand{glsxtrAltTreePar, + name={\csfmt{gls\-xtr\-Alt\-Tree\-Par}}, + description={used by the \glostyle{alttree} styles to indicate a +paragraph break that retains the hanging indent}, + topics={formattingcommands,glossarystylecommands}, + note={\styfmt{glossaries-extra-stylemods} v1.05+}, + category={command} +} + +@glscommand{glsaccsupp, + name={\csfmt{gls\-acc\-supp}}, + user1={\margm{accessible text}\margm{text}}, + description={used by the accessibility support to interface with + the \sty{accsupp} package (use \cs{xglsaccsupp} if \meta{text} + needs to be fully expanded first)}, + topics={access-support}, + note={\styfmt{glossaries-accsupp}}, + seealso={xglsaccsupp}, + category={command} +} + +@glscommand{xglsaccsupp, + name={\csfmt{xgls\-acc\-supp}}, + user1={\margm{accessible text}\margm{text}}, + description={used by the accessibility support to interface with + the \sty{accsupp} package, where \meta{text} is fully expanded}, + topics={access-support}, + note={\styfmt{glossaries-accsupp}}, + seealso={glsaccsupp}, + category={command} +} + +@glscommand{forglsentries, + name={\csfmt{for\-gls\-entries}}, + user1={\oargm{type}\margm{cs}\margm{body}}, + description={iterates over all entries defined in the glossary + identified by \meta{type} (or the default, if \meta{type} + is omitted) and perform \meta{body} where you can use the + control sequence \meta{cs} to reference the current entry label}, + topics={loops,entryrefcommands}, + note={\styfmt{glossaries}}, + seealso={forallglsentries}, + category={command} +} + +@glscommand{forallglsentries, + name={\csfmt{for\-all\-gls\-entries}}, + user1={\oargm{glossary-list}\margm{cs}\margm{body}}, + description={iterates over all entries defined in the + comma-separated \meta{glossary-list} (or all defined non-ignored + glossaries if the optional argument is omitted) and perform + \meta{body} where you can use the control sequence \meta{cs} to + reference the current entry label}, + topics={loops,glossrefs,entryrefcommands}, + note={\styfmt{glossaries}}, + seealso={forglsentries,forallglossaries}, + category={command} +} + +@glscommand{forallglossaries, + name={\csfmt{for\-all\-glos\-saries}}, + user1={\oargm{glossary-list}\margm{cs}\margm{body}}, + description={iterates over all glossaries identified in the + comma-separated \meta{glossary-list} (or all defined non-ignored + glossaries if the optional argument is omitted) and performs \meta{body} + where you can use the control sequence \meta{cs} to reference + the current glossary label}, + topics={loops,glossrefs}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glsxtrforcsvfield, + name={\csfmt{gls\-xtr\-for\-csv\-field}}, + user1={\margm{label}\margm{field}\margm{handler}}, + description={iterates over the comma-separated list + in the given \meta{field} for the entry identified + by \meta{label} and performs \meta{handler}\margm{element} + on each element of the list, where \meta{handler} is + a control sequence which takes a single argument}, + topics={loops,fieldrefcommands,listcommands}, + note={\styfmt{glossaries}}, + note={\styfmt{glossaries-extra} v1.24+}, + seealso={glsxtrendfor}, + category={command} +} + +@glscommand{glsxtrendfor, + name={\csfmt{gls\-xtr\-end\-for}}, + user1={}, + description={may be used within the handler macro + of \cs{glsxtrforcsvfield} to prematurely break the loop}, + topics={loops,listcommands}, + note={\styfmt{glossaries-extra} v1.24+}, + seealso={glsxtrforcsvfield}, + category={command} +} + +@glscommand{ifglossaryexists, + name={\csfmt{if\-glossary\-exists}}, + user1={\margm{type}\margm{true}\margm{false}}, + description={tests if the glossary given by \meta{type} exists + and does \meta{true} if it does exists, otherwise does \meta{false}}, + topics={conditionals,glossrefs}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{ifignoredglossary, + name={\csfmt{if\-ignored\-glossary}}, + user1={\margm{type}\margm{true}\margm{false}}, + description={tests if the glossary given by \meta{type} was + defined as an ignored glossary}, + topics={conditionals,glossrefs}, + note={\styfmt{glossaries} v4.08+}, + category={command} +} + +@glscommand{glsdoifexists, + name={\csfmt{gls\-do\-if\-exists}}, + user1={\margm{label}\margm{code}}, + description={if the entry given by \meta{label} exists, \meta{code} + is done, otherwise an error (or warning with + \sty{glossaries-extra}'s \styopt[warn]{undefaction} option) is + triggered}, + topics={conditionals,entryrefcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glsdoifnoexists, + name={\csfmt{gls\-do\-if\-no\-exists}}, + user1={\margm{label}\margm{code}}, + description={if the entry given by \meta{label} doesn't exist, \meta{code} + is done, otherwise an error (or warning with + \sty{glossaries-extra}'s \styopt[warn]{undefaction} option) is + triggered}, + topics={conditionals,entryrefcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glsdoifexistsordo, + name={\csfmt{gls\-do\-if\-exists\-or\-do}}, + user1={\margm{label}\margm{code}\margm{else code}}, + description={if the entry given by \meta{label} exists, \meta{code} + is done, otherwise an error (or warning with + \sty{glossaries-extra}'s \styopt[warn]{undefaction} option) is + triggered and \meta{else code} is done}, + topics={conditionals,entryrefcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glsdoifnoexistsordo, + name={\csfmt{gls\-do\-if\-no\-exists\-or\-do}}, + user1={\margm{label}\margm{code}\margm{else code}}, + description={if the entry given by \meta{label} doesn't exist, \meta{code} + is done, otherwise an error (or warning with + \sty{glossaries-extra}'s \styopt[warn]{undefaction} option) is + triggered and \meta{else code} is done}, + topics={conditionals,entryrefcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@command{TrackLocale, + name={\csfmt{Track\-Locale}}, + user1={\margm{language tag}}, + description={tracks the given language tag}, + note={\styfmt{tracklang} v1.3+}, + category={command} +} + +@command{GetTrackedDialectFromLanguageTag, + name={\csfmt{Get\-Tracked\-Dialect\-From\-Language\-Tag}}, + user1={\margm{language tag}\margm{cs}}, + description={gets the \styfmt{tracklang} dialect label from the +given language tag and stores it in the command \meta{cs}. The +result will be empty if there's no tracked dialect associated with +the given language tag}, + note={\styfmt{tracklang} v1.3+}, + category={command} +} + +@command{TrackedDialectClosestSubMatch, + name={\csfmt{Tracked\-Dialect\-Closest\-Sub\-Match}}, + description={set by \cs{GetTrackedDialectFromLanguageTag} + if an exact match isn't found but a partial match on the + root language is found}, + note={\styfmt{tracklang} v1.3.6+}, + category={command} +} + +@command{IfTrackedDialectHasMapping, + name={\csfmt{If\-Tracked\-Dialect\-Has\-Mapping}}, + user1={\margm{tracklang label}\margm{true}\margm{false}}, + description={tests if the \styfmt{tracklang} dialect label has +been assigned a mapping to a language hook label}, + note={\styfmt{tracklang} v1.3+}, + category={command} +} + +@command{GetTrackedDialectToMapping, + name={\csfmt{Get\-Tracked\-Dialect\-To\-Mapping}}, + user1={\margm{tracklang label}}, + description={the language hook label corresponding to the given +\sty{tracklang} label}, + note={\styfmt{tracklang} v1.3+}, + category={command} +} + +@glscommand{glstextformat, + name={\csfmt{glstextformat}}, + user1={\margm{text}}, + description={used by commands like \cs{gls} to format the + \idx{link-text}}, + topics={formattingcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glsxtrregularfont, + name={\csfmt{gls\-xtr\-reg\-u\-lar\-font}}, + user1={\margm{text}}, + description={used by commands like \cs{gls} to format the + \idx{link-text} for regular terms}, + topics={formattingcommands}, + note={\styfmt{glossaries-extra} v1.04+}, + category={command} +} + +@glscommand{glsxtrabbreviationfont, + name={\csfmt{gls\-xtr\-abbre\-vi\-a\-tion\-font}}, + user1={\margm{text}}, + description={used by commands like \cs{gls} to format the + \idx{link-text} for (non-regular) abbreviations}, + topics={formattingcommands,abbreviationcommands}, + note={\styfmt{glossaries-extra} v1.30+}, + category={command} +} + +@glscommand{GlsXtrExpandedFmt, + name={\csfmt{Gls\-Xtr\-Expanded\-Fmt}}, + user1={\margm{cs}\margm{text}}, + description={fully expands \meta{text} and then does + \meta{cs}\margm{expanded text}}, + topics={formattingcommands}, + note={\styfmt{glossaries-extra} v1.30+}, + category={command} +} + +@glscommand{GlsXtrStartUnsetBuffering, + name={\csfmt{Gls\-Xtr\-Start\-Unset\-Buffer\-ing}}, + description={starts buffering calls to \cs{glsunset} + (which is internally used by commands like \cs{gls}) + for use in code where the boolean switch causes a problem. + The buffer can later be processed and cleared with + \cs{GlsXtrStopUnsetBuffering}. The starred form + (added to v1.31) avoids duplicate labels in the buffer's + internal list}, + topics={entryrefcommands,conditionals}, + note={\styfmt{glossaries-extra} v1.30+}, + seealso={GlsXtrForUnsetBufferedList}, + category={command} +} + +@glscommand{GlsXtrStopUnsetBuffering, + name={\csfmt{Gls\-Xtr\-Stop\-Unset\-Buffer\-ing}}, + description={unsets (locally with the starred form) the + \idx{firstuseflag} of all the entry whose labels are stored in the + buffer that was started with + \cs{GlsXtrStartUnsetBuffering} and then clears the buffer}, + topics={entryrefcommands,conditionals}, + note={\styfmt{glossaries-extra} v1.30+}, + seealso={GlsXtrForUnsetBufferedList}, + category={command} +} + +@glscommand{GlsXtrForUnsetBufferedList, + name={\csfmt{Gls\-Xtr\-For\-Unset\-Buffered\-List}}, + user1 = {\margm{cs}}, + description={iterates over + all the entry whose labels are stored in the + buffer that was started with + \cs{GlsXtrStartUnsetBuffering} and implements + \meta{cs}\margm{label} at each iteration}, + topics={entryrefcommands,listcommands}, + note={\styfmt{glossaries-extra} v1.31+}, + category={command} +} + +@glscommand{glsunset, + name={\csfmt{gls\-unset}}, + user1 = {\margm{label}}, + description={unsets the \idx{firstuseflag} so that the entry is +marked as having been used}, + topics={conditionals}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glslocalunset, + name={\csfmt{gls\-local\-unset}}, + user1 = {\margm{label}}, + description={locally unsets the \idx{firstuseflag} so that the entry is +marked as having been used}, + topics={conditionals}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glsreset, + name={\csfmt{gls\-reset}}, + user1 = {\margm{label}}, + description={resets the \idx{firstuseflag} so that the entry is +marked as not used}, + topics={conditionals}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glslocalreset, + name={\csfmt{gls\-local\-reset}}, + user1 = {\margm{label}}, + description={locally resets the \idx{firstuseflag} so that the entry is +marked as not used}, + topics={conditionals}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glspatchtabularx, + name={\csfmt{gls\-patch\-tab\-ularx}}, + description={preamble command that will patch the \env{tabularx} + environment to deal with the problem of unsetting the + \idx{firstuseflag} either explicitly with \cs{glsunset} or + implicitly through commands like \cs{gls} (does nothing if + \sty{tabularx} hasn't been loaded)}, + topics={hooks,entryrefcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@command{TrackLangLastTrackedDialect, + name={\csfmt{Track\-Lang\-Last\-Tracked\-Dialect}}, + user1={}, + description={set by commands like \cs{TrackLocale}}, + note={\styfmt{tracklang}}, + category={command} +} + +@command{TrackedLanguageFromDialect, + name={\csfmt{Tracked\-Language\-From\-Dialect}}, + user1={\margm{dialect}}, + description={expands to the root language associated with the +given (\styfmt{tracklang}) dialect label}, + note={\styfmt{tracklang}}, + category={command} +} + +@command{DTMdisplaydate, + name={\csfmt{DTM\-display\-date}}, + user1={\margm{year}\margm{month}\margm{day}\margm{dow}}, + description={formats the given date where all arguments are + numeric}, + note={\styfmt{datetime2}}, + category={command} +} + +@command{DTLformatlist, + name={\csfmt{DTL\-format\-list}}, + user1={\margm{list}}, + description={formats a comma-separated list}, + note={\styfmt{datatool-base}\texparserdefnote\ v2.28+}, + seealso={ifDTLlistskipempty}, + category={command} +} + +@command{DTLlistformatitem, + name={\csfmt{DTL\-list\-format\-item}}, + user1={\margm{element}}, + description={used by \ics{DTLformatlist} to format each + element in the list}, + note={\styfmt{datatool-base}\texparserdefnote\ v2.28+}, + seealso={DTLformatlist}, + category={command} +} + +@command{DTLlistformatsep, + name={\csfmt{DTL\-list\-format\-sep}}, + user1={}, + description={used by \ics{DTLformatlist} to separate items in the +list, except for the last pair}, + note={\styfmt{datatool-base}\texparserdefnote\ v2.28+}, + seealso={DTLformatlist}, + category={command} +} + +@command{DTLlistformatlastsep, + name={\csfmt{DTL\-list\-format\-last\-sep}}, + user1={}, + description={used by \ics{DTLformatlist} to separate the last two items in the +list}, + note={\styfmt{datatool-base}\texparserdefnote\ v2.28+}, + seealso={DTLformatlist}, + category={command} +} + +@command{DTLlistformatoxford, + name={\csfmt{DTL\-list\-format\-oxford}}, + user1={}, + description={insert before \ics{DTLlistformatlastsep} if the list +has three or more items}, + note={\styfmt{datatool-base}\texparserdefnote\ v2.28+}, + seealso={DTLformatlist}, + category={command} +} + +@command{DTLandname, + name={\csfmt{DTL\-and\-name}}, + user1={}, + description={used in the definition of \ics{DTLlistformatlastsep}}, + note={\styfmt{datatool-base}\texparserdefnote\ v2.28+}, + seealso={DTLformatlist}, + category={command} +} + +@command{DTLlistelement, + name={\csfmt{DTL\-list\-element}}, + user1={\margm{list}\margm{index}}, + description={does the \meta{index}th element (starting from 1 for + the first element) in the comma-separated \meta{list}}, + note={\styfmt{datatool-base}\texparserdefnote\ v2.31+}, + seealso={DTLfetchlistelement,ifDTLlistskipempty}, + category={command} +} + +@command{DTLfetchlistelement, + name={\csfmt{DTL\-fetch\-list\-element}}, + user1={\margm{list}\margm{index}\margm{cs}}, + description={fetches the \meta{index}th element (starting from 1 for + the first element) in the comma-separated \meta{list} and stores + it in the command given by \meta{cs}}, + note={\styfmt{datatool-base}\texparserdefnote\ v2.31+}, + seealso={DTLlistelement,ifDTLlistskipempty}, + category={command} +} + +@command{ifDTLlistskipempty, + name={\csfmt{if\-DTL\-list\-skip\-empty}}, + description={conditional that determines whether or not commands + like \cs{DTLformatlist} should skip empty elements}, + note={\styfmt{datatool-base}\texparserdefnote\ v2.31+}, + category={command} +} + +@command{DTLnumitemsinlist, + name={\csfmt{DTL\-num\-items\-in\-list}}, + user1={\margm{list}\margm{cs}}, + description={counts the number of elements in the comma-separated + \meta{list} and stores the value in the command given by \meta{cs}}, + note={\styfmt{datatool-base}\texparserdefnote\ v2.31+}, + seealso={DTLformatlist,DTLlistelement,ifDTLlistskipempty}, + category={command} +} + +@command{DTLifinlist, + name={\csfmt{DTL\-if\-in\-list}}, + user1={\margm{element}\margm{list}\margm{true}\margm{false}}, + description={tests if \meta{element} is in the comma-separated \meta{list}}, + note={\styfmt{datatool-base}\texparserdefnote}, + category={command} +} + +@command{si, + name={\csfmt{si}}, + user1={\margm{unit}}, + description={displays the unit with intelligent formatting}, + note={\styfmt{siunitx}\texparserdefnote}, + category={command} +} + +@command{ce, + name={\csfmt{ce}}, + user1={\margm{formula}}, + description={displays the chemical formula}, + note={\styfmt{mhchem}\texparserdefnote}, + category={command} +} + +@command{textweathersymbol, + name={\csfmt{text\-weather\-symbol}}, + user1={\margm{number}}, + description={displays weather symbol identified by \meta{number}}, + note={\styfmt{ifsym}}, + category={command} +} + +@command{toprule, + name={\csfmt{top\-rule}}, + description={horizontal rule for the top of a \envfmt{tabular}-like environment}, + note={\styfmt{booktabs}}, + category={command} +} + +@command{midrule, + name={\csfmt{mid\-rule}}, + description={horizontal rule for divider between header and main + content of a \envfmt{tabular}-like environment}, + note={\styfmt{booktabs}}, + category={command} +} + +@command{bottomrule, + name={\csfmt{bottom\-rule}}, + description={horizontal rule for the bottom of a + \envfmt{tabular}-like environment}, + note={\styfmt{booktabs}}, + category={command} +} + +@command{endhead, + name={\csfmt{end\-head}}, + description={ends the header section}, + note={\styfmt{longtable}}, + category={command} +} + +@command{endfoot, + name={\csfmt{end\-foot}}, + description={ends the footer section}, + note={\styfmt{longtable}}, + category={command} +} + +@command{MakeTextLowercase, + name={\csfmt{MakeTextLowercase}}, + user1={\margm{text}}, + description={converts \meta{text} to lower case}, + note={\styfmt{textcase}\texparserdefnote}, + category={command} +} + +@command{MakeTextUppercase, + name={\csfmt{MakeTextUppercase}}, + user1={\margm{text}}, + description={converts \meta{text} to \idx{uppercase}}, + note={\styfmt{textcase}\texparserdefnote}, + category={command} +} + +@command{NoCaseChange, + name={\csfmt{NoCaseChange}}, + user1={\margm{text}}, + description={prevents \cs{MakeTextUppercase} and + \cs{MakeTextLowercase} from converting \meta{text}}, + note={\styfmt{textcase}\texparserdefnote}, + category={command} +} + +@command{MakeUppercase, + name={\csfmt{MakeUppercase}}, + user1={\margm{text}}, + description={converts \meta{text} to \idx{uppercase}}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{char, + name={\csfmt{char}}, + user1={\meta{number}}, + description={accesses the character identified by \meta{number} +(use \code{\csfmt{char}\idx{doublequotecharhex}\meta{hex}} if the +number is hexadecimal)}, + note={{}\TeX\ primitive\texparserdefnote}, + category={command} +} + +@command{number, + name={\csfmt{number}}, + user1={\meta{value}}, + description={expands the given numerical \meta{value} to + a base~10 integer number stripping any leading + zeros (use \code{\csfmt{char}\idx{doublequotecharhex}\meta{hex}} + if the value is hexadecimal)}, + note={{}\TeX\ primitive\texparserdefnote}, + category={command} +} + +@command{the, + name={\csfmt{the}}, + user1={\meta{register}}, + description={expands \meta{register} to the current value of the + register}, + note={{}\TeX\ primitive\texparserdefnote}, + category={command} +} + +@command{cs.string, + name={\csfmt{string}}, + user1={\meta{token}}, + description={if \meta{token} is a control sequence it expands + to the escape character followed by the control sequence name}, + note={{}\TeX\ primitive\texparserdefnote}, + category={command} +} + +@command{let, + name={\csfmt{let}}, + user1={\meta{token1}\meta{token2}}, + description={assigns \meta{token1} to \meta{token2}}, + note={{}\TeX\ primitive\texparserdefnote}, + category={command} +} + +@command{u, + name={\csfmt{u}}, + user1={\margm{character}}, + description={puts a breve accent over \meta{character}}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{acute, + name={\csfmt{'}}, + user1={\margm{character}}, + description={puts an acute accent over \meta{character}}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{umlaut, + name={\csfmt{"}}, + user1={\margm{character}}, + description={puts an umlaut accent over \meta{character}}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{c, + name={\csfmt{c}}, + user1={\margm{character}}, + description={puts a cedilla accent over \meta{character}}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{AA, + name={\csfmt{AA}}, + description={produces the \idx!{uppercase} A-ring character \AA}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{aa, + name={\csfmt{aa}}, + description={produces the \idx!{lowercase} a-ring character \aa}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{O, + name={\csfmt{O}}, + description={produces the \idx!{uppercase} O-slash character \O}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{o, + name={\csfmt{o}}, + description={produces the \idx!{lowercase} o-slash character \o}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{L, + name={\csfmt{L}}, + description={produces the \idx!{uppercase} L-slash character \L}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{l, + name={\csfmt{l}}, + description={produces the \idx!{lowercase} l-slash character \l}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{ae, + name={\csfmt{ae}}, + description={produces the \idx!{lowercase} \ae-ligature}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{AE, + name={\csfmt{AE}}, + description={produces the \idx!{uppercase} \AE-ligature}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{oe, + name={\csfmt{oe}}, + description={produces the \idx!{lowercase} \oe-ligature}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{OE, + name={\csfmt{OE}}, + description={produces the \idx!{uppercase} \OE-ligature}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{th, + name={\csfmt{th}}, + description={produces the \idx!{lowercase} thorn \th}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{TH, + name={\csfmt{TH}}, + description={produces the \idx!{uppercase} thorn \TH}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{ss, + name={\csfmt{ss}}, + description={produces the \idx!{lowercase} eszett \ss}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{SS, + name={\csfmt{SS}}, + description={produces the \idx!{uppercase} eszett \SS}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{ng, + name={\csfmt{ng}}, + description={produces the \idx!{lowercase} eng \ng}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{NG, + name={\csfmt{NG}}, + description={produces the \idx!{uppercase} eng \NG}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{dh, + name={\csfmt{dh}}, + description={produces the \idx!{lowercase} eth \dh}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{DH, + name={\csfmt{DH}}, + description={produces the \idx!{uppercase} eth \DH}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{dj, + name={\csfmt{dj}}, + description={produces the \idx!{lowercase} d-stroke \dj}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{DJ, + name={\csfmt{DJ}}, + description={produces the \idx!{uppercase} d-stroke \DJ}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{textsuperscript, + name={\csfmt{textsuperscript}}, + user1={\margm{text}}, + description={displays \meta{text} as a superscript}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{textsubscript, + name={\csfmt{textsubscript}}, + user1={\margm{text}}, + description={displays \meta{text} as a subscript}, + note={kernel command\texparserdefnote\ as from 2015/01/01}, + category={command} +} + +@command{MakeLowercase, + name={\csfmt{MakeLowercase}}, + user1={\margm{text}}, + description={converts \meta{text} to lower case}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{textsc, + name={\csfmt{textsc}}, + user1={\margm{text}}, + description={applies small-caps font to \meta{text}}, + note={kernel command}, + category={command} +} + +@command{textsmaller, + name={\csfmt{text\-smaller}}, + user1={\margm{text}}, + description={typesets \meta{text} in a font size that's smaller + than the surrounding text}, + note={\styfmt{relsize}}, + category={command} +} + +@glscommand{glstextup, + name={\csfmt{gls\-text\-up}}, + user1={\margm{text}}, + description={typesets \meta{text} in an upright font (used to +cancel the effect of \cs{textsc} in abbreviation styles that use +\ics{glsabbrvscfont})}, + note={\styfmt{glossaries} v3.09a+}, + topics={abbreviationcommands,formattingcommands}, + category={command} +} + +@command{usepackage, + name={\csfmt{use\-pack\-age}}, + user1={\oargm{options}\margm{name}\oargm{min version}}, + description={loads the package identified by \meta{name}}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{RequirePackage, + name={\csfmt{Require\-Pack\-age}}, + user1={\oargm{options}\margm{name}\oargm{min version}}, + description={loads the package identified by \meta{name} from + within another package}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{ProvidesPackage, + name={\csfmt{Provides\-Pack\-age}}, + user1={\margm{name}\oargm{version}}, + description={identifies a package}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{DeclareOption, + name={\csfmt{Declare\-Opt\-ions}}, + user1={\margm{name}\margm{code}}, + description={declares an option with the given \meta{name}}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{DeclareOption*, + name={\csfmt{Declare\-Opt\-ions*}}, + user1={\margm{code}}, + description={indicates what to do with unknown options}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{ProcessOptions, + name={\csfmt{Process\-Opt\-ions}}, + description={processes supplied options}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{PackageError, + name={\csfmt{Pack\-age\-Err\-or}}, + user1={\margm{name}\margm{code}\margm{help}}, + description={generates an error message for the package identified +by \meta{name}}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{cs.color, + name={\csfmt{color}}, + user1={\oargm{model}\margm{spec}}, + description={switches the current font colour}, + note={\styfmt{color}}, + category={command} +} + +@command{textcolor, + name={\csfmt{textcolor}}, + user1={\oargm{model}\margm{spec}\margm{text}}, + description={typesets \meta{text} in the given colour}, + note={\styfmt{color}}, + category={command} +} + +@examplecommand{cjkname, + name={\csfmt{cjkname}}, + user1={\margm{CJK characters}}, + description={example command}, + category={command} +} + +@command{citation, + name={\csfmt{citation}}, + user1={\margm{label}}, + description={written to the \ext{aux} file on each occurrence of + \cs{cite}}, + note={kernel command}, + category={command} +} + +@command{cite, + name={\csfmt{cite}}, + user1={\margm{label}}, + description={cross-reference a bibliographic citation}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{bibliography, + name={\csfmt{bibliography}}, + user1={\margm{file list}}, + description={display bibliography created by \BibTeX}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{refstepcounter, + name={\csfmt{refstepcounter}}, + user1={\margm{counter name}}, + description={increments the given counter in a manner compatible + with the \cs{label} cross-referencing mechanism}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{label, + name={\csfmt{label}}, + user1={\margm{id}}, + description={creates a label that can be referenced with \ics{ref} +or \ics{pageref}}, + seealso={ref,pageref}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{pageref, + name={\csfmt{pageref}}, + user1={\margm{id}}, + description={cross-reference the page where \cs{label}\margm{id} +occurred}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{ref, + name={\csfmt{ref}}, + user1={\margm{id}}, + description={cross-reference the location where \cs{label}\margm{id} +occurred}, + seealso={label}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{autoref, + name={\csfmt{autoref}}, + user1={\margm{id}}, + description={cross-reference with textual tag inferred from the +associated counter}, + seealso={label}, + note={\styfmt{hyperref}}, + category={command} +} + +@command{par, + name={\csfmt{par}}, + description={paragraph break}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{hyperlink, + name={\csfmt{hyperlink}}, + user1={\margm{target name}\margm{text}}, + description={create a hyperlink to \meta{target name} with the given +\meta{text}}, + note={\styfmt{hyperref}\texparserdefnote}, + category={command} +} + +@command{hypertarget, + name={\csfmt{hypertarget}}, + user1={\margm{target name}\margm{text}}, + description={create a hypertarget with the given \meta{target +name} and the displayed \meta{text}}, + note={\styfmt{hyperref}\texparserdefnote}, + category={command} +} + +@command{texorpdfstring, + name={\csfmt{texorpdfstring}}, + user1={\margm{\TeX\ code}\margm{PDF text}}, + description={does \meta{PDF text} if used in a PDF bookmark, + otherwise does \meta{\TeX\ code}}, + note={\styfmt{hyperref}}, + category={command} +} + +@command{cs.hyperref, + name={\csfmt{hyperref}}, + note={\styfmt{hyperref}}, + category={command} +} + +@command{cs.hyperref.ext, + parent={cs.hyperref}, + name={\csfmt{hyperref}}, + user1={\margm{URL}\margm{category}\margm{name}\margm{text}}, + description={create a hyperlink to an external location with + the anchor formed from \code{\meta{category}.\meta{name}} + and the displayed \meta{text}}, + category={command} +} + +@command{cs.hyperref.int, + parent={cs.hyperref}, + name={\csfmt{hyperref}}, + user1={\oargm{label}\margm{text}}, + description={create an internal hyperlink with + the displayed \meta{text} to the same place + that \code{\cs{ref}\margm{label}} would be linked. + Note that the \meta{label} argument isn't optional. The + square bracket notation disambiguates from the + syntax for the external form of \cs{cs.hyperref.ext}}, + category={command} +} + +@command{@currentlabelname, + name={\csfmt{@current\-label\-name}}, + user1={}, + description={used to store the current title information for the next instance + of \cs{label}}, + note={\styfmt{hyperref}}, + category={command} +} + +@command{@currentHref, + name={\csfmt{@current\-H\-ref}}, + user1={}, + description={used to store the current anchor for the next instance + of \cs{label}}, + note={\styfmt{hyperref}}, + category={command} +} + + +@glscommand{glsrefentry, + name={\csfmt{gls\-ref\-entry}}, + user1={\margm{label}}, + description={when used with \styopt{entrycounter} or + \styopt{subentrycounter} may be used to cross-reference the + entry's number in the glossary list with \cs{ref}}, + topics={crossrefcommands}, + seealso={ref}, + note={\styfmt{glossaries} v3.0+}, + category={command} +} + +@glscommand{glsxtrpageref, + name={\csfmt{gls\-xtr\-page\-ref}}, + user1={\margm{label}}, + description={when used with \styopt{entrycounter} or + \styopt{subentrycounter} may be used to cross-reference the + entry's number in the glossary list with \cs{pageref}}, + seealso={pageref}, + topics={crossrefcommands}, + note={\styfmt{glossaries-extra} v1.11}, + category={command} +} + +@glscommand{glsxtrglossentry, + name={\csfmt{gls\-xtr\-gloss\-entry}}, + user1={\margm{label}}, + description={displays the given entry \field{name} including a hypertarget (if +\sty{hyperref} has been loaded) as the destination for commands like +\cs{gls}}, + topics={linkcommands,fieldrefcommands}, + note={\styfmt{glossaries-extra} v1.21}, + category={command} +} + +@glscommand{glsxtrglossentryother, + name={\csfmt{gls\-xtr\-gloss\-entry\-other}}, + user1={\margm{header}\margm{label}\margm{field}}, + description={like \gls{glsxtrglossentry} but uses the value given +in the supplied internal \meta{field} where \meta{header} is the +code +to use in the header (leave empty for default)}, + topics={linkcommands,fieldrefcommands}, + note={\styfmt{glossaries-extra} v1.22+}, + category={command} +} + +@glscommand{glsshowtarget, + name={\csfmt{gls\-show\-target}}, + user1={\margm{label}}, + description={used to show the target name when the + \styopt[showtargets]{debug} option is on}, + topics={debugging,linkcommands}, + note={\styfmt{glossaries} v4.32+}, + category={command} +} + +@glscommand{showgloparent, + name={\csfmt{show\-glo\-parent}}, + user1={\margm{label}}, + description={interrupts the document build and shows the value of + the \field{parent} field in the transcript}, + topics={debugging,fieldrefcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{showglolevel, + name={\csfmt{show\-glo\-level}}, + user1={\margm{label}}, + description={interrupts the document build and shows the entry's + hierarchical level in the transcript}, + topics={debugging,fieldrefcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{showgloname, + name={\csfmt{show\-glo\-name}}, + user1={\margm{label}}, + description={interrupts the document build and shows the value of + the \field{name} field in the transcript}, + topics={debugging,fieldrefcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{showglosort, + name={\csfmt{show\-glo\-sort}}, + user1={\margm{label}}, + description={interrupts the document build and shows the value of + the \field{sort} field in the transcript}, + topics={debugging,fieldrefcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{showglosymbol, + name={\csfmt{show\-glo\-symbol}}, + user1={\margm{label}}, + description={interrupts the document build and shows the value of + the \field{symbol} field in the transcript}, + topics={debugging,fieldrefcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{showglosymbolplural, + name={\csfmt{show\-glo\-symbol\-plural}}, + user1={\margm{label}}, + description={interrupts the document build and shows the value of + the \field{symbolplural} field in the transcript}, + topics={debugging,fieldrefcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{showgloshort, + name={\csfmt{show\-glo\-short}}, + user1={\margm{label}}, + description={interrupts the document build and shows the value of + the \field{short} field in the transcript}, + topics={debugging,fieldrefcommands,abbreviationcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{showglolong, + name={\csfmt{show\-glo\-long}}, + user1={\margm{label}}, + description={interrupts the document build and shows the value of + the \field{long} field in the transcript}, + topics={debugging,fieldrefcommands,abbreviationcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{showgloloclist, + name={\csfmt{show\-glo\-loc\-list}}, + user1={\margm{label}}, + description={interrupts the document build and shows the value of + the \field{loclist} field in the transcript}, + topics={debugging,fieldrefcommands,loclistcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{showgloflag, + name={\csfmt{show\-glo\-flag}}, + user1={\margm{label}}, + description={interrupts the document build and shows the value of + the \idx{firstuseflag} in the transcript}, + topics={debugging,fieldrefcommands,conditionals}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{showglodesc, + name={\csfmt{show\-glo\-desc}}, + user1={\margm{label}}, + description={interrupts the document build and shows the value of + the \field{description} field in the transcript}, + topics={debugging,fieldrefcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{showglodescplural, + name={\csfmt{show\-glo\-desc\-plural}}, + user1={\margm{label}}, + description={interrupts the document build and shows the value of + the \field{descriptionplural} field in the transcript}, + topics={debugging,fieldrefcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{showglotext, + name={\csfmt{show\-glo\-text}}, + user1={\margm{label}}, + description={interrupts the document build and shows the value of + the \field{text} field in the transcript}, + topics={debugging,fieldrefcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{showgloplural, + name={\csfmt{show\-glo\-plural}}, + user1={\margm{label}}, + description={interrupts the document build and shows the value of + the \field{plural} field in the transcript}, + topics={debugging,fieldrefcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{showglofirst, + name={\csfmt{show\-glo\-first}}, + user1={\margm{label}}, + description={interrupts the document build and shows the value of + the \field{first} field in the transcript}, + topics={debugging,fieldrefcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{showglofirstpl, + name={\csfmt{show\-glo\-firstpl}}, + user1={\margm{label}}, + description={interrupts the document build and shows the value of + the \field{firstplural} field in the transcript}, + topics={debugging,fieldrefcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{showglotype, + name={\csfmt{show\-glo\-type}}, + user1={\margm{label}}, + description={interrupts the document build and shows the value of + the \field{type} field in the transcript}, + topics={debugging,fieldrefcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{showglocounter, + name={\csfmt{show\-glo\-counter}}, + user1={\margm{label}}, + description={interrupts the document build and shows the value of + the \field{counter} field in the transcript}, + topics={debugging,fieldrefcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{showglouseri, + name={\csfmt{show\-glo\-useri}}, + user1={\margm{label}}, + description={interrupts the document build and shows the value of + the \field{user1} field in the transcript}, + topics={debugging,fieldrefcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{showglouserii, + name={\csfmt{show\-glo\-userii}}, + user1={\margm{label}}, + description={interrupts the document build and shows the value of + the \field{user2} field in the transcript}, + topics={debugging,fieldrefcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{showglouseriii, + name={\csfmt{show\-glo\-useriii}}, + user1={\margm{label}}, + description={interrupts the document build and shows the value of + the \field{user3} field in the transcript}, + topics={debugging,fieldrefcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{showglouseriv, + name={\csfmt{show\-glo\-useriv}}, + user1={\margm{label}}, + description={interrupts the document build and shows the value of + the \field{user4} field in the transcript}, + topics={debugging,fieldrefcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{showglouserv, + name={\csfmt{show\-glo\-userv}}, + user1={\margm{label}}, + description={interrupts the document build and shows the value of + the \field{user5} field in the transcript}, + topics={debugging,fieldrefcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{showglouservi, + name={\csfmt{show\-glo\-uservi}}, + user1={\margm{label}}, + description={interrupts the document build and shows the value of + the \field{user6} field in the transcript}, + topics={debugging,fieldrefcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{showglofield, + name={\csfmt{show\-glo\-field}}, + user1={\margm{entry label}\margm{internal field}}, + description={interrupts the document build and shows the value of + the given field in the transcript}, + topics={debugging,fieldrefcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{showgloglossaries, + name={\csfmt{show\-glo\-glossaries}}, + description={interrupts the document build and shows the list + of all non-ignored glossary types in the transcript}, + topics={debugging,glossrefs}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{showglossarytitle, + name={\csfmt{show\-glos\-sary\-title}}, + user1={\margm{type}}, + description={interrupts the document build and shows the title + of the given glossary in the transcript}, + topics={debugging,glossrefs}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{showglossarycounter, + name={\csfmt{show\-glos\-sary\-counter}}, + user1={\margm{type}}, + description={interrupts the document build and shows the default + counter for the given glossary in the transcript}, + topics={debugging,glossrefs}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{showglossaryentries, + name={\csfmt{show\-glos\-sary\-entries}}, + user1={\margm{type}}, + description={interrupts the document build and shows the list of + entry labels for the given glossary in the transcript}, + topics={debugging,glossrefs}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{GlsEntryCounterLabelPrefix, + name={\csfmt{Gls\-Entry\-Counter\-Label\-Prefix}}, + description={used as a prefix in the \cs{label} command + automatically implemented by the \styopt{entrycounter} + and \styopt{subentrycounter} options}, + topics={hooks,crossrefcommands}, + note={\styfmt{glossaries} v4.38+}, + category={command} +} + +@glscommand{GlsXtrStandaloneGlossaryType, + name={\csfmt{Gls\-Xtr\-Stand\-alone\-Glossary\-Type}}, + description={expands to the label for \gls{currentglossary} + within \gls{glsxtrglossentry} and \gls{glsxtrglossentryother}}, + topics={hooks,glossrefs,standalonestyles}, + note={\styfmt{glossaries-extra} v1.31+}, + category={command} +} + +@glscommand{GlsXtrStandaloneSubEntryItem, + name={\csfmt{Gls\-Xtr\-Stand\-alone\-Sub\-Entry\-Item}}, + user1 = {\margm{label}}, + description={used within \gls{glsxtrglossentry} and +\gls{glsxtrglossentryother} to display sub-item labels}, + topics={hooks,glossarystylecommands}, + note={\styfmt{glossaries-extra} v1.31+}, + category={command} +} + +@glscommand{GlsXtrStandaloneEntryName, + name={\csfmt{Gls\-Xtr\-Stand\-alone\-Entry\-Name}}, + user1 = {\margm{label}}, + description={used within \gls{glsxtrglossentry} to + display the name (with a hypertarget, if supported)}, + topics={hooks,glossarystylecommands,fieldrefcommands,linkcommands}, + note={\styfmt{glossaries-extra} v1.37+}, + category={command} +} + +@glscommand{GlsXtrStandaloneEntryOther, + name={\csfmt{Gls\-Xtr\-Stand\-alone\-Entry\-Other}}, + user1 = {\margm{label}\margm{field}}, + description={used within \gls{glsxtrglossentryother} to + display the given field value (with a hypertarget, if supported)}, + topics={hooks,glossarystylecommands,fieldrefcommands,linkcommands}, + note={\styfmt{glossaries-extra} v1.37+}, + category={command} +} + +@glscommand{glsresetentrycounter, + name={\csfmt{gls\-reset\-entry\-counter}}, + description={resets the \counter{glossaryentry} counter if the +\styopt{entrycounter} setting is on}, + topics={hooks,glossarystylecommands,assigncommands,crossrefcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{setentrycounter, + name={\csfmt{set\-entry\-counter}}, + user1={\oargm{prefix}\margm{counter}}, + description={sets up the entry's associated counter and prefix + required by \cs{glshypernumber}}, + topics={glossarystylecommands,assigncommands,loclistcommands,linkcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{setupglossaries, + name={\csfmt{set\-up\-glossaries}}, + user1 = {\margm{\keyvallist}}, + description={applies the base \styfmt{glossaries} options + that are allowed to be changed after the package has loaded}, + topics={assigncommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@glscommand{glossariesextrasetup, + name={\csfmt{glossaries\-extra\-setup}}, + user1 = {\margm{\keyvallist}}, + description={applies the extension \styfmt{glossaries-extra} options + that are allowed to be changed after the package has loaded}, + topics={assigncommands}, + note={\styfmt{glossaries-extra}}, + category={command} +} + +@glscommand{glstreepredesc, + name={\csfmt{gls\-tree\-pre\-desc}}, + user1={\margm{label}}, + description={separator used before the description for the + \glostyle{tree} styles}, + topics={glossarystylecommands,separatorcommands,formattingcommands}, + note={\styfmt{glossary-tree} v4.26+}, + category={command} +} + +@glscommand{glstreenonamedesc, + name={\csfmt{gls\-tree\-no\-name\-desc}}, + user1={\margm{label}}, + description={displays the pre-description separator, the + description and the post-description hook for the + \glostyle{treenoname} styles}, + topics={glossarystylecommands,separatorcommands,formattingcommands}, + note={\styfmt{glossaries-extra-stylemods} v1.31+}, + category={command} +} + +@glscommand{glsfmtshort, + name={\csfmt{gls\-fmt\-short}}, + user1={\margm{label}}, + description={provided for use in section or caption titles, this +displays the short form of the given abbreviation}, + topics={formattingcommands,entryrefcommands,fieldrefcommands,abbreviationcommands,capheadcommands}, + note={\styfmt{glossaries-extra}}, + category={command} +} + +@glscommand{glsfmtlong, + name={\csfmt{gls\-fmt\-long}}, + user1={\margm{label}}, + description={provided for use in section or caption titles, this +displays the long form of the given abbreviation}, + topics={formattingcommands,entryrefcommands,fieldrefcommands,abbreviationcommands,capheadcommands}, + note={\styfmt{glossaries-extra}}, + category={command} +} + +@glscommand{glsfmtfull, + name={\csfmt{gls\-fmt\-full}}, + user1={\margm{label}}, + description={provided for use in section or caption titles, this + displays the full form of the given abbreviation (using the inline + style that matches \cs{glsxtrfull})}, + topics={formattingcommands,entryrefcommands,abbreviationcommands,capheadcommands}, + note={\styfmt{glossaries-extra}}, + category={command} +} + +@glscommand{glsfmtname, + name={\csfmt{gls\-fmt\-name}}, + user1={\margm{label}}, + description={provided for use in section or caption titles, this +displays the given entry's name}, + topics={formattingcommands,entryrefcommands,fieldrefcommands,capheadcommands}, + note={\styfmt{glossaries-extra}}, + category={command} +} + +@glscommand{glsfmtfirst, + name={\csfmt{gls\-fmt\-first}}, + user1={\margm{label}}, + description={provided for use in section or caption titles, this +displays the given entry's \field{first} field}, + topics={formattingcommands,entryrefcommands,fieldrefcommands,capheadcommands}, + note={\styfmt{glossaries-extra}}, + category={command} +} + +@glscommand{glsfmttext, + name={\csfmt{gls\-fmt\-text}}, + user1={\margm{label}}, + description={provided for use in section or caption titles, this +displays the given entry's \field{text} field}, + topics={formattingcommands,entryrefcommands,fieldrefcommands,capheadcommands}, + note={\styfmt{glossaries-extra}}, + category={command} +} + +@glscommand{theHentrycounter, + name={\csfmt{the\-H\-entry\-counter}}, + user1={}, + description={when indexing, this is set to the + \csfmt{theH}\meta{counter} command corresponding to the + current indexing counter (or, if undefined, + \csfmt{the}\meta{counter})}, + topics={glossarystylecommands,linkcommands}, + note={\styfmt{glossaries}}, + category={command} +} + +@command{tableofcontents, + name={\csfmt{table\-of\-contents}}, + description={displays the \glsxtrlong{toc} (by reading in the +\ext{toc} file) and then opens \ext{toc} file to allow the +sectioning commands to write to it}, + note={kernel command\texparserdefnote}, + category={command} +} + +@command{underline, + name={\csfmt{under\-line}}, + user1={\margm{text}}, + description={underlines the given text}, + note={kernel command}, + category={command} +} + +@command{ul, + name={\csfmt{ul}}, + user1={\margm{text}}, + description={underlines the given text}, + note={\styfmt{soul}}, + category={command} +} + +@command{ding, + name={\csfmt{ding}}, + user1={\margm{number}}, + description={displays the symbol associated with the given number}, + note={\styfmt{pifont}\texparserdefnote}, + category={command} +} + +@index{exampleterms, + name = {example terms} +} + +@exampleentry{ex1.duck, + parent={exampleterms}, + name={duck}, + description={a waterbird with webbed feet}, + identifier={animal} +} + +@exampleentry{ex1.goose, + parent={exampleterms}, + name={goose}, + plural={geese}, + description={a large waterbird with a long neck, short legs, + webbed feet and a short broad bill}, + identifier={animal} +} + +@exampleentry{ex2.duck, + parent={exampleterms}, + name={Duck (noun)}, + first={duck (quack, quack)}, + firstplural={ducks (quack, quack)}, + text={duck}, + description={a waterbird with webbed feet}, + identifier={animal} +} + +@exampleentry{ex2.goose, + parent={exampleterms}, + name={Goose (noun, pl.\ geese)}, + first={goose (honk, honk)}, + firstplural={geese (honk, honk)}, + text={goose}, + plural={geese}, + description={a large waterbird with a long neck, short legs, + webbed feet and a short broad bill}, + identifier={animal} +} + +@exampleentry{ex.fleuron, + parent={exampleterms}, + name = {fleuron}, + symbol = {\ding{167}}, + category = {ornament}, + description = {typographic ornament} +} + +@exampleentry{ex.pi, + parent={exampleterms}, + name = {Archimedes' constant}, + symbol = {\ensuremath{\pi}}, + category = {constant}, + description = {ratio of a circle's circumference to its diameter} +} + +@exampleentry{ex.thetai, + parent = {exampleterms}, + name = {theta parameter}, + symbol = {\ensuremath{\theta_i}}, + description = {one of the model parameters} +} + +@exampleabbreviation{ex.tug, + parent={exampleterms}, + category = {longshortem}, + short = {TUG}, + long = {\TeX\ Users Group} +} + +@exampleabbreviation{ex.ascii, + short = {ascii}, + long = {American Standard Code for Information Interchange}, + category={shortsc} +} + +@exampleabbreviation{ex.svm, + parent={exampleterms}, + short = {SVM}, + long = {support vector machine} +} + +@exampleabbreviation{ex.ssl, + parent={exampleterms}, + category = {markwordsexample}, + short = {SSL}, + long = {Secure Sockets Layer} +} + +@exampleabbreviation{ex.xml, + parent={exampleterms}, + category = {taggingexample}, + short = {XML}, + long = {e\itag{x}tensible \itag{m}arkup \itag{l}anguage} +} + +@exampleabbreviation{ex.dante, + parent={exampleterms}, + category = {discardperiodexample}, + short = {DANTE e.V.}, + long = {Deutschsprachige Anwendervereinigung \TeX\ e.V.} +} + +@exampleabbreviation{ex.gp, + parent={exampleterms}, + category = {discardperiodexample}, + short = {G.P.}, + long = {General Practitioner} +} + +@exampleabbreviation{ex2.gp, + parent={exampleterms}, + category = {initialism}, + short = {GP}, + long = {General Practitioner} +} + +@exampleabbreviation{ex.rna, + parent={exampleterms}, + short = {RNA}, + long = {ribonukleins\"aure}, + user1 = {ribonucleic acid}, + category = {abbrvtrans} +} + +@exampleentry{ex.length, + parent={exampleterms}, + name = {length}, + symbol = {\si{\metre}}, + description = {measurement between two points} +} + +@exampleentry{ex.area, + parent={exampleterms}, + name = {area}, + symbol = {\si{\metre\squared}}, + description = {measurement of a surface} +} + +@examplesymbol{ex2.length, + parent={exampleterms}, + description = {length}, + name = {\si{\metre}} +} + +@examplesymbol{ex2.area, + parent={exampleterms}, + description = {area}, + name = {\si{\metre\squared}} +} + +@examplesymbol{ex.deriv, + parent={exampleterms}, + description = {derivative}, + name = {\ensuremath{\derivfn{x}}}, + user1 = {derivfn} +} + +@exampleindex{hom.bow1, + name={bow}, + description={(rhymes with toe)}, + category = {homograph} +} + +@exampleentry{hom.bowknot, + parent={hom.bow1}, + description = {a knot tied with two loops and loose ends}, + category = {homograph} +} + +@exampleentry{hom.bowweapon, + parent={hom.bow1}, + description = {a weapon for shooting arrows, made of curved wood + joined at both ends with taut string}, + category = {homograph} +} + +@exampleindex{hom.bow2, + name={bow}, + description={(rhymes with cow)}, + category = {homograph} +} + +@exampleindex{hom.bowbend, + parent={hom.bow2}, + description={bend head or upper body}, + category = {homograph} +} + +@exampleindex{hom.bowpressure, + parent={hom.bow2}, + description={give in to pressure}, + category = {homograph} +} + +@exampleindex{hom.bow3, + name={bow}, + description={(also bows) the front end of a ship}, + category = {homograph} +} + +@exampleindex{hom.glossary, + name={glossary}, + category = {homograph} +} + +@exampleentry{hom.glossarycol, + parent = {hom.glossary}, + description = {collection of glosses}, + category = {homograph} +} + +@exampleentry{hom.glossarylist, + parent = {hom.glossary}, + description = {list of technical words}, + category = {homograph} +} + +@exampleentry{hier.animal, + name = {animal}, + description = {living organism with a nervous system and sense organs + that can move independently}, + category = {hierarchical} +} + +@exampleentry{hier.bird, + parent = {hier.animal}, + name = {bird}, + description = {warm-blooded egg-laying animal with feathers, wings + and a beak}, + category = {hierarchical} +} + +@exampleentry{hier.duck, + parent = {hier.bird}, + name = {duck}, + description={a waterbird with webbed feet}, + category = {hierarchical} +} + +@exampleentry{hier.goose, + parent = {hier.bird}, + name = {goose}, + description = {a large waterbird with a long neck, short legs, + webbed feet and a short broad bill}, + category = {hierarchical} +} + +@exampleentry{hier.mineral, + name = {mineral}, + description = {natural inorganic substance}, + category = {hierarchical} +} + +@exampleentry{hier.calcite, + parent = {hier.mineral}, + name = {calcite}, + description = {a carbonate mineral}, + category = {hierarchical} +} + +@exampleentry{hier.quartz, + parent = {hier.mineral}, + name = {quartz}, + description = {hard mineral consisting of silica}, + category = {hierarchical} +} + +@exampleentry{hier.amethyst, + parent = {hier.quartz}, + name = {amethyst}, + description = {a purple type of quartz}, + category = {hierarchical} +} + +@exampleentry{hier.citrine, + parent = {hier.quartz}, + name = {citrine}, + description = {a form of quartz with a colour ranging +from pale yellow to brown due to ferric impurities}, + category = {hierarchical} +} + +@exampleentry{ex2.amethyst, + name = {amethyst}, + description = {a purple type of quartz}, + symbol = {\ce{SiO2}}, + user3={A}, + user4={A}, + category = {standalone} +} + +@exampleentry{ex3.goose, + name={goose}, + user3={G}, + user4={G}, + plural={geese}, + description={a large waterbird with a long neck, short legs, + webbed feet and a short broad bill}, + category={standalone} +} + +@exampleentry{ex3.duck, + name={duck}, + user3={D}, + user4={D}, + description={a waterbird with webbed feet}, + category={standalone} +} + +@exampleentry{standalone.pi, + name = {\ensuremath{\pi}}, + description = {Archimedes' constant}, + user3={glssymbols}, + user4={greek}, + category = {standalone} +} + +@exampleentry{standalone.area, + name = {\ensuremath{A}}, + description = {area}, + user3={glssymbols}, + user4={A}, + category = {standalone} +} + +@exampleentry{standalone.radius, + name = {\ensuremath{r}}, + description = {radius}, + user3={glssymbols}, + user4={R}, + category = {standalone} +} + +@exampleentry{standalone.circumference, + name = {\ensuremath{C}}, + user3={glssymbols}, + user4={C}, + description = {circumference}, + category = {standalone} +} + diff --git a/support/bib2gls/src/bib2gls.pod b/support/bib2gls/src/bib2gls.pod new file mode 100644 index 0000000000..c1f41701ad --- /dev/null +++ b/support/bib2gls/src/bib2gls.pod @@ -0,0 +1,304 @@ +=head1 SYNOPSIS + +B<bib2gls> [I<option>]+ I<auxfile> + +=head1 DESCRIPTION + +B<bib2gls> is designed to work with the B<glossaries-extra> LaTeX +package. (The B<record> package option is required.) The application +performs two functions in one: (1) selects entries from .bib files +according to information found in the I<auxfile> (similar to +B<bibtex>); (2) hierarchically sorts entries and collates location +lists (similar to B<makeindex> and B<xindy>). The .aux extension may +be omitted from I<auxfile>. + +=head1 OPTIONS + +=over 4 + +=item B<--help> or B<-h> + +Display help message and exit. + +=item B<--version> or B<-v> + +Display version information and exit. + +=item B<--debug> [I<level>] + +Switch on the debug mode (optionally at the given I<level>, which +should be a non-negative integer). If I<level> is B<0> then the +debug mode is switched off. + +=item B<--no-debug> (or B<--nodebug>) + +Switch off debug mode. (Equivalent to B<--debug> B<0>) + +=item B<--verbose> + +Switch on verbose mode. + +=item B<--no-verbose> (or B<--noverbose>) + +Switch off verbose mode. (Some messages will still be written to +STDOUT.) + +=item B<--silent> + +Only display error messages. All other messages are just written to +the transcript file. + +=item B<--locale> I<lang> (or B<-l> I<lang>) + +Use language resource file for I<lang> (which should be an IETF +locale tag). + +=item B<--log-file> I<file> (or B<-t> <file>) + +Set the transcript file. + +=item B<--dir> I<directory> (or B<-d> <directory>) + +Files are relative to I<directory>. (This doesn't change the current +working directory.) + +=item B<--tex-encoding> I<name> + +Set the character encoding for the output files. This overrides the +setting given in I<auxfile>. + +=item B<--interpret> + +Use the TeX parser library to interpret known (La)TeX commands +(default). + +=item B<--no-interpret> + +Don't try interpreting (La)TeX commands. + +=item B<--break-space> + +Interpret tilde character as a normal space. + +=item B<--no-break-space> + +Interpret tilde as a non-breaking space (default). + +=item B<--cite-as-record> + +Treat B<\citation> as an ignored record. + +=item B<--no-cite-as-record> + +Don't check for instances of B<\citation> in the B<.aux> file (default). + +=item B<--warn-non-bib-fields> + +Warn if internal non-bib fields are found in the .bib file. + +=item B<--no-warn-non-bib-fields> + +Don't warn if internal non-bib fields are found in the .bib file. +The use of these internal fields can cause unexpected results, so +only use this option if you have taken appropriate precautions. + +=item B<--warn-unknown-entry-types> + +Warn if any unknown entry types are found in the .bib file. + +=item B<--no-warn-unknown-entry-types> + +Don't warn if any unknown entry types are found in the .bib file. + +=item B<--merge-wrglossary-records> + +Merge an entry's B<wrglossary> records for the same page locations. +(For use with the B<indexcounter> package option.) + +=item B<--no-merge-wrglossary-records> + +Don't merge an entry's B<wrglossary> records. + +=item B<--merge-nameref-on> I<rule> + +Rule for merging locations created with the record=nameref package option +(requires glossaries-extra.sty version 1.37+). The I<rule> may be +one of: B<hcounter>, B<href>, B<title> or B<location>. + +=item B<--force-cross-resource-refs> or B<-x> + +Force cross-resource referencing mode on. + +=item B<--no-force-cross-resource-refs> + +Don't force cross-resource referencing mode on (default). + +=item B<--support-unicode-script> + +Text superscript (\textsuperscript) or subscripts (\textsubscript) +will use Unicode superscript/subscript characters if available. +For example, \textsuperscript{2} will be converted to U+00B2 +(superscript two). + +=item B<--no-support-unicode-script> + +Text superscript (\textsuperscript) or subscripts (\textsubscript) +won't be converted to Unicode superscript/subscript characters. +For example, \textsuperscript{2} will be converted to <sup>2</sup> +and the markup will be stripped leaving just the character 2. + +=item B<--packages> I<list> (or B<-p> I<list>) + +Instruct the TeX parser library to pretend the packages listed +in I<list> have been used by the document. Note that there's only a +limited number of packages supported by the TeX parser library. +This option has a cumulative action so B<--packages wasysym,pifont> +is the same as B<--packages wasysym --packages pifont>. + +You can find out the list of supported packages with +B<--list-known-packages>. + +=item B<--custom-packages> I<list> + +Instruct the TeX parser library to attempt to parse the +packages listed in I<list>. This is intended for simple custom +packages that don't contain complex code. + +=item B<--ignore-packages> I<list> (or B<-k> I<list>) + +Don't parse the log file for the packages listed in I<list>. Note +that B<--packages> overrides this option, so if the same package is +listed in both B<--ignore-packages> and B<--packages> then the +interpreter will check if it's supported. This option has a +cumulative action. Only known packages may be included in +I<list>. + +=item B<--list-known-packages> + +Lists all the packages that have are known to the TeX parser +library and then exits (with exit code 0). Any of the listed +packages may be used in B<--packages> or B<--ignore-packages>. + +=item B<--mfirstuc-protection> I<fields>|B<all> (or B<-u> I<fields>|B<all>) + +Insert an empty group if fields start with certain problematic +commands to protect against case-changing commands like \Gls. + +The default is to do this for all fields. To do this for only a +subset of fields, set I<fields> to a comma-separated list of fields +(e.g. B<name,short,long>). The keyword B<all> indicates all fields. + +=item B<--no-mfirstuc-protection> + +Switch off the auto-insertion of an empty group for all fields. + +=item B<--mfirstuc-math-protection> + +Switch on the auto-insertion of an empty group for math-shift ($). +This option will be overridden by B<--no-mfirstuc-protection>. + +=item B<--no-mfirstuc-math-protection> + +Switch off the auto-insertion of an empty group for math-shift ($). + +=item B<--nested-link-check> I<list>|B<none> + +Check each field listed in I<list> for potentially problematic +nested link text. (Default list: name, text, plural, first, +firstplural, short, shortplural, long, longplural, symbol). + +If B<none>, disable check. + +=item B<--no-nested-link-check> + +Don't check for potentially problematic nested link text. +(Equivalent to B<--nested-link-check> B<none>) + +=item B<--shortcuts> I<option> + +Check for the shortcut commands when searching for dependencies. +Permitted values of I<option>: B<acronyms> (or B<acro>), B<ac>, +B<abbreviations> (or B<abbr>), B<all> (or B<true>), B<none> (or +B<false>). This overrides the setting given in I<auxfile>. + +=item B<--map-format> I<key>B<:>I<value>[B<,>I<key>B<:>I<value>]* (or +B<-m> I<key>B<:>I<value>[B<,>I<key>B<:>I<value>]*) + +Set location format mappings. + +=item B<--group> or B<-g> + +Add 'group' field to entries. + +=item B<--no-group> + +Don't add 'group' field to entries (default). + +=item B<--record-count> or B<-c> + +Add record count fields to entries. + +=item B<--no-record-count> + +Don't add record count field to entries (default). +This option automatically implements B<--no-record-count-unit>. + +=item B<--record-count-unit> or B<-n> + +Add unit record count fields to entries. +This option automatically implements B<--record-count>. + +=item B<--no-record-count-unit> + +Don't add unit record count field to entries (default). + +=item B<--trim-fields> + +Trim leading and trailing spaces from fields. + +=item B<--no-trim-fields> + +Don't trim leading and trailing spaces from fields (default). + +=item B<--expand-fields> + +Don't write B<\glsnoexpandfields> to the B<.glstex> file. + +=item B<--no-expand-fields> + +Write B<\glsnoexpandfields> to the B<.glstex> file (default). + +=back + +=head1 REQUIRES + +Java 7 or later and a TeX distribution. + +=head1 LICENSE + +License GPLv3+: GNU GPL version 3 or later +<http://gnu.org/licenses/gpl.html> +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. + +=head1 RECOMMENDED READING + +The bib2gls manual: + + texdoc bib2gls + +The glossaries-extra manual: + + texdoc glossaries-extra + +The glossaries manual: + + texdoc glossaries + +=head1 AUTHOR + +Nicola L. C. Talbot, +L<http://www.dickimaw-books.com/> + +=cut + diff --git a/support/bib2gls/src/bib2gls.tex b/support/bib2gls/src/bib2gls.tex new file mode 100644 index 0000000000..f7ba9c27ef --- /dev/null +++ b/support/bib2gls/src/bib2gls.tex @@ -0,0 +1,22549 @@ +% arara: lualatex +% arara: bib2gls: {group: on} if missing("glstex") || changed("bib") || found("log", "Warning: Glossary entry") +% arara: bibtex +% arara: lualatex if changed("glstex") || missing("toc") +% arara: bib2gls: {group: on, packages: [mfirstuc-english]} +% arara: lualatex +% arara: lualatex if found ("log", "Rerun") +\documentclass[titlepage=false,index=totoc,bibliography=totoc, + fontsize=12pt,captions=tableheading]{scrreprt} + +\usepackage[autooneside=false]{scrlayer-scrpage} +\usepackage{pifont} + +% Need support for extended characters +% and need a mono font that supports hyphenation +\usepackage[no-math]{fontspec} +\setmainfont{Linux Libertine O} + +\newfontface\cyrillicmono{FreeMono}[Scale=MatchLowercase] +\newcommand{\textcyrillicmono}[1]{{\cyrillicmono #1}} + +\newfontface\greekmono{FreeMono}[Scale=MatchLowercase] +\newfontface\freeserif{FreeSerif} +\newcommand{\devone}{{\freeserif\char"0967}} +\newcommand{\devtwo}{{\freeserif\char"0968}} +\newcommand{\devsix}{{\freeserif\char"096C}} +\newcommand{\insularG}{{\freeserif\char"A77D}} +\newcommand{\insularg}{{\freeserif\char"1D79}} +\newcommand{\longs}{\char"017F} +\newcommand{\Wynn}{\char"01F7} +\newcommand{\wynn}{\char"01BF} + +\usepackage[x11names]{xcolor} +\usepackage{alltt} +\usepackage{array} +\usepackage{upquote} +\usepackage{etoolbox} + +\usepackage{hologo} +\usepackage{amsmath} +\usepackage{accents} +\usepackage{tikz} +\usepackage{tcolorbox} +\usepackage{datetime2} +\usepackage{listings} +\usepackage[hidelinks]{hyperref} +\usepackage{cleveref} +\usepackage[% v1.21+ + record,% use bib2gls + index,% create index glossary + entrycounter,% enable entry counting + subentrycounter,% enable entry counting + %debug=showtargets,% debugging information + stylemods={mcols,bookindex},% adjust predefined styles and load glossary-mcols.sty and glossary-bookindex.sty + style=bookindex + ] + {glossaries-extra} + +\lstset{language={[LaTeX]TeX},upquote,basicstyle={\ttfamily\small}, + commentstyle={\color{gray}}} + +\renewcommand*{\glsshowtarget}[1]{\texttt{\small [#1]}} + +\glsxtrprovidestoragekey{note}{}{} +\glsxtrprovidestoragekey{package}{}{} +\glsxtrprovidestoragekey{nametitle}{}{} + +\providecommand{\omicron}{o} + +% put break before dash to avoid confusion with a hyphen +\newcommand{\dhyphen}{% + \texorpdfstring + {\discretionary{}{}{}\texttt{-}}% + {-}% +} + +% Redefine \- (used in entry names) so that hyphenation in command names, +% switches options etc uses a serif hyphen to reduce confusion with an +% actual hyphen in the code. +\renewrobustcmd{\-}{% + \discretionary + {{\rmfamily\char\ifnum\hyphenchar\font<0 + \defaulthyphenchar\else\hyphenchar\font\fi + }}% + {}{}% +} + +\renewcommand{\glsentrycounterlabel}{} +\renewcommand{\glssubentrycounterlabel}{} +\renewcommand\glstreeitem{\par\hangindent10pt} +\renewcommand\glstreesubitem{\par\hangindent30pt\hspace*{15pt}} + +\newcommand{\bibglsseealsosep}{\glstreesubitem} + +\renewcommand*{\glsseesep}{, \glstreesubitem\qquad} +\renewcommand*{\glsseelastsep}{\glstreesubitem\qquad\andname\space} + +\newcommand{\glsxtrpostnameabbreviation}{% + \space(\glsentrylong{\glscurrententrylabel})% +} + +\newcommand{\glsxtrpostnameenvironment}{\space environment} +\newcommand{\glsxtrpostnamecounter}{\space counter} + +\newcommand*{\csfmtfont}[1]{\texttt{#1}} +\newcommand*{\csfmtcolourfont}[1]{\texttt{\textcolor{cs}{#1}}} + +\newcommand*{\csfmt}[1]{% + \texorpdfstring + {\csfmtfont{\char`\\ #1}}% + {\string\\#1}% +} + +\newcommand{\texparserdefprefix}{} +\newcommand{\texparserdefnotetarget}{% + \raisebox{2ex}{\hypertarget{\texparserdefprefix texparserdef}{}}% + \textsuperscript{*}Indicates command is + recognised by \bibgls's interpreter although it may have + a slightly different implementation. +} +\newcommand{\texparserdefnote}{\hyperlink{\texparserdefprefix texparserdef}{*}} + +\setabbreviationstyle{long-short-sc} +\setabbreviationstyle[common]{short-sc-nolong} + +\glsxtrprovidestoragekey{unsortedprogeny}{}{} + +\GlsXtrLoadResources[ + entry-type-aliases={ + bibglscommand=dualindexentry, + mainglscommand=spawndualindexentry, + glscommand=spawnentry, + abbrvstylecommand=spawnentry, + glostylecommand=spawnentry, + resourceoption=dualindexentry, + packageoption=dualindexentry, + field=dualindexentry, + entrytype=dualindexentry, + switch=dualindexentry, + samplefile=dualindexentry, + examplecommand=dualindexentry, + examplesymbol=symbol, + exampleabbreviation=abbreviation, + exampleentry=entry + }, + field-aliases={topics=adoptparents}, + replicate-fields={name=nametitle,progeny=unsortedprogeny}, + field-case-change={nametitle=title}, + interpret-fields={nametitle}, + no-case-change-cs={fieldfmt,abbrstylefmt,glostylefmt}, + short-case-change={lc}, + dual-short-case-change={lc}, + unknown-entry-alias={index}, + save-original-entrytype, + label-prefix={idx.}, + save-loclist=false, + sort={letternumber-nocase}, + sort-replace={{\glshex2423}{ },{\string\\([a-zA-Z])}{\glscapturedgroup1}}, + type={index}, + dual-field={dualid}, + match-action={add}, + match-op={or}, + match={ + {category}={.*field}, + {original entrytype}={.*(gls|style)command}, + {original entrytype}={.*option}, + {original entrytype}={abbreviationstyle}, + {original entrytype}={glossarystyle}, + }, + dual-prefix={}, + dual-type={main}, + combine-dual-locations={primary}, + selection={recorded and deps and see}, + symbol-sort-fallback={name}, + sort-label-list={progeny:letter-nocase:glsxtrentryparentname}, + strip-missing-parents, + save-child-count +] + +\glsxtraddlabelprefix{} +\glsxtraddlabelprefix{idx.} + +\DTMsavetimestamp{creation}{2017-01-20T15:39:00Z} + +\IfFileExists{../java/Bib2Gls.java} +{ + \DTMsavefilemoddate{moddate}{../java/Bib2Gls.java} +} +{ + \DTMsavenow{moddate} +} + +\newif\ifmainmatter + +% ignore locations outside of main matter +\GlsXtrSetDefaultNumberFormat{glsignore} + +\GlsXtrSetAltModifier{!}{format=glsignore} + +\newcommand{\frontmatter}{% + \clearpage\pagenumbering{roman}% + \pagestyle{scrheadings}% + \automark[section]{chapter}% + \mainmatterfalse +} +\newcommand{\mainmatter}{% + \clearpage\pagenumbering{arabic}% + \GlsXtrSetDefaultNumberFormat{glsnumberformat}% + \mainmattertrue +} + +\newcommand{\rightleftmark}[2]{\ifstrequal{#1}{#2}{#1}{#1: #2}} +\makeatletter +\newcommand{\setsecdepth}{\@ifstar\s@setsecdepth\@setsecdepth} +\newcommand{\s@setsecdepth}[1]{% + \setcounter{secnumdepth}{#1}% + \automark[section]{chapter}% + \let\@rightmark\rightleftmark +} +\newcommand{\@setsecdepth}[1]{% + \setcounter{secnumdepth}{#1}% + \ifnum#1 > 0 + \automark[section]{chapter}% + \else + \automark{chapter}% + \fi + \let\@rightmark\@secondoftwo +} +\makeatother + +\newtcolorbox{important}{colback=red!5!white,colframe=red} + +\newcommand{\bibgls}{\appfmt{bib2gls}} + +\newcommand*{\BibTeX}{\hologo{BibTeX}} +\newcommand*{\eTeX}{\hologo{eTeX}} +\newcommand*{\XeLaTeX}{\hologo{XeLaTeX}} +\newcommand*{\LuaLaTeX}{\hologo{LuaLaTeX}} +\newcommand*{\pdfLaTeX}{\hologo{pdfLaTeX}} + +\newcommand{\langxml}{\hyperref[sec:lang.xml]{language resource file}} + +\newcommand{\hex}[1]{0x#1} +\newcommand{\hexsb}[1]{\textsubscript{\scriptsize\rmfamily#1}} +\newcommand{\subfigfmt}[1]{(\emph{#1})} + +\newcommand{\qt}[1]{``#1''} + +\newcommand{\qtt}[1]{\qt{\,\texttt{#1}\,}} + +\newcommand{\qtdelim}[1]{\idx{doublequotechardelim}#1\idx{doublequotechardelim}} + +\newcommand{\ifnumhex}[1]{\cs{ifnum}\idx{doublequotecharhex}#1} + +\newcommand{\charhex}[1]{\cs{char}\idx{doublequotecharhex}#1} +\newcommand{\icharhex}[1]{\ics{char}\idx[format=glsnumberformat,noindex=false]{doublequotecharhex}#1} + +\newcommand{\era}[1]{\texorpdfstring{\textsc{\MakeLowercase{#1}}}{#1}} + +\newcommand{\dequals}{% + \texorpdfstring + {\discretionary{}{}{}\texttt{=}\discretionary{}{}{}}% + {=}% +} + +\newcommand{\dcomma}{% + \texorpdfstring + {\texttt{,}\discretionary{}{}{}}% + {,}% +} + +\newcommand{\dcolon}{% + \texorpdfstring + {\texttt{:}\discretionary{}{}{}}% + {:}% +} + +\pdfstringdefDisableCommands{% + \def\dhyphen{-}% + \def\dcolon{:}% + \def\dcomma{,}% + \def\dequals{,}% + \let\-\empty +} + +% Provide commands that work like \gls[#1]{idx.#2}[#3] + +\glsxtrnewglslike{idx.}{\idx}{\idxpl}{\Idx}{\Idxpl} +\newcommand{\idxlink}[3][]{\glslink[#1]{idx.#2}{#3}} + +\newcommand{\stringu}{\idx{cs.string}\idx{u}} + +\newcommand*{\filefmt}[1]{\texorpdfstring{\texttt{#1}}{#1}} +\newcommand*{\metafilefmt}[3]{% + \filefmt{#1}\discretionary{}{}{}\meta{#2}\discretionary{}{}{}\filefmt{#3}% +} + +\newcommand*{\primaryresourcefmt}{% + \texorpdfstring + {\texttt{\char`\\ jobname.glstex}}% + {\string\\jobname.glstex}% +} + +\newcommand*{\suppresourcefmt}[1]{% + \texorpdfstring + {\texttt{\char`\\ jobname-#1.glstex}}% + {\string\\jobname-#1.glstex}% +} + +\definecolor{field}{named}{DarkSlateGray4} +\definecolor{cs}{named}{DarkSeaGreen4} +\definecolor{styopt}{named}{DarkOrchid4} +\definecolor{entry}{named}{SteelBlue4} +\definecolor{comment}{named}{gray} +\definecolor{attribute}{named}{Purple4} +\definecolor{style}{named}{Blue4} + +\newcommand{\extstyopt}{\textsuperscript{\textdagger}} + +\newcommand*{\appfmt}[1]{\texorpdfstring{\texttt{#1}}{#1}} +\newcommand*{\styfmt}[1]{\texorpdfstring{\textsf{#1}}{#1}} +\newcommand*{\envfmt}[1]{\texorpdfstring{\textsf{#1}}{#1}} +\newcommand*{\optfmt}[1]{\texorpdfstring{\texttt{#1}}{#1}} +\newcommand*{\csoptfmt}[1]{\texorpdfstring{\textcolor{cs}{\optfmt{#1}}}{#1}} +\newcommand*{\styoptfmt}[1]{\texorpdfstring{\textcolor{styopt}{\optfmt{#1}}}{#1}} +\newcommand*{\fieldfmt}[1]{\texorpdfstring{\texttt{\color{field}#1}}{#1}} +\newcommand*{\entryfmt}[1]{\texorpdfstring{\texttt{\color{entry}#1}}{#1}} +\newcommand*{\atentryfmt}[1]{\entryfmt{@#1}} +\newcommand*{\abbrstylefmt}[1]{\texorpdfstring{\textsf{#1}}{#1}} +\newcommand*{\glostylefmt}[1]{\texorpdfstring{\textsf{#1}}{#1}} +\newcommand*{\catattrfmt}[1]{\texorpdfstring{\textsf{#1}}{#1}} +\newcommand*{\counterfmt}[1]{\texorpdfstring{\textsf{#1}}{#1}} +\newcommand*{\idprefixfmt}[1]{% + \texorpdfstring{\texttt{#1\spacefactor999 .}}{#1.}} +\newcommand*{\xmltagfmt}[1]{\texorpdfstring{\texttt{#1}}{#1}} + +\newcommand*{\argor}{\texorpdfstring{\protect\textbar}{|}} + +\newrobustcmd*{\texmeta}[1]{{\normalfont\normalcolor$\langle$\emph{#1}$\rangle$}} + +\newcommand*{\meta}[1]{% + \texorpdfstring{\ifmmode\text{\texmeta{#1}}\else\texmeta{#1}\fi}{#1}% +} + +\newcommand*{\oarg}[1]{\discretionary{}{}{}[#1]} +\newcommand*{\oargm}[1]{\oarg{\meta{#1}}} + +\newcommand*{\marg}[1]{\texorpdfstring + {\discretionary{}{}{}\char`\{#1\char`\} }% + {\{#1\}}% +} + +\newcommand*{\margm}[1]{\marg{\meta{#1}}} + +\newcommand*{\file}[1]{% + \texorpdfstring + {\idx{file.#1}}% + {#1}% +} + +\newcommand{\texmfcnffmt}[1]{\texttt{#1}} + +\glsxtrnewgls{idx.texmfcnf.}{\texmfcnf} + +\newcommand*{\extfmt}[1]{\filefmt{.#1}}% + +\glsxtrnewgls[format=glsignore]{idx.ext.}{\ext} + +\newcommand*{\iext}[1]{% + \glsxtrtitleorpdforheading{\idx{ext.#1}}{.#1}{\extfmt{#1}}% +} + +\glsxtrnewgls[format=glsignore]{idx.}{\sty} + +\newcommand*{\isty}[1]{% + \texorpdfstring{\idx[noindex=false]{#1}}{#1}% +} + +\newcommand*{\env}[1]{% + \texorpdfstring{\idx{env.#1}}{#1}% +} + +\newcommand{\glsxtrpostdescenvironment}{environment} + +\newcommand*{\abbrstyle}[1]{% + \texorpdfstring{\idx{abbrstyle.#1}}{#1}% +} + +\newcommand*{\topicabbrstyle}[1]{% + %\texorpdfstring{\idx[prefix=topic.]{abbrstyle.#1}}{#1}% + \texorpdfstring{\idx{abbrstyle.#1}}{#1}% +} + +\newcommand*{\glostyle}[1]{% + \texorpdfstring{\idx{glostyle.#1}}{#1}% +} + +\newcommand*{\topicglostyle}[1]{% + %\texorpdfstring{\idx[prefix=topic.]{glostyle.#1}}{#1}% + \texorpdfstring{\idx{glostyle.#1}}{#1}% +} + +\newcommand*{\iglostyle}[1]{% + \texorpdfstring{\idx[noindex=false]{glostyle.#1}}{#1}% +} + +\newcommand*{\catattr}[1]{% + \texorpdfstring{\idx{catattr.#1}}{#1}% +} + +\newcommand*{\counter}[1]{% + \texorpdfstring{\idx{ctr.#1}}{#1}% +} + +\newcommand{\glsxtrpostdesccounter}{counter} + +\newcommand*{\idprefix}[1]{% + \texorpdfstring{\idx{idprefix.#1}}{#1}% +} + + +\newcommand*{\styopt}[2][]{% + \texorpdfstring% + {% + \gls{styopt.#2}\styoptfmt{\ifblank{#1}{}{\dequals\marg{#1}}}% + }% + {#2\ifblank{#1}{}{=#1}}% +} + +\newcommand*{\istyopt}[2][]{% + \texorpdfstring% + {% + \gls[noindex=false]{styopt.#2}\styoptfmt{\ifblank{#1}{}{\dequals\marg{#1}}}% + }% + {#2\ifblank{#1}{}{=#1}}% +} + +\newcommand*{\styoptref}[1]{\gls[format=glsignore]{styopt.#1}} + +\newcommand*{\keyvallist}{% + \texorpdfstring + {key\dequals value list}% + {key=value list}% +} + +\newcommand{\cssection}[2][\subsection]{% + #1{\texorpdfstring{\glsxtrglossentry{#2}}{\string\\#2}}% +} + +\newcommand{\format}[1]{% + \gls{#1}\glsentryuseri{#1}% +} + +\newcommand{\formatdef}[1]{% + \begin{definition}% + \gls[hyper=false]{#1}\glsentryuseri{#1}% + \end{definition}\ignorespaces +} + +\newcommand{\nosecformatdef}[1]{% + \begin{definition} + \renewcommand{\GlsXtrStandaloneEntryName}[1]{\glstarget{##1}{\strut}\cs{##1}}% + \glsadd{#1}\glsxtrglossentry{#1}% + \glsentryuseri{#1}% + \end{definition}\ignorespaces +} + +\newcommand{\nosecdef}[1]{% + \begin{flushleft}\ttfamily + \renewcommand{\GlsXtrStandaloneEntryName}[1]{\glstarget{##1}{\strut}\cs{##1}}% + \glsadd{#1}\glsxtrglossentry{#1}% + \glsentryuseri{#1}% + \end{flushleft}\ignorespaces +} + +\newcommand{\inlinedef}[1]{% + \code + {% + \glsadd{#1}\glsxtrglossentry{#1}% + \glsentryuseri{#1}% + }% +} + +\newcommand*{\csref}{\gls} + +\newcommand*{\cs}[1]{% + \glsdoifexists{idx.#1}% + {\glsdohyperlink{\glolinkprefix cs.idx.#1}{\glsentryname{idx.#1}}}% +} + +\glsxtridentifyglslike{idx.}{\cs} + +\newcommand*{\ics}[2][]{\glsadd[#1]{idx.#2}\cs{#2}} + +\newcommand*{\csdisp}[2]{% + \texorpdfstring + {\glsdohyperlink{\glolinkprefix cs.idx.#1}{\csfmt{#2}}}% + {\string\\#2}% +} + +\newcommand*{\icsdisp}[3][]{% + \glsadd[#1]{idx.#2}\glsdohyperlink{\glolinkprefix cs.idx.#2}{\csfmt{#3}}% +} + +\newcommand*{\encapdisp}[2]{% + \texorpdfstring + {\glsdohyperlink{\glolinkprefix cs.idx.#1}{\code{#2}}}% + {#2}% +} + +\glsxtridentifyglslike{idx.}{\ics} + +\newcommand*{\icswithargs}[2][]{\glsadd[#1]{idx.#2}\cs{#2}\glsentryuseri{#2}} + +\newcommand*{\postdeschook}[1]{% + \glsdohyperlink{\glolinkprefix cs.idx.glsxtrpostdesccategory}{\csfmt{glsxtrpostdesc#1}}} +\newcommand*{\postnamehook}[1]{% + \glsdohyperlink{\glolinkprefix cs.idx.glsxtrpostnamecategory}{\csfmt{glsxtrpostname#1}}} +\newcommand*{\postlinkhook}[1]{% + \glsdohyperlink{\glolinkprefix cs.idx.glsxtrpostlinkcategory}{\csfmt{glsxtrpostlink#1}}} + +\newcommand*{\encap}[2][]{\glsadd[#1]{idx.#2}% + {% + \let\csfmt\code + \glsdohyperlink{\glolinkprefix cs.idx.#2}{\glsentryname{idx.#2}}% + }% +} + +\newcommand{\optsection}[2][\subsection]{% + \glsxtrifhasfield*{useri}{opt.#2}% + {% + #1[\texorpdfstring + {\glsxtrheadname{opt.#2}\csoptfmt{=\glscurrentfieldvalue}}% + {\glsentryname{opt.#2}=\glscurrentfieldvalue}] + {\glsadd{opt.#2}\glsxtrglossentry{opt.#2}% + \csoptfmt{=\glscurrentfieldvalue}% + }% + }% + {% + #1[\texorpdfstring{\glsxtrheadname{opt.#2}}{\glsentryname{opt.#2}}] + {\glsadd{opt.#2}\glsxtrglossentry{opt.#2}}% + }% +} + +\glsxtrnewgls{file.}{\exfile} + +\newcommand{\filesection}[2][\section]{% + #1[\texorpdfstring{\glsxtrheadname{file.#2}}{\glsentryname{file.#2}}] + {\glsadd{file.#2}\glsxtrglossentry{file.#2}}% +} + +\newcommand*{\csopt}[2][]{\gencsopt{#1}{opt}{#2}}% +\newcommand*{\glsopt}[2][]{\gencsopt{#1}{idx.gls}{#2}}% +\newcommand*{\glsaddopt}[2][]{\gencsopt{#1}{idx.glsadd}{#2}}% +\newcommand*{\printglossopt}[2][]{\gencsopt{#1}{idx.printgloss}{#2}}% +\newcommand*{\iprintglossopt}[2][]{\glsadd{idx.printgloss.#2}\gencsopt{#1}{idx.printgloss}{#2}}% + +\newcommand*{\gencsopt}[3]{% + \texorpdfstring% + {% + \gls{#2.#3}% + \csoptfmt{\ifblank{#1}{}{\dequals\marg{#1}}}% + }% + {#3\ifblank{#1}{}{=#1}}% +} + +\newcommand*{\field}[1]{% + \texorpdfstring + {\gls{field.#1}}% + {#1}% +} + +\newcommand*{\fielddisp}[2]{% + \texorpdfstring + {\glsdisp{field.#1}{\fieldfmt{#2}}}% + {#2}% +} + +\newcommand*{\fielddef}[1]{% + \glsadd{field.#1}% + \glsxtrglossentry{field.#1}{}% +} + +\newcommand*{\fieldref}[1]{\gls[format=glsignore]{field.#1}} + +\newglossarystyle{fieldstyle}{% + \renewenvironment{theglossary}% + {% + \setlength{\glsdescwidth}{\dimexpr\linewidth-\maxnamewidth-4\tabcolsep}% + \begin{longtable}{l>{\raggedright}p{\glsdescwidth}}% + }% + {\end{longtable}}% + \renewcommand*{\glossaryheader}{% + \noalign{\xdef\dofieldtabcaption{% + \noexpand\caption\expandonce\fieldtablelotcaption + {\expandonce\fieldtablecaption}}}% + \dofieldtabcaption + \fieldtablecaptionlabel + \fieldtablepostcaption\tabularnewline + \bfseries Field & \bfseries Description\tabularnewline + \endfirsthead + \caption*{\fieldtablecaption\ (Continued)}\tabularnewline + \bfseries Field & \bfseries Description\tabularnewline + \endhead + }% + \renewcommand*{\glsgroupheading}[1]{}% + \renewcommand{\glossentry}[2]{% + \glsadd{##1}% + \glsentryitem{##1}\glstarget{##1}{\glossentryname{##1}} & + \glossentrydesc{##1}\tabularnewline + }% + \renewcommand{\subglossentry}[3]{\glossentry{##2}{##3}}% + \renewcommand*{\glsgroupskip}{}% +} + +\newcommand*{\fieldhook}[1]{% + \edef\currentcategory{\glscategory{#1}}% + \glsxtriflabelinlist{\currentcategory}{\fieldcategories}% + {% + \settowidth{\dimen0}{\glsentryname{#1}}% + \ifdim\dimen0>\maxnamewidth \setlength{\maxnamewidth}{\dimen0}\fi + }% + {\printunsrtglossaryskipentry}% +} + +\newlength\maxnamewidth + +%\printfields[postcaption]{category list}[lot caption]{caption}{label} +\newcommand*{\printfields}[2][]{% + \ifstrempty{#1}% + {% + \def\fieldtablepostcaption{}% + }% + {% + \def\fieldtablepostcaption{% + \tabularnewline + \multicolumn{2}{p{\linewidth}}{#1}% + \tabularnewline + }% + }% + \def\fieldcategories{#2}% + \innerprintfields +} + +\newcommand*{\innerprintfields}[3][]{% + \printunsrtglossary*[style=fieldstyle]{% + \renewcommand*\glossarysection[2][]{}% + \ifstrempty{#1}% + {% + \def\fieldtablelotcaption{}% + }% + {% + \def\fieldtablelotcaption{[#1]}% + }% + \def\fieldtablecaption{#2}% + \def\fieldtablecaptionlabel{\label{#3}}% + \setlength{\maxnamewidth}{0pt}% + \let\printunsrtglossaryentryprocesshook\fieldhook + }% +} + +\renewcommand*{\glsxtrbookindexname}[1]{% + \glsxtrifhasfield{dualid}{#1}% + {% + \glshyperlink[\glossentryname{#1}]{\glscurrentfieldvalue}% + } + {% + \GlsXtrIfFieldEqStr{category}{#1}{command}% + {\glsdohyperlink{\glolinkprefix cs.#1}{\glossentryname{#1}}}% + {\glossentryname{#1}}% + }% +} + +\newcommand{\summarysubheaderfont}[1]{\textbf{\sffamily #1}} + +\newcommand{\summaryoptionhandler}[1]{% + \par\smallskip\nopagebreak + \par\noindent\hspace{1em}% + \code{\gls{#1}\glsxtrifhasfield{useri}{#1}{=\glscurrentfieldvalue}{}}% + \glsxtrifhasfield{note}{#1}% + {\nolinebreak\hfill\mbox{\footnotesize\glscurrentfieldvalue}}% + {}% + \nopagebreak\par\hangindent2em\noindent\hspace{2em}\Glossentrydesc{#1}% +} + +\newrobustcmd{\donote}[1]{% + \glsxtrifhasfield{note}{#1}% + {\nolinebreak\hfill\mbox{\normalfont\footnotesize\glscurrentfieldvalue}}% + {}% +} + +\newglossarystyle{commandsummary}% +{% + \setglossarystyle{index}% + \renewcommand*{\glossaryheader}{\raggedright}% + \renewcommand*{\glsgroupheading}[1]{% + \glsxtrgetgrouptitle{##1}{\thisgrptitle}% + \glsxtrbookindexbookmark{\thisgrptitle}{summary.##1}% + \glsxtrbookindexformatheader{\thisgrptitle}% + \nopagebreak\indexspace\nopagebreak\csuse{@afterheading}% + }% + \renewcommand*{\glossentry}[2]{% + \glstreeitem \glstarget{cs.##1}{\strut}% + \glsxtrifhasfield{dualid}{##1}% + {% + {% + \let\csfmtfont\csfmtcolourfont + \glshyperlink{\glscurrentfieldvalue}% + }% + \glsxtrifhasfield{useri}{##1}{\glscurrentfieldvalue}{}% + \donote{##1}% + \nopagebreak\par\hspace{10pt}% + \Glossentrydesc{\glscurrentfieldvalue}% + \ifglshasdesc{\glscurrentfieldvalue}{\@. }{}% + }% + {% + {\let\csfmtfont\csfmtcolourfont\gls[hyper=false]{##1}}% + \glsxtrifhasfield{useri}{##1}{\glscurrentfieldvalue}{}% + \donote{##1}% + \nopagebreak\par\hspace{10pt}% + \Glossentrydesc{##1}% + \ifglshasdesc{##1}{\@. }{}% + }% + \GlsXtrIfFieldEqStr{originalentrytype}{##1}{glscommand}% + {% + % Does this entry have options? + \GlsXtrIfHasNonZeroChildCount{##1}% + {% + \glspar\medskip\glspar + \summarysubheaderfont{Options:} + \glsxtrfieldforlistloop{##1}{childlist}{\summaryoptionhandler}% + }% + {}% + }% + {% + \GlsXtrIfHasNonZeroChildCount{##1}% + {This command has \glscurrentfieldvalue\ forms:}{}% + }% + %\listtopics{##1}% + \par\medskip + }% + \renewcommand*{\subglossentry}[3]{% + \glstreesubitem \glstarget{cs.##2}{\strut}% + \glsxtrifhasfield{dualid}{##2}% + {% + {% + \let\csfmtfont\csfmtcolourfont + \glshyperlink{\glscurrentfieldvalue}% + }% + \glsxtrifhasfield{useri}{##2}{\glscurrentfieldvalue}{}% + \donote{##2}% + \nopagebreak\par\hspace{20pt}% + \ifglshasdesc{\glscurrentfieldvalue}% + {\Glossentrydesc{\glscurrentfieldvalue}.}{}% + }% + {% + {\let\csfmtfont\csfmtcolourfont\gls[hyper=false]{##2}}% + \glsxtrifhasfield{useri}{##2}{\glscurrentfieldvalue}{}% + \donote{##2}% + \nopagebreak\par\hspace{20pt}% + \ifglshasdesc{##2}{\Glossentrydesc{##2}.}{}% + }% + \par\medskip + }% +} + +\newcommand*{\commandsummaryhook}[1]{% + \edef\currentcategory{\glscategory{#1}}% + \ifdefstring{\currentcategory}{command}% + {% + \glsxtrifhasfield*{progenitor}{#1}% + {\printunsrtglossaryskipentry}{}% + }% + {\printunsrtglossaryskipentry}% +} + +\newcommand*{\printcommandsummary}{% + \printunsrtglossary*[type=index, + style=commandsummary, + title={General Command Summary}, + ]% + {% + \def\glossarypreamble{This is an alphabetical summary of + commands referenced in this document. See the + relevent user guides for further details.\endgraf\medskip + \texparserdefnotetarget}% + \let\printunsrtglossaryentryprocesshook\commandsummaryhook + \let\csref\cs + \glsxtrlocalsetgrouptitle{glssymbols}{}% + }% +} + +\newcommand{\topicxrhandler}[1]{% + \glsxtrifhasfield{parent}{#1}% + {% + \let\field\fieldfmt + \hyperlink + {topic.\glscurrentfieldvalue}% + {\glsentryname{\glscurrentfieldvalue}}% + }% + {% + \hyperlink{topic.#1}{\glsentryname{#1}}% + }% +} + +% \iffirstprogeny{entry label}{topic label}{true}{false} +\makeatletter +\newcommand{\iffirstprogeny}[2]{% + \let\doiffirstprogeny\@secondoftwo + \def\firstprogeny{}% + \glsxtrifhasfield*{unsortedprogeny}{#1}% + {% + \edef\suppliedprogeny{#2}% + \@for\thisprogeny:=\glscurrentfieldvalue\do{% + \let\firstprogeny\thisprogeny + \ifdefequal{\thisprogeny}{\suppliedprogeny}% + {\let\doiffirstprogeny\@firstoftwo}% + {\let\doiffirstprogeny\@secondoftwo}% + \@endfortrue + }% + }% + {}% + \doiffirstprogeny +} +\makeatother + +\newcommand{\ifstylecommand}[1]{% + \letcs\doifstylecommand{@firstoftwo}% + \GlsXtrIfFieldEqStr{originalentrytype}{#1}{abbrvstylecommand}% + {}% + {% + \GlsXtrIfFieldEqStr{originalentrytype}{#1}{glostylecommand}% + {}% + {\global\letcs\doifstylecommand{@secondoftwo}}% + }% + \doifstylecommand +} + +\newcommand{\listtopics}[1]{% + \glsxtrifhasfield{progeny}{#1}% + {% + \ifdefequal\glscurrentfieldvalue\glscurrententrylabel + {}% + {% + \par\nopagebreak\medskip\par\footnotesize + \sloppy + \ifstylecommand{#1}% + {\summarysubheaderfont{Styles:}}% + {\summarysubheaderfont{Topics:}}% + \space + \let\DTLlistformatitem\topicxrhandler + \DTLformatlist{\glscurrentfieldvalue}.\par + }% + }% + {}% +} + +\newglossarystyle{commandtopic}% +{% + \setglossarystyle{index}% + %\renewcommand*{\glossaryheader}{\raggedright}% + \renewcommand*{\glsgroupheading}[1]{}% + \renewcommand*{\glossentry}[2]{% + \glsfieldfetch{##1}{nametitle}{\thisvalue}% + \section*{% + \raisebox{2ex}% + {\pdfbookmark[1]{\thisvalue}{topic.##1}\hypertarget{topic.##1}{}}% + \glsdisp{##1}{\thisvalue}\donote{##1}% + }% + \expandafter\sectionmark\expandafter{\thisvalue}% + \ifglshasdesc{##1}{\Glossentrydesc{##1}.}{}% + \glsxtrifhasfield{seealso}{##1}% + {% + \par\smallskip + \emph{See also:} + \let\DTLlistformatitem\topicxrhandler + \DTLformatlist{\glscurrentfieldvalue}.% + \par\medskip\par + }% + {}% + }% + \renewcommand*{\subglossentry}[3]{% + \glsifcategory{##2}{command}% + {% + \glsdohypertarget{topic.##2}{\strut}% + \glsxtrifhasfield*{progenitor}{##2}% + {\let\originallabel\glscurrentfieldvalue}% + {\def\originallabel{##2}}% +% + \ifstylecommand{##2}% + {% + \iffirstprogeny{\originallabel}{##2}% + {\letcs\dothisentry{@firstofone}}% + {% + \glspar + \ifdefempty\firstprogeny + {% + {\let\csfmtfont\csfmtcolourfont\gls[noindex]{\originallabel}}% + \glsxtrifhasfield{useri}{##2}{\glscurrentfieldvalue}{}% + }% + {% + {\let\csfmtfont\csfmtcolourfont + \hyperlink{topic.\firstprogeny}{\glsentryname{\firstprogeny}}}% + \glsxtrifhasfield{useri}{##2}{\glscurrentfieldvalue}{}% + \glsxtrifhasfield{parent}{\firstprogeny}% + {\hfill + {\footnotesize\emph{see} \hyperlink{topic.\glscurrentfieldvalue}% + {\glsentryname{\glscurrentfieldvalue}}.}} + {}% + }% + \letcs\dothisentry{@gobble}% + }% + }% + {\letcs\dothisentry{@firstofone}}% + \dothisentry + {% + \par\smallskip\par + % hyperlink to index: + {\let\csfmtfont\csfmtcolourfont\gls[format=glsignore]{\originallabel}}% + \glsxtrifhasfield{useri}{##2}{\glscurrentfieldvalue}{}% + \glsxtrifhasfield{note}{##2}% + {\nolinebreak\hfill\mbox{\footnotesize\glscurrentfieldvalue}}% + {}% + \nopagebreak\par\smallskip\par\nopagebreak + \ifglshasdesc{##2}{\Glossentrydesc{##2}.}{}% + % Topics + \listtopics\originallabel + \par\smallskip + }% + }% + {% + \glsfieldfetch{##2}{nametitle}{\thisvalue}% + \subsection*{% + \raisebox{2ex}% + {\hypertarget{topic.##2}{}\pdfbookmark[2]{\thisvalue}{topic.##2}}% + \glsdisp{##2}{\thisvalue}\donote{##2}% + }% + \expandafter\subsectionmark\expandafter{\thisvalue}% + \ifglshasdesc{##2}{\Glossentrydesc{##2}.\glspar\nopagebreak\smallskip}{}% + }% + }% +} + +\newcommand*{\commandtopichook}[1]{% + \glsxtrifhasfield*{progenitor}{#1}% + {}% + {% + \GlsXtrIfFieldEqStr*{originalentrytype}{#1}{topic}% + {}% + {% + \glsxtrifhasfield*{parent}{#1}% + {% + \GlsXtrIfFieldEqStr*{originalentrytype}{\glscurrentfieldvalue}{topic}% + {}% + {\printunsrtglossaryskipentry}% + }% + {\printunsrtglossaryskipentry}% + }% + }% +} + +\newcommand*{\printcommandtopic}{% + \setsecdepth*{0}% + \automark[subsection]{section}% + \printunsrtglossary*[type=index, + style=commandtopic, + title={Summary by Topic of Glossary Commands}, + label={sec:topics}, + nogroupskip, + nonumberlist + ]% + {% + \def\texparserdefprefix{topic.}% + \def\glossarypreamble{This is a summary of commands provided + by \styfmt{glossaries}, \styfmt{glossaries-extra} and + their supplementary packages that may be useful to + \bibgls\ users. Commands specific to other indexing methods + aren't listed unless they've been referenced in this manual. + See the appropriate user guides for further details. + \endgraf\medskip + \texparserdefnotetarget}% + \let\abbrstyle\topicabbrstyle + \let\glostyle\topicglostyle + \let\printunsrtglossaryentryprocesshook\commandtopichook + \let\csref\cs + }% + \setsecdepth{0}% +} + +\newglossarystyle{styoptsummary}% +{% + \setglossarystyle{mcolindex}% + \renewcommand{\glossarypreamble}{% + Most options are in the form \meta{option}=\meta{value} and + may have a default if \meta{value} is omitted, + but some options don't have values and should not have + one assigned. For boolean options, + if the value is omitted \styoptfmt{true} is assumed. + \extstyopt Indicates a value that's only provided by + \styfmt{glossaries-extra} and not by the base + \styfmt{glossaries} package. \par + }% + \renewcommand*{\glossaryheader}{}% + \renewcommand*{\glsgroupheading}[1]{% + \glsxtrgetgrouptitle{##1}{\thisgrptitle}% + \glsxtrbookindexbookmark{\thisgrptitle}{styopt.##1}% + \glsxtrbookindexformatheader{\thisgrptitle}% + \nopagebreak\indexspace\nopagebreak\csuse{@afterheading}% + }% + \renewcommand*{\glossentry}[2]{% + \item \glstarget{##1}{\strut}% + \glsxtrifhasfield{dualid}{##1}% + {% + \glshyperlink{\glscurrentfieldvalue}% + }% + {% + \gls[hyper=false]{##1}% + }% + \glsxtrifhasfield{useri}{##1}{=\glscurrentfieldvalue}{}% + \nopagebreak\par\hspace{10pt}% + \Glossentrydesc{##1}.% + \glsxtrifhasfield{package}{##1}% + {\nopagebreak\par \ding{43}Provided by + \ifdefstring{\glscurrentfieldvalue}{glossaries,glossaries-extra} + {\styfmt{glossaries} and modified by \styfmt{glossaries-extra}}% + {\styfmt{\glscurrentfieldvalue}}.}% + {}% + \glsxtrifhasfield{note}{##1}% + {\space \xmakefirstuc{\glscurrentfieldvalue}.}% + {}% + \par\medskip + }% +} + +\newcommand*{\styoptsummaryhook}[1]{% + \edef\currentcategory{\glscategory{#1}}% + \ifdefstring{\currentcategory}{packageoption}% + {}% + {\printunsrtglossaryskipentry}% +} + +\newcommand*{\printstyoptsummary}{% + \printunsrtglossary*[type=main, + style=styoptsummary, + title={Package Option Summary} + ]% + {% + \let\printunsrtglossaryentryprocesshook\styoptsummaryhook + \glsxtrlocalsetgrouptitle{glssymbols}{@}% + }% +} + +\newcommand{\entrysection}[2][\subsection]{% + #1[\texorpdfstring{\glsxtrheadname{entry.#2}}{\glsentryname{entry.#2}}] + {\glsadd{entry.#2}\glsxtrglossentry{entry.#2}}% +} + +\newcommand{\entrydef}[1]{\glsadd{entry.#1}\glsxtrglossentry{entry.#1}} + +\newcommand*{\atentry}[2][]{% + \texorpdfstring + {\gls[#1]{entry.#2}}% + {#2}% +} + +\newcommand*{\atentrypageref}[1]{% + \atentry{#1} (page~\glsxtrpageref{entry.#1})}% + +\newcommand*{\atentryref}[1]{\gls[format=glsignore]{entry.#1}} + +\newcommand{\argsection}[2][\section]{% + \def\switcharg{}% + \def\switchalt{}% + \def\switchaltpdf{}% + \glsxtrifhasfield*{useri}{switch.#2}% + {% + \edef\switcharg{ \expandonce\glscurrentfieldvalue}% + }% + {}% + \ifglshassymbol{switch.#2}% + {% + \def\switchalt{ (or \protect\glsentrysymbol{switch.#2}\switcharg)}% + }% + {}% + #1[\texorpdfstring + {\glsxtrheadname{switch.#2}}% + {\glsentryname{switch.#2}}% + \switcharg\switchalt + ] + {\glsadd{switch.#2}% + \glsxtrglossentry{switch.#2}\switcharg\switchalt}% +} + +\newrobustcmd{\longswitch}{\string-{}\string-} + +\newcommand*{\longargfmt}[1]{% + \texorpdfstring{\texttt{\longswitch #1}}% + {\string-\string-#1}% +} + +\newcommand*{\shortargfmt}[1]{% + \texorpdfstring{\texttt{\string-#1}}% + {\string-#1}% +} + +\newcommand*{\longarg}[1]{% + \texorpdfstring + {\gls{switch.#1}}% + {\string-\string-#1}% +} + +\newcommand*{\longargpageref}[1]{% + \longarg{#1} (page~\glsxtrpageref{switch.#1})}% + +\newcommand*{\longargorshort}[1]{% + \texorpdfstring + {\gls{switch.#1}\ifglshassymbol{switch.#1}{ or \glssymbol{switch.#1}}{}}% + {\string-\string-#1}% +} + +\newcommand*{\unicodecategoryfmt}[1]{\qt{\textsf{#1}}} + +\definecolor{defbackground}{rgb}{1,1,0.75} +\newsavebox\defsbox +\newlength\defwidth + +\newenvironment{definition}% +{% + \setlength{\fboxsep}{4pt}\setlength{\fboxrule}{1.25pt}% + \begin{lrbox}{\defsbox}% + \setlength\defwidth\linewidth + \addtolength\defwidth{-2\fboxrule}% + \addtolength\defwidth{-2\fboxsep}% + \begin{minipage}{\defwidth} + \flushleft\ttfamily\ignorespaces +}% +{% + \end{minipage}% + \end{lrbox}\par\medskip\noindent + \fcolorbox{black}{defbackground}{\usebox\defsbox}% + \medskip\par\noindent + \ignorespacesafterend +} + +\newcommand{\introguide}{\href{bib2gls-begin.pdf}{\qt{\styfmt{glossaries-extra} +and \bibgls: An Introductory Guide} (\filefmt{bib2gls-begin.pdf})}} + +\setcounter{tocdepth}{4} + +\newcommand*{\sectionref}[1]{\cref{#1}} +\newcommand*{\Sectionref}[1]{\Cref{#1}} +\newcommand*{\figureref}[1]{\hyperlink{#1-top}{figure~\ref*{#1}}} +\newcommand*{\Figureref}[1]{\hyperlink{#1-top}{Figure~\ref*{#1}}} +\newcommand*{\tableref}[1]{\cref{#1}} +\newcommand*{\Tableref}[1]{\Cref{#1}} + +\newcommand{\figcontents}[3]{% + \hypertarget{#3-top}{}% + \centering + #1\par + #2\label{#3}% +} + +\newlength\imagewidth +\newcount\tmpctr + +\newcommand*{\pdftwocol}[3][1]{% + \renewcommand{\tabcolsep}{2pt}% + \setlength{\imagewidth}{\dimexpr.5\linewidth-2\tabcolsep}% + \def\tabcontents{\begin{tabular}{@{}cc@{}}}% + \tmpctr\numexpr#1-1\relax + \loop + \advance\tmpctr by 1\relax + \eappto\tabcontents{\noexpand\frame{% + \noexpand\includegraphics[page=\the\tmpctr,width=\noexpand\imagewidth]{#2}}}% + \ifodd\tmpctr + \appto\tabcontents{&}% + \else + \appto\tabcontents{\\}% + \fi + \ifnum\tmpctr<#3 + \repeat + \appto\tabcontents{\end{tabular}}% + \tabcontents +} + +\makeatletter +\newcommand*{\tablelistcs}[2]{% + \tmpctr=0\relax + \def\tabcontents{}% + \loop + \advance\tmpctr by 1\relax + \appto\tabcontents{l}% + \ifnum\tmpctr<#1 + \repeat +% + \edef\tabcontents{\noexpand\begin{tabular}{@{}\tabcontents @{}}}% + \def\thislist{#2}% + \dtlsortlist{\thislist}{\dtlicompare}% + \tmpctr=1\relax + \@for\thislabel:=\thislist\do{% + \eappto\tabcontents{\noexpand\ics{\thislabel}}% + \ifnum\tmpctr<#1\relax + \appto\tabcontents{&}% + \advance\tmpctr by 1\relax + \else + \appto\tabcontents{\\}% + \tmpctr=1\relax + \fi + }% + \appto\tabcontents{\end{tabular}}% + \tabcontents +} +\makeatother + +% This is a bit fiddly. Need to represent \vec{v} in typewriter +% font for the interpreter examples. ($\mathtt{\vec{v}}$ doesn't +% work) +\newsavebox\varrow +\sbox\varrow{$\mathtt{\accentset{\to}{v}}$} + +\newcommand*{\mtx}[1]{\boldsymbol{#1}} +\newcommand*{\set}[1]{\mathcal{#1}} +\newcommand*{\card}[1]{|\set{#1}|} +\newcommand*{\imaginary}{i} + +\newcommand{\addr}[1]{\\\href{https://www.#1/}{\nolinkurl{#1}}} +\title{\bibgls: a command line Java application to convert +\filefmt{.bib} files to \filefmt{glossaries-extra.sty} resource +files} +\author{Nicola Talbot\addr{dickimaw-books.com}} +\date{\DTMusedate{moddate}} + +\makeatletter +\renewcommand{\fps@figure}{htbp} + +\newcommand{\code}[1]{\texorpdfstring{{\ttfamily\obeyspaces #1}}{#1}} + +\newcommand{\setupcodeenvfmts}{% + \def\cmd{\char`\\}% + \def\comment##1{\mbox{\textcolor{comment}{\idx{commentchar}\ ##1}}}% + \renewcommand*{\styfmt}[1]{##1}% + \renewcommand*{\counterfmt}[1]{##1}% + \renewcommand*{\catattrfmt}[1]{\textcolor{attribute}{##1}}% + \renewcommand*{\abbrstylefmt}[1]{\textcolor{style}{##1}}% + \renewcommand*{\csfmtfont}[1]{\textcolor{cs}{##1}}% +} + +\newenvironment{codeenv} + {% + \renewcommand{\glslinkpresetkeys}{\setkeys{glslink}{noindex}}% + \setupcodeenvfmts + \begin{flushleft}\ttfamily\obeylines\frenchspacing\@vobeyspaces + \parindent\z@\parfillskip\@flushglue\parskip\z@skip + } + {\end{flushleft}\ignorespacesafterend} + +\newenvironment{codeenv*} + {% + \setupcodeenvfmts + \begin{flushleft}\ttfamily\obeylines\frenchspacing\@vobeyspaces + \parindent\z@\parfillskip\@flushglue\parskip\z@skip + } + {\end{flushleft}\ignorespacesafterend} + +\begingroup + \renewcommand{\addr}[1]{} + \let\texorpdfstring\@secondoftwo + \DTMsetstyle{pdf} + \protected@edef\x{\endgroup + \noexpand\hypersetup{% + pdfinfo={ + Title={\@title}, + Author={\@author}, + CreationDate={\DTMuse{creation}}, + ModDate={\DTMuse{moddate}}, + }% + }% + }\x + +\makeatother + +\renewcommand{\titlepagestyle}{empty} + +\begin{document} +\maketitle +\pagenumbering{alph} +\pagestyle{empty} + +\begin{abstract} +The \bibgls\ command line application can be used to extract +glossary information stored in a \ext{bib} file and convert it +into glossary entry definitions that can be read using +\styfmt{glossaries-extra}'s \gls{GlsXtrLoadResources} command. When used +in combination with the \styoptfmt{record} package option, \bibgls\ +can select only those entries that have been used in the document, +as well as any dependent entries, which reduces the \TeX\ resources +required by not defining unnecessary commands. + +Since \bibgls\ can also sort and collate the recorded locations +present in the \ext{aux} file, it can simultaneously by-pass the +need to use \idx{makeindex} or \idx{xindy}, although \bibgls\ +can be used together with an external indexing application if required. (For +example, if a custom \idx{xindy} rule is needed.) + +An additional build may be required to ensure the locations are +up-to-date as the page-breaking may be slightly different on the +first \LaTeX\ run due to the unknown references being replaced with +?? which can be significantly shorter than the actual text produced +when the reference is known. + +Note that \bibgls\ is a Java application, and requires at least +Java~8.\footnote{The \code{List.sort} method used to sort the +entries was only introduced to Java~8.} Additionally, +\sty{glossaries-extra} must be at least version 1.12. (Although +the latest version is recommended.) This application was +developed in response to the question +\qt{\href{http://tex.stackexchange.com/q/342544}{Is there a program +for managing glossary tags?}} on \TeX\ on +StackExchange~\cite{tex.sx}. The \ext{bib} file can be managed in an +application such as JabRef. + +If you already have a \ext{tex} file containing +entry definitions using commands like \gls{newglossaryentry} +then you can use the supplementary tool \idx{convertgls2bib} +to convert the entries to the \ext{bib} format required by +\bibgls. See \sectionref{sec:gls2bib} for further details. + +The supplementary file \introguide\ is an +introductory guide to the \sty{glossaries-extra} package, which you +may prefer to start with if you are unfamiliar with the +\sty{glossaries} and \sty{glossaries-extra} packages. +\end{abstract} + +\frontmatter + +\tableofcontents +\listoftables +\listoffigures + +\mainmatter +\chapter{Introduction} + +If you have extensively used the \styfmt{glossaries}~\cite{glossaries} or +\styfmt{glossaries-extra}~\cite{glossaries-extra} package, +you may have found yourself creating a large \iext{tex} file +containing many definitions that you frequently use in documents. +This file can then simply be loaded using \ics{input} or +\ics{loadglsentries}, but a large file like this can be difficult to +maintain and if the document only actually uses a small proportion +of those entries, the document build is unnecessarily slow due to +the time and resources taken on defining the unwanted entries. + +The aim of \bibgls\ is to allow the entries to be stored in a +\iext{bib} file, which can be maintained using a reference system +such as JabRef. The document build process +can now be analogous to that used with \idx{bibtex} (or +\appfmt{biber}), where only those entries that have been recorded in the +document (and possibly their dependent entries) will be extracted +from the \ext{bib} file. Since \bibgls\ can also perform +hierarchical sorting and can collate location lists, it doubles as +an indexing application, which means that the \idx{makeglossaries} +step can be skipped. +Note that \bibgls\ doesn't warn you if an entry that's referenced +in the document doesn't exist in any of the supplied \ext{bib} +files, but instead relies on the \styfmt{glossaries-extra} package +to generate the warning. So at the end of the document build check +the \ext{log} file for warnings. + +You can't use \ics{glsaddall} with \bibgls\ as that command works +by iterating over all defined entries and calling +\code{\ics{glsadd}\margm{label}}. On the first \LaTeX\ run there are no +entries defined, so \ics{glsaddall} does nothing. If you want to +select all entries, just use \csopt[all]{selection} instead (which +has the advantage over \ics{glsaddall} in that it doesn't create a +redundant location for each entry). + +Note that \bibgls\ requires the extension package +\isty{glossaries-extra} and can't be used with just the base +\isty{glossaries} package, since it requires some of the extension +commands. See the \styfmt{glossaries-extra} user +manual~\cite{glossaries-extra} for information +on the differences between the basic package and the extended +package, as some of the default settings are different. + +Since the information used by \bibgls\ is +written to the \iext{aux} file, it's not possible to run \bibgls\ +through \TeX's shell escape while the \ext{aux} file is open for +write access. (The \ext{aux} file is closed \emph{after} the end +document hook, so it can't be deferred with \ics{AtEndDocument}.) +This means that if you really want to run \bibgls\ +through \ics{write18} it must be done in the preamble with +\ics{immediate}. For example: +\begin{verbatim} +\immediate\write18{bib2gls \jobname} +\end{verbatim} +As from version 1.14 of \styfmt{glossaries-extra}, this can be done +automatically with the \styopt{automake} option if the \ext{aux} +file exists. (Remember that this will require the shell escape to be +enabled.) + +\section{Example Use} +The glossary entries are stored in a \ext{bib} file. For +example, the file \filefmt{entries.bib} might contain: +\begin{codeenv} +\atentry{entry}\marg{bird, + \field{name}=\marg{bird}, + \field{description} = \marg{feathered animal} +} +\strut +\atentry{abbreviation}\marg{html, + \field{short}=\qtdelim{html}, + \field{long}=\marg{hypertext markup language} +} +\strut +\atentry{symbol}\marg{v, + \field{name}=\marg{\idx{mshiftchar}\cs{vec}\marg{v}\idx{mshiftchar}}, + \field{text}=\marg{\cs{vec}\marg{v}}, + \field{description}=\marg{a vector} +} +\strut +\atentry{index}\marg{goose,\field{plural}=\qtdelim{geese}} +\end{codeenv} +Here's an example document that uses this data: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cs{usepackage}\oarg{\styoptref{record}}\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{data in entries.bib} + \csopt[en-GB]{sort}\comment{sort according to 'en-GB' locale} +} +\strut +\cmd{begin}\marg{document} +\cs{Gls}\marg{bird} and \cs{gls}\marg{goose}. +Symbol: \idx{mshiftchar}\cs{gls}\marg{v}\idx{mshiftchar}. +Abbreviation: \cs{gls}\marg{html}. +\strut +\cs{printunsrtglossaries} +\cmd{end}\marg{document} +\end{codeenv} +If this document is called \filefmt{myDoc.tex}, the build +process is: +\begin{verbatim} +pdflatex myDoc +bib2gls myDoc +pdflatex myDoc +\end{verbatim} +(This manual assumes \appfmt{pdflatex} for simplicity. Replace +with \appfmt{latex}, \appfmt{xelatex} or \appfmt{lualatex} as +appropriate.) If you want \idxpl{lettergroup} (either headed, with +styles like \glostyle{indexgroup}, or just a blank line separator +with \styopt[false]{nogroupskip}) then you need to use the +\longarg{group} switch: +\begin{verbatim} +pdflatex myDoc +bib2gls --group myDoc +pdflatex myDoc +\end{verbatim} + +You can have multiple instances of \gls{GlsXtrLoadResources}. For +example: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\oarg{\styopt{record},\styopt{index},\styopt{abbreviations},\styopt{symbols}}\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{data in entries.bib} + \csopt[en-GB]{sort},\comment{sort according to 'en-GB' locale} + \csopt[entrytype=\marg{entry}]{match},\comment{only select \atentry{entry}} + \csopt[main]{type}\comment{put these entries in the 'main' glossary} +} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{data in entries.bib} + \csopt[en-GB]{sort},\comment{sort according to 'en-GB' locale} + \csopt[entrytype=\marg{abbreviation}]{match},\comment{only select \atentry{abbreviation}} + \csopt[abbreviations]{type}\comment{put these in the 'abbreviations' glossary} +} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{data in entries.bib} + \csopt[letter-case]{sort},\comment{case-sensitive letter sort} + \csopt[entrytype=\marg{symbol}]{match},\comment{only select \atentry{symbol}} + \csopt[symbols]{type}\comment{put these entries in the 'symbols' glossary} +} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{data in entries.bib} + \csopt[en-GB]{sort},\comment{sort according to 'en-GB' locale} + \csopt[entrytype=\marg{index}]{match},\comment{only select \atentry{index}} + \csopt[index]{type}\comment{put these entries in the 'index' glossary} +} +\strut +\cmd{begin}\marg{document} +\cs{Gls}\marg{bird} and \cs{gls}\marg{goose}. +Symbol: \idx!{mshiftchar}\cs{gls}\marg{v}\idx!{mshiftchar}. Abbreviation: \cs{gls}\marg{html}. +\cs{printunsrtglossaries} +\cmd{end}\marg{document} +\end{codeenv} +There are more examples provided in \sectionref{sec:examples}. + +Note that there's no need to called \idx!{xindy} or \idx!{makeindex} +since \bibgls\ automatically sorts the entries and collates the locations +after selecting the required entries from the \ext{bib} file and +before writing the temporary file that's input with \gls{glsxtrresourcefile} +(or the more convenient shortcut +\gls{GlsXtrLoadResources}).\footnote{This document will mostly use +the more convenient \gls{GlsXtrLoadResources}.} This +means the entries are already defined in the correct order, and only +those entries that are required in the document are defined, so +\ics{printunsrtglossary} (or \ics{printunsrtglossaries}) may be used. +(The \qtt{unsrt} part of the command name indicates that all +defined entries should be listed in the order of definition from +\styfmt{glossaries-extra}'s point of view, see the supplementary +document \introguide\ for further details.) + +If you don't provide a value with the \styopt{record} option, then +\styopt[only]{record} is assumed. This saves the same indexing +information that's used with the \ics{cs.makeglossaries} and +\ics{makenoidxglossaries} methods (described in the main +\styfmt{glossaries} user manual~\cite{glossaries}). As from +\styfmt{glossaries-extra} version 1.37, you can instead use +\styopt[nameref]{record}, which saves some extra information for +each location that's not available for the other indexing methods. +See \longarg{merge-nameref-on} for further details. + +If you additionally want to use an indexing application, such +as \idx{xindy}, you need the package option +\styopt[alsoindex]{record} and use \ics{cs.makeglossaries} +and \ics{printglossary} (or the iterative \ics{printglossaries}) as usual. +This requires a more complicated build process: +\begin{verbatim} +pdflatex myDoc +bib2gls myDoc +pdflatex myDoc +makeglossaries myDoc +pdflatex myDoc +\end{verbatim} +(The entries aren't defined until the second \LaTeX\ run, so the +indexing files required by \idx!{xindy} or \idx!{makeindex} can't be +created until then.) In this case, \bibgls\ is simply being used to +fetch the entry definitions from one or more \ext{bib} files, with +the sorting and collating performed by the other indexing +application (so the resource option list would need +\csopt[none]{sort} and \csopt[false]{save-locations}). In general, +it's best to avoid this hybrid method unless you have a particular +set of \idx{xindy} rules that can't be replicated with \bibgls. + +\section{Logical Divisions: \field{type} vs \field{group} vs \field{parent}} +\label{sec:logicaldivisions} + +If you have a document with many terms that need listing, it's +likely that you may want to divide the terms into separate blocks or +units for easier reading. There are three fields that are used +for this. +\begin{description} +\item[\field{type}] The highest division is the glossary to which +the entry belongs. The glossary must first be defined (see +\sectionref{sec:newglossary}) with an associated label used to +identify it. The title is assigned to the glossary when it is +defined or it can be overridden with the \printglossopt{title} key. +The glossary is displayed using \cs{printunsrtglossary} and the +title is placed in a sectioning command by default. + +\begin{important} +\bibgls\ does not provide any means of sorting glossary types. If +you use \ics{printunsrtglossaries} the order will be according to +the order in which the glossaries were defined. You may use +\cs{printunsrtglossary} to list individual glossaries in your own +preferred order. +\end{important} + +\item[\field{group}] The entries within a glossary can form groups +as a by-product of the sorting method. This must be enabled with the +\longarg{group} switch and isn't available for the sort methods +listed in \tableref{tab:sortoptionsnosort}. The group label is +stored in the \field{group} field. This is an internal field that +typically shouldn't be set in the \ext{bib} file. + +You can specify your own custom groups but if you do so you must +ensure that the terms are ordered in such a way that they are +gathered according to group. This is typically done by splitting the +glossary into blocks using a separate \gls{GlsXtrLoadResources} with +the \csopt{group} option set. You control the order of the groups by +your ordering of \gls{GlsXtrLoadResources}. The group title can be +assigned using \gls{glsxtrsetgrouptitle} within the document. + +\begin{important} +\bibgls\ does not sort by group title. At most it can sort by the +group label (by changing the \csopt{sort-field}) but this is usually +an indication that you actually have a hierarchical glossary and you +ought to be using the \field{parent} field instead. (Compare +\exfile{sample-textsymbols.tex} and +\exfile{sample-textsymbols2.tex}.) +\end{important} + +\item[\field{parent}] An entry may have one or more sub-entries. +Most of the sort methods will produce a hierarchical ordering that +ensures that the sub-entries are listed immediately after their +parent entry. The parent entry is identified by the \field{parent} +field which should contain the parent's label. + +\begin{important} +\bibgls\ sorts the parent and child entries using the same +comparator. The sort methods listed +in \tableref{tab:sortoptionsnosort} disregard the hierarchical +level, which can result in child entries becoming detached from +their parent entry. The other methods sort hierarchically using +the same comparator but take the hierarchical level into account. +\end{important} + +\end{description} + +Suppose you have a mixture of terms, abbreviations and symbols, then +you might want to have three glossaries that are listed in the table +of contents. In this case, you use the \field{type} field or the +\field{type} resource option. The ordering of the glossaries is +determined by the ordering of the \cs{printunsrtglossary} +commands within the document. For example: +\begin{codeenv} +\cs{printunsrtglossary} +\cs{printunsrtglossary}\oarg{\printglossopt[abbreviations]{type}} +\cs{printunsrtglossary}\oarg{\printglossopt[symbols]{type}} +\end{codeenv} + +Suppose that your list of terms spans many pages and you feel it +would be helpful to the reader to split it up into letter groups +then you would need to run \bibgls\ with the \longarg{group} switch +and use a glossary style that supports letter groups for that +glossary. For example: +\begin{codeenv} +\cs{printunsrtglossary}\oarg{\printglossopt[indexgroup]{style}} +\end{codeenv} + +Suppose that your list of symbols consists of pictographs, Latin characters +and Greek characters and you want them grouped together +in that order. Then you would use a separate +\gls{GlsXtrLoadResources} for each block and assign your own custom +group. This means ensuring that each \idx{resourceset} only selects +the terms for that group. The simplest way of doing this is to +have a separate \ext{bib} file for each set. For example: +\begin{codeenv} +\gls{glsxtrsetgrouptitle}\marg{pictographs}\marg{Pictographs} +\gls{glsxtrsetgrouptitle}\marg{latinsymbols}\marg{Latin Characters} +\gls{glsxtrsetgrouptitle}\marg{greeksymbols}\marg{Greek Characters} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[generalsymbols]{src},\comment{data in generalsymbols.bib} + \csopt[pictographs]{group}, + \csopt[symbols]{type} +} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[latinsymbols]{src},\comment{data in latinsymbols.bib} + \csopt[latin]{group}, + \csopt[symbols]{type} +} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[greeksymbols]{src},\comment{data in greeksymbols.bib} + \csopt[greek]{group}, + \csopt[symbols]{type} +} +\end{codeenv} + +Suppose instead that you have many of these logical blocks and you +want them ordered according to the block title. In this case you +have a hierarchical glossary and you need to use the \field{parent} +field. You then need to select an appropriate \idx{glossarystyle}. + +If you only want to have a single \ext{bib} file that contains all +your entries and you want to share it across multiple documents then +the most flexible approach is to use custom fields and entry types +that can be aliased according to the needs of the +\idxpl{resourceset}. + +For example, the file \filefmt{entries.bib}: +\begin{codeenv} +\comment{Encoding: UTF-8} +\strut +\atentryfmt{indexplural}\marg{latin,\field{text}=\marg{Latin character}} +\atentryfmt{indexplural}\marg{greek,\field{text}=\marg{Greek character}} +\atentryfmt{indexplural}\marg{pictograph} +\strut +\atentry{symbol}\marg{fx, + \field{name}=\marg{\cs{ensuremath}\marg{f(x)}}, + \field{description}=\marg{function of \idx{mshiftchar}x\idx{mshiftchar}}, + \fieldfmt{identifier}=\marg{latin} +} +\strut +\atentry{symbol}\marg{f\idx{aposchar}x, + \field{name}={\cs{ensuremath}\marg{f\idx{aposchar}(x)}}, + \field{description}=\marg{derivative of \cs{gls}\marg{fx}}, + \fieldfmt{identifier}=\marg{latin} +} +\strut +\atentry{symbol}\marg{pi, + \field{name}=\marg{\cs{ensuremath}\marg{\cs{pi}}}, + \field{description}=\marg{ratio of circumference to diameter}, + \fieldfmt{identifier}=\marg{greek} +} +\strut +\atentry{symbol}\marg{heart, + \field{name}=\marg{\cs{ensuremath}\marg{\ics{heartsuit}}}, + \field{description}=\marg{heart}, + \fieldfmt{identifier}=\marg{pictograph} +} +\strut +\atentry{symbol}\marg{diamond, + \field{name}=\marg{\cs{ensuremath}\marg{\ics{diamondsuit}}}, + \field{description}=\marg{diamond}, + \fieldfmt{identifier}=\marg{pictograph} +} +\strut +\atentry{abbreviation}\marg{html, + \field{short}=\marg{html}, + \field{long}=\marg{hypertext markup language}, + \fieldfmt{identifier}=\marg{markuplanguage} +} +\strut +\atentry{abbreviation}\marg{xml, + \field{short}=\marg{xml}, + \field{long}=\marg{extensible markup language}, + \fieldfmt{identifier}=\marg{markuplanguage} +} +\strut +\atentry{entry}\marg{duck, + \field{name}=\marg{duck}, + \field{description}=\marg{a waterbird with webbed feet}, + \fieldfmt{identifier}=\marg{animal} +} +\strut +\atentry{entry}\marg{parrot, + \field{name}=\marg{parrot}, + \field{description}=\marg{mainly tropical bird with bright plumage}, + \fieldfmt{identifier}=\marg{animal} +} +\end{codeenv} +This has a custom field \fieldfmt{identifier}. This will be ignored +by \bibgls\ unless defined or aliased in the document. + +Here's an example document that creates three glossary types (the +default \code{main} glossary and the glossaries created with the +\styopt{abbreviations} and \styopt{symbols} options). They are +listed in the order of \cs{printunsrtglossary} and their titles are +added to the table of contents. + +The custom \fieldfmt{identifier} fields are ignored for the +main and abbreviation glossaries, but they are aliased for the +symbols to the \field{group} field. Since I've split the symbols +glossary into blocks with each block only containing entries that +have the same \field{group} value, this isn't a problem. It also +won't trigger a warning with \longarg{warn-non-bib-fields} as it's +being aliased rather than set in the \ext{bib} file. The blocks +appear in the same order as the corresponding \gls{GlsXtrLoadResources} +commands. The title for each block is provided in the document +using \gls{glsxtrsetgrouptitle}. +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\oarg{\styopt{record},\styopt{abbreviations},\styopt{symbols}}\marg{glossaries-extra} +\strut +\cs{renewcommand}\marg{\gls{GlsXtrDefaultResourceOptions}}\marg{ + \csopt[all]{selection},\csopt[entries]{src},\csopt[false]{save-locations}} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[main]{type},\csopt[entrytype=entry]{match}} +\gls{GlsXtrLoadResources}\oarg{\csopt[abbreviations]{type}, + \csopt[entrytype=abbreviation]{match}} +\strut +\gls{glsxtrsetgrouptitle}\marg{pictograph}\marg{Pictographs} +\gls{GlsXtrLoadResources}\oarg{\csopt[symbols]{type}, + \csopt[identifier=\field{group}]{field-aliases}, + \csopt[\field{group}=pictograph]{match}} +\strut +\gls{glsxtrsetgrouptitle}\marg{latin}\marg{Latin Characters} +\gls{GlsXtrLoadResources}\oarg{\csopt[symbols]{type}, + \csopt[identifier=\field{group}]{field-aliases}, + \csopt[\field{group}=latin]{match}} +\strut +\gls{glsxtrsetgrouptitle}\marg{greek}\marg{Greek Characters} +\gls{GlsXtrLoadResources}\oarg{\csopt[symbols]{type}, + \csopt[identifier=\field{group}]{field-aliases}, + \csopt[\field{group}=greek]{match}} +\strut +\cmd{begin}\marg{document} +\cs{tableofcontents} +\cs{printunsrtglossary}\oarg{\printglossopt[abbreviations]{type}} +\cs{printunsrtglossary} +\cs{printunsrtglossary}\oarg{\printglossopt[symbols]{type},\printglossopt[\glostyle{treegroup}]{style}} +\cmd{end}\marg{document} +\end{codeenv} + +In the above example document, the symbols list is divided into +three groups, listed in the order: Pictographs, Latin characters and +Greek characters. If you want these titles ordered alphabetically +then you need a hierarchical structure instead. This can be obtained +by aliasing the custom \fieldfmt{identifier} field to +\field{parent}: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\oarg{\styopt{record},\styopt[topic]{stylemods},\styopt{abbreviations},\styopt{symbols}}\marg{glossaries-extra} +\strut +\cs{renewcommand}\marg{\gls{GlsXtrDefaultResourceOptions}}\marg{\comment{} + \csopt[all]{selection},\csopt[entries]{src},\csopt[false]{save-locations}} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[main]{type},\csopt[entrytype=entry]{match}} +\gls{GlsXtrLoadResources}\oarg{\csopt[abbreviations]{type}, + \csopt[entrytype=abbreviation]{match}} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[symbols]{type}, + \csopt[identifier=\field{parent}]{field-aliases}, + \csopt[entrytype=symbol,entrytype=indexplural]{match}} +\strut +\cmd{begin}\marg{document} +\cs{tableofcontents} +\cs{printunsrtglossary}\oarg{\printglossopt[abbreviations]{type}} +\cs{printunsrtglossary} +\cs{printunsrtglossary}\oarg{\printglossopt[symbols]{type},\printglossopt[\glostyle{topic}]{style}} +\cmd{end}\marg{document} +\end{codeenv} +The style used for the symbols list is now \glostyle{topic} rather +than \glostyle{treegroup}. This results in a slightly different +appearance. You can select the most appropriate style according to +your needs (see the gallery of predefined +styles~\cite{glossarystylesgallery}). The topic ordering is now: +Greek characters, Latin characters and Pictographs. + +\section{Defining a New Glossary} +\label{sec:newglossary} + +Some of the examples in this manual use \ics{newglossary*} to define +a new glossary type and some use \ics{newignoredglossary} or +\ics{newignoredglossary*}. Why the starred forms and why define an +\idx{ignoredglossary}? + +The base \styfmt{glossaries} package was originally designed to work +with \idx!{makeindex}. Support for \idx!{xindy} was later added, but +both require three files per glossary type: the transcript file +(created by the indexing application), the file written by \LaTeX\ +(and input by the indexing application) and the file input by +\LaTeX\ (and written by the indexing application). So when a new glossary +is defined with \ics{newglossary}, this not only defines internal +control sequences that store the list of entry labels associated +with that glossary, the title and the entry format but also has to +define internal control sequences that store the three file +extensions. The starred form \cs{newglossary*} is just a shortcut +that forms the extensions from the glossary label. For the purposes +of \bibgls, this is simpler than the unstarred version since the +extensions are now irrelevant as they are only applicable to +\idx!{makeindex} and \idx!{xindy}. (Unless, of course, you are using +a hybrid method with \styopt[alsoindex]{record}.) + +Since some users wanted the ability to define entries that were +common enough to not be worth including in any glossary lists, the +concept of an \idx{ignoredglossary} was introduced, defined with +\cs{newignoredglossary}. This only requires an internal control +sequence to store the list of entry labels associated with that +glossary\footnote{All entries must be assigned to a glossary. If you +don't use the \field{type} field the default is used.}\ and the +associated internal command that governs the way that +commands like \cs{gls} are displayed for that glossary type. +Since this type of glossary has no associated files, it can't be +used with \cs{printglossary} and therefore isn't included in the +list of glossary labels that's iterated over by commands like +\cs{printglossaries}. Since there's no glossary list (and therefore +no targets), \cs{newignoredglossary} additionally disables hyperlinks for that +glossary type, but it doesn't disable indexing. The indexing macro +is still called, but because there's no associated file to write to, +it has no effect. With \bibgls, the indexing is written to the +\ext{aux} file and so does have an effect. + +Although \idxpl{ignoredglossary} can't be used with +\cs{printglossary}, they can be used with \cs{printunsrtglossary}, +which is designed to work without any indexing, but you need to +explicitly set the title in the optional argument to override the +default. The \idxpl{ignoredglossary} still can't be used in +\cs{printunsrtglossaries}, since they're not included in the list +that this command iterates over. + +So \cs{newignoredglossary} is useful with \bibgls\ if you're happy +to use \cs{printunsrtglossary} as it reduces the overall number of +internal control sequences. Since there is now the possibility of +targets (created within \cs{printunsrtglossary}), it's useful to +have an \idx{ignoredglossary} that doesn't suppress the hyperlinks, +which can be obtained with the starred form \ics{newignoredglossary*} +provided by \styfmt{glossaries-extra}. + +Some resource options, such as \csopt{master}, \csopt{secondary} and +\csopt{trigger-type}, need to ensure that a +required glossary is defined. In this case, \bibgls\ uses +\ics{provideignoredglossary*} in the \iext{glstex} file. If you +haven't already defined that glossary in the document with \cs{newglossary*}, +you'll need to set the title in the optional argument of +\cs{printunsrtglossary} if you don't want the default. The glossary +won't be defined on the first run (if the definition is only +provided in the \ext{glstex} file) but \cs{printunsrtglossary} will +just give a warning if the type is undefined so it won't interrupt +the document build. + +\section{Resource Sets} +\label{sec:resourcesets} + +Each instance of \gls{glsxtrresourcefile} or +\gls{GlsXtrLoadResources} in the document represents a \idx{resourceset}. Each +\idx{resourceset} has one or more associated \iext{bib} files +that provides the data for that set. Command line switches +(\sectionref{sec:switches}) are applied to all \idxpl{resourceset}. +Resource options (\sectionref{sec:resourceopts}) are only applied to +that specific \idx{resourceset}. Each \idx{resourceset} is processed +in stages: +\begin{description} + +\item[Stage 1 (Initialisation)] Occurs after the \ext{aux} file has +been read, this stage parses the resource option list and ensures +options are valid and don't cause a conflict. The transcript will +show the message +\begin{alltt} +Initialising resource \meta{resource-name} +\end{alltt} +at this point. + +\item[Stage 2 (Parsing)] All the \iext{bib} files associated with +the \idx{resourceset} are parsed. Entry aliases (identified by +\csopt{entry-type-aliases}) are performed. The +\hyperref[sec:multientry]{multi-entry types}, such as +\atentry{bibtexentry} and \atentry{progenitor}, spawn their +associated primary entries. Preamble information (provided by +\atentry{preamble}) is saved but is not interpreted at this stage. +The transcript will show the message +\begin{alltt} +Parsing bib files for resource \meta{resource-name} +\end{alltt} +at this point. + +\item[Stage 3 (Processing Entries)] +The transcript will show the message +\begin{alltt} +Processing resource \meta{resource-name} +\end{alltt} +at this point. +For each entry that was found in +the corresponding set of \ext{bib} files: +\begin{itemize} +\item Records are transferred to aliases if required (\csopt{alias-loc}). +\item Field checks and modifications are performed: + \begin{itemize} + \item field aliases are performed (\csopt{field-aliases}); + + \item ignored fields (identified by \csopt{ignore-fields}) are + removed; + + \item case-changes (for example, \csopt{short-case-change}) are + performed, except for the \field{name} field and fields identified + with \csopt{field-case-change}; + + \item suffixes are appended if required (for example, with + \csopt{short-plural-suffix}); + + \item field replications are made (\csopt{replicate-fields}), + and any of the above case-change or suffixes required + on the replicated fields are performed; + + \item the \field{group} field is assigned if \csopt[\meta{label}]{group} + is set; + + \item any variables (identified by \atentry{string}) are expanded + (if not already done in any of the previous steps); + + \item any fields that have been identified by + \csopt{bibtex-contributor-fields} are converted; + + \item any fields that have been identified with + \csopt{encapsulate-fields} are converted; + + \item any fields that have been identified with + \csopt{encapsulate-fields*} are converted; + + \item any fields that must be converted into a label form + (\csopt{labelify} or \csopt{labelify-list}) are processed; + + \item any fields identified by \csopt{dependency-fields} are parsed for + dependent entries; + + \item any fields whose value must be a label are interpreted + if \csopt{interpret-label-fields} is set; + + \item the \field{parent} field is adjusted according to the label prefix + settings (\csopt{label-prefix} etc); + + \item \ics{makefirstuc} protection is applied according to + \longarg{mfirstuc-protection} and \longarg{mfirstuc-math-protection}; + + \item fields are parsed for commands like \cs{gls} or + \cs{glshyperlink} and also checked for nested links if + \longarg{nested-link-check} is set; + + \item the \field{description} field is adjusted according to + \csopt{strip-trailing-nopost}; + + \item end punctuation is checked according to + \csopt{check-end-punctuation}; + + \item \field{name} case-change is performed if + \csopt{name-case-change} is set; + + \item if \csopt[true]{copy-alias-to-see} the \field{alias} is copied + to the \field{see} field; + + \item general field case changes identified by + \csopt{field-case-change} are performed; + + \item any fields that have been identified with + \csopt{interpret-fields} are replaced with their interpreted + values. + \end{itemize} +\item The dual version (if appropriate) is created. +\item Records are added to the entry's location list (or transferred +to the dual\slash primary according to \csopt{combine-dual-locations}). +\item The \field{type}, \field{category} and \field{counter} fields +are set according to \csopt{type}, \csopt{dual-type}, +\csopt{category}, \csopt{dual-category}, \csopt{counter} and +\csopt{dual-counter}. +\item Filtering is applied (according to options like \csopt{match} +but not \csopt{selection} or \csopt{limit}). +\item Required fields are checked for existence. +\item Dependencies are registered (if +\csopt[recorded and deps]{selection} or \csopt[recorded and deps and +see]{selection}). +\item Any fields that have been identified by +\csopt{date-time-fields}, \csopt{date-fields} or \csopt{time-fields} +are converted. +\end{itemize} +If \csopt[recorded and deps and see]{selection} then any recorded +entries that have been cross-referenced by an unrecorded entry, will +register a dependency with the unrecorded entry. Finally, +supplemental records are added to entries. + +\item[Stage 4 (Selection, Sorting, Writing)] Entries are selected +from the list according to the \csopt{selection} setting, sorting is +performed (if required), truncation is applied (if \csopt{limit} is +set) and the \iext{glstex} file is written. +The transcript will show the message +\begin{alltt} +Selecting entries for resource \meta{resource-name} +\end{alltt} +or (if \csopt{master}) +\begin{alltt} +Processing master \meta{resource-name} +\end{alltt} +at this point. + +\end{description} + +Parent entries must always be in the same \idx{resourceset} as their +child entries. (They may be defined in different \ext{bib} files as +long as all those \ext{bib} files are listed in the same \csopt{src}.) +Other forms of dependencies may be in a +different \idx{resourceset} under certain circumstances. These types +of dependencies are instances of commands such as \cs{gls} being +found (for example, in the \field{description} field), or the +cross-reference fields (\field{see}, \field{seealso} or +\field{alias} or fields identified with \csopt{dependency-fields}) +in recorded entries that reference unrecorded entries. + +The \qt{cross-referenced by} dependencies enabled with +\csopt[recorded and deps and see]{selection} (where an unrecorded +entry references a recorded entry through the cross-reference +fields) \emph{aren't supported} across \idxpl{resourceset} (even with +\longarg{force-cross-resource-refs}). + +A \idx{crossresourceref} is a reference from a recorded entry provided in one +\idx{resourceset} to an unrecorded entry in another \idx{resourceset}. +Since +the contents of each \idx{resourceset}['s] preamble must be +processed before fields can be interpreted and one +\idx{resourceset}['s] preamble may contain definitions that override +another, \idxpl{crossresourceref} can't be supported if fields +containing cross-referencing information need to be interpreted. + +The \idx{crossresourceref} mode determines whether or not \bibgls\ +can support \idxpl{crossresourceref}. If enabled, the message +\begin{verbatim} +Cross-resource references allowed. +\end{verbatim} +will be written to the transcript otherwise the message is +\begin{verbatim} +Cross-resource references disabled. +\end{verbatim} +The mode can only be enabled if the following condition is satisfied: +\begin{itemize} +\item the interpreter is off (\longarg{no-interpret}), or +\item every \idx{resourceset} either doesn't have a preamble +(\atentry{preamble}) or has \csopt[false]{interpret-preamble} set. +\end{itemize} +If you know the preamble contents won't cause a problem, you +can force the \idxpl{crossresourceref} mode on with +\longarg{force-cross-resource-refs}. + +If you don't use either \csopt[recorded and +deps]{selection} or \csopt[recorded and deps and see]{selection} +then the dependencies aren't picked up for that \idx{resourceset} +(and so can't be cross-referenced from another \idx{resourceset}). + +Trails don't work with \idxpl{crossresourceref}. For example, if +entry $A$ has been recorded and depends on entry $B$ that hasn't been +recorded, then $B$ can be picked up from a different +\idx{resourceset}, but if $A$ and $B$ are in the same +\idx{resourceset} and $B$ is dependent on $C$ which is in a +different \idx{resourceset} then $C$ won't be picked up if it hasn't +been recorded because $B$ hasn't been recorded and is in a different +\idx{resourceset}. + +If the \idx{crossresourceref} mode is enabled then stage~3 and +stage~4 are processed in separate loops, otherwise they are +processed in the same loop. + +\section{Indexing} + +The dual index entries such as \atentry{dualindexentry} (described in +\sectionref{sec:dualentry}) are designed to provide a way of +including an entry in a glossary (with a description) and also +include the term (without the description) in an index. Additional +terms that should only appear in the index can be defined with +\atentry{index}. (See, for example, the \exfile{sample-multi1.tex} +and \exfile{sample-multi2.tex} sample files.) + +Although \bibgls\ is designed to create indexes as well as glossary +lists using the same interface (\cs{gls} etc), it is +possible to have a mixture of \bibgls\ and \ics{index}. For example: +\begin{codeenv} +\cmd{documentclass}\marg{report} +\strut +\cmd{usepackage}\marg{makeidx} +\cmd{usepackage}\oarg{\styopt{record}}\marg{glossaries-extra} +\strut +\cmd{makeindex} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}} +\strut +\ics{glssetcategoryattribute}\marg{general}\marg{dualindex}\marg{true} +\cs{glssetcategoryattribute}\marg{symbol}\marg{dualindex}\marg{true} +\cs{glssetcategoryattribute}\marg{abbreviation}\marg{dualindex}\marg{true} +\strut +\cs{glssetcategoryattribute}\marg{general}\marg{indexname}\marg{hyperbf} +\cs{glssetcategoryattribute}\marg{symbol}\marg{indexname}\marg{hyperbf} +\cs{glssetcategoryattribute}\marg{abbreviation}\marg{indexname}\marg{hyperbf} +\strut +\cmd{begin}\marg{document} +\cmd{chapter}\marg{Example} +\cs{gls}\marg{bird}, \cs{gls}\marg{html}, \idx{mshiftchar}\cs{gls}\marg{v}\idx{mshiftchar} and \cs{glspl}\marg{goose}. +\strut +\cs{printunsrtglossaries} +\cmd{printindex} +\cmd{end}\marg{document} +\end{codeenv} +If the document is called \filefmt{myDoc.tex} then the document +build is: +\begin{verbatim} +pdflatex myDoc +bib2gls myDoc +pdflatex myDoc +makeindex myDoc.idx +pdflatex myDoc +\end{verbatim} +This requires an additional \LaTeX\ call between \bibgls\ and +\idx{makeindex} since the entries must be defined before they can be +indexed (and they can't be defined until \bibgls\ creates the +associated \ext{glstex} files). + +Note that this method will use the \field{sort} value obtained by \bibgls\ +as the \meta{sort} part within +\code{\cs{index}\marg{\meta{sort}@\meta{actual}}}. +Be careful if you use \idx{makeindex} as this can result in Unicode +characters appearing in the sort value, which \idx{makeindex} +doesn't support. +The \meta{actual} part is given by +\code{\ics{glsentryname}\margm{label}}. +(You can change the \meta{sort} and \meta{actual} parts by +redefining \ics{glsxtrautoindexassignsort} and +\ics{glsxtrautoindexentry}. See the \sty{glossaries-extra} manual +for further details.) + +\section{Security} + +\TeX\ Live come with security settings +\texmfcnf{openinany} and \texmfcnf{openoutany} that, respectively, +govern read and write file access (in addition to the operating +system's file permissions). \bibgls\ uses \idx{kpsewhich} to +determine these values and honours them. MikTeX doesn't use these +settings, so if these values are unset, \bibgls\ will default to +\code{a} (any) for \texmfcnf{openinany} and \code{p} (paranoid) for +\texmfcnf{openoutany}. + +The only external processes that are run by \bibgls\ are calls to +\idx{kpsewhich} to check the security settings and locate files on +\TeX's path. These are started with Java's \code{ProcessBuilder} +class so there should be no issues with spaces or shell special characters +in the argument. The \longarg{debug} switch will write the process +call in the transcript file and will delimit the argument in the log +with single quote characters for convenience, but the process isn't +actually called in that way. + +\bibgls\ creates files with the extension \ext{glstex}, which are +input by \gls{glsxtrresourcefile} (and therefore by the shortcut +\gls{GlsXtrLoadResources}). This extension is fixed and is imposed +by both \bibgls\ and \gls{glsxtrresourcefile}. \bibgls\ also creates +a transcript file with the default extension \ext{glg}. This may be +overridden by the \longarg{log-file} switch, but \bibgls\ always +forbids write access to any file with the following extensions: +\extfmt{tex}, \extfmt{ltx}, \extfmt{sty}, \extfmt{cls}, +\extfmt{bib}, \extfmt{dtx}, \extfmt{ins}, \extfmt{def} and +\extfmt{ldf}. + +\section{Localisation} +\label{sec:lang.xml} + +The messages produced by \bibgls\ are fetched from a resource file +called \metafilefmt{bib2gls-}{lang}{.xml}, where \meta{lang} is a +valid \idx{IETF} language tag. + +The appropriate file is searched for in the following order, where +\meta{locale} is the operating system's locale or the value supplied +by the \longarg{locale} switch: +\begin{enumerate} +\item \meta{lang} exactly matches \meta{locale}. +For example, my locale is \code{en-GB}, so \bibgls\ will first search +for \filefmt{bib2gls-en-GB.xml}. This file doesn't exist, so it will +try again. + +\item If \meta{locale} has an associated script, the +next try is with \meta{lang} set to \meta{lang +code}\code{-}\meta{script} where \meta{lang code} is the two +letter ISO language code and \meta{script} is the script code. +For example, if \meta{locale} is \code{sr-RS-Latn} +then \bibgls\ will search for \filefmt{bib2gls-sr-Latn.xml} if +\filefmt{bib2gls-sr-RS-Latn.xml} doesn't exist. + +\item The final attempt is with \meta{lang} set to just the two +letter ISO language code. For example, \filefmt{bib2gls-sr.xml}. +\end{enumerate} + +If there is no match, \bibgls\ will fallback on the English resource file +\file{bib2gls-en.xml}. +(Currently only \file{bib2gls-en.xml} exists as my language skills aren't up +to translating it. Any volunteers who want to provide other language +resource files would be much appreciated.) + +Note that if you use the \csopt[true]{loc-prefix} option, the +textual labels (\qt{Page} and \qt{Pages} in English) will be taken +from the resource file. In the event that the loaded resource file +doesn't match the document language, you will have to manually set +the correct translation (in English, this would be +\csopt[Page\dcomma Pages]{loc-prefix}). The default definition of +\gls!{bibglspassim} is also obtained from the resource file. + +\section{Conditional Document Build} + +If you are using a document build method that tries to determine +whether or not \bibgls\ should be run, you can find the information +by searching the \iext{aux} file for instances of +\nosecdef{glsxtr@resource} +Each instance corresponds to an instance of \gls{glsxtrresourcefile} +where \meta{filename} is the base name of the \iext{glstex} file +that \bibgls\ needs to create for this resource set. If the +\meta{options} part is missing the \csopt{src} option, then +\meta{filename} also indicates the base name for the \iext{bib} file. + +So the simplest check to determine if \bibgls\ needs to be run is to test +if the \iext{aux} file contains \gls{glsxtr@resource}. For +example, with \idx{arara} version 4.0: +\begin{codeenv} +\% arara: bib2gls if found("aux", "glsxtr@resource") +\end{codeenv} +A sophisticated method could check if +\meta{filename}\ext{glstex} is missing or is older than the document +\ext{tex} file for each instance of \gls{glsxtr@resource} found in +the \ext{aux} file. + +It might also be possible, although far more complex, to +parse the \meta{options} part in each instance of \gls{glsxtr@resource} +for \csopt{src} and determine if the corresponding \ext{bib} file or +files are newer than the \ext{tex} file. + +It's not possible to determine if the location lists require +updating, just as it's not possible to do this for the +\idx{toc}, list of figures, list of tables etc. (Or, if it could +be implemented, the required code would make the document build far +more complicated.) + +In general, the basic algorithm is: +\begin{enumerate} +\item Run \LaTeX\ (or PDF\LaTeX\ etc). + +\item If \gls{glsxtr@resource} is found in the \ext{aux} file then: + + \begin{enumerate} + \item run \bibgls; + \item run \LaTeX\ (or PDF\LaTeX\ etc). + \end{enumerate} + +\item If \ics{@istfilename} is found in the \ext{aux} file then: + + \begin{enumerate} + \item run \idx{makeglossaries} (or \idx{makeglossaries-lite}); + \item run \LaTeX\ (or PDF\LaTeX\ etc). + \end{enumerate} + +\end{enumerate} +This allows for the \styopt[alsoindex]{record} package option. See +also +\href{https://www.dickimaw-books.com/latex/buildglossaries}{\qt{Incorporating +\idx[hyper=false,noindex]{makeglossaries} or +\idx[hyper=false,noindex]{makeglossaries-lite} or \bibgls\ into +the document build}}~\cite{buildglossaries}. + +\section{Manual Installation} + +If you are unable to install \bibgls\ through your \TeX\ package +manager, you can install manually using the instructions below. +Replace \meta{TEXMF} with the path to your local or home TEXMF tree +(for example, \filefmt{\glstildechar/texmf}). + +Copy the files provided to the following locations: +\begin{itemize} +\item \meta{TEXMF}\filefmt{/scripts/bib2gls/bib2gls.jar} +(Java application.) +\item \meta{TEXMF}\filefmt{/scripts/bib2gls/convertgls2bib.jar} +(Java application.) +\item \meta{TEXMF}\filefmt{/scripts/bib2gls/texparserlib.jar} +(Java library.) +\item \meta{TEXMF}\filefmt{/scripts/bib2gls/resources/bib2gls-en.xml} +(English resource file.) +\item \meta{TEXMF}\filefmt{/doc/support/bib2gls/bib2gls.pdf} +(This document.) +\item \meta{TEXMF}\filefmt{/doc/support/bib2gls/bib2gls-begin.pdf} +(Introductory guide.) +\end{itemize} +If you use the Unix \appfmt{man} command, copy the +\filefmt{bib2gls.1} and \filefmt{convertgls2bib.1} files to the +appropriate location. + +If you are using a Unix-like system, there are also bash scripts +provided called \file{bib2gls.sh} and \file{convertgls2bib.sh}. +Either copy then directly to somewhere on your path without the \iext{sh} +extension, for example: +\begin{verbatim} +cp bib2gls.sh ~/bin/bib2gls +cp convertgls2bib.sh ~/bin/convertgls2bib +\end{verbatim} +or copy the files to +\meta{TEXMF}\filefmt{/scripts/bib2gls/} and create a +symbolic link to them called just \filefmt{bib2gls} and +\filefmt{convertgls2bib} from somewhere on +your path, for example: +\begin{verbatim} +cp bib2gls.sh ~/texmf/scripts/bib2gls/ +cp convertgls2bib.sh ~/texmf/scripts/bib2gls/ +cd ~/bin +ln -s ~/texmf/scripts/bib2gls/bib2gls.sh bib2gls +ln -s ~/texmf/scripts/bib2gls/convertgls2bib.sh convertgls2bib +\end{verbatim} +The \file{texparserlib.jar} file isn't an application but is a +library used by both \file{bib2gls.jar} and +\file{convertgls2bib.jar}, and so needs to be in the same class path. +(The library is in a separate +\href{https://github.com/nlct/texparser}{GitHub +repository}~\cite{texparser} as it's +also used by some of my other applications.) + +Windows users can create a \iext{bat} file that works in a +similar way to the bash scripts. To do this, create a file called +\file{bib2gls.bat} that contains the following: +\begin{verbatim} +@ECHO OFF +FOR /F "tokens=*" %%I IN ('kpsewhich --progname=bib2gls --format=texmfscripts +bib2gls.jar') DO SET JARPATH=%%I +java -Djava.locale.providers=CLDR,JRE -jar "%JARPATH%" %* +\end{verbatim} +Save this file to somewhere on your system's path. +(Similarly for \filefmt{convertgls2bib}.) Note that \TeX\ +distributions for Windows usually convert \iext{jar} files to +executables. + +You may need to refresh \TeX's database to ensure that +\idx{kpsewhich} can find the \iext{jar} files. +To test that the application has been successfully installed, open a +command prompt or terminal and run the following command: +\begin{verbatim} +bib2gls --version +convertgls2bib --version +\end{verbatim} +This should display the version information for both applications. + +\chapter{\texorpdfstring{\TeX}{TeX}\ Parser Library} +\label{sec:texparserlib} + +The \bibgls\ application requires the \TeX\ Parser Library +\file{texparserlib.jar}\footnote{\url{https://github.com/nlct/texparser}} +which is used to parse the \iext{aux} and \iext{bib} files. + +With the \longarg{interpret} switch on (default), this library is +also used to interpret the sort value when it contains a backslash +\idx{escchar} or a tilde \idx{nbspchar} or a dollar symbol +\idx{mshiftchar} or braces \idx{bgroupchar} \idx{egroupchar} +(and when the \csopt{sort} option is not +\optfmt{unsrt} or \optfmt{none} or \optfmt{use}).\footnote{The other +special characters are omitted from the check: the comment symbol +\idx{commentchar} is best avoided in field values, the subscript and +superscript characters \idx{sbchar} and \idx{spchar} should +either be encapsulated by \idx{mshiftchar} or by \cs{ensuremath}, which +will be picked up by the check for \idx{mshiftchar} or +\idx{escchar}, and the other special characters would +indicate something too complex for the interpreter to handle.} + +The other cases that the interpreter is used for are: +\begin{itemize} +\item when \csopt{set-widest} is used to determine the width of +the \field{name} field; +\item if \csopt{labelify} or \csopt{labelify-list} are set the +identified field values are first interpreted (if they contain +\idx{escchar} \idx{bgroupchar} \idx{egroupchar} +\idx{nbspchar} or \idx{mshiftchar}) before being converted to labels; +\item if \csopt[true]{interpret-label-fields} is set and the +\field{parent}, \field{category}, \field{type}, \field{group}, +\field{seealso} or \field{alias} fields contain \idx{escchar} +or \idx{bgroupchar} or \idx{egroupchar} the interpreter is used +since these fields must be just a label +(other special characters aren't checked as they won't expand to +characters allowed in a label). +\end{itemize} + +Information in the \ext{aux} file is parsed for specific commands +but the arguments of those commands are not interpreted so, for +example, UTF-8 characters that occur in any resource options will +need to be detokenized when using \sty{inputenc} to prevent +expansion when they are written to the \ext{aux} file. (In some +options, such as \csopt{sort-rule}, you can use \cs{glshex}\meta{hex} +syntax to specify a UTF-8 character.) + +The \longarg{no-interpret} switch will turn off the interpreter, but +the library will still be used to parse the \ext{aux} and \ext{bib} +files. Note that the \field{see} field doesn't use the interpreter +with \csopt[true]{interpret-label-fields} as +it may legitimately contain \LaTeX\ code in the optional tag part +(such as \cs{seealsoname}). + +The parser has a different concept of expansion to \TeX\ +and will expand some things that aren't expanded by \LaTeX\ +(such as \ics{MakeUppercase} and \ics{char}) and won't expand other commands +that would be expanded by \LaTeX\ (such as commands defined +in terms of complicated internals). + +If you get a \idx{StackOverflowError} while a field is being +interpreted (with a long stack trace that contains repeated file names and +line numbers) then it's likely you have an infinite loop. For +example, this can be triggered if a field contains \csfmt{foo} that +has been defined as: +\begin{codeenv} +\cs{def}\cmd{foo}\marg{\cmd{foo}} +\end{codeenv} +This will obviously also cause an error in the \LaTeX\ document as +well (unless the document has a different definition that doesn't +have this unbounded recursion). + +The \file{texparserlib.jar} library is not a \TeX\ engine and there +are plenty of situations where it doesn't work. In particular, in +this case it's being used in a fragmented context without knowing +most of the packages used by the document or any custom commands or +environments provided within the document. + +\bibgls\ can detect from the log file a small +number of packages that the parser recognises. Note that in +some cases there's only very limited support. For example, +\isty{siunitx}'s \ics{si} command is recognised but other +commands from that package aren't. See +\longargpageref{list-known-packages} for further details. + +Since the parser doesn't have a full set of commands available +within the \LaTeX\ document, when it encounters \ics{renewcommand} it +won't check if the command is undefined. If the command isn't +defined, it will simply behave like \cs{newcommand}. Whereas +with \ics{providecommand} the parser will only define the command +if it's unrecognised. + +The interpreter has its own internal implementation of the +glossary-related commands listed in \tableref{tab:bibglsdefs}. These +may be overridden by custom packages provided with the +\longarg{custom-packages} switch. Note that commands that reference +an entry, such as \cs{glsentryname}, aren't guaranteed to work +across \idxpl{resourceset} and will only be able to look up field +values that are known to \bibgls. (For example, the \field{name} +field for abbreviations is typically set by the associated +abbreviation style, which isn't available to \bibgls.) + +\begin{table}[htbp] +\caption{Glossary-Related Commands Implemented by the \bibgls\ Interpreter} +\label{tab:bibglsdefs} +\setlength{\tabcolsep}{4pt}% +\centering +\tablelistcs{3}{glsxtrprovidecommand,bibglsuppercase,bibglslowercase,bibglsfirstuc,% +bibglstitlecase,GlsXtrEnableInitialTagging,bibglscontributorlist,% +bibglshyperlink,glshyperlink,bibglscontributor,bibglsdatetime,% +bibglsdate,bibglstime,glsentryname,glsentrytext,glsentryshort,% +glsentrylong,glsentryfirst,glsentrysymbol,glsentryuseri,% +glsentryuserii,glsentryuseriii,glsentryuseriv,glsentryuserv,% +glsentryuservi,glsentryplural,glsentryfirstplural,glsentryshortpl,% +glsentrylongpl,glsentrysymbolplural,Glsentryname,Glsentrytext,% +Glsentryshort,Glsentrylong,Glsentryfirst,Glsentrysymbol,% +Glsentryuseri,Glsentryuserii,Glsentryuseriii,Glsentryuseriv,% +Glsentryuserv,Glsentryuservi,Glsentryplural,Glsentryfirstplural,Glsentryshortpl,% +Glsentrylongpl,Glsentrysymbolplural,bibglshashchar,bibglsunderscorechar,% +bibglsdollarchar,bibglsampersandchar,bibglscircumchar,glsbackslash,glstildechar,glsopenbrace,glsclosebrace,glspercentchar,% +glsxtrusefield,Glsxtrusefield,GLSxtrusefield,glsentrytitlecase,% +glsxtrhiernamesep,glsxtrhiername,Glsxtrhiername,GlsXtrhiername,% +GLSxtrhiername,GLSXTRhiername} +\end{table} + +If a command isn't recognised, you can provide it in the +\atentry{preamble} and use \ics{char} to map a symbol to the most +appropriate Unicode character. For example, suppose your document +loads a package that provides symbols for use on maps, such as +\csfmt{Harbour}, \csfmt{Battlefield} and \csfmt{Stadium}, then you +can provide versions of these commands just for \bibgls's +use:\footnote{These commands won't work with PDF\LaTeX, as the +\cs{char} values are too large, but they're fine for \bibgls.} +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{Harbour}}\marg{\charhex{2693}} +\cs{providecommand}\marg{\cmd{Battlefield}}\marg{\charhex{2694}} +\cs{providecommand}\marg{\cmd{Stadium}}\marg{\charhex{26BD}}}} +\end{codeenv} +Since these use \cs{providecommand}, they won't overwrite the +document's version (provided these commands have been defined before +\gls!{GlsXtrLoadResources}). Alternatively, you can instruct \bibgls\ +to not write the \atentry{preamble} contents to the resource file +using \csopt[false]{write-preamble}. Now you can either sort these +symbols by +their Unicode values (\csopt[letter-case]{sort}) or provide a custom +rule that recognises these Unicode characters (for example, +\csopt[custom]{sort}, +\csopt[\cs{glshex}2694 \string< \cs{glshex}2693 \string< \cs{glshex}26BD]{sort-rule}). + +\TeX\ syntax can be quite complicated and, in some cases, far too +complicated for simple \idxpl!{regex}. The \TeX\ parser library performs +better than a simple pattern match, and that's the purpose of +\file{texparserlib.jar} and why it's used by \bibgls\ (and by +\idx{convertgls2bib}). When the \longarg{debug} mode is on, any +warnings or errors triggered by the interpreter will be written to +the transcript prefixed with \code{texparserlib:} (the results of +the conversions will be included in the transcript as informational +messages prefixed with \code{texparserlib:} even with +\longarg{no-debug}). + +For example, suppose the \ext{bib} file includes: +\begin{codeenv} +\atentry{preamble}\marg{ +\qtdelim{\cs{providecommand}\marg{\cmd{mtx}}[1]\marg{\cs{boldsymbol}\marg{\idx{param}1}} +\cs{providecommand}\marg{\cmd{set}}[1]\marg{\ics{mathcal}\marg{\idx{param}1}} +\cs{providecommand}\marg{\cmd{card}}[1]\marg{|\cmd{set}\marg{\idx{param}1}|} +\cs{providecommand}\marg{\cmd{imaginary}}\marg{i}}} +\strut +\atentry{entry}\marg{M, + \field{name}=\marg{\marg{}\idx{mshiftchar}\cmd{mtx}\marg{M}\idx{mshiftchar}}, + \field{text}=\marg{\cmd{mtx}\marg{M}}, + \field{description}=\marg{a matrix} +} +\strut +\atentry{entry}\marg{v, + \field{name}=\marg{\marg{}\idx{mshiftchar}\cs{vec}\marg{v}\idx{mshiftchar}}, + \field{text}=\marg{\cs{vec}\marg{v}}, + \field{description}=\marg{a vector} +} +\strut +\atentry{entry}\marg{S, + \field{name}=\marg{\marg{}\idx{mshiftchar}\cmd{set}\marg{S}\idx{mshiftchar}}, + \field{text}=\marg{\cmd{set}\marg{S}}, + \field{description}=\marg{a set} +} +\strut +\atentry{entry}\marg{card, + \field{name}=\marg{\marg{}\idx{mshiftchar}\cmd{card}\marg{S}\idx{mshiftchar}}, + \field{text}=\marg{\cmd{card}\marg{S}}, + \field{description}=\marg{the cardinality of the set \idx{mshiftchar}\cmd{set}\marg{S}\idx{mshiftchar}} +} +\strut +\atentry{entry}\marg{i, + \field{name}=\marg{\marg{}\idx{mshiftchar}\cmd{imaginary}\idx{mshiftchar}}, + \field{text}=\marg{\cmd{imaginary}}, + \field{description}=\marg{square root of minus one (\idx{mshiftchar}\cmd{sqrt}\marg{-1}\idx{mshiftchar})} +} +\end{codeenv} +(The empty group at the start of the \field{name} fields +protects against the possibility that the \catattr{glossname} +category attribute might be set to \optfmt{firstuc}, which +automatically converts the first letter of the name to +\idx{uppercase} when displaying the glossary. See also +\longarg{mfirstuc-protection} and +\longarg{mfirstuc-math-protection}.) + +None of these entries have a \field{sort} field so the \field{name} +is used. If the entry type had been \atentry{symbol} instead, +the fallback would be the entry's label. +This means that with \atentry{symbol} instead of \atentry{entry}, and the default +\csopt[sort]{sort-field}, and with +\csopt[letter-case]{sort}, these entries will be defined in +the order: \code{M}, \code{S}, \code{card}, \code{i}, \code{v} (since +this is the case-sensitive letter order of the labels) whereas +with \csopt[letter-nocase]{sort-field}, the order will be: +\code{card}, \code{i}, \code{M}, \code{S}, \code{v} (since this +is the case-insensitive letter order of the labels). + +However, with \atentry{entry}, the fallback field will be taken from +the \field{name} which in the above example contains \TeX\ code, so +\bibgls\ will use \file{texparserlib.jar} to interpret this code. +The library has several different ways of writing the processed +code. For simplicity, \bibgls\ uses the library's HTML output and +then strips the HTML markup and trims any leading or trailing +spaces. The library method that writes \idx{non-ASCII} characters +using \qtt{\&x\meta{hex};} markup is overridden by \bibgls\ to just +write the actual Unicode character, which means that the letter-based +sorting options will sort according to the integer value \meta{hex} +rather than the string \qtt{\&x\meta{hex};}. + +The interpreter is first passed the code provided with +\atentry{preamble}: +\begin{codeenv} +\cs{providecommand}\marg{\cmd{mtx}}[1]\marg{\cs{boldsymbol}\marg{\idx{param}1}} +\cs{providecommand}\marg{\cmd{set}}[1]\marg{\cs{mathcal}\marg{\idx{param}1}} +\cs{providecommand}\marg{\cmd{card}}[1]\marg{|\cmd{set}\marg{\idx{param}1}|} +\cs{providecommand}\marg{\cmd{imaginary}}\marg{i} +\end{codeenv} +(unless \csopt[false]{interpret-preamble}). +This means that the provided commands are now recognised by the +interpreter when it has to parse the fields later. + +In the case of the \code{M} entry in the example above, the +code that's passed to the interpreter is: +\begin{verbatim} +{}$\mtx{M}$ +\end{verbatim} +The transcript (\iext{glg}) file will show the results of the +conversion: +\begin{verbatim} +texparserlib: {}$\mtx{M}$ -> M +\end{verbatim} +So the \field{sort} value for this entry is set to \qtt{M}. The font +change (caused by math-mode and \ics{boldsymbol}) has been +ignored. The sort value therefore consists of a single Unicode +character \hex{4D} (Latin \idx!{uppercase} letter \qtt{M}, decimal value 77). + +For the \code{v} entry, the code is: +\begin{verbatim} +{}$\vec{v}$ +\end{verbatim} +The transcript shows: +\begin{alltt} +texparserlib: \marg{}\$\ics{vec}\marg{v}\$ -> \usebox\varrow +\end{alltt} +So the \field{sort} value for this entry is set to \qtt{\usebox\varrow}, +which consists of two Unicode characters \hex{76} +(Latin \idx!{lowercase} letter \qtt{v}, decimal value 118) and +\hex{20D7} (combining right arrow above, decimal value 8407). + +For the \code{set} entry, the code is: +\begin{verbatim} +{}$\set{S}$ +\end{verbatim} +The transcript shows: +\begin{verbatim} +texparserlib: {}$\set{S}$ -> S +\end{verbatim} +So the \field{sort} value for this entry is set to \qtt{S} (again +ignoring the font change). This consists of a single Unicode +character \hex{53} (Latin \idx!{uppercase} letter \qtt{S}, decimal value~83). + +For the \code{card} entry, the code is: +\begin{verbatim} +{}$\card{S}$ +\end{verbatim} +The transcript shows: +\begin{verbatim} +texparserlib: {}$\card{S}$ -> |S| +\end{verbatim} +So the \field{sort} value for this entry is set to \qtt{|S|} +(the \textbar\ characters from the definition of \csfmt{card} provided +in \atentry{preamble} have been included, but the +font change has been discarded). In this case the sort value +consists of three Unicode characters \hex{7C} (vertical line, decimal +value 124), +\hex{53} (Latin \idx!{uppercase} letter \qtt{S}, decimal value 83) and +\hex{7C} again. +If \csopt[false]{interpret-preamble} had been used, \csfmt{card} +wouldn't be recognised and would be discarded leaving just \qtt{S} +as the sort value. + +(Note that if \ics{vert} is used instead of \textbar\ then it would +be converted into the mathematical operator \hex{2223} and result in +a different order.) + +For the \code{i} entry, the code is: +\begin{verbatim} +{}$\imaginary$ +\end{verbatim} +The transcript shows: +\begin{verbatim} +texparserlib: {}$\imaginary$ -> i +\end{verbatim} +So the \field{sort} value for this entry is set to \qtt{i}. +If \csopt[false]{interpret-preamble} had been used, \csfmt{imaginary} +wouldn't be recognised and would be discarded, leaving an empty sort +value. + +This means that in the case of the default \csopt[sort]{sort-field} with +\csopt[letter-case]{sort}, these entries will be defined in +the order: \code{M} ($\mtx{M}$), \code{S} ($\set{S}$), +\code{i} ($\imaginary$), \code{v} ($\vec{v}$) and +\code{card} ($\card{S}$). +In this case, the entries have been sorted according to +the character codes. If you run \bibgls\ with \longarg{verbose} +the decimal character codes will be included in the transcript. +For this example: +\begin{alltt} +i -> 'i' [105] +card -> '|S|' [124 83 124] +M -> 'M' [77] +S -> 'S' [83] +v -> '\usebox\varrow' [118 8407] +\end{alltt} + +The \longarg{group} option (in addition to \longarg{verbose}) +will place the letter group in +parentheses before the character code list: +\begin{alltt} +i -> 'i' (i) [105] +card -> '|S|' [124 83 124] +M -> 'M' (M) [77] +S -> 'S' (S) [83] +v -> '\usebox\varrow' (v) [118 8407] +\end{alltt} +(Note that the \code{card} entry doesn't have a letter +group since the vertical bar character isn't considered a +letter.) + +If \csopt[letter-nocase]{sort} is used instead then, after conversion +by the interpreter, the sort values will all be changed to +\idx{lowercase}. The order is now: \code{i} ($\imaginary$), +\code{M} ($\mtx{M}$), \code{S} ($\set{S}$), +\code{v} ($\vec{v}$) and \code{card} ($\card{S}$). +The transcript (with \longarg{verbose}) now shows +\begin{alltt} +i -> 'i' [105] +card -> '|s|' [124 115 124] +M -> 'm' [109] +S -> 's' [115] +v -> '\usebox\varrow' [118 8407] +\end{alltt} +With \longarg{group} (in addition to \longarg{verbose}) +the letter groups are again included: +\begin{alltt} +i -> 'i' (I) [105] +card -> '|s|' [124 115 124] +M -> 'm' (M) [109] +S -> 's' (S) [115] +v -> '\usebox\varrow' (V) [118 8407] +\end{alltt} +Note that the letter groups are \idx{uppercase} not \idx{lowercase}. +Again the \code{card} entry doesn't have an associated +letter group. + +If a locale-based sort is used, the ordering will follow the +locale's alphabet rules. For example, with \csopt[en]{sort} +(English, no region or variant), the order becomes: +\code{card} ($\card{S}$), \code{i} ($\imaginary$), +\code{M} ($\mtx{M}$), \code{S} ($\set{S}$) and +\code{v} ($\vec{v}$). The transcript (with \longarg{verbose}) +shows the collation keys instead: +\begin{alltt} +i -> 'i' [0 92 0 0 0 0] +card -> '|S|' [0 66 0 102 0 66 0 0 0 0] +M -> 'M' [0 96 0 0 0 0] +S -> 'S' [0 102 0 0 0 0] +v -> '\usebox\varrow' [0 105 0 0 0 0] +\end{alltt} +Again the addition of the \longarg{group} switch will show +the letter groups.\footnote{For more information on collation keys see the +\href{http://docs.oracle.com/javase/8/docs/api/java/text/CollationKey.html}{CollationKey} +class in Java's API~\cite{collationkey}.} + +Suppose I add a new symbol to my \ext{bib} file: +\begin{codeenv} +\atentry{symbol}\marg{angstrom, + \field{name}=\marg{\ics{AA}}, + \field{description}=\marg{\cs{AA} ngstr\ics{umlaut}om} +} +\end{codeenv} +and I also use this entry in the document.\footnote{A better method +is to use \sty{siunitx} instead.} Then with +\csopt[en]{sort}, the order is: \code{card} ($\card{S}$), +\code{angstrom} (\AA), \code{i} ($\imaginary$), \code{M} +($\mtx{M}$), \code{S} ($\set{S}$), and \code{v} ($\vec{v}$). +The \longarg{group} switch shows that the \code{angstrom} entry +(\AA) has been placed in the \qt{A} letter group. + +However, if I change the locale to \csopt[sv]{sort}, the +\code{angstrom} entry is moved to the end of the list and the +\longarg{group} switch shows that it's been placed in the \qt{\AA} +letter group. + +\label{locale.provider}If you are using Java~8, you can set the +\code{java.locale.providers} property~\cite{javacldr} to use +the \idx{CLDR} \idx{localeprovider}, which has more extensive +support for locales than the native \idx{JRE}. For example: +\begin{verbatim} +java.locale.providers=CLDR,JRE +\end{verbatim} +This should be enabled by default for Java~9. The property +can either be set in a script that runs \bibgls, for example, +\begin{verbatim} +java -Djava.locale.providers=CLDR,JRE,SPI -jar "$jarpath" "$@" +\end{verbatim} +(where \verb|$jarpath| is the path to the \file{bib2gls.jar} +file and \verb|"$@"| is the argument list) or you can set the +property as the default for all Java applications by adding +the definition to the \code{JAVA\_TOOL\_OPTIONS} environment +variable~\cite{javaoptions}. +For example, in a bash shell: +\begin{verbatim} +export JAVA_TOOL_OPTIONS='-Djava.locale.providers=CLDR,JRE,SPI' +\end{verbatim} +or in Windows: +\begin{verbatim} +set JAVA_TOOL_OPTIONS=-Djava.locale.providers=CLDR,JRE,SPI +\end{verbatim} + +\chapter{Command Line Options} +\label{sec:switches} +\setsecdepth{0} + +The syntax of \bibgls\ is: +\begin{alltt} +bib2gls \oargm{options} \meta{filename} +\end{alltt} +where \meta{filename} is the name of the \ext{aux} file. (The +extension may be omitted.) Only one \meta{filename} is permitted. +Available options are listed below. + +\argsection{help} + +Display the help message and quit. + +\argsection{version} + +Display the version information and quit. + +\argsection{debug} + +Switch on debugging mode. If \meta{n} is present, it must be a +non-negative integer indicating the debugging level. If omitted 1 is +assumed. This option also switches on the verbose mode. A value of 0 +is equivalent to \longargfmt{no-debug}. + +\argsection{no-debug} + +Switches off the debugging mode. + +\argsection{verbose} + +Switches on the verbose mode. This writes extra information to the +terminal and transcript file. + +\argsection{no-verbose} + +Switches off the verbose mode. This is the default behaviour. +Some messages are written to the terminal. To completely suppress +all messages (except errors), switch on the silent mode. +For additional information messages, switch on the verbose mode. + +\argsection{silent} + +Suppresses all messages except for errors that would normally be +written to the terminal. Warnings and informational messages are +written to the transcript file, which can be inspected afterwards. + +\argsection{locale} + +Specify the preferred \langxml, where \meta{lang} is a valid \idx{IETF} language tag. +This option requires an appropriate \metafilefmt{bib2gls-}{lang}{.xml} +resource file otherwise \bibgls\ will fallback on English. +This also sets the default document locale when \csopt[doc]{sort} is +used and the document doesn't have any language support. +Note that \csopt[locale]{sort} uses the \idx{JVM}['s] default +locale and is not governed by this switch. + +If a document doesn't have any locale support or has support +for more than one language then it's best to explicitly set +the required locale in the appropriate \idx{resourceset}. + +\argsection{log-file} + +Sets the name of the transcript file. By default, the name is the +same as the \iext{aux} file but with a \iext{glg} extension. Note that +if you use \bibgls\ in combination with \idx{xindy} or +\idx{makeindex}, you will need to change the transcript file name to +prevent conflict. + +\argsection{dir} + +By default \bibgls\ assumes that the output files should be written +in the current working directory. The input \iext{bib} files are assumed to be +either in the current working directory or on \TeX's path (in which +case \idx{kpsewhich} will be used to find them). + +If your \iext{aux} file isn't in the current working directory (for +example, you have run \TeX\ with \shortargfmt{output-directory}) +then you need to take care how you invoke \bibgls. + +Suppose I have a file called \filefmt{test-entries.bib} that +contains my entry definitions and a document called +\filefmt{mydoc.tex} that selects the \ext{bib} file using: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[test-entries]{src}} +\end{codeenv} +(\filefmt{test-entries.bib} is in the same directory as +\filefmt{mydoc.tex}). +If I compile this document using +\begin{verbatim} +pdflatex -output-directory tmp mydoc +\end{verbatim} +then the auxiliary file \filefmt{mydoc.aux} will be written to the +\filefmt{tmp} sub-directory. The resource information is listed in +the \ext{aux} file as +\begin{codeenv} +\gls{glsxtr@resource}\marg{\csopt[test-entries]{src}}\marg{mydoc} +\end{codeenv} +If I run \bibgls\ from the \filefmt{tmp} directory, then it won't +be able to find the \filefmt{test-entries.bib} file (since it's in +the parent directory). + +If I run \bibgls\ from the same directory as \filefmt{mydoc.tex} +using +\begin{verbatim} +bib2gls tmp/mydoc +\end{verbatim} +then the \ext{aux} file is found and the transcript file is +\filefmt{tmp/mydoc.glg} (since the default path name is the same as the +\ext{aux} file but with the extension changed to \iext{glg}) but the +output file \filefmt{mydoc.glstex} will be written to the current +directory. + +This works fine from \TeX's point of view as it can find the +\iext{glstex} file, but it may be that you'd rather the \ext{glstex} +file was tidied away into the \filefmt{tmp} directory along with all +the other files. In this case you need to invoke \bibgls\ with the +\longargorshort{dir} option: +\begin{verbatim} +bib2gls -d tmp mydoc +\end{verbatim} + +\argsection{interpret} + +Switch on the interpreter mode (default). See \sectionref{sec:texparserlib} +for more details. + +\argsection{no-interpret} + +Switch off the interpreter mode. See \sectionref{sec:texparserlib} +for more details about the interpreter. + +\argsection{no-break-space} + +The interpreter treats a tilde character \idx{nbspchar} as a non-breakable +space (default). + +\argsection{break-space} + +The interpreter treats a tilde character \idx{nbspchar} as a normal +space. + +\argsection{cite-as-record} + +Treat instances of \code{\ics{citation}\margm{label}} found in the +\ext{aux} file as though it was actually an \idx{ignoredrecord}: +\begin{codeenv} +\gls{glsxtr@record}\margm{label}\marg{}\marg{\counter{page}}\marg{\encap{glsignore}}\marg{} +\end{codeenv} +Note that \code{\cs{citation}\marg{*}} will always be skipped. Use +\csopt[all]{selection} to select all entries. +This switch is most useful in conjunction with +\atentrypageref{bibtexentry}. + +\argsection{no-cite-as-record} + +Don't check for instances of \ics{citation} in the \ext{aux} file +(default). + +\argsection{warn-non-bib-fields} + +If any internal fields are found in the \ext{bib} file, this setting +will issue a warning as their use can cause unexpected results. +The fields checked for are those listed in Tables~\ref{tab:internalfields} +and \ref{tab:baseinternalfields} with a few exceptions, notably +\field{type} and \field{sort}. Ideally you shouldn't need to use +\field{sort} as there should be an appropriate fallback set up to +use if \field{sort} isn't set, such as the label for symbols or the +name for terms or the short form for abbreviations. + +This is the default setting and was added as some users were +confused over which fields could be used in the \ext{bib} file. +The use of these fields can break \bibgls's normal behaviour and +cause unexpected results. + +The check is performed before field aliasing, so it's possible to +alias a field to an internal field, such as \field{group}, without +triggering this warning. If you do this you need to make sure you +have taken appropriate precautions to avoid unexpected results. + +\argsection{no-warn-non-bib-fields} + +Switches off the check for non-bib fields. If you use this option +you need to make sure you have taken appropriate precautions to +avoid unexpected results. + +\argsection{warn-unknown-entry-types} + +If any unknown entry types are found in the \ext{bib} file, \bibgls\ +will issue a warning with this option set (default). + +\argsection{no-warn-unknown-entry-types} + +This option will suppress the warning if an unknown entry types are +found in the \ext{bib} file. + +\argsection{merge-wrglossary-records} + +For use with the \styopt{indexcounter} package option +(\styfmt{glossaries-extra} v1.29+), this switch merges an entry's +\counter{wrglossary} records for the same page location. This is the +default setting. (See also \csopt{save-index-counter}.) + +\argsection{no-merge-wrglossary-records} + +Don't merge an entry's \counter{wrglossary} records. This means that you +may end up with duplicate page numbers in the entry's location list, +but they will link to different parts of the page. + +\argsection{merge-nameref-on} + +The \styopt[nameref]{record} package option (introduced to +\sty{glossaries-extra} version 1.37) provides extra information +in the record when indexing, obtained from \ics{@currentlabelname}, +\ics{@currentHref} and \ics{theHentrycounter}. Instead of writing the record as: +\begin{codeenv} +\format{glsxtr@record} +\end{codeenv} +the record is written as: +\nosecdef{glsxtr@record@nameref} +If \isty{hyperref} hasn't been loaded \meta{title} and \meta{href} +will always be empty. The most reliable target is given by +\code{\meta{counter}.\meta{hcounter}}, where \meta{counter} is the +associated counter name and \meta{hcounter} is +obtained from \cs{theHentrycounter}, which is set to the hyper +target command \csfmt{theH}\meta{counter} during indexing. Since +this information can't be included in the location when indexing +with \idx!{makeindex} or \idx!{xindy}, the base \sty{glossaries} +package tries to obtain a prefix from which the target name can be +formed. This doesn't work if \csfmt{theH}\meta{counter} can't be +formed from \meta{prefix}\csfmt{the}\meta{counter}, which results in +broken links. Since \bibgls\ doesn't have the same restrictions, the +actual target can be included in the record. You can then customize +the document to choose whether to use \meta{href} (to link to the +nearest anchor) or \meta{hcounter} to link to the place where the +indexing counter was incremented. + +The \code{nameref} record will be written to the \idx{locationlist} using: +\nosecdef{glsxtrdisplaylocnameref} +The \meta{file} part will be empty for normal internal locations, +and will be set to the corresponding file name for supplemental +locations. + +With \sty{hyperref}, \meta{title} is initially empty. The \meta{href} will be +\code{Doc-Start} at the start of the document and is updated +globally on every instance of \ics{refstepcounter}. The +\meta{title} is updated locally by certain commands, such as +\ics{section} or \ics{caption}. This means that the \meta{href} +may not always correspond to the \meta{title}, so using +the \styopt[nameref]{record} package option can have unpredictable +results if the \meta{title} is used as link text with \meta{href} as +the target. + +For compactness, \bibgls\ tries to merge duplicate or near +duplicate records. There are four possible rules that it will +use for \code{nameref} records, identified by \meta{rule} in the +\longarg{merge-nameref-on} switch: +\begin{itemize} +\item \optfmt{location}: merge records that match on the +\meta{prefix}, \meta{counter} and \meta{location} parts (as regular +records); +\item \optfmt{title}: merge records that match on the \meta{counter} +and \meta{title} parts; +\item \optfmt{href}: merge records that match on the \meta{counter} +and \meta{href} parts; +\item \optfmt{hcounter}: merge records that match on the \meta{counter} +and \meta{hcounter} parts. +\end{itemize} +The default \meta{rule} is \optfmt{hcounter}. Note that for all +rules the \meta{counter} must match. See the \qt{Nameref Record} +section of the \sty{glossaries-extra} user manual for further +details. + +\argsection{force-cross-resource-refs} + +Force \idx{crossresourceref} mode on (see +\sectionref{sec:resourcesets}). + +\argsection{no-force-cross-resource-refs} + +Don't force \idx{crossresourceref} mode on (default). +The mode will be enabled if applicable (see +\sectionref{sec:resourcesets}). + +\argsection{support-unicode-script} + +Text superscript (\ics{textsuperscript}) and subscript +(\ics{textsubscript}) will use Unicode super/subscript characters +if available (default). For example, +\begin{codeenv} +\cs{textsuperscript}\marg{(2)} +\end{codeenv} +will be converted to \code{\textsuperscript{(2)}}, which consists +of: \hex{207D} (superscript left parenthesis) +\hex{00B2} (superscript two) \hex{207E} (superscript right +parenthesis). If the entire contents of the argument can't be +represented by Unicode characters, the interpreter uses \verb|<sup>| +and \verb|<sub>| markup, which is then stripped by \bibgls. For +example, +\begin{codeenv} +\cs{textsuperscript}\marg{(2,3)} +\end{codeenv} +will be converted to +\begin{verbatim} +<sup>(2,3)</sup> +\end{verbatim} +(since there's no superscript comma). The markup is stripped leaving +just \code{(2,3)}. + +Superscripts and subscripts in maths mode always use markup +regardless of this setting. Some supported packages that use +\idx{spchar} or \idx{sbchar} as shortcuts within an encapsulating +command may internally use the same code as \cs{textsuperscript} and +\cs{textsubscript}, in which case they will be sensitive to this +setting. + +\argsection{no-support-unicode-script} + +Text superscript (\cs{textsuperscript}) and subscript +(\cs{textsubscript}) won't use Unicode super/subscript characters. +Note that if other commands are provided that expand to Unicode +superscript or subscript characters, then they won't be affected by +this setting. For example, if \csfmt{superiortwo} is defined as +\begin{codeenv} +\cs{providecommand}\marg{\cmd{superiortwo}}\marg{\charhex{B2}} +\end{codeenv} +then it will be interpreted as \hex{00B2} (superscript two) even if +this setting is on. + +\argsection{list-known-packages} + +This option will list all the packages supported by the \TeX\ parser +library and will then exit \bibgls. The results are divided into two +sections: those packages that are searched for in the \iext{log} +file and those packages that aren't searched for in the \iext{log} +file but have some support available. Some of the support is very +limited. Package options aren't detected. +The transcript file is always searched for \isty{glossaries-extra} +to ensure that the version is new enough to support \bibgls. + +Packages that fall into the first category are: +\isty{amsmath}, \isty{amssymb}, \isty{bpchem}, \isty{fontenc}, +\isty{fontspec}, \isty{fourier}, +\isty{hyperref}, \isty{lipsum}, \isty{MnSymbol}, \isty{mhchem}, \isty{natbib}, +\isty{pifont}, \isty{siunitx} (limited), \isty{stix}, +\isty{textcase}, \isty{textcomp}, \isty{tipa}, \isty{upgreek} and +\isty{wasysym}. (You can omit checking for specific packages with +\longarg{ignore-packages}.) These are packages that provide commands +that might be needed within entry fields. The check for +\isty{fontspec} is to simply determine whether or not UTF-8 +characters are allowed in labels (for \csopt{labelify} and +\csopt{labelify-list}). + +Packages that fall into the second category are: +\isty{booktabs}, \isty{color}, \isty{datatool-base} (very limited), +\isty{datatool} (very limited), \isty{etoolbox} (very limited), \isty{graphics}, +\isty{graphicx}, \isty{ifthen}, \isty{jmlrutils}, +\isty{mfirstuc-english}, \isty{probsoln}, \isty{shortvrb}, +and \isty{xspace}. These are less likely to be needed within fields +and so aren't checked for by default. If they are needed then you +can instruct \bibgls\ to support them with \longarg{packages}. + +Note that \sty{mfirstuc} is always automatically loaded, but +\sty{mfirstuc-english} is not implemented unless explicitly +requested with \code{\longarg{packages} mfirstuc-english}. + +If you're wondering about the selection, the \file{texparserlib.jar} +library was originally written for another application that required +support for some of them. + +\argsection{packages} + +Instruct the interpreter to assume the packages listed +in \meta{list} have been used by the document. +This option has a cumulative action so \code{\longarg{packages} +"wasysym,pifont"} is the same as \code{\longarg{packages} wasysym +\longarg{packages} pifont}. + +Note that there's only a limited number of packages supported by the +\TeX\ parser library. This option is provided for cases where you're +using a command from a package that the interpreter doesn't support +but it happens to have the same name and meaning as a command from +a package that the interpreter does support. You can also use it to +provide support for known packages that aren't checked for when the +\ext{log} file is parsed. If you want \bibgls\ to parse an +unsupported package use \longarg{custom-packages}. + +\argsection{custom-packages} + +Instruct the interpreter to parse the package files identified in +\meta{list}. The package files need to be quite simple. When this +switch is used, the interpreter can recognise \ics{ProvidesPackage}, +\ics{DeclareOption} (and \ics{DeclareOption*}), +\ics{ProcessOptions}, \ics{PackageError} and \ics{RequirePackage}, +but it can't deal with complicated code. In the case of +\ics{RequirePackage}, support will also be governed by +\longargfmt{custom-packages}. This option has a cumulative action. + +\argsection{ignore-packages} + +This option is cumulative. When the document \iext{log} file is +parsed for known packages, \bibgls\ will skip the check for any +listed in \meta{list}. Note that this option simply instructs +\bibgls\ to ignore the package information in the log file. Any packages +that are identified with \longarg{packages} will be passed to the +interpreter if support is available, even if the package is also +listed in \longargfmt{ignore-packages}. Note that +unknown packages can't be included in the ignored \meta{list}. + +\argsection{mfirstuc-protection} + +Commands like \ics{Gls} use \ics{makefirstuc} provided by the +\isty{mfirstuc} package. This command has limitations and one of the +things that can break it is the use of a referencing command +at the start of its argument. The \sty{glossaries-extra} package has +more detail about the problem in the \qt{Nested Links} section of +the user manual~\cite{glossaries-extra}. If a glossary field starts +with one of these problematic commands, the recommended method (if +the command can't be replaced) is to insert an empty group in front +of it. + +For example, the following definition +\begin{codeenv} +\gls{newabbreviation}\marg{shtml}\marg{shtml}\marg{\ics{glsps}\marg{ssi} enabled \cs{glsps}\marg{short}\marg{html}} +\end{codeenv} +will cause a problem for \code{\cs{Gls}\marg{shtml}} on first use. +The above example would be written in a \ext{bib} file as: +\begin{codeenv} +\atentry{abbreviation}\marg{shtml, + \field{short}=\marg{shtml}, + \field{long}=\marg{\cs{glsps}\marg{ssi} enabled \cs{glsps}\marg{html}} +} +\end{codeenv} +The default \sty{mfirstuc} protection will automatically insert an empty +group before \code{\cs{glsps}\marg{ssi}} when writing the definition +in the \ext{glstex} file. + +The argument for this switch should either be a comma-separated list +of fields or the keyword \code{all} (which indicates all fields). +\bibgls\ will automatically insert an empty group at the start of +the listed fields that start with a problematic command, and a +warning will be written to the transcript. Unknown fields are +skipped even if they're included in the list. An empty argument is +equivalent to \longarg{no-mfirstuc-protection}. The default value is +\code{all}. + +\argsection{no-mfirstuc-protection} + +Switches off the \isty{mfirstuc} protection mechanism described +above. + +\argsection{mfirstuc-math-protection} + +This works in the same way as \longarg{mfirstuc-protection} but +guards against fields starting with inline maths +(\idx{mshiftchar}\ldots\idx{mshiftchar}). For example, if the +\field{name} field starts with +\code{\idx{mshiftchar}x\idx{mshiftchar}} and the glossary style +automatically tries to convert the first letter of the name to +\idx{uppercase}, then this will cause a problem. + +With \longarg{mfirstuc-math-protection} set, \bibgls\ will +automatically insert an empty group at the start of the field and +write a warning in the transcript. This setting is on by default. + +\argsection{no-mfirstuc-math-protection} + +Switches off the above. + +\argsection{nested-link-check} + +By default, \bibgls\ will parse certain fields for potential nested links. +(See the section \qt{Nested Links} in the \sty{glossaries-extra} +user manual~\cite{glossaries-extra}.) + +The default set of fields to check are: \field{name}, \field{text}, +\field{plural}, \field{first}, \field{firstplural}, \field{long}, +\field{longplural}, \field{short}, \field{shortplural} and +\field{symbol}. + +You can change this set of fields using +\longarg{nested-link-check} \meta{value} where \meta{value} may be +\optfmt{none} (don't parse any of the fields) or a comma-separated +list of fields to be checked. + +\argsection{no-nested-link-check} + +Equivalent to \longarg{nested-link-check} \optfmt{none}. + +\argsection{shortcuts} + +Some entries may reference another entry within a field, using +commands like \ics{gls}, so \bibgls\ parses the fields for these +commands to determine dependent entries to allow them to be selected +even if they haven't been used within the document. +The \styopt{shortcuts} package option provided by +\styfmt{glossaries-extra} defines various synonyms, such as \ics{ac} +which is equivalent to \ics{gls}. By default the value of the +\styopt{shortcuts} option will be picked up by \bibgls\ when parsing the +\iext{aux} file. This then allows \bibgls\ to additionally search for +those shortcut commands while parsing the fields. + +You can override the \styopt{shortcuts} setting using +\longarg{shortcuts} \meta{value} (where \meta{value} may take +any of the allowed values for the \styopt{shortcuts} package option), +but in general there is little need to use this switch. + +\argsection{map-format} + +This sets up the rule of precedence for partial location +matches (see \sectionref{sec:locationopts}). The argument may be +a comma-separated list of \meta{map}\code{:}\meta{value} pairs. +Alternatively, you can have multiple instances of +\longarg{map-format} \meta{map}\dcolon\meta{value} which have a +cumulative effect. + +For example, +\begin{verbatim} +bib2gls --map-format "emph:hyperbf" mydoc +\end{verbatim} +This essentially means that if there's a record conflict +involving \encap{emph}, try replacing \encap{emph} with +\encap{hyperbf} and see if that resolves the conflict. + +Note that if the conflict includes a range formation, the +range takes precedence. +The mapping tests are applied as the records are +read. For example, suppose the records are listed in the \ext{aux} +file as: +\begin{codeenv} +\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{emph}}\marg{3} +\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{hypersf}}\marg{3} +\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{hyperbf}}\marg{3} +\end{codeenv} +and \bibgls\ is invoked with +\begin{verbatim} +bib2gls --map-format "emph:hyperbf,hypersf:hyperit" mydoc +\end{verbatim} +or +\begin{verbatim} +bib2gls --map-format emph:hyperbf --map-format hypersf:hyperit mydoc +\end{verbatim} +then \bibgls\ will process these records as follows: +\begin{enumerate} +\item Accept the first record (\encap{emph}) since there's +currently no conflict. (This is the first record for page~3 for the +entry given by \code{gls.sample}.) +\item The second record (\encap{hypersf}) conflicts +with the existing record (\encap{emph}). Neither has +the format \encap{glsnumberformat} or \encap{glsignore} so \bibgls\ consults +the mappings provided by \longargfmt{map-format}. +\begin{itemize} +\item The \encap{hypersf} format (from the new record) is mapped to +\encap{hyperit}, +so \bibgls\ checks if the existing record +has this format. In this case it doesn't (the format is +\code{emph}). So \bibgls\ moves on to the next test: + +\item The \encap{emph} format (from the existing record) is mapped +to \encap{hyperbf}, +so \bibgls\ checks if the new record has this format. +In this case it doesn't (the format is \encap{hypersf}). + +Since the provided mappings haven't resolved this conflict, +the new record is discarded with a warning. Note that there's +no look ahead to the next record. (There may be other +records for other entries also used on page~3 interspersed between these records.) +\end{itemize} +\item The third record (\encap{hyperbf}) conflicts +with the existing record (\encap{emph}). Neither has +the format \encap{glsnumberformat} or \encap{glsignore} so \bibgls\ again consults +the mappings provided by \longargfmt{map-format}. +\begin{itemize} +\item The new record's \encap{hyperbf} format has no mapping provided, +so \bibgls\ moves on to the next test: + +\item The existing record's \encap{emph} format has a mapping +provided (\encap{hyperbf}). This matches the new record's format, +so the new record takes precedence. + +This means that the location list ends up with the \encap{hyperbf} +location for page~3. +\end{itemize} +\end{enumerate} + +If, on the other hand, the mappings are given as +\begin{verbatim} +--map-format "emph:hyperit,hypersf:hyperit,hyperbf:hyperit" +\end{verbatim} +then all the three conflicting records (\encap{emph}, +\encap{hypersf} and \encap{hyperbf}) will end up being replaced +by a single record with \encap{hyperit} as the format. + +Multiple conflicts will typically be rare as there's usually little +reason for more than two or three different location formats within +the same list. (For example, \encap{glsnumberformat} as the default +and \encap{hyperbf} or \encap{hyperit} for a primary reference.) + +\argsection{group} + +The \styfmt{glossaries-extra} \styopt{record} package option +automatically creates a new internal field called \field{group}. If the +\longarg{group} switch is used with the default \csopt[auto]{group} +option then, when sorting, \bibgls\ will try +to determine the letter group for each entry and assign it to the +\field{group} field. (Some \csopt{sort} options ignore this +setting.) This value will be picked up by \ics{printunsrtglossary} +if group headings are required (for example with the +\glostyle{indexgroup} style) or if group separators are required +(for example, the \glostyle{index} style with the default +\styopt[false]{nogroupskip}). If you don't require grouping within +the glossary, there's no need to use this switch. Note that this +switch doesn't automatically select an appropriate glossary style. + +\begin{important} +The \field{group} field should typically not be set in the \ext{bib} +file and will trigger a warning if found. The explicit use of the +\field{group} key will override \bibgls's normal group formation behaviour, +which can cause unexpected results. The custom use of the +\field{group} field requires some care. As a general rule, if you +find yourself wanting to use the \field{group} field in the \ext{bib} file, +then the chances are that what you actually have is a hierarchical +glossary (list of topics) and what you really need is the \field{parent} field. +Compare the example files \exfile{sample-textsymbols.tex} and +\exfile{sample-textsymbols2.tex}. See also \sectionref{sec:logicaldivisions}. +\end{important} +There are eight types of groups: +\begin{description} +\item[\idx{lettergroup}] The first non-ignored character of the +sort value is alphabetic. This type of group occurs when using the +alphabetic sort methods listed in \tableref{tab:sortoptionsrule} or +with the letter sort methods listed in +\tableref{tab:sortoptionsletter} or with the letter-number sort +methods listed in \tableref{tab:sortoptionsletternumber}. The group +label is obtained from \gls!{bibglslettergroup}. + +\item[\idx{nonlettergroup} (or \idx{symbolgroup})] +The first non-ignored character of all the sort values within this group +are non-alphabetical. This type of group occurs when using the +alphabetic sort methods listed in \tableref{tab:sortoptionsrule} or +with the letter sort methods listed in +\tableref{tab:sortoptionsletter} or with the letter-number sort +methods listed in \tableref{tab:sortoptionsletternumber}. +The alphabetic sort methods ignore many punctuation +characters, so an entry that has a non-alphabetic initial +character in the sort value may actually be placed in a +\idx{lettergroup}. +The group label is obtained from \gls!{bibglsothergroup}. + +\item[\idx{emptygroup}] The sort value is empty when sorting with an +alphabetical, letter or letter-number method, typically a +result of the original value consisting solely of commands that \bibgls\ +can't interpret. The group label is obtained from \gls!{bibglsemptygroup}. + +\item[\idx{numbergroup}] The entries were sorted by one of the +numeric comparisons listed in \tableref{tab:sortoptionsnumerical}. +The group label is obtained from \gls!{bibglsnumbergroup}. + +\item[\idx{datetimegroup}] The entries were sorted by one of the date-time +comparisons listed in \tableref{tab:sortoptionsdatetime} (where both +date and time are present). +The group label is obtained from \gls!{bibglsdatetimegroup}. + +\item[\idx{dategroup}] The entries were sorted by one of the date +comparisons (where the time is omitted). +The group label is obtained from \gls!{bibglsdategroup}. + +\item[\idx{timegroup}] The entries were sorted by one of the time +comparisons (where the date is omitted). +The group label is obtained from \gls!{bibglstimegroup}. + +\item[\idx{customgroup}] The group label is explicitly set either by +aliasing a field (with \csopt{field-aliases}) or by using the +\csopt[\meta{label}]{group} resource option. You will need to use +\gls{glsxtrsetgrouptitle} in the document to provide an associated title if the +\meta{label} isn't the same as the title. Remember that the label +can't contain any active characters, so you can't use non-ASCII +characters in \meta{label} with \sty{inputenc} (but you can use +non-ASCII alphanumerics with \sty{fontspec}). + +\end{description} + +The \idx{lettergroup} titles will typically have the first character +converted to \idx{uppercase} for the alphabet sort methods +(\tableref{tab:sortoptionsrule}). A \qt{letter} may not necessarily +be a single character (depending on the sort rule), but may be +composed of multiple characters, such as a \idx{digraph} (two +characters) or \idx{trigraph} (three characters). + +For example, if the sort rule recognises the digraph \qt{dz} as a +letter, then it will be converted to \qt{Dz} for the group title. +There are some exceptions to this. For example, the Dutch digraph +\qt{ij} should be \qt{IJ} rather than \qt{Ij}. This is indicated +by the following line in the \langxml: +\begin{verbatim} +<entry key="grouptitle.case.ij">IJ</entry> +\end{verbatim} +If there isn't a \idx{grouptitle.case.lc} key (where +\meta{lc} is the \idx!{lowercase} version), then only the first character +will be converted to \idx{uppercase} otherwise the value supplied by the +resource file is used. This resource key is only checked for +the alphabetical comparisons listed in +\tableref{tab:sortoptionsrule}. If the initial part of the sort +value isn't recognised as a letter according to the sort rule, then +the entry will be in a \idx{nonlettergroup} (even if the character is +alphabetical). + +The letter (\tableref{tab:sortoptionsletter}) and letter-number +(\tableref{tab:sortoptionsletternumber}) methods only select the +first character of the sort value for the group. If the character is +alphabetical\footnote{according to Java's +\code{Character.isAlphabetic(int)} method} then it will be a +\idx{lettergroup} otherwise it's a \idx{nonlettergroup}. The case-insensitive +ordering (such as \csopt[letter-nocase]{sort}) will convert the +letter group character to \idx{uppercase}. The case-sensitive ordering +(such as \csopt[letter-case]{sort}) won't change the case. + +Glossary styles with navigational links to groups (such as +\glostyle{indexhypergroup}) require an extra run for the ordinary +\cs{cs.makeglossaries} and \cs{makenoidxglossaries} methods. For +example, for the document \filefmt{myDoc.tex}: +\begin{verbatim} +pdflatex myDoc +makeglossaries myDoc +pdflatex myDoc +pdflatex myDoc +\end{verbatim} +On the first \appfmt{pdflatex} call, there's no glossary. On the second +\appfmt{pdflatex}, there's a glossary but the glossary must be +processed to find the group information, which is written to the +\iext{aux} file as +\nosecdef{@gls@hypergroup} +The third \appfmt{pdflatex} reads this information and is then able +to create the navigation links. + +With \bibgls, if the \optfmt{type} is provided (through the +\field{type} field or via options such as \csopt{type} and +\csopt{dual-type}) then this information can be determined when +\bibgls\ is ready to write the \iext{glstex} file, which means that +the extra \LaTeX\ run isn't necessary. If \bibgls\ doesn't know +the glossary type then it will fallback on the original method +which requires an extra \LaTeX\ run. + +For example: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\cmd{usepackage}\oarg{colorlinks}\marg{hyperref} +\cmd{usepackage}\oarg{\styopt{record},\styopt{abbreviations},\styopt[indexhypergroup]{style}}\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\comment{data in entries.bib} + \csopt[main]{type}\comment{put these entries in the 'main' glossary} +} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[abbrvs]{src},\comment{data in abbrvs.bib} + \csopt[abbreviations]{type}\comment{put entries in the 'abbreviations' glossary} +} +\end{codeenv} +Here the \csopt{type} is set and \bibgls\ can detect that +\isty{hyperref} has been loaded, so if the \longargfmt{group} switch +is used, then the group hyperlinks can be set (using +\gls!{bibglshypergroup}). This means that the build process is +just: +\begin{verbatim} +pdflatex myDoc +bibtex --group myDoc +pdflatex myDoc +\end{verbatim} +Note that this requires \isty{glossaries} v4.32+. If your version of +\sty{glossaries} is too old then \bibgls\ can't override +the default behaviour of \isty{glossary-hypernav}'s +\ics{glsnavhypertarget}. + +If \isty{hyperref} isn't loaded or the \longargfmt{group} switch +isn't used or the \field{type} isn't set or your version of +\sty{glossaries} is too old, then the information can't be saved in +the \ext{glstex} file. + +For example: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\cmd{usepackage}\oarg{colorlinks}\marg{hyperref} +\cmd{usepackage}\oarg{\styopt{record},\styopt{abbreviations},\styopt[indexhypergroup]{style}}\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}}\comment{data in entries.bib} +\gls{GlsXtrLoadResources}\oarg{\csopt[abbrvs]{src}}\comment{data in abbrvs.bib} +\end{codeenv} +This requires the build process: +\begin{verbatim} +pdflatex myDoc +bibtex --group myDoc +pdflatex myDoc +pdflatex myDoc +\end{verbatim} +because the group hyperlink information can't be determined by +\bibgls, so it's best to always set the \optfmt{type} if you want +hyper-group styles, and make sure you have an up-to-date version of +\styfmt{glossaries} (and \styfmt{glossaries-extra}). + +\argsection{no-group} + +Don't automatically set the \field{group} field with +\csopt[auto]{group} (default). The glossary won't have groups even if a +group style, such as \glostyle{indexgroup}, is used (unless the +\field{group} field is set to a custom value). + +\argsection{tex-encoding} + +\bibgls\ tries to determine the character encoding to use for the +output files. If the document has loaded the \isty{inputenc} package then +\bibgls\ can obtain the value of the encoding from the +\iext{aux} file. This is then converted to a name +recognised by Java. For example, \code{utf8} will be mapped to +\code{UTF-8}. If the \isty{fontspec} package has been loaded, +\styfmt{glossaries-extra} will assume the encoding is \code{utf8} and +write that value to the \ext{aux} file. + +If neither package has been loaded, \bibgls\ will assume the \idx{JVM}['s] +default encoding (identified by the \code{file.encoding} property). If this is +incorrect or if \bibgls\ can't work out the appropriate mapping then you can +specify the correct encoding using \longargfmt{tex-encoding} \meta{name} where +\meta{name} is the encoding name (such as \code{UTF-8}). + +If you have a problem with non-ASCII characters not displaying +correctly in your document: +\begin{itemize} +\item Check that the file encoding of your document \ext{tex} file (or files) +has been correctly set by your text editor. +\item Check that your document supports that encoding (for example, +through the \isty{inputenc} package). +\item Check \bibgls's transcript file (\ext{glg}) for the line that +starts +\begin{verbatim} +TeX character encoding: +\end{verbatim} +This should be followed by the encoding used by \bibgls\ when +creating the \ext{glstex} files. If this is incorrect use +\longargfmt{tex-encoding}. +\item Check that the encoding of the \ext{bib} files (set by your +text editor or bibliographic management system) matches the encoding +line in the \ext{bib} file or the \csopt{charset} resource option. +\end{itemize} + +\argsection{no-expand-fields} + +By default, \gls{newglossaryentry} and similar commands expand field values +(except for \field{name}, \field{symbol} and \field{description}). +This is useful if constructing field values programmatically +(for example in a loop) but can cause a problem if certain fragile +commands are included in the field. + +The switch \longarg{no-expand-fields} makes \bibgls\ write +\gls{glsnoexpandfields} to the \iext{glstex} file, which +switches off the expansion. Since \bibgls\ is simply +fetching the data from \iext{bib} files, it's unlikely +that this automatic expansion is required and since it can +also be problematic this option is on by default. You can +switch it off with \longarg{expand-fields}. + +\argsection{expand-fields} + +Don't write \gls{glsnoexpandfields} to the \iext{glstex} file, +allowing fields to expand when the entries are defined. +Remember that this doesn't include the \field{name}, \field{symbol} +or \field{description} fields, which need to have their +expansion switched on with \gls{glssetexpandfield} +before the entries are defined (that is, before using +\gls!{GlsXtrLoadResources}). + +\argsection{trim-fields} + +Trim leading and trailing spaces from field values. For example, +if the \ext{bib} file contains: +\begin{codeenv} +\atentry{entry}\marg{sample, + \field{name} = \marg{ sample }, + \field{description} = \marg{ + an example + } +} +\end{codeenv} +This will cause spurious spaces. Using \longarg{trim-fields} will +automatically trim the values before writing the \iext{glstex} file. + +\argsection{no-trim-fields} + +Don't trim any leading or trailing spaces from field values. +This is the default setting. + +\argsection{record-count} + +Switch on record counting. This will ensure that when each entry +is written to the \iext{glstex} file, \bibgls\ will additionally +set the following fields +\begin{itemize} +\item \field{recordcount}: set to the total +number of records found for the entry; +\item \field{recordcount.counter}: set to the total +number of records found for the entry for the given counter. +\end{itemize} +These fields can then be used with the \gls{rgls}-like commands. +The default behaviour of +\nosecdef{rgls} +is to check the \field{recordcount} field against the \catattr{recordcount} +attribute value. This attribute can be set with +\nosecdef{GlsXtrSetRecordCountAttribute} +where \meta{category list} is a comma-separated list +of category labels and \meta{value} is a positive integer. +If the value of the \field{recordcount} field is greater than +\meta{value} then \gls{rgls} behaves like \ics{gls}, otherwise +it does +\nosecdef{rglsformat} +instead. +If the use of \gls{rglsformat} is triggered in this way, +then \gls{rgls} writes a record to the \iext{aux} file +with the \glsopt{format} set to \encap{glstriggerrecordformat}. +This ensures that the record count is correct on the next run, +but the record isn't added to the location list as +\bibgls\ recognises it as a special \idx{ignoredrecord}. +Note that the entry will still appear in the usual glossary unless +you assign it to a different one with \csopt{trigger-type}. + +If the \catattr{recordcount} attribute hasn't been set +\gls{rgls} behaves like \ics{gls}. (That is, \gls{rgls} +uses the same internal command used by \ics{gls}.) You can use +\ics{glsxtrenablerecordcount} to redefine \ics{gls} +to \gls{rgls}, so that you can continue to use \ics{gls} +without having to switch command name. + +For example: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[abbrevs]{src},\comment{entries defined in abbrevs.bib} + \csopt[ignored]{trigger-type}, + \csopt[abbreviation]{category} +} +\cs{glsxtrenablerecordcount} +\gls{GlsXtrSetRecordCountAttribute}\marg{abbreviation}\marg{1} +\end{codeenv} +See the \sty{glossaries-extra} user manual~\cite{glossaries-extra} +for further details. + +\argsection{no-record-count} + +Switch off record counting. (Default.) + +\argsection{record-count-unit} + +Automatically implements \longarg{record-count} and additionally +sets the \field{recordcount.counter.location} fields. +These fields can then be used with the \gls{rgls}-like +commands. + +\argsection{no-record-count-unit} + +Switches off unit record counting. (Default.) +Note that you need \longarg{no-record-count} to completely +switch off record counting. + +\chapter{\iext{bib} Format} +\label{sec:bib} +\setsecdepth{1} + +\bibgls\ recognises certain entry types. Any unrecognised types will +be ignored and a warning will be written to the transcript file. +Entries are defined in the usual \ext{bib} format: +\begin{codeenv*} +\idx{atchar}\meta{entry-type}\marg{\meta{id}, + \meta{field-name-1} = \margm{text}, + \ldots + \meta{field-name-n} = \margm{text} +} +\end{codeenv*} +where \meta{entry-type} is the entry type (listed below), +\meta{field-name-1}, \ldots, \meta{field-name-n} are the field names and +\meta{id} is a unique label. The label can't contain any spaces or +commas, and most special characters are forbidden. The hyphen character and +some other punctuation characters are allowed by \bibgls, but you need to make +sure that your document hasn't made them active. In general it's best to +stick with alpha-numeric labels. The field values may be delimited by braces +\margm{text} or double-quotes \code{\qtdelim{\meta{text}}}. + +The \csopt{label-prefix} option can be used to instruct \bibgls\ to +insert prefixes to the labels (\meta{id}) when the data is read. +Remember to use these prefixes when you reference the entries in the +document, but don't include them when you reference them in the +\ext{bib} file. There are some special prefixes that have a +particular meaning to \bibgls: \qt{\idprefix{dual}} and +\qt{\idprefix{extn}} where \meta{n} is a positive integer. +In the first case, \idprefix{dual} references the dual element of a +dual entry (see \atentry{dualentry}). This prefix will be +replaced by the value of the \csopt{dual-prefix} option. The +\idprefix{extn} prefix is used to reference an entry from a +different set of resources (loaded by another +\gls{GlsXtrLoadResources} command). This prefix is replaced by the +corresponding element of the list supplied by \csopt{ext-prefixes}, +but this is only supported if the \idx{crossresourceref} mode is enabled +(see \sectionref{sec:resourcesets}). + +In the event that the \field{sort} value falls back on the label, +the original label supplied in the \ext{bib} file is used, not the +prefixed label. + +\section{Encoding} +\label{sec:bibencoding} + +Avoid \idx{non-ASCII} characters in the \meta{id} if your document uses the +\isty{inputenc} package. (This isn't a problem for \XeLaTeX\ or +\LuaLaTeX, but you still need to avoid special characters.) +You can set the character \idx{encoding} in the \ext{bib} file using: +\begin{codeenv} +\idx{commentchar} Encoding: \meta{encoding-name} +\end{codeenv} +where \meta{encoding-name} is the name of the character encoding. +For example: +\begin{verbatim} +% Encoding: UTF-8 +\end{verbatim} +You can also set the encoding using the \csopt{charset} option, +but it's simpler to include the above comment on the first line of +the \ext{bib} file. (This comment is also searched for by JabRef +to determine the encoding, so it works for both applications.) +If you don't use either method \bibgls\ will +have to search the entire \ext{bib} file, which is inefficient and +you may end up with a mismatched encoding. + +\section{Comments} +\label{sec:bibcomments} + +The original \ext{bib} file format as defined by \BibTeX\ doesn't +have a designated comment character, but instead treats anything +outside of \code{@\meta{entry}\margm{data}} as unwanted material +that's ignored. This can catch out users who try to do something +like: +\begin{verbatim} +%@misc{sample, title={Sample} } +\end{verbatim} +In this case, the percent character is simply discarded and the +line is treated as: +\begin{verbatim} +@misc{sample, title={Sample} } +\end{verbatim} +Some applications that parse \ext{bib} files are less tolerant of +unwanted material. In the case of \bibgls, the percent character is +treated as a comment character and other unwanted material +should be omitted. Avoid using comments within field values. +Comments are best placed outside of entry definitions. + +The most common type of comment is the encoding comment, described +above. \BibTeX's \entrydef{comment} is also supported by \bibgls\ +for general comments, but not for the encoding. For example, JabRef +uses \atentryfmt{Comment} for metadata. +\begin{codeenv} +\atentryfmt{Comment}\marg{jabref-meta: databaseType:bib2gls;} +\end{codeenv} + +\section{Fields} +\label{sec:fields} + +Each entry type may have required fields, optional fields and +ignored fields. These are set using a \keyvallist\ within +\code{@\meta{entry-type}\marg{\meta{id},\meta{fields}}} in the +\ext{bib} file. Most keys recognised by +\gls{newglossaryentry} may be used as a field unless \bibgls\ +considers them an internal field (see below). In general, you +shouldn't need to use the \field{sort} field. + +If an optional field is missing and \bibgls\ needs to access it for +some reason, \bibgls\ will try to fallback on another value. The +actual fallback value depends on the entry type. The most common +fallback is that used if the \field{sort} field is missing, which is +typically the case. This approach allows different entry types to +have different fields used for sorting. + +Predefined fields for use in \ext{bib} files are listed in +Tables~\ref{tab:fields}, \ref{tab:bib2glsfields}, +\ref{tab:prefixfields} and~\ref{tab:accsuppfields}. If you add any +custom keys in your document using \ics{glsaddkey} or +\ics{glsaddstoragekey}, those commands must be placed before the +first use of \gls{GlsXtrLoadResources} to ensure that \bibgls\ +recognises them as a valid field name. + +Internal fields that may be assigned within the document (the +\LaTeX\ assignment code having been written by \bibgls\ in the +\iext{glstex} file) are listed in Table~\ref{tab:internalfields}. +These typically shouldn't be used in the \ext{bib} file. Some of +these fields can be set for a particular document using a resource +option, such as \csopt{type} or \csopt{group}. With +\longarg{warn-non-bib-fields} set, \bibgls\ will check for internal +fields that can cause interference with its normal operations and +will warn if any are found in the \ext{bib} file. + +There are also some fields that are set and used by +\styfmt{glossaries} or \styfmt{glossaries-extra} listed in +Table~\ref{tab:baseinternalfields} that aren't recognised by \bibgls. +In most cases these fields don't have a designated key and are only +intended for internal use by \bibgls\ or by the \styfmt{glossaries} or +\styfmt{glossaries-extra} package. Note that the value of the \field{sort} field +written to the \ext{bib} file doesn't always exactly match the sort +value used by \bibgls\ (which is stored in \field{bib2gls@sort}). +Any special characters found in the sort value are always substituted +before writing the \ext{bib} file to avoid syntax errors. + +Any unrecognised fields will be ignored by \bibgls. This is more +convenient than using \ics{input} or \ics{loadglsentries}, which +requires all the keys used in the file to be defined, regardless of +whether or not you actually need them in the document. + +Other entries can be cross-referenced using the \field{see}, +\field{seealso} or \field{alias} fields or +by using commands like \ics{gls} or \ics{glsxtrp} in any of the +recognised fields. These will automatically be selected if the +\csopt{selection} setting includes dependencies, but you may need to +rebuild the document to ensure the location lists are correct. Use +of the \ics{glssee} command will create an \idx{ignoredrecord} and the +\field{see} field will be set to the relevant information. If an +entry has the \field{see} field already set, any instance of +\ics{glssee} in the document for that entry will be appended to the +\field{see} field (provided you have at least v1.14 of +\sty{glossaries-extra}). In general, it's best just to use the +\field{see} field and not use \ics{glssee}. + +The \field{seealso} key was only added to \sty{glossaries-extra} +v1.16, but this field may be used with \bibgls\ even if you only +have version 1.14 or 1.15. If the key isn't available, +\code{\field{seealso}=\margm{xr-list}} will be treated as +\code{\field{see}=\marg{[\ics{seealsoname}]\meta{xr-list}}} (the resource +option \csopt{seealso} won't have an effect). You can't use both +\field{see} and \field{seealso} for the same entry with \bibgls. +Note that the \field{seealso} field doesn't allow for the optional +\oargm{tag} part. If you need a different tag, either use \field{see} +or change the definition of \ics{seealsoname} or +\ics{glsxtruseseealsoformat}. Note that, unless you are using +\idx{xindy}, \ics{glsxtrindexseealso} just does +\ics{glssee}\oarg{\ics{seealsoname}}, and so will be treated as \field{see} +rather than \field{seealso} by \bibgls. Again, it's better to just +use the \field{seealso} field directly. + +You can identify an arbitrary field as containing a list of dependent entry +labels with \csopt{dependency-fields}. This instructs \bibgls\ to parse the +listed fields for dependencies in a similar manner to the \field{see} field, +but it doesn't add any information to the cross-referencing part of the +location list. The option may be used in combination with the \field{see} or +\field{seealso} fields. + +\clearpage + +\printfields + {basefield,extrafield} + {Fields Provided by \styfmt{glossaries-extra}} + {tab:fields} + +\clearpage + +\printfields + {bib2glsfield} + {Fields Provided by \bibgls} + {tab:bib2glsfields} + +\printfields + {prefixfield}% + [Fields Provided by \styfmt{glossaries-prefix}]% + {Fields Provided by \isty{glossaries-prefix}} + {tab:prefixfields} + +\printfields + [% + Don't load \isty{glossaries-accsupp} directly (with \ics{usepackage}) + when using \styfmt{glossaries-extra}. Load using the \styopt{accsupp} + package option instead. +%\begin{codeenv} +%\cs{usepackage}\oarg{\styopt{record},\styopt{accsupp}}\marg{glossaries-extra} +%\end{codeenv} + ]% + {accessfield}% + [Fields Provided by \styfmt{glossaries-accsupp}]% + {Fields Provided by \isty{glossaries-accsupp}} + {tab:accsuppfields} + +\printfields + [% + You may define and assign \field{bibtextype} as a key (although it's more + likely to be aliased). Don't define any of the others listed in this + table, and don't use any of them in the \ext{bib} file. A possible + exception is the \field{type} field, but it's more flexible to set + that through a resource option. The explicit use of \field{group} + within a \ext{bib} file can cause unpredictable + results and is best set through a resource option or by \bibgls. + In general, you shouldn't need to set the \field{sort} field as + appropriate fallbacks should produce useful sort values.% + ]% + {internalfield}% + [Fields Set by \bibgls]% + {Fields Sometimes Set by \bibgls\ in the \iext{glstex} File}% + {tab:internalfields} + +\printfields + [% + Don't define any of these as keys and don't use any of them in the \ext{bib} + file.% + ]% + {baseinternalfield}% + [Internal Fields Set by \styfmt{glossaries} or \styfmt{glossaries-extra} + or \bibgls]% + {Internal Fields Set by \isty{glossaries} or \isty{glossaries-extra} + or \bibgls}% + {tab:baseinternalfields} + +\clearpage + +\section{Standard Entry Types} +\label{sec:standardentry} + +\entrysection{string} + +The standard \atentry{string} is available and can be used to define +variables that may be used in field values. Don't include braces or +double-quote delimiters when referencing a variable. You can use +\idx{stringconcat} to concatenate strings. +For example: +\begin{codeenv} +\atentry{string}\marg{ssi=\marg{server-side includes}} +\atentry{string}\marg{html=\marg{hypertext markup language}} +\strut +\atentry{abbreviation}\marg{shtml, + \field{short}=\qtdelim{shtml}, + \field{long}=ssi \idx{stringconcat} \qtdelim{ enabled } \idx{stringconcat} html, + \field{see}=\marg{ssi,html} +} +\strut +\atentry{abbreviation}\marg{html, + \field{short}=\qtdelim{html}, + \field{long}=html +} +\strut +\atentry{abbreviation}\marg{ssi, + \field{short}=\qtdelim{ssi}, + \field{long}=ssi +} +\end{codeenv} +Note the difference between \code{=\qtdelim{ssi}} (a field value delimited by +double-quotes), the undelimited \code{=ssi} (a reference to the +variable), the grouped \code{=\marg{ssi,html}} (a field value +delimited by braces) and \code{ssi} the entry label. + +\entrysection{preamble} + +The standard \atentry{preamble} is available and can be used to +provide command definitions used within field values. +For example: +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{mtx}}[1]\marg{\cs{boldsymbol}\marg{\idx{param}1}}}} +\strut +\atentry{entry}\marg{matrix, + \field{name}=\marg{matrix}, + \field{plural}=\marg{matrices}, + \field{description}=\marg{rectangular array of values, denoted \idx{mshiftchar}\cmd{mtx}\marg{M}\idx{mshiftchar}} +} +\end{codeenv} +Alternatively you can use \ics{glsxtrprovidecommand} which behaves +the same as \ics{providecommand} within the document but behaves +like \ics{renewcommand} within \bibgls, which allows you to change +\bibgls's internal definition of a command without affecting the +definition within the document (if it's already been defined before +the resource file is input). In general, it's best to just use +\cs{providecommand}. + +The \TeX\ parser library used by \bibgls\ will parse the contents of +\atentry{preamble} before trying to interpret the field value used +as a fallback when \field{sort} is omitted (unless +\csopt[false]{interpret-preamble} is set in the resource options). +For example: +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{set}}[1]\marg{\cs{mathcal}\marg{\idx{param}1}} +\cs{providecommand}\marg{\cmd{card}}[1]\marg{|\cmd{set}\marg{\idx{param}1}|}}} +\strut +\atentry{entry}\marg{S, + \field{name}=\marg{\marg{}\idx{mshiftchar}\cmd{set}\marg{S}\idx{mshiftchar}}, + \field{text}=\marg{\cmd{set}\marg{S}}, + \field{description}=\marg{a set} +} +\atentry{entry}\marg{card, + \field{name}=\marg{\marg{}\idx{mshiftchar}\cmd{card}\marg{S}\idx{mshiftchar}}, + \field{text}=\marg{\cmd{card}\marg{S}}, + \field{description}=\marg{the cardinality of \cs{gls}\marg{S}} +} +\end{codeenv} +Neither entry has the \field{sort} field, so \bibgls\ has to fall +back on the \field{name} field and, since this contains the special +characters \idx{escchar} (backslash), \idx{mshiftchar} (maths +shift), \idx{bgroupchar} (begin group) and +\idx{egroupchar} (end group), the \TeX\ parser library is used to interpret it. +The definitions provided by \atentry{preamble} allow \bibgls\ to +deduce that the \field{sort} value of the \code{S} entry is just +\code{S} and the \field{sort} value of the \code{card} entry is +\verb"|S|" (see \sectionref{sec:texparserlib}). + +What happens if you also need to use these commands in the document? +The definitions provided in \atentry{preamble} won't be available +until the \iext{glstex} file has been created, which means the +commands won't be defined on the first \LaTeX\ run. + +There are several approaches: +\begin{enumerate} +\item Just define the commands in the document. This means the +commands are available, but \bibgls\ won't be able to correctly +interpret the \field{name} fields. + +\item Define the commands in both the document and in +\atentry{preamble}. For example: +\begin{codeenv} +\cs{newcommand}\marg{\cmd{set}}[1]\marg{\cs{mathcal}\marg{\idx{param}1}} +\cs{newcommand}\marg{\cmd{card}}[1]\marg{|\cmd{set}\marg{\idx{param}1}|} +\gls{GlsXtrLoadResources}\oarg{\csopt[my-data]{src}} +\end{codeenv} +Alternatively: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[my-data]{src}} +\cs{providecommand}\marg{\cmd{set}}[1]\marg{\cs{mathcal}\marg{\idx{param}1}} +\cs{providecommand}\marg{\cmd{card}}[1]\marg{|\cmd{set}\marg{\idx{param}1}|} +\end{codeenv} +If the provided definitions match those given in the \ext{bib} file, +there's no difference. If they don't match then in the first example +the document definitions will take precedence (but the interpreter +will use the \atentry{preamble} definitions) and in the second +example the \atentry{preamble} definitions will take precedence. +For example, the document may define \csfmt{card} as: +\begin{codeenv} +\cs{newcommand}\marg{\cmd{card}}[1]\marg{\ics{vert}\cmd{set}\marg{\idx{param}1}\cs{vert}} +\end{codeenv} + +\item Make use of \gls{glsxtrfmt} provided by \styfmt{glossaries-extra} which +allows you to store the name of the formatting command in a field. +The default is the \field{user1} field, but this can be changed to +another field by redefining \ics{GlsXtrFmtField}. + +The \ext{bib} file can now look like this: +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{set}}[1]\marg{\cs{mathcal}\marg{\idx{param}1}} +\cs{providecommand}\marg{\cmd{card}}[1]\marg{|\cmd{set}\marg{\idx{param}1}|}}} +\strut +\atentry{symbol}\marg{S, + \field{name}=\marg{\marg{}\idx{mshiftchar}\cmd{set}\marg{S}\idx{mshiftchar}}, + \field{text}=\marg{\cmd{set}\marg{S}}, + \field{user1}=\marg{set}, + \field{description}=\marg{a set} +} +\atentry{symbol}\marg{cardS, + \field{name}=\marg{\marg{}\idx{mshiftchar}\cmd{card}\marg{S}\idx{mshiftchar}}, + \field{text}=\marg{\cmd{card}\marg{S}}, + \field{user1}=\marg{card}, + \field{description}=\marg{the cardinality of \cs{gls}\marg{S}} +} +\end{codeenv} +Within the document, you can format \meta{text} using the formatting +command provided in the \field{user1} field with: +\nosecformatdef{glsxtrfmt} +(which internally uses \ics{glslink}) or +\nosecformatdef{glsxtrentryfmt} +which just applies the appropriate formatting command to +\meta{text}. Version 1.23+ of \sty{glossaries-extra} also provides a +starred form of the linking command: +\nosecformatdef{glsxtrfmt*} +which inserts additional material inside the link text but outside +the formatting command. + +If the entry given by \meta{label} hasn't been defined, +then \gls!{glsxtrfmt} just does \meta{text} (followed by \meta{insert} for +the starred version) and a warning is issued. (There's no warning +if the entry is defined but the field hasn't been set.) +The \meta{options} are as for \ics{glslink} but \ics{glslink} will +actually be using: +\begin{codeenv} +\ics{glslink}\oarg{\meta{def-options},\meta{options}}\margm{label}\marg{\cmd{}\meta{csname}\margm{text}\meta{insert}} +\end{codeenv} +where the default options \meta{def-options} are given by +\ics{GlsXtrFmtDefaultOptions}. The default definition of this is +just \code{noindex} which suppresses the automatic indexing or +recording action. (See the \sty{glossaries-extra} +manual~\cite{glossaries-extra} for further details.) The +\meta{insert} part is omitted for the unstarred form. + +This means that the document doesn't need to actually provide +\verb|\set| or \verb|\card| but can instead use, for example, +\begin{codeenv} +\gls{glsxtrfmt}\marg{S}\marg{A} +\gls{glsxtrentryfmt}\marg{cardS}\marg{B} +\end{codeenv} +instead of: +\begin{verbatim} +\set{A} +\card{B} +\end{verbatim} +The first \LaTeX\ run will simply ignore the formatting and produce +a warning. + +Since this is a bit cumbersome to write, you can provide shortcut +commands. For example: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[my-data]{src}} +\cs{newcommand}\marg{\cmd{gset}}[2][]\marg{\gls{glsxtrfmt}\oarg{\idx{param}1}\marg{S}\marg{\idx{param}2}} +\cs{newcommand}\marg{\cmd{gcard}}[2][]\marg{\gls{glsxtrfmt}\oarg{\idx{param}1}\marg{cardS}\marg{\idx{param}2}} +\end{codeenv} +Whilst this doesn't seem a great deal different from simply +providing the definitions of \csfmt{set} and \csfmt{card} in the +document, this means you don't have to worry about remembering +the names of the actual commands provided in the \ext{bib} file +(just the entry labels) and the use of \gls{glsxtrfmt} will +automatically produce a hyperlink to the glossary entry if the +\isty{hyperref} package has been loaded. +\end{enumerate} + +Here's an alternative \ext{bib} that defines entries with a term, a +description and a symbol: +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{setfmt}}[1]\marg{\cs{mathcal}\marg{\idx{param}1}} +\cs{providecommand}\marg{\cmd{cardfmt}}[1]\marg{|\cmd{setfmt}\marg{\idx{param}1}|}}} +\strut +\atentry{entry}\marg{set, + \field{name}=\marg{set}, + \field{symbol}=\marg{\cmd{setfmt}\marg{S}}, + \field{user1}=\marg{setfmt}, + \field{description}=\marg{collection of values} +} +\atentry{entry}\marg{cardinality, + \field{name}=\marg{cardinality}, + \field{symbol}=\marg{\cmd{cardfmt}\marg{S}}, + \field{user1}=\marg{cardfmt}, + \field{description}=\marg{the number of elements in the \cs{gls}\marg{set} \idx{mshiftchar}\cs{glssymbol}\marg{set}\idx{mshiftchar}} +} +\end{codeenv} +I've changed the entry labels and the names of the formatting commands. +The definitions in the document need to reflect the change in label +but not the change in the formatting commands: +\begin{codeenv} +\cs{newcommand}\marg{\cmd{gset}}[2][]\marg{\gls{glsxtrfmt}\oarg{\idx{param}1}\marg{set}\marg{\idx{param}2}} +\cs{newcommand}\marg{\cmd{gcard}}[2][]\marg{\gls{glsxtrfmt}\oarg{\idx{param}1}\marg{cardinality}\marg{\idx{param}2}} +\end{codeenv} + +Here's another approach that allows for a more complicated argument +for the cardinality. (For example, if the argument is an expression +involving set unions or intersections.) +The \ext{bib} file is now: +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{setfmt}}[1]\marg{\cs{mathcal}\marg{\idx{param}1}} +\cs{providecommand}\marg{\cmd{cardfmt}}[1]\marg{|\idx{param}1|}}} +\strut +\atentry{entry}\marg{set, + \field{name}=\marg{set}, + \field{symbol}=\marg{\cmd{setfmt}\marg{S}}, + \field{user1}=\marg{setfmt}, + \field{description}=\marg{collection of values} +} +\atentry{entry}\marg{cardinality, + \field{name}=\marg{cardinality}, + \field{symbol}=\marg{\cmd{cardfmt}\marg{\cmd{setfmt}\marg{S}}}, + \field{user1}=\marg{cardfmt}, + \field{description}=\marg{the number of elements in the \cs{gls}\marg{set} \idx{mshiftchar}\cs{glssymbol}\marg{set}\idx{mshiftchar}} +} +\end{codeenv} +This has removed the \csfmt{setfmt} command from the definition of +\csfmt{cardfmt}. Now the definitions in the document are: +\begin{codeenv} +\cs{newcommand}\marg{\cmd{gset}}[1]\marg{\gls{glsxtrentryfmt}\marg{set}\marg{\idx{param}1}} +\cs{newcommand}\marg{\cmd{gcard}}[2][]\marg{\gls{glsxtrfmt}\oarg{\idx{param}1}\marg{cardinality}\marg{\idx{param}2}} +\end{codeenv} +This allows for code such as: +\begin{verbatim} +\[ \gcard{\gset{A} \cap \gset{B}} \] +\end{verbatim} +which will link back to the \code{cardinality} entry in the +glossary and avoids any hyperlinking with \csfmt{gset}. +Alternatively to avoid links with \csfmt{gcard} as well: +\begin{codeenv} +\cs{newcommand}\marg{\cmd{gset}}[1]\marg{\gls{glsxtrentryfmt}\marg{set}\marg{\idx{param}1}} +\cs{newcommand}\marg{\cmd{gcard}}[1]\marg{\gls{glsxtrentryfmt}\marg{cardinality}\marg{\idx{param}1}} +\end{codeenv} +Now \csfmt{gset} and \csfmt{gcard} are simply formatting commands, +but their actual definitions are determined in the \ext{bib} file. + +\section{Single Entry Types} +\label{sec:singleentry} + +The entry types described in this section create a single glossary +definition per entry (from \styfmt{glossaries-extra}'s point of view). +For example: +\begin{codeenv} +\atentry{entry}\marg{matrix, + \field{name}=\marg{matrix}, + \field{plural}=\marg{matrices}, + \field{description}=\marg{rectangular array of values} +} +\end{codeenv} +is analogous to: +\begin{codeenv} +\gls{newglossaryentry}\marg{matrix}\comment{label} +\marg{\comment{fields} + \field{name}=\marg{matrix}, + \field{plural}=\marg{matrices}, + \field{description}=\marg{rectangular array of values} +} +\end{codeenv} +The \csopt{secondary} option allows the creation of a fake glossary +with the entry labels in its internal list in a different order. +This means that the same data can be displayed in two separate lists +without duplicating the resources required by each glossary entry. + +\Sectionref{sec:dualentry} describes \bibgls\ entry types +that create two separate (but related) \styfmt{glossaries-extra} +definitions per \ext{bib} entry. + +\entrysection{entry} + +Regular terms are defined by the \atentry{entry} field. This requires the +\field{description} field and either \field{name} or \field{parent}. +For example: +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{mtx}}[1]\marg{\cs{boldsymbol}\marg{\idx{param}1}}}} +\strut +\atentry{entry}\marg{matrix, + \field{name}=\marg{matrix}, + \field{plural}=\marg{matrices}, + \field{description}=\marg{rectangular array of values, denoted \cs{gls}\marg{M}}, + \field{seealso}=\marg{vector} +} +\strut +\atentry{entry}\marg{M, + \field{name}=\marg{\cs{ensuremath}\marg{M}}, + \field{description}=\marg{a \cs{gls}\marg{matrix}} +} +\strut +\atentry{entry}\marg{vector, + \field{name} = \qtdelim{vector}, + \field{description} = \marg{column or row of values, denoted \cs{gls}\marg{v}}, + \field{seealso}=\marg{matrix} +} +\strut +\atentry{entry}\marg{v, + \field{name}=\marg{\cs{ensuremath}\marg{\cs{vec}\marg{v}}}, + \field{description}=\marg{a \cs{gls}\marg{vector}} +} +\end{codeenv} + +If the \field{sort} field is missing the default is obtained from +the \field{name} field (unless overridden by +\csopt{entry-sort-fallback}). For hierarchical entries, if the +\field{name} field is omitted it will be obtained from the parent's +\field{name}. + +Terms defined using \atentry{entry} will be written to the output +(\ext{glstex}) file using the command \gls!{bibglsnewentry}. + +\entrysection{symbol} + +The \atentry{symbol} entry type is much like \atentry{entry}, but it's +designed specifically for symbols, so in the previous example, the +\code{M} and \code{v} terms would be better defined using the +\atentry{symbol} entry type instead. For example: +\begin{codeenv} +\atentry{symbol}\marg{M, + \field{name}=\marg{\cs{ensuremath}\marg{M}}, + \field{description}=\marg{a \cs{gls}\marg{matrix}} +} +\end{codeenv} + +The required fields are \field{name} or \field{parent}. The +\field{description} field is required if the \field{name} field is +missing. If the \field{sort} field is omitted, the default sort is +given by the entry label (unless overridden by +\csopt{symbol-sort-fallback}). Note that this is different from +\atentry{entry} where the sort defaults to \field{name} if omitted. + +Terms that are defined using \atentry{symbol} will be written to +the output file using the command \gls!{bibglsnewsymbol}. + +\entrysection{number} + +The \atentry{number} entry type is like \atentry{symbol}, but it's for +numbers. The numbers don't have to be explicit digits and may have a +symbolic representation. There's no real difference between the +behaviour of \atentry{number} and \atentry{symbol} except that terms +defined using \atentry{number} will be written to the output file +using the command \gls!{bibglsnewnumber}. + +For example, the file \filefmt{constants.bib} might define +mathematical constants like this: +\begin{codeenv} +\atentry{number}\marg{pi, + \field{name}=\marg{\cs{ensuremath}\marg{\ics{pi}}}, + \field{description}=\marg{the ratio of the length of the circumference + of a circle to its diameter}, + \field{user1}=\marg{3.14159} +} +\strut +\atentry{number}\marg{e, + \field{name}=\marg{\cs{ensuremath}\marg{e}}, + \field{description}=\marg{base of natural logarithms}, + \field{user1}=\marg{2.71828} +} +\end{codeenv} +This stores the approximate value in the \field{user1} field. This +can be used to sort the entries in numerical order according to the +values rather than the symbols: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[constants]{src},\comment{constants.bib} + \csopt[number]{category},\comment{set the category for all selected entries} + \csopt[double]{sort},\comment{numerical double-precision sort} + \csopt[user1]{sort-field}\comment{sort according to 'user1' field} +} +\end{codeenv} +The \csopt[number]{category} option makes it easy to adjust the +glossary format to include the \field{user1} field: +\begin{codeenv} +\ics{glsdefpostdesc}\marg{number}\marg{\comment{} + \cs{ifglshasfield}\marg{useri}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{ (approximate value: \cs{glscurrentfieldvalue})}\comment{} + \marg{}\comment{} +} +\end{codeenv} + +\entrysection{index} + +The \atentry{index} entry type is designed for entries that don't +have a description. Only the label is required. If \field{name} is +omitted, it's assumed to be the same as the label, even if +\field{parent} is present. (Note this is different to the fallback +behaviour of \atentry{entry}, which fetches the name from the parent +entry.) If the name contains any characters that can't be used in +the label, you must use the \field{name} field. If the \field{sort} +field is missing the default is obtained from the \field{name}. +Note that the \atentry{index} entry type is \emph{not} governed by +\csopt{entry-sort-fallback}. This allows \atentry{index} and +\atentry{entry} to have different fallbacks if the \field{sort} +field is missing. + +Example: +\begin{codeenv} +\atentry{index}\marg{duck} +\atentry{index}\marg{goose,\field{plural}=\marg{geese}} +\atentry{index}\marg{sealion,\field{name}=\marg{sea lion}} +\atentry{index}\marg{facade,\field{name}=\marg{fa\ics{c}\marg{c}ade}} +\end{codeenv} + +Terms that are defined using \atentry{index} will be written to the output +file using the command \gls!{bibglsnewindex}. + +\entrysection{indexplural} + +The \atentry{indexplural} entry type is similar to the +\atentry{index} entry type except that the \field{name} field, if +missing, is obtained from the \field{plural} field. If the +\field{plural} field is missing it's obtained from the \field{text} +field with the plural suffix appended. If the \field{text} field is +missing, it's obtained from the original entry label. If the +\field{sort} field is missing the default is obtained from the +\field{name} field. (As with \atentry{index}, \atentry{indexplural} +is \emph{not} governed by \csopt{entry-sort-fallback}.) +All fields are optional. For example: +\begin{codeenv} +\atentry{indexplural}\marg{goose, + \field{plural} = \marg{geese} +} +\strut +\atentry{indexplural}\marg{duck} +\strut +\atentry{indexplural}\marg{chateau, + \field{text} = \marg{ch\ics{cs.circum}ateau}, + \field{plural} = \marg{ch\cs{cs.circum}ateaux} +} +\end{codeenv} +This is equivalent to: +\begin{codeenv} +\atentry{indexplural}\marg{goose, + \field{name} = \marg{geese}, + \field{text} = \marg{goose}, + \field{plural} = \marg{geese} +} +\strut +\atentry{indexplural}\marg{duck, + \field{name} = \marg{ducks}, + \field{text} = \marg{duck}, + \field{plural} = \marg{ducks} +} +\strut +\atentry{indexplural}\marg{chateau, + \field{name} = \marg{ch\cs{cs.circum}ateaux}, + \field{text} = {ch\cs{cs.circum}ateau}, + \field{plural} = {ch\cs{cs.circum}ateaux} +} +\end{codeenv} + +Terms that are defined using \atentry{indexplural} will be written to the output +file using the command \gls!{bibglsnewindexplural}. + +\entrysection{abbreviation} + +The \atentry{abbreviation} entry type is designed for abbreviations. +The required fields are \field{short} and \field{long}. If the +\field{sort} key is missing, \bibgls\ will use the field given by +\csopt{abbreviation-sort-fallback}, which defaults to the \field{short} field. +(If you want an equivalent of \gls!{newdualentry}, use +\atentry{dualabbreviationentry} instead.) + +If you use \csopt[name]{sort-field} (rather than the default +\csopt[sort]{sort-field}), then the fallback for the +\field{name} field is always the \field{short} field, regardless of +the \csopt{abbreviation-sort-fallback} setting, unless you use +\csopt{abbreviation-name-fallback} to change the fallback for the +\field{name} field. + +Note that you must set the abbreviation style before loading the +resource file to ensure that the abbreviations are defined +correctly, however \bibgls\ has no knowledge of the abbreviation +style so it doesn't know if the \field{description} field must be +included or if the default \field{sort} value isn't simply the value +of the \field{short} field. + +You can instruct \bibgls\ to sort by the \field{long} field instead +using \csopt[long]{abbreviation-sort-fallback}. You can also tell \bibgls\ to +ignore certain fields using \csopt{ignore-fields}, so you can +include a \field{description} field in the \ext{bib} file if +you sometimes need it, and then instruct \bibgls\ to ignore it when +you don't want it. + +For example: +\begin{codeenv} +\atentry{abbreviation}\marg{html, + \field{short} = \marg{html}, + \field{long} = \marg{hypertext markup language}, + \field{description} = \marg{a markup language for creating web pages} +} +\end{codeenv} +If you want the \abbrstyle{long-noshort-desc} style, then you can put +the following in your document (where the \ext{bib} file is called +\filefmt{entries-abbrv.bib}): +\begin{codeenv} +\ics{setabbreviationstyle}\marg{long-noshort-desc} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries-abbrv]{src}, + \csopt[long]{abbreviation-sort-fallback}} +\end{codeenv} +Whereas, if you want the \abbrstyle{long-short-sc} style, then you can +instead do: +\begin{codeenv} +\cs{setabbreviationstyle}\marg{long-short-sc} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries-abbrv]{src},\csopt[description]{ignore-fields}} +\end{codeenv} +or to convert the short value to \idx{uppercase} and use the +\abbrstyle{long-short-sm} style instead: +\begin{codeenv} +\cs{setabbreviationstyle}\marg{long-short-sm} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries-abbrv]{src}, + \csopt[uc]{short-case-change},\comment{convert short value to upper case} + \csopt[description]{ignore-fields}} +\end{codeenv} + +Case-changing can be applied with \csopt{short-case-change} to +convert the case of the \field{short} field, as illustrated above. +If you use a style that obtains the \field{description} from the +\field{long} form, but you want to apply a case-change to the +\field{description} field with \csopt{description-case-change}, then +you can copy the \field{long} field to the \field{description} with +\csopt[\field{long}=\field{description}]{replicate-fields}. + +For example, if \filefmt{entries-abbrv.bib} contains: +\begin{codeenv} +\atentry{abbreviation}\marg{html, + \field{short} = \marg{html}, + \field{long} = \marg{hypertext markup language} +} +\end{codeenv} +then the document may include: +\begin{codeenv} +\cs{setabbreviationstyle}\marg{long-short-sc} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries-abbrv]{src}, + \csopt[firstuc]{description-case-change}, + \csopt[\field{long}=\field{description}]{replicate-fields}} +\end{codeenv} +Note that this can cause a problem for styles that set the +\field{description} field to the \field{long} form encapsulated by a +style command (such as with the \abbrstyle{long-em-short-em} style) +as this will override the style setting. + +Similarly, if you want to change the case of the \field{name} field: +\begin{codeenv} +\cs{setabbreviationstyle}\marg{long-short-sc} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries-abbrv]{src}, + \csopt[firstuc]{description-case-change}, + \csopt[uc]{name-case-change}, + \csopt[\field{long}=\field{description},\field{short}=\field{name}]{replicate-fields}} +\end{codeenv} +Again, this will lose any custom formatting command that would +usually be applied by the abbreviation style to the \field{name} +field (and \field{description}, if applicable). + +Terms defined using \atentry{abbreviation} will be written to the output +file using the command \gls!{bibglsnewabbreviation}. + +\entrysection{acronym} + +The \atentry{acronym} entry type is like \atentry{abbreviation} except that +the term is written to the output file using the command +\gls!{bibglsnewacronym}. + +\entrysection{contributor} + +The \atentry{contributor} entry type is primarily provided for use +by the \atentry{bibtexentry} type. You may use it explicitly +if you want, but you need to take care that it doesn't clash with +\atentry{bibtexentry}. It behaves much like \atentry{index} except that the +term is written to the \ext{glstex} file using the command +\gls!{bibglsnewcontributor}. There are no required fields. As with +\atentry{index}, if the \field{name} field is missing, the fallback +value is the entry's label. When this entry type is automatically +created by \atentry{bibtexentry}, the \field{name} is set to +\begin{codeenv} +\gls{bibglscontributor}\margm{forenames}\margm{von}\margm{surname}\margm{suffix} +\end{codeenv} + +If you do explicitly use \atentry{contributor} you need to make sure it's +defined \emph{before} the first instance of \atentry{bibtexentry} that +tries to access it, but within the same resource set. If you ensure that +the label of \atentry{contributor} matches the contributor label generated by +\atentry{bibtexentry} then they can have their dependency lists +updated, and +the \field{bibtexentry} and \field{bibtexentry@entrytype} internal +fields can be set for the +\atentry{contributor} entry. For example: +\begin{codeenv} +\atentry{contributor}\marg{KnuthDonaldE, + \field{name}=\marg{\gls{bibglscontributor}\marg{Donald E.}\marg{}\marg{Knuth}\marg{}}, + \field{description}=\marg{Famous mathematician and computer scientist who + created \cmd{TeX}} +} +\strut +@book\marg{texbook, + title = \marg{The {\cmd{TeX} book}}, + author = \marg{Donald E. Knuth}, + publisher = \marg{Addison-Wesley}, + year = 1986 +} +\end{codeenv} +The resource options then need to include: +\begin{codeenv} + \csopt[\ics{GlsXtrBibTeXEntryAliases}]{entry-type-aliases}, + \csopt[ + \marg{[ \cs{cs.string}\csfmt{-}\cs{cs.string}\csfmt{.}]}\marg{} + ]{labelify-replace} +\end{codeenv} + +If the \atentry{contributor} entry is deferred until after the +corresponding \atentry{bibtexentry} then you will end up with a label clash. + +\section{Dual Entry Types} +\label{sec:dualentry} + +The entry types described in this section create two separate (but +related) \styfmt{glossaries-extra} entry definitions per \ext{bib} +entry. The first of these entries is considered the +\idx{primary} entry, and the second is the \idx{dual} entry +(also referred to as the \idx{secondary} entry, but is not +related to the \csopt{secondary} option). The naming scheme is +\code{@dual}\meta{entry-type} where both the primary and dual are +considered to have the same type of entry (such as +\atentry{dualsymbol} where both the primary and dual are +functionally like \atentry{symbol}) or +\code{@dual}\meta{primary}\meta{dual} where the primary +is functionally like \code{@}\meta{primary} and the dual is +functionally like \code{@}\meta{dual}. + +For example: +\begin{codeenv} +\atentry{dualabbreviationentry}\marg{svm, + \field{short} = \marg{SVM}, + \field{long} = \marg{support vector machine}, + \field{description} = \marg{statistical pattern recognition technique} +} +\end{codeenv} +is like: +\begin{codeenv} +\atentry{abbreviation}\marg{svm, + \field{short} = \marg{SVM}, + \field{long} = \marg{support vector machine}, +} +\atentry{entry}\marg{dual.svm, + \field{text} = \marg{SVM}, + \field{name} = \marg{support vector machine}, + \field{description} = \marg{statistical pattern recognition technique} +} +\end{codeenv} +and is analogous to: +\begin{codeenv} +\gls{newabbreviation}\marg{svm}\marg{SVM}\marg{support vector machine} +\gls{newglossaryentry}\marg{dual.svm}\marg{\field{name}=\marg{support vector machine},\field{text}=\marg{SVM}, + \field{description}=\marg{statistical pattern recognition technique}} +\end{codeenv} +but both entries are considered dependent on each other. This means +that if you only reference the primary entry (using \ics{gls} etc) +then the dual entry will still be selected if the \csopt{selection} +setting includes dependencies. + +The creation of the dual entry involves mapping or copying fields +from the primary entry. Each dual entry type has a set of mappings. +If a field in the set of mappings is missing, its fallback value is +used. Any fields that aren't listed in the mappings are simply copied, +except for the \field{alias} field, which will never be copied to +the dual entry, nor can it be mapped. The alias will only apply to +the primary entry. The dual entry is given the label +\meta{prefix}\meta{id} where \meta{prefix} is set by the +\csopt{dual-prefix} option and \meta{id} is the label supplied in +the \ext{bib} file. + +If \csopt[combine]{dual-sort} then the dual entries will be sorted +along with the primary entries, otherwise the \csopt{dual-sort} +indicates how to sort the dual entries and the dual entries will be +appended to the end of the \ext{glstex} file. The +\csopt{dual-sort-field} determines what field to use for the sort +value if the dual entries should be sorted separately. + +Take care if you have a mixture of entry types (such as +\atentry{dualindexentry}, \atentry{dualindexsymbol} +and \atentry{index}) and you're not +using the default \csopt[combine]{dual-sort}. Remember that the +primary entries are all sorted together along with the single +entries types described in \sectionref{sec:dualentry} (but they may +be assigned to different glossary types), and then the dual entries +are sorted together (but may be assigned to different glossary +types). This may result in an odd ordering if some of the primaries +and some of the duals are assigned to the same glossary. For +example, don't mix \atentry{dualindexabbreviation} (duals are +abbreviations) with \atentry{dualabbreviationentry} (primaries +are abbreviations) when you aren't using \csopt[combine]{dual-sort} +(unless you have two different glossaries for the primary vs dual +abbreviations). + +Remember that \bibgls\ is designed to take advantage of +\ics{printunsrtglossary}, which simply iterates over all defined +entries in the order in which they were defined (or, more precisely, +the order of the internal list of entry labels associated with that +glossary). The aim of \bibgls\ is to write the entry definitions to +the \ext{glstex} file so that the internal list of labels is in the +appropriate order. + +For example, suppose the file \filefmt{entries.bib} contains: +\begin{codeenv} +\atentry{index}\marg{aardvark} +\atentry{index}\marg{mouse} +\atentry{index}\marg{zebra} +\atentry{dualindexabbreviation}\marg{xml, + \field{short}=\marg{XML}, + \field{long}=\marg{extensible markup language} +} +\atentry{dualabbreviationentry}\marg{ssi, + \field{short}=\marg{SSI}, + \field{long}=\marg{server-side includes}, + \field{description}=\marg{directives placed in \cs{gls}\marg{html} pages + evaluated by the server} +} +\atentry{dualindexabbreviation}\marg{html, + \field{short}=\marg{HTML}, + \field{long}=\marg{hypertext markup language} +} +\atentry{dualabbreviationentry}\marg{css, + \field{short}=\marg{CSS}, + \field{long}=\marg{cascading stylesheets}, + \field{description}=\marg{a language that describes the style of an + \cs{gls}\marg{html} document} +} +\end{codeenv} +This contains a mixture of entry types, including +\atentry{dualindexabbreviation} (where the dual is the +abbreviation) and \atentry{dualabbreviationentry} (where the +primary is the abbreviation). + +Now consider the following document: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[\styopt{record},\styopt{abbreviations}]\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[all]{selection},\csopt[entries]{src}} +\strut +\cmd{begin}\marg{document} +\cs{printunsrtglossaries} +\cmd{end}\marg{document} +\end{codeenv} +This uses the default \csopt[combine]{sort}, so all the entries are +sorted together, resulting in the order: +\code{aardvark}, +\code{dual.css}, +\code{css}, +\code{html}, +\code{dual.html}, +\code{mouse}, +\code{dual.ssi}, +\code{ssi}, +\code{xml}, +\code{dual.xml}, +\code{zebra}. + +The \LaTeX\ code written to the \iext{glstex} file is essentially +(but not exactly): +\begin{codeenv} +\comment{from \atentry{index}\marg{aardvark}:} +\gls{newglossaryentry}\marg{aardvark}\marg{\field{name}=\marg{aardvark},\field{description}=\marg{}} +\strut +\comment{dual of \atentry{dualabbreviationentry}\marg{css,\ldots}:} +\gls{newglossaryentry}\marg{dual.css}\marg{\field{name}=\marg{cascading stylesheets},\marg{text}=\marg{CSS}, + \field{description}=\marg{a language that describes the style of an + \cs{glsxtrshort}\marg{html} document}} +\strut +\comment{primary of \atentry{dualabbreviationentry}\marg{css,\ldots}:} +\gls{newabbreviation}\marg{css}\marg{CSS}\marg{cascading stylesheets} +\strut +\comment{primary of \atentry{dualindexabbreviation}\marg{html,\ldots}:} +\gls{newglossaryentry}\marg{html}\marg{\field{name}=\marg{HTML},\field{description}=\marg{}} +\strut +\comment{dual of \atentry{dualindexabbreviation}\marg{html,\ldots}:} +\gls{newabbreviation}\marg{dual.html}\marg{HTML}\marg{hypertext markup language} +\strut +\comment{from \atentry{index}\marg{mouse}:} +\gls{newglossaryentry}\marg{mouse}{\marg{name}=\marg{mouse},\field{description}=\marg{}} +\strut +\comment{dual of \atentry{dualabbreviationentry}\marg{ssi,\ldots}:} +\gls{newglossaryentry}\marg{dual.ssi}\marg{\field{name}=\marg{server-side includes},\field{text}=\marg{SSI}, + \field{description}=\marg{directives placed in \cs{glsxtrshort}\marg{html} pages + evaluated by the server}} +\strut +\comment{primary of \atentry{dualabbreviationentry}\marg{ssi,\ldots}:} +\gls{newabbreviation}\marg{ssi}\marg{SSI}\marg{server-side includes} +\strut +\comment{primary of \atentry{dualindexabbreviation}\marg{xml,\ldots}:} +\gls{newglossaryentry}\marg{xml}\marg{\field{name}=\marg{XML},\field{description}=\marg{}} +\strut +\comment{dual of \atentry{dualindexabbreviation}\marg{xml,\ldots}:} +\gls{newabbreviation}\marg{dual.xml}\marg{XML}\marg{extensible markup language} +\strut +\comment{from \atentry{index}\marg{zebra}:} +\gls{newglossaryentry}\marg{zebra}\marg{\field{name}=\marg{zebra},\field{description}=\marg{}} +\end{codeenv} +Since the document uses the \styopt{abbreviations} package option, +\gls{newabbreviation} automatically assigns the abbreviation +to the \code{abbreviations} glossary (created through that package +option). This means that the \code{main} (default) glossary +contains the entries (in order): +\begin{itemize} +\item \code{aardvark} (name: aardvark), +\item \code{dual.css} (name: cascading stylesheets), +\item \code{html} (name: HTML), +\item \code{mouse} (name: mouse), +\item \code{dual.ssi} (name: server-side includes), +\item \code{xml} (name: XML), +\item \code{zebra} (name: zebra). +\end{itemize} +The \code{abbreviations} glossary contains: +\begin{itemize} +\item \code{css} (short: CSS), +\item \code{dual.html} (short: HTML), +\item \code{ssi} (short: SSI), +\item \code{dual.xml} (short: XML). +\end{itemize} + +Since all the entries were combined and sorted together, the +resulting glossaries are both ordered alphabetically (using +\field{short} for the abbreviations and \field{name} for the rest), +but note that you need to take care when referencing the +abbreviations if you want to make use of the abbreviation style. You +need \verb|\gls{css}| and \verb|\gls{ssi}| for the primary +abbreviations created with \atentry{dualabbreviationentry} and +\verb|\gls{dual.html}| and \verb|\gls{dual.xml}| for the dual +abbreviations created with \atentry{dualindexabbreviation}. Also +the \field{name} of the primary\slash dual alternative of the +abbreviations is also inconsistent (short form for \code{html} and +\code{xml} and long form for \code{dual.css} and \code{dual.ssi}), +as different field mappings are used. + +If the document is changed so that the dual entries are now +sorted and written after all the primary entries have been dealt +with: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src}, + \csopt[letter-nocase]{dual-sort}, + \csopt[all]{selection} +} +\end{codeenv} +then \bibgls\ first orders the primaries: +\begin{itemize} +\item \code{aardvark} (name: aardvark), +\item \code{css} (short: CSS), +\item \code{html} (name: HTML), +\item \code{mouse} (name: mouse), +\item \code{ssi} (short: SSI), +\item \code{xml} (name: XML), +\item \code{zebra} (name: zebra) +\end{itemize} +and writes them to the \ext{glstex} file +(functionally like): +\begin{codeenv} +\comment{from \atentry{index}\marg{aardvark}:} +\gls{newglossaryentry}\marg{aardvark}\marg{\field{name}=\marg{aardvark},\field{description}=\marg{}} +\strut +\comment{primary of \atentry{dualabbreviationentry}\marg{css,\ldots}:} +\gls{newabbreviation}\marg{css}\marg{CSS}\marg{cascading stylesheets} +\strut +\comment{primary of \atentry{dualindexabbreviation}\marg{html,\ldots}:} +\gls{newglossaryentry}\marg{html}\marg{\field{name}=\marg{HTML},\field{description}=\marg{}} +\strut +\comment{from \atentry{index}\marg{mouse}:} +\gls{newglossaryentry}\marg{mouse}\marg{\field{name}=\marg{mouse},\field{description}=\marg{}} +\strut +\comment{primary of \atentry{dualabbreviationentry}\marg{ssi,\ldots}:} +\gls{newabbreviation}\marg{ssi}\marg{SSI}\marg{server-side includes} +\strut +\comment{primary of \atentry{dualindexabbreviation}\marg{xml,\ldots}:} +\gls{newglossaryentry}\marg{xml}\marg{\field{name}=\marg{XML},\field{description}=\marg{}} +\strut +\comment{from \atentry{index}\marg{zebra}:} +\gls{newglossaryentry}\marg{zebra}\marg{\field{name}=\marg{zebra},\field{description}=\marg{}} +\end{codeenv} +Then \bibgls\ orders the duals: +\begin{itemize} +\item \code{dual.css} (name: cascading stylesheets), +\item \code{dual.html} (short: HTML), +\item \code{dual.ssi} (name: server-side includes), +\item \code{dual.xml} (short: XML) +\end{itemize} +and writes them to the \ext{glstex} file +(functionally like): +\begin{codeenv} +\comment{dual of \atentry{dualabbreviationentry}\marg{css,\ldots}:} +\gls{newglossaryentry}\marg{dual.css}\marg{\field{name}=\marg{cascading stylesheets},\field{text}=\marg{CSS}, + \field{description}=\marg{a language that describes the style of an + \cs{glsxtrshort}\marg{html} document}} +\strut +\comment{dual of \atentry{dualindexabbreviation}\marg{html,\ldots}:} +\gls{newabbreviation}\marg{dual.html}\marg{HTML}\marg{hypertext markup language} +\strut +\comment{dual of \atentry{dualabbreviationentry}\marg{ssi,\ldots}:} +\gls{newglossaryentry}\marg{dual.ssi}\marg{\field{name}=\marg{server-side includes},\field{text}=\marg{SSI}, + \field{description}=\marg{directives placed in \cs{glsxtrshort}\marg{html} pages + evaluated by the server}} +\strut +\comment{dual of \atentry{dualindexabbreviation}\marg{xml,\ldots}:} +\gls{newabbreviation}\marg{dual.xml}\marg{XML}\marg{extensible markup language} +\end{codeenv} +When the \ext{glstex} file is input (during the next \LaTeX\ run) +the entries are defined in the order: +\begin{enumerate} +\item \code{aardvark} (type: \code{main}), +\item \code{css} (type: \code{abbreviations}), +\item \code{html} (type: \code{main}), +\item \code{mouse} (type: \code{main}), +\item \code{ssi} (type: \code{abbreviations}), +\item \code{xml} (type: \code{main}), +\item \code{zebra} (type: \code{main}), +\item \code{dual.css} (type: \code{main}), +\item \code{dual.html} (type: \code{abbreviations}), +\item \code{dual.ssi} (type: \code{main}), +\item \code{dual.xml} (type: \code{abbreviations}). +\end{enumerate} +This means that the \code{main} glossary's internal list is in the +order: +\begin{itemize} +\item \code{aardvark} (aardvark), +\item \code{html} (HTML), +\item \code{mouse} (mouse), +\item \code{xml} (XML), +\item \code{zebra} (zebra), +\item \code{dual.css} (cascading stylesheets), +\item \code{dual.ssi} (server-side includes) +\end{itemize} +and the \code{abbreviations} glossary's internal list is in the order: +\begin{itemize} +\item \code{css} (CSS), +\item \code{ssi} (SSI), +\item \code{dual.html} (HTML), +\item \code{dual.xml} (XML). +\end{itemize} +The lists are no longer in alphabetical order as they have a mixture +of primary and dual entries that were separated before sorting. + +The above is a fairly contrived example as it wouldn't make sense +in a real document to have glossary terms (that include a +description) mixed with index terms (that don't include a +description). +A better solution would be to use +\atentry{tertiaryindexabbreviationentry} instead of +\atentry{dualabbreviationentry}. + +\entrysection{dualentry} + +The \atentry{dualentry} entry type is similar to \atentry{entry} but +actually defines two entries. +The dual entry contains the same information as the primary entry +but some of the fields are swapped around. +The default mappings are: +\begin{itemize} +\item \field{name} $\mapsto$ \field{description} +\item \field{plural} $\mapsto$ \field{descriptionplural} +\item \field{description} $\mapsto$ \field{name} +\item \field{descriptionplural} $\mapsto$ \field{plural} +\end{itemize} +The required fields are as for \atentry{entry}. + +For example: +\begin{codeenv} +\atentry{dualentry}\marg{child, + \field{name}=\marg{child}, + \field{plural}=\marg{children}, + \field{description}=\marg{enfant} +} +\end{codeenv} +is like: +\begin{codeenv} +\atentry{entry}\marg{child, + \field{name}=\marg{child}, + \field{plural}=\marg{children}, + \field{description}=\marg{enfant} + \field{descriptionplural}=\marg{enfants} +} +\strut +\atentry{entry}\marg{dual.child, + \field{description}=\marg{child}, + \field{descriptionplural}=\marg{children}, + \field{name}=\marg{enfant} + \field{plural}=\marg{enfants} +} +\end{codeenv} +where \idprefix{dual} is replaced by the value of the +\csopt{dual-prefix} option. However, instead of defining the entries +with \csfmt{bibglsnewentry} both the primary and dual entries are +defined using \gls!{bibglsnewdualentry}. The \field{category} +and \field{type} fields can be set for the dual entry using the +\csopt{dual-category} and \csopt{dual-type} options. + +For example: +\begin{codeenv} +\cs{newglossary*}\marg{english}\marg{English} +\cs{newglossary*}\marg{french}\marg{French} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries-dual]{src},\comment{data in entries-dual.bib} + \csopt[english]{type},\comment{put primary entries in glossary 'english'} + \csopt[french]{dual-type},\comment{put dual entries in glossary 'french'} + \csopt[dictionary]{category},\comment{set the primary category to 'dictionary'} + \csopt[dictionary]{dual-category},\comment{set the dual category to 'dictionary'} + \csopt[en]{sort},\comment{sort primary entries according to language 'en'} + \csopt[fr]{dual-sort}\comment{sort dual entries according to language 'fr'} +} +\end{codeenv} + +\entrysection{dualindexentry} + +There are no required fields. The primary +entry behaves like \atentry{index} and the dual entry behaves +like \atentry{entry}. The default field mapping is: +\begin{itemize} +\item \field{name} $\mapsto$ \field{name} +\end{itemize} +This doesn't actually perform any swapping of fields, but it +provides the field used for backlinks (if +\csopt{dual-indexentry-backlink} is set). The reason that the primary +(rather than the dual) is like \atentry{index} is to allow the +primaries to merge with any \atentry{index} entries found in the +resource set, since glossary entries with descriptions are likely to +be a subset of all indexed entries. + +If no \field{name} is given, the dual entry is assigned the +(unprefixed) entry label. For example: +\begin{codeenv} +\atentry{dualindexentry}\marg{array, + \field{description}=\marg{ordered list of values} +} +\end{codeenv} +This is effectively like: +\begin{codeenv} +\atentry{index}\marg{array} +\strut +\atentry{entry}\marg{dual.array, + \field{name}=\marg{array}, + \field{description}=\marg{ordered list of values} +} +\end{codeenv} +The primary entries are defined using +\gls!{bibglsnewdualindexentry}, +which by default sets the \field{category} to \optfmt{index} +(although this may be overridden, for example, by the \csopt{category} option). +The dual entries are defined with +\gls!{bibglsnewdualindexentrysecondary}. + +This is the most convenient way of having an entry that's also +automatically indexed. For example, suppose the file +\filefmt{terms.bib} contains: +\begin{codeenv} +\atentry{index}\marg{duck} +\atentry{index}\marg{zebra} +\atentry{index}\marg{aardvark} +\end{codeenv} +and suppose the file \filefmt{entries.bib} contains: +\begin{codeenv} +\atentry{dualindexentry}\marg{array, + \field{description}=\marg{ordered list of values} +} +\strut +\atentry{dualindexentry}\marg{vector, + \field{name}=\marg{vector}, + \field{description}=\marg{column or row of values} +} +\strut +\atentry{dualindexentry}\marg{set, + \field{description}=\marg{collection of values} +} +\strut +\atentry{dualindexentry}\marg{matrix, + \field{plural}=\marg{matrices}, + \field{description}=\marg{rectangular array of values} +} +\end{codeenv} +These entries can be used in an example document that has an +index and a glossary: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[colorlinks]\marg{hyperref} +\cmd{usepackage}[\styopt{record},\styopt{index},\styopt[mcols]{stylemods}]\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[terms,entries]{src}, + \csopt[index]{type}, + \csopt[idx.]{label-prefix}, + \csopt[gls.]{dual-prefix}, + \csopt[primary]{combine-dual-locations}, + \csopt[main]{dual-type} +} +\strut +\cmd{begin}\marg{document} +\cs{gls}\marg{gls.array}, \cs{gls}\marg{gls.vector}, \cs{gls}\marg{gls.set}, \cs{gls}\marg{gls.matrix}. +\strut +\cs{gls}\marg{idx.duck}, \cs{gls}\marg{idx.aardvark}, \cs{gls}\marg{idx.zebra}. +\strut +\cs{renewcommand}\marg{\cs{glstreenamefmt}}[1]\marg{\ics{textsc}\marg{\idx{param}1}} +\cs{printunsrtglossary}\oarg{\printglossopt[main]{type},\printglossopt[index]{style},\iprintglossopt{nogroupskip}} +\strut +\cs{renewcommand}\marg{\cs{glstreenamefmt}}[1]\marg{\idx{param}1} +\cs{renewcommand}\marg{\cs{glstreegroupheaderfmt}}[1]\marg{\cs{textbf}\marg{\idx{param}1}} +\cs{printunsrtglossary}\oarg{\printglossopt[index]{type},\printglossopt[mcolindexgroup]{style}} +\cmd{end}\marg{document} +\end{codeenv} +This uses \csopt{combine-dual-locations} to combine the locations +for the primary and dual entries so that they only appear in the +index. + +To avoid the inconvenience of remembering which prefix to use, you can +set up the prefixes with \ics{glsxtraddlabelprefix} and reference entries +with \ics{dgls}, \ics{dGls} etc instead of \cs{gls}, \cs{Gls} etc. + +\entrysection{dualindexabbreviation} + +The \atentry{dualindexabbreviation} entry type is similar to +\atentry{dualindexentry} and again, by default, the +field mapping is: +\begin{itemize} +\item \field{name} $\mapsto$ \field{name} +\end{itemize} +However in this case the required fields are \field{short} and +\field{long}. The \field{name} for the primary entry defaults to +\field{short} if omitted. (This may be changed with the +\csopt{abbreviation-name-fallback} option.) The fallback for the +\field{sort} field is given by \csopt{abbreviation-sort-fallback}, +which defaults to the \field{short} field. + +For example: +\begin{codeenv} +\atentry{dualindexabbreviation}\marg{html, + \field{short} = \marg{HTML}, + \field{long} = \marg{hypertext markup language} +} +\end{codeenv} +is like: +\begin{codeenv} +\atentry{index}\marg{html,\field{name}=\marg{HTML}} +\strut +\atentry{abbreviation}\marg{dual.html, + \field{short} = \marg{HTML}, + \field{long} = \marg{hypertext markup language} +} +\end{codeenv} +The primary term is defined using +\gls!{bibglsnewdualindexabbreviation}, which encapsulates the +\field{name} to match the font used by +the dual abbreviation. The encapsulation command depends +on the \csopt{abbreviation-name-fallback} value. If it's +the \field{short} field then \gls{bibglsuseabbrvfont} is +used, otherwise \gls{bibglsuselongfont} is used. + +The primary definition also +by default sets the \field{category} to \optfmt{index} (although +this again may be overridden). +The dual term is defined using +\gls!{bibglsnewdualindexabbreviationsecondary}. + +\entrysection{dualindexsymbol} + +The \atentry{dualindexsymbol} entry type is similar to +\atentry{dualindexentry}, but by default the +field mappings are: +\begin{itemize} +\item \field{symbol} $\mapsto$ \field{name} +\item \field{name} $\mapsto$ \field{symbol} +\item \field{symbolplural} $\mapsto$ \field{plural} +\item \field{plural} $\mapsto$ \field{symbolplural} +\end{itemize} +The required field is: \field{symbol}. +If the \field{name} field is omitted, the dual entry is assigned a +symbol from the original (unprefixed) label. +The primary entries are defined using +\gls!{bibglsnewdualindexsymbol}, +which by default sets the \field{category} to \optfmt{index}, +and the dual entries are defined using +\gls!{bibglsnewdualindexsymbolsecondary}, +which by default sets the \field{category} to \optfmt{symbol}. +For example: +\begin{codeenv} +\atentry{dualindexsymbol}\marg{pi, + \field{symbol}=\marg{\cs{ensuremath}\marg{\ics{pi}}}, + \field{description}=\marg{ratio of a circle's circumference to its diameter} +} +\end{codeenv} +is like: +\begin{codeenv} +\atentry{index}\marg{pi,\field{symbol}=\marg{\cs{ensuremath}\marg{\cs{pi}}}} +\strut +\atentry{symbol}\marg{dual.pi, + \field{name}=\marg{\cs{ensuremath}\marg{\cs{pi}}}, + \field{symbol}=\marg{pi}, + \field{description}=\marg{ratio of a circle's circumference to its diameter} +} +\end{codeenv} + +For example, suppose I have a file called \filefmt{symbols.bib} that +contains: +\begin{codeenv} +\atentry{dualindexsymbol}\marg{pi, + \field{symbol}=\marg{\cs{ensuremath}\marg{\cs{pi}}}, + \field{description}=\marg{ratio of a circle's circumference to its diameter} +} +\strut +\atentry{dualindexsymbol}\marg{e, + \field{name}=\marg{Euler's number}, + \field{symbol}=\marg{\cs{ensuremath}\marg{e}}, + \field{description}=\marg{base of the natural logarithm} +} +\end{codeenv} +Then the previous example document can be modified to have an index, +a glossary and a list of symbols: +\begin{codeenv} +\cmd{documentclass}\marg{report} +\strut +\cmd{usepackage}[colorlinks]\marg{hyperref} +\cmd{usepackage}[\styopt{record},\styopt{symbols},\styopt{index},\styopt[mcols]{stylemods}]\marg{glossaries-extra} +\strut +\cs{newcommand}\marg{\gls{bibglsnewdualindexsymbolsecondary}}[5]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{category}=symbol,\comment{} + \field{symbol}=\marg{\idx{param}4},\idx{param}2,\field{type}=\marg{symbols}}\marg{\idx{param}5}\comment{} +} +\strut +\cs{newcommand}\marg{\cmd{indexprimary}}[1]\marg{\ics{glsadd}\oarg{\glsaddopt[\encap{hyperbf}]{format}}\marg{idx.\idx{param}1}} +\strut +\cs{glsdefpostdesc}\marg{symbol}\marg{\cmd{indexprimary}\marg{\cs{glscurrententrylabel}}} +\cs{glsdefpostdesc}\marg{general}\marg{\cmd{indexprimary}\marg{\cs{glscurrententrylabel}}} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries,terms,symbols]{src}, + \csopt[index]{type}, + \csopt{set-widest}, + \csopt[idx.]{label-prefix}, + \csopt[\empty]{dual-prefix}, + \csopt[primary]{combine-dual-locations}, + \csopt[letter-case]{dual-sort}, + \csopt[main]{dual-type} +} +\strut +\gls{glsxtrnewglslike}\oarg{\glsopt[false]{hyper}}\marg{idx.}\marg{\cmd{idx}}\marg{\cmd{idxpl}}\marg{\cmd{Idx}}\marg{\cmd{Idxpl}} +\strut +\cmd{begin}\marg{document} +\cs{gls}\marg{array}, \cs{gls}\marg{vector}, \cs{gls}\marg{set}, \cs{glspl}\marg{matrix}. +\cmd{idx}\marg{duck}, \cmd{idx}\marg{aardvark}, \cmd{idx}\marg{zebra}. +\cs{gls}\marg{e} and \cs{gls}\marg{pi}. +\strut +\cmd{newpage} +\cs{gls}\marg{array}, \cmd{idx}\marg{vector}, \cmd{idx}\marg{set}, \cs{gls}\marg{matrix}. +\strut +\cmd{newpage} +\cs{gls}\marg{array}, \cs{gls}\marg{vector}, \cs{gls}\marg{set}, \cs{gls}\marg{matrix}. +\strut +\cs{renewcommand}\marg{\cs{glstreenamefmt}}[1]\marg{\cs{textsc}\marg{\idx{param}1}} +\cs{printunsrtglossary}\oarg{\printglossopt[main]{type},\printglossopt{nogroupskip},\printglossopt[\glostyle{alttree}]{style}} +\strut +\cs{renewcommand}\marg{\cs{glstreenamefmt}}[1]\marg{\idx{param}1} +\cs{printunsrtglossary}\oarg{\printglossopt[symbols]{type},\printglossopt{nogroupskip},\printglossopt[index]{style}} +\strut +\cs{renewcommand}\marg{\cs{glstreenamefmt}}[1]\marg{\idx{param}1} +\cs{renewcommand}\marg{\cs{glstreegroupheaderfmt}}[1]\marg{\cs{textbf}\marg{\idx{param}1}} +\cs{printunsrtglossary}\oarg{\printglossopt[index]{type},\printglossopt[\glostyle{mcolindexgroup}]{style}} +\strut +\cmd{end}\marg{document} +\end{codeenv} +Here I've provided some convenient commands for referencing the +primary (index) terms (\csfmt{idx}, \csfmt{idxpl}, \csfmt{Idx} +and \csfmt{Idxpl}). This means I don't need to worry about the +label prefix and it also switches off the hyperlinks (with +\code{\glsopt[false]{hyper}}). These custom +commands are defined using: +\nosecformatdef{glsxtrnewglslike} +which, in this case, essentially does: +\begin{codeenv} +\cs{newcommand}\marg{\cmd{idx}}[2][]\marg{\cs{gls}\oarg{\glsopt[false]{hyper},\idx{param}1}\marg{idx.\idx{param}2}} +\cs{newcommand}\marg{\cmd{Idx}}[2][]\marg{\cs{Gls}\oarg{\glsopt[false]{hyper},\idx{param}1}\marg{idx.\idx{param}2}} +\cs{newcommand}\marg{\cmd{idxpl}}[2][]\marg{\cs{glspl}\oarg{\glsopt[false]{hyper},\idx{param}1}\marg{idx.\idx{param}2}} +\cs{newcommand}\marg{\cmd{Idxpl}}[2][]\marg{\cs{Glspl}\oarg{\glsopt[false]{hyper},\idx{param}1}\marg{idx.\idx{param}2}} +\end{codeenv} +but the new commands will also recognise the \ics{gls} modifiers, so +\verb|\idx+| will behave like \verb|\gls+| which wouldn't be +possible if \csfmt{idx} was defined using \ics{newcommand} in the +above manner. There's a similar command: +\nosecformatdef{glsxtrnewgls} +if no case-changing versions are required. + +I've also redefined \gls!{bibglsnewdualindexsymbolsecondary} to put +the dual entries created with \atentry{dualindexsymbol} into +the \code{symbols} glossary (which is created with the +\styopt{symbols} package option), so it overrides the +\csopt[main]{dual-type} setting. + +This command also sets the \field{category} +to \code{symbol}, so I can redefine the post-description hook +for symbols (\ics{glsxtrpostdescsymbol}) to automatically index +the symbol definition. Similarly for the \code{general} +post-description hook \ics{glsxtrpostdescgeneral}. + +Since the post-description hook isn't done until the glossary has +been created, this requires a slightly longer build process. If the +document file is called \filefmt{myDoc.tex}, then the complete +document build is: +\begin{verbatim} +pdflatex myDoc +bib2gls -g myDoc +pdflatex myDoc +bib2gls -g myDoc +pdflatex myDoc +\end{verbatim} + +As from \sty{glossaries-extra-bib2gls} version 1.37, an alternative +method is to identify possible label prefixes with +\ics{glsxtraddlabelprefix} or \ics{glsxtrprependlabelprefix} and use +\ics{dgls}, \ics{dglspl}, \ics{dGls} or \ics{dGlspl}. See the +\styfmt{glossaries-extra} user manual~\cite{glossaries-extra} for +further details. + +\entrysection{dualindexnumber} + +The \atentry{dualindexnumber} entry type is almost identical to +\atentry{dualindexsymbol}, but the primary entries are defined using +\gls!{bibglsnewdualindexnumber}, +which by default sets the \field{category} to \optfmt{index}, +and the dual entries are defined using +\gls!{bibglsnewdualindexnumbersecondary}, +which by default sets the \field{category} to \optfmt{number}. + +\entrysection{dualabbreviationentry} + +The \atentry{dualabbreviationentry} entry type is similar to +\atentry{dualentry}, but by default the +field mappings are: +\begin{itemize} +\item \field{long} $\mapsto$ \field{name} +\item \field{longplural} $\mapsto$ \field{plural} +\item \field{short} $\mapsto$ \field{text} +\end{itemize} +You may need to add a mapping from \field{shortplural} to +\field{plural} if the default is inappropriate. +(In \bibgls\ version 1.0 this entry type was originally called +\atentry{dualentryabbreviation}. In version 1.1, it was renamed +\atentry{dualabbreviationentry} which makes for a more consistent naming scheme +\code{@dual}\meta{primary}\meta{dual}.) + +The required fields are: \field{short}, \field{long} and +\field{description}. This entry type is designed to emulate the +example \gls{newdualentry} command given in the \sty{glossaries} +user manual~\cite{glossaries}. The primary entry is an abbreviation with the given +\field{short} and \field{long} fields (but not the +\field{description}) and the secondary entry is a regular entry with +the \field{name} copied from the \field{long} field. +The fallback for the \field{sort} is given by +\csopt{abbreviation-sort-fallback}, which defaults to the +\field{short} field. + +For example: +\begin{codeenv} +\atentry{dualabbreviationentry}\marg{svm, + \field{long} = \marg{support vector machine}, + \field{short} = \marg{SVM}, + \field{description} = \marg{statistical pattern recognition technique} +} +\end{codeenv} +is rather like doing: +\begin{codeenv} +\atentry{abbreviation}\marg{svm, + \field{long} = \marg{support vector machine}, + \field{short} = \marg{SVM} +} +\strut +\atentry{entry}\marg{dual.svm, + \field{name} = \marg{support vector machine}, + \field{description} = \marg{statistical pattern recognition technique} +} +\end{codeenv} +but \code{dual.svm} will automatically be selected if \code{svm} +is indexed in the document. If \code{dual.svm} isn't explicitly +indexed, it won't have a location list. + +If the \field{sort} field is missing \bibgls\ by default falls back +on the \field{name} field. If this is missing, this sort value will +fallback on the \field{short} field. This means that if \field{name} +isn't explicitly given in \atentry{dualabbreviationentry}, then the +primary entry will be sorted according to \field{short} but the dual +will be sorted according its \field{name} (which has been copied +from the primary \field{long}). + +Entries provided using \atentry{dualabbreviationentry} will be defined +with: +\begin{codeenv} +\gls{bibglsnewdualabbreviationentry} +\end{codeenv} +(which uses \gls{newabbreviation}) for the primary entries and with : +\begin{codeenv} +\gls{bibglsnewdualabbreviationentrysecondary} +\end{codeenv} +(which uses \gls{longnewglossaryentry}) for the secondary entries. +This means that if the \styopt{abbreviations} +package option is used, the primary entry will be put in the +\optfmt{abbreviations} glossary and the secondary entry in the +\optfmt{main} glossary. Use the \csopt{type} and +\csopt{dual-type} options to override this. + +\entrysection{dualentryabbreviation} + +This entry type is deprecated as from \bibgls\ version 1.1. It's functionally +equivalent to \atentry{dualabbreviationentry} but its name +doesn't fit the general dual entry naming scheme. + +\entrysection{dualsymbol} + +This is like \atentry{dualentry} but the default mappings are: +\begin{itemize} +\item \field{name} $\mapsto$ \field{symbol} +\item \field{plural} $\mapsto$ \field{symbolplural} +\item \field{symbol} $\mapsto$ \field{name} +\item \field{symbolplural} $\mapsto$ \field{plural} +\end{itemize} +The \field{name} and \field{symbol} fields are required. +For example: +\begin{codeenv} +\atentry{dualsymbol}\marg{pi, + \field{name}=\marg{pi}, + \field{symbol}=\marg{\cs{ensuremath}\marg{\cs{pi}}}, + \field{description}=\marg{the ratio of the length of the circumference + of a circle to its diameter} +} +\end{codeenv} + +Entries are defined using \gls!{bibglsnewdualsymbol}, which by +default sets the \field{category} to \optfmt{symbol}. + +\entrysection{dualnumber} + +This is almost identical to \atentry{dualsymbol} but entries are +defined using \gls!{bibglsnewdualnumber}, which by default sets +the \field{category} to \optfmt{number}. + +The above example could be defined as a number since $\pi$ is a +constant: +\begin{codeenv} +\atentry{dualnumber}\marg{pi, + \field{name}=\marg{pi}, + \field{symbol}=\marg{\cs{ensuremath}\marg{\cs{pi}}}, + \field{description}=\marg{the ratio of the length of the circumference + of a circle to its diameter}, + \field{user1}=\marg{3.14159} +} +\end{codeenv} + +This has stored the approximate value in the \field{user1} field. +The post-description hook could then be adapted to show this. +\begin{codeenv} +\cs{glsdefpostdesc}\marg{number}\marg{\comment{} + \cs{ifglshasfield}\marg{useri}\marg{\cs{glscurrententrylabel}} + \marg{ (approximate value: \cs{glscurrentfieldvalue})}\comment{} + \marg{}\comment{} +} +\end{codeenv} + +This use of the \field{user1} field means that the dual entries +could be sorted numerically according to the approximate value: +\begin{codeenv} +\cmd{usepackage}[\styopt{record},\styopt{postdot},\styopt{numbers},\styopt[index]{style}]\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{entries.bib} + \csopt[numbers]{dual-type}, + \csopt[double]{dual-sort},\comment{decimal sort} + \csopt[user1]{dual-sort-field} +} +\end{codeenv} + +\entrysection{dualabbreviation} + +The \atentry{dualabbreviation} entry type is similar to +\atentry{dualentry}, but by default the +field mappings are: +\begin{itemize} +\item \field{short} $\mapsto$ \field{dualshort} +\item \field{shortplural} $\mapsto$ \field{dualshortplural} +\item \field{long} $\mapsto$ \field{duallong} +\item \field{longplural} $\mapsto$ \field{duallongplural} +\item \field{dualshort} $\mapsto$ \field{short} +\item \field{dualshortplural} $\mapsto$ \field{shortplural} +\item \field{duallong} $\mapsto$ \field{long} +\item \field{duallongplural} $\mapsto$ \field{longplural} +\end{itemize} +The required fields are: \field{short}, \field{long}, +\field{dualshort} and \field{duallong}. +This includes some new fields: \field{dualshort}, +\field{dualshortplural}, \field{duallong} and +\field{duallongplural}. If these aren't already defined, they +will be provided in the \iext{glstex} file with +\begin{codeenv} +\ics{glsxtrprovidestoragekey}\margm{key}\marg{}\marg{} +\end{codeenv} +Note that this use with an empty third argument prevents +the creation of a field access command (analogous to +\ics{glsentrytext}). The value can be accessed with +\ics{glsxtrusefield} instead. Remember that the field won't be +available until the \ext{glstex} file has been created. + +Note that \bibgls\ doesn't know what abbreviation styles +are in used, so if the \field{sort} field is missing +it will fallback on the \field{short} field. If the abbreviations +need to be sorted according to the \field{long} field instead, +use \csopt[long]{abbreviation-sort-fallback}. + +Terms that are defined using \atentry{dualabbreviation} will be +written to the output file using \gls!{bibglsnewdualabbreviation}. + +If the \csopt{dual-abbrv-backlink} option is on, the default field +used for the backlinks is the \field{dualshort} field, so you'll need +to make sure you adapt the glossary style to show that field. The +simplest way to do this is through the category \idx{postdescriptionhook}. + +For example, if the entries all have the \field{category} set +to \optfmt{abbreviation}, then this requires redefining +\ics{glsxtrpostdescabbreviation} (either with \cs{renewcommand} +or via \cs{glsdefpostdesc}). + +Here's an example dual abbreviation for a document where English is +the primary language and German is the secondary language: +\begin{codeenv} +\atentry{dualabbreviation}\marg{rna, + \field{short}=\marg{RNA}, + \field{dualshort}=\marg{RNS}, + \field{long}=\marg{ribonucleic acid}, + \field{duallong}=\marg{Ribonukleins\"aure} +} +\end{codeenv} +If the abbreviation is in the file called +\filefmt{entries-dual-abbrv.bib}, then here's an example document: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[T1]\marg{fontenc} +\cmd{usepackage}[utf8]\marg{inputenc} +\strut +\cmd{usepackage}[ngerman,main=english]\marg{babel} +\cmd{usepackage}[colorlinks]\marg{hyperref} +\cmd{usepackage}[\styopt{record},\styopt{nomain}]\marg{glossaries-extra} +\strut +\cs{newglossary*}\marg{english}\marg{English} +\cs{newglossary*}\marg{german}\marg{German} +\strut +\cs{setabbreviationstyle}\marg{long-short} +\strut +\cs{glsdefpostdesc}\marg{abbreviation}\marg{\comment{} + \cs{ifglshasfield}\marg{dualshort}\marg{\cs{glscurrententrylabel}} + \marg{\comment{} + \cmd{space}(\cs{glscurrentfieldvalue})\comment{} + }\comment{} + \marg{}\comment{} +} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries-dual-abbrv]{src},\comment{entries-dual-abbrv.bib} + \csopt[english]{type},\comment{put primary entries in glossary 'english'} + \csopt[german]{dual-type},\comment{put primary entries in glossary 'german'} + \csopt[en.]{label-prefix},\comment{primary label prefix} + \csopt[de.]{dual-prefix},\comment{dual label prefix} + \csopt[en]{sort},\comment{sort primary entries according to language 'en'} + \csopt[de-1996]{dual-sort},\comment{sort dual entries according to 'de-1996'} + \comment{(German new orthography)} + \csopt{dual-abbrv-backlink}\comment{add links in the glossary to the opposite entry} +} +\strut +\cmd{begin}\marg{document} +\strut +English: \cs{gls}\marg{en.rna}; \cs{gls}\marg{en.rna}. +\strut +German: \cs{gls}\marg{de.rna}; \cs{gls}\marg{de.rna}. +\strut +\cs{printunsrtglossaries} +\cmd{end}\marg{document} +\end{codeenv} +If the \csopt{label-prefix} is omitted, then only the dual entries +will have a prefix: +\begin{codeenv} +English: \cs{gls}\marg{rna}; \cs{gls}\marg{rna}. +\strut +German: \cs{gls}\marg{de.rna}; \cs{gls}\marg{de.rna}. +\end{codeenv} +Another variation is to use the \abbrstyle{long-short-user} +abbreviation style and modify the associated \ics{glsxtruserfield} so that +the \field{duallong} field is selected for the parenthetical +material: +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{glsxtruserfield}}\marg{duallong} +\end{codeenv} +This means that the first use of the primary entry is displayed as +\begin{quote} +ribonucleic acid (RNA, Ribonukleins\"aure) +\end{quote} +and the first use of the dual entry is displayed as: +\begin{quote} +Ribonukleins\"aure (RNS, ribonucleic acid) +\end{quote} + +Here's an example to be used with the \abbrstyle{long-short-desc} +style: +\begin{codeenv} +\atentry{dualabbreviation}\marg{rna, + \field{short}=\marg{RNA}, + \field{dualshort}=\marg{RNS}, + \field{long}=\marg{ribonucleic acid}, + \field{duallong}=\marg{Ribonukleins\"aure} + \field{description}=\marg{a polymeric molecule}, + \field{user1}=\marg{Ein polymeres Molek\"ul} +} +\end{codeenv} +This stores the dual description in the \field{user1} field, +so this needs a mapping. +The new example document is much the same as the previous one, except +that the \csopt{dual-abbrv-map} option is needed to include the +mapping between the \field{description} and \field{user1} fields: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[T1]\marg{fontenc} +\cmd{usepackage}[utf8]\marg{inputenc} +\strut +\cmd{usepackage}[ngerman,main=english]\marg{babel} +\cmd{usepackage}[colorlinks]\marg{hyperref} +\cmd{usepackage}[\styopt{record},\styopt{nomain}]\marg{glossaries-extra} +\strut +\cs{newglossary*}\marg{english}\marg{English} +\cs{newglossary*}\marg{german}\marg{German} +\strut +\cs{setabbreviationstyle}\marg{long-short-desc} +\strut +\cs{glsdefpostdesc}\marg{abbreviation}\marg{\comment{} + \cs{ifglshasfield}\marg{dualshort}\marg{\cs{glscurrententrylabel}} + \marg{\comment{} + \cmd{space}(\cs{glscurrentfieldvalue})\comment{} + }\comment{} + \marg{}\comment{} +} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries-dual-abbrv-desc]{src},\comment{entries-dual-abbrv-desc.bib} + \csopt[english]{type},\comment{put primary entries in glossary 'english'} + \csopt[german]{dual-type},\comment{put primary entries in glossary 'german'} + \csopt[en.]{label-prefix},\comment{primary label prefix} + \csopt[de.]{dual-prefix},\comment{dual label prefix} + \csopt[en]{sort},\comment{sort primary entries according to language 'en'} + \csopt[long]{abbreviation-sort-fallback},\comment{fallback on 'long' field} + \csopt[de-1996]{dual-sort},\comment{sort dual entries according to 'de-1996'} + \comment{(German new orthography)} + \csopt{dual-abbrv-backlink},\comment{add links in the glossary to the opposite entry} +\comment{ dual key mappings:} + \csopt[\comment{} + \marg{short,shortplural,long,longplural,dualshort,dualshortplural, + duallong,duallongplural,description,user1}, + \marg{dualshort,dualshortplural,duallong,duallongplural,short,shortplural, + long,longplural,user1,description} + ]{dual-abbrv-map} +} +\strut +\cmd{begin}\marg{document} +\strut +English: \cs{gls}\marg{en.rna}; \cs{gls}\marg{en.rna}. +\strut +German: \cs{gls}\marg{de.rna}; \cs{gls}\marg{de.rna}. +\strut +\cs{printunsrtglossaries} +\cmd{end}\marg{document} +\end{codeenv} +Note that since this document uses the \abbrstyle{long-short-desc} +abbreviation style, the \csopt{abbreviation-sort-fallback} needs to be changed +to \optfmt{long}. + +If I change the order of the mapping to: +\begin{codeenv} + \csopt[\comment{} + \marg{long,longplural,short,shortplural,dualshort,dualshortplural, + duallong,duallongplural,description,user1}, + \marg{duallong,duallongplural,dualshort,dualshortplural,short,shortplural, + long,longplural,user1,description} + ]{dual-abbrv-map} +\end{codeenv} +Then the back-link field will switch to \field{duallong}. The +\idx{postdescriptionhook} can be modified to allow for this: +\begin{codeenv} +\cs{glsdefpostdesc}\marg{abbreviation}\marg{\comment{} + \cs{ifglshasfield}\marg{duallong}\marg{\cs{glscurrententrylabel}} + \marg{\comment{} + \cmd{space}(\cs{glscurrentfieldvalue})\comment{} + }\comment{} + \marg{}\comment{} +} +\end{codeenv} + +An alternative is to use the \abbrstyle{long-short-user-desc} style +without the \idx!{postdescriptionhook}: +\begin{codeenv} +\cs{setabbreviationstyle}\marg{long-short-user-desc} +\cs{renewcommand}*\marg{\cs{glsxtruserfield}}\marg{duallong} +\end{codeenv} +However be careful with this approach as it can cause nested +hyperlinks. In this case it's better to use the +\abbrstyle{long-postshort-user-desc} style which defers the +parenthetical material until after the link-text: +\begin{codeenv} +\cs{setabbreviationstyle}\marg{long-postshort-user-desc} +\cs{renewcommand}*\marg{\cs{glsxtruserfield}}\marg{duallong} +\end{codeenv} +If the back-link field has been switched to \field{duallong} then +the \idx!{postdescriptionhook} is no longer required. + +\entrysection{dualacronym} + +As \atentry{dualabbreviation} but defines the entries with +\gls!{bibglsnewdualacronym}. + +\section{Tertiary Entry Types} +\label{sec:tertiaryentry} + +A tertiary entry type is essentially a dual entry that creates three +separate (but related) \styfmt{glossaries-extra} entry definitions per +\ext{bib} entry. As with dual entries, the first and second of these +are the primary and secondary. The third of these is the +\idx{tertiary} which is effectively an appendage of the +secondary, and is defined by the same associated +\csfmt{bibglsnew\ldots secondary} command that defines the secondary +entry. Therefore the secondary and tertiary are both considered the +dual and are treated as a single entry for the purposes of sorting +and collating. + +The tertiary entry will never have any locations. Any records found +will be assigned to the secondary (and may then be moved to the +primary with \csopt[primary]{combine-dual-locations}). The tertiary +will always have the same order as the secondary and will have the same +\field{group} value. You can set the \field{type} for the tertiary +with \csopt{tertiary-type} and the \field{category} with +\csopt{tertiary-category}. The label prefix defaults to +\idprefix{tertiary} and can be changed with \csopt{tertiary-prefix}. + +\entrysection{tertiaryindexabbreviationentry} + +This entry type is very similar to +\atentry{dualindexabbreviation} but creates a tertiary entry as +well. The required fields are: \field{short} and \field{long} (as for +\atentry{dualindexabbreviation}) and also \field{description}. The +mappings are shared by both entry types. For example: +\begin{codeenv} +\atentry{tertiaryindexabbreviationentry}\marg{html, + \field{short} = \marg{HTML}, + \field{long} = \marg{hypertext markup language}, + \field{description} = \marg{a markup language for creating web pages} +} +\end{codeenv} +is analogous to: +\begin{codeenv} +\gls{newglossaryentry}\marg{html,\field{name}=\marg{HTML},\field{description}=\marg{}} +\strut +\gls{newabbreviation}\marg{dual.html}\marg{HTML}\marg{hypertext markup language} +\strut +\gls{newglossaryentry}\marg{tertiary.html, + \field{name}=\marg{hypertext markup language}, + \field{description}=\marg{a markup language for creating web pages} +} +\end{codeenv} +The last two are actually defined using one command: +\begin{codeenv} +\gls{bibglsnewtertiaryindexabbreviationentrysecondary} + \marg{dual.html}\comment{secondary label} + \marg{tertiary.html}\comment{tertiary label} + \marg{\ldots}\comment{secondary fields} + \marg{\ldots}\comment{tertiary fields} + \marg{HTML}\comment{primary name} + \marg{HTML}\comment{short} + \marg{hypertext markup language}\comment{long} + \marg{a markup language for creating web pages}\comment{description} +\end{codeenv} +The \gls!{bibglsnewtertiaryindexabbreviationentrysecondary} +command is provided in the \iext{glstex} file as: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewtertiaryindexabbreviationentrysecondary}}[8]\marg{\comment{} + \gls{newabbreviation}\oarg{\idx{param}3}\marg{\idx{param}1}\marg{\idx{param}6}\marg{\idx{param}7}\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}2}\comment{} + \marg{\field{name}=\marg{\cmd{protect}\gls{bibglsuselongfont}\marg{\idx{param}7}\marg{\ics{glscategory}\marg{\idx{param}1}}},\idx{param}4}\comment{} + \marg{\idx{param}8}\comment{} +} +\end{codeenv} +which defines the secondary as an abbreviation using +\csfmt{newabbreviation} and the tertiary as a regular entry using +\csfmt{longnewglossaryentry}. This means that the tertiary entry is +always defined immediately after the corresponding secondary entry. +The primary may be defined earlier or later in the file depending on the +way the entries are sorted and on the \csopt{dual-sort} setting. + +\section{Multi-Entry Types} +\label{sec:multientry} + +A multi-entry type is an entry that may spawn multiple +primary entries. This means that both the main entry and the +spawned entries are sorted together along with all the other primary +entries. In the case of \atentry{spawndualindexentry}, the main and +spawned entries are primary. The main entry's dual is created as per +\atentry{dualindexentry}. + +\entrysection{bibtexentry} + +The \atentry{bibtexentry} type will typically need to be aliased +as it's designed for converting \BibTeX\ entries into \bibgls\ +entries. For example, to make \bibgls\ treat \atentryfmt{article} +and \atentryfmt{book} as though they were both +\atentry{bibtexentry}: +\begin{codeenv} +\csopt[ + article=bibtexentry, + book=bibtexentry +]{entry-type-aliases} +\end{codeenv} +For convenience, \isty{glossaries-extra-bib2gls} v1.29+ +provides \ics{GlsXtrBibTeXEntryAliases} which covers all the +standard \BibTeX\ entry types. Alternatively, you can use +\csopt[bibtexentry]{unknown-entry-alias} to alias all entries +that aren't recognised by \bibgls. If you use +\csopt[same as original entry]{category}, the \field{category} +field will be set to the original entry type (for example, +\code{article} or \code{book}). Similarly you can use +\csopt[same as original entry]{type} to set the \field{type} +field (but remember that the glossary types will need to be defined +in the document). + +There are no required fields. The fallback for the \field{sort} +field is given by \csopt{bibtexentry-sort-fallback}. If you want to +access any of the \BibTeX\ fields, you will need to alias or define +them. For example: +\begin{codeenv} +\csopt[ + \fieldfmt{title}=\field{name} +]{field-aliases} +\end{codeenv} +Since \BibTeX's \fieldfmt{type} field conflicts with \bibgls's +\field{type} field, when \bibgls\ parses \atentry{bibtexentry} +if will convert \fieldfmt{type} to \field{bibtextype}, so you +must use \field{bibtextype} as the identifier when aliasing. + +Alternatively, you can use \ics{GlsXtrProvideBibTeXFields} which +uses \ics{glsaddstoragekey} to provide all the standard \BibTeX\ +fields. (Remember that new fields must be defined before the first +\idx{resourceset}.) + +The \atentry{bibtexentry} essentially creates an \atentry{index} +form of entry, but it additionally defines a \atentry{contributor} +entry for each listed author or editor +and updates the dependency lists: each \atentry{contributor} is +added to the main +\atentry{bibtexentry}'s list of dependencies (so if the +\atentry{bibtexentry} has a record then all its satellite +\atentry{contributor}s are selected with the default +\csopt[recorded and deps]{selection}), and +each \atentry{contributor} is treated as having a cross-reference to +the main \atentry{bibtexentry} (so if a \atentry{contributor} +has a record then all the linked \atentry{bibtexentry} terms will +be selected if \csopt[recorded and deps and see]{selection}). +You can instruct \bibgls\ to treat \ics{citation} as an +\idx{ignoredrecord} using \longarg{cite-as-record}. + +Each contributor is effectively defined as: +\begin{codeenv} +\atentry{contributor}\marg{\meta{label}, + \field{name}=\marg{\gls{bibglscontributor}\margm{forenames}\margm{von}\margm{surname}\margm{suffix}} +} +\end{codeenv} +The label is obtained by converting the \field{name} +to a label, using the same function as \csopt{labelify} (which +means it's governed by \csopt{labelify-replace}). + +The \fieldfmt{author} and \fieldfmt{editor} fields are always +checked, even if those fields aren't recognised by \bibgls, (which +they aren't by default). These checks are performed before field +aliases are applied. If neither field is present, no additional +entries are spawned. If the dependent \atentry{contributor} entry +has already been defined, it won't be redefined, but will have the +new \atentry{bibtexentry} added to its internal \field{bibtexentry} +field. + +The main \atentry{bibtexentry} is defined using +\gls{bibglsnewbibtexentry} and is followed by: +\begin{codeenv} +\gls{glsxtrfieldlistadd}\margm{id}\marg{bibtexcontributor}\margm{contributor-id} +\end{codeenv} +where \meta{id} is the label identifying the main +\atentry{bibtexentry} and \meta{contributor-id} is the +label identifying the contributor, for each contributor that has +been selected. + +Each contributor is defined using \gls{bibglsnewcontributor}. The definition +is followed by: +\begin{codeenv} +\gls{glsxtrfieldlistadd}\margm{contributor-id}\marg{bibtexentry}\margm{id} +\gls{glsxtrfieldlistadd}\margm{contributor-id}\marg{bibtexentry@\meta{entry-type}}\margm{id} +\end{codeenv} +for each selected \atentry{bibtexentry} associated with that contributor. The +second line provides the internal list field +\field{bibtexentry@entrytype}, where \meta{entry-type} is the +original entry type (before it was aliased to +\atentry{bibtexentry} and converted to \idx!{lowercase}). +For example \code{article} or \code{book}. + +You can iterate over these internal list fields using +\ics{glsxtrfielddolistloop} or \ics{glsxtrfieldforlistloop}. +For example: +\begin{codeenv} +\cs{newcommand}\marg{\csfmt{contributorhandler}}[1]\marg{\csfmt{par}\cs{glsentryname}\marg{\#1}} + +\cs{newcommand}\marg{\postdeschook{contributor}}\marg{\comment{} + \cs{glsxtrifhasfield}\marg{bibtexentry}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{\comment{} + \cs{glsxtrfieldforlistloop} + \marg{\cs{glscurrententrylabel}}\marg{bibtexentry}\comment{} + \marg{\csfmt{contributorhandler}}\comment{} + }\comment{} + \marg{\csfmt{par} No titles.}\comment{} +} +\end{codeenv} +(where the resource option \csopt[\fieldfmt{title}=\field{name}]{field-aliases} +has been used). + +Here's an example that uses the test \file{xampl.bib} file that's +provided with \TeX\ distributions: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[\styopt{record},\styopt{nomain}]\marg{glossaries-extra} +\strut +\cs{newglossary*}\marg{contributors}\marg{Authors/Editors} +\cs{newglossary*}\marg{titles}\marg{Titles} +\strut +\cs{newcommand}\marg{\gls{bibglsnewbibtexentry}}[4]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}={\idx{param}3},\idx{param}2,\field{type}=\marg{titles}}\marg{\idx{param}4}\comment{} +} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[xampl]{src}, + \csopt[false]{write-preamble}, + \csopt[ + \ics{GlsXtrBibTeXEntryAliases} + ]{entry-type-aliases}, + \csopt[ + \fieldfmt{title}=\field{name} + ]{field-aliases}, + \csopt[ + \fieldfmt{note}=\field{name} + ]{replicate-fields}, + \csopt[ + \marg{[ \cs{cs.string}\csfmt{-}\cs{cs.string}\csfmt{.}]}\marg{} + ]{labelify-replace}, + \csopt[contributors]{type}, + \csopt[same as original entry]{category}, + \csopt[\field{category}]{sort-field}, + \csopt[\field{name}]{sort-suffix} +} +\strut +\gls{glsxtrsetgrouptitle}\marg{article}\marg{Articles} +\gls{glsxtrsetgrouptitle}\marg{booklet}\marg{Booklets} +\gls{glsxtrsetgrouptitle}\marg{book}\marg{Books} +\gls{glsxtrsetgrouptitle}\marg{inbook}\marg{Book Chapters} +\gls{glsxtrsetgrouptitle}\marg{misc}\marg{Miscellaneous} +\strut +\cs{newcommand}\marg{\csfmt{contributorhandler}}[1]\marg{\csfmt{par}\ics{glsentryname}\marg{\idx{param}1} (\idx{param}1)} +\strut +\cs{newcommand}\marg{\postdeschook{contributor}}{\comment{} + \cs{glsxtrifhasfield}\marg{bibtexentry}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{\comment{} + \ics{glsxtrfieldforlistloop} + \marg{\cs{glscurrententrylabel}}\marg{bibtexentry}\comment{} + \marg{\csfmt{contributorhandler}}\comment{} + }\comment{} + \marg{\csfmt{par} No titles.}\comment{} +} +\strut +\csfmt{begin}\marg{document} +Sample\idx{nbspchar}\ics{cite}\marg{book-minimal,article-full,inbook-full,misc-minimal}. +Another sample\idx{nbspchar}\cs{cite}\marg{booklet-minimal,misc-full,article-minimal}. +\strut +\csfmt{bibliographystyle}\marg{plain} +\ics{bibliography}\marg{xampl} +\strut +\cs{printunsrtglossary}[\printglossopt[contributors]{type},\printglossopt[altlist]{style}] +\cs{printunsrtglossary*}[\printglossopt[titles]{type},\printglossopt[indexgroup]{style}] +\marg{\comment{} + \cs{renewcommand}\marg{\ics{glsxtrgroupfield}}\marg{category}\comment{} + \cs{renewcommand}\marg{\cs{glstreenamefmt}}[1]\marg{\cs{emph}\marg{\idx{param}1}}\comment{} + \cs{renewcommand}\marg{\cs{glstreegroupheaderfmt}}[1]\marg{\cs{textbf}\marg{\idx{param}1}}\comment{} +} +\strut +\csfmt{end}\marg{document} +\end{codeenv} +If the file is called \filefmt{myDoc.tex} then the document build +is: +\begin{codeenv} +pdflatex myDoc +bib2gls \longarg{cite-as-record} myDoc +bibtex myDoc +pdflatex myDoc +pdflatex myDoc +\end{codeenv} + +\entrysection{progenitor} + +The \atentryfmt{progenitor} type of entries are the only place where +the \field{adoptparents} field is permitted. The value should be a +comma-separated list of labels. The \field{adoptparents} field +must be set and must contain a least one label. If the value +contains any of the characters \idx{backslashchar} (backslash), +\idx{bgroupchar} (open brace) or \idx{egroupchar} (close brace) then +the field will be interpreted (if the default \longarg{interpret} settings +is on). + +Since entries are spawned before fields are processed, the +\field{adoptparents} field is parsed before any field aliases +(\csopt{field-aliases}) or replication (\csopt{replicate-fields}) +takes place. However, if the \field{adoptparents} field isn't found, +\bibgls\ will check for a simple mapping in both the +\csopt{field-aliases} and \csopt{replicate-fields} settings. + +This entry type creates a main \idx[textformat=emph]{progenitor} +term (with all the given fields except \field{adoptparents}) +and $n$ spawned \idx[textformat=emph]{progeny} terms, where +$n$ is the number of elements in the \field{adoptparents} field, +that are dependent on the main term. + +Each of the spawned \idx{progeny} entries have the field identified by +\csopt{adopted-parent-field} (\field{parent} by default) set to the +corresponding element in the \field{adoptparents} field. + +All fields from the original definition are copied except for the +\field{adoptparents}, \field{alias} and \field{parent} fields. The +\field{parent} field is never copied, regardless of the value of +\csopt{adopted-parent-field}. If the adopted parent field is +changed to one that's contained in the original entry, it's value +will be from \field{adoptparents} not the value from the original +entry. + +The copied fields follow the same conditions as normal +entries. (For example, unknown fields are ignored, case-changes are +applied, if appropriate, and the \field{type} field must reference a +valid glossary, if set.) If \csopt{progenitor-type} is set, then +this assignment is made after the \idx{progeny} are created +and only applies to the main \idx{progenitor} entry. The +type for the \idx{progeny} can be set with \csopt{progeny-type}. +For example, \csopt[same as parent]{progeny-type} will ensure +that the \idx{progeny} are in the same glossary type as +their parent entry. + +For example, an entry defined as: +\begin{codeenv} +\atentry{progenitor}\marg{\meta{id}, + \field{adoptparents} = \marg{\meta{parent-1 id},\ldots,\meta{parent-N id}}, + \meta{field-name-1} = \margm{text}, + \ldots + \meta{field-name-n} = \margm{text} +} +\end{codeenv} +is essentially like: +\begin{codeenv} +\atentry{index}\marg{\meta{id}, + \field{progeny} = \marg{\meta{parent-1 id}.\meta{id},\ldots,\meta{parent-N id}.\meta{id}}, + \meta{field-name-1} = \margm{text}, + \ldots + \meta{field-name-n} = \margm{text} +} +\strut +\atentry{index}\marg{\meta{parent-1 id}.\meta{id}, + \field{progenitor} = \margm{id}, + \field{parent} = \margm{parent-1 id}, + \meta{field-name-1} = \margm{text}, + \ldots + \meta{field-name-n} = \margm{text} +} +\strut +\ldots +\strut +\atentry{index}\marg{\meta{parent-N id}.\meta{id}, + \field{progenitor} = \margm{id}, + \field{parent} = \margm{parent-N id}, + \meta{field-name-1} = \margm{text}, + \ldots + \meta{field-name-n} = \margm{text} +} +\end{codeenv} +This creates the main (\idx{progenitor}) \meta{id} entry, which +contains all the fields (except for \field{adoptparents}) that were +in the original \atentry{progenitor} definition and has the new +field \field{progeny} set to the comma-separated list of spawned +entry labels. The main entries are defined in the \ext{glstex} file +with \gls{bibglsnewprogenitor}. + +In addition to the main \meta{id} entry, the above also creates the +spawned \idx{progeny} entries \code{\meta{parent-1 id}.\meta{id}}, \ldots, +\code{\meta{parent-N id}.\meta{id}} that are dependent on the main +\meta{id} entry. + +The spawned entries have the \field{parent} field set to the +corresponding label obtained from the \field{adoptparents} list. +This parent entry must also be defined, as usual for the +\field{parent} field. (This restriction obviously doesn't apply if +\csopt{adopted-parent-field} is changed from the default +\field{parent}.) The spawned entries are defined in the \ext{glstex} +file with \gls{bibglsnewspawnedindex} + +If the main \idx{progenitor} entry is referenced in the document +then (assuming the default selection criteria) the spawned entries +will also be automatically selected. You can check for the existence +of the \field{progenitor} field using \cs{glsxtrifhasfield} and +fetch the \field{location} field from the main entry, if required. + +Although the spawned entries are considered dependents of the main +entry, the reverse doesn't apply. If a spawned entry is referenced +in the document (with \code{\meta{parent-id}.\meta{id}}) then the +main entry and its other spawned entries aren't automatically +selected. + +For example, suppose the file \filefmt{entries.bib} contains: +\begin{codeenv} +\atentry{indexplural}\marg{stylesheet, \field{text}=\marg{stylesheet language}} +\strut +\atentry{index}\marg{webdesign, \field{name}=\marg{web design}} +\strut +\atentry{indexplural}\marg{markup, \field{text}=\marg{markup language}} +\strut +\atentry{progenitor}\marg{xml, + \field{name}=\marg{XML}, + \field{adoptparents}=\marg{markup} +} +\strut +\atentry{progenitor}\marg{css, + \field{name}=\marg{CSS}, + \field{adoptparents}=\marg{stylesheet,webdesign} +} +\strut +\atentry{progenitor}\marg{html, + \field{name}=\marg{HTML}, + \field{adoptparents}=\marg{markup,webdesign} +} +\strut +\atentry{progenitor}\marg{xsl, + \field{name}=\marg{XSL}, + \field{adoptparents}=\marg{stylesheet} +} +\end{codeenv} +and if the document contains: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\oarg{\styopt{record},\styopt[tree]{stylemods},\styopt[index]{style}}\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[all]{selection}} +\strut +\cs{newcommand}*\marg{\cs{glstreenamefmt}}[1]\marg{\idx{param}1} +\cmd{begin}\marg{document} +\cs{printunsrtglossaries} +\cmd{end}\marg{document} +\end{codeenv} +Then the resulting list will be: +\begin{quote} +\setlength{\parindent}{0pt}% +\setlength{\parskip}{0pt plus 0.3pt}% +\glstreeitem CSS\par +\glstreeitem HTML\par +\glstreeitem markup language\par +\glstreesubitem HTML\par +\glstreesubitem XML\par +\glstreeitem stylesheet language\par +\glstreesubitem CSS\par +\glstreesubitem XSL\par +\glstreeitem web design\par +\glstreesubitem CSS\par +\glstreesubitem HTML\par +\glstreeitem XML\par +\glstreeitem XSL\par +\end{quote} +This allows the HTML and CSS entries to be listed under multiple +parents. + +The following \atentryfmt{spawn\meta{single-type}} commands are all forms +of \atentry{progenitor} that create the given +\atentryfmt{\meta{single-type}} of entry. The spawned entries are actually +created with the private entry type \atentryfmt{spawned\meta{type}}. In the +case of \atentry{progenitor}, the spawned entries are defined as +a \atentryfmt{spawnedindex} entry. These special +\atentryfmt{spawned\meta{type}} entry types aren't intended for use +in the \ext{bib} file, but if you reference the entry type (for +example, with \csopt[same as entry]{category}) you will get +\atentryfmt{spawned\meta{type}} as the entry type. The +original entry type for the spawned entries is the same as +the original entry for the main \atentry{progenitor} entry. + +There is currently only one form of dual \atentry{progenitor} entry and that's +\atentry{spawndualindexentry}. Only the main \idx{progenitor} entry +is a dual entry. The spawned \idx{progeny} are all \atentry{index} +primary entries. + +\entrysection{spawnindex} + +As \atentry{progenitor}, but the main entries are defined in the +\ext{glstex} file with \gls{bibglsnewspawnindex} and the +spawned entries are defined with \gls{bibglsnewspawnedindex}. + +\entrysection{spawnindexplural} + +As \atentry{progenitor}, except that it creates +\atentry{indexplural} terms instead of \atentry{index}. +As with \atentry{indexplural}, if the \field{name} field isn't set, +it's assigned to the same value as the \field{plural} field (or the +fallback for the \field{plural}, if not defined). + +The main entries are defined in the +\ext{glstex} file with \gls{bibglsnewspawnindexplural} and the +spawned entries are defined with \gls{bibglsnewspawnedindexplural}. + +\entrysection{spawnentry} + +As \atentry{progenitor}, except that it creates +\atentry{entry} terms instead of \atentry{index}. +As with \atentry{entry}, the \field{description} field is required +and either \field{name} or \field{parent}. + +The main entries are defined in the +\ext{glstex} file with \gls{bibglsnewspawnentry} and the +spawned entries are defined with \gls{bibglsnewspawnedentry}. + +\entrysection{spawnabbreviation} + +As \atentry{progenitor}, except that it creates +\atentry{abbreviation} terms instead of \atentry{index}. +As with \atentry{abbreviation}, the \field{short} and \field{long} +fields are required. + +The main entries are defined in the +\ext{glstex} file with \gls{bibglsnewspawnabbreviation} and the +spawned entries are defined with \gls{bibglsnewspawnedabbreviation}. + +\entrysection{spawnacronym} + +As \atentry{progenitor}, except that it creates +\atentry{acronym} terms instead of \atentry{index}. +As with \atentry{acronym}, the \field{short} and \field{long} +fields are required. + +The main entries are defined in the +\ext{glstex} file with \gls{bibglsnewspawnacronym} and the +spawned entries are defined with \gls{bibglsnewspawnedacronym}. + +\entrysection{spawnsymbol} + +As \atentry{progenitor}, except that it creates +\atentry{symbol} terms instead of \atentry{index}. +As with \atentry{symbol}, the required fields are \field{name} or +\field{parent}, and the \field{description} field is required if the +\field{name} field is missing. + +The main entries are defined in the +\ext{glstex} file with \gls{bibglsnewspawnsymbol} and the +spawned entries are defined with \gls{bibglsnewspawnedsymbol}. + +\entrysection{spawnnumber} + +As \atentry{progenitor}, except that it creates +\atentry{number} terms instead of \atentry{index}. +As with \atentry{number}, the required fields are \field{name} or +\field{parent}, and the \field{description} field is required if the +\field{name} field is missing. + +The main entries are defined in the +\ext{glstex} file with \gls{bibglsnewspawnnumber} and the +spawned entries are defined with \gls{bibglsnewspawnednumber}. + +\entrysection{spawndualindexentry} + +As \atentry{progenitor}, except that the main (\idx{progenitor}) +entry behaves like \atentry{dualindexentry}. The spawned +\idx{progeny} behave like \atentry{index} are so are all considered primary +entries. The \field{adoptparents} field should therefore reference +primary entries with the default \csopt[parent]{adopted-parent-field}. + +The main primary and secondary (dual) entries are defined in the +\ext{glstex} file with +\gls{bibglsnewspawndualindexentry} and +\gls{bibglsnewspawndualindexentrysecondary}. The spawned +\idx{progeny} are defined with \gls{bibglsnewspawnedindex}. + +\chapter{Resource File Options} +\label{sec:resourceopts} + +Make sure that you use \isty{glossaries-extra} with the +\styopt{record} package option. This ensures that \bibgls\ can pick +up the required information from the \iext{aux} file, and both +\styopt[only]{record} and \styopt[nameref]{record} additionally +load the supplementary \isty{glossaries-extra-bib2gls} package. +These two \styopt{record} option values also +switch on the \styopt[none]{sort} package option (if you have a new +enough version of the base \isty{glossaries} package), which means +that there's no attempt to assign or process the \field{sort} key if +it's omitted from \gls{newglossaryentry} (or similar commands). The +\field{sort} key will be provided by \bibgls\ for informational +purposes, but there's no need for \LaTeX\ to write it to any +external files (unless you use the hybrid \styopt[alsoindex]{record}, +in which case you need to prevent \bibgls\ from sorting using the +\csopt[none]{sort} resource option). + +The \iext{glstex} resource files created by \bibgls\ are loaded in +the document using +\nosecformatdef{glsxtrresourcefile} +where \meta{filename} is the name of the resource file without the +\ext{glstex} extension. +You can have multiple \gls{glsxtrresourcefile} commands within your +document, but each \meta{filename} must be unique, otherwise \LaTeX\ +would attempt to input the same \ext{glstex} file multiple times +(\bibgls\ checks for non-unique file names). The associated data for each +resource file is called the \idx{resourceset} (see +\sectionref{sec:resourcesets}). + +There's a shortcut command that uses +\ics{jobname} in the \meta{filename}: +\nosecformatdef{GlsXtrLoadResources} +The first instance of this command is equivalent to: +\begin{codeenv} +\gls{glsxtrresourcefile}\oargm{options}\marg{\ics{jobname}} +\end{codeenv} +Any additional use of \gls{GlsXtrLoadResources} is equivalent to: +\begin{codeenv} +\gls{glsxtrresourcefile}\oargm{options}\marg{\ics{jobname}-\meta{n}} +\end{codeenv} +where \meta{n} is number. For example: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries-en]{src},\csopt[en]{sort}} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries-fr]{src},\csopt[fr]{sort}} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries-de]{src},\csopt[de-1996]{sort}} +\end{codeenv} +This is equivalent to: +\begin{codeenv} +\gls{glsxtrresourcefile}\oarg{\csopt[entries-en]{src},\csopt[en]{sort}}\marg{\cs{jobname}} +\gls{glsxtrresourcefile}\oarg{\csopt[entries-fr]{src},\csopt[fr]{sort}}\marg{\cs{jobname}-1} +\gls{glsxtrresourcefile}\oarg{\csopt[entries-de]{src},\csopt[de-1996]{sort}}\marg{\cs{jobname}-2} +\end{codeenv} +In general, it's simplest just to use \gls{GlsXtrLoadResources}. + +The optional argument \meta{options} is a comma-separated +\keyvallist. Allowed options are listed below. The option list +applies only to that specific \meta{filename}\ext{glstex} and are +not carried over to the next instance of \gls{glsxtrresourcefile}. +Only the definitions provided in \atentry{preamble} (if the +interpreter is on and \csopt[true]{interpret-preamble}) are carried +over to the next resource set and, possibly, +\idxpl{crossresourceref} if permitted (see +\sectionref{sec:resourcesets}). The \sty{glossaries-extra} package +doesn't parse the options, but just writes the information to the +\ext{aux} file. This means that any invalid options will be reported +by \bibgls\ not by \sty{glossaries-extra}. + +As from \sty{glossaries-extra} v1.40 you can provide a default set +of options by redefining: +\nosecdef{GlsXtrDefaultResourceOptions} +This command will be inserted at the start of the options list for +all resource commands (and will expand as it's written to +the \ext{aux} file). For example: +\begin{codeenv} +\cs{renewcommand}\marg{\gls{GlsXtrDefaultResourceOptions}}\marg{\comment{} + \csopt[all]{selection},\csopt[entries]{src}} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[symbols]{type}, + \csopt[entrytype=symbol]{match}} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[abbreviations]{type}, + \csopt[entrytype=abbreviation]{match}} +\end{codeenv} +This acts like: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[all]{selection},\csopt[entries]{src}, + \csopt[symbols]{type}, + \csopt[entrytype=symbol]{match}} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[all]{selection},\csopt[entries]{src}, + \csopt[abbreviations]{type}, + \csopt[entrytype=abbreviation]{match}} +\end{codeenv} + +If you have multiple \ext{bib} files you can either select them all +using \csopt[\meta{bib list}]{src} in a single +\gls{glsxtrresourcefile} call, if they all require the same settings, +or you can load them separately with different settings applied. + +For example, if the files \filefmt{entries-terms.bib} and +\filefmt{entries-symbols.bib} have the same settings: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries-terms,entries-symbols]{src}} +\end{codeenv} +Alternatively, if they have different settings: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries-terms]{src},\csopt[main]{type}} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries-symbols]{src},\csopt[use]{sort},\csopt[symbols]{type}} +\end{codeenv} + +Note that the sorting is applied to each \idx{resourceset} independently +of other \idxpl{resourceset}. This means that if you have multiple instances +of \gls{glsxtrresourcefile} but only one glossary type, the glossary +will effectively contain blocks of sorted entries. For example, if +\filefmt{file1.bib} contains: +\begin{codeenv} +\atentry{index}\marg{duck} +\atentry{index}\marg{zebra} +\atentry{index}\marg{aardvark} +\end{codeenv} +and \filefmt{file2.bib} contains: +\begin{codeenv} +\atentry{index}\marg{caterpillar} +\atentry{index}\marg{bee} +\atentry{index}\marg{wombat} +\end{codeenv} +then +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[file1,file2]{src}} +\end{codeenv} +will result in the list: aardvark, bee, caterpillar, duck, wombat, +zebra. These six entries are all defined when +\csfmt{jobname}\filefmt{.glstex} is read. +Whereas +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[file1]{src}} +\gls{GlsXtrLoadResources}\oarg{\csopt[file2]{src}} +\end{codeenv} +will result in the list: aardvark, duck, zebra, bee, caterpillar, +wombat. The first three (aardvark, duck, zebra) are defined when +\csfmt{jobname}\filefmt{.glstex} is read. The second three (bee, +caterpillar, wombat) are defined when \csfmt{jobname}\filefmt{-1.glstex} +is read. Since \ics{printunsrtglossary} simply iterates over all +defined entries, this is the ordering used. + +Abbreviation styles must be set (using \ics{setabbreviationstyle}) +before the resource command that selects the abbreviations from the +appropriate \ext{bib} file, since the entries are defined (through +\gls{newabbreviation} or \gls{newacronym}) when +\gls{glsxtrresourcefile} inputs the \ext{glstex} file. (Similarly for any +associated abbreviation style commands that must be set before +abbreviations are defined, such as \cs{glsxtrlongshortdescname}.) + +Note \bibgls\ allows \iext{bib} files that don't provide any entries. +This can be used to provide commands in \atentry{preamble}. +For example, suppose I have \filefmt{defs.bib} that just contains: +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{strong}}[1]\marg{\cs{textbf}\marg{\ics{cs.color}\marg{red}\idx{param}1}} +\cs{providecommand}\marg{\cmd{parenswap}}[2]\marg{\idx{param}2 (\idx{param}1)}}} +\end{codeenv} +This provides two commands: +\nosecdef{strong} +(which sets the font weight and colour) and +\nosecdef{parenswap} +(which just displays its second argument followed by the first in parentheses). + +Suppose I also have \filefmt{entries.bib} that contains: +\begin{codeenv} +\atentry{index}\marg{example, + \field{name}=\marg{\gls{strong}\marg{\gls{parenswap}\marg{stuff}\marg{example}}} +} +\atentry{index}\marg{sample} +\atentry{index}\marg{test} +\atentry{index}\marg{foo} +\atentry{index}\marg{bar} +\end{codeenv} +This contains an entry that requires the commands provided in +\filefmt{defs.bib}, so to ensure those commands are defined, I can +do: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[defs,entries]{src}} +\end{codeenv} +Unfortunately this results in the sort value for \code{example} being +set to \code{redexample (stuff)} because the interpreter has +detected the provided commands and expanded: +\begin{codeenv} +\gls{strong}\marg{\gls{parenswap}\marg{stuff}\marg{example}} +\end{codeenv} +to: +\begin{codeenv} +\cs{textbf}\marg{\cs{cs.color}\marg{red}example (stuff)} +\end{codeenv} +It discards font changes, so \cs{textbf} is ignored, but it doesn't +recognise \cs{cs.color} and so doesn't know that the first argument is +just the colour specifier and therefore doesn't discard it. +This means that \qt{\textbf{\color{red}example (stuff)}} is placed +between \qt{foo} and \qt{sample} instead of between \qt{bar} and +\qt{foo}. + +I can prevent the interpreter from parsing \atentry{preamble}: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[defs,entries]{src},\csopt[false]{interpret-preamble}} +\end{codeenv} +Now when the sort value for \code{example} is obtained from: +\begin{codeenv} +\gls{strong}\marg{\gls{parenswap}\marg{stuff}\marg{example}} +\end{codeenv} +no expansion occurs (since \gls{strong} and \gls{parenswap} are now +unrecognised) so the sort value ends up as: +\code{stuffexample} +which places \qt{\textbf{\color{red}example (stuff)}} between +\qt{sample} and \qt{test}, which is again incorrect. + +The best thing to do in this situation is to split the provided +commands into two \iext{bib} files: one that shouldn't be interpreted +and one that should. + +For example, \filefmt{defs-nointerpret.bib}: +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\gls{strong}}[1]\marg{\cs{textbf}\marg{\cs{cs.color}\marg{red}\idx{param}1}}}} +\end{codeenv} +and \filefmt{defs-interpret.bib}: +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\gls{parenswap}}[2]\marg{\idx{param}2 (\idx{param}1)}}} +\end{codeenv} +Now the first one can be loaded with \csopt[false]{interpret-preamble}: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[defs-nointerpret]{src},\csopt[false]{interpret-preamble}} +\end{codeenv} +This creates a \iext{glstex} file that provides \gls{strong} but +doesn't define any entries. The other file \filefmt{defs-interpret.bib} can +then be loaded with the default \csopt[true]{interpret-preamble}: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[defs-interpret,entries]{src}} +\end{codeenv} +The provided commands are remembered by the interpreter, so you can +also do: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[defs-interpret]{src}} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}} +\end{codeenv} +The \emph{contents} of \atentry{preamble} are only written to the +associated \iext{glstex} file, but the definitions contained within +the \atentry{preamble} are retained by the interpreter for subsequent +\idxpl{resourceset}. + +\section{General Options} +\label{sec:generalopts} + +\optsection{charset} + +If the character \idx{encoding} hasn't been supplied in the \iext{bib} file +with the encoding comment +\begin{alltt} +\idx{commentchar} Encoding: \meta{encoding-name} +\end{alltt} +then you can supply the correct encoding using +\csopt[encoding-name]{charset}. In general, it's better to include +the encoding in the \ext{bib} file where it can also be read by +a \ext{bib} managing systems, such as JabRef. + +See \longarg{tex-encoding} for the encoding used to write the \ext{glstex} +file. + +\optsection{interpret-preamble} + +This is a boolean option that determines whether or not the +interpreter should parse the contents of \atentry{preamble}. +The default is \optfmt{true}. If \optfmt{false}, the preamble +contents will still be written to the \iext{glstex} file, but any +commands provided in the preamble won't be recognised by the +interpreter (see \sectionref{sec:texparserlib}). + +Related options are: \csopt{set-widest} (which uses the interpreter to determine +the widest name for the \glostyle{alttree} style or the +\isty{glossary-longextra} styles), \csopt{interpret-label-fields} (which governs +whether or not fields that must only contain a label should be interpreted), +\csopt{labelify} (which converts a field into a string suitable for use as a +label), and \csopt{labelify-list} (which converts a field into a string suitable +for use as a comma-separated list of labels). + +\optsection{write-preamble} + +This is a boolean option that determines whether or not the +preamble should be written to the \ext{glstex} file. The default +is \optfmt{true}. Note that the preamble will +still be parsed if \csopt[true]{interpret-preamble} even if +\csopt[false]{write-preamble}. This means it's possible to +provide \bibgls\ command definitions in \atentry{preamble} +that don't get seen by \LaTeX. + +\optsection{set-widest} + +The \glostyle{alttree} glossary style needs to know the widest +\field{name} (for each level, if hierarchical). This can be set +using \ics{glssetwidest} provided by the \styfmt{glossary-tree} +package (or similar commands like \ics{glsupdatewidest} provided by +\styfmt{glossaries-extra-stylemods}), but this requires knowing +which name is the widest. Alternatively, one of the iterative commands +such as \ics{glsFindWidestTopLevelName} can be used, which slows the +document build as it has to iterate over all defined entries. + +The \isty{glossary-longextra} package, provided with +\sty{glossaries-extra} v1.37+, also needs to know the widest name, +but in this case only the top-level is needed. If this has already +been found through the commands provided with the \glostyle{alttree} +style then that value will be used as the default, but you can set another +value that's only used for the \sty{glossary-longextra} styles with +\ics{glslongextraSetWidest}. + +The \sty{glossaries-extra-bib2gls} package provides \ics{glsxtrSetWidest}, +which sets the widest name for those styles that need it. As from version +1.8, \bibgls\ now checks for the existence of this command and will use it with +\csopt{set-widest} to allow for the new styles provided by the +\sty{glossary-longextra} package. + +The boolean option \csopt[true]{set-widest} will try to calculate +the widest names for each hierarchical level to help remove the need +to determine the correct value within the document. +Since \bibgls\ doesn't know the fonts that will be used +in the document or if there are any non-standard commands that +aren't provided in the \ext{bib} files preamble, \emph{this option may not +work}. For example, if one entry has the \field{name} defined as: +\begin{codeenv} +\field{name}=\marg{some \marg{\cmd{Huge} huge} text} +\end{codeenv} +and another entry has the \field{name} defined as: +\begin{codeenv} +\field{name}=\marg{some \marg{\cmd{small} small} text} +\end{codeenv} +then \bibgls\ will determine that the second name is the widest +although the first will actually be wider when it's rendered in the +document. + +When using this option, the transcript file will include the message: +\begin{alltt} +Calculated width of '\meta{text}': \meta{number} +\end{alltt} +where \meta{text} is \bibgls's interpretation of the contents of the +\field{name} field and \meta{number} is a rough guide to the width +of \meta{text} assuming the operating system's default serif font. +The entry that has the largest \meta{number} is the one that will be +selected. This will then be implemented as follows: +\begin{itemize} +\item If the \field{type} is unknown then: + \begin{itemize} + \item if the interpreter resolves all \field{name} fields to the + empty string (that is the \field{name} fields all consist of + unknown commands) then + \begin{itemize} + \item if there are child entries \gls{bibglssetwidestfallback} + is used, + \item otherwise \gls{bibglssetwidesttoplevelfallback} is used; + \end{itemize} + \item otherwise \gls{bibglssetwidest} is used. + \end{itemize} +\item If the \field{type} is known then: + \begin{itemize} + \item if the interpreter resolves all \field{name} fields for that + type to the empty string (that is the \field{name} fields all consist of + unknown commands) then + \begin{itemize} + \item if there are child entries \gls{bibglssetwidestfortypefallback} + is used, + \item otherwise + \gls{bibglssetwidesttoplevelfortypefallback} is used; + \end{itemize} + \item otherwise \gls{bibglssetwidestfortype} is used. + \end{itemize} +\end{itemize} +This leaves \TeX\ to compute the width according to the document +fonts. If \bibgls\ can't correctly determine the widest entry then +you will need to use one of the commands provided by +\sty{glossary-tree}, \sty{glossary-longextra} or +\sty{glossaries-extra-stylemods} to set it. + +In general, if you have more than one glossary it's best to +set the \field{type} using options like \csopt{type} and +\csopt{dual-type} if you use \csopt{set-widest}. + +\optsection{entry-type-aliases} + +In the \ext{bib} file, the data is identified by +\code{@\meta{entry-type}}, such as \atentry[noindex]{abbreviation}. +It may be that you want to replace all instances of +\code{@\meta{entry-type}} with a different +type of entry. For example, suppose my \ext{bib} file +contains abbreviations defined in the form: +\begin{codeenv} +\atentry{abbreviation}\marg{html, + \field{short} = \marg{html}, + \field{long} = \marg{hypertext markup language}, + \field{description} = \marg{a markup language for creating web pages} +} +\end{codeenv} +but suppose in one of my documents I actually want all these +abbreviations defined with \atentry[noindex]{dualabbreviationentry} +instead of \atentry[noindex]{abbreviation}. Instead of editing +the \ext{bib} file I can just supply a mapping: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{data in entries.bib} + \csopt[abbreviation=dualabbreviationentry]{entry-type-aliases} +} +\end{codeenv} +This makes all instances of \atentry[noindex]{abbreviation} +behave as \atentry[noindex]{dualabbreviationentry}. You can have more than +one mapping. For example: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{data in entries.bib} + \csopt[ + \comment{\atentry{abbreviation} -> \atentry{dualabbreviationentry}:} + abbreviation=dualabbreviationentry, + \comment{\atentry{entry} -> \atentry{index}:} + entry=index + ]{entry-type-aliases} +} +\end{codeenv} +This option isn't cumulative. Multiple instances of +\csopt{entry-type-aliases} override previous instances. +If \meta{\keyvallist} is empty there will be no mappings. +You can save the original entry type in the +\field{originalentrytype} field with +\csopt{save-original-entrytype}. + +Here's another example entry in a \ext{bib} file: +\begin{codeenv} +@foo\marg{html, + \field{name} = \marg{HTML}, + \field{short} = \marg{HTML}, + \field{long} = \marg{hypertext markup language}, + \field{description} = \marg{hypertext markup language} +} +\end{codeenv} +Ordinarily this entry would be ignored since \code{@foo} +isn't recognised, but it can be mapped like this: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{data in entries.bib} + \csopt[short,long]{ignore-fields}, + \csopt[foo=entry]{entry-type-aliases} +} +\end{codeenv} +This treats the entry as though it had been defined as: +\begin{codeenv} +\atentry{entry}\marg{html, + \field{name} = \marg{HTML}, + \field{description} = \marg{hypertext markup language} +} +\end{codeenv} +whereas: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{data in entries.bib} + \csopt[name,description]{ignore-fields}, + \csopt[foo=abbreviation]{entry-type-aliases} +} +\end{codeenv} +treats the entry as though it had been defined as: +\begin{codeenv} +\atentry{abbreviation}\marg{html, + \field{short} = \marg{HTML}, + \field{long} = \marg{hypertext markup language} +} +\end{codeenv} + +\optsection{unknown-entry-alias} + +If this option is set, the \meta{value} is used as the alias for any +unknown entry types (after any aliases provided with +\csopt{entry-type-aliases} have been applied). If the value is +missing or empty, unknown entry types will be ignored with a +warning. + +\optsection{action} + +This governs how the entries are written in the \iext{glstex} file. +The \meta{value} may be one of: +\begin{itemize} +\item\code{define}: define the entries; +\item\code{copy}: copy the entries; +\item\code{define or copy}: copy existing entries and define +non-existing entries. +\end{itemize} +The default setting is \csopt[define]{action}, which writes the entry +definition to the \ext{glstex} file using one of the commands +described in \sectionref{sec:newentrydefs}. Since the \styopt{record} +package option automatically switches on the \styopt[warn]{undefaction} +option, any attempt at defining an entry that's already been defined +will generate a warning rather than an error. The duplicate +definition will be ignored. (The warnings can be found in the +\ext{log} file since they are warnings produce by +\sty{glossaries-extra} not by \bibgls.) + +For example, if you try: +\begin{codeenv} +\cs{newglossary*}\marg{copies}\marg{Copies} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}} +\gls{GlsXtrLoadResources}\oarg{\csopt[use]{sort},\csopt[copies]{type},\csopt[entries]{src}} +\end{codeenv} +you'll find that the \code{copies} glossary is empty and there will +be warnings in the \ext{log} file when the second resource file is +loaded. + +There are various ways of having the same entries in multiple +glossaries. The simplest method is to use \csopt{secondary}, but +another method is to use \csopt[copy]{action} which simply writes +\nosecformatdef{glsxtrcopytoglossary} +instead of using one of the commands listed in +\sectionref{sec:newentrydefs}. This copies the entries rather than +defining them, which means the entries must already have been +defined. The \meta{type} is determined as follows: +\begin{itemize} +\item if the entry has the \field{type} field set, that's used; +\item if the entry is a tertiary and \csopt{tertiary-type} is set, that's +used; +\item if the entry is a dual and \csopt{dual-type} is set, that's +used; +\item otherwise the value of the \csopt{type} option is used. +\end{itemize} +If you're not sure whether the entries may already be defined, you +can use \csopt[define or copy]{action} which will use +\ics{ifglsentryexists} in the resource file to determine whether to +define or copy the entry. + +Options that set or modify fields, such as \csopt{category}, +\csopt{group}, \csopt{save-locations}, \csopt{flatten} or +\csopt{name-case-change}, will be ignored if entries are copied. +However the \csopt{copy-action-group-field} may be used to copy +the \field{group} field (which may have been locally set by the +\csopt{sort} method) to another field. This ensures that the +original \field{group} value from the entry definition in an earlier +resource set won't be overwritten (unless you set +\csopt[group]{copy-action-group-field}). + +Remember that \gls{glsxtrcopytoglossary} simply copies the entry's +label to the glossary's internal list. The only checks that \bibgls\ +performs if \csopt{action} is not \code{define} is to ensure that +the \csopt{master} or \csopt{secondary} options have not been used, +since they're incompatible, and that the \csopt{type} option is set, +since it's required as a fallback for any entries that don't have +the \field{type} field set. (There are too many options that alter +field values to check them all and some may be used to alter the +sorting.) The purpose of the copy action is simply to provide a +duplicate list in a different order. + +Remember that if you are using \sty{hyperref}, you need to use +\code{\printglossopt[false]{target}} in the optional argument of +\ics{printunsrtglossary} for the glossary containing the copies to +prevent duplicate hypertargets. Commands like \cs{gls} will link to +the original entries. For example, in the preamble: +\begin{codeenv} +\cs{newignoredglossary}\marg{copies} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[use]{sort}, + \csopt[copy]{action}, + \csopt[copies]{type}, + \csopt[entries]{src} +} +\end{codeenv} +and later in the document: +\begin{codeenv} +\cs{printunsrtglossary}\oarg{\printglossopt[Glossary (Alphabetical)]{title},\printglossopt[\glostyle{indexgroup}]{style}} +\cs{printunsrtglossary}\oarg{\printglossopt[copies]{type},\printglossopt[Glossary (Order of Use)]{title}, + \printglossopt[index]{style},\printglossopt{nogroupskip},\comment{no grouping} + \printglossopt[false]{target}} +\end{codeenv} +Note also the need to use \code{nogroupskip} and a non-group style +for the duplicates since the \field{group} field will have been +assigned in the first resource set if \bibgls\ was invoked with +\longarg{group}. The grouping is appropriate for alphabetical +ordering but not for order of use. + +If you want different grouping for the duplicates, you can specify +the field name to use in which to store the group information using +\csopt{copy-action-group-field}. Unlike \csopt{secondary}, you +will need to redefine \ics{glsxtrgroupfield} to the relevant field +before you display the glossary. The simplest way to do this is with +the starred form of \cs{printunsrtglossary}. +For example, if \csopt[dupgroup]{copy-action-group-field} is added to +the options for the second resource set: +\begin{codeenv} +\ics{printunsrtglossary*}\oarg{\printglossopt[copies]{type},\printglossopt[Duplicates]{title},\printglossopt[\glostyle{indexgroup}]{style}} + \marg{\cs{renewcommand}\marg{\cs{glsxtrgroupfield}}\marg{dupgroup}} +\end{codeenv} +This just does: +\begin{codeenv} +\cmd{begingroup} + \cs{renewcommand}\marg{\ics{glsxtrgroupfield}}\marg{dupgroup}\comment{} + \cs{printunsrtglossary}\oarg{\printglossopt[copies]{type},\printglossopt[Duplicates]{title},\printglossopt[indexgroup]{style}} +\cmd{endgroup} +\end{codeenv} + + +\section{Selection Options} +\label{sec:selectionopts} + +\optsection{src} + +This identifies the \iext{bib} files containing the entry +definitions. The value should be a comma-separated list of the +required \ext{bib} files. These may either be in the current working +directory or in the directory given by the \longarg{dir} switch or on +\TeX's path (in which case \idx{kpsewhich} will be used to find +them). The \ext{bib} extension may be omitted. Remember that if +\meta{list} contains multiple files it must be grouped to protect +the comma from the \meta{options} list. + +For example: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries-terms,entries-symbols]{src}} +\end{codeenv} +indicates that \bibgls\ must read the files +\filefmt{entries-terms.bib} and \filefmt{entries-symbols.bib} and +create the file given by \ics{jobname}\iext{glstex} on the first +instance or \ics{jobname}\code{-}\meta{n}\ext{glstex} on subsequent +use. + +With \code{\gls!{glsxtrresourcefile}\oargm{options}\margm{filename}}, if +the \csopt{src} option is omitted, +the \ext{bib} file is assumed to be \meta{filename}\ext{bib}. For example: +\begin{codeenv} +\gls{glsxtrresourcefile}\marg{entries-symbols} +\end{codeenv} +indicates that \bibgls\ needs to read the file +\filefmt{entries-symbols.bib}, which contains the entry data, and create the file +\filefmt{entries-symbols.glstex}. If the \ext{bib} file is +different or if you have multiple \ext{bib} files, you need to use +the \csopt{src} option. + +\gls{GlsXtrLoadResources} uses \ics{jobname} as the argument of +\gls{glsxtrresourcefile} on the first instance, so: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{} +\end{codeenv} +will assume \csopt[\ics{jobname}]{src}. Remember that subsequent uses +of \gls{GlsXtrLoadResources} append a suffix, so in general it's +best to always supply \csopt{src}. + +If you have non-ASCII characters in the \ext{bib} filename but +aren't using \XeLaTeX\ or \LuaLaTeX, then you will need to use +\ics{detokenize} to prevent expansion when the information is +written to the \ext{aux} file. Similarly for any special characters +that need protecting (although it's better not to use special +characters in filenames). For example: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\oarg{T2A}\marg{fontenc} +\cmd{usepackage}\oarg{utf8}\marg{inputenc} +\cmd{usepackage}\oarg{russian}\marg{babel} +\cmd{usepackage}\oarg{record}\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[\cs{detokenize}\marg{\textcyrillicmono{кириллица}}]{src},\comment{data in \textcyrillicmono{кириллица.bib}} + \csopt[all]{selection} +} +\strut +\cmd{begin}\marg{document} +\cs{printunsrtglossary} +\cmd{end}\marg{document} +\end{codeenv} + +\optsection{selection} + +By default all entries that have records in the \iext{aux} file will +be selected as well as all their dependent entries. The dependent +entries that don't have corresponding records on the first \LaTeX\ +run, may need an additional build to ensure their location lists +are updated. + +Remember that on the first \LaTeX\ run the \iext{glstex} files don't +exist. This means that the entries aren't defined at that point. The +\styopt{record} package option additionally switches on the +\styopt[warn]{undefaction} option, which means that you'll only get +warnings rather than errors when you reference entries in the +document. You can't use \ics{glsaddall} with +\bibgls\ because the glossary lists are empty on the first run, so +there's nothing for \ics{glsaddall} to iterate over. +Instead, if you want to add all defined entries, you need to +instruct \bibgls\ to do this with the \csopt{selection} option. The +following values are allowed: +\begin{itemize} +\item \optfmt{recorded and deps}: add all recorded entries and +their dependencies (default). +\item \optfmt{recorded and deps and see}: as above but will also +add unrecorded entries whose \field{see} or \field{seealso} field refers to a recorded entry. +\item \optfmt{recorded no deps}: add all recorded entries but not +their dependencies. The dependencies include those referenced in the +\field{see} or \field{seealso} field or fields identified by +\csopt{dependency-fields}, \field{parent} entries and those found referenced +with commands like \ics{gls} in the field values that are parsed by +\bibgls. With this setting, parents will be omitted unless they've +been referenced in the document through commands like \ics{gls}. +\item \optfmt{recorded and ancestors}: this is like the previous +setting but parents are added even if they haven't been referenced +in the document. The other dependent entries are omitted if they +haven't been referenced in the document. +\item \optfmt{all}: add all entries found in the \ext{bib} files +supplied in the \csopt{src} option. +\end{itemize} +The \meta{value} must be supplied. + +For example, suppose the file \filefmt{entries.bib} contains: +\begin{codeenv} +\atentry{index}\marg{run} +\atentry{index}\marg{sprint,\field{see}=\marg{run}} +\atentry{index}\marg{dash,\field{see}=\marg{sprint}} +\end{codeenv} +If the document only references the \qt{run} entry (for example, +using \code{\cs{gls}\marg{run}}) then: +\begin{itemize} +\item If \csopt[recorded and deps]{selection}, only the \qt{run} +entry is selected. The \qt{run} entry has a record, so it's +selected, but it has no dependencies. Neither \qt{sprint} nor +\qt{dash} have records, so they're not selected. +\item If \csopt[recorded and deps and see]{selection}, the \qt{run} +and \qt{sprint} entries are selected, but not the \qt{dash} entry. +The \qt{run} entry is selected because it has a record. The +\qt{sprint} entry doesn't have a record but its \field{see} field +includes \qt{run}, which does have a record, so \qt{sprint} is also +selected. The \qt{dash} entry doesn't have a record. Its +\field{see} field references \qt{sprint}. Although \qt{sprint} has +been selected, it doesn't have any records, so \qt{dash} isn't +selected. +\end{itemize} +The above is just an example. The circuitous redirection of +\qt{dash} to \qt{sprint} to \qt{run} is unhelpful to the reader and +is best avoided (especially for an index where there are no accompanying +descriptions and no \idx{locationlist} for the intermediate \qt{sprint}). +A better method would be: +\begin{codeenv} +\atentry{index}\marg{run} +\atentry{index}\marg{sprint,\field{see}=\marg{run}} +\atentry{index}\marg{dash,\field{see}=\marg{run}} +\end{codeenv} +The \csopt[recorded and deps and see]{selection} in this case will +select all three entries, and the document won't send the reader on a +long-winded detour. + +Now suppose that the file \filefmt{entries.bib} contains: +\begin{codeenv} +\atentry{entry}\marg{run, + \field{name} = \marg{run}, + \field{description}=\marg{move fast using legs} +} +\strut +\atentry{entry}\marg{sprint, + \field{name} = \marg{sprint}, + \field{description}=\marg{run at full speed over short distance}, + \field{seealso}=\marg{run} +} +\strut +\atentry{entry}\marg{dash, + \field{name} = \marg{dash}, + \field{description}=\marg{run in a great hurry}, + \field{seealso}=\marg{sprint} +} +\end{codeenv} +and suppose the document only references \qt{dash} (for example, with +\code{\cs{gls}\marg{dash}}), then with the default \csopt[recorded and deps]{selection} +\qt{dash} will be selected because it has a record, and \qt{sprint} +will be selected because \qt{dash} requires it (for the cross-reference), +and \qt{run} will be selected because \qt{sprint} requires it +(for the cross-reference). In this case, neither \qt{sprint} nor \qt{run} +have a \idx{locationlist} but they do both provide additional information +for the reader in their descriptions. + +A better method here would be for each entry to have a cross-reference +list that includes all related terms: +\begin{codeenv} +\atentry{entry}\marg{run, + \field{name} = \marg{run}, + \field{description}=\marg{move fast using legs}, + \field{seealso}=\marg{sprint,dash} +} +\strut +\atentry{entry}\marg{sprint, + \field{name} = \marg{sprint}, + \field{description}=\marg{run at full speed over short distance}, + \field{seealso}=\marg{run,dash} +} +\strut +\atentry{entry}\marg{dash, + \field{name} = \marg{dash}, + \field{description}=\marg{run in a great hurry}, + \field{seealso}=\marg{sprint,run} +} +\end{codeenv} +Now, whichever one is indexed in the document, the other two will automatically +be selected. + +\optsection{match} + +It's possible to filter the selection by matching field values. +The value is required for this key but may be empty, which indicates +that the setting is switched off, otherwise +\meta{\keyvallist} should be a \meta{key}=\meta{regexp} list, where +\meta{key} is the name of a field or \optfmt{id} for the entry's +label or \optfmt{entrytype} for the \bibgls\ entry type (as in +the part after \verb|@| identifying the entry not the \field{type} +field identifying the glossary label). If you've used +\csopt{entry-type-aliases}, this refers to the target entry type not +the original entry type specified in the \ext{bib} file. + +The \meta{regex} part should be a \idx{regex} conforming +to +\href{http://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html}{Java's +Pattern class}~\cite{pattern}. The pattern is anchored +(\code{oo}\idx{matchanydot}\idx{zeroormore} matches +\code{oops} but not \code{loops}) and \meta{regexp} can't be +empty. Remember that \TeX\ will expand the option list as +it writes the information to the \ext{aux} file so take +care with special characters. For example, to match a literal +period use \cs{cs.string}\idx{cs.period} not \idx{cs.period} (backslash dot). + +If the field is missing its value it is assumed to be empty for +the purposes of the pattern match even if it will be assigned a +non-empty default value when the entry is defined. If the field is +unrecognised by \bibgls\ any reference to it in \meta{\keyvallist} will +be ignored. + +If a field is listed multiple times, the pattern for that +field is concatenated using: +\begin{alltt} +(?:\meta{pattern-1})|(?:\meta{pattern-2}) +\end{alltt} +where \meta{pattern-1} is the current pattern for that field +and \meta{pattern-2} is the new pattern. This means it performs a +logical OR\@. For the non-duplicate +fields the logical operator is given by \csopt{match-op}. +For example: +\begin{codeenv} +\csopt[and]{match-op}, +\csopt[ + \field{category}=animals, + \fieldfmt{topic}=biology, + \field{category}=vegetables +]{match} +\end{codeenv} +This will keep all the selected entries that satisfy: +\begin{itemize} +\item \field{category} matches \verb"(?:animals)|(?:vegetables)" + +(the \field{category} is either \optfmt{animals} or +\optfmt{vegetables}) + +\item[AND] + +\item \fieldfmt{topic} (custom key provided by user) is \code{biology}. +\end{itemize} +and will discard any entries that don't satisfy this condition. +A message will be written to the log file for each entry +that's discarded. + +Patterns for unknown fields will be ignored. If the entire +list consists of patterns for unknown fields it will be +treated as \csopt[\empty]{match}. That is, no filtering will be +applied. In the above example, the custom \fieldfmt{topic} key must +be provided before the first \gls{GlsXtrLoadResources} with +\ics{glsaddkey} or \ics{glsaddstoragekey}. + +\optsection{match-op} + +If the value of \csopt{match} contains more than one +\meta{key}=\meta{pattern} element, the \csopt{match-op} +determines whether to apply a logical AND or a logical OR. +The \meta{value} may be either \optfmt{and} or \optfmt{or}. +The default is \csopt[and]{match-op}. + +\optsection{not-match} + +If \csopt[\meta{\keyvallist}]{match} would cause an entry to be +selected then \csopt[\meta{\keyvallist}]{not-match} would cause that +entry to be ignored. The value is required for this key but may be +empty, which indicates that the setting is switched off. If you +have both \csopt{match} and \csopt{not-match} in the same resource +set, the last one listed takes precedence. + +\optsection{match-action} + +The default behaviour with \csopt{match} or \csopt{not-match} +is to filter the selection. This may be changed to append to the +selection instead. The \meta{value} may be one of: +\begin{itemize} +\item\optfmt{filter}: (default) filter selection; +\item\optfmt{add}: append any matches (with \csopt{match}) or +non-matches (with \csopt{not-match}) to the selection. +This setting can't be used with \csopt[use]{sort}. +\end{itemize} +For example, if I want to select all record entries and their +dependencies, but I also want to make sure that any entries with +the category set to \code{important} are always selected regardless +of whether or not they have any records: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{data in entries.bib} + \csopt[add]{match-action}, + \csopt[\field{category}=important]{match} +} +\end{codeenv} + +\optsection{limit} + +If \meta{number} is greater than 0 then this will truncate the +list of selected entries after sorting to \meta{number} (if the list +size is greater than that value). The transcript will show the +message: +\begin{alltt} +Truncating according to limit=\meta{number} +\end{alltt} +When used with \csopt{shuffle}, this provides a means of randomly +selecting at most \meta{number} entries. The default setting is +\csopt[0]{limit} (no truncation). A negative value of \meta{number} is not +permitted. + +If you have any dual entries, then the truncation will be applied to +the combined list of primary and duals if \csopt[combine]{dual-sort} +otherwise each list will be truncated separately by \meta{number}, +which results in a maximum of $2 \times \meta{number}$. Remember +that tertiary entries are created when dual entries are defined in +the \ext{glstex} file, so this will increase the total number of +entries. + +\section{Hierarchical Options} +\label{sec:hierarchicalopts} + +\optsection{save-child-count} + +This is a boolean option. The default setting is +\csopt[false]{save-child-count}. +If \csopt[true]{save-child-count}, +each entry will be assigned a field called \field{childcount} with +the value equal to the number of child entries that have been +selected. As from version 1.5, this option also creates +the \field{childlist} field for entries that have children +selected. This field is in \sty{etoolbox}'s internal list +format and can be iterated over using \ics{glsxtrfieldforlistloop}. + +The assignment is done using \ics{GlsXtrSetField} so there's +no associated key. You can test if the field is set and non-zero +using: +\nosecformatdef{GlsXtrIfHasNonZeroChildCount} +which is provided with \sty{glossaries-extra-bib2gls} v1.31+. +Within \meta{true}, you can access the actual value with +\ics{glscurrentfieldvalue}. If \csopt[false]{save-child-count}, +this command will do \meta{false} as the \field{childcount} field +won't be set. + +For example, suppose \filefmt{entries.bib} contains: +\begin{codeenv} +\atentry{index}\marg{birds} +\atentry{index}\marg{duck,\field{parent}=\marg{birds}} +\atentry{index}\marg{goose,\field{plural}=\marg{geese},\field{parent}=\marg{birds}} +\atentry{index}\marg{swan,\field{parent}=\marg{birds}} +\strut +\atentry{index}\marg{minerals} +\atentry{index}\marg{quartz,\field{parent}=\marg{minerals}} +\atentry{index}\marg{corundum,\field{parent}=\marg{minerals}} +\atentry{index}\marg{amethyst,\field{parent}=\marg{minerals}} +\atentry{index}\marg{gypsum,\field{parent}=\marg{minerals}} +\atentry{index}\marg{gold,\field{parent}=\marg{minerals}} +\end{codeenv} +and the document contains: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[\styopt{record},\styopt[indexgroup]{style}]\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt{save-child-count}} +\strut +\cmd{begin}\marg{document} +\cs{gls}\marg{duck} and \cs{gls}\marg{goose}. +\cs{gls}\marg{quartz}, \cs{gls}\marg{corundum}, \cs{gls}\marg{amethyst}. +\strut +\cs{printunsrtglossaries} +\cmd{end}\marg{document} +\end{codeenv} +Then the \ext{glstex} file will contain: +\begin{codeenv} +\cs{GlsXtrSetField}\marg{birds}\marg{childcount}\marg{2} +\cs{GlsXtrSetField}\marg{duck}\marg{childcount}\marg{0} +\gls{glsxtrfieldlistadd}\marg{birds}\marg{childlist}\marg{duck} +\cs{GlsXtrSetField}\marg{goose}\marg{childcount}\marg{0} +\gls{glsxtrfieldlistadd}\marg{birds}\marg{childlist}\marg{goose} +\cs{GlsXtrSetField}\marg{minerals}\marg{childcount}\marg{3} +\cs{GlsXtrSetField}\marg{amethyst}\marg{childcount}\marg{0} +\gls{glsxtrfieldlistadd}\marg{minerals}\marg{childlist}\marg{amethyst} +\cs{GlsXtrSetField}\marg{corundum}\marg{childcount}\marg{0} +\gls{glsxtrfieldlistadd}\marg{minerals}\marg{childlist}\marg{corundum} +\cs{GlsXtrSetField}\marg{quartz}\marg{childcount}\marg{0} +\gls{glsxtrfieldlistadd}\marg{minerals}\marg{childlist}\marg{quartz} +\end{codeenv} +Note that although \code{birds} has three children defined in the +\ext{bib} file, only two have been selected, so the child count is +set to~2. Similarly the \code{minerals} entry has five children +defined in the \ext{bib} file, but only three have been selected, so +the child count is~3. + +The following uses the post-description hook to show the child count +in parentheses: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[general]{category},\csopt{save-child-count}} +\strut +\cs{glsdefpostdesc}\marg{general}\marg{\comment{} + \cs{glsxtrifhasfield}\marg{childcount}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{ (child count: \cs{glscurrentfieldvalue}.)}\comment{} + \marg{}\comment{} +} +\end{codeenv} +\ics{glsxtrifhasfield} requires at least \sty{glossaries-extra} v1.19. +It's slightly more efficient than \ics{ifglshasfield} provided by +the base \styfmt{glossaries} package, and it doesn't complain if the +entry or field don't exist, but note that \ics{glsxtrifhasfield} +implicitly scopes its content. Use the starred version to omit the +grouping. With \sty{glossaries-extra} v1.31+ you can perform a +numerical test with \ics{GlsXtrIfFieldNonZero} or +\ics{GlsXtrIfFieldEqNum}. + +\optsection{flatten} + +This is a boolean option. The default value is \csopt[false]{flatten}. +If \csopt[true]{flatten}, the sorting will ignore hierarchy and +the \field{parent} field will be omitted when writing +the definitions to the \ext{glstex} file, but the parent entries +will still be considered a dependent ancestor from the +\csopt{selection} point of view. + +Note the difference between this option and using +\csopt[parent]{ignore-fields} which will remove the dependency +(unless a dependency is established through another field). + +\optsection{flatten-lonely} + +This may take one of three values: \optfmt{false} (default), +\optfmt{presort} and \optfmt{postsort}. The value must be supplied. + +Unlike the \csopt{flatten} option, which completely +removes the hierarchy, the \csopt{flatten-lonely} option can be used +to selectively alter the hierarchy. In this case only those entries +that have a parent but have no siblings are considered. This option +is affected by the \csopt{flatten-lonely-rule} setting. The conditions for +moving a child up one hierarchical level are as follows: +\begin{itemize} +\item The child must have a parent, and +\item the child can't have any selected siblings, and +\item if \csopt[only unrecorded parents]{flatten-lonely-rule} + then the parent can't have a location list, where the location list + includes records and \field{see} or \field{seealso} + cross-references (for the other rules the parent may have a location + list as long as it only has the one child selected). +\end{itemize} +If the child is selected for hierarchical adjustment, the parent +will be removed if: +\begin{itemize} +\item The parent has no location list, and +\item \csopt{flatten-lonely-rule} isn't set to \optfmt{no discard}. +\end{itemize} + +The value of \csopt{flatten-lonely} determines whether the +adjustment should be made before sorting (\optfmt{presort}) +or after sorting (\optfmt{postsort}). To disable this function +use \csopt[false]{flatten-lonely}. + +For example, suppose the file \filefmt{entries.bib} contains: +\begin{codeenv} +\atentry{index}\marg{birds} +\atentry{index}\marg{duck,\field{parent}=\marg{birds}} +\atentry{index}\marg{goose,\field{plural}=\marg{geese},\field{parent}=\marg{birds}} +\atentry{index}\marg{swan,\field{parent}=\marg{birds}} +\atentry{index}\marg{chicken,\field{parent}=\marg{birds}} +\strut +\atentry{index}\marg{vegetable} +\atentry{index}\marg{cabbage,\field{parent}=\marg{vegetable}} +\strut +\atentry{index}\marg{minerals} +\atentry{index}\marg{quartz,\field{parent}=\marg{minerals}} +\atentry{index}\marg{corundum,\field{parent}=\marg{minerals}} +\atentry{index}\marg{amethyst,\field{parent}=\marg{minerals}} +\atentry{index}\marg{gypsum,\field{parent}=\marg{minerals}} +\strut +\atentry{index}\marg{aardvark} +\atentry{index}\marg{bard} +\atentry{index}\marg{buzz} +\strut +\atentry{index}\marg{item} +\atentry{index}\marg{subitem,\field{parent}=\marg{item}} +\atentry{index}\marg{subsubitem,\field{parent}=\marg{subitem}} +\end{codeenv} +and suppose the document contains: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[\styopt{record},\styopt[indexgroup]{style}]\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[entries.bib]{src}} +\strut +\cmd{begin}\marg{document} +\cs{gls}\marg{duck}. +\cs{gls}\marg{quartz}, \cs{gls}\marg{corundum}, \cs{gls}\marg{amethyst}. +\cs{gls}\marg{aardvark}, \cs{gls}\marg{bard}, \cs{gls}\marg{buzz}. +\cs{gls}\marg{vegetable}, \cs{gls}\marg{cabbage}. +\cs{gls}\marg{subsubitem}. +\strut +\cs{printunsrtglossaries} +\cmd{end}\marg{document} +\end{codeenv} +Although the \code{duck} entry has siblings in the +\filefmt{entries.bib} file, none of them have been recorded +(indexed) in the document, nor has the parent \code{birds} entry. + +This document hasn't used \csopt{flatten-lonely}, so the default +\csopt[false]{flatten-lonely} is assumed. This results in the +hierarchical structure: +\begin{description}\setlength\itemsep{0pt}% +\item[A] \null +\item[aardvark] 1 +\item[B] \null +\item[bard] 1 +\item[birds] \mbox{} + \begin{description}\setlength\itemsep{0pt}% + \item[duck] 1 + \end{description} +\item[buzz] 1 +\item[I] \null +\item[item] \mbox{} + \begin{description}\setlength\itemsep{0pt}% + \item[subitem] \mbox{} + \begin{description}\setlength\itemsep{0pt}% + \item[subsubitem] 1 + \end{description} + \end{description} +\item[M] \null +\item[minerals] \mbox{} + \begin{description}\setlength\itemsep{0pt}% + \item[amethyst] 1 + \item[corundum] 1 + \item[quartz] 1 + \end{description} +\item[V] \null +\item[vegetable] 1 + \begin{description}\setlength\itemsep{0pt}% + \item[cabbage] 1 + \end{description} +\end{description} +(The \qt{1} in the above indicates the page number.) +There are some entries here that look a little odd: \code{duck}, +\code{cabbage} and \code{subsubitem}. In each case they are a +lone child entry. It would look better if they could be compressed, +but I don't want to use the \csopt{flatten} option, as I still want +to keep the mineral hierarchy. + +If I now add \csopt[postsort]{flatten-lonely}: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries.bib]{src},\csopt[postsort]{flatten-lonely}} +\end{codeenv} +the hierarchy becomes: +\begin{description}\setlength\itemsep{0pt}% +\item[A] \null +\item[aardvark] 1 +\item[B] \null +\item[bard] 1 +\item[birds, duck] 1 +\item[buzz] 1 +\item[I] \null +\item[item, subitem, subsubitem] 1 +\item[M] \null +\item[minerals] \mbox{} + \begin{description}\setlength\itemsep{0pt}% + \item[amethyst] 1 + \item[corundum] 1 + \item[quartz] 1 + \end{description} +\item[V] \null +\item[vegetable] 1 + \begin{description}\setlength\itemsep{0pt}% + \item[cabbage] 1 + \end{description} +\end{description} +The \field{name} field of the \code{duck} entry has been +set to: +\begin{codeenv} +\field{name}=\marg{\gls{bibglsflattenedchildpostsort}\marg{birds}\marg{duck}} +\end{codeenv} +the \field{text} field has been set to: +\begin{codeenv} +\field{text}=\marg{duck} +\end{codeenv} +the \field{group} field is copied over from the parent entry (\qt{B}), +and the \field{parent} field has been adjusted, moving \code{duck} +up one hierarchical level. +Finally, the former parent \code{birds} entry has been removed (the default +\csopt[only unrecorded parents]{flatten-lonely-rule} is in effect). + +The default definition of \gls!{bibglsflattenedchildpostsort} +formats its arguments so that they are separated by a comma and +space (\qt{birds, duck}). If the \field{text} field had been set +in the original \atentry{index} definition of \text{duck}, it +wouldn't have been altered. This adjustment ensures that in the +document \code{\cs{gls}\marg{duck}} still produces \qt{duck} rather than +\qt{birds, duck}. +(If the child and parent \field{name} fields are identical, +the terms are considered homographs. See below for further details.) + +The \code{subsubitem} entry has also been adjusted. This was done +in a multi-stage process, starting with sub-items and then moving down +the hierarchical levels: +\begin{itemize} +\item The \code{subitem} entry was adjusted, moving it from a +sub-entry to a top-level entry. The \field{name} field was then +modified to: +\begin{codeenv} +\field{name}=\marg{\gls{bibglsflattenedchildpostsort}\marg{item}\marg{subitem}} +\end{codeenv} +This now means that the \code{subsubitem} entry is now a sub-entry +(rather than a sub-sub-entry). The \code{subitem} entry now has no +parent, but at this stage the \code{subsubitem} entry still has +\code{subitem} as its parent. +\item The \code{subsubitem} entry is then adjusted moving from a +sub-entry to a top-level entry. The \field{name} field was then +modified to: +\begin{codeenv} +\field{name}= +\marg{\comment{} + \gls{bibglsflattenedchildpostsort} + \marg{\comment{} + \comment{name from former parent} + \gls{bibglsflattenedchildpostsort}\marg{item}\marg{subitem}\comment{} + }\comment{} + \marg{subsubitem}\comment{original name} +} +\end{codeenv} +The first argument of \gls!{bibglsflattenedchildpostsort} is +obtained from the \field{name} field of the entry's former parent +(which is removed from the child's set of ancestors). This field +value was changed in the previous step, and the change is +reflected here. + +This means that the name for \code{subitem} will be displayed as +\qt{item, subitem} and the name for \code{subsubitem} will be +displayed as \qt{item, subitem, subsubitem}. + +\item The parent entries \code{item} and \code{subitem} +are removed from the selection as they have no location lists. +\end{itemize} + +Note that the \code{cabbage} sub-entry hasn't been adjusted. It +doesn't have any siblings but its parent entry (\code{vegetable}) +has a location list so it can't be discarded. +If I change the rule: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries.bib]{src}, + \csopt[discard unrecorded]{flatten-lonely-rule}, + \csopt[postsort]{flatten-lonely} +} +\end{codeenv} +then this will move the \code{cabbage} entry up a level but the +original parent entry \code{vegetable} will remain: +\begin{description}\setlength\itemsep{0pt}% +\item[A] \null +\item[aardvark] 1 +\item[B] \null +\item[bard] 1 +\item[birds, duck] 1 +\item[buzz] 1 +\item[I] \null +\item[item, subitem, subsubitem] 1 +\item[M] \null +\item[minerals] \mbox{} + \begin{description}\setlength\itemsep{0pt}% + \item[amethyst] 1 + \item[corundum] 1 + \item[quartz] 1 + \end{description} +\item[V] \null +\item[vegetable] 1 +\item[vegetable, cabbage] 1 +\end{description} + +Remember that \csopt[postsort]{flatten-lonely} performs the +adjustment after sorting. This means that the entries are still in +the same relative location that they were in with the original +\csopt[false]{flatten-lonely} setting. For example, \code{duck} +remains in the B letter group before \qt{buzz}. + +With \csopt[presort]{flatten-lonely} the adjustments are made before +the sorting is performed. For example, using: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries.bib]{src}, + \csopt[discard unrecorded]{flatten-lonely-rule}, + \csopt[presort]{flatten-lonely} +} +\end{codeenv} +the hierarchical order is now: +\begin{description}\setlength\itemsep{0pt}% +\item[A] \null +\item[aardvark] 1 +\item[B] \null +\item[bard] 1 +\item[buzz] 1 +\item[C] \null +\item[cabbage] 1 +\item[D] \null +\item[duck] 1 +\item[M] \null +\item[minerals] \mbox{} + \begin{description}\setlength\itemsep{0pt}% + \item[amethyst] 1 + \item[corundum] 1 + \item[quartz] 1 + \end{description} +\item[S] \null +\item[subsubitem] 1 +\item[V] \null +\item[vegetable] 1 +\end{description} +This method uses a different format for the modified \field{name} +field. For example, the \code{duck} entry now has: +\begin{codeenv} +\field{name}=\marg{\gls{bibglsflattenedchildpresort}\marg{duck}\marg{birds}} +\end{codeenv} +The default definition of \gls{bibglsflattenedchildpresort} simply +does the first argument and ignores the second. The sorting is then +performed, but the interpreter recognises this command and can +deduce that the sort value for this entry should be \code{duck}, +so \qt{duck} now ends up in the D letter group. + +If you provide a definition of \gls{bibglsflattenedchildpresort} in +the \atentry{preamble}, it will be picked up by the interpreter. +For example: +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\gls{bibglsflattenedchildpresort}}[2]\marg{\idx{param}1 (\idx{param}2)}}} +\end{codeenv} + +Note that the \field{text} field is only changed if not already set. +This option may have unpredictable results for abbreviations as the +\field{name} field (and sometimes the \field{text} field) is +typically set by the abbreviation style. Remember that +if the parent entry doesn't have a \idx{locationlist} and the rule isn't +set to \optfmt{no discard} then the parent entry will be discarded +after all relevant entries and their dependencies have been +selected, so any cross-references within the parent entry (such as +\ics{gls} occurring in the description) may end up being selected +even if they wouldn't be selected if the parent entry didn't exist. + +With both \optfmt{presort} and \optfmt{postsort}, +if the parent \field{name} is the same as the child's \field{name} +then the child is considered a homograph and +the child's name is set to: +\begin{codeenv*} +\format{bibglsflattenedhomograph} +\end{codeenv*} +instead of the corresponding \csfmt{bibglsflattenedchild\ldots sort}. +This defaults to just \meta{name}. + + +\optsection{flatten-lonely-rule} + +This option governs the rule used by \csopt{flatten-lonely} to +determine which sub-entries (that have no siblings) to adjust and +which parents to remove. The value may be one of the following: +\begin{description} +\item[\optfmt{only unrecorded parents}] Only the sub-entries +that have a parent without a \idx{locationlist} will be altered. +The parent entry will be removed from the selection. +This value is the default setting. +\item[\optfmt{discard unrecorded}] This setting will adjust all +sub-entries that have no siblings regardless of whether or not the +parent has a \idx{locationlist}. +Only the parent entries that don't have a location list will be +removed from the selection. +\item[\optfmt{no discard}] This setting will adjust all +sub-entries that don't have siblings regardless of whether or not the +parent has a \idx{locationlist}. No entries will be discarded, so parent +entries that don't have a \idx{locationlist} will still appear in the +glossary. +\end{description} +In the above, the \idx{locationlist} includes records and +cross-references obtained from the \field{see} or \field{seealso} +fields. See \csopt{flatten-lonely} for further details. + +\optsection{strip-missing-parents} + +The \sty{glossaries} package requires that all child entries must be +defined after the parent entry. An error occurs otherwise, so +\bibgls\ will omit the \field{parent} field if it can't be found in +the given \idx{resourceset}. However, when the default +\csopt[false]{strip-missing-parents} is on, this omission only occurs +while writing the definitions in the \ext{glstex} file (after +selection and sorting). + +Sorting is performed hierarchically and the \field{group} field is set +accordingly for the top-level entries (but not for child entries), +which means that an entry with a \field{parent} field will be +treated by the sort method as a child entry. This can lead to a +strange result, which \bibgls\ warns about: +\begin{alltt} +Parent '\meta{parent id}' not found for entry \meta{child-id} +\end{alltt} + +This is the default behaviour as it may simply be a result of a +typing mistake in the \field{parent} field. If you actually want +missing parents to be stripped before sorting (but after the +selection process) then use \csopt[true]{strip-missing-parents}. If +you want all parents stripped then use \csopt{flatten} or +\csopt[parent]{ignore-fields} instead. As from version 1.4, if you +want \bibgls\ to create the missing parents, then you can use +\csopt[create]{missing-parents}. + +\optsection{missing-parents} + +As an alternative to \csopt{strip-missing-parents}, as from version +1.4 you can now use \csopt[\meta{value}]{missing-parents} where +\meta{value} may be one of: +\begin{itemize} +\item \optfmt{strip}: this is equivalent to +\csopt[true]{strip-missing-parents}; + +\item \optfmt{warn}: this is equivalent to the default +\csopt[false]{strip-missing-parents}; + +\item \optfmt{create}: this will create a new \atentry{index} +entry with the missing parent's label (after it's been processed by +options such as \csopt{labelify}) with the \field{name} obtained +from the \emph{original} value of the \field{parent} field (before being +processed by options like \csopt{labelify}). +If the child entry has the \field{type} field set, then the new +parent entry will be given the same value. The \field{category} for +the new parent entry can be assigned with +\csopt{missing-parent-category}. +\end{itemize} + +For example, consider the \exfile{books.bib} file which contains +entries like: +\begin{codeenv} +\atentry{entry}\marg{ubik, + \field{name}=\marg{Ubik}, + \field{description}=\marg{novel by Philip K. Dick}, + \fieldfmt{identifier}=\marg{book}, + \fieldfmt{author}=\marg{\gls{sortmediacreator}\marg{Philip K.}\marg{Dick}}, + \fieldfmt{year}=\marg{1969} +} +\end{codeenv} +then the field alias: +\begin{codeenv} +\csopt[\fieldfmt{author}=\field{parent}]{field-aliases} +\end{codeenv} +will treat: +\begin{codeenv} + \fieldfmt{author}=\marg{\gls{sortmediacreator}\marg{Philip K.}\marg{Dick}}, +\end{codeenv} +as though it had been defined as: +\begin{codeenv} + \field{parent}=\marg{\gls{sortmediacreator}\marg{Philip K.}\marg{Dick}}, +\end{codeenv} +This can be converted into a label with the options: +\begin{codeenv} + \csopt[parent]{labelify}, + \csopt[ + \marg{[ \cs{cs.string}\csfmt{.}]}\marg{} + ]{labelify-replace} +\end{codeenv} +If the interpreter has been provided with the definition: +\begin{codeenv} +\cs{providecommand}*\marg{\gls{sortmediacreator}}[2]\marg{\idx{param}2 \idx{param}1} +\end{codeenv} +then the \field{parent} field for the \code{ubik} entry +will become \code{DickPhilipK} but the original value is stored +internally when \csopt[create]{missing-parents} is set so that it +can be used as the \field{name} if the parent needs to be created. +Once all the entries have been processed, if \code{ubik} has been +selected but no entry can be found with the label \code{DickPhilipK} +then a new entry will be added as though it had been defined with: +\begin{codeenv} +\atentry{index}\marg{DickPhilipK, + \field{name}=\marg{\gls{sortmediacreator}\marg{Philip K.}\marg{Dick}} +} +\end{codeenv} +This is an alternative approach to the \exfile{sample-authors.tex} +document from the \hyperref[sec:examples]{examples chapter}. + +\optsection{missing-parent-category} + +If a missing parent entry is created through the use of +\csopt[create]{missing-parents} then the \field{category} field can +be assigned to the new parent entry with this option. The +\meta{value} may be one of: +\begin{itemize} + \item \code{same as child}: the parent entry's \field{category} + field is set to the same value as the child's (if set); + \item \code{same as base}: the parent entry's \field{category} is + set to the base name of the \ext{bib} file that provided the + child entry's definition; + \item \code{no value}: don't set the \field{category} field; + \item \meta{label}: the parent entry's \field{category} field is set to + \meta{label} (which shouldn't contain any special characters). +\end{itemize} +The default setting is \csopt[no value]{missing-parent-category}. + +\section{Master Documents} +\label{sec:master} + +Suppose you have two documents \filefmt{mybook.tex} and +\filefmt{myarticle.tex} that share a common glossary that's shown +in \filefmt{mybook.pdf} but not in \filefmt{myarticle.pdf}. +Furthermore, you'd like to use \isty{hyperref} and be able to click +on a term in \filefmt{myarticle.pdf} and be taken to the relevant +page in \filefmt{mybook.pdf} where the term is listed in the +glossary. + +This can be achieved with the \catattr{targeturl} and +\catattr{targetname} category attributes. For example, without +\bibgls\ the file \filefmt{mybook.tex} might look like: +\begin{codeenv} +\cmd{documentclass}\marg{book} +\cmd{usepackage}[colorlinks]\marg{hyperref} +\cmd{usepackage}\marg{glossaries-extra} +\strut +\cs{cs.makeglossaries} +\strut +\gls{newglossaryentry}\marg{sample}\marg{\field{name}=\marg{sample},\field{description}=\marg{an example}} +\strut +\cmd{begin}\marg{document} +\cs{chapter}\marg{Example} +\cs{gls}\marg{sample}. +\strut +\cs{printglossaries} +\cmd{end}\marg{document} +\end{codeenv} +The other document \filefmt{myarticle.tex} might look like: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\cmd{usepackage}[colorlinks]\marg{hyperref} +\cmd{usepackage}\marg{glossaries-extra} +\strut +\cs{newignoredglossary*}\marg{external} +\ics{glssetcategoryattribute}\marg{external}\marg{targeturl}\marg{mybook.pdf} +\cs{glssetcategoryattribute}\marg{external}\marg{targetname}\marg{\cs{glolinkprefix}\cs{glslabel}} +\strut +\gls{newglossaryentry}\marg{sample}\marg{\field{type}=external,\field{category}=external, + \field{name}=\marg{sample},\field{description}=\marg{an example}} +\strut +\cmd{begin}\marg{document} +\cs{gls}\marg{sample}. +\cmd{end}\marg{document} +\end{codeenv} +In this case the \optfmt{main} glossary isn't used, but the category +attributes allow a mixture of internal and external references, so +the \optfmt{main} glossary could be used for the internal +references. (In which case, \csfmt{makeglossaries} and +\csfmt{printglossaries} would need to be added back to +\filefmt{myarticle.tex}.) + +Note that both documents had to define the common terms. The above +documents can be rewritten to work with \bibgls. First a \ext{bib} +file needs to be created: +\begin{codeenv} +\atentry{entry}\marg{sample, + \field{name}=\marg{sample}, + \field{description}=\marg{an example} +} +\end{codeenv} +Assuming this file is called \filefmt{myentries.bib}, then +\filefmt{mybook.tex} can be changed to: +\begin{codeenv} +\cmd{documentclass}\marg{book} +\cmd{usepackage}[colorlinks]\marg{hyperref} +\cmd{usepackage}[record]\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[myentries]{src}} +\strut +\cmd{begin}\marg{document} +\cs{chapter}\marg{Example} +\cs{gls}\marg{sample}. +\strut +\cs{printunsrtglossaries} +\cmd{end}\marg{document} +\end{codeenv} +and \filefmt{myarticle.tex} can be changed to: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\cmd{usepackage}[colorlinks]\marg{hyperref} +\cmd{usepackage}[record]\marg{glossaries-extra} +\strut +\cs{newignoredglossary*}\marg{external} +\cs{glssetcategoryattribute}\marg{external}\marg{targeturl}\marg{mybook.pdf} +\cs{glssetcategoryattribute}\marg{external}\marg{targetname}\marg{\cs{glolinkprefix}\cs{glslabel}} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[myentries]{src}, + \csopt[none]{sort}, + \csopt[external]{type}, + \csopt[external]{category} +} +\strut +\cmd{begin}\marg{document} +\cs{gls}\marg{sample}. +\cmd{end}\marg{document} +\end{codeenv} +Most of the options related to sorting and the glossary format are +unneeded here since the glossary isn't being displayed. This may be +sufficient for your needs, but it may be that the book has changed +various settings that have been written to \filefmt{mybook.glstex} +but aren't present in the \iext{bib} file (such as +\csopt[uc]{short-case-change}). In this case, you could just remember to copy +over the settings from \filefmt{mybook.tex} to +\filefmt{myarticle.tex}, but +another possibility is to simply make \filefmt{myarticle.tex} input +\filefmt{mybook.glstex} instead of using \gls{GlsXtrLoadResources}. This +can work but it's not so convenient to set the label prefix, the +type and the category. The \optfmt{master} option allows this, but +it has limitations (see below), so in complex cases (in particular +different label prefixes combined with hierarchical entries or cross-references) you'll have to use +the method shown in the example code above. + +\optsection{master} + +This option will disable most of the options that relate to +parsing and processing data contained in \iext{bib} files +(since this option doesn't actually read any \ext{bib} files). +It also can't be used with \csopt[copy]{action} or \csopt[define +or copy]{action}. + +The use of \optfmt{master} isn't always suitable. In particular +if any of the terms cross-reference each other, such as through +the \field{see} or \field{seealso} field or the \field{parent} field or +using commands like \ics{gls} in any of the other fields when +the labels have been assigned prefixes. In this +case you will need to use the method described in the example above. + +The \meta{name} is the name of the \iext{aux} file for the master +document without the extension (in this case, \filefmt{mybook}). It +needs to be relative to the document referencing it or an absolute +path using forward slashes as the directory divider. Remember that +if it's a relative path, the PDF files (\filefmt{mybook.pdf} and +\filefmt{myarticle.pdf}) will also need to be located in the same +relative position. + +When \bibgls\ detects the \csopt{master} option, it won't search for +entries in any \ext{bib} files (for that particular resource set) +but will create a \iext{glstex} file that inputs the master +document's +\ext{glstex} files, but it will additionally temporarily +adjust the internal commands used to define entries so that +the prefix given by \csopt{label-prefix}, the glossary type and the +category type are all automatically inserted. If the \csopt{type} +or \csopt{category} options haven't been used, the corresponding +value will default to \optfmt{master}. The \catattr{targeturl} +and \catattr{targetname} category attributes will automatically be +set, and the glossary type will be provided using +\code{\ics{provideignoredglossary*}\margm{type}}. + +The above \filefmt{myarticle.tex} can be changed to: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\cmd{usepackage}[colorlinks]\marg{hyperref} +\cmd{usepackage}[record]\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[book.]{label-prefix},\csopt[mybook]{master}} +\strut +\cmd{begin}\marg{document} +\cs{gls}\marg{book.sample}. +\cmd{end}\marg{document} +\end{codeenv} + +There are some settings from the master document that you +still need to repeat in the other document. These include +the label prefixes set when the master document loaded +the resource files, and any settings in the master document +that relate to the master document's entries. + +For example, if the master document loaded a resource file +with \csopt[term.]{label-prefix} then you also need this +prefix when you reference the entries in the dependent document +in addition to the \optfmt{label-prefix} for the dependent document. +Suppose \filefmt{mybook.tex} loads the resources using: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[myentries]{src},\csopt[term.]{label-prefix}} +\end{codeenv} +and \filefmt{myarticle.tex} loads the resources using: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[book.]{label-prefix},\csopt[mybook]{master}} +\end{codeenv} +Then the entries referenced in \filefmt{myarticle.tex} need +to use the prefix \optfmt{book.term.}\ as in: +\begin{codeenv} +This is a \cs{gls}\marg{book.term.sample} term. +\end{codeenv} + +Remember that the category labels will need adjusting to reflect the +change in category label in the dependent document. + +For example, if \filefmt{mybook.tex} included: +\begin{codeenv} +\cs{setabbreviationstyle}\marg{long-short-sc} +\end{codeenv} +then \filefmt{myarticle.tex} will need: +\begin{codeenv} +\cs{setabbreviationstyle}\oarg{master}\marg{long-short-sc} +\end{codeenv} +(change \optfmt{master} to \meta{value} if you have used +\csopt[\meta{value}]{category}). You can, of course, choose +a different abbreviation style for the dependent document, +but the category in the optional argument needs to be correct. + +\optsection{master-resources} + +If the master document has multiple resource files +then by default all the master document's +\iext{glstex} files will be input. If you don't want them all +you can use \optfmt{master-resources} to specify +only those files that should be included. The value \meta{list} is +a comma-separated list of names, where each name corresponds +to the final argument of \gls!{glsxtrresourcefile}. +Remember that \gls{GlsXtrLoadResources} is just a shortcut +for \gls{glsxtrresourcefile} that bases the name on \ics{jobname}. +(Note that, as with the argument of \gls{glsxtrresourcefile}, +the \ext{glstex} extension should not be included in \meta{list}.) The file +\primaryresourcefmt\ is considered the primary +resource file and the files \suppresourcefmt{\meta{n}} +(starting with \meta{n} equal to 1) are considered the supplementary resource files. + +For example, to just select the first and third of the +supplementary resource files (omitting the primary +\filefmt{mybook.glstex}): +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[mybook]{master}, + \csopt[mybook-1,mybook-3]{master-resources} +} +\end{codeenv} + +\section{Field and Label Options} +\label{sec:fieldlabelopts} + +The options in this section may be used to set or adjust field +values or labels. Some field values are expected to be labels (such +as \field{group}). These labels must not contain special +characters or commands, but it's possible to convert a field value +into a valid label using options such as \csopt{labelify}. + +\subsection{Label Options} +\label{sec:labelopts} + +\optsection[\subsubsection]{interpret-label-fields} + +This is a boolean option that determines whether or not the fields +that may only contain labels should have their values interpreted +(\field{parent}, \field{category}, \field{type}, \field{group}, +\field{seealso} and \field{alias}). Although this option interprets +commands within those fields, it doesn't strip any characters that +can't be used within a label. The \field{see} field isn't included +as it may optionally start with \code{\oargm{tag}} where \meta{tag} +may legitimately contain \LaTeX\ code that shouldn't be interpreted. + +The default setting is \csopt[false]{interpret-label-fields}. +Note that if this setting is on, \idxpl{crossresourceref} aren't +permitted. This setting has no effect if the interpreter has been +disabled. + +Related settings are \csopt{labelify} and +\csopt{labelify-list} which can be used to strip content that +can't be used in labels and may be used more generally for other +fields. The \csopt{labelify} and \csopt{labelify-list} options +are performed before \csopt{interpret-label-fields}. + +\optsection[\subsubsection]{labelify} + +This option should take a comma-separated list of recognised field names as the +value. (If a field is present in both \csopt{labelify} and +\csopt{labelify-list}, then \csopt{labelify-list} takes precedence.) +Note that if this setting is on, \idxpl{crossresourceref} aren't +permitted. The value is required for this key but may be empty, +which indicates an empty set of fields (that is, the setting is +switched off). + +Each listed field will be converted into a string suitable +for use as a label. (Not necessarily a glossary entry label, but +any label that may be used in the construction of a control sequence +name.) + +The conversion is performed in the following order: +\begin{enumerate} +\item If the interpreter is on and the field value contains +any of the characters \idx{escchar}~(backslash), +\idx{bgroupchar}~(begin group), \idx{egroupchar}~(end group), +\idx{nbspchar}~(non-breakable space) or \idx{mshiftchar}~(maths shift), +then the value is interpreted. + +\item Any substitutions that have been specified with +\csopt{labelify-replace} are performed. + +\item All characters that aren't alphanumeric or the space character + or any of the following punctuation +characters \code{.}~(full stop), \code{-}~(hyphen), \code{+}~(plus), +\code{:}~(colon), \code{;}~(semi-colon), \code{\string|}~(pipe), +\code{/}~(forward slash), \code{!}~(exclamation mark), +\code{?}~(question mark), \code{*}~(asterisk), \code{<}~(less than), +\code{>}~(greater than), \code{\textasciigrave}~(backtick), +\code{'}~(apostrophe) or \code{@}~(at-sign) are stripped. If you want to +retain commas, use \csopt{labelify-list} instead. If you want to +strip any of the allowed punctuation, use \csopt{labelify-replace} to +remove the unwanted characters. (Remember that \sty{babel} can make +some of these punctuation characters active, in which case they need +to be stripped.) + +\item If \bibgls\ hasn't detected \sty{fontspec} in the document's +transcript file, the value is then decomposed and all non-ASCII +characters are removed. +\end{enumerate} + +For example, suppose the \ext{bib} file contains: +\begin{codeenv} +\atentry{index}\marg{sample, + \field{name}=\marg{\ics{AA} ngstr\ics{umlaut}om, \ics{O} stergaard, d'Arcy, and Fotheringay-Smythe} +} +\end{codeenv} +Then: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{data in entries.bib} + \csopt[name]{labelify} +} +\end{codeenv} +will convert the \field{name} field into: +\begin{verbatim} +Angstrom stergaard d'Arcy and Fotheringay-Smythe +\end{verbatim} +if the document hasn't used \sty{fontspec} otherwise it will be: +\begin{verbatim} +Ångström Østergaard d'Arcy and Fotheringay-Smythe +\end{verbatim} +Note that \O\ is considered an unmodified letter and so can't +be decomposed into a basic Latin letter with a combining diacritic. +It's therefore removed completely from the non-\sty{fontspec} +version. Whereas \AA\ can be decomposed into \qt{A} followed by the +\qt{combining ring above} character and \"o can be decomposed into \qt{o} +followed by the \qt{combining diaresis} character. You can use +\csopt{labelify-replace} to replace non-ASCII characters into +the closest match. Alternatively, switch to using \XeLaTeX\ or +\LuaLaTeX. + +You can use this option with \csopt{replicate-fields} if you need +to retain the original: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{data in entries.bib} + \csopt[\field{name}=\marg{\field{user1}}]{replicate-fields}, + \csopt[\field{user1}]{labelify} +} +\end{codeenv} + +\optsection[\subsubsection]{labelify-list} + +This option is like \csopt{labelify} but it retains commas, as it's +designed for fields that should be converted into a comma-separated +list of labels. Any empty elements are removed. For example, with +the \ext{bib} entry from above: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{data in entries.bib} + \csopt[\field{name}=\marg{\field{user1}}]{replicate-fields}, + \csopt[\field{user1}]{labelify-list} +} +\end{codeenv} +will convert the \field{user1} field into: +\begin{verbatim} +Angstrom, stergaard, d'Arcy, and Fotheringay-Smythe +\end{verbatim} +or: +\begin{verbatim} +Ångström, Østergaard, d'Arcy, and Fotheringay-Smythe +\end{verbatim} +depending on whether or not \sty{fontspec} was detected. + +\optsection[\subsubsection]{labelify-replace} + +This option takes a comma-separated list as a value with each +element in the list in the form \code{\margm{regex}\margm{replacement}} +where \meta{regex} is a \idx{regex} (that conforms to \href{http://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html}{Java's +Pattern class}~\cite{pattern}) and \meta{replacement} +is the replacement text. The value is required for this key but +may be empty, which indicates that the +setting is switched off. + +Remember that the argument of +\gls{GlsXtrLoadResources} is expanded when written to the \ext{aux} +file so take care to protect any special characters. For example, to +match a literal \idx{full-stop} use \cs{cs.string}\idx{cs.period} +rather than just \idx{cs.period} (backslash dot). + +In the \meta{replacement} part, you can use +\ics{glscapturedgroup}\meta{n} to reference a captured sub-sequence. +For example: +\begin{codeenv} +\csopt[\marg{([A-Z])\ics{cs.string}\idx{cs.period}}\marg{\cs{glscapturedgroup}1}]{labelify-replace} +\end{codeenv} +This removes any \idx{full-stop} that follows any of the characters +A,\ldots,Z. Alternatively, you can just use \verb|\string\$| +instead of \cs{glscapturedgroup}. If you want a literal dollar +character, you need to use \cs{glshex}\code{24} (or +\verb|\string\u24|). This isn't recommended for labels (since special +characters are automatically stripped), but +\csopt{sort-replace} follows the same rules as +\csopt{labelify-replace}, and it may be needed +for that. + +Both \csopt{labelify} and \csopt{labelify-list} use the +\csopt{labelify-replace} setting to +perform substitutions. For example, to replace the sub-string \qt{ and } +(including spaces) with a comma: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{data in entries.bib} + \csopt[\field{name}=\marg{\field{user1}}]{replicate-fields}, + \csopt[\marg{ and }\marg{,}]{labelify-replace}, + \csopt[\field{user1}]{labelify-list} +} +\end{codeenv} +The earlier example will now end up as: +\begin{verbatim} +Angstrom, stergaard, d'Arcy,Fotheringay-Smythe +\end{verbatim} +or: +\begin{verbatim} +Ångström, Østergaard, d'Arcy,Fotheringay-Smythe +\end{verbatim} +depending on whether or not \sty{fontspec} was detected. + +Note that this produces the same result regardless of whether or not +the Oxford comma is present as \verb*|, and | would first be +converted to \verb|,,| and then the empty element is removed +resulting in a single comma. + +You can have more than one replacement: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{data in entries.bib} + \csopt[\field{name}=\marg{\field{user1}}]{replicate-fields}, + \csopt[ + \marg{ and }\marg{,},\comment{first substitution} + \marg{[ '\cs{cs.string}\cmd{-}]}\marg{},\comment{second substitution} + \marg{\ics{glshex}00D8}\marg{O}\comment{third substitution} + ]{labelify-replace}, + \csopt[\field{user1}]{labelify-list} +} +\end{codeenv} +This additionally removes the space, apostrophe and hyphen +characters (second substitution) and replaces \qt{\O} (\hex{00D8}) +with \qt{O} (third substitution) so the string now ends up as: +\begin{verbatim} +Angstrom,Ostergaard,dArcy,FotheringaySmythe +\end{verbatim} +or: +\begin{verbatim} +Ångström,Ostergaard,dArcy,FotheringaySmythe +\end{verbatim} +depending on whether or not \sty{fontspec} was detected. + +\optsection[\subsubsection]{label-prefix} + +The \csopt{label-prefix} option prepends \meta{tag} to each entry's label. This +\meta{tag} will also be inserted in front of any cross-references, unless they +start with \idprefix{dual} or \idprefix{tertiary} or \idprefix{extn} (where +\meta{n} is an integer). Use \csopt{dual-prefix} to change the dual label +prefixes and \csopt{ext-prefixes} to change the external label prefixes. + +As from version 1.8, the primary label prefix is identified +in the \ext{glstex} file with: +\begin{codeenv} +\format{bibglsprimaryprefixlabel} +\end{codeenv} + +For example, if the \ext{bib} file contains: +\begin{codeenv} +\atentry{entry}\marg{bird, + \field{name}=\marg{bird}, + \field{description} = \marg{feathered animal, such as a \cs{gls}\marg{duck} or \cs{gls}\marg{goose}} +} +\strut +\atentry{entry}\marg{waterfowl, + \field{name}=\marg{waterfowl}, + \field{description}=\marg{Any \cs{gls}\marg{bird} that lives in or about water}, + \field{see}=\marg{[see also]\marg{duck,goose}} +} +\strut +\atentry{index}\marg{duck} +\strut +\atentry{index}\marg{goose,\field{plural}=\qtdelim{geese}} +\end{codeenv} +Then if this \ext{bib} file is loaded with \csopt[gls.]{label-prefix} +it's as though the entries had been defined as: +\begin{codeenv} +\atentry{entry}\marg{gls.bird, + \field{name}=\marg{bird}, + \field{description} = \marg{feathered animal, such as a \cs{gls}\marg{gls.duck} or \cs{gls}\marg{gls.goose}} +} +\strut +\atentry{entry}\marg{gls.waterfowl, + \field{name}=\marg{waterfowl}, + \field{description}=\marg{Any \cs{gls}\marg{gls.bird} that lives in or about water}, + \field{see}=\marg{[see also]\marg{gls.duck,gls.goose}} +} +\strut +\atentry{index}\marg{gls.duck,\field{name}=\marg{duck}} +\strut +\atentry{index}\marg{gls.goose,\field{name}=\marg{goose},\field{plural}=\qtdelim{geese}} +\end{codeenv} + +Remember to use this prefix when you reference the terms in the +document with commands like \ics{gls}. + +\optsection[\subsubsection]{duplicate-label-suffix} + +The \sty{glossaries} package doesn't permit entries with duplicate +labels (even if they're in different glossaries). If you +have multiple \idxpl{resourceset} and an entry that's selected +in one \idx{resourceset} is also selected in another, by +default, \bibgls\ will issue a warning, but it will still write the +entry definition to the \ext{glstex} file, which means you'll also +get a warning from \sty{glossaries-extra} and the duplicate +definition will be ignored, but associated internal fields +set with commands like \cs{GlsXtrSetField} may still be set. + +If you actually want the duplicate, you need to specify a +suffix with \csopt{duplicate-label-suffix}. This suffix is only +set just before writing the entry definition to the \ext{glstex} +file, so it doesn't affect selection criteria nor can label +substitutions be performed in any cross-references. Options such as +\csopt{set-widest} that reference entry labels are incompatible +as they will use the unsuffixed label. + +The actual suffix is formed from \meta{value}\meta{n} where \meta{n} +is an integer that's incremented in the event of multiple +duplicates. For example, \csopt[.copy]{duplicate-label-suffix} will +change the label to \meta{id}\code{.copy1} for the first duplicate +of the entry whose label is \meta{id}, and \meta{id}\code{.copy2} for +the second duplicate, etc. + +\optsection[\subsubsection]{record-label-prefix} + +If set, this option will cause \bibgls\ to pretend that each record +label starts with \meta{tag}, if it doesn't already. For example, suppose +the records in the \ext{aux} file are: +\begin{codeenv} +\gls{glsxtr@record}\marg{bird}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1} +\gls{glsxtr@record}\marg{waterfowl}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1} +\gls{glsxtr@record}\marg{idx.duck}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1} +\gls{glsxtr@record}\marg{idx.goose}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1} +\end{codeenv} +The use of \csopt[idx.]{record-label-prefix} makes \bibgls\ act as +though the records were given as: +\begin{codeenv} +\gls{glsxtr@record}\marg{idx.bird}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1} +\gls{glsxtr@record}\marg{idx.waterfowl}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1} +\gls{glsxtr@record}\marg{idx.duck}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1} +\gls{glsxtr@record}\marg{idx.goose}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1} +\end{codeenv} + + +\optsection[\subsubsection]{cs-label-prefix} + +If you have commands such as \code{\ics{gls}\margm{label}} or +\code{\ics{glstext}\margm{label}} in field +values (in situations where nested link text won't cause a problem) +the \meta{label} will be converted as follows: +\begin{itemize} +\item if \meta{label} starts with \idprefix{dual} then +\idprefix{dual} will be replaced by the \csopt{dual-prefix} value; +\item if \meta{label} starts with \idprefix{tertiary} then +\idprefix{tertiary} will be replaced by the \csopt{tertiary-prefix} value; +\item if \meta{label} starts with \idprefix{extn} then +\idprefix{extn} will be replaced by the corresponding +\csopt{ext-prefixes} setting (if \idx{crossresourceref} mode is +enabled, see \sectionref{sec:resourcesets}); +\item if \meta{label} doesn't start with one of the above recognised +prefixes then, if \csopt{cs-label-prefix} has been used the supplied +value will be inserted otherwise the \csopt{label-prefix} setting +will be inserted. +\end{itemize} +For example, given: +\begin{codeenv} +\atentry{entry}\marg{bird, + \field{name}=\marg{bird}, + \field{description} = \marg{feathered animal, such as a \cs{gls}\marg{duck} or \cs{gls}\marg{goose}} +} +\end{codeenv} +then if \csopt[idx.]{label-prefix} is set but \csopt{cs-label-prefix} +isn't included in the resource option list this will convert the +\field{description} field to: +\begin{codeenv} +\field{description} = \marg{feathered animal, such as a \cs{gls}\marg{idx.duck} or +\cs{gls}\marg{idx.goose}} +\end{codeenv} +However with \csopt[gls.]{cs-label-prefix} the \field{description} +field will be converted to: +\begin{codeenv} +\field{description} = \marg{feathered animal, such as a \cs{gls}\marg{gls.duck} or +\cs{gls}\marg{gls.goose}} +\end{codeenv} +regardless of the \csopt{label-prefix} setting. Whereas if the +original entry definition is: +\begin{codeenv} +\atentry{entry}\marg{bird, + \field{name}=\marg{bird}, + \field{description} = \marg{feathered animal, such as a \cs{gls}\marg{dual.duck} or +\cs{gls}\marg{dual.goose}} +} +\end{codeenv} +then \idprefix{dual} will be replaced by the value of the +\csopt{dual-prefix} option regardless of the \csopt{cs-label-prefix} +setting. + +The \csopt{cs-label-prefix} setting doesn't affect labels in the +fields that have an entry label or label list as the value +(\field{parent}, \field{alias}, \field{see} and \field{seealso}). + +\optsection[\subsubsection]{ext-prefixes} + +Any cross-references in the \iext{bib} file that start with +\idprefix{extn} (where \meta{n} is a positive integer) will be +substituted with the \meta{n}th tag listed in the comma-separated +\meta{list}. If there aren't that many items in the list, the +\idprefix{extn} will simply be removed. The default setting is +an empty list, which will strip all \idprefix{extn} prefixes. +Remember that \idx{crossresourceref} mode needs to be enabled for +this option to work (see \sectionref{sec:resourcesets}). + +As from version 1.8, the external label prefixes are identified +in the \ext{glstex} file with: +\begin{codeenv} +\format{bibglsexternalprefixlabel} +\end{codeenv} + +For example, suppose the file \filefmt{entries-terms.bib} contains: +\begin{codeenv} +\atentry{entry}\marg{set, + \field{name}=\marg{set}, + \field{description}=\marg{collection of values, denoted \cs{gls}\marg{ext1.set}} +} +\end{codeenv} +and the file \filefmt{entries-symbols.bib} contains: +\begin{codeenv} +\atentry{symbol}\marg{set, + \field{name}=\marg{\cs{ensuremath}\marg{\cs{mathcal}\marg{S}}}, + \field{description}=\marg{a \cs{gls}\marg{ext1.set}} +} +\end{codeenv} + +These files both contain an entry with the label \code{set} +but the \field{description} field includes \code{\cs{gls}\marg{ext1.set}} +which is referencing the entry from the other file. These +two files can be loaded without conflict using: +\begin{codeenv} +\cmd{usepackage}[\styopt{record},\styopt{symbols}]\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[entries-terms]{src}, + \csopt[gls.]{label-prefix}, + \csopt[sym.]{ext-prefixes} +} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[entries-symbols]{src}, + \csopt[symbols]{type}, + \csopt[sym.]{label-prefix}, + \csopt[gls.]{ext-prefixes} +} +\end{codeenv} + +Now the \code{set} entry from \filefmt{entries-terms.bib} +will be defined with the label \code{gls.set} and the +description will be: +\begin{codeenv} +collection of values, denoted \cs{gls}\marg{sym.set} +\end{codeenv} +The \code{set} entry +from \filefmt{entries-symbols.bib} will be defined with the label +\code{sym.set} and the description will be: +\begin{codeenv} +a \cs{gls}\marg{gls.set} +\end{codeenv} + +Note that in this case the \ext{bib} files have to be loaded +as two separate resources. They can't be combined into a +single \csopt{src} list as the labels aren't unique. + +If you want to allow the flexibility to choose between +loading them together or separately, you'll have to give them +unique labels. For example, \filefmt{entries-terms.bib} could +contain: +\begin{codeenv} +\atentry{entry}\marg{set, + \field{name}=\marg{set}, + \field{description}=\marg{collection of values, denoted \cs{gls}\marg{ext1.S}} +} +\end{codeenv} +and \filefmt{entries-symbols.bib} could contain: +\begin{codeenv} +\atentry{symbol}\marg{S, + \field{name}=\marg{\cs{ensuremath}\marg{\cs{mathcal}\marg{S}}}, + \field{description}=\marg{a \cs{gls}\marg{ext1.set}} +} +\end{codeenv} +Now they can be combined with: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries-terms,entries-symbols]{src}} +\end{codeenv} +which will simply strip the \glsdisp{idx.idprefix.extn}{\idprefixfmt{ext1}} +prefix from the cross-references. Alternatively: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries-terms,entries-symbols]{src}, + \csopt[gls.]{label-prefix}, + \csopt[gls.]{ext-prefixes} +} +\end{codeenv} +which will insert the supplied \csopt{label-prefix} at the +start of the labels in the entry definitions and will replace +the \idprefixfmt{ext1} prefix with \idprefixfmt{gls} in the +cross-references. + +\optsection[\subsubsection]{save-original-id} + +The \meta{value} may be either the keyword \code{false} or +the name of an internal field in which to store the entry's original +label (as given in the \ext{bib} file). The default setting is +\csopt[false]{save-original-id}. If \meta{value} is omitted, +\csopt[originalid]{save-original-id} is assumed. + +If \meta{value} is a known field, it will be set after the field +aliases, otherwise it will simply be added to the \ext{glstex} file +using \ics{GlsXtrSetField} after the entry definition. + +\optsection[\subsubsection]{dependency-fields} + +The \meta{list} should be a comma-separated list of fields that +have values in the form \code{\oargm{tag}\meta{id-list}} where +\meta{id-list} is a comma-separated list of entry labels. The value +is required for this key but may be empty, which indicates an empty +set of fields (that is, the setting is switched off). + +This setting makes those fields act like the \field{see} field by +identifying the listed entries as dependencies, but the information +isn't added to the cross-reference part of the location list. This +action is performed after \csopt{labelify-list}, if that's also set. + +For example, suppose the file \filefmt{entries-en.bib} contains: +\begin{codeenv} +\atentry{index}\marg{cat, + \fieldfmt{translations-pt}=\marg{gato,gatinho}, + \field{seealso}=\marg{kitten} +} +\strut +\atentry{index}\marg{kitten, + \fieldfmt{translations-pt}=\marg{gato,gatinho} +} +\strut +\atentry{index}\marg{staple} +\atentry{index}\marg{rivet} +\atentry{index}\marg{mat} +\atentry{index}\marg{carpet} +\atentry{index}\marg{rug} +\atentry{index}\marg{tapestry} +\atentry{index}\marg{doormat} +\atentry{index}\marg{matting} +\atentry{index}\marg{coconut-matting, + \field{name}=\marg{coconut matting} +} +\atentry{index}\marg{track} +\atentry{index}\marg{furrow} +\end{codeenv} +and suppose the file \filefmt{entries-pt.bib} contains: +\begin{codeenv} +\atentry{index}\marg{gato, + \field{prefix}=\marg{o}, + \fieldfmt{translations-en}=\marg{cat,staple,rivet}, + \field{seealso}=\marg{gatinho} +} +\strut +\atentry{index}\marg{gatinho, + \fieldfmt{translations-en}=\marg{kitten} +} +\strut +\atentry{index}\marg{tapete, + \fieldfmt{translations-en}=\marg{carpet,rug,mat,tapestry} +} +\strut +\atentry{index}\marg{esteira, + \field{prefix}=\marg{a}, + \fieldfmt{translations-en}=\marg{mat,track,matting,furrow} +} +\strut +\atentry{index}\marg{capacho, + \field{prefix}=\marg{o}, + \fieldfmt{translations-en}=\marg{doormat,matting,mat,coconut-matting} +} +\end{codeenv} +The aim here is to have a document containing an +English-to-Portuguese and a Portuguese-to-English dictionary. The +custom \fieldfmt{translations-pt} and \fieldfmt{translations-pt} +fields contain comma-separated lists of possible translations. In +this case I don't want to use the \field{see} field (and, in fact, +can't for the entries that have the \field{seealso} field set), but +I can identify the values of those fields as dependent entries to +ensure that they are selected even if they're not referenced in the +document. + +For convenience I've aliased the custom fields to \field{user1}: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[T1]\marg{fontenc} +\cmd{usepackage}[utf8]\marg{inputenc} +\cmd{usepackage}[british,brazilian]\marg{babel} +\cmd{usepackage}[colorlinks]\marg{hyperref} +\cmd{usepackage}\oarg{\styopt{record}, + \styopt{nomain}, + \styopt{nostyles}, + \styopt[bookindex]{stylemods}, + \styopt[\glostyle{bookindex}]{style} +}\marg{glossaries-extra} +\cmd{usepackage}\marg{\isty{glossaries-prefix}} +\strut +\cs{newglossary*}\marg{en}\marg{English Terms} +\cs{newglossary*}\marg{pt}\marg{Portuguese Terms} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[en]{type}, + \csopt[entries-en]{src}, + \csopt[en-GB]{sort}, + \csopt[en]{category}, + \csopt[\fieldfmt{translations-pt}=\field{user1}]{field-aliases}, + \csopt[\field{user1}]{dependency-fields}, + \csopt[\field{user1}:pt-BR:\encap{glsentryname}]{sort-label-list} +} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[pt]{type}, + \csopt[entries-pt]{src}, + \csopt[pt-BR]{sort}, + \csopt[pt]{category}, + \csopt[\fieldfmt{translations-en}=\field{user1}]{field-aliases}, + \csopt[\field{user1}]{dependency-fields}, + \csopt[\field{user1}:en-GB:\encap{glsentryname}]{sort-label-list} +} +\strut +\cs{apptoglossarypreamble}\oarg{en}\marg{\cs{selectlanguage}\marg{british}} +\cs{apptoglossarypreamble}\oarg{pt}\marg{\cs{selectlanguage}\marg{brazilian}} +\strut +\cmd{begin}\marg{document} +\cs{selectlanguage}\marg{british} +The \cs{gls}\marg{cat} sat on the \cs{gls}\marg{mat}. +\strut +\cs{selectlanguage}\marg{brazilian} +O \cs{gls}\marg{gato} sentou-se no \cs{gls}\marg{tapete}. +\strut +\cs{renewcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\comment{} + \cs{glsxtrifhasfield}\marg{\field{prefix}}\marg{\idx{param}1}\marg{\ics{xmakefirstuc}\cs{glscurrentfieldvalue}\cs{cs.space}}\marg{}\comment{} + \cs{glossentryname}\marg{\idx{param}1}\comment{} + \cs{glsxtrifhasfield}\marg{\field{useri}}\marg{\idx{param}1} + \marg{; translations: \cs{glsxtrseelist}\cs{glscurrentfieldvalue}}\marg{}\comment{} +} +\cs{printunsrtglossaries} +\cmd{end}\marg{document} +\end{codeenv} + +\subsection{Assignments} +\label{sec:fieldassignments} + +\optsection[\subsubsection]{group} + +The \csopt{group} option will set the \field{group} field to \meta{label} +unless \meta{label} is \optfmt{auto}. If \csopt[auto]{group} then if +the \longarg{group} switch is used the value of the \field{group} +field is set automatically during the sorting (see also \csopt{group-formation} +and \sectionref{sec:logicaldivisions}). If the \longarg{no-group} +setting is on then \csopt[auto]{group} does nothing. + +The corresponding group title can be set with +\gls{glsxtrsetgrouptitle} in the document if the title is different +from the label. The default behaviour is \csopt[auto]{group}. + +For example: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[integer]{sort},\csopt[Constants]{group}, + \csopt[entries-constants]{src}\comment{data in entries-constants.bib} +} +\gls{GlsXtrLoadResources}\oarg{\csopt[letter-case]{sort},\csopt[Variables]{group}, + \csopt[entries-variables]{src}\comment{data in entries-variables.bib} +} +\end{codeenv} +In this case, if the \field{type} field hasn't been set in the \ext{bib} files, +these entries will be added to the same glossary, but will +be grouped according to each instance of \gls{GlsXtrLoadResources}, +with the provided group label. + + +\optsection[\subsubsection]{category} + +The selected entries may all have their \field{category} field +changed before writing their definitions to the \ext{glstex} file. +The \meta{value} may be: +\begin{itemize} +\item \optfmt{same as entry}: set the +\field{category} to the \ext{bib} entry type used to define it +(\idx!{lowercase} and without the initial \code{@}) after any aliasing, +if applicable; + +\item \optfmt{same as original entry}: (new to v1.4) set the \field{category} +to the original entry type (\idx!{lowercase} and without +the initial \code{@}) before it was aliased (behaves like +\optfmt{same as entry} if the entry type wasn't aliased); + +\item \optfmt{same as base}: (new to v1.1) set the \field{category} +to the base name of the \ext{bib} file (without the extension) +that provided the entry definition; + +\item \optfmt{same as type}: set the \field{category} to the same +value as the \field{type} field (if that field has been provided +either in the \ext{bib} file or through the \csopt{type} option); + +\item \meta{label}: the \field{category} is set to +\meta{label} (which mustn't contain any special characters). +\end{itemize} +This will override any +\field{category} fields supplied in the \ext{bib} file. + +When used with \csopt{entry-type-aliases}, the option \csopt[same as +entry]{category} refers to the \emph{target} entry type whereas +\csopt[same as original entry]{category} refers to the +\emph{original} entry type given in the \ext{bib} file. In both +cases, the value is converted to \idx!{lowercase} to ensure consistency. + +For example, if the \ext{bib} file contains: +\begin{codeenv} +\atentry{entry}\marg{bird, + \field{name}=\marg{bird}, + \field{description} = \marg{feathered animal} +} +\strut +\atentry{index}\marg{duck} +\strut +\atentry{index}\marg{goose,\field{plural}=\qtdelim{geese}} +\strut +\atentry{dualentry}\marg{dog, + \field{name}=\marg{dog}, + \field{description}=\marg{chien} +} +\end{codeenv} +then if the document contains: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[same as entry]{category},\csopt[entries]{src}} +\end{codeenv} +this will set the \field{category} of the \code{bird} term to \optfmt{entry} +(since it was defined with \atentry{entry}), the \field{category} of the +\code{duck} and \code{goose} terms to \optfmt{index} (since they were defined +with \atentry{index}), and the \field{category} of the \code{dog} term to +\optfmt{dualentry} (since it was defined with \atentry{dualentry}). Note that +the dual entry \code{dual.dog} doesn't have the category set, since that's +governed by \csopt{dual-category} instead. + +If, instead, the document contains: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[animals]{category},\csopt[entries]{src}} +\end{codeenv} +then the \field{category} of all the primary selected entries will +be set to \optfmt{animals}. Again the dual entry \code{dual.dog} +doesn't have the \field{category} set. + +Note that the categories may be overridden by the commands that are used to +actually define the entries (such as \gls!{bibglsnewindex}). + +For example, if the document contains: +\begin{codeenv} +\cs{newcommand}\marg{\gls{bibglsnewdualentry}}[4]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2,\field{category}=\marg{dual}}\marg{\idx{param}4}\comment{} +} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[animals]{category},\csopt[entries]{src}} +\end{codeenv} +then both the \code{dog} and \code{dual.dog} entries will +have their \field{category} field set to \optfmt{dual} since the +new definition of \gls{bibglsnewdualentry} has overridden +the \csopt[animals]{category} option. + +\optsection[\subsubsection]{type} + +The \meta{value} may be one of: +\begin{itemize} + \item \optfmt{same as entry} set the \field{type} field + to the entry type (\idx!{lowercase} and without the initial \code{@}); + + \item \optfmt{same as original entry} set the \field{type} + to the original entry type (\idx!{lowercase} and without + the initial \code{@}) before it was aliased (behaves like + \optfmt{same as entry} if the entry type wasn't aliased); + + \optfmt{same as base} set the \field{type} field + to the base name of the corresponding \ext{bib} file + (without the extension); + + \item \optfmt{same as category} set the \field{type} field + to the same value as the \field{category} field + (\field{type} unchanged if \field{category} not set); + +\item \optfmt{same as parent}: sets the \field{type} to the same as +the entry's parent (new to v1.9). If the entry doesn't have a parent +or if the parent doesn't have the \field{type} field set, then +no change is made. Entries should always have the same type +as their parent, but it's possible for spawned entries to +pick up the \field{type} field from their \idx{progenitor} entry +(if it was explicitly set in the \ext{bib} file), +which may be inappropriate. + + \item\meta{label} sets the \field{type} field to the glossary + identified by \meta{label}. +\end{itemize} +When used with \csopt{entry-type-aliases}, the option \csopt[same as +entry]{type} refers to the \emph{target} entry type and \csopt[same +as original entry]{type} refers to the \emph{original} entry type +given in the \ext{bib} file. It's not possible to have both +\csopt[same as type]{category} and \csopt[same as category]{type}. + +Note that this setting only changes the \field{type} field for +primary entries. Use \csopt{dual-type} for dual entries. + +For example: +\begin{codeenv} +\cmd{usepackage}[\styopt{record},\styopt{symbols}]\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[entries-symbols]{src},\csopt[symbols]{type}} +\end{codeenv} + +Make sure that the glossary type has already been defined +(see \sectionref{sec:newglossary}). In the above, the +\styopt{symbols} option defines the \code{symbols} glossary. +If you want to use a custom glossary, you need to provide it. For +example: +\begin{codeenv} +\cmd{usepackage}[\styopt{record},\styopt{nomain}]\marg{glossaries-extra} +\strut +\cs{newglossary*}\marg{dictionary}\marg{Dictionary} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[entries-symbols]{src},\csopt[dictionary]{type}} +\end{codeenv} +(The \styopt{nomain} option was added to suppress the +creation of the default \code{main} glossary.) + +\optsection[\subsubsection]{trigger-type} + +The record counting commands, such as \gls{rgls}, use the special +format \ics{glstriggerrecordformat}, which \bibgls\ also treats +as an \idx{ignoredrecord}. This means the entry will still be +identified as having a record for selection purposes, which is +necessary for the entry to be defined for use in the document, but +in order to prevent it from appearing in the glossary you need to +transfer the entry with \csopt[\meta{type}]{trigger-type}. +This will override the \csopt{type}, \csopt{dual-type}, +\csopt{tertiary-type} and the type specification in +\csopt{secondary}. + +The provided value \meta{type} must be a glossary label (not one of +the keywords allowed by \csopt{type}). +You can define the glossary before loading the resource, but +it's not required as \bibgls\ will write +\code{\ics{provideignoredglossary*}\margm{type}} to the \ext{glstex} file +(see \sectionref{sec:newglossary}). + +\optsection[\subsubsection]{progenitor-type} + +This sets the default \field{type} field for the main term defined by +\atentry{progenitor}-like entries. The \meta{value} is as for +\csopt{type}. This doesn't change the \field{type} for the spawned +\idx{progeny}. + +\optsection[\subsubsection]{progeny-type} + +This sets the default \field{type} field for the \idx{progeny} term +spawned by +\atentry{progenitor}-like entries. The \meta{value} is as for +\csopt{type}. This doesn't change the \field{type} for the main +\idx{progenitor}. Remember that with the default +\csopt[parent]{adopted-parent-field} setting, the given type +should match the type of the parent entry. + +\optsection[\subsubsection]{adopted-parent-field} + +This identifies the target field to be set to the corresponding +value of the \field{adoptparents} list by the \idx{progeny} +entries spawned by the \atentry{progenitor} type of entry. +The default is \field{parent}. + +\optsection[\subsubsection]{abbreviation-name-fallback} + +The entry types that define abbreviations (such as +\atentry{abbreviation} and \atentry{acronym}) will, by default, +fallback on the \field{short} field if the \field{name} field is +missing and it's required for some reason (for example, with +\csopt[name]{sort-field}). If you prefer to +fallback on a different field, then you can use this option to +specify the field. For example, +\csopt[long]{abbreviation-name-fallback}. +The \meta{field} value must be a known field label. + +\optsection[\subsubsection]{ignore-fields} + +The \csopt{ignore-fields} key indicates that you want \bibgls\ to +skip the fields listed in the supplied comma-separated \meta{list} of field +labels. Remember that unrecognised fields will always be skipped. + +For example, suppose my \ext{bib} file contains: +\begin{codeenv} +\atentry{abbreviation}\marg{html, + \field{short} =\qtdelim{html}, + \field{long} = \marg{hypertext markup language}, + \field{description}=\marg{a markup language for creating web pages}, + \field{seealso}=\marg{xml} +} +\end{codeenv} +but I want to use the \abbrstyle{short-long} style and I don't want +the cross-referenced term, then I can use +\csopt[seealso,description]{ignore-fields}. + +Note that \csopt[parent]{ignore-fields} removes the \field{parent} +before determining the dependency lists. This means that +\csopt[recorded and deps]{selection} and +\csopt[recorded and ancestors]{selection} won't pick up the +label in the \field{parent} field. + +If you want to maintain the dependency and ancestor relationship but +omit the \field{parent} field when writing the entries to the +\ext{glstex} file, you need to use \csopt{flatten} instead. + +\optsection[\subsubsection]{field-aliases} + +You can instruct \bibgls\ to treat one field as though it +was another using this option. The value should be a comma-separated +list of \meta{field1}\dequals\meta{field2} pairs, where +\meta{field1} and \meta{field2} are field names. Identical +mappings and trails aren't permitted. (That is, \meta{field1} +and \meta{field2} can't be the same nor can you have both +\meta{field1}\dequals\meta{field2} and +\meta{field2}\dequals\meta{field3}.) If you want to swap +fields you need to use one of the dual entry types instead. +Field aliases are performed before \csopt{ignore-fields}, +so if \meta{field1} is listed in \csopt{ignore-fields} it won't +be ignored (unless \meta{field2} is in \csopt{ignore-fields}). + +For example, suppose \filefmt{people.bib} contains: +\begin{codeenv} +\atentry{entry}\marg{alexander, + \field{name}=\marg{Alexander III of Macedon}, + \field{description}=\marg{Ancient Greek king of Macedon}, + \fieldfmt{born}=\marg{20 July 356 BC}, + \fieldfmt{died}=\marg{10 June 323 BC}, + \fieldfmt{othername}=\marg{Alexander the Great} +} +\end{codeenv} +This contains three non-standard fields: \fieldfmt{born}, +\fieldfmt{died} and \fieldfmt{othername}. I could define +these fields using \ics{glsaddkey}, but another possibility +is to map these onto the user keys \field{user1}, \field{user2} +and \field{user3}, which saves the overhead of providing new +keys: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[people]{src},\comment{data in people.bib} + \csopt[\fieldfmt{born}=\field{user1},\fieldfmt{died}=\field{user2},\fieldfmt{othername}=\field{user3}]{field-aliases} +} +\end{codeenv} + +\optsection[\subsubsection]{replicate-fields} + +The value of one field can be copied to other fields using +this option where each \meta{key}\dequals\meta{value} pair +is in the form +\code{\meta{field1}\dequals\marg{\meta{field2},\meta{field3},\ldots}} +where all values are field names. The value is required for this key +but may be empty, which indicates that the setting is switched off. + +This option copies the contents +of \meta{field1} to \meta{field2}, \meta{field3}, \ldots\ +(only if the target field isn't already set with +\csopt[false]{replicate-override}). This action is +performed after \csopt{ignore-fields} (see +\sectionref{sec:resourcesets}). If the source field is missing, the +\csopt{replicate-missing-field-action} setting determines the +action. + +For example, suppose \filefmt{people.bib} contains: +\begin{codeenv} +\atentry{entry}\marg{alexander, + \field{name}=\marg{Alexander III of Macedon (Alexander the Great)}, + \field{text}=\marg{Alexander}, + \field{description}=\marg{Ancient Greek king of Macedon} +} +\end{codeenv} +Since the \field{first} field hasn't been supplied, it +will default to the value of the \field{text} field, but +perhaps for one of my documents I'd like the \field{first} +field to be the same as the \field{name} field. Rather than +editing the \ext{bib} file, I can just do: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[people]{src},\comment{data in people.bib} + \csopt[\field{name}=\field{first}]{replicate-fields} +} +\end{codeenv} +This copies the contents of the \field{name} field into the +\field{first} field. If you have more than one field +in the list take care to brace the lists to avoid confusion. +For example, if for some reason I want to copy the value +of the \field{name} field to both \field{first} and +\field{firstplural} and copy the value of the \field{text} +field to the \field{plural} field, then this requires braces +for the inner list: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[people]{src},\comment{data in people.bib} + \csopt[\field{name}=\marg{\field{first},\field{firstplural}},\field{text}=\field{plural}]{replicate-fields} +} +\end{codeenv} + +If my \filefmt{people.bib} file instead contained: +\begin{codeenv} +\atentry{entry}\marg{alexander, + \field{name}=\marg{Alexander III of Macedon (Alexander the Great)}, + \field{first}=\marg{Alexander the Great}, + \field{text}=\marg{Alexander}, + \field{description}=\marg{Ancient Greek king of Macedon} +} +\end{codeenv} +then: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[people]{src},\comment{data in people.bib} + \csopt[\field{name}=\field{first}]{replicate-fields} +} +\end{codeenv} +won't alter the \field{first} field since \csopt{replicate-fields} +doesn't override existing values by default. You can use +\csopt{replicate-override} to change this. Alternatively, since +\csopt{replicate-fields} is always performed after \csopt{ignore-fields} +it's possible to ignore the \field{first} field which means that the +\field{name} value can then be copied into it: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[people]{src},\comment{data in people.bib} + \csopt[\field{first}]{ignore-fields}, + \csopt[\field{name}=\field{first}]{replicate-fields} +} +\end{codeenv} +Note that the ordering within the resource options doesn't +make a difference. The same result occurs with: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[people]{src},\comment{data in people.bib} + \csopt[\field{name}=\field{first}]{replicate-fields}, + \csopt[\field{first}]{ignore-fields} +} +\end{codeenv} + +\optsection[\subsubsection]{replicate-override} + +This is a boolean option. The default setting is +\csopt[false]{replicate-override}. If \optfmt{true}, +\csopt{replicate-fields} will override the existing value if the +target field is already set. + +\optsection[\subsubsection]{replicate-missing-field-action} + +This option indicates what to do if a source field identified in +\csopt{replicate-fields} is missing. The value may be one of: +\begin{itemize} +\item \optfmt{skip}: skip the replication of the missing field +(default); +\item \optfmt{fallback}: use the fallback for the missing field, if +one is available (otherwise skip); +\item \optfmt{empty}: make the target field empty. +\end{itemize} + +\optsection[\subsubsection]{counter} + +The \csopt{counter} option assigns the default counter to use +for the selected entries. (This can be overridden with the +\glsopt{counter} key when using commands like \csfmt{gls}.) +The value must be the name of a counter. Since \bibgls\ doesn't know +which counters are defined within the document, there's no check to +determine if the value is valid (except for ensuring that +\meta{value} is non-empty). + +Note that this will require an extra \LaTeX\ and \bibgls\ call since +the counter can't be used for the indexing until the entry has been +defined. + +\optsection[\subsubsection]{copy-action-group-field} + +This option may only be used when invoking \bibgls\ with the +\longarg{group} (or \shortargfmt{g}) switch. If an action +other than the default \csopt[define]{action} is set, +this option can be used to identify a field in which to save +the letter group information +where \meta{value} is the name of the field. This just uses +\cs{GlsXtrSetField}. You will need to redefine +\ics{glsxtrgroupfield} to \meta{value} before displaying the glossary. +For example, if \csopt[dupgroup]{copy-action-group-field}, +\csopt[copy]{action} and \csopt[copies]{type} are set in +the resource options and \code{copies} identifies a custom +glossary: +\begin{codeenv} +\ics{printunsrtglossary*}\oarg{\printglossopt[copies]{type},\printglossopt[\glostyle{indexgroup}]{style}} + \marg{\cs{renewcommand}\marg{\cs{glsxtrgroupfield}}\marg{dupgroup}} +\end{codeenv} + +This option is ignored when used with \csopt[define]{action}. +This option is not used by \csopt{secondary} which will +always save the group information in the \field{secondarygroup} +field. When used with \csopt[define or copy]{action}, entries +that are defined will have both \field{group} and +the field given by \csopt{copy-action-group-field} set. + +Note that you may do \csopt[group]{copy-action-group-field} which +will override the \field{group} field from the original definition. +This may be useful if you don't use grouping in the primary +glossary. That is, you use \code{nogroupskip} and a non-group +style. For example: +\begin{codeenv} +\cs{printunsrtglossary}\oarg{\printglossopt{nogroupskip},\printglossopt[\glostyle{index}]{style}} +\cs{printunsrtglossary}\oarg{\printglossopt[copies]{type},\printglossopt[indexgroup]{style}} +\end{codeenv} + +\optsection[\subsubsection]{copy-alias-to-see} + +If set, the value of the \field{alias} field is copied to +the \field{see} field. The default setting is \csopt[false]{copy-alias-to-see}. + +\optsection[\subsubsection]{save-original-entrytype} + +If this is set to \optfmt{true}, the original entry type +(without the leading \idx{atchar}) is stored in the +\field{originalentrytype} field. If no entry aliasing has been +applied (with \csopt{entry-type-aliases}) the field will be set to +the actual entry type. + +\subsection{Field Adjustments} +\label{sec:fieldmods} + +\optsection[\subsubsection]{post-description-dot} + +The \styopt{postdot} package option (or \styopt[false]{nopostdot}) +can be used to append a \idx{full-stop} (\idx{periodchar})\ to the +end of all the descriptions. This can be awkward if some of the +descriptions end with punctuation characters. This resource option +can be used instead. The \meta{value} may be one of: +\begin{itemize} +\item\optfmt{none}: don't append a \idx{full-stop} (default); +\item\optfmt{all}: append a \idx{full-stop} to all \field{description} + fields in this resource set; +\item\optfmt{check}: selectively append a \idx{full-stop} (see below). +\end{itemize} +Note that if you have dual entries and you use this option to +append a \idx{full-stop}, then it will be copied over to the mapped field. +This is different to the \styopt{postdot} option which doesn't +add the dot to the field but incorporates it in the +\idx{postdescriptionhook}. This means that a dot inserted with +\csopt{post-description-dot} will come before the +\idx{postdescriptionhook} whereas with \styopt{postdot} the +punctuation comes after any category-specific hook. + +The \csopt[check]{post-description-dot} setting determines whether +to append the dot as follows: +\begin{itemize} +\item If the \field{description} field ends with +\ics{nopostdesc} or \ics{glsxtrnopostpunc}, then a dot isn't appended. +\item If the \field{description} field doesn't end with a regular +(ungrouped letter or other) character, then a dot is appended. +(For example, if the description ends with a control sequence +or an end group token.) +\item If the \field{description} field ends with a character +that belongs to the Unicode category \idx{punctuationclose} +or \idx{punctuationfinalquote} then the token preceding +that character is checked. +\item If the \field{description} field doesn't end with +a character that belongs to the Unicode category +\idx{punctuationother} then the dot is added. +\end{itemize} +Note that the interpreter isn't used during the check. +If the \field{description} ends with a command then a dot will be +appended (unless it's \cs{glsxtrnopostpunc} or \cs{nopostdesc}) even if +that command expands in such a way that it ends with a terminating +punctuation character. This option only applies to the +\field{description} field. + +\optsection[\subsubsection]{strip-trailing-nopost} + +This option is always performed before \csopt{post-description-dot}. +The default setting is \csopt[false]{strip-trailing-nopost}. If \optfmt{true} +any trailing ungrouped \ics{nopostdesc} or \ics{glsxtrnopostpunc} found in the +\field{description} field will be removed. Note that the command (possibly +followed by ignored space) must be at the very end of the description for it to +be removed. A description should not contain both commands. This option only +applies to the \field{description} field. + +For example, \cs{nopostdesc} will be stripped from: +\begin{codeenv} +\field{description}=\marg{sample\cs{nopostdesc}} +\end{codeenv} +since it's at the end. It will also be stripped from: +\begin{codeenv} +\field{description}=\marg{sample\cs{nopostdesc} } +\end{codeenv} +since the trailing space is ignored as it follows a control +word. It won't be stripped from: +\begin{codeenv} +\field{description}=\marg{sample\cs{nopostdesc}\marg{} } +\end{codeenv} +because the final space is now significant, but even without the +space it still won't be stripped as the field ends with +an empty group not with \cs{nopostdesc}. Similarly it won't be +stripped from: +\begin{codeenv} +\field{description}=\marg{sample\cs{nopostdesc}\cmd{relax}} +\end{codeenv} +because again it's not at the end. + +\optsection[\subsubsection]{check-end-punctuation} + +This options checks the end of all the fields given in \meta{list} for +end of sentence punctuation. This is determined as follows, for each +\meta{field} in the comma-separated \meta{list}: +\begin{itemize} +\item if the last character is of type \idx{punctuationclose} +or \idx{punctuationfinalquote}, check the character that comes +before it; +\item if the character is of type \idx{punctuationother}, then check +if it's listed in the entry given by \idx{sentence.terminators} +in \bibgls's \langxml. +\end{itemize} +If a sentence terminator is found, an internal field is created +called \field{fieldendpunc} that contains the punctuation +character. Fields whose values must be labels (such as +\field{parent}, \field{category} and \field{type}) aren't checked, +even if they're included in \meta{list}. + +The default \idx{sentence.terminators} is defined in \file{bib2gls-en.xml} +as: +\begin{verbatim} +<entry key="sentence.terminators">.?!</entry> +\end{verbatim} +Any character that isn't of type \idx{punctuationother} won't +match. + +For example, the sample \exfile{books.bib} file contains: +\begin{codeenv} +\atentry{entry}\marg{whydidnttheyaskevans, + \field{name}=\marg{Why Didn't They Ask Evans?}, + \field{description}=\marg{novel by Agatha Christie}, + \fieldfmt{identifier}=\marg{book}, + \fieldfmt{author}=\marg{\gls{sortmediacreator}\marg{Agatha}\marg{Christie}}, + \fieldfmt{year}=\marg{1934} +} +\end{codeenv} +With \csopt[name]{check-end-punctuation}, this entry will be +assigned an internal field called +\fielddisp{fieldendpunc}{nameendpunc} set to \code{?}\ +as that's included in \idx{sentence.terminators} and is found +at the end of the \field{name} field: +\begin{codeenv} +\cs{GlsXtrSetField}\marg{whydidnttheyaskevans}\marg{nameendpunc}\marg{?} +\end{codeenv} +(Note that \csopt[first,text]{check-end-punctuation} won't match +as there's no \field{first} or \field{text} field supplied.) + +If you have a field that ends with an abbreviation followed by a +\idx{full-stop}, this will be considered an end of sentence terminator, but +the main purpose of this option is to provide a way to deal with +cases like: +\begin{codeenv} +Agatha Christie wrote \cs{gls}\marg{whydidnttheyaskevans}. +\end{codeenv} +where the end of sentence punctuation following \cs{gls} needs to be +discarded. This is needed regardless of whether or not +the link text ends with an abbreviation or is a complete sentence. + +It's then possible to hook into the \idx{postlinkhook} \qt{discard +period} check. By default this just checks the category attributes +that govern whether or not to discard a following period, but +(with \styfmt{glossaries-extra} v1.23+) it's possible to provide +an additional check by redefining: +\nosecdef{glsxtrifcustomdiscardperiod} +This should expand to \meta{true} if the check should be performed +otherwise it should expand to \meta{false}. You can reference the +label using \cs{glslabel}. For example: +\begin{codeenv} +\cs{renewcommand}*\marg{\gls{glsxtrifcustomdiscardperiod}}[2]\marg{\comment{} + \cs{GlsXtrIfFieldUndef}\marg{nameendpunc}\marg{\cs{glslabel}}\marg{\idx{param}2}\marg{\idx{param}1}\comment{} +} +\end{codeenv} +This uses \ics{GlsXtrIfFieldUndef} rather than +\ics{glsxtrifhasfield*} since there's no need to access the field's +value. (The unstarred form \ics{glsxtrifhasfield} can't be used +as it introduces implicit scoping, which would interfere with the +punctuation lookahead.) The other difference between +\ics{GlsXtrIfFieldUndef} and the other \csfmt{\ldots hasfield} tests +is the case where the field is set to an empty value. In this case +the field is defined (so \ics{GlsXtrIfFieldUndef} does the +\meta{false} argument) but it's considered unset (so commands like +\ics{ifglshasfield} do the \meta{false} argument). + +\optsection[\subsubsection]{sort-label-list} + +This option takes a list as the value with each element in the list +in the form: +\begin{codeenv} +\code{\meta{field-list}:\meta{sort}:\meta{csname}} +\end{codeenv} +or: +\begin{codeenv} +\code{\meta{field-list}:\meta{sort}} +\end{codeenv} +where: +\begin{itemize} +\item \meta{field-list} is a comma-separated list of valid fields; +\item \meta{sort} is a valid sort method as per the \csopt{sort} +option, but not including \optfmt{none} or \optfmt{unsrt}; +\item \meta{csname} is the name (without a leading backslash) of a +command that takes a label as its sole mandatory argument that's +recognised by \bibgls' interpreter (such as those listed in +\tableref{tab:bibglsdefs}). +\end{itemize} +The final \code{:\meta{csname}} part may be omitted if no command +need be applied. (That is, sort by label.) The value is required for this key but +may be empty, which indicates the setting is switched off. + +The sorting options are as those for the main list. For example, +for entries in the primary list the break point is obtained from the +\csopt{break-at} setting and for entries in the dual list the break +point is obtained from \csopt{dual-break-at}. (Remember that if +\csopt[combine]{dual-sort} then there is only one list that contains both +the primary and dual entries, which is governed by the primary +options only.) + +If the \meta{field-list} has more than one element +take care to use braces \code{\marg{}} to avoid confusion for the +list-parser. For example: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[\marg{see,seealso}:en:glsentryname]{sort-label-list} +} +\end{codeenv} + +Note that strange results may occur if this setting is used on any +fields that don't simply contain a list of entry labels or if any of +the referenced entries are processed in different +\idxpl{resourceset} (see \sectionref{sec:resourcesets}). + +After the main sorting of each set of selected entries is performed +(as per \csopt{sort} or \csopt{dual-sort}), if this +option is set, then for each +\code{\margm{field-list}:\meta{sort}:\meta{csname}} the following +steps are performed: +\begin{enumerate} +\item For each entry \meta{id}: + \begin{enumerate} + \item For each \meta{field} in \meta{field-list}, if the field is + set for entry \meta{id} then: + + \begin{enumerate} + \item The field value must be in the form + \code{\oargm{tag}\meta{label-list}} where + \code{\oargm{tag}} is optional and + \meta{label-list} is a comma-separated list of entry labels + \meta{label$_1$}, \ldots, \meta{label$_n$}; + \item A new list is constructed where the $i$th element is: + \code{\marg{\csfmt{}\meta{csname}\margm{label$_i$}}} + unless \meta{csname} hasn't been set, in which case the + $i$th element is just \margm{label$_i$} (the optional + \oargm{tag} part is omitted); + \item This new list is sorted according to the interpreter's + definition of the command given by \meta{csname} (if provided) + and the designated \meta{sort} method; + \item The field value is reconstructed with the labels in the + corresponding order (prefixed with \code{\oargm{tag}} if it was + present in the original). + \end{enumerate} + \end{enumerate} +\end{enumerate} +Note that there is no hierarchical structure in the sorting of the field list +even if any of the referenced entries has a parent. + +For example, suppose the file \filefmt{entries.bib} contains: +\begin{codeenv} +\atentry{index}\marg{bird} +\strut +\atentry{index}\marg{waterfowl, \field{parent}=\marg{bird} } +\strut +\atentry{index}\marg{duck, + \field{parent}=\marg{waterfowl}, + \field{seealso}=\marg{swan,duckling,parrot,goose} +} +\strut +\atentry{index}\marg{swan, + \field{parent}=\marg{waterfowl}, + \field{seealso}=\marg{goose,duck} +} +\strut +\atentry{index}\marg{goose, + \field{parent}=\marg{waterfowl}, + \field{seealso}=\marg{duck} +} +\strut +\atentry{index}\marg{parrot, \field{parent}=\marg{bird} } +\strut +\atentry{index}\marg{duckling, + \field{see}=\marg{[related terms]fluffy,velociraptor,duck,tardigrade} +} +\strut +\atentry{index}\marg{fluffy} +\strut +\atentry{index}\marg{tardigrade, \field{name}=\marg{water bear} } +\strut +\atentry{index}\marg{velociraptor} +\end{codeenv} +And suppose the document contains: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[\styopt{record},\styopt[tree]{style}]\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src}, + \csopt[en]{sort}, + \csopt[\marg{seealso,see}:en:glsentryname]{sort-label-list} +} +\strut +\cmd{begin}\marg{document} +\cs{Gls}\marg{parrot}, \cs{gls}\marg{tardigrade}, \cs{gls}\marg{swan}, \cs{gls}\marg{duck}, +\cs{gls}\marg{goose}, \cs{gls}\marg{fluffy} \cs{gls}\marg{duckling}, \cs{gls}\marg{velociraptor}. +\strut +\cs{printunsrtglossaries} +\cmd{end}\marg{document} +\end{codeenv} +Then this reorders the \field{see} and \field{seealso} fields according to +the referenced entry's name (obtained with \ics{glsentryname}). + +For example, the \field{see} field for the \code{duckling} entry was +originally: +\begin{codeenv} +\field{see}=\marg{[related terms]fluffy,velociraptor,duck,tardigrade} +\end{codeenv} +but in the \ext{glstex} file it's written as: +\begin{codeenv} +\field{see}=\marg{[related terms]duck,fluffy,velociraptor,tardigrade} +\end{codeenv} +The reason for \code{tardigrade} being placed after +\code{velociraptor} is because +\code{\ics{glsentryname}\marg{tardigrade}} is expanded to \qt{water +bear} (and \qt{W} comes after \qt{V}). If no encapsulating command +was specified: +\begin{codeenv} +\csopt[\marg{seealso,see}:en]{sort-label-list} +\end{codeenv} +then the list would have been sorted according to the labels +instead (and so \code{tardigrade} would come before +\code{velociraptor}). Note that the optional tag is kept at the start of the +list. + +The \field{seealso} fields have also been changed. For example, +the \code{duck} entry originally had: +\begin{codeenv} +\field{seealso}=\marg{swan,duckling,parrot,goose} +\end{codeenv} +but in the \ext{glstex} file it's written as: +\begin{codeenv} +\field{seealso}=\marg{duckling,goose,parrot,swan} +\end{codeenv} +Note that the hierarchical structure hasn't been maintained. The glossary +lists \qt{duckling} (a top-level entry) after \qt{swan} (a level~2 entry) +but the \field{seealso} field has \code{duckling} first. + +If you want to maintain the hierarchy you can use \ics{glsxtrhiername} instead +of \ics{glsentryname}: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src}, + \csopt[en]{sort}, + \csopt[\marg{seealso,see}:en:glsxtrhiername]{sort-label-list} +} +\end{codeenv} +The separator between the levels is +given by \ics{glsxtrhiernamesep} which is defined by +\sty{glossaries-extra} to produce \qt{\glsxtrhiernamesep}. +The \bibgls\ interpreter's definition of this command is different +to assist sorting and simply expands to a \idx{full-stop} to prevent +it from being replaced by the default word break marker. + +In this case \code{\ics{glsxtrhiername}\marg{swan}} would be +displayed as \qt{bird\glsxtrhiernamesep waterfowl\glsxtrhiernamesep +swan} if used in the document, but the interpreter converts it to +\qt{bird.waterfowl.swan}, so with the default \csopt{break-at} +setting the actual sort value becomes \code{bird.waterfowl.swan|} +(instead of \code{bird|waterfowl|swan|} which would be the result if +the interpreter used the same definition as \sty{glossaries-extra}). + +Therefore the \field{seealso} field for the \code{duck} entry ends up as: +\begin{codeenv} +\field{seealso}=\marg{parrot,goose,swan,duckling} +\end{codeenv} +Now \code{swan} comes before \code{duckling} because the actual sort +value started with a \qt{B} not \qt{S}. + +This hierarchical information isn't shown in the cross-reference by +default, so the \code{duck} cross-reference list appears in the +document as: parrot, goose, swan \& duckling. + +If you want the hierarchical information to appear to help assist +the reader, you can redefine \ics{glsseeitemformat} in the document +to use \ics{glsxtrhiername}: +\begin{codeenv} +\cmd{renewcommand}*\marg{\cs{glsseeitemformat}}[1]\marg{\cs{glsxtrhiername}\marg{\idx{param}1}} +\end{codeenv} +This means that the \code{duck} cross-reference now appears in the +document as: bird\glsxtrhiernamesep parrot, bird\glsxtrhiernamesep +waterfowl\glsxtrhiernamesep goose, bird\glsxtrhiernamesep waterfowl +\glsxtrhiernamesep swan \& duckling. + +This next example document has two languages, English and +Portuguese. The file \filefmt{entries-en.bib} contains the English +terms, such as: +\begin{codeenv} +\atentry{index}\marg{cat, \fieldfmt{translations}=\marg{gato,gatinho} } +\atentry{index}\marg{kitten, \fieldfmt{translations}=\marg{gatinho} } +\atentry{index}\marg{staple, \fieldfmt{translations}=\marg{grampo}} +\atentry{index}\marg{rivet, \fieldfmt{translations}=\marg{rebite}} +\end{codeenv} +The file \filefmt{entries-pt.bib} contains the Portuguese +terms, such as: +\begin{codeenv} +\atentry{index}\marg{gato, \fieldfmt{translations}=\marg{cat,staple,rivet} } +\atentry{index}\marg{gatinho, \fieldfmt{translations}=\marg{kitten} } +\end{codeenv} + +Both files have a custom field called \fieldfmt{translations} that +will need to be either defined or aliased. This field contains a +comma-separated list of labels for the corresponding entries in the +other language file that provide a possible translation. Where a +word has multiple possible translations, I'd like the list sorted +alphabetically. (In practice, it would make more sense to sort them +according to how likely the translation is, but this is for +illustrative purposes.) For convenience, the +custom field is simply aliased to the \field{user1} field. + +The document has two glossaries for each set of terms. The English +terms are sorted according to \csopt[en-GB]{sort} in one +\idx{resourceset} and the Portuguese terms are sorted according to +\csopt[pt-BR]{sort} in another \idx{resourceset}. This means that there +are cross-resource references, but since there are no instances of +\atentry{preamble} it should be possible to resolve the references. + +The document code is: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[T1]\marg{fontenc} +\cmd{usepackage}[utf8]\marg{inputenc} +\cmd{usepackage}[british,brazilian]\marg{babel} +\cmd{usepackage}\oarg{\styopt{record}, + \styopt{nomain}, + \styopt{nostyles}, + \styopt[bookindex]{stylemods}, + \styopt[bookindex]{style} +}\marg{glossaries-extra} +\cmd{usepackage}\marg{glossaries-prefix} +\strut +\cs{newglossary*}\marg{en}\marg{English Terms} +\cs{newglossary*}\marg{pt}\marg{Portuguese Terms} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[all]{selection}, + \csopt[en]{type}, + \csopt[entries-en]{src}, + \csopt[en-GB]{sort}, + \csopt[\fieldfmt{translations}=\field{user1}]{field-aliases}, + \csopt[\field{user1}:pt-BR:\encap{glsentryname}]{sort-label-list} +} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[all]{selection}, + \csopt[pt]{type}, + \csopt[entries-pt]{src}, + \csopt[pt-BR]{sort}, + \csopt[\fieldfmt{translations}=\field{user1}]{field-aliases}, + \csopt[\field{user1}:en-GB:\encap{glsentryname}]{sort-label-list} +} +\strut +\cs{apptoglossarypreamble}\oarg{en}\marg{\ics{selectlanguage}\marg{british}} +\cs{apptoglossarypreamble}\oarg{pt}\marg{\cs{selectlanguage}\marg{brazilian}} +\strut +\cmd{begin}\marg{document} +\cs{renewcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\comment{} + \cs{glossentryname}\marg{\idx{param}1}\comment{} + \cs{glsxtrifhasfield}\marg{useri}\marg{\idx{param}1}\marg{: \ics{glsxtrseelist}\cs{glscurrentfieldvalue}}\marg{}\comment{} +} +\cs{printunsrtglossaries} +\cmd{end}\marg{document} +\end{codeenv} +In verbose mode, the transcript file indicates that it's performing +the label list sorting. For example, when sorting according to +\csopt[user1:pt-BR:glsentryname]{sort-label-list}, the transcript +file contains: +\begin{verbatim} +Label list sort method 'pt-BR' on field: user1 +\end{verbatim} +The \code{cat} entry has a list of two elements in this field: +\code{gato,gatinho}. This is converted into a new list where the +first element is: +\begin{codeenv} +\marg{\cs{glsentryname}\marg{gato}} +\end{codeenv} +and the second element is: +\begin{codeenv} +\marg{\cs{glsentryname}\marg{gatinho}} +\end{codeenv} +Regardless of the level of verbosity, the transcript file will +contain the conversions obtained by the interpreter: +\begin{verbatim} +texparserlib: {\glsentryname{gato}} -> gato +texparserlib: {\glsentryname{gatinho}} -> gatinho +\end{verbatim} +The \code{kitten} entry has the same list, and the same process is +repeated for that entry. The \longarg{verbose} mode will provide additional +information. The \longarg{debug} mode will indicate whether the +referenced label was found in the current \idx{resourceset} or if it had +to be fetched from another \idx{resourceset}. So if the resulting +order isn't what you expect, check the transcript file for messages. + +\optsection[\subsubsection]{bibtex-contributor-fields} + +This option indicates that the listed fields all use \BibTeX's name +syntax (as used in \BibTeX's \code{author} and \code{editor} fields). The value is required for this key but +may be empty, which indicates an empty set of fields (that is, the +setting is switched off). + +The values of these fields will be converted into the form: +\begin{codeenv} +\gls{bibglscontributorlist}\margm{contributor list}\margm{n} +\end{codeenv} +where \meta{n} is the number of names in the list and +\meta{contributor-list} is a comma-separated list of names in the +form: +\begin{codeenv} +\gls{bibglscontributor}\margm{forenames}\margm{von-part}\margm{surname}\margm{suffix} +\end{codeenv} + +The \gls{bibglscontributorlist} command is initially defined in +\bibgls's interpreter to just do the first argument and ignore the +second. This means that if you're sorting on this field, the \qt{and} +part between the final names doesn't appear in the sort value. +The actual definition of \gls{bibglscontributorlist} provided in the +\ext{glstex} file depends on whether or not \ics{DTLformatlist} is defined. +(Note that \styfmt{glossaries} automatically loads \sty{datatool-base} +so this command will be defined if you have at least v2.28 of +\sty{datatool-base}.) + +For example, if the \field{name} field is specified as: +\begin{codeenv} +\field{name}=\marg{John Smith and Jane Doe and Dickie von Duck} +\end{codeenv} +then \csopt[name]{bibtex-contributor-fields} will convert the +\field{name} field value to: +\begin{codeenv} +\gls{bibglscontributorlist}\marg{\comment{} + \gls{bibglscontributor}\marg{John}\marg{}\marg{Smith}\marg{},\comment{} + \gls{bibglscontributor}\marg{Jane}\marg{}\marg{Doe}\marg{},\comment{} + \gls{bibglscontributor}\marg{Dickie}\marg{von}\marg{Duck}\marg{}}\marg{3} +\end{codeenv} +With \csopt[von]{contributor-order} the sort value obtained from +this field will be: +\begin{verbatim} +Smith, John,Doe, Jane,von Duck, Dickie +\end{verbatim} +With one of the locale sort methods and with the default +\csopt[word]{break-at}, this will end up as: +\begin{verbatim} +Smith|John|Doe|Jane|von|Duck|Dickie +\end{verbatim} + +\optsection[\subsubsection]{contributor-order} + +The \gls{bibglscontributor} command is defined in +\bibgls's interpreter and its definition is dependent on this +setting. The \meta{value} may be one of (where the parts in square +brackets are omitted if that argument is empty): +\begin{itemize} +\item \optfmt{surname}: \gls{bibglscontributor} expands to +\meta{surname}\oarg{, \meta{suffix}}\oarg{, \meta{forenames}}\oarg{, +\meta{von-part}}; +\item \optfmt{von}: \gls{bibglscontributor} expands to +\oarg{\meta{von-part} }\meta{surname}\oarg{, \meta{suffix}}\oarg{, \meta{forenames}}; +\item \optfmt{forenames}: \gls{bibglscontributor} expands to +\oarg{\meta{forenames} }\oarg{\meta{von-part} }\meta{surname}\oarg{, +\meta{suffix}}. +\end{itemize} +The default value is \optfmt{von}. Note that if you have multiple +resource sets, this option governs the way \bibgls's version of +\gls{bibglscontributor} behaves. The actual definition is written to +the \ext{glstex} using \cs{providecommand}, which means that \LaTeX\ +will only pick up the first definition. + +For example: +\begin{codeenv} +\cs{newcommand}*\marg{\gls{bibglscontributor}}[4]\marg{\comment{} + \idx{param}1\ics{ifstrempty}\marg{\idx{param}2}\marg{}\marg{ \idx{param}2} \idx{param}3\cs{ifstrempty}\marg{\idx{param}4}\marg{}\marg{, \idx{param}4}\comment{} +} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{data in entries.bib} + \csopt[name]{bibtex-contributor-fields} +} +\end{codeenv} +This will display the names in the glossary with the forenames +first, but \bibgls\ will sort according to surname. + +An alternative approach, if you need an initial resource set +such as with the \exfile{no-interpret-preamble.bib} file: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[no-interpret-preamble]{src}, + \csopt[false]{interpret-preamble}, + \csopt[name]{bibtex-contributor-fields}, + \csopt[forenames]{contributor-order} +} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{data in entries.bib} + \csopt[name]{bibtex-contributor-fields} +} +\end{codeenv} +Note the need to use \csopt[name]{bibtex-contributor-fields} +in the first resource set even though there are no entries in +the \ext{bib} file. This is because the definition of +\gls{bibglscontributor} is only written to the \ext{glstex} file if +\csopt{bibtex-contributor-fields} has been set to a non-empty list. +The second resource set will use the default +\csopt[von]{bibtex-contributor-fields} setting when obtaining the +sort value. + +\optsection[\subsubsection]{encapsulate-fields} + +This option should take a comma-separated list of +\optfmt{\meta{field}\dequals\meta{cs-name-1arg}} values, where +\meta{cs-name-1arg} is the name of a control sequence that takes +one argument. The value is required for this key but +may be empty, which indicates an empty set (that is, the +setting is switched off). + +During the processing stage, each field identified in +the list (if defined) will have its value replaced with: +\begin{codeenv} +\cmd{\meta{cs-name-1arg}}\margm{value} +\end{codeenv} +where \meta{value} was its previous value. An +empty list switches off encapsulation (the default). + +This action overrides any previous use of \csopt{encapsulate-fields} +within the same \idx{resourceset} and is always performed before +\csopt{encapsulate-fields*}, regardless of the order in the +\idx{resourceset}['s] list of options. + +\optsection[\subsubsection]{encapsulate-fields*} + +This option should take a comma-separated list of +\optfmt{\meta{field}\dequals\meta{cs-name-2arg}} values, where +\meta{cs-name-2arg} is the name of a control sequence that takes two +arguments. The value is required for this key but +may be empty, which indicates an empty set (that is, the +setting is switched off). + +During the processing stage, each field identified in the +list (if defined) will have its value replaced with: +\begin{codeenv} +\cmd{\meta{cs-name-2arg}}\margm{value}\margm{label} +\end{codeenv} +where \meta{value} was its previous value and \meta{label} is the +entry's label (including prefix, if appropriate). An +empty list switches off encapsulation (the default). + +This action overrides any previous use of +\csopt{encapsulate-fields*} within the same \idx{resourceset}, and +is always performed after \csopt{encapsulate-fields}, regardless of +the order in the \idx{resourceset}['s] list of options, so if the +same field is listed in both settings, its value will end up as: +\begin{codeenv} +\cmd{\meta{cs-name-2arg}}\marg{\cmd{\meta{cs-name-1arg}}\margm{value}}\margm{label} +\end{codeenv} + +\optsection[\subsubsection]{interpret-fields} + +This option indicates that the listed fields should be replaced by +their interpreted values. The value is required for this key but +may be empty, which indicates an empty set of fields (that is, the +setting is switched off). Other fields not listed may still be +interpreted depending on other settings. As with the \field{sort} +field, any special characters are replaced with commands like +\ics{glsbackslash} and \ics{bibglsdollarchar}. This option is +applied after \csopt{field-case-change} (if set). + +For example, suppose I have a file \filefmt{entries.bib} that +contains definitions like: +\begin{codeenv} +\atentry{symbol}\marg{pi, + \field{name}=\marg{\cs{ensuremath}\marg{\ics{pi}}}, + \field{description}=\marg{the ratio of a circle's circumference to its diameter}, +} +\strut +\atentry{symbol}\marg{sigma, + \field{name} = \marg{\cs{ensuremath}\marg{\ics{sigma}}}, + \field{description} = \marg{standard deviation} +} +\end{codeenv} +Instead of having a list of terms (glossary), suppose I want to have +standalone definitions, where the term appears in a section heading. +I could define a command like this: +\begin{codeenv} +\cs{newcommand}\marg{\cmd{definition}}[1]\marg{\comment{} + \cs{ifglsentryexists}\marg{\idx{param}1}\comment{} + \marg{\comment{} + \cs{section}\oarg{\cs{glsentryname}\marg{\idx{param}}}\marg{\cs{glsadd}\marg{\idx{param}1}\ics{glsxtrglossentry}\marg{\idx{param}1}}\comment{} + \ics{Glossentrydesc}\marg{\idx{param}1}\cs{glspostdescription} + }\comment{} + \marg{\cs{section}\oarg{Missing `\idx{param}1'}\marg{\cs{glsadd}\marg{\idx{param}1}}}\comment{} +} +\end{codeenv} +which can be used in the document: +\begin{codeenv} +\ics{tableofcontents} +\cmd{definition}\marg{pi} +\cmd{definition}\marg{sigma} +\end{codeenv} +A problem with this definition of my custom command occurs if I add +\sty{hyperref} to the document, because this tries to write \cs{pi} +and \cs{sigma} to the PDF bookmarks, which doesn't work because +those commands can't be automatically converted to characters +permitted in a PDF string. This leads to a warning from +\sty{hyperref}: +\begin{alltt} +Token not allowed in a PDF string (Unicode) +\end{alltt} +Ideally I'd like to be able to convert these symbols to Unicode so +that they can appear in the bookmarks. Since \bibgls' interpreter +recognises these commands, I can get it to make the conversion +instead of trying to implement a method within \TeX: +\begin{codeenv} +\cs{glsaddstoragekey}\marg{pdfname}\marg{}\marg{\cmd{pdfname}} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src}, + \csopt[\field{name}=\fieldfmt{pdfname}]{replicate-fields}, + \csopt[fallback]{replicate-missing-field-action}, + \csopt[\fieldfmt{pdfname}]{interpret-fields} +} +\end{codeenv} +This first copies the \field{name} field to the custom +\fieldfmt{pdfname} and then interprets the copy. This leaves +the \field{name} field with the \LaTeX\ code to produce the symbol +in the document, but the \fieldfmt{pdfname} field ends up with all markup +stripped by the interpreter and the \cs{pi} and \cs{sigma} are +converted to the Unicode characters \hex{1D70B} (mathematical italic +small pi) and \hex{1D70E} (mathematical italic small sigma). With +\XeLaTeX\ or \LuaLaTeX\ these characters can be written to the PDF +bookmarks by adjusting the definition of the custom command: +\begin{codeenv} +\cs{newcommand}\marg{\cmd{definition}}[1]\marg{\comment{} + \cs{ifglsentryexists}\marg{\idx{param}1}\comment{} + \marg{\comment{} + \cs{section} + \oarg{\ics{texorpdfstring}\marg{\cs{glsentryname}\marg{\idx{param}1}}\marg{\cmd{pdfname}\marg{\idx{param}1}}} + \marg{\cs{glsadd}\marg{\idx{param}1}\cs{glsxtrglossentry}\marg{\idx{param}1}}\comment{} + \cs{Glossentrydesc}\marg{\idx{param}1}\cs{glspostdescription} + }\comment{} + \marg{\cs{section}\oarg{Missing `\idx{param}1'}\marg{\cs{glsadd}\marg{\idx{param}1}}}% +} +\end{codeenv} + +\optsection[\subsubsection]{date-time-fields} + +This option indicates that the listed fields all contain +date and time information. Primary entries will have these fields +parsed according to \csopt{date-time-field-format} and +\csopt{date-time-field-locale} and dual entries will have these +fields parsed according to \csopt{dual-date-time-field-format} and +\csopt{dual-date-time-field-locale}. If the field value is missing +or doesn't match the given pattern it remains unchanged, otherwise +it's converted into the form: +\formatdef{bibglsdatetime} +where \meta{original} is the value of the field before conversion. +If the interpreter is on, the value will be interpreted before +being parsed if it contains \idx{escchar}, \idx{mshiftchar}, +\idx{bgroupchar}, \idx{egroupchar} or \idx{nbspchar}. (Remember that +\idx{nbspchar} is converted to the non-breaking space character +\hex{A0} unless \longarg{break-space} is used.) + +\optsection[\subsubsection]{date-fields} + +As \csopt{date-time-fields} but for fields that only contain date +(not time) information. If parsed correctly, the field is converted +to: +\formatdef{bibglsdate} +The fields are parsed according to +\csopt{date-field-format} and +\csopt{date-field-locale} for primary entries and according to +\csopt{dual-date-field-format} and +\csopt{dual-date-field-locale} for dual entries. + +\optsection[\subsubsection]{time-fields} + +As \csopt{date-time-fields} but for fields that only contain time +(not date) information. If parsed correctly, the field is converted +to: +\formatdef{bibglstime} +The fields are parsed according to +\csopt{time-field-format} and +\csopt{time-field-locale} for primary entries and according to +\csopt{dual-time-field-format} and +\csopt{dual-time-field-locale} for dual entries. + +\optsection[\subsubsection]{date-time-field-format} + +This option also sets +\csopt[\meta{value}]{dual-date-time-field-format}. +The value is the format pattern used when parsing fields identified +by \csopt{date-time-fields}. The \meta{value} is as for +\csopt{date-sort-format}. + +\optsection[\subsubsection]{date-field-format} + +This option also sets +\csopt[\meta{value}]{dual-date-field-format}. +The value is the format pattern used when parsing fields identified +by \csopt{date-fields}. The \meta{value} is as for +\csopt{date-sort-format}. + +\optsection[\subsubsection]{time-field-format} + +This option also sets +\csopt[\meta{value}]{dual-time-field-format}. +The value is the format pattern used when parsing fields identified +by \csopt{time-fields}. The \meta{value} is as for +\csopt{date-sort-format}. + +\optsection[\subsubsection]{date-time-field-locale} + +This option also sets +\csopt[\meta{value}]{dual-date-time-field-locale}. +The value is the locale used when parsing fields identified +by \csopt{date-time-fields}. The \meta{value} is as for +\csopt{date-sort-locale}. + +\optsection[\subsubsection]{date-field-locale} + +This option also sets +\csopt[\meta{value}]{dual-date-field-locale}. +The value is the locale used when parsing fields identified +by \csopt{date-fields}. The \meta{value} is as for +\csopt{date-sort-locale}. + +\optsection[\subsubsection]{time-field-locale} + +This option also sets +\csopt[\meta{value}]{dual-time-field-locale}. +The value is the locale used when parsing fields identified +by \csopt{time-fields}. The \meta{value} is as for +\csopt{date-sort-locale}. + +\subsection{Case-Changing} +\label{sec:fieldcase} + +The \sty{glossaries-extra} package comes with the category +attributes \catattr{glossdesc} and \catattr{glossname}, which may +take the values \optfmt{firstuc} or \optfmt{title}. These don't +change the actual \field{name} or \field{description} fields, but +instead \ics{glossentryname} and \ics{glossentrydesc} (which are +used by the default glossary styles) check for the corresponding +attribute and apply the appropriate \idx{case-change} to the field value. + +So \ics{glossentryname} will use \ics{Glsentryname} if the +\catattr{glossname} attribute for the given entry is set to \optfmt{firstuc} +and \ics{glossentrydesc} will use \ics{Glsentrydesc} if the +\catattr{glossdesc} attribute is set to \optfmt{firstuc}. +The \optfmt{title} setting will instead use \ics{capitalisewords} +applied to the field value. + +The resource options described in this section provide an +alternative to those attributes that actually modify the relevant +field (rather than just adjusting the style code used to display it). +There are two forms of modification: the field is adjusted so that +the original value is encapsulated by a command or \bibgls\ will +perform the actual \idx{case-change} according to its own algorithm. +The results can vary according to the field content. + +Only a subset of known fields have a resource option that can be +used to apply a \idx{case-change}. For example, \csopt{name-case-change} +can be used to change the case of the \field{name} field, but +there's no equivalent option for the \field{text} field. + +Each of the case-changing resource options may take one of the +following values: +\begin{itemize} +\item \optfmt{none}: don't apply any case-changing (default); + +\item \optfmt{lc-cs}: make \bibgls\ behave as though the field +assignment: +\begin{codeenv} +\meta{field} = \margm{text} +\end{codeenv} +had actually been specified as: +\begin{codeenv*} +\meta{field} = \marg{\gls{bibglslowercase}\margm{text}} +\end{codeenv*} +which uses \TeX\ to convert the field to \idx{lowercase}; + +\item \optfmt{uc-cs}: make \bibgls\ behave as though the field +assignment: +\begin{codeenv} +\meta{field} = \margm{text} +\end{codeenv} +had actually been specified as: +\begin{codeenv*} +\meta{field} = \marg{\gls{bibglsuppercase}\margm{text}} +\end{codeenv*} +which uses \TeX\ to convert the field to \idx{uppercase}; + +\item \optfmt{firstuc-cs}: make \bibgls\ behave as though the field +assignment: +\begin{codeenv} +\meta{field} = \margm{text} +\end{codeenv} +had actually been specified as: +\begin{codeenv*} +\meta{field} = \marg{\gls{bibglsfirstuc}\margm{text}} +\end{codeenv*} +which uses \TeX\ to convert the field to first-letter \idx{uppercase}; + +\item \optfmt{title-cs}: make \bibgls\ behave as though the field +assignment: +\begin{codeenv} +\meta{field} = \margm{text} +\end{codeenv} +had actually been specified as: +\begin{codeenv*} +\meta{field} = \marg{\gls{bibglstitlecase}\margm{text}} +\end{codeenv*} +which uses \TeX\ to convert the field to \idx{titlecase}; + +\item \optfmt{lc}: convert to \idx{lowercase} by making the +appropriate modifications to tokens in the field value that have +a known \idx{lowercase} alternative (see below); + +\item \optfmt{uc}: convert to \idx{uppercase} by making the +appropriate modifications to tokens in the field value that have +a known \idx{uppercase} alternative (see below); + +\item \optfmt{firstuc}: convert to first letter \idx{uppercase} +by making the appropriate modification, if it has +a known \idx{uppercase} alternative (see below); + +\item \optfmt{title}: convert to \idx{titlecase} by making the +appropriate modifications to the first letter of each identified +word in the field value that has a known \idx{uppercase} +alternative (see below). + +A word-boundary is identified according to the +\csopt{word-boundaries} setting. Words to be excluded from the +case-changing (unless they occur at the start) can be identified +with \ics{MFUnocap} in the \atentry{preamble} or you can use +\code{\longarg{packages} mfirstuc-english} for the exclusion list +provided by the \isty{mfirstuc-english} package. Alternatively, you +can use \longarg{custom-packages} to load a simple package that +contains the required \cs{MFUnocap} commands (in a similar style to +\sty{mfirstuc-english}). + +The \bibgls\ word-boundary implementation is slightly different with +this setting than with the \cs{capitalisewords} command (implemented +in \TeX\ or by the \TeX\ parser library when interpreting field +values). Only words in the exclusion list that start with an +alphabetical character can be matched. Punctuation following a +word-boundary is not considered part of the next word. + +\end{itemize} +The \optfmt{firstuc-cs} and \optfmt{firstuc} options are essentially +a \idx{sentencecase} change, but there's no check for +sentence-breaks within the value, so even if the value contains +multiple sentences, only the first is changed. + +The \optfmt{\meta{option}-cs} settings defer the actual case-changing +to \TeX, which means that the case-changing has to be applied every +time the field is typeset (and it introduces non-expandable content +to the field value). Be aware of the limitations of using any of the +case-changing commands. See the \isty{textcase} and \isty{mfirstuc} +package documentation for further details~\cite{textcase,mfirstuc}. +You may use \code{\ics{NoCaseChange}\margm{content}} (provided by +\sty{textcase}) to prevent any \idx{case-change} to \meta{content}. + +For the settings where \bibgls\ itself performs the \idx{case-change}, then +\bibgls\ will iterate over each token of the field value and apply +the following rules: +\begin{enumerate} + +\item If the token is a normal Unicode alphabetic character, it will +be replaced with the corresponding upper or lower case character, as +appropriate. +For \optfmt{title} and \optfmt{firstuc}, the \idx{titlecase} character is +used as the replacement, for \optfmt{uc} the \idx{uppercase} character is +used as the replacement, and for \optfmt{lc} the \idx{lowercase} character +is used as the replacement. Many characters have the same upper and +title case alternative (for example, \qt{a} will be converted to \qt{A} +for the \optfmt{title}, \optfmt{firstuc} and \optfmt{uc} settings), but +some characters have different title and upper versions (for example, +the digraph \qt{\char"01F3} has the title version \qt{\char"01F2} +and \idx{uppercase} version \qt{\char"01F1}). + +If the option is \optfmt{firstuc} then all the remaining tokens are +skipped. If the option is \optfmt{title} then the subsequent tokens +are skipped until a word-boundary is found. + +\item If the token is a normal Unicode character that isn't alphabetical, +then this token will be skipped for all options. + +\item If \code{\idx{mshiftchar}\meta{maths}\idx{mshiftchar}} is +encountered, it will be skipped. If the option is \optfmt{firstuc} +then all remaining tokens are skipped, so no \idx{case-change} will be +performed. + +\item\label{case-change-group} If a group \code{\margm{content}} is +found, then the \idx{case-change} is applied to the entire \meta{content} +(which may be empty). This corresponds to the way \ics{makefirstuc} +and \ics{capitalisewords} work if a~word starts with a group. Note +that with \optfmt{firstuc} and \optfmt{title} the group content will +be converted according to \optfmt{uc}, so the normal \idx{uppercase} +character is used rather than the title case character (if they are +different). + +If the option is \optfmt{firstuc} then all the remaining tokens are +skipped. If the option is \optfmt{title} then the subsequent tokens +are skipped until a word-boundary is found. + +\item If a control sequence \csfmt{}\meta{csname} is found, then: + + \begin{enumerate} + \item If the control sequence is \cs{protect}, this token is skipped + for all options. + + \item If the control sequence is one of: \ics{o}, \ics{O}, \ics{l}, + \ics{L}, \ics{ae}, \ics{AE}, \ics{oe}, \ics{OE}, \ics{aa}, \ics{AA}, + \ics{ss}, \ics{SS}, \ics{ng}, \ics{NG}, \ics{th}, \ics{TH}, + \ics{dh}, \ics{DH}, \ics{dj} or \ics{DJ}, then + it's replaced with its \idx{case-change} counterpart (if not already the + correct case). + + If the option is \optfmt{firstuc} then all the remaining tokens are + skipped. If the option is \optfmt{title} then the subsequent tokens + are skipped until a word-boundary is found. + + \item If the control sequence is \ics{NoCaseChange} or is in the + \csopt{no-case-change-cs} list, then the + control sequence and its argument is ignored. With \optfmt{firstuc} + and \optfmt{title}, if \code{\ics{NoCaseChange}\margm{text}} + (but not any \csopt{no-case-change-cs} command) + occurs at the start of a word, then \bibgls\ will act as though + the word hasn't started yet (so the next token will be considered + for a \idx{case-change}). This is different to the way \ics{makefirstuc} + and \ics{capitalisewords} work. + + \item If the control sequence is \ics{ensuremath}, \ics{si} or if + \meta{csname} ends with \qtt{ref} (for example, \ics{ref} or + \ics{pageref}) then the control sequence and its argument is ignored. + In the case where \meta{csname} ends with \qtt{ref}, a following + star (\code{*}) or optional argument before the mandatory argument + will also be skipped. This allows for some common cross-referencing + commands, such as \sty{hyperref}['s] \ics{autoref}, which may have + a starred form, but does not allow for more complicated commands with + multiple arguments. + + If the option is \optfmt{firstuc} then all the remaining tokens are + skipped (so no \idx{case-change} will be performed). If the option is + \optfmt{title} then the subsequent tokens + are skipped until a word-boundary is found (so no \idx{case-change} is + performed for this word). + + \item If the control sequence is \ics{glsentrytitlecase} then: + \begin{description} + \item[\optfmt{lc}] the control sequence is converted to + \ics{glsxtrusefield}; + \item[\optfmt{uc}] the control sequence is converted to + \ics{GLSxtrusefield}; + \item[\optfmt{firstuc}] the control sequence is converted to + \ics{Glsxtrusefield} and the remaining tokens are skipped; + \item[\optfmt{title}] the control sequence is left unchanged + and subsequent tokens are skipped until a word-boundary is found. + \end{description} + The field and entry label arguments are skipped. + + \item If the control sequence is \ics{glshyperlink} then the + \idx{case-change} is applied to its optional argument. (If there was no + optional argument in the original field value, one will be inserted.) + The label argument is skipped. + + If the option is \optfmt{firstuc} then all the remaining tokens are + skipped. If the option is \optfmt{title} then the subsequent tokens + are skipped until a word-boundary is found. + + \item If the control sequence is \ics{glsdisp}, \ics{glslink}, + \ics{dglsdisp} or \ics{dglslink} then the \idx{case-change} will be + applied to the appropriate argument. The optional argument (if + present) and the label are skipped. + + If the option is \optfmt{firstuc} then all the remaining tokens are + skipped. If the option is \optfmt{title} then the subsequent tokens + are skipped until a word-boundary is found. + + \item If the control sequence has a known case variant, it will be + substituted. For example, \ics{gls} will be changed to \ics{Gls} + or \ics{GLS}. In some cases there isn't an appropriate variant. + For example, \ics{glsentrytext} has a first-letter upper case + version \ics{Glsentrytext}, but not an all-caps version. + + If the option is \optfmt{firstuc} then all the remaining tokens are + skipped. If the option is \optfmt{title} then the subsequent tokens + are skipped until a word-boundary is found. + + \item If the control sequence is followed by a group, then the + appropriate \idx{case-change} is applied to the group contents. + Unlike step~\ref{case-change-group}, the \idx{case-change} isn't + applied to the entire group content with \optfmt{firstuc} and + \optfmt{title}. (Again, this follows the way that + \ics{makefirstuc} and \ics{capitalisewords} work.) + + If there are subsequent groups, they won't be considered arguments, + but will be treated as groups, as per step~\ref{case-change-group}. + (This will only affect the \optfmt{title} setting as they will be + skipped by the \optfmt{firstuc} setting.) For complex cases, + consider using a semantic command that hides non-textual context + such as the \csfmt{strong} example described on page~\glsxtrpageref{strong}. + + \item Otherwise the control sequence is skipped. + \end{enumerate} + +\item Anything else is skipped. + +\end{enumerate} + +For example, if an entry is defined as: +\begin{codeenv} +\atentry{abbreviation}\marg{html, + \field{short} = \marg{HTML}, + \field{long} = \marg{hypertext markup language}, + \field{description}=\marg{a markup language for creating web pages} +} +\end{codeenv} +then: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[lc]{short-case-change}, + \csopt[title]{long-case-change}, + \csopt[firstuc]{description-case-change} +} +\end{codeenv} +will make the entry behave as if it had been defined as: +\begin{codeenv} +\atentry{abbreviation}\marg{html, + \field{short} = \marg{html}, + \field{long} = \marg{Hypertext Markup Language}, + \field{description}=\marg{A markup language for creating web pages} +} +\end{codeenv} +whereas: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[lc-cs]{short-case-change}, + \csopt[title-cs]{long-case-change}, + \csopt[firstuc-cs]{description-case-change} +} +\end{codeenv} +will make the entry behave as if it had been defined as: +\begin{codeenv} +\atentry{abbreviation}\marg{html, + \field{short} = \marg{\gls{bibglslowercase}\marg{HTML}}, + \field{long} = \marg{\gls{bibglstitlecase}\marg{hypertext markup language}}, + \field{description}=\marg{\gls{bibglsfirstuc}\marg{a markup language for creating web pages}} +} +\end{codeenv} +If the given field is missing, no change is made, except under +certain circumstances (see the relevant resource option for details). +For example, if an abbreviation is simply defined as: +\begin{codeenv} +\atentry{abbreviation}\marg{html, + \field{short} = \marg{html}, + \field{long} = \marg{hypertext markup language} +} +\end{codeenv} +then: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[uc]{name-case-change}, + \csopt[title]{description-case-change} +} +\end{codeenv} +won't have an effect. Although the default \abbrstyle{long-short} abbreviation +style sets the \field{name} and \field{description} fields, \bibgls\ doesn't +have access to this information. + +Remember that you can create missing fields by copying the value +from another field. So if the resource options are changed to: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[uc]{name-case-change}, + \csopt[title]{description-case-change}, + \csopt[\field{short}=\field{name},\field{long}=\field{description}]{replicate-fields} +} +\end{codeenv} +then \bibgls\ will act as though the entry had been defined as: +\begin{codeenv} +\atentry{abbreviation}\marg{html, + \field{short} = \marg{html}, + \field{long} = \marg{hypertext markup language}, + \field{name} = \marg{HTML}, + \field{description} = \marg{Hypertext Markup Language} +} +\end{codeenv} +If the \abbrstyle{long-short-sc} abbreviation style is set (before +\gls{GlsXtrLoadResources}) then this will override the default style +for the \field{name} and \field{description}, so +\code{\cs{gls}\marg{html}} will display the short form using +\code{\ics{textsc}\marg{html}} but the \field{name} in the glossary +will be displayed using just \code{HTML}. + +Note that with \atentry{index} the \field{name} and \field{text} +fields will automatically be created if they are missing and +\csopt{name-case-change} is used. For example, if an entry is +defined as: +\begin{codeenv} +\atentry{index}\marg{duck} +\end{codeenv} +then \csopt[firstuc]{name-case-change} will make this entry behave +as though it was defined as: +\begin{codeenv} +\atentry{index}\marg{duck, + \field{name} = \marg{Duck}, + \field{text} = \marg{duck} +} +\end{codeenv} + +Suppose I have a slightly eccentric abbreviation definition: +\begin{codeenv} +\atentry{abbreviation}\marg{html, + \field{short} = \qtdelim{ht\cs{emph}\marg{ml}}, + \field{long} = \qtdelim{hypertext markup language} +} +\end{codeenv} +then \csopt[uc]{short-case-change} would convert the value of the +\field{short} field into: +\begin{codeenv} +HT\cs{emph}{ML} +\end{codeenv} +Note that \csfmt{emph} isn't modified as it's recognised as a +command. There's a difference between a group that follows a control +sequence and one that doesn't. For example: +\begin{codeenv} +\atentry{abbreviation}\marg{html, + \field{short} = \qtdelim{\marg{ht}ml}, + \field{long} = \qtdelim{hypertext markup language} +} +\end{codeenv} +In this case \csopt[firstuc]{short-case-change} will convert the +\field{short} field value to: +\begin{codeenv} +\marg{HT}ml +\end{codeenv} +(The entire contents of the group \code{\marg{ht}} has been +converted.) Whereas with: +\begin{codeenv} +\atentry{abbreviation}\marg{html, + \field{short} = \qtdelim{\cs{emph}\marg{ht}ml}, + \field{long} = \qtdelim{hypertext markup language} +} +\end{codeenv} +then \csopt[firstuc]{short-case-change} will convert the +\field{short} field value to: +\begin{codeenv} +\cs{emph}\marg{Ht}ml +\end{codeenv} +(Only the first letter of the argument \code{\marg{ht}} has been +converted.) + +There's no attempt at interpreting the field contents at this point (but +the value may later be interpreted during sorting). +For example, suppose a \field{name} field is defined using: +\begin{codeenv} +\field{name} = \qtdelim{z\ics{ae}\ics{oe}}, +\end{codeenv} +then with \csopt[uc]{name-case-change}, the value would be converted to +\begin{codeenv} +Z\ics{AE}\ics{OE} +\end{codeenv} +because \cs{ae} and \cs{oe} have known \idx{uppercase} versions. + +With \csopt[uc-cs]{name-case-change}, the \field{name} +value would be converted to: +\begin{codeenv} +\gls{bibglsuppercase}\marg{z\cs{ae}\cs{oe}} +\end{codeenv} +If the interpreter is used during sorting, the sort value will be set to +\code{Z\AE\OE} because the interpreter recognises all three commands. + +You can use \code{\ics{NoCaseChange}\margm{text}} to prevent the given +\meta{text} from having the case changed. For example, if the \field{short} +field is defined as: +\begin{codeenv} +\field{short} = \marg{a\cs{NoCaseChange}\marg{bc}d} +\end{codeenv} +then with \csopt[uc]{short-case-change}, this would be converted to +\begin{codeenv} +A\cs{NoCaseChange}\marg{bc}D +\end{codeenv} + +Note that with \optfmt{firstuc} and \optfmt{title}, if +\code{\ics{NoCaseChange}\margm{text}} occurs at the start of a word +then it's skipped, and the case change is +applied to the material following its argument. For example, +suppose the \field{short} field is defined as: +\begin{codeenv} +\field{short}=\marg{\cs{NoCaseChange}\marg{h}tml} +\end{codeenv} +then the result is: +\begin{codeenv} +\cs{NoCaseChange}\marg{h}Tml +\end{codeenv} +whereas with: +\begin{codeenv} +\field{short}=\marg{\marg{}html} +\end{codeenv} +then the result is just \code{\marg{}html} (since the case change is +applied to the empty group, which has no effect). + +If you have a command that takes a label or identifier as an argument then it's +best to hide the label in a custom command. For example, if the +\field{short} field in the \ext{bib} definition is defined as: +\begin{codeenv} + \field{short} = \qtdelim{ht\ics{textcolor}\marg{red}\marg{ml}}, +\end{codeenv} +then with \csopt[uc]{short-case-change} this would end up as: +\begin{codeenv} +HT\cs{textcolor}\marg{RED}\marg{ML} +\end{codeenv} +which is incorrect. Instead, provide a command that hides the label +(such as the \csfmt{strong} example described on page~\glsxtrpageref{strong}). + +\optsection[\subsubsection]{no-case-change-cs} + +Instructs the non-\TeX\ case-changing options (where \bibgls, not +\TeX, performs the modification) to treat the commands whose control +sequence names are given in the comma-separated \meta{list} in the +same way as it treats \cs{ensuremath} etc. That is, the case-change +is omitted for the argument that follows any of those commands. + +For example, this manual defines some semantic commands such as +\csfmt{fieldfmt} (to format field names), \csfmt{abbrstylefmt} +(to format abbreviation style names) and \csfmt{glostylefmt} (to format +glossary style names). These occur in some of the section +and subsection headings in the \hyperref[sec:topics]{topic summary} +which are converted to \idx{titlecase} (see \csopt{field-case-change}). +These formatting commands shouldn't have their argument changed so they +are identified with: +\begin{codeenv} +\csopt[fieldfmt,abbrstylefmt,glostylefmt]{no-case-change-cs} +\end{codeenv} + +\optsection[\subsubsection]{word-boundaries} + +Governs how the \optfmt{title} \idx{case-change} option +determines word boundaries. The \meta{list} must contain one or +more of the following keywords: +\begin{description} +\item[\optfmt{white space}] any white space Unicode character +that is not a non-breakable space indicates a word-boundary; +\item[\optfmt{cs space}] the control sequences +\ics{space} or \ics{cs.space} indicate a word-boundary; +\item[\optfmt{dash}] a Unicode character that belongs to the +\idx{punctuationdash} block indicates a word-boundary; +\item[\optfmt{nbsp}] the \idx{nbspchar} active character or the Unicode +non-breakable characters \hex{00A0}, \hex{2007} and \hex{202F} +indicate a word-boundary. +\end{description} +Any keyword that is not listed indicates that particular setting is off. This +option is not cumulative. Any subsequent use of +\csopt{word-boundaries} within the same set of resource options will +override previous settings. + +The default setting is \csopt[white space,cs +space]{word-boundaries}, which excludes non-breakable +spaces and dashes. + +\optsection[\subsubsection]{short-case-change} + +Applies a case-change to the \field{short} field (if present). +This option may take one of the values described above. + +See \csopt{dual-short-case-change} to adjust the \field{dualshort} +field. + +\optsection[\subsubsection]{long-case-change} + +Applies a case-change to the \field{long} field (if present). +This option may take one of the values described above. + +See \csopt{dual-long-case-change} to adjust the \field{duallong} +field. + +\optsection[\subsubsection]{name-case-change} + +Applies a case-change to the \field{name} field. +This option may take one of the values described above. + +If the \field{text} field hasn't been set, the \field{name} +value is first copied to the \field{text} field. If the \field{name} +field hasn't been set (for example, with the \atentry{index} entry +type), it's copied from the fallback value (which +depends on the entry type) unless the entry type is +\atentry{abbreviation} or \atentry{acronym}, in which case if +the \field{name} field is missing no action is performed. + +\optsection[\subsubsection]{description-case-change} + +Applies a case-change to the \field{description} field (if present). +This option may take one of the values described above. + +\optsection[\subsubsection]{field-case-change} + +A general case-change instruction. The value should be a +comma-separated list of \code{\meta{field}\dequals\meta{setting}} for each +field that needs a case-change applied. The value is required for this key but +may be empty, which indicates this option is switched off. + +The \meta{setting} should be +the same as the permitted values for the above options. This +option is applied after all fields have been parsed but before +\csopt{interpret-fields}. If the +specified field is missing, the fallback for that field (if known) is copied +into the field. For example: +\begin{codeenv} +\csopt[\field{user1}=uc,\field{user2}={firstuc}]{field-case-change} +\end{codeenv} +This manual provides a custom storage key called +\fieldfmt{nametitle}: +\begin{codeenv} +\cs{glsxtrprovidestoragekey}\marg{\fieldfmt{nametitle}}\marg{}\marg{} +\end{codeenv} +The resource options copy the \field{name} value to this custom +field and convert \fieldfmt{nametitle} to \idx{titlecase}: +\begin{codeenv} +\csopt[\field{name}=\fieldfmt{nametitle}]{replicate-fields}, +\csopt[\fieldfmt{nametitle}=title]{field-case-change}, +\end{codeenv} +This means that the \hyperref[sec:topics]{topic summary} +(page~\pageref{sec:topics}) can fetch the value of +\fieldfmt{nametitle} instead of \field{name}, which provides an +expandable \idx{titlecase} form that's suitable for the PDF +bookmarks. + +This option isn't cumulative. If used multiple times in the same +\idx{resourceset}, the last instance will be the one used. If +the \keyvallist\ is missing, no general case-changing is applied +(the default). + +\section{Plurals} +\label{sec:plurals} + +Some languages, such as English, have a general rule that plurals +are formed from the singular with a suffix appended. This isn't +an absolute rule. There are plenty of exceptions (for example, +geese, children, churches, elves, fairies, sheep, mice), so a +simplistic approach of just doing \code{\ics{gls}\margm{label}[s]} +will sometimes produce inappropriate results, so the \styfmt{glossaries} +package provides a \field{plural} key with the corresponding command +\ics{glspl}. + +In some cases a plural may not make any sense (for example, if the +term is a verb or symbol), so the \field{plural} key is optional, but to +make life easier for languages where the majority of plurals can +simply be formed by appending a suffix to the singular, the +\styfmt{glossaries} package lets the \field{plural} field default +to the value of the \field{text} field with \ics{glspluralsuffix} +appended. This command is defined to be just the letter \qt{s}. +This means that the majority of terms in such languages don't need to have the +\field{plural} supplied as well, and you only need to use it for the +exceptions. + +For languages that don't have this general rule, the \field{plural} +field will always need to be supplied for nouns. + +There are other plural fields, such as \field{firstplural}, +\field{longplural} and \field{shortplural}. Again, if you are using +a language that doesn't have a simple suffix rule, you'll have to +supply the plural forms if you need them (and if a plural makes +sense in the context). + +If these fields are omitted, the \styfmt{glossaries} package follows +these rules: +\begin{itemize} +\item If \field{firstplural} is missing, then \ics{glspluralsuffix} +is appended to the \field{first} field, if that field has been +supplied. If the \field{first} field hasn't been supplied but the +\field{plural} field has been supplied, then the \field{firstplural} +field defaults to the \field{plural} field. If the \field{plural} +field hasn't been supplied, then both the \field{plural} and +\field{firstplural} fields default to the \field{text} field (or +\field{name}, if no \field{text} field) with \ics{glspluralsuffix} +appended. + +\item If the \field{longplural} field is missing, then +\ics{glspluralsuffix} is appended to the \field{long} field, if the +\field{long} field has been supplied. + +\item If the \field{shortplural} field is missing then, \emph{with +the base \styfmt{glossaries} acronym mechanism}, \ics{acrpluralsuffix} +is appended to the \field{short} field. + +\end{itemize} + +The last case is different with the \isty{glossaries-extra} extension +package. The \field{shortplural} field defaults to the \field{short} +field with \ics{abbrvpluralsuffix} appended \emph{unless overridden +by category attributes}. This suffix command is set by the +abbreviation styles. This means that every time an abbreviation +style is implemented, \ics{abbrvpluralsuffix} is redefined. Most +styles simply define this command as: +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{abbrvpluralsuffix}}\marg{\cs{glsxtrabbrvpluralsuffix}} +\end{codeenv} +where \ics{glsxtrabbrvpluralsuffix} expands to \ics{glspluralsuffix}. +The \qt{sc} styles (such as \abbrstyle{long-short-sc}) use a different +definition: +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{abbrvpluralsuffix}}\marg{\cs{protect}\ics{glsxtrscsuffix}} +\end{codeenv} +This allows the suffix to be reverted back to the upright font, +counteracting the affect of the small-caps font. + +This means that if you want to change or strip the suffix used for +the plural short form, it's usually not sufficient to redefine +\ics{abbrvpluralsuffix}, as the change will be undone the next time +the style is applied. Instead, for a document-wide solution, you +need to redefine \ics{glsxtrabbrvpluralsuffix}. Alternatively you can +use the category attributes. + +There are two attributes that affect the short plural suffix +formation. The first is \catattr{aposplural} which uses the suffix +\begin{codeenv*} +\idx{aposchar}\cs{abbrvpluralsuffix} +\end{codeenv*} +That is, an \idx{apostrophe} followed by \ics{abbrvpluralsuffix} is +appended. The second attribute is \catattr{noshortplural} which +suppresses the suffix and simply sets \field{shortplural} to the +same as \field{short}. + +With \bibgls, if you have some abbreviations where the plural should +have a suffix and some where the plural shouldn't have a suffix +(for example, the document has both English and French abbreviations) +then there are two approaches. + +The first approach is to use the category attributes. For example: +\begin{codeenv} +\cs{glssetcategoryattribute}\marg{french}\marg{\catattr{noshortplural}} +\end{codeenv} +Now just make sure all the French abbreviations are have their +\field{category} field set to \optfmt{french}: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[fr-abbrvs]{src},\csopt[french]{category}} +\end{codeenv} + +The other approach is to use the options listed below for the given +\idx{resourceset}. For example: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[fr-abbrvs]{src},\csopt[\empty]{short-plural-suffix}} +\end{codeenv} + +\optsection{short-plural-suffix} + +Sets the plural suffix for the default \field{shortplural} to +\meta{value}. The \meta{value} may be one of: +\begin{itemize} +\item \meta{suffix}: add the +\field{shortplural} field, if missing, with the given \meta{suffix}. +\item \meta{empty}: add the +\field{shortplural} field, if missing, with no suffix. +\item \optfmt{use-default}: leave +it to \styfmt{glossaries-extra} to determine the appropriate default. +\end{itemize} +The default setting is \csopt[use-default]{short-plural-suffix}. +If the \code{=\meta{value}} part is omitted, then +\csopt[\empty]{short-plural-suffix} is assumed. + +\optsection{dual-short-plural-suffix} + +Sets the plural suffix for the default \field{dualshortplural} field to +\meta{value}. As with \csopt{short-plural-suffix}, the default +setting is \csopt[use-default]{dual-short-plural-suffix}. If the +\meta{value} is omitted or empty, the suffix is set to empty. + +\section{Location List Options} +\label{sec:locationopts} + +The \styopt{record} package option automatically adds two new keys: +\field{loclist} and \field{location}. These two fields are set by +\bibgls\ from the information supplied in the \iext{aux} file (unless +the option \csopt[false]{save-locations} is used). The +\field{location} field contains the code to typeset the formatted +\idx{locationlist}. + +The \field{loclist} field has the syntax of an \isty{etoolbox} internal list +and includes every location (except for the discarded duplicates and +\idxpl{ignoredrecord}) with no range formations. Any explicit range markup +is stripped from the \glsopt{format} information to leave just the \idx{encap} +name, so you just get the start and end locations added as individual +elements but they are still encapsulated with the associated formatting +command. Each item in the list is provided in one of the following forms: +\begin{codeenv} +\ics{glsseeformat}\oargm{tag}\margm{label list}\marg{} +\end{codeenv} +for the cross-reference supplied by the \field{see} field, +\begin{codeenv} +\ics{glsxtruseseealsoformat}\margm{xr list} +\end{codeenv} +for the cross-reference supplied by the \field{seealso} field, +\nosecdef{glsnoidxdisplayloc} +for standard the internal locations, +\begin{codeenv} +\format{glsxtrdisplaysupploc} +\end{codeenv} +for supplemental (external) locations and +\begin{codeenv} +\format{glsxtrdisplaylocnameref} +\end{codeenv} +for \code{nameref} records. (See \sectionref{sec:supplementalopts} +for more information about supplemental locations and +\longarg{merge-nameref-on} for more information about \code{nameref} +records.) + +You can iterate through the \field{loclist} value +using one of \sty{etoolbox}'s internal list loops (either +by first fetching the list using \ics{glsfieldfetch} +or through \styfmt{glossaries-extra}'s \ics{glsxtrfielddolistloop} +or \ics{glsxtrfieldforlistloop} shortcuts). + +The \meta{format} is that supplied by the \glsopt{format} key +when using commands like \ics{gls} or \ics{glsadd} (the encapsulator or +\idx{encap} in \idx!{makeindex} parlance). If omitted, the default +\glsopt[glsnumberformat]{format} is assumed (unless this +default value is changed with \ics{GlsXtrSetDefaultNumberFormat}. +The value of the \glsopt{format} key must be the name of +a text-block command without the leading backslash that takes +a single argument (the location). The location +is encapsulated by that command. For example, +\begin{codeenv} +\cs{gls}\oarg{\glsopt[\encap{textbf}]{format}}\marg{sample} +\end{codeenv} +will display the corresponding location in bold, but note that this +will no longer have a hyperlink if you've used \sty{hyperref}. +If you want to retain the hyperlink you need the location +encapsulated with \cs{hyperbf} instead of \cs{textbf}: +\begin{codeenv} +\cs{gls}\oarg{\glsopt[\encap{hyperbf}]{format}}\marg{sample} +\end{codeenv} +The \csfmt{hyper}\meta{xx} set of commands all internally use +\cs{glshypernumber} which adds the appropriate hyperlink to the +location. See Table~6.1 in the \styfmt{glossaries}~\cite{glossaries} +user manual for a list of all the \csfmt{hyper}\meta{xx} commands. + +Ranges can be explicitly formed using the parenthetical +syntax \glsopt[\idx{openrange}]{format} and +\glsopt[\idx{openrange}]{format} or \glsopt[\idx{openrange}\meta{csname}]{format} and +\glsopt[\idx{closerange}\meta{csname}]{format} (where \meta{csname} is again the name of +a text-block command without the initial backslash) in the optional +argument of commands like \ics{gls} or \ics{glsadd}. These will always +form a range, regardless of \csopt{min-loc-range}, and will be +encapsulated by \gls!{bibglsrange}. (This command is not used with +ranges that are formed by collating consecutive locations.) The +initial marker is stripped from the \meta{format} argument of the +location formatting commands, such as \gls{glsnoidxdisplayloc}, to +allow for easy conversion to the corresponding text-block command. + +Explicit ranges don't merge with neighbouring locations, but will +absorb any single locations within the range that don't conflict. +(Conflicts will be moved to the start of the explicit range.) +For example, if \code{\cs{gls}\marg{sample}} is used on page~1, +\code{\cs{gls}\oarg{\glsopt[\idx{openrange}]{format}}\marg{sample}} is used on page~2, +\code{\cs{gls}\marg{sample}} is used on page~3, and +\code{\cs{gls}\oarg{\glsopt[\idx{closerange}]{format}}\marg{sample}} is used on page~4, then the location +list will be 1, 2--4. The entry on page~3 is absorbed into the +explicit range, but the range can't be expanded to include page~1. +If the entry on page~3 had a different format to the explicit range, +for example \code{\cs{gls}\oarg{\glsopt[\encap{textbf}]{format}}\marg{sample}} +then it would cause a warning and be moved before the start of the +range so that the location list would then be 1, \textbf{3}, 2--4. + +An \idx{ignoredrecord} identifies a term that needs to be treated as +though it has a record for selection purposes, but the record +should not be included in the location list. +The special format \glsaddopt[\encap{glsignore}]{format} is provided +by the \styfmt{glossaries} package for cases where the location +should be ignored. (The command \ics{glsignore} simply ignores its +argument.) This works reasonably well if an entry only has the one +location, but if the entry happens to be indexed again, it can lead +to an odd empty gap in the location list with a spurious comma. If +\bibgls\ encounters a record with this special format, the entry +will be selected but the record will be discarded. + +This means that the location list will be empty if the entry was +only indexed with the special ignored format, but if the entry was also +indexed with another format then the location list won't include the +\idxpl{ignoredrecord}. (This format is used by \ics{glsaddallunused} but +remember that iterative commands like this don't work with \bibgls. +Instead, just use \csopt[all]{selection} to select all entries. +Those that don't have records won't have a location list.) + +For example, suppose you only want main matter locations in the +number list, but you want entries that only appear in the back matter +to still appear in the glossary (without a location list), then you could do: +\begin{codeenv} +\ics{backmatter} +\ics{GlsXtrSetDefaultNumberFormat}\marg{\encap{glsignore}} +\end{codeenv} +If you also want to drop front matter locations as well: +\begin{codeenv} +\ics{frontmatter} +\cs{GlsXtrSetDefaultNumberFormat}\marg{\encap{glsignore}} +\ldots +\ics{mainmatter} +\cs{GlsXtrSetDefaultNumberFormat}\marg{\encap{glsnumberformat}} +\ldots +\cs{backmatter} +\cs{GlsXtrSetDefaultNumberFormat}\marg{\encap{glsignore}} +\end{codeenv} + +Note that explicit range formations aren't discarded, so if +\encap{glsignore} is used in a range, such as: +\begin{codeenv} +\ics{glsadd}\oarg{\glsopt[\idx{openrange}\encap{glsignore}]{format}}\marg{sample} +\ldots +\cs{glsadd}\oarg{\glsopt[\idx{closerange}\encap{glsignore}]{format}}\marg{sample} +\end{codeenv} +then the range will be included in the location list (encapsulated +with \ics{glsignore}), but this case would be a rather odd use of +this special format and is not recommended. + +The record counting commands, such as \gls{rgls}, use the special +format \encap{glstriggerrecordformat}, which \bibgls\ also treats +as an \idx{ignoredrecord} and the same rules as for \encap{glsignore} apply. + +The locations are always listed in the order in which they were indexed, +(except for the cross-reference which may be placed at the start or +end of the list or omitted). +This is different to \idx!{xindy} and \idx!{makeindex} where you can +specify the ordering (such as \idx!{lowercase} Roman first, then digits, +etc), but unlike those applications, \bibgls\ allows any location, +although it may not be able to work out an integer representation. +(With \idx!{xindy}, you can define new location formats, but you need +to remember to add the appropriate code to the custom module.) + +It's possible to define a custom glossary style where +\ics{glossentry} (and the child form \ics{subglossentry}) ignore the +final argument (which will be the \field{location} field) +and instead parse the \field{loclist} field and re-order the +locations or process them in some other way. Remember that you can +also use \ics{glsnoidxloclist} +provided by \styfmt{glossaries}. For example: +\begin{codeenv} +\cs{glsfieldfetch}\marg{gls.sample}\marg{loclist}\marg{\cmd{loclist}}\comment{fetch location list} +\cs{glsnoidxloclist}\marg{\cmd{loclist}}\comment{iterate over locations} +\end{codeenv} +This uses \ics{glsnoidxloclisthandler} as the list's \idx{handler} +macro, which simply displays each location separated by \ics{delimN}. +(See also +\href{http://www.dickimaw-books.com/latex/admin/html/foreachtips.shtml}{Iteration +Tips and Tricks}~\cite{iterationtips}.) + +Each regular location is listed in the \iext{aux} file in the form: +\nosecdef{glsxtr@record} +(See \longarg{merge-nameref-on} for \code{nameref} records.) +Exact duplicates are discarded. For example, if \code{cat} +is indexed twice on page 1: +\begin{codeenv} +\gls{glsxtr@record}\marg{cat}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1} +\gls{glsxtr@record}\marg{cat}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1} +\end{codeenv} +then the second record is discarded. Only the first record is added +to the location list. + +Partial duplicates, where all arguments match except for +\meta{format}, may be discarded depending on the value +of \meta{format}. For example, if page~1 of the document +uses \code{\cs{gls}\marg{cat}} and +\code{\cs{gls}\oarg{\glsopt[\encap{hyperbf}]{format}}\marg{cat}} +then the \ext{aux} file will contain: +\begin{codeenv} +\gls{glsxtr@record}\marg{cat}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1} +\gls{glsxtr@record}\marg{cat}\marg{}\marg{\counter{page}}\marg{\encap{hyperbf}}\marg{1} +\end{codeenv} +This is a partial record match. In this case, \bibgls\ +makes the following tests: +\begin{itemize} +\item If one of the formats includes a range formation, the +range takes precedence. + +\item If one of the formats is \encap{glsnumberformat} (as in the +above example) or an \idx{ignoredrecord} format such as +\encap{glsignore}, that format will be skipped. So in the above +example, the second record will be added to the location list, but +not the first. (A message will only be written to the transcript if +the \longarg{debug} switch is used.) The default +\encap{glsnumberformat} will take precedence over the +\idx{ignoredrecord} formats (\encap{glsignore} and +\encap{glstriggerrecordformat}). + +\item If a mapping has been set with the \longarg{map-format} +switch that mapping will be checked. +\item Otherwise the duplicate record will be discarded with a +warning. +\end{itemize} + +The \field{location} field is used to store the formatted location +list. The code for this list is generated by \bibgls\ based on the +information provided in the \iext{aux} file, the presence of the +\field{see} or \field{seealso} field and the various settings described in this +chapter. When you display the glossary using \ics{printunsrtglossary}, +if the \field{location} field is present it will be displayed +according to the glossary style (and other factors, such as whether the +\styopt{nonumberlist} option has been used, either as a package +option or supplied in the optional argument of \ics{printunsrtglossary}). +For more information on adjusting the formatting see the +\styfmt{glossaries}~\cite{glossaries} and +\styfmt{glossaries-extra}~\cite{glossaries-extra} user manuals. + +\optsection{save-locations} + +By default, the locations will be processed and stored in the +\field{location} and \field{loclist} fields. However, if you don't +want the location lists (for example, you are using the +\styopt{nonumberlist} option or you are using \idx{xindy} with a +custom location rule), then there's no need for \bibgls\ to process +the locations. To switch this function off, just use +\csopt[false]{save-locations}. Note that with this setting, if +you're not additionally using \idx!{makeindex} or \idx!{xindy}, then +the locations won't be available even if you don't have the +\styopt{nonumberlist} option set. + +\optsection{save-loclist} + +If you want the \field{location} field but don't need +\field{loclist}, you can use \csopt[false]{save-loclist}. +This can help to save resources and build time. + +\optsection{save-primary-locations} + +It's sometimes useful to identify primary locations with a different +format, such as bold or italic. This helps the reader select which +location to try first in the event of a long location list. However, +you may prefer to store the primary location in a different field to +give it a more prominent position. In order to do this you +need to specify the format (or formats) used to identify primary +locations with \csopt{primary-location-formats} and +use \csopt{save-primary-locations} to determine how to deal with +these locations. + +This option may take one of the following values: +\begin{itemize} +\item \optfmt{false}: don't save primary locations (default); +\item \optfmt{retain}: save primary locations in the +\field{primarylocations} field but don't remove from the usual +\idx{locationlist}; +\item \optfmt{default format}: similar to \optfmt{retain} but the +format for the primary records in the \field{location} field is +converted to the default \encap{glsnumberformat} \idx{encap} (the records in the +\field{primarylocations} field retain their given format); +\item \optfmt{start}: save primary locations in the +\field{primarylocations} field and also move to the start of the +usual \idx{locationlist}; +\item \optfmt{remove}: save primary locations in the +\field{primarylocations} field and remove from the usual +\idx{locationlist}. +\end{itemize} + +The primary locations are copied to the \field{primarylocations} +field and encapsulated with \gls!{bibglsprimary}. +If you use \csopt[remove]{save-primary-locations}, the +\field{location} field will end up empty if the locations for the +associated entry were all identified as primary. If you use +\csopt[start]{save-primary-locations}, all primary locations will be +moved to the start of the \idx{locationlist} stored in the +\field{location} field, but there will be no additional markup +(other than the given format) to identify them. If you need +additional markup, then use \csopt[remove]{save-primary-locations} +and adjust the \idx{locationlist} format to insert the primary +locations at the start. This can be done by modifying the glossary +style. + +For example, the \glostyle{bookindex} style inserts +\ics{glsxtrbookindexprelocation} before the location, so you could +redefine this: +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{glsxtrbookindexprelocation}}[1]\marg{\comment{} + \cs{glsxtrifhasfield}\marg{primarylocations}\marg{\idx{param}1}\comment{} + \marg{\comment{} + \ics{glsxtrprelocation} + \cs{glscurrentfieldvalue} + \cs{glsxtrifhasfield}\marg{location}\marg{\idx{param}1}\marg{;}\marg{}\comment{} + }\comment{} + \marg{}\comment{} + \cs{glsxtrprelocation} +} +\end{codeenv} +(Note that if \csopt{loc-prefix} is used, the prefix will be +in the \field{location} field and so will come after the primary +locations in the above example. Similarly for cross-references +unless they've been omitted.) + +You can switch from using the \field{location} field to the +\field{primarylocations} field by locally changing +\ics{GlsXtrLocationField}: +\begin{codeenv} +\cs{printunsrtglossary*}\marg{\comment{} + \cs{renewcommand}\marg{\cs{GlsXtrLocationField}}\marg{primarylocations}\comment{} +} +\end{codeenv} +Remember that the \idx{handler} used by \cs{printunsrtglossary} will +fallback on the \field{loclist} field if the field identified +by \cs{GlsXtrLocationField} is missing or empty. You may want to +consider using \csopt[false]{save-loclist} to prevent this. + +\optsection{primary-location-formats} + +This option will automatically set +\csopt[retain]{save-primary-locations} unless it has already been +changed from the default \csopt[false]{save-primary-locations} +setting. The argument should be a comma-separated list of +formats. If a record's format is contained in this list then it will +be considered a primary location and it will be included in the +associated entry's \field{primarylocations} field. + +For example, suppose the file \filefmt{entries.bib} contains: +\begin{codeenv} +\atentry{entry}\marg{bird, + \field{name}=\marg{bird}, + \field{description}=\marg{feathered animal} +} +\atentry{entry}\marg{waterfowl, + \field{name}=\marg{waterfowl}, + \field{description}=\marg{any bird that lives in or about water} +} +\atentry{entry}\marg{zebra, + \field{name}=\marg{zebra}, + \field{description}=\marg{striped African horse} +} +\atentry{entry}\marg{parrot, + \field{name}=\marg{parrot}, + \field{description}=\marg{mainly tropical bird with bright plumage} +} +\end{codeenv} +and the document \filefmt{test.tex} contains: +\begin{codeenv} +\cmd{documentclass}\marg{report} +\strut +\cmd{usepackage}\oarg{colorlinks}\marg{hyperref} +\cmd{usepackage}\oarg{\styopt{record}, + \styopt[dot]{postpunc}, + \styopt{nostyles}, + \styopt[tree,bookindex]{stylemods}, + \styopt[bookindex]{style}}\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src}, + \csopt[hyperbf,hyperemph]{primary-location-formats}, + \csopt[remove]{save-primary-locations} +} +\strut +\cmd{renewcommand}*\marg{\cs{glsxtrbookindexprelocation}}[1]\marg{\comment{} + \cs{glsxtrifhasfield}\marg{\field{primarylocations}}\marg{\idx{param}1}\comment{} + \marg{\comment{} + \ics{glsxtrprelocation} + \cs{glscurrentfieldvalue} + \cs{glsxtrifhasfield}\marg{\field{location}}\marg{\idx{param}1}\marg{;}\marg{}\comment{} + }\comment{} + \marg{}\comment{} + \cs{glsxtrprelocation} +} +\strut +\gls{glsxtrnewglslike}\oarg{\glsopt[\encap{hyperbf}]{format}}\marg{}\marg{\cmd{primary}}\marg{\cmd{primarypl}}\marg{\cmd{Primary}}\marg{\cmd{Primarypl}} +\strut +\cmd{begin}\marg{document} +\cmd{chapter}\marg{Sample} +\cmd{Primary}\marg{waterfowl}, \cs{gls}\marg{bird} and \cs{gls}\marg{zebra}. +\strut +\cmd{chapter}\marg{Another Sample} +\cs{Gls}\marg{waterfowl}, \cmd{primary}\marg{bird} and \cs{gls}\marg{zebra}. +\strut +\cmd{chapter}\marg{Yet Another Sample} +\cs{Gls}\marg{waterfowl}, \cs{gls}\marg{bird} and \cmd{primary}\marg{zebra}. +\strut +\cmd{chapter}\marg{Yet Another Sample Again} +\cs{Gls}\marg{waterfowl}, \cs{gls}\marg{bird}, \cmd{primarypl}\marg{parrot} and \cs{gls}\marg{zebra}. +\strut +\ics{printunsrtglossary*}\oarg{\printglossopt[\iglostyle{tree}]{style},\printglossopt{nonumberlist}}\marg{\comment{} + \cmd{renewcommand}*\marg{\ics{glsextrapostnamehook}}[1]\marg{\ics{glsadd}\oarg{\glsopt[\encap{hyperemph}]{format}}\marg{\idx{param}1}}\comment{} +} +\strut +\cs{printunsrtglossary}\oarg{\printglossopt[Index]{title},\printglossopt[false]{target}} +\cmd{end}\marg{document} +\end{codeenv} + +The \csopt[\encap{hyperbf},\encap{hyperemph}]{primary-location-formats} setting +in the above indicates that locations encapsulated with \ics{hyperbf} and +\ics{hyperemph} are primary records. In this case, the bold format is used to +indicate the primary location in the main document text and the emphasized +format is used to indicate the location in the main glossary. + +The primary records are removed from the \field{location} field +due to the \csopt[remove]{save-primary-locations} setting. This can +lead to a ragged location list. The option +\csopt[default format]{save-primary-locations} can allow the primary +location to be absorbed into a range. + +The main glossary records are added through the category-independent post-name +hook with \cs{glsadd}. This won't be implemented until the entries are actually +defined as the page number can't be determined until the glossary can be +displayed. This means that the document build requires an extra \bibgls\ and +\LaTeX\ run: +\begin{verbatim} +pdflatex test +bib2gls --group test +pdflatex test +bib2gls --group test +pdflatex test +\end{verbatim} + +For consistency, I've used \gls{glsxtrnewglslike} to provide commands +used to indicate a primary reference in the text. This means that if +I decide to change the optional arguments used for primary +references I only need to edit one line. For example, I might want to +change the default counter: +\begin{codeenv} +\gls{glsxtrnewglslike}\oarg{\glsopt[\encap{hyperbf}]{format},\glsopt[\counter{chapter}]{counter}}\marg{}\marg{\cmd{primary}}\marg{\cmd{primarypl}}\marg{\cmd{Primary}}\marg{\cmd{Primarypl}} +\end{codeenv} + +Here's another example that only has one primary format (\encap{hyperrm}) +that's indexed through the use of \ics{GlsXtrAutoAddOnFormat}, which sets +up a hook that automatically inserts: +\begin{codeenv*} +\ics{glsadd}\oarg{\glsaddopt[\counter{chapter}]{counter},\glsaddopt[\encap{hyperrm}]{format}}\margm{label} +\end{codeenv*} +on each instance of \code{\cs{gls}\oarg{\glsopt[primaryfmt]{format}}\margm{label}} (or +similar). This means that the entry is indexed twice when this particular +format is used: first with the \encap{hyperrm} format and \counter{chapter} +counter (from the \cs{glsadd} command in the hook), and then with the +\code{primaryfmt} format and the default counter (as per normal behaviour): +\begin{codeenv} +\cmd{documentclass}\marg{report} +\strut +\cmd{usepackage}\oarg{colorlinks}\marg{hyperref} +\cmd{usepackage}\oarg{ + \styopt[nameref]{record}, + \styopt[dot]{postpunc}, + \styopt{nostyles}, + \styopt[tree,bookindex]{stylemods}, + \styopt[bookindex]{style}}\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[topics]{src}, + \csopt[hyperrm]{primary-location-formats}, + \csopt[remove]{save-primary-locations}, + \csopt[false]{save-loclist} +} +\strut +\cmd{newcommand}\marg{\cmd{primaryfmt}}\oarg{1}\marg{\cs{hyperbf}\marg{\idx{param}1}} +\strut +\ics{GlsXtrAutoAddOnFormat}\marg{primaryfmt}\marg{\glsaddopt[\counter{chapter}]{counter},\glsaddopt[\encap{hyperrm}]{format}} +\strut +\gls{glsxtrnewglslike}\oarg{\glsaddopt[primaryfmt]{format}}\marg{}\marg{\cmd{primary}}\marg{\cmd{primarypl}}\marg{\cmd{Primary}}\marg{\cmd{Primarypl}} +\strut +\cmd{begin}\marg{document} +\cmd{chapter}\marg{Sample} +\cmd{Primary}\marg{waterfowl}, \cs{gls}\marg{bird} and \cs{gls}\marg{zebra}. +\strut +\cmd{chapter}\marg{Another Sample} +\cs{Gls}\marg{waterfowl}, \cmd{primary}\marg{bird} and \cs{gls}\marg{zebra}. +\strut +\cmd{chapter}\marg{Yet Another Sample} +\cs{Gls}\marg{waterfowl}, \cs{gls}\marg{bird} and \cmd{primary}\marg{zebra}. +\strut +\cmd{chapter}\marg{Yet Another Sample Again} +\cs{Gls}\marg{waterfowl}, \cs{gls}\marg{bird}, \cmd{primarypl}\marg{parrot} and \cs{gls}\marg{zebra}. +\strut +\ics{printunsrtglossary*}\oarg{\printglossopt[\glostyle{tree}]{style},\printglossopt[Summary]{title}}\marg{\comment{} + \cmd{renewcommand}*\marg{\ics{glsextrapostnamehook}}[1]\marg{\ics{glsadd}\oarg{\glsaddopt[\encap{hyperemph}]{format}}\marg{\idx{param}1}}\comment{} + \cmd{renewcommand}\marg{\ics{GlsXtrLocationField}}\marg{\field{primarylocations}}\comment{} +} +\strut +\cs{printunsrtglossary}\oarg{\printglossopt[Index]{title},\printglossopt[false]{target}} +\cmd{end}\marg{document} +\end{codeenv} + +Note that in this case, from \bibgls' point of view, the primary format is +\encap{hyperrm} not \code{primaryfmt}. This picks out the records created with +the automated \ics{glsadd}, which have the counter set to \counter{chapter}. +The first glossary (with the title \qt{Summary}) switches the location field to +\field{primarylocations} so that only the primary records are listed. Since +\styopt[nameref]{record} has been used this means that the chapter title is +shown rather than the chapter number. + +The second glossary (\qt{Index}) shows the location lists that only +have the \counter{page} counter (because the automated \cs{glsadd} +records with the \counter{chapter} counter have been removed because +they were identified as primary records). These just show the page +number as that's the default display with \styopt[nameref]{record} +for records with the \counter{page} counter. + +An alternative to \ics{GlsXtrAutoAddOnFormat} would be to simply +define the custom commands as follows: +\begin{codeenv} +\cmd{newcommand}\marg{\cmd{primary}}[2][]\marg{\comment{} + \cs{glsadd}\oarg{\glsaddopt[\counter{chapter}]{counter},\glsaddopt[\encap{hyperrm}]{format}}\marg{\idx{param}2}\comment{} + \cs{gls}\oarg{\glsopt[primaryfmt]{format},\idx{param}1}\marg{\idx{param}2}\comment{} +} +\cmd{newcommand}\marg{\cmd{primarypl}}[2][]\marg{\comment{} + \cs{glsadd}\oarg{\glsaddopt[\counter{chapter}]{counter},\glsaddopt[\encap{hyperrm}]{format}}\marg{\idx{param}2}\comment{} + \cs{glspl}\oarg{\glsopt[primaryfmt]{format},\idx{param}1}\marg{\idx{param}2}\comment{} +} +\cmd{newcommand}\marg{\cmd{Primary}}[2][]\marg{\comment{} + \cs{glsadd}\oarg{\glsaddopt[\counter{chapter}]{counter},\glsaddopt[\encap{hyperrm}]{format}}\marg{\idx{param}2}\comment{} + \cs{Gls}\oarg{\glsopt[primaryfmt]{format},\idx{param}1}\marg{\idx{param}2}\comment{} +} +\cmd{newcommand}\marg{\cmd{Primarypl}}[2][]\marg{\comment{} + \cs{glsadd}\oarg{\glsaddopt[\counter{chapter}]{counter},\glsaddopt[\encap{hyperrm}]{format}}\marg{\idx{param}2}\comment{} + \cs{Glspl}\oarg{\glsopt[primaryfmt]{format},\idx{param}1}\marg{\idx{param}2}\comment{} +} +\end{codeenv} +This is more useful if you want to simply omit the +\code{\glsopt[primaryfmt]{format}} option (just remove it from the above four +definitions), which makes it easier to merge the locations into +ranges in the index. + +\optsection{min-loc-range} + +By default, three or more consecutive locations \meta{loc-1}, +\meta{loc-2}, \ldots, \meta{loc-n} are compressed into +the range \code{\meta{loc-1}\ics{delimR} \meta{loc-n}}. Otherwise +the locations are separated by \gls!{bibglsdelimN} or \gls!{bibglslastDelimN}. +As mentioned above, these aren't merged with explicit range formations. + +You can change this with the \csopt{min-loc-range} setting where +\meta{value} is either \optfmt{none} (don't form ranges) or an +integer greater than one indicating how many consecutive locations should be +converted into a range. + +\bibgls\ determines if one location +\code{\margm{prefix-2}\margm{counter-2}\margm{format-2}\margm{location-2}} +is one unit more than another location +\code{\margm{prefix-1}\margm{counter-1}\margm{format-1}\margm{location-1} } +according to the following: +\begin{enumerate} +\item\label{itm:pre} If \meta{prefix-1} is not equal to \meta{prefix-2} or +\meta{counter-1} is not equal to \meta{counter-2} or \meta{format-1} +is not equal to \meta{format-2}, then the locations aren't +considered consecutive. +\item\label{itm:emptyloc} If either \meta{location-1} or \meta{location-2} are empty, +then the locations aren't considered consecutive. +\item\label{itm.csmatch} If both \meta{location-1} and \meta{location-2} match the +pattern (line break for clarity only)\footnote{The Java class \code{\csfmt{p}\marg{javaDigit}} +used in the \idx{regex} will match any digits in the +Unicode \idx{numberdecimaldigit} category not just the digits in the Basic Latin set. Similarly \code{\csfmt{p}\marg{javaAlphabetic}} will also match alphabetic +characters outside the Basic Latin set.} +\begin{verbatim} +(.*?)(?:\\protect\s*)?(\\[\p{javaAlphabetic}@]+)\s*\{([\p{javaDigit} +\p{javaAlphabetic}]+)\} +\end{verbatim} +then: + \begin{itemize} + \item if the control sequence matched by group 2 isn't the same for + both locations, the locations aren't considered consecutive; + \item if the argument of the control sequence (group 3) is the same for + both locations, then the test is retried with \meta{location-1} +set to group 1 of the first pattern match and \meta{location-2} +set to group 1 of the second pattern match; + \item otherwise the test is retried with \meta{location-1} set to +group 3 of the first pattern match and \meta{location-2} set to +group 3 of the second pattern match. + \end{itemize} +\item\label{itm:decmatch} If both \meta{location-1} and \meta{location-2} match the +pattern +\begin{verbatim} +(.*?)([^\p{javaDigit}]?)(\p{javaDigit}+) +\end{verbatim} +then: + \begin{enumerate} + \item\label{itm:decgrp3eq} if group 3 of both pattern matches are +equal then: + \begin{enumerate} + \item\label{itm:decgrp3nz} if group 3 isn't zero, the locations +aren't considered consecutive; + \item if the separators (group 2) are different the test is +retried with \meta{location-1} set to the concatenation of the first +two groups \meta{group-1}\meta{group-2} of the first pattern match +and \meta{location-2} set to the concatenation of the first two groups +\meta{group-1}\meta{group-2} of the second pattern +match; + \item\label{itm:decgrp3eqsepeq} if the separators (group 2) are the same the test is +retried with \meta{location-1} set to the first +group \meta{group-1} of the first pattern match +and \meta{location-2} set to the first group +\meta{group-1} of the second pattern match. + \end{enumerate} + \item If \meta{group-1} of the first pattern match (of +\meta{location-1}) doesn't equal +\meta{group-1} of the second pattern match (of \meta{location-2}) +or \meta{group-2} of the first pattern match (of +\meta{location-1}) doesn't equal +\meta{group-2} of the second pattern match (of \meta{location-2}) +then the locations aren't considered consecutive; + \item\label{itm:decgrp3} If $0 < l_2 - l_1 \leq d $ +where $l_2$ is \meta{group 3} of the second pattern match, +$l_1$ is \meta{group 3} of the first pattern match and +$d$ is the value of \optfmt{max-loc-diff} then the locations +are consecutive otherwise they're not consecutive. + \end{enumerate} +\item\label{itm:rommatch} The next pattern matches for \meta{prefix}\meta{sep}\meta{n} +where \meta{n} is a \idx!{lowercase} Roman numeral, which is converted to +a decimal value and the test is performed in the same way as the +above \hyperref[itm:decmatch]{decimal test}. +\item\label{itm:Rommatch} The next pattern matches for \meta{prefix}\meta{sep}\meta{n} +where \meta{n} is an \idx!{uppercase} Roman numeral, which is converted to +a decimal value and the test is performed +in the same way as the above \hyperref[itm:decmatch]{decimal test}. +\item\label{itm:alphmatch} The next pattern matches for \meta{prefix}\meta{sep}\meta{c} +where \meta{c} is either a \idx!{lowercase} letter from \code{a} to +\code{z} or an \idx!{uppercase} letter from \code{A} to \code{Z}. +The character is converted to its code point and the test is +performed in the same way as the \hyperref[itm:decmatch]{decimal pattern} above. +\item\label{itm:nomatch} If none of the above, the locations aren't considered +consecutive. +\end{enumerate} + +Examples: +\begin{enumerate} +\item +\begin{codeenv} +\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1} +\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{2} +\end{codeenv} +These records are consecutive. The prefix, counter and format are +identical (so the test passes step~\ref{itm:pre}), the locations match +the \hyperref[itm:decmatch]{decimal pattern} and the test in +step~\ref{itm:decgrp3} passes. + +\item +\begin{codeenv} +\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1} +\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{textbf}}\marg{2} +\end{codeenv} +These records aren't consecutive since the formats are different. + +\item +\begin{codeenv} +\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{A.i} +\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{A.ii} +\end{codeenv} +These records are consecutive. The prefix, counter and format are +identical (so it passes step~\ref{itm:pre}). The locations match +the \hyperref[itm:rommatch]{lower case Roman numeral pattern}, where +\code{A} is considered a prefix and the dot is consider a +separator. The Roman numerals i and ii are converted to decimal and +the test is retried with the locations set to 1 and 2, respectively. +This now passes the decimal pattern test (step~\ref{itm:decgrp3}). + +\item +\begin{codeenv} +\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{i.A} +\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{ii.A} +\end{codeenv} +These records aren't consecutive. They match the +\hyperref[itm:alphmatch]{alpha pattern}. The first location is +considered to consist of the prefix \code{i}, the separator +\code{.}\ (dot) and the number given by the character code of A. +The second location is considered to consist of the prefix +\code{ii}, the separator \code{.}\ (dot) and the number +given by the character code of A. + +The test fails because the numbers are equal and the prefixes are +different. + +\item +\begin{codeenv} +\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1.0} +\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{2.0} +\end{codeenv} +These records are consecutive. They match the \hyperref[itm:decmatch]{decimal +pattern}, and then step~\ref{itm:decgrp3eq} followed by +step~\ref{itm:decgrp3eqsepeq}. The \code{.0} part is discarded and +the test is retried with the first location set to 1 and the second +location set to 2. + +\item +\begin{codeenv} +\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1.1} +\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{2.1} +\end{codeenv} +These records aren't consecutive as the test branches off into +step~\ref{itm:decgrp3nz}. + +\item +\begin{codeenv} +\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{\cmd{@alph}\marg{1}} +\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{\cmd{@alph}\marg{2}} +\end{codeenv} +These records are consecutive. The locations match the +\hyperref[itm.csmatch]{control sequence pattern}. The control +sequences are the same, so the test is retried with the first +location set to 1 and the second location set to 2. + +In this example, the location has been written to the file as +\code{\csfmt{@alph}\margm{number}} instead of fully expanding according to the +normal behaviour of \code{\ics{alph}\margm{counter}}. (Note that +\gls!{glsxtrresourcefile} changes the category code of \code{@} to allow for +internal commands in locations.) This unusual case is for illustrative purposes. +\end{enumerate} + +\optsection{max-loc-diff} + +This setting is used to determine whether two locations are +considered consecutive. +The value must be an integer greater than or equal to 1. +(The default is \optfmt{1}.) + +For two locations, \meta{location-1} and \meta{location-2}, +that have numeric values $n_1$ and $n_2$ (and identical prefix, +counter and format), then the sequence \meta{location-1}, +\meta{location-2} is considered consecutive if +\[ +0 < n_2 - n_1 \leq \text{\meta{max-loc-diff}} +\] +The default value of 1 means that \meta{location-2} immediately +follows \meta{location-1} if $n_2 = n_1+1$. + +For example, if \meta{location-1} is \qt{B} and \meta{location-2} +is \qt{C}, then $n_1 = 66$ and $n_2 = 67$. Since $n_2 = 67 = 66+1= +n_1+1$ then \meta{location-2} immediately follows \meta{location-1}. + +This is used in the range formations within the location lists (as described +in the above section). +So, for example, the list \qt{1, 2, 3, 5, 7, 8, 10, 11, 12, 58, 59, +61} becomes +\qt{1--3, 5, 7, 8, 10--12, 58, 59, 61}. + +The automatically indexing of commands like \ics{gls} means that +the location lists can become long and ragged. You could +deal with this by switching off the automatic indexing and +only explicitly index pertinent use or you can adjust +the value of \optfmt{max-loc-diff} so that a range can be formed even +if there are one or two gaps in it. +By default, any location ranges that have skipped gaps in this +manner will be followed by \gls!{bibglspassim}. The default +definition of this command is obtained from the resource file. +For English, this is \verb*| passim| (space followed by \qt{passim}). + +So with the above set of locations, if \csopt[2]{max-loc-diff} then +the list becomes \qt{1--12 passim, 58--61 passim} which now highlights that +there are two blocks within the document related to that +term. + +\optsection{suffixF} + +If set, a range consisting of two consecutive locations +\meta{loc-1} and \meta{loc-2} will be +displayed in the location list as \meta{loc-1}\meta{value}. + +Note that \csopt[\empty]{suffixF} sets the suffix to the +empty string. To remove the suffix formation use +\csopt[none]{suffixF}. + +The default is \csopt[none]{suffixF}. + +\optsection{suffixFF} + +If set, a range consisting of three or more consecutive locations +\meta{loc-1} and \meta{loc-2} will be +displayed in the location list as \meta{loc-1}\meta{value}. + +Note that \csopt[\empty]{suffixFF} sets the suffix to the +empty string. To remove the suffix formation use +\csopt[none]{suffixFF}. + +The default is \csopt[none]{suffixFF}. + +\optsection{compact-ranges} + +The \meta{value} may be an integer \meta{n} or \optfmt{false} (equivalent to +\csopt[0]{compact-ranges}) or \optfmt{true} (equivalent to +\csopt[3]{compact-ranges}). If no \meta{value} is specified, +\optfmt{true} is assumed. + +This setting allows location ranges such as 184--189 to appear +more compactly as 184--9. The end location is encapsulated +in the command \gls{bibglscompact}, so the range would actually +become: +\begin{codeenv} +184\ics{delimR}\gls{bibglscompact}\marg{digit}\marg{18}\marg{9} +\end{codeenv} +If the location is in the form \code{\meta{cs}\margm{loc}} +(where \meta{cs} is a command) +then \gls{bibglscompact} will be inside the argument. +For example, if the range would normally be: +\begin{codeenv} +\cmd{custom}\marg{184}\ics{delimR}\cmd{custom}\marg{189} +\end{codeenv} +then it would become: +\begin{codeenv} +\cmd{custom}\marg{184}\ics{delimR}\cmd{custom}\marg{\gls{bibglscompact}\marg{digit}\marg{18}\marg{9}} +\end{codeenv} +The numerical value given in \csopt[\meta{n}]{compact-ranges} +indicates that compaction should only occur if the actual location +consists of at least \meta{n} characters, for $\meta{n} \geq 2$. +Any value of \meta{n} less than 2 will switch off compaction. + +For example, \code{189} consists of 3 characters, so it will be +compacted with \csopt[3]{compact-ranges} but not with +\csopt[4]{compact-ranges}. Whereas \code{\csfmt{custom}\marg{89}} +would only be compacted with \csopt[2]{compact-ranges} +because \code{89} only consists of 2 characters. + +The compaction isn't limited to decimal digits but it will only +occur if both the start and end location have the same number of +characters. For example, xvi--xviii can't be compacted because +the start consists of three characters and the end consists +of five characters, whereas xxv--xxx can be compacted to xxv--x, +which may look a little strange. In this case, you may want to +consider changing the definition of \cs{bibglscompact} so that +it only performs the compaction for digits. + +\optsection{see} + +If an entry has a \field{see} field, this can be placed before or +after the location list, or completely omitted (but the value will +still be available in the \field{see} field for use with +\ics{glsxtrusesee}). The required \meta{value} must be one of: +\begin{itemize} +\item \optfmt{omit}: omit the see reference from the location +list. +\item \optfmt{before}: place the see reference before the location +list. +\item \optfmt{after}: place the see reference after the location +list (default). +\end{itemize} + +The separator between the location list and the cross-reference is +provided by \gls!{bibglsseesep}. This separator is omitted if the +location list is empty. The cross-reference is written to the +\field{location} field using \code{\gls{bibglsusesee}\margm{label}}. + +\optsection{seealso} + +This is like \csopt{see} but governs the location of the cross-references +provided by the \field{seealso} field. You need at least v1.16 +of \sty{glossaries-extra} for this option. The values are the +same as for \csopt{see} but the separator is given by +\gls!{bibglsseealsosep}. The cross-reference is written to the +\field{location} field using \code{\gls{bibglsuseseealso}\margm{label}}. + +\optsection{alias} + +This is like \csopt{alias} but governs the location of the cross-references +provided by the \field{alias} field. The separator is given by +\gls!{bibglsaliassep}. The cross-reference is written to the +\field{location} field using \code{\gls{bibglsusealias}\margm{label}}. + +\optsection{alias-loc} + +If an entry has an \field{alias} field, the location list +may be retained or omitted or transferred to the target entry. +The required \meta{value} must be one of: +\begin{itemize} +\item\optfmt{keep}: keep the location list; +\item\optfmt{transfer}: transfer the location list; +\item\optfmt{omit}: omit the location list. +\end{itemize} +The default setting is \csopt[transfer]{alias-loc}. +In all cases, the target entry will be added to the \field{see} +field of the entry with the \field{alias} field, unless it +already has a \field{see} field (in which case the \field{see} value +is left unchanged). + +Note that with \csopt[transfer]{alias-loc}, both the aliased +entry and the target entry must be in the same resource set. +(That is, both entries have been selected by the same instance of +\gls!{glsxtrresourcefile}.) If you have \sty{glossaries-extra} version~1.12, +you may need to redefine \ics{glsxtrsetaliasnoindex} to do +nothing if the location lists aren't showing correctly +with aliased entries. (This was corrected in version~1.13.) + +\optsection{loc-prefix} + +The \csopt{loc-prefix} setting indicates that the location lists +should begin with \code{\gls!{bibglslocprefix}\margm{n}}. The \meta{value} may +be one of the following: +\begin{itemize} +\item \optfmt{false}: don't insert \code{\gls{bibglslocprefix}\margm{n}} at the +start of the location lists (default). + +\item \optfmt{\margm{prefix-1},\margm{prefix-2},\ldots,\margm{prefix-n}}: +insert \code{\gls{bibglslocprefix}\margm{n}} (where \meta{n} is the number of +locations in the list) at the start of each location list and the +definition of \gls{bibglslocprefix} will be appended to the glossary +preamble providing an \ics{ifcase} condition: +\begin{codeenv} +\cmd{providecommand}\marg{\gls{bibglslocprefix}}[1]\marg{\comment{} + \ics{ifcase}\idx{param}1 + \cmd{or} \meta{prefix-1}\gls{bibglspostlocprefix} + \cmd{or} \meta{prefix-2}\gls{bibglspostlocprefix} + \ldots + \cmd{else} \meta{prefix-n}\gls{bibglspostlocprefix} + \cmd{fi} +} +\end{codeenv} + +\item \optfmt{comma}: equivalent to \csopt[\marg{,~}]{loc-prefix} +but avoids confusion with the list syntax. That is, the prefix is a comma +followed by a space for non-empty locations. + +\item \optfmt{list}: equivalent to \csopt[\ics{pagelistname} ]{loc-prefix}. + +\item \optfmt{true}: equivalent to +\csopt[\gls{bibglspagename},\gls{bibglspagesname}]{loc-prefix}, +where the definitions of \gls{bibglspagename} and +\gls{bibglspagesname} are obtained from the \idx{tag.page} and +\idx{tag.pages} entries in \bibgls's \langxml. +This setting works best if the document's language matches the +language file. However, you can redefine these commands within +the document's language hooks or in the glossary preamble. + +\end{itemize} + +If \meta{value} is omitted, \optfmt{true} is assumed. Take care not +to mix different values of \csopt{loc-prefix} for entries for the +same \csopt{type} setting. It's okay to mix \csopt[false]{loc-prefix} with +another value, but don't mix non-\optfmt{false} values. +See the description of \gls!{bibglslocprefix} for +further details. + +For example: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[main]{type},\csopt[entries1]{src},\csopt[false]{loc-prefix}} +\gls{GlsXtrLoadResources}\oarg{\csopt[main]{type},\csopt[entries2]{src},\csopt{loc-prefix}} +\gls{GlsXtrLoadResources}\oarg{\csopt[symbols]{type},\csopt[entries3]{src},\csopt[p.,pp.]{loc-prefix}} +\end{codeenv} +This works since the conflicting \csopt[p.,pp.]{loc-prefix} and +\csopt[true]{loc-prefix} are in different glossaries (assigned through the +\csopt{type} key). The entries fetched from \filefmt{entries1.bib} +won't have a location prefix. The entries fetched from +\filefmt{entries2.bib} will have the location prefix obtained from +the language resource file. The entries fetched from +\filefmt{entries3.bib} will have the location prefix \qt{p.}\ or +\qt{pp.} (Note that using the \csopt{type} option isn't the same as +setting the \field{type} field for each entry in the \ext{bib} +file.) + +If the \csopt{type} option isn't used: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries1]{src},\csopt[false]{loc-prefix}} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries2]{src},\csopt{loc-prefix}} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries3]{src},\csopt[p.,pp.]{loc-prefix}} +\end{codeenv} +then \csopt[true]{loc-prefix} takes precedence over +\csopt[p.,pp.]{loc-prefix} (since it was used first). The entries fetched from +\filefmt{entries1.bib} still won't have a location prefix, but the entries +fetched from both \filefmt{entries2.bib} and \filefmt{entries3.bib} +have the location prefixes obtained from the language resource file. + +\optsection{loc-suffix} + +This is similar to \csopt{loc-prefix} but there are some subtle +differences. In this case \meta{value} may either be the keyword +\optfmt{false} (in which case the location suffix is omitted) +or a comma-separated list +\optfmt{\meta{suffix-0}\dcomma\meta{suffix-1}\dcomma\ldots\dcomma\meta{suffix-n}} +where \meta{suffix-0} is the suffix to use when the location list +only has a cross-reference with no locations, \meta{suffix-1} is the suffix to use +when the location list has one location (optionally with a +cross-reference), and so on. The final \meta{suffix-n} in the list +is the suffix when the location list has \meta{n} or more locations +(optionally with a cross-reference). + +This option will append \code{\gls!{bibglslocsuffix}\margm{n}} to location +lists that either have a cross-reference or have at least one location. +Unlike \gls{bibglslocprefix}, this command isn't used when the +location list is completely empty. Also, unlike +\gls{bibglslocprefix}, this suffix command doesn't have an equivalent +to \gls{bibglspostlocprefix}. + +If \meta{value} omitted, \csopt[\ics{at}\idx{periodchar}]{loc-suffix} +is assumed. The default is \csopt[false]{loc-suffix}. + +As with \csopt{loc-prefix}, take care not to mix different values +of \csopt{loc-suffix} for entries in the same glossary type. + +\optsection{loc-counters} + +Commands like \ics{gls} allow you to select a different +counter to use for the location for that specific instance +(overriding the default counter for the entry's glossary type). +This is done with the \glsopt{counter} option. For example, +consider the following document: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\oarg{colorlinks}\marg{hyperref} +\cmd{usepackage}\oarg{\styopt{record},\styopt[tree]{style}}\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src}\comment{data in entries.bib} +} +\strut +\cmd{begin}\marg{document} +\strut +\cs{gls}\marg{pi}. +\cmd{begin}\marg{equation} +\cs{gls}\oarg{\glsopt[\counter{equation}]{counter}}\marg{pi} +\cmd{end}\marg{equation} +\cmd{begin}\marg{equation} +\cs{gls}\oarg{\glsopt[\counter{equation}]{counter}}\marg{pi} +\cmd{end}\marg{equation} +\strut +\cmd{newpage} +\cmd{begin}\marg{equation} +\cs{gls}\oarg{\glsopt[\counter{equation}]{counter}}\marg{pi} +\cmd{end}\marg{equation} +\strut +\cmd{newpage} +\cs{gls}\marg{pi}. +\strut +\cmd{newpage} +\cs{gls}\marg{pi}. +\strut +\cmd{newpage} +\cs{gls}\marg{pi}. +\strut +\cmd{newpage} +\cs{printunsrtglossaries} +\cmd{end}\marg{document} +\end{codeenv} +This results in the location list \qt{1, 1--3, 3--5}. This +looks a little odd and it may seem as though the range formation +hasn't worked, but the locations are actually: page~1, equation~1, +equation~2, equation~3, page~3, page~4 and page~5. Ranges can't +be formed across different counters. + +The \csopt[\meta{list}]{loc-counters} option instructs \bibgls\ +to group the locations according to the counters given in +the comma-separated \meta{list}. If a location has a counter +that's not listed in \meta{list}, then the location is discarded. + +For example: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[\counter{equation},\counter{page}]{loc-counters},\comment{group locations by counter} + \csopt[entries]{src}\comment{data in entries.bib} +} +\end{codeenv} +This will first list the locations for the \counter{equation} +counter and then the locations for the \counter{page} counter. +Each group of locations is encapsulated within the command +\gls!{bibglslocationgroup}\margm{n}\margm{counter}\margm{locations}. +The groups are separated by \gls!{bibglslocationgroupsep}. + +The \meta{list} value must be non-empty. Use +\csopt[as-use]{loc-counters} to restore the default behaviour, where +the locations are listed in the document order of use, or +\csopt[false]{save-locations} to omit the location lists. Note that +you can't form counter groups from +\hyperref[sec:supplementalopts]{supplemental location lists}. + +\optsection{save-index-counter} + +\emph{This option requires at least version 1.29 of +\isty{glossaries-extra}.} The \meta{value} may be one of: +\begin{itemize} +\item \optfmt{false}: don't create the \field{indexcounter} field +(default); +\item \optfmt{true}: create the \field{indexcounter} field with the +value set to the first \counter{wrglossary} location; +\item \meta{encap}: create the \field{indexcounter} field with the +value set to the first \counter{wrglossary} location +where the \glsopt{format} is \meta{encap}. +\end{itemize} +This setting will have no effect if the \styopt{indexcounter} package +option hasn't been used. In the case where the \meta{value} is +\meta{encap}, make sure that this format takes priority in the +location precedence rules (\longarg{map-format}). If the location +with that \meta{encap} format value is discarded then it can't be +saved. + +The \styopt{indexcounter} package option +(\sty{glossaries-extra} v1.29+) creates a new counter called +\counter{wrglossary} that's incremented every time a term is +indexed (recorded), except for cross-references such as \cs{glssee}. +The increment is performed using \ics{refstepcounter} and is +followed by \code{\ics{label}\marg{wrglossary.\meta{n}}} where +\meta{n} is the value of the \counter{wrglossary} counter. +This option is intended for use with the \sty{hyperref} package to +allow locations to link back to the particular part of the page where +the term was referenced rather than to the top of the page. + +The \styopt{indexcounter} package option also automatically +implements the option \styopt[wrglossary]{counter}, which means that +each instance of \code{\ics{gls}\margm{id}} writes the label +information to the \iext{aux} file: +\begin{codeenv} +\cmd{newlabel}\marg{wrglossary.\meta{n}}\marg{\margm{n}\margm{page}\marg{}\marg{wrglossary.\meta{n}}\marg{}} +\end{codeenv} +(where \meta{page} is the page number) followed by the record: +\begin{codeenv} +\gls{glsxtr@record}\margm{id}\marg{}\marg{wrglossary}\marg{\encap{glsnumberformat}}\margm{n} +\end{codeenv} +The location here is actually the value of the \counter{wrglossary} +counter not the page number, but \bibgls\ can pick up the +corresponding \meta{page} from the \csfmt{newlabel} command. It then +replaces the record's location \meta{n} with: +\nosecdef{glsxtr@wrglossarylocation} +(but it only does this for records that have the \counter{wrglossary} +counter). + +The \sty{glossaries-extra} package (v1.29+) adjusts the definition +of \ics{glshypernumber} (which is internally used by +\cs{glsnumberformat}, \cs{hyperbf} etc when \sty{hyperref} has been +loaded) so that if the counter is \counter{wrglossary} then +\ics{pageref} is used instead of \ics{hyperlink}. This means that the +page number is displayed in the location list but it links back to +the place where the corresponding \cs{label} occurred. + +This method works partially with \appfmt{makeindex} and \appfmt{xindy} +but from their point of view the location is the value of the +\counter{wrglossary} counter, which interferes with their ability to +merge duplicate page numbers and form ranges. Since \bibgls\ is +designed specifically to work with \sty{glossaries-extra}, it's +aware of this special counter and will merge and collate the +locations according to the corresponding page number instead. + +With the default \longarg{merge-wrglossary-records} switch, if a +term has multiple \counter{wrglossary} records for a given page they +will be merged. The reference link will be the dominant record for +that page. + +The \csopt{save-index-counter} option allows you to save the first +of the \counter{wrglossary} locations for a given entry or the first +instance of a specific format of the \counter{wrglossary} locations +for a given entry. This location is stored in the +\field{indexcounter} internal field using: +\begin{codeenv} +\ics{GlsXtrSetField}\margm{id}\marg{\field{indexcounter}}\marg{\gls{glsxtr@wrglossarylocation}\margm{n}\margm{page}} +\end{codeenv} +Since \gls{glsxtr@wrglossarylocation} simply expands to its first +argument, the corresponding label can be obtained with: +\begin{codeenv} +wrglossary.\gls{glsxtr@wrglossarylocation}\margm{n}\margm{page} +\end{codeenv} +For convenience, \sty{glossaries-extra-bib2gls} provides: +\nosecdef{GlsXtrIndexCounterLink} +which will do: +\begin{codeenv*} +\ics{cs.hyperref.int}\oarg{wrglossary.\meta{value}}\margm{text} +\end{codeenv*} +where \meta{value} is the value of the \field{indexcounter} field if +it has been set. If the \field{indexcounter} field hasn't been set +(or if \sty{hyperref} hasn't been loaded) then just \meta{text} is +done. + +This provides a convenient way of encapsulating the \field{name} in +the glossary so that it links back to the first \counter{wrglossary} +entry or the first \glsopt[\meta{encap}]{format} \counter{wrglossary} +entry. This encapsulation can be done by providing a new glossary +style or more simply by redefining \ics{glsnamefont}: +\begin{codeenv} +\cmd{renewcommand}\marg{\cs{glsnamefont}}[1]\marg{\comment{} + \gls{GlsXtrIndexCounterLink}\marg{\idx{param}1}\marg{\cs{glscurrententrylabel}}} +\end{codeenv} +Here's a complete example: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\marg{lipsum}\comment{dummy filler text} +\cmd{usepackage}\oarg{colorlinks}\marg{hyperref} +\cmd{usepackage}\oarg{\styopt{record},\styopt{indexcounter}}\marg{glossaries-extra} +\strut +\cmd{newcommand}\marg{\cmd{primary}}[1]\marg{\cs{hyperbf}\marg{\idx{param}1}} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{terms defined in entries.bib} + \csopt[primary]{save-index-counter} +} +\strut +\cmd{renewcommand}\marg{\cs{glsnamefont}}[1]\marg{\comment{} + \gls{GlsXtrIndexCounterLink}\marg{\idx{param}1}\marg{\cs{glscurrententrylabel}}} +\strut +\cmd{begin}\marg{document} +\strut +A \cs{gls}\marg{sample}. \cmd{lipsum}*[1] A \cs{gls}\marg{duck}. +\strut +An equation: +\cmd{begin}\marg{equation} +\cs{gls}\oarg{\glsopt[\counter{equation}]{counter}}\marg{pi} +\cmd{end}\marg{equation} +\strut +\cmd{lipsum}[2] +\strut +Another \cs{gls}\oarg{\glsopt[primary]{format}}\marg{sample}. \cmd{lipsum}*[3] Another +\cs{gls}\marg{duck}. +\strut +\cs{gls}\marg{pi}. \cmd{lipsum}[4] +\strut +A \cs{gls}\marg{sample}. \cmd{lipsum}*[5] A \cs{gls}\marg{duck} and +\cs{gls}\oarg{\glsopt[primary]{format}}\marg{pi}. +\strut +\cmd{lipsum}*[6] A \cs{gls}\oarg{\glsopt[primary]{format}}\marg{duck}. +\strut +\cs{printunsrtglossaries} +\cmd{end}\marg{document} +\end{codeenv} +Note that the \glsopt[\counter{equation}]{counter} entry will have its own +independent location. In this example, it's difficult to tell the +difference between 1 (the equation reference) and 1 (the page +reference) in the location list for the \code{pi} entry. + +The \glsopt[primary]{format} instances indicate primary references. +They're displayed in bold (since \csfmt{primary} is defined to use +\csfmt{hyperbf}) and these are the locations saved in the +\field{indexcounter} field because that's the \meta{encap} +identified by the \csopt[primary]{save-index-counter} setting. + +\section{Supplemental Locations} +\label{sec:supplementalopts} + +\emph{These options require at least version 1.14 of +\isty{glossaries-extra}.} If you require locations from multiple +external sources, then you need at least version 1.36 of +\isty{glossaries-extra} (or, more specifically, +\isty{glossaries-extra-bib2gls}, which is automatically loaded +by the \styopt[only]{record} package option). + +The \sty{glossaries-extra} package (from v1.14) provides a way of +manually adding locations in supplemental documents through the use +of the \glsaddopt{thevalue} option in the optional argument of +\ics{glsadd}. Setting values manually is inconvenient and can result +in errors, so \bibgls\ provides a way of doing this automatically. +Both the main document and the supplementary document need to use +the \styopt{record} option. The entries provided in the \csopt{src} +set must have the same labels as those used in the supplementary +document. (The simplest way to achieve this is to ensure that both +documents use the same \ext{bib} files and the same prefixes.) + +For example, suppose the file \filefmt{entries.bib} contains: +\begin{codeenv} +\atentry{entry}\marg{sample, + \field{name}=\marg{sample}, + \field{description}=\qtdelim{an example entry} +} +\strut +\atentry{abbreviation}\marg{html, + \field{short}=\qtdelim{html}, + \field{long}=\marg{hypertext markup language} +} +\strut +\atentry{abbreviation}\marg{ssi, + \field{short}=\qtdelim{ssi}, + \field{long}=\qtdelim{server-side includes} +} +\strut +\atentry{index}\marg{goose,\field{plural}=\qtdelim{geese}} +\end{codeenv} +Now suppose the supplementary document is contained in the file +\filefmt{suppl.tex}: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\oarg{colorlinks}\marg{hyperref} +\cmd{usepackage}\oarg{\styopt{record},\styopt[section]{counter}}\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}} +\strut +\cmd{renewcommand}\marg{\cmd{thesection}}\marg{S\cmd{arabic}\marg{section}} +\cmd{renewcommand}\marg{\cmd{theHsection}}\marg{\cmd{thepart}.\cmd{thesection}} +\strut +\cmd{begin}\marg{document} +\cmd{part}\marg{Sample Part} +\cmd{section}\marg{Sample Section} +\cs{gls}\marg{goose}. \cs{gls}\marg{sample}. +\strut +\cmd{part}\marg{Another Part} +\cmd{section}\marg{Another Section} +\cs{gls}\marg{html}. +\cs{gls}\marg{ssi}. +\strut +\cs{printunsrtglossaries} +\cmd{end}\marg{document} +\end{codeenv} +This uses the \counter{section} counter for the locations and has a +prefix (\code{\csfmt{thepart}.})\ for the section hyperlinks. + +Now let's suppose I have another document called \filefmt{main.tex} +that uses the \code{sample} entry, but also needs to include the +location (S1) from the supplementary document. The manual approached +offered by \styfmt{glossaries-extra} is quite cumbersome and requires +setting the \catattr{externallocation} attribute and using +\ics{glsadd} with \glsaddopt[S1]{thevalue}, \glsaddopt[I.S1]{theHvalue} +and \glsaddopt[\encap{glsxtrsupphypernumber}]{format}. + +This can be simplified with \bibgls\ by using the +\optfmt{supplemental-locations} option, described below. + +Version 1.36 of \isty{glossaries-extra-bib2gls} introduces some +special location formatting commands that don't use the +\catattr{externallocation} attribute, but instead have an extra +argument that indicates the external reference. The additional +argument means that it can't be used by the \glsaddopt{format} +key, but with \bibgls\ you don't use \cs{glsadd} to record +the external locations. Instead it obtains the records from +the corresponding supplementary \ext{aux} file, and adjusts the +location encapsulator as appropriate. + +If \bibgls\ detects an older version of \sty{glossaries-extra}, +it will only allow one external supplemental source, and +will set the \catattr{externallocation} attribute and use +the \encap{glsxtrsupphypernumber} format. Otherwise \bibgls\ +will allow multiple sources and use the newer method. + +\optsection{supplemental-locations} + +The value should be the base name (without the extension) of the +supplementary document (\optfmt{suppl} in the above example). +If you have at least version 1.36 of \sty{glossaries-extra}, +the value may be a comma-separated list of base names (without the +extensions) of the supplementary documents. If an older version is +detected, \bibgls\ will issue a warning and only accept the first +element of the list. + +For example: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\oarg{colorlinks}\marg{hyperref} +\cmd{usepackage}\oarg{\styopt{record}}\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[suppl]{supplemental-locations},\comment{fetch records from suppl.aux} + \csopt[entries]{src}} +\strut +\cmd{begin}\marg{document} +\cs{Gls}\marg{sample} document. +\strut +\cs{printunsrtglossaries} +\cmd{end}\marg{document} +\end{codeenv} +The location list for \code{sample} will now be \qt{1, S1} (page~1 +from the main document and S1 from the supplementary document). + +With \sty{glossaries-extra} v1.36+, a regular location from the +supplementary document will be encapsulated with: +\nosecdef{glsxtrdisplaysupploc} +By default, this simply creates an external hyperlink to the +supplementary document with the location as the hyperlink text. +The hyperlink is created using \meta{src} as the target path +with the fragment part (anchor) formed from the prefix and +location. The \catattr{externallocation} attribute is not set in +this case. The actual formatting is done via: +\nosecdef{glsxtrmultisupplocation} +which ignores the \meta{format} argument by default. Its +definition is simply: +\begin{codeenv} +\cmd{newcommand}*\marg{\gls{glsxtrmultisupplocation}}[3]\marg{\comment{} + \marg{\comment{scope required to localise changes} + \cmd{def}\cs{glsxtrsupplocationurl}\marg{\idx{param}2}\comment{} + \cs{glshypernumber}\marg{\idx{param}1}\comment{} + }\comment{} +} +\end{codeenv} +This locally sets the command \ics{glsxtrsupplocationurl}, which is checked +by \ics{glshypernumber} to establish an external rather than internal link. +You can redefine the supplemental location command to retain the original +\idx{encap} used in the target document: +\begin{codeenv} +\cmd{renewcommand}*\marg{\gls{glsxtrmultisupplocation}}[3]\marg{\comment{} + \marg{\comment{scope required to localise changes} + \cmd{def}\cs{glsxtrsupplocationurl}\marg{\idx{param}2}\comment{} + \ics{csuse}\marg{\idx{param}3}\marg{\idx{param}1}\comment{} + }\comment{} +} +\end{codeenv} +but remember that if a hyperlink is required, the identified +control sequence name must correspond to a command that +uses \cs{glshyperlink} (such as \cs{hyperbf}), otherwise you +will lose the hyperlink. + +With older versions of \sty{glossaries-extra}, +the original location format from the supplementary document +will be replaced by \encap{glsxtrsupphypernumber}, which +again produces an external hyperlink. The \catattr{externallocation} +attribute also needs to be set (this can be done automatically with +\csopt{supplemental-category}) to identify the external document. +The original format can't be accessed. + +In both cases, if the document hasn't loaded the \isty{hyperref} package, the +location will simply be displayed without a hyperlink. Even if both the main +and the supplementary documents have loaded \sty{hyperref}, note that not all +PDF viewers can handle external hyperlinks, and some that can open the external +PDF file may not recognise the destination within that file. + +The special \code{nameref} locations (see +\longarg{merge-nameref-on}) are still identified with +\gls!{glsxtrdisplaylocnameref} but the \meta{file} argument will now +be set. + +As from \bibgls\ v1.7, any awkward characters in the file path are +replaced with \gls{bibglshrefchar} or (for \idx{non-ASCII} characters when +\sty{fontspec} is loaded) \gls{bibglshrefunicode}. Both commands +take two arguments: the hexadecimal character code and the actual +character. In the case of \gls{bibglshrefchar}, the second +argument is ignored, and the first is preceded by a literal percent +character, so \filefmt{file name.pdf} will be converted to: +\begin{codeenv} +file\gls{bibglshrefchar}\marg{20}\marg{ }name.pdf +\end{codeenv} +which will expand to \verb|file%20name.pdf|. +In the case of \gls{bibglshrefunicode}, the first argument is +ignored, so \filefmt{skr\'aarnafn.pdf} will be converted to: +\begin{codeenv} +skr\gls{bibglshrefunicode}\marg{E1}\marg{\'a}arnafn.pdf +\end{codeenv} +which will expand to \code{skr\'aarnafn.pdf}. + + +The supplementary locations lists are encapsulated within +\gls{bibglssupplemental}. With \sty{glossaries-extra} v1.36+, +this command will encapsulate the sub-lists with +\gls{bibglssupplementalsublist}. + +So the above example with an old version of \sty{glossaries-extra} +(pre 1.36) will set the supplemental location list (which only consists +of one location) to: +\begin{codeenv} +\gls{bibglssupplemental} +\marg{1}\marg{\ics{setentrycounter}\oarg{I}\marg{\counter{section}}\cs{glsxtrsupphypernumber}\marg{S1}} +\end{codeenv} +and the external target must be supplied through the +\catattr{externallocation} attribute, which can be set +with the \csopt{supplemental-category} option. + +Whereas with at least version 1.36, the list will be: +\begin{codeenv} +\gls{bibglssupplemental}\marg{1}\marg{\gls{bibglssupplementalsublist}\marg{1}\marg{suppl.pdf} +\marg{\gls{glsxtrdisplaysupploc}\marg{I}\marg{\counter{section}}\marg{\encap{glsnumberformat}}\marg{suppl.pdf}\marg{S1}}} +\end{codeenv} + +If an entry has both a main location list and a supplementary +location list (such as the \code{sample} entry above), the lists +will be separated by \gls!{bibglssupplementalsep}. The sub-lists +(when supported) are separated by \gls{bibglssupplementalsubsep}. + +\optsection{supplemental-selection} + +In the above example, only the \code{sample} entry is listed in +the main document, even though the supplementary document also +references the \code{goose}, \code{html} and \code{ssi} +entries. By default, only those entries that are referenced in the +main document will have supplementary locations added (if found in +the supplementary document's \iext{aux} file). You can additionally +include other entries that are referenced in the supplementary +document but not in the main document using +\optfmt{supplemental-selection}. The \meta{value} may be one of the +following: +\begin{itemize} +\item \optfmt{all}: add all the entries in the supplementary +document that have been defined in the \ext{bib} files listed in +\csopt{src} for this resource set in the main document. +\item \optfmt{selected}: only add supplemental locations for entries +that have already been selected by this resource set. +\item \meta{label-1},\ldots,\meta{label-2}: in addition to all those +entries that have already been selected by this resource set, also +add the entries identified in the comma-separated list. If a label +in this list doesn't have a record in the supplementary document's +\ext{aux} file, it will be ignored. +\end{itemize} +Any records in the supplementary \ext{aux} file that aren't defined +by the current resource set (through the \ext{bib} files listed in +\csopt{src}) will be ignored. Entry aliases aren't taken into +account when including supplementary locations. + +For example: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\oarg{colorlinks}\marg{hyperref} +\cmd{usepackage}\oarg{\styopt{record}}\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[suppl]{supplemental-locations}, + \csopt[html,ssi]{supplemental-selection}, + \csopt[entries]{src}} +\strut +\cmd{begin}\marg{document} +\cs{Gls}\marg{sample} document. +\strut +\cs{printunsrtglossaries} +\cmd{end}\marg{document} +\end{codeenv} +This will additionally add the \code{html} and \code{ssi} entries +even though they haven't been used in this document. The +\code{goose} entry used in the supplementary document won't be +included. + +\optsection{supplemental-category} + +The \field{category} field for entries containing supplemental location +lists may be set using this option. If unset, +\meta{value} defaults to the same as that given by the +\csopt{category} option. The \meta{value} may either be a known +identifier (as per \csopt{category}) or the category label. For example: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\oarg{colorlinks}\marg{hyperref} +\cmd{usepackage}\oarg{\styopt{record}}\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[suppl]{supplemental-locations}, + \csopt[html,ssi]{supplemental-selection}, + \csopt[supplemental]{supplemental-category}, + \csopt[entries]{src}} +\strut +\cmd{begin}\marg{document} +\cs{Gls}\marg{sample} document. +\strut +\cs{printunsrtglossaries} +\cmd{end}\marg{document} +\end{codeenv} + +\section{Sorting} +\label{sec:sortingopts} + +Entries are typically displayed in an ordered list, but the +\styfmt{glossaries-extra} package is versatile enough to be used in +wider contexts than simple terms, symbols or abbreviations. For +example, entries could contain theorems or problems where the +\field{name} supplies the title and the \field{description} provides +a description of the theorem or problem. Another field might then +contain the proof or solution. Therefore, somewhat unusually for an +indexing application, \bibgls\ also provides the option to shuffle +the entries instead of sorting them. + +This section covers the resource options for sorting primary +entries. See \sectionref{sec:dualoptssort} for sorting dual entries +and also \csopt{sort-label-list} for sorting field values that +contain a comma-separated list of entry labels (such as the +\field{see} or \field{seealso} fields). + +The sort methods that use a comparison function (that is, all the +sort methods except those listed in \tableref{tab:sortoptionsnosort}) +require a sort value for each entry. The function compares these +values to determine the order. By default, this sort value is +obtained from the \field{sort} field but for greater flexibility +it's best to not actually set this field. \bibgls\ has a set of fallbacks +that it uses if a field it needs to access is missing. These +fallbacks depend on the entry type and resource settings. + +For example, if a term defined with \atentry{index} doesn't have the +\field{sort} field set then \bibgls\ will use the value given by the +\field{name} field because \field{name} is the fallback field for +\field{sort} for \atentry{index} entries. If the \field{name} field +isn't set either then \bibgls\ will use the fallback for that field. +In the case of \atentry{index} that's the entry's label. If the +\field{sort} field is explicitly set then there's no need to use the +fallback. + +If, on the other hand, a term defined with \atentry{symbol} doesn't +have the \field{sort} field set then \bibgls\ will use the value +from the field identified by \csopt{symbol-sort-fallback}, which is +the entry's label by default (not the \field{name} field). + +This means that if I don't explicitly set the \field{sort} field for +any entries then I can, for example, sort terms defined with +\atentry{index} by \field{name} and those defined with +\atentry{symbol} by \field{description} with the setting: +\begin{codeenv} +\csopt[description]{symbol-sort-fallback} +\end{codeenv} + +If the field used to obtain the sort value is changed +(with \csopt{sort-field}) then the \field{sort} field won't be +queried. This reduces the flexibility of selecting the most +appropriate field for given entry types. For example, +\csopt[name]{sort-field} will force all entries to be sorted by the +\field{name} field, which may not be appropriate for symbols. + +\begin{important} +If you choose a field whose value must be a label (such as +\field{parent} or \field{group}) then the sort value will be that label. +\end{important} + +You can have \atentry{preamble} definitions that +can be hidden from \bibgls's interpreter. For example, +\exfile{no-interpret-preamble.bib} might contain: +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cmd{providecommand}\marg{\gls{sortop}}[2]\marg{\idx{param}1 \idx{param}2}}} +\end{codeenv} +which is loaded using: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[no-interpret-preamble]{src}, + \csopt[false]{interpret-preamble}} +\end{codeenv} +This provides a custom command: +\nosecdef{sortop} +for internal use in the document. (Remember it won't be defined on +the first \LaTeX\ run before the \iext{glstex} file has been +created and so is only used within entry fields.) + +Another file, say, \filefmt{interpret-preamble.bib} may provide +a definition for \bibgls: +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cmd{providecommand}\marg{\gls{sortop}}[2]\marg{\idx{param}2, \idx{param}1}}} +\end{codeenv} +which can be processed with: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[interpret-preamble]{src}} +\end{codeenv} +to provide \bibgls\ with this definition. +The \filefmt{entries.bib} file could contain: +\begin{codeenv} +\atentry{entry}\marg{caesar, + \field{name}=\marg{\gls{sortop}\marg{Gaius Julius}\marg{Caesar}}, + \field{first}=\marg{Julius Caesar}, + \field{text}=\marg{Caesar}, + \field{description}=\marg{Roman politician and general} +} +\end{codeenv} +and then be processed with: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}} +\end{codeenv} + +The definition provided in \filefmt{interpret-preamble.bib}, which +swaps the two arguments around, is now picked up by \bibgls, so the +sort value becomes \code{Caesar, Gaius Julius}, but this new +definition doesn't affect the document since \LaTeX\ has already +defined \gls{sortop} from the first resource set, so the name will +appear as \qt{Gaius Julius Caesar} in the glossary. (If you have +\cs{renewcommand} rather than \cs{providecommand}, you can prevent +the redefinition occurring in the document with +\csopt[false]{write-preamble}.) + +Alternatively both of these \ext{bib} files can be loaded in one +\idx{resourceset}: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[interpret-preamble,entries]{src}} +\end{codeenv} +Another possibility is to provide a custom package that contains the +command definitions for the \bibgls\ interpreter and load it with +\longarg{custom-packages} instead of having the +\filefmt{interpret-preamble.bib} file. + +\optsection{sort} + +The \csopt{sort} key indicates how primary entries should be sorted. +If the \meta{value} is omitted, \csopt[doc]{sort} is assumed. If the +\csopt{sort} option isn't used then \csopt[doc]{sort} is assumed if the +document has a language that's been detected by \sty{tracklang}, +otherwise \csopt[locale]{sort} is assumed. + +The \optfmt{\meta{method}\dhyphen reverse} options reverse the +result returned by the corresponding \meta{method} comparator. +However \optfmt{\meta{method}\dhyphen reverse} may not produce a +list that's the exact reverse of the underlying non-reversed +\meta{method} as the hierarchical structure or associated settings +can affect the order. + +\begin{table}[p] +\caption{Summary of Available Sort Options: No Actual Sorting} +\label{tab:sortoptionsnosort} +\centering +\begin{tabular}{ll} +\optfmt{none} or \optfmt{unsrt} & don't sort\tabularnewline +\optfmt{random} & shuffle entries\tabularnewline +\optfmt{use} & order of use\tabularnewline +\optfmt{use-reverse} & reverse order of use +\end{tabular} +\end{table} + +\begin{table}[p] +\caption{Summary of Available Sort Options: Alphabet} +\label{tab:sortoptionsrule} +\centering +\begin{tabular}{ll} +\meta{lang tag} & sort according to this language tag\tabularnewline +\meta{lang tag}\optfmt{-reverse} & reverse sort according to this language tag\tabularnewline +\optfmt{doc} & sort according to the document +language\tabularnewline +\optfmt{doc-reverse} & reverse sort according to the document +language\tabularnewline +\optfmt{locale} & sort according to the default +locale\tabularnewline +\optfmt{locale-reverse} & reverse sort according to the default +locale\tabularnewline +\optfmt{custom} & sort according to \csopt[\meta{custom +rule}]{sort-rule}\tabularnewline +\optfmt{custom-reverse} & reverse sort according to \csopt[\meta{custom rule}]{sort-rule} +\end{tabular} +\end{table} + +\begin{table}[p] +\caption{Summary of Available Sort Options: Letter (Non-Locale)} +\label{tab:sortoptionsletter} +\centering +\begin{tabular}{ll} +\optfmt{letter-case} & case-sensitive letter sort\tabularnewline +\optfmt{letter-case-reverse} & reverse case-sensitive letter +sort\tabularnewline +\optfmt{letter-nocase} & case-insensitive letter sort\tabularnewline +\optfmt{letter-nocase-reverse} & reverse case-insensitive letter +sort\tabularnewline +\optfmt{letter-upperlower} & upper-lower letter sort\tabularnewline +\optfmt{letter-upperlower-reverse} & reverse upper-lower letter +sort\tabularnewline +\optfmt{letter-lowerupper} & lower-upper letter sort\tabularnewline +\optfmt{letter-lowerupper-reverse} & reverse lower-upper letter sort +\end{tabular} +\end{table} + +\begin{table}[p] +\caption{Summary of Available Sort Options: Letter-Number} +\label{tab:sortoptionsletternumber} +\centering +\begin{tabular}{ll} +\optfmt{letternumber-case} & case-sensitive letter-number +sort\tabularnewline +\optfmt{letternumber-case-reverse} & reverse case-sensitive +letter-number sort\tabularnewline +\optfmt{letternumber-nocase} & case-insensitive letter-number +sort\tabularnewline +\optfmt{letternumber-nocase-reverse} & reverse case-insensitive +letter-number sort\tabularnewline +\optfmt{letternumber-upperlower} & upper-lower letter-number +sort\tabularnewline +\optfmt{letternumber-upperlower-reverse} & reverse upper-lower +letter-number sort\tabularnewline +\optfmt{letternumber-lowerupper} & lower-upper letter-number +sort\tabularnewline +\optfmt{letternumber-lowerupper-reverse} & reverse lower-upper letter-number sort +\end{tabular} +\end{table} + +\begin{table}[p] +\caption{Summary of Available Sort Options: Numerical} +\label{tab:sortoptionsnumerical} +\centering +\begin{tabular}{ll} +\optfmt{integer} & integer sort\tabularnewline +\optfmt{integer-reverse} & reverse integer sort\tabularnewline +\optfmt{hex} & hexadecimal sort\tabularnewline +\optfmt{hex-reverse} & reverse hexadecimal sort\tabularnewline +\optfmt{octal} & octal sort\tabularnewline +\optfmt{octal-reverse} & reverse octal sort\tabularnewline +\optfmt{binary} & binary sort\tabularnewline +\optfmt{binary-reverse} & reverse binary sort\tabularnewline +\optfmt{float} & float sort\tabularnewline +\optfmt{float-reverse} & reverse float sort\tabularnewline +\optfmt{double} & double sort\tabularnewline +\optfmt{double-reverse} & reverse double sort\tabularnewline +\optfmt{numeric} & locale-sensitive numeric sort\tabularnewline +\optfmt{numeric-reverse} & reverse locale-sensitive numeric +sort\tabularnewline +\optfmt{currency} & locale-sensitive currency sort\tabularnewline +\optfmt{currency-reverse} & reverse locale-sensitive currency +sort\tabularnewline +\optfmt{percent} & locale-sensitive percent sort\tabularnewline +\optfmt{percent-reverse} & reverse locale-sensitive percent +sort\tabularnewline +\optfmt{numberformat} & locale-sensitive custom numeric +sort\tabularnewline +\optfmt{numberformat-reverse} & reverse locale-sensitive custom numeric sort +\end{tabular} +\end{table} + +\begin{table}[p] +\caption{Summary of Available Sort Options: Date-Time} +\label{tab:sortoptionsdatetime} +\centering +\begin{tabular}{ll} +\optfmt{date} & locale-sensitive date sort\tabularnewline +\optfmt{date-reverse} & reverse locale-sensitive date +sort\tabularnewline +\optfmt{datetime} & locale-sensitive date-time sort\tabularnewline +\optfmt{datetime-reverse} & reverse locale-sensitive date-time +sort\tabularnewline +\optfmt{time} & locale-sensitive time sort\tabularnewline +\optfmt{time-reverse} & reverse locale-sensitive time sort +\end{tabular} +\end{table} + +\subsubsection{No Sort} + +The sort methods listed in \tableref{tab:sortoptionsnosort} +don't actually perform any sorting. This may cause a problem for +hierarchical entries. In some cases this can lead to detached child +entries or an attempt to define a child entry before its parent. +\begin{itemize} + +\item \optfmt{none} (or \optfmt{unsrt}): don't sort the entries. +(The entries will be in the order they were processed when parsing +the data.) + +\item \optfmt{random}: shuffles rather than sorts the entries. +This won't work if there are hierarchical entries, so it's best +to use this option with \csopt{flatten}. The seed for the +random generator can be set using \csopt{shuffle} (which +also automatically sets \csopt[random]{sort} and \csopt{flatten}). + +\item \optfmt{use}: order of use. This order is determined +by the records written to the \iext{aux} file by the \styopt{record} +package option. Dependencies and cross-references (including those +identified with \ics{glssee}) come after entries with records. + +Note that this is different from using the analogous option with +\idx{makeindex} or \idx{xindy}, which does actually sort +numerically, where each entry has an associated number set on the +first use of that term that's used as the sort value. + +\item \optfmt{use-reverse}: reverses the order that would be +obtained with \csopt[use]{sort} without reference to hierarchy. + +\end{itemize} + +\subsubsection{Alphabet} + +The sort methods listed in \tableref{tab:sortoptionsrule} are for +alphabets that are defined by a rule. These usually ignore most +punctuation and may ignore modifiers (such as accents). Use with +\csopt{break-at} to determine whether or not to split at word +boundaries. The collation rules (except for the custom options) are obtained +from the \idx{localeprovider} (see page~\pageref{locale.provider}). + +\begin{itemize} +\item \meta{lang tag}: sort according to the rules of the locale +given by the \idx{IETF} language tag \meta{lang tag}. + +\item \meta{lang tag}\optfmt{-reverse}: reverse sort according to the rules of the locale +given by the \idx{IETF} language tag \meta{lang tag}. + +\item \optfmt{locale}: equivalent to +\csopt[\meta{lang tag}]{sort} where \meta{lang tag} is obtained +from the \idx{JRE} (which usually matches the +operating system's locale). + +\item \optfmt{locale-reverse}: equivalent to +\csopt[\meta{lang tag}-reverse]{sort} where \meta{lang tag} is obtained +from the \idx{JRE}. + +\item \optfmt{doc}: sort the entries according to the document +language. This is equivalent to \csopt[\meta{lang tag}]{sort} +where \meta{lang tag} is the locale associated with the document +language. In the case of a multi-lingual document, \meta{lang tag} +is the locale of the last language resource file to be loaded through +\isty{tracklang}'s interface. It's best to explicitly set the locale +for multi-lingual documents to avoid confusion. If no languages have been tracked, this +option is equivalent to \csopt[locale]{sort}. + +\item \optfmt{doc-reverse}: as \optfmt{doc} but in reverse order. + +\item \optfmt{custom}: sort the entries according to the +rule provided by \csopt{sort-rule}. + +\item \optfmt{custom-reverse}: reverse sort the entries according to the +rule provided by \csopt{sort-rule}. +\end{itemize} + +Note that \csopt[\meta{locale}]{sort} can provide more detail about the +given locale than \csopt[doc]{sort}, depending on how the document +language has been specified. For example, with: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\cmd{usepackage}\oarg{ngerman}\marg{babel} +\cmd{usepackage}\oarg{\styopt{record}}\marg{glossaries} +\gls{GlsXtrLoadResources}\oarg{\csopt[german-terms]{src}} +\end{codeenv} +the language tag will be \code{de-1996}, which doesn't have an +associated region, so this is equivalent to using \csopt[de-1996]{sort}. +Whereas with: +\begin{codeenv} +\cmd{documentclass}\oarg{de-DE-1996}\marg{article} +\cmd{usepackage}\oarg{ngerman}\marg{babel} +\cmd{usepackage}\oarg{\styopt{record}}\marg{glossaries} +\gls{GlsXtrLoadResources}\oarg{\csopt[german-terms]{src}} +\end{codeenv} +the language tag will be \code{de-DE-1996} because \isty{tracklang} +has picked up the locale from the document class options, so this is +equivalent to using \csopt[de-DE-1996]{sort}. This is +only likely to cause a difference if a language has different +sorting rules according to the region or if the language may be +written in multiple scripts. + +If no language package is loaded then the default is \csopt[locale]{sort} +rather than \csopt[doc]{sort}. For example, with: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\cmd{usepackage}\oarg{\styopt{record}}\marg{glossaries} +\gls{GlsXtrLoadResources}\oarg{\csopt[german-terms]{src}} +\end{codeenv} +the language tag will be whatever is the default locale for the \idx{JVM}. +For a user in Germany, this could be \code{de-DE-1996} and for a user +in Austria this could be \code{de-AT-1996}. + +A multilingual document will need to have the \csopt{sort} specified +when loading the \idx{resourceset} to ensure the correct language is chosen. +For example: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[english-terms]{src},\csopt[en-GB]{sort}} +\gls{GlsXtrLoadResources}\oarg{\csopt[german-terms]{src},\csopt[de-DE-1996]{sort}} +\end{codeenv} + +\subsubsection{Letter (Non Locale)} + +The sort methods listed in \tableref{tab:sortoptionsletter} +use letter comparators. These simply compare the +character codes. The \optfmt{-nocase} options first convert the +\field{sort} field to \idx{lowercase} before performing the sort to +provide a case-insensitive comparison. + +Punctuation isn't ignored. +Use \csopt[\meta{lang tag}]{sort} with \csopt[none]{break-at} to +emulate \idx!{xindy}['s] locale letter ordering. The examples below +show the ordering of the list \code{antelope}, \code{bee}, \code{Africa}, +\code{aardvark} and \code{Brazil}. +\begin{itemize} +\item \optfmt{letter-case}: case-sensitive letter sort. +\Idx{uppercase} and \idx{lowercase} are in separate letter groups. +Example: + +\code{Africa} (letter group \idx{uppercase} \qt{A}), \code{Brazil} +(letter group \idx{uppercase} \qt{B}), \code{aardvark} (letter group +\idx{lowercase} \qt{a}), \code{antelope} (letter group +\idx{lowercase} \qt{a}), \code{bee} (letter group \idx{lowercase} \qt{b}). + +\item \optfmt{letter-case-reverse}: reverse case-sensitive letter sort. +Example: + +\code{bee} (letter group \idx{lowercase} \qt{b}), \code{antelope} +(letter group \idx{lowercase} \qt{a}), \code{aardvark} (letter group +\idx{lowercase} \qt{a}) \code{Brazil} (letter group \idx{uppercase} +\qt{B}), \code{Africa} (letter group \idx{uppercase} \qt{A}). + +\item \optfmt{letter-nocase}: case-insensitive letter sort. (All +\idx{uppercase} characters will have first been converted to +\idx{lowercase} in the sort value.) +Example: + +\code{aardvark} (letter group \qt{A}), \code{Africa} +(letter group \qt{A}), \code{antelope} (letter group \qt{A}), +\code{bee} (letter group \qt{B}), +\code{Brazil} (letter group \qt{B}). + +\item \optfmt{letter-nocase-reverse}: reverse case-insensitive letter sort. +Example: + +\code{Brazil} (letter group \qt{B}), \code{bee} (letter group +\qt{B}), \code{antelope} (letter group \qt{A}), \code{Africa} +(letter group \qt{A}), \code{aardvark} (letter group \qt{A}). + +\item \optfmt{letter-upperlower}: each character pair is first +compared according to their \idx{lowercase} values. If these are equal, +then they are compared according to case. This puts upper and lower +case in the same letter group but the \idx{uppercase} comes first. +Example: + +\code{Africa} (letter group \qt{A}), \code{aardvark} (letter group +\qt{A}), \code{antelope} (letter group \qt{A}), \code{Brazil} +(letter group \qt{B}), \code{bee} (letter group \qt{B}). + +\item \optfmt{letter-upperlower-reverse}: reverse upper-lower letter sort. +This now puts the \idx{lowercase} letters first within the letter group. +Example: + +\code{bee} (letter group \qt{B}), \code{Brazil} (letter group +\qt{B}), \code{antelope} (letter group \qt{A}), \code{aardvark} +(letter group \qt{A}), \code{Africa} (letter group \qt{A}). + +\item \optfmt{letter-lowerupper}: each character pair is first +compared according to their \idx{lowercase} values. If these are equal, +then they are compared according to case. This puts +\idxlink{uppercase}{upper} and \idx{lowercase} in the same letter group but the \idx{lowercase} comes first. +Example: + +\code{aardvark} (letter group \qt{A}), \code{antelope} (letter group \qt{A}), +\code{Africa} (letter group \qt{A}), \code{bee} (letter group +\qt{B}), \code{Brazil} (letter group \qt{B}). + +\item \optfmt{letter-lowerupper-reverse}: reverse lower-upper letter sort. +This now puts the \idx{uppercase} letters first within the letter group. +Example: + +\code{Brazil} (letter group \qt{B}), \code{bee} (letter group +\qt{B}), \code{Africa} (letter group \qt{A}), \code{antelope} +(letter group \qt{A}), \code{aardvark} (letter group \qt{A}). + +\end{itemize} + +\subsubsection{Letter-Number} +\label{sec:letternumber} + +The sort methods listed in \tableref{tab:sortoptionsletternumber} +use a letter-integer hybrid. They behave in a similar way to the +above letter sort methods, but if an integer number pattern is detected in +the string then the sub-string containing the number will be compared. +This only detects base 10 integers (unlike the numeric methods +such as \csopt[hexadecimal]{sort} or \csopt[float]{sort}) but in +addition to recognising all the digits in the Unicode \idx{numberdecimaldigit} +category it also recognises the subscript and +superscript digits, such as \textsuperscript{1} (\hex{00B9}) +and \textsuperscript{2} (\hex{00B2}). + +As with the letter sort methods, letters are compared using a +character code comparison not by a locale alphabet. The closest +locale-sensitive equivalent is to use \csopt{sort-number-pad} with a +locale sort method. + +\begin{figure} +\figcontents +{% +\begin{tikzpicture}[every node/.style={minimum size=9mm}, + ampersand replacement=\&] +\matrix[font={\Large\ttfamily}] +{ + \node[draw]{a\hexsb{61}}; \& \node{$=$}; \& \node[draw]{a\hexsb{61}}; \&[20mm] + \node[draw]{a\hexsb{61}}; \& \node{$=$}; \& \node[draw]{a\hexsb{61}}; + \\ + \node[draw]{b\hexsb{62}}; \& \node{$=$}; \& \node[draw]{b\hexsb{62}}; \& + \node[draw]{b\hexsb{62}}; \& \node{$=$}; \& \node[draw]{b\hexsb{62}}; + \\ + \node[draw]{c\hexsb{63}}; \& \node{$=$}; \& \node[draw]{c\hexsb{63}}; \& + \node[draw]{c\hexsb{63}}; \& \node{$=$}; \& \node[draw]{c\hexsb{63}}; + \\ + \node[draw,ultra thick]{1\hexsb{31}}; \& \node{$<$}; \& + \node[draw,ultra thick]{6\hexsb{36}}; \& + \node (n1) {1}; \& \node{$>$}; \& \node[draw,ultra thick]{6}; + \\ + \node[draw]{2\hexsb{32}}; \& \& \node[draw]{b\hexsb{62}}; \& + \node (n2) {2}; \& \& \node[draw]{b\hexsb{62}}; + \\ + \node[draw]{f\hexsb{66}}; \& \& \node[draw]{a\hexsb{61}}; \& + \node[draw]{f\hexsb{66}}; \& \& \node[draw]{a\hexsb{61}}; + \\ + \node[draw]{o\hexsb{6f}}; \& \& \node[draw]{r\hexsb{72}}; \& + \node[draw]{o\hexsb{6f}}; \& \& \node[draw]{r\hexsb{72}}; + \\ + \node[draw]{o\hexsb{6f}}; \& \& \& + \node[draw]{o\hexsb{6f}}; \& \& + \\[10pt] + \& \node[font=\rmfamily]{\subfigfmt{a}}; \& \& + \& \node[font=\rmfamily]{\subfigfmt{b}}; \& + \\ +}; +\draw[ultra thick] (n1.north east) rectangle (n2.south west); +\end{tikzpicture}% +} +{% + \caption[Regular letter comparison vs letter-number + comparison]{Regular letter comparison vs letter-number comparison. + Comparing the strings \code{abc12foo} and \code{abc6bar}: + \subfigfmt{a} \optfmt{letter-case}; \subfigfmt{b} + \optfmt{letternumber-case}.}% +} +{fig:letternumber} +\end{figure} + +For example, suppose the first string is \code{abc12foo} +and the second string is \code{abc6bar}. +\Figureref{fig:letternumber}\subfigfmt{a} shows the regular letter +comparison using \csopt[letter-case]{sort}, where the subscript +indicates the hexadecimal character code. The first three characters +from each string are identical (\code{abc}). At this point there's +no difference detected, so the comparator moves on to the next +character, \code{1\hexsb{31}} for the first string and +\code{6\hexsb{36}} for the second string. Since \hex{31} is less than +\hex{36}, the first string (\code{abc12foo}) is considered less than the second +(\code{abc6bar}). + +With the letter-number comparison using +\csopt[letternumber-case]{sort}, the comparator starts in much the +same way. The first three characters from each string are still +identical, so the comparator moves on to the next character, +\code{1} for the first string and \code{6} for the second. +These are now both recognised as digits, so the comparator +looks ahead and reads in any following digits (if present). For the +first case, this is the sub-string \code{12} and, for the second +case, \code{6} (\figureref{fig:letternumber}\subfigfmt{b}). These +are both compared according to their integer representation $12 > +6$, so \code{abc12bar} is considered greater than \code{abc6foo} +(that is, \code{abc12bar} comes after \code{abc6foo}). + +The same result occurs for other numbering systems, for example if +the Basic Latin digits 1, 2 and 6 are replaced with the +corresponding Devanagari digits \devone, \devtwo\ and +\devsix. (But note that the letter comparisons will still be +based on their Unicode values not according to a particular locale. +This type of sort method is intended primarily for symbolic values, +such as chemical formulae, rather than for words or phrases.) + +Signed integers are also recognised, so \code{abc-12foo} is less +than \code{abc+6bar}, which is again different from the result +obtained with a straight letter comparator where the +character~\code{+} (\hex{2B}) +comes before the character~\code{-} (\hex{2D}). The sign must be followed by at +least one digit for it to be recognised as a number otherwise it's +treated as a punctuation character. + +If only one sub-string is numeric +then the \csopt{letter-number-rule} is used to determine the +result. Where both sub-strings are non-numeric, then the +\csopt{letter-number-punc-rule} setting is used to determine the result +according to the category of the characters, which may be one of the +following: +\begin{itemize} +\item white space: belongs to the Unicode \idx{separatorspace} +category. If both characters are white space, then they are compared +according to their Unicode values otherwise they are ordered according to +the \csopt{letter-number-punc-rule} setting. + +\item letter: belongs to one of the Unicode categories \idx{letteruppercase}, +\idx{letterlowercase}, \idx{lettertitlecase}, +\idx{lettermodifier} or \idx{letterother}. If both characters +are letters then, for sort method \optfmt{letternumber-\meta{modifier}}, +the characters are compared in the same way as the +corresponding \optfmt{letter-\meta{modifier}} sort method otherwise +they are ordered according to the +\csopt{letter-number-punc-rule} setting. + +\item punctuation: everything else. If both characters are +punctuation, then they are compared according to their Unicode value +otherwise they are ordered according to +the \csopt{letter-number-punc-rule} setting. +\end{itemize} +For simplicity, the actual sort value used during sorting isn't a +simple string but is converted into a list of objects that represent +one of: letter, integer, space or other (punctuation). This reduces +the amount of parsing of substrings that needs to be performed. + +The examples below show the ordering of the list: +\code{CH\textsubscript{2}O}, +\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}}, +\code{C\textsubscript{5}H\textsubscript{4}NCOOH}, +\code{CO}, \code{Cl}, +\code{Co}, \code{Co\textsubscript{2}O\textsubscript{3}}, +\code{Co\textsubscript{2}}, \code{CO\textsubscript{2}}, +\code{CoMoO\textsubscript{4}} and \code{CoCl\textsubscript{2}}, +for the setting +\csopt[between]{letter-number-rule}, where the subscripts are +the Unicode subscript characters. + +\begin{itemize} +\item \optfmt{letternumber-case}: case-sensitive +letter-number sort. Example: + +\code{CH\textsubscript{2}O}, +\code{CO}, +\code{CO\textsubscript{2}}, +\code{C\textsubscript{5}H\textsubscript{4}NCOOH}, +\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}}, +\code{Cl}, +\code{Co}, +\code{CoCl\textsubscript{2}}, +\code{CoMoO\textsubscript{4}}, +\code{Co\textsubscript{2}}, +\code{Co\textsubscript{2}O\textsubscript{3}}. + +(Order determined by: $\mathtt{H} < \mathtt{O} < 5 < 10 < \mathtt{l} < \mathtt{o}$.) + +\item \optfmt{letternumber-case-reverse}: reverse case-sensitive +letter-number sort. Example: + +\code{Co\textsubscript{2}O\textsubscript{3}}, +\code{Co\textsubscript{2}}, +\code{CoMoO\textsubscript{4}}, +\code{CoCl\textsubscript{2}}, +\code{Co}, +\code{Cl}, +\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}}, +\code{C\textsubscript{5}H\textsubscript{4}NCOOH}, +\code{CO\textsubscript{2}}, +\code{CO}, +\code{CH\textsubscript{2}O}. + +\item \optfmt{letternumber-nocase}: case-insensitive +letter-number sort. The sort value is first converted to lower +case. Note that \csopt[between]{letter-number-rule} doesn't make +sense in this context as there won't be any \idx!{uppercase} characters in +the sort value, so numbers will always come before letters. Example: + +\code{C\textsubscript{5}H\textsubscript{4}NCOOH}, +\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}}, +\code{CH\textsubscript{2}O}, +\code{Cl}, +\code{CO}, +\code{Co}, +\code{CO\textsubscript{2}}, +\code{Co\textsubscript{2}}, +\code{Co\textsubscript{2}O\textsubscript{3}}, +\code{CoCl\textsubscript{2}}, +\code{CoMoO\textsubscript{4}}. + +(Order determined by: $5 < 10 < \mathtt{h} < \mathtt{l} < \mathtt{o}$.) + +\item \optfmt{letternumber-nocase-reverse}: reverse case-insensitive +letter-number sort, so numbers will now always come after letters. Example: + +\code{CoMoO\textsubscript{4}}, +\code{CoCl\textsubscript{2}}, +\code{Co\textsubscript{2}O\textsubscript{3}}, +\code{Co\textsubscript{2}}, +\code{CO\textsubscript{2}}, +\code{Co}, +\code{CO}, +\code{Cl}, +\code{CH\textsubscript{2}O}, +\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}}, +\code{C\textsubscript{5}H\textsubscript{4}NCOOH}. + +\item \optfmt{letternumber-upperlower}: upper-lower +letter-number sort. This behaves slightly differently to +\optfmt{letter-upperlower} when used with \csopt[between]{letter-number-rule} +and has a more complicated rule that's determined by the character +following the number and implied numbers inserted between letters. +(There was a bug in earlier versions that has been corrected in v1.8 +so you may find a slightly different ordering when upgrading.) +Example: + +\code{CH\textsubscript{2}O}, +\code{C\textsubscript{5}H\textsubscript{4}NCOOH}, +\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}}, +\code{Cl}, +\code{CO}, +\code{CO\textsubscript{2}}, +\code{Co}, +\code{Co\textsubscript{2}}, +\code{CoCl\textsubscript{2}}, +\code{CoMoO\textsubscript{4}}, +\code{Co\textsubscript{2}O\textsubscript{3}}. + +(Order determined by: $\mathtt{H} < 5\mathtt{H} < 10\mathtt{H} < +\mathtt{l} < \mathtt{O} < \mathtt{o}$, and for the terms starting +with \code{CO} or \code{Co}: 2 comes after null and $\mathtt{C} < +\mathtt{M} < 2\mathtt{O}$.) + +Compare this with \csopt[before letter]{letter-number-rule} which +results in the order: + +\code{C\textsubscript{5}H\textsubscript{4}NCOOH}, +\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}}, +\code{CH\textsubscript{2}O}, +\code{Cl}, +\code{CO}, +\code{CO\textsubscript{2}}, +\code{Co}, +\code{Co\textsubscript{2}}, +\code{Co\textsubscript{2}O\textsubscript{3}}, +\code{CoCl\textsubscript{2}}, +\code{CoMoO\textsubscript{4}}. + +\item \optfmt{letternumber-upperlower-reverse}: reverse upper-lower +letter-number sort. Example (with \csopt[between]{letter-number-rule}): + +\code{Co\textsubscript{2}O\textsubscript{3}}, +\code{CoMoO\textsubscript{4}}, +\code{CoCl\textsubscript{2}}, +\code{Co\textsubscript{2}}, +\code{Co}, +\code{CO\textsubscript{2}}, +\code{CO}, +\code{Cl}, +\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}}, +\code{C\textsubscript{5}H\textsubscript{4}NCOOH}, +\code{CH\textsubscript{2}O}. + +Compare this with \csopt[before letter]{letter-number-rule} which +results in the order: + +\code{CoMoO\textsubscript{4}}, +\code{CoCl\textsubscript{2}}, +\code{Co\textsubscript{2}O\textsubscript{3}}, +\code{Co\textsubscript{2}}, +\code{Co}, +\code{CO\textsubscript{2}}, +\code{CO}, +\code{Cl}, +\code{CH\textsubscript{2}O}, +\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}}, +\code{C\textsubscript{5}H\textsubscript{4}NCOOH}. + +Remember that the associated settings are reversed +well. So \csopt[before letter]{letter-number-rule} +results in numbers \emph{after} letters. + +\item \optfmt{letternumber-lowerupper}: lower-upper letter-number +sort. As with the upper-lower option, this behaves slightly differently to +\optfmt{letter-lowerupper} when used with \csopt[between]{letter-number-rule} +and has a more complicated rule. +Example: + +\code{CH\textsubscript{2}O}, +\code{C\textsubscript{5}H\textsubscript{4}NCOOH}, +\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}}, +\code{Cl}, +\code{Co}, +\code{Co\textsubscript{2}}, +\code{CoCl\textsubscript{2}}, +\code{CoMoO\textsubscript{4}}, +\code{Co\textsubscript{2}O\textsubscript{3}}, +\code{CO}, +\code{CO\textsubscript{2}}. + +Compare this with \csopt[before letter]{letter-number-rule} which +results in the order: + +\code{C\textsubscript{5}H\textsubscript{4}NCOOH}, +\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}}, +\code{CH\textsubscript{2}O}, +\code{Cl}, +\code{Co}, +\code{Co\textsubscript{2}}, +\code{Co\textsubscript{2}O\textsubscript{3}}, +\code{CoCl\textsubscript{2}}, +\code{CoMoO\textsubscript{4}}, +\code{CO}, +\code{CO\textsubscript{2}}. + +\item \optfmt{letternumber-lowerupper-reverse}: reverse lower-upper +letter-number sort. Example (with \csopt[between]{letter-number-rule}): + +\code{CO\textsubscript{2}}, +\code{CO}, +\code{Co\textsubscript{2}O\textsubscript{3}}, +\code{CoMoO\textsubscript{4}}, +\code{CoCl\textsubscript{2}}, +\code{Co\textsubscript{2}}, +\code{Co}, +\code{Cl}, +\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}}, +\code{C\textsubscript{5}H\textsubscript{4}NCOOH}, +\code{CH\textsubscript{2}O}. + +\end{itemize} + +\subsubsection{Numerical} +\label{sec:numerical} + +The sort methods listed in \tableref{tab:sortoptionsnumerical} +use numeric comparisons. The sort value is expected to +be a numeric value. If it can't be parsed then it's treated as 0 +(and a warning will be written to the transcript). +These all recognise the digits in the Unicode \qt{Number, +Decimal Digit} category but, unlike the hybrid letter-number +comparators above, they don't recognise the superscript or subscript +digits. The \qt{non-locale} in some of the descriptions below +indicates that the method doesn't recognise locale-sensitive +formatting, such as group separators. +\begin{itemize} +\item \optfmt{integer}: integer sort. This is for non-locale integer sort +values. + +\item \optfmt{integer-reverse}: as above but reverses the order. + +\item \optfmt{hex}: hexadecimal integer sort. This is for non-locale +hexadecimal sort values. + +\item \optfmt{hex-reverse}: as above but reverses the order. + +\item \optfmt{octal}: octal integer sort. This is for non-locale +octal sort values. + +\item \optfmt{octal-reverse}: as above but reverses the order. + +\item \optfmt{binary}: binary integer sort. This is for non-locale binary sort +values. + +\item \optfmt{binary-reverse}: as above but reverses the order. + +\item \optfmt{float}: single-precision sort. This is for non-locale +decimal sort values. + +\item \optfmt{float-reverse}: as above but reverses the order. + +\item \optfmt{double}: double-precision sort. This is for non-locale +decimal sort values. + +\item \optfmt{float-reverse}: as above but reverses the order. + +\item \optfmt{numeric}: locale-sensitive numeric sort. Use +\csopt{numeric-locale} to set the locale. + +\item \optfmt{numeric-reverse}: as above but reverses the order. + +\item \optfmt{currency}: locale-sensitive currency sort. Use +\csopt{numeric-locale} to set the locale. + +\item \optfmt{currency-reverse}: as above but reverses the order. + +\item \optfmt{percent}: locale-sensitive percent sort. Use +\csopt{numeric-locale} to set the locale. + +\item \optfmt{percent-reverse}: as above but reverses the order. + +\item \optfmt{numberformat}: locale-sensitive custom numeric sort. Use +\csopt{numeric-locale} to set the locale and +\csopt{numeric-sort-pattern} to set the number pattern. + +\item \optfmt{numberformat-reverse}: as above but reverses the order. + +\end{itemize} + +In general, it doesn't make much sense to have hierarchical entries +that need to be sorted by a number, but it is possible as long as each +level uses the same type of numbering. + +\subsubsection{Date-Time} + +The sort methods listed in \tableref{tab:sortoptionsdatetime} +are for dates and times. Use \csopt{date-sort-format} +and \csopt{date-sort-locale} to specify the date format and locale. +\begin{itemize} +\item \optfmt{date}: sort dates. + +\item \optfmt{date-reverse}: as above but reverses the order. + +\item \optfmt{datetime}: sort date and time information. + +\item \optfmt{datetime-reverse}: as above but reverses the order. + +\item \optfmt{time}: sort times. + +\item \optfmt{time-reverse}: as above but reverses the order. + +\end{itemize} + +If the field you want to sort by contains a date then the +simplest way to sort is to ensure the date is in ISO format +and then just use a letter sort. However it may be that +the date is in the format particular to your locale or you have a +mix of \era{AD} and \era{BC}. In which +case you can use one of the date/time sort options (such as +\csopt[date]{sort} or \csopt[date-reverse]{sort}). The locale +is assumed to be your default locale (as given by the \idx{JVM}) +but if you are using a different locale this can +be set with \csopt{date-sort-locale}. The pattern is assumed +to be the default for that locale but you can change this with +\csopt{date-sort-format}. If you provide your +own custom pattern you must make sure that it matches the selected +\optfmt{sort} option. + +Take care if you switch from using the \idx{JRE} to the \idx{CLDR} + \idx{localeprovider} as you may find the default pattern changes. + +The locale and pattern information is used by \bibgls\ to parse the +field. If the field value can't be parsed then \bibgls\ will issue +a warning and assume the current date (or time). + +The actual sort value that's used by the comparator is numeric. In +the case of the time-based \csopt[datetime]{sort} and +\csopt[time]{sort} (or their \optfmt{-reverse} versions), this value +is the number of milliseconds since 1st~January, 1970. In the case +of \csopt[date]{sort} (or \csopt[date-reverse]{sort}), this value is +obtained from $a(y\times10000 + m\times100 + d)$ where $y$ is the +year, $m$ is the month number, $d$ is the day of month number, and +$a$ is an integer representation of the era ($-1$ for \era{BC} and +$+1$ for \era{AD}). + +Unlike the numeric sort methods (such as \csopt[integer]{sort}) +the date-time sort methods set the \field{sort} field to a value +that can be more easily parsed within the document and that should +mostly achieve the same ordering if a letter comparator were to be used +with it (except for \era{BC} dates, where the order needs to be +reversed). This has the by-product of providing a field that +you can access within the document that can be more easily parsed by +\LaTeX. + +In general, it doesn't make much sense to have hierarchical entries +that need to be sorted by date, but it is possible as long as each +level uses the same date format. + +For example, suppose my \ext{bib} file contains: +\begin{codeenv} +\atentry{entry}\marg{journalentry, + \field{name}=\marg{10 Jan 2017}, + \field{description}=\marg{an interesting journal entry} +} +\end{codeenv} +The \field{name} field uses an abbreviated UK date format. +If all my other entries also use this format in the \field{name} +then I can sort them chronologically: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{data in entries.bib} + \csopt[date]{sort}, + \csopt[en-GB]{date-sort-locale}, + \csopt[medium]{date-sort-format} +} +\end{codeenv} +(The medium format is actually the default for this locale, +and the locale matches my system locale, so I could omit +both \csopt{date-sort-locale} and \csopt{date-sort-format}.) + +If \longarg{verbose} mode is on, the transcript will show +the label, sort value and numeric value for each entry. +In this case, the information is: +\begin{verbatim} +journalentry -> '+1 2017-01-10' [20170110] +\end{verbatim} +The first value is the label (\code{journalentry}), the second +value is assigned to the \field{sort} field +(\code{+1 2017-01-10}) and the number in square brackets +is the actual numeric value used by the comparator. The signed +number at the start of the sort field \code{+1} is the numeric +representation of the era as used for the $a$ variable in the +computation of the numeric value (as described earlier). + +If I change the format to \csopt[short]{date-sort-format}, +then the date can't be parsed correctly and \bibgls\ will +issue the following warning: +\begin{verbatim} +Warning: Can't parse sort value '10 Jan 2017' for 'journalentry' +(pattern: 'dd/MM/yyyy') +\end{verbatim} +This shows the value that \bibgls\ is trying to +parse (\code{10 Jan 2017}) for the entry identified by +the given label (\code{journalentry}). The pattern \bibgls\ +expects is also given (\code{dd/MM/yyyy}). + +\optsection{shuffle} + +Automatically sets \csopt[random]{sort} and \csopt{flatten}. +The value \meta{seed} may be omitted. If present, it should +be an integer used as a seed for the random number generator. + +\optsection{sort-field} + +The \csopt{sort-field} key indicates which field provides the sort +value. The \meta{field} must be a recognised field name or you +may use \csopt[id]{sort-field} to sort according to the label. +The default value is the \field{sort} field (which is typically +inferred rather than explicitly set). + +Example: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries-terms]{src},\comment{data in entries-terms.bib} + \csopt[category]{sort-field},\comment{sort by 'category' field} + \csopt[letter-case]{sort}\comment{case-sensitive letter sort} +} +\end{codeenv} +This sorts the entries according to the \field{category} field using +a case-sensitive letter comparison. + +If an entry is missing a value for \meta{field}, then the value of +the fallback field will be used instead. If \csopt{missing-sort-fallback} is +set, then that's used as the fallback, otherwise it depends on the +entry type. +If no fallback field can be found, the entry's label will be used. + +For the specific case with the default \csopt[sort]{sort-field} +setting, the fallback for the \field{sort} field is governed not +only by the entry type but also by some associated settings: + +\begin{itemize} +\item If the entry is defined using \atentry{entry} (or a dual form +that acts like \atentry{entry}), then if the \field{sort} field is +missing the value is obtained from the field identified by +\csopt{entry-sort-fallback}. If that field is also missing then +that field's fallback is used. + +\item For the index entry types like \atentry{index} or +\atentry{indexplural}, then if the \field{sort} field is missing the +value is obtained from the \field{name} field. If that field is also +missing, then the value is obtained from the particular entry type's +fallback for the \field{name} field. (For example, the entry's label +for \atentry{index} or the \field{plural} field for +\atentry{indexplural}.) + +\item If the entry is defined with an abbreviation type (for +example, \atentry{abbreviation} or \atentry{acronym}) then if the +\field{sort} field is missing, \bibgls\ will fallback on the field +given by \csopt{abbreviation-sort-fallback}. + +\item The symbol-like entry types fallback on the field given by +\csopt{symbol-sort-fallback} if the \field{sort} field is missing. + +\item Entries defined using \atentry{bibtexentry} fallback on the field +given by \csopt{bibtexentry-sort-fallback}, which defaults to the +\field{name} field. Note that this only applies to the main entry. +The spawned \atentry{contributor} entries behave like +\atentry{index}. + +\end{itemize} +Use \csopt{dual-sort-field} when sorting dual entries. + +\optsection{missing-sort-fallback} + +With \csopt[\meta{sort-field}]{sort-field}, if the value of the field +identified by \meta{sort-field} is missing, then \bibgls\ behaves as +follows: +\begin{enumerate} +\item If \csopt[\meta{fallback-field}]{missing-sort-fallback} is set, then +\bibgls\ will fallback on the value provided by the field +\meta{fallback-field}. If \meta{fallback-field} is +missing, then \bibgls\ will query the entry type's fallback for +\meta{fallback-field} (not for \meta{sort-field}). +\item If the entry type has a fallback rule for \meta{sort-field}, +then that rule is used. When \csopt[sort]{sort-field} this means: +\begin{itemize} +\item If the entry was defined using one of the index types (such as +\atentry{index}), then \bibgls\ will fallback on the \field{name} +field. + +\item If the entry was defined using the \atentry{entry} type (or a +dual form that acts like \atentry{entry}), then \bibgls\ will +fallback on the field given by \csopt{entry-sort-fallback}. + +\item If the entry was defined using +one of the symbol types (such as \atentry{symbol}), then \bibgls\ +will fallback on the field given by \csopt{symbol-sort-fallback}. + +\item If the entry was defined using +one of the abbreviation types (such as \atentry{abbreviation}), then \bibgls\ +will fallback on the field given by +\csopt{abbreviation-sort-fallback}. + +\item If the entry was defined using \atentry{bibtexentry} (but not +the spawned \atentry{contributor} entries), then \bibgls\ will +fallback on the field given by +\csopt{bibtexentry-sort-fallback}. +\end{itemize} +If \meta{sort-field} is not \field{sort}, then there may not be a +fallback, in which case the next condition applies: +\item Otherwise the sort value will be set to the entry label and \bibgls\ +will issue a warning. +\end{enumerate} +The default setting is \csopt[\empty]{missing-sort-fallback}, which +means that step~1 above is omitted. + +Use \csopt{dual-missing-sort-fallback} when sorting dual entries +separately from primaries, and use +\csopt{secondary-missing-sort-fallback} for \csopt{secondary} +sorting. + +\optsection{entry-sort-fallback} + +The regular entry types (such as \atentry{entry} and +\atentry{dualentry}) will, by default, fallback on the \field{name} +field if the \field{sort} field is missing (assuming +\csopt[sort]{sort-field}). If you prefer to +fallback on a different field, then you can use this option to +specify the field. +Note that \csopt{missing-sort-fallback} overrides this setting. + +This setting doesn't affect the index type of entries, such as +\atentry{index} or \atentry{indexplural}. This is useful if your +glossary contains homographs (terms with the same spelling) which +can't be distinguished by the sort comparators. For example, suppose +my file \filefmt{entries.bib} contains: +\begin{codeenv} +\atentry{index}\marg{pagelist, + \field{name}=\marg{page list}, + \field{description}=\marg{a list of individual pages or page ranges} +} +\strut +\atentry{index}\marg{glossary} +\strut +\atentry{entry}\marg{glossarylist, + \field{parent}=\marg{glossary}, + \field{description}={list of technical words} +} +\strut +\atentry{entry}\marg{glosscol, + \field{parent}=\marg{glossary}, + \field{description}=\marg{collection of glosses} +} +\end{codeenv} +Now first consider a document that uses the default settings: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\oarg{\styopt{record},\styopt{subentrycounter},\styopt[\glostyle{treenoname}]{style}}\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}} +\strut +\cmd{begin}\marg{document} +A test document describing \cs{glspl}\marg{pagelist} and +\cs{gls}\marg{glosscol} (collection) vs \cs{gls}\marg{glossarylist} (list). +\strut +\cs{printunsrtglossary} +\cmd{end}\marg{document} +\end{codeenv} +The default behaviour for \atentry{entry} if the \field{sort} field +is missing is to fallback on the \field{name} field. If the +\field{name} field is missing (as with \code{glossarylist} and +\code{glosscol}), then the value is obtained from the +\field{name} field from the parent entry. The parent entry for these +homographs is the \code{glossary} entry, which was defined with +\atentry{index} and doesn't have the \field{name} field. For the +\atentry{index} entries, if \field{name} is missing the value is +obtained from the label. + +Therefore both \code{glossarylist} and \code{glosscol} end +up with the same sort value: \code{glossary}. This triggers a +message in verbose mode (\longarg{verbose}) which can be found +in the transcript file: +\begin{verbatim} +Identical sort values for 'glossarylist' and 'glosscol' +Falling back on ID +\end{verbatim} +So the actual sort values used are \qt{glossarylist} and +\qt{glosscol}. This puts the \code{glossarylist} entry +before the \code{glosscol} entry. + +Now suppose a minor modification is made to the document: +\begin{codeenv} +\gls{GlsXtrLoadResources} + \oarg{ + \csopt[entries]{src}, + \csopt[description]{entry-sort-fallback} + } +\end{codeenv} +This means that when the sort function fails to find the +\field{sort} field for the terms defined with \atentry{entry}, it +will fallback on the \field{description} field. This doesn't affect +the terms defined with \atentry{index}, which still fallback on the +\field{name} field. This time there's no message in the transcript +file and the \code{glosscol} entry now comes before the +\code{glossarylist} entry. + +\begin{important} +The \csopt{entry-sort-fallback} setting is only used when \bibgls\ +tries to access the \field{sort} field for a term defined with +\atentry{entry} and finds that the field hasn't been set. This means +that this setting has no effect if you explicitly set the \field{sort} +field or if you change the field used for sorting +(\csopt{sort-field}). +\end{important} + +\optsection{abbreviation-sort-fallback} + +The entry types that define abbreviations (such as +\atentry{abbreviation} and \atentry{acronym}) will, by default, +fallback on the \field{short} field if the \field{sort} field is +missing (assuming \csopt[sort]{sort-field}). If you prefer to +fallback on a different field, then you can use this option to +specify the field. For example, +\csopt[long]{abbreviation-sort-fallback}. Note that if you use +\csopt[name]{sort-field}, then the fallback field will be given by +\csopt{abbreviation-name-fallback} if the \field{name} field is +omitted. The \meta{field} value must be a known field label. + +Note that \csopt{missing-sort-fallback} overrides this setting. + +\begin{important} +The \csopt{abbreviation-sort-fallback} setting is only used when \bibgls\ +tries to access the \field{sort} field for an abbreviation and finds +that the field hasn't been set. This means that this setting has no effect +if you explicitly set the \field{sort} field or if you change the field used +for sorting (\csopt{sort-field}). +\end{important} + +\optsection{symbol-sort-fallback} + +The entry types that define symbols (such as \atentry{symbol} and +\atentry{number}) will, by default, fallback on the label if the +\field{sort} field is missing (assuming the default +\csopt[sort]{sort-field}). If you prefer to fallback on a different +field, then you can use this option to specify the field. For +example, \csopt[name]{symbol-sort-fallback}. The \meta{field} value +must be a known field label. + +Note that \csopt{missing-sort-fallback} overrides this setting. + +\begin{important} +The \csopt{symbol-sort-fallback} setting is only used when \bibgls\ +tries to access the \field{sort} field for a symbol and finds +that the field hasn't been set. This means that this setting has no effect +if you explicitly set the \field{sort} field or if you change the field used +for sorting (\csopt{sort-field}). +\end{important} + +\optsection{bibtexentry-sort-fallback} + +The main \atentry{bibtexentry} entry types will, by default, +fallback on the \field{name} if the +\field{sort} field is missing (assuming the default +\csopt[sort]{sort-field}). If you prefer to fallback on a different +field, then you can use this option to specify the field. + +Note that \csopt{missing-sort-fallback} overrides this setting. + +\begin{important} +The \csopt{bibtexentry-sort-fallback} setting is only used when +\bibgls\ tries to access the \field{sort} field for a main entry +defined with \atentry{bibtexentry} and finds that the field hasn't +been set. This means that this setting has no effect if you +explicitly set the \field{sort} field or if you change the field used for +sorting (\csopt{sort-field}). +\end{important} + +\optsection{trim-sort} + +If the interpreter is used to determine the sort value, this setting +governs whether or not the interpreter should trim leading and +trailing spaces. The default setting is \csopt[true]{trim-sort}. + +This option automatically sets \csopt[\meta{boolean}]{dual-trim-sort} +and \csopt[\meta{boolean}]{secondary-trim-sort}. + +\optsection{sort-replace} + +This option may be used to perform \idx{regex} substitutions +on the sort value and has the same syntax as \csopt{labelify-replace}. +The value is required for this key but may be empty, which indicates +that the setting is switched off. + +This action is done after the interpreter parses the +sort value (if applicable) and before \csopt{sort-number-pad} (if +applicable). For example, suppose the sort value is: +\begin{codeenv} +\cs{ensuremath}\marg{\ics{approx} 3.14} +\end{codeenv} +then the interpreter will convert this to $\mathtt{\approx}$\texttt{3.14} but: +\begin{codeenv} +\csopt[\marg{\cs{glshex}2248}\marg{}]{sort-replace} +\end{codeenv} +can be used to strip the $\approx$ symbol (\hex{2248}) so that the value can +now be parsed as a number if \csopt[double]{sort} has been used. + +Use \csopt{dual-sort-replace} for dual +and \csopt{secondary-sort-replace} for secondary sort methods. + +\optsection{sort-rule} + +If the \csopt[custom]{sort} option is used, the sort rule must be +provided with \optfmt{sort-rule}. If \csopt{sort} is not set to +\optfmt{custom}, the \optfmt{sort-rule} setting will be ignored. +This setting uses Java's +\href{http://docs.oracle.com/javase/8/docs/api/java/text/RuleBasedCollator.html}{RuleBasedCollator} +class~\cite{rulebasedcollator}, and the rule syntax needs to conform +to that format. + +Remember that the options will be expanded as they are written to +the \iext{aux} file, so be careful of any special characters that +occur in the rule. For the special characters \idx{param} +\idx{commentchar} \idx{sbchar} \idx{colsep} \idx{bgroupchar} and +\idx{egroupchar} you can use \ics{cs.hash}, \ics{cs.percent}, +\ics{cs.underscore}, \ics{cs.amp}, \ics{cs.openbrace} and +\ics{cs.closebrace}. These will be written to the \ext{aux} file +with the leading backslash, but \bibgls\ will remove it for this +resource option. Remember that the \styfmt{glossaries} package +provides \ics{glsbackslash} and \ics{glstildechar} which can be used +to produce a literal backslash (\idx{backslashchar}) and tilde +(\idx{tildechar}). + +You can also +use \stringu\meta{hex} (where \meta{hex} is a hexadecimal +code) to represent a Unicode character. For example: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[custom]{sort}, + \csopt[< a,A < b,B < c,C < ch,Ch,CH < d,D + < dd,Dd,DD < e,E < f,F < ff,Ff,FF + < g,G < ng,Ng,NG < h,H < ij,Ij,IJ + < i,I < j,J < k,K < l,L < ll,Ll,LL < m,M + < n,N < o,O < p,P < ph,Ph,PH < q,Q < r,R < rh,Rh,RH + < s,S < t,T < th,Th,TH < u,U < v,V < w,W < x,X < y,Y < z,Z + < \stringu00E6,\stringu00C6]{sort-rule} +} +\end{codeenv} +It's best to use \ics{cs.string} rather than \ics{protect} to avoid +unwanted spaces interfering with \meta{hex}. Note that +\sty{glossaries-extra} v1.21+ provides\footnote{The command +definition was moved to \isty{glossaries-extra-bib2gls} from version +1.27 since it's only needed with \bibgls.}\ \ics{glshex} +which just does \stringu\ so you can do +\code{\ics{glshex} 00E6} instead of \code{\stringu00E6}. +This is only one character different, but you can redefine +\ics{glsxtrresourceinit} to locally set \ics{u} to \ics{glshex} while +the protected write is performed. For example: +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{glsxtrresourceinit}}\marg{\cmd{let}\cmd{u}\cs{glshex}} +\end{codeenv} +Then you can just do \code{\csfmt{u}00E6} instead of \code{\stringu00E6}. + +The \isty{glossaries-extra-bib2gls} package (which is automatically loaded by +the \styopt{record} option) provides some commands for common rule blocks +that may be used in the construction of custom rules. For example: +\begin{codeenv} +\csopt[\ics{glsxtrcontrolrules} + ;\ics{glsxtrspacerules} + ;\ics{glsxtrnonprintablerules} + ;\ics{glsxtrcombiningdiacriticrules} + ,\ics{glsxtrhyphenrules} + <\ics{glsxtrgeneralpuncrules} + <\ics{glsxtrdigitrules} + <\ics{glsxtrfractionrules} + <\ics{glsxtrMathItalicGreekIrules} + <\ics{glsxtrGeneralLatinIVrules} + <\ics{glsxtrLatinAA} + <\ics{glsxtrLatinOslash} +]{sort-rule} +\end{codeenv} +This places the Greek maths symbols (such as \ics{alpha}) before the +Latin block. See the \sty{glossaries-extra} documentation for +further details of these commands. + +You might find it convenient to provide similar commands in a +package for rules you may often need. For example, suppose I have a +package called, say, \styfmt{mapsymbols} for providing map symbols: +\begin{codeenv} +\cmd{NeedsTeXFormat}\marg{LaTeX2e} +\cmd{ProvidesPackage}\marg{mapsymbols} +\comment{some package or font loading stuff here to provide} +\comment{the appropriate symbols} +\cmd{newcommand}\marg{\cmd{Stadium}}\marg{\ldots} +\cmd{newcommand}\marg{\cmd{Battlefield}}\marg{\ldots} +\cmd{newcommand}\marg{\cmd{Harbour}}\marg{\ldots} +\comment{etc} +\strut +\comment{Provide a rule block:} +\cmd{newcommand}\marg{\cmd{MapSymbolOrder}}\marg{\comment{} + \cs{glshex} 2694 \comment{crossed-swords 0x2694} + < \cs{glshex} 2693 \comment{anchor 0x2693} + < \cs{glshex} 26BD \comment{football 0x26BD} +} +\end{codeenv} +In addition to \filefmt{mapsymbols.sty}, I also need to create +\filefmt{mapsymbols.bib} to provide the appropriate definitions for +\bibgls: +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cs{glsxtrprovidecommand}\marg{\cmd{Harbour}}\marg{\icharhex{2693}} +\cs{glsxtrprovidecommand}\marg{\cmd{Battlefield}}\marg{\charhex{2694}} +\cs{glsxtrprovidecommand}\marg{\cmd{Stadium}}\marg{\charhex{26BD}}}} +\end{codeenv} +The use of \ics{glsxtrprovidecommand} will override any previous +definitions of these commands in \bibgls's interpreter but will act +like \ics{providecommand} within the document, and so won't +interfere with the commands defined in \filefmt{mapsymbols.sty}. +Now I can just do: +\begin{codeenv} +\cmd{usepackage}\marg{mapsymbols}\comment{my custom package} +\cmd{usepackage}[\styopt{record}]\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[mapsymbols,\comment{<--- my custom mapsymbols.bib} + entries\comment{data in entries.bib} + ]{src}, + \csopt[custom]{sort}, + \csopt[\cs{glsxtrcontrolrules} + ;\cs{glsxtrspacerules} + ;\cs{glsxtrnonprintablerules} + ;\cs{glsxtrcombiningdiacriticrules} + ,\cs{glsxtrhyphenrules} + <\cs{glsxtrgeneralpuncrules} + <\cs{glsxtrdigitrules} + <\cs{glsxtrfractionrules} + <\cmd{MapSymbolOrder} \comment{<--- custom map symbols} + <\cs{glsxtrMathItalicGreekIrules} + <\ics{glsxtrGeneralLatinIrules} + ]{sort-rule} +} +\end{codeenv} + +An alternative to providing \filefmt{mapsymbols.bib} is to provide a +custom package just for \bibgls' use. For example, +\filefmt{mapsymbols-bib2gls.sty}: +\begin{codeenv} +\comment{Provided for \bibgls\ only.} +\comment{Use \cmd{usepackage}\marg{mapsymbols} in the document.} +\cmd{NeedsTeXFormat}\marg{LaTeX2e} +\cmd{ProvidesPackage}\marg{mapsymbols-bib2gls} +\cs{glsxtrprovidecommand}\marg{\cmd{Harbour}}\marg{\charhex{2693}} +\cs{glsxtrprovidecommand}\marg{\cmd{Battlefield}}\marg{\charhex{2694}} +\cs{glsxtrprovidecommand}\marg{\cmd{Stadium}}\marg{\charhex{26BD}} +\cmd{endinput} +\end{codeenv} +and instruct \bibgls\ to parse it with +\code{\longarg{custom-packages} mapsymbols-bib2gls} (and use +\filefmt{mapsymbols.sty} in the document). Remember that \bibgls\ +isn't a \TeX\ engine so make sure to only use simple commands in +this file. + +\optsection{break-at} + +This option automatically implements +\csopt[\meta{option}]{dual-break-at} and +\csopt[\meta{option}]{secondary-break-at}. + +The alphabet sort options (\tableref{tab:sortoptionsrule}) typically +list non-letter characters before alphabetical characters and spaces +are quite often in the ignored set. This means that the alphabet +sort options are naturally in a letter order, similar to +\idx{xindy}['s] \code{ord/letorder} module. (This isn't the same as +\csopt[letter-nocase]{sort}, which just sorts according to the +Unicode value not according to a particular alphabet.) + +In order to replicate \idx!{makeindex} and \idx!{xindy}['s] default word +order, \bibgls\ splits up the sort value at word boundaries and +inserts a marker (identified by \csopt{break-marker}). +For example, if the sort value is \qt{sea lion} then it's actually +converted to \verb"sea|lion|" whereas \qt{sea} becomes \verb"sea|" +and \qt{seal} becomes \verb"seal|". The default marker is \verb"|" +which is commonly placed in collation rules before digits but +after the ignored characters, such as spaces and hyphens. + +Note that this action removes non-letters, so for example, +if the sort value is \verb"# (parameter)" then it will be converted +to \verb"parameter|" (hash, space and parentheses removed). +If you only want to break at spaces (optionally following a comma) +use the following instead: +\begin{codeenv} + \csopt[none]{break-at}, + \csopt[\marg{,? +}\marg{|}]{sort-replace} +\end{codeenv} + +You can change the construction of the break points with +\csopt[\meta{option}]{break-at} where \meta{option} may be one of: +\begin{itemize} +\item \optfmt{word}: break at word boundaries (default). +Note that what constitutes a word varies +according to the locale but usually anything that's not alphanumeric +will designate a word-boundary. The characters between words are +discarded. +For example, the sort value \qt{Tom, Dick, and Harry} becomes +\verb"Tom|Dick|and|Harry", which has discarded the comma and space +characters. +\item \optfmt{character}: break after each character. +\item \optfmt{sentence}: break after each sentence. +\item \optfmt{upper-notlower}: break after any \idx{uppercase} character +that's not followed by a \idx{lowercase} character. For example, +\qt{MathML} becomes \verb"MathM|L|" and \qt{W3C} becomes +\verb"W|3C|". +\item \optfmt{upper-upper}: break after any \idx{uppercase} character +that's followed by an \idx{uppercase} character. +\item \optfmt{upper-notlower-word}: first applies break-points +according to \optfmt{upper-notlower} and then according to +\optfmt{word}. +\item \optfmt{upper-upper-word}: first applies break-points +according to \optfmt{upper-upper} and then according to +\optfmt{word}. +\item \optfmt{none}: don't create break points. Use this option to +emulate \idx{makeindex} or \idx{xindy}'s letter ordering, or combine +with \csopt{sort-replace} to insert custom break points. +\end{itemize} + +This option is ignored when used with the non-alphabetic +\csopt{sort} options. You can find the break points in the +\field{sort} field for the entry's definition in the \ext{glstex} +file (which is provided for information rather than for use in the +document). Alternatively, use the \longarg{debug} switch to show +the break points in the transcript. (This will also show the +collation rule.) + +\optsection{break-marker} + +This option automatically implements the dual and secondary settings +\csopt[\meta{marker}]{dual-break-marker} and +\csopt[\meta{marker}]{secondary-break-marker}. + +The break marker can be changed using +\csopt[\meta{marker}]{break-marker}, where \meta{marker} is +the character to use. For example, \csopt[-]{break-marker} will use a +hyphen. The marker may be empty, which effectively strips the +inter-word punctuation. For example, with +\csopt[\empty]{break-marker}, \qt{Tom, Dick, and Harry} becomes +\code{TomDickandHarry} and \qt{sea lion} simply becomes +\code{sealion}. If \meta{marker} is omitted, +\csopt[\empty]{break-marker} is assumed. + +\optsection{sort-number-pad} + +This option automatically implements the dual and secondary settings +\csopt[\meta{number}]{dual-sort-number-pad}, +\csopt[\meta{number}]{secondary-sort-number-pad}. + +If \meta{number} is greater than 1, any integer sub-strings found +in the sort value will be zero-padded up to this value. Since the +\code{-} character is often ignored by rule-based sort methods, +any signs found will be replaced with the markers given by +\csopt{sort-pad-plus} and \csopt{sort-pad-minus}, which should be +chosen to ensure that negative numbers are ordered before positive +numbers (if this is desired). An unsigned number will have the +\csopt{sort-pad-plus} marker inserted before it. The default value +is \csopt[0]{sort-number-pad}, which doesn't implement any padding. + +If you use this with a locale sort method, it's best to also set +\csopt[none]{break-at}, as the default word boundary break points +will likely be confused by a mix of alphanumerics. + +\optsection{sort-pad-plus} + +This option automatically implements the dual and secondary settings +\csopt[\meta{marker}]{dual-sort-pad-plus}, +\csopt[\meta{marker}]{secondary-sort-pad-plus}. + +This option only has an effect when used with +\csopt[\meta{number}]{sort-number-pad} where \meta{number} is +greater than 1. Positive numbers will have their sign replaced with +\meta{marker}. The default setting is \csopt[>]{sort-pad-plus}. + +\optsection{sort-pad-minus} + +This option automatically implements the dual and secondary settings +\csopt[\meta{marker}]{dual-sort-pad-minus}, +\csopt[\meta{marker}]{secondary-sort-pad-minus}. + +This option only has an effect when used with +\csopt[\meta{number}]{sort-number-pad} where \meta{number} is +greater than 1. Negative numbers will have their sign replaced with +\meta{marker}. The default setting is \csopt[<]{sort-pad-plus}. + +\optsection{identical-sort-action} + +This option automatically implements the dual and secondary settings +\csopt[\meta{value}]{dual-identical-sort-action} and +\csopt[\meta{value}]{secondary-identical-sort-action}. + +This option determines what the comparator should do if +two entries at the same hierarchical level are considered +equal. The \meta{value} may be one of: +\begin{itemize} +\item\optfmt{none}: don't take any further action if sort values are +identical; +\item\optfmt{id}: if sort values are identical, compare +the entry labels; +\item\optfmt{original id}: if sort values are identical, compare the +original unprefixed entry labels (as given in the \ext{bib} file); +\item\meta{field}: if sort values are identical, compare +the values from the given \meta{field}. +\end{itemize} +In each case (other than \csopt[none]{identical-sort-action}) a +simple case-sensitive string comparison is used. If \meta{value} +isn't a recognised keyword or valid field an error will occur. The +default setting is \csopt[id]{identical-sort-action}. If you're +using one of the sort rules listed in \tableref{tab:sortoptionsrule} +and you also want a locale-sensitive sort used on the fallback, then +you need to use \csopt{sort-suffix} instead. + +\bibgls\ allows duplicate sort values, but this can cause a problem +for hierarchical entries where parent entries with duplicate sort +fields are clumped together and their children follow. To prevent +this from happening, the \csopt[id]{identical-sort-action} +setting will fallback on comparing the labels. Since all labels +must be unique, this means comparisons between two different entries +are all either strictly higher or strictly lower. + +This action occurs after any suffixes have been appended through +\csopt{sort-suffix}. + +\optsection{sort-suffix} + +This option automatically implements the dual and secondary settings +\csopt[\meta{value}]{dual-sort-suffix} and +\csopt[\meta{value}]{secondary-sort-suffix}. +The value may be one of: +\begin{itemize} +\item\optfmt{none}: don't append a suffix to any \field{sort} value; +\item\optfmt{non-unique}: append a numeric suffix to non-unique + \field{sort} values; +\item\meta{field}: append the value of the given field (if set) to + the \field{sort} field. The given field must be defined (has an + associated key for use in \gls{newglossaryentry}) but may be unset. + If the interpreter is on, the field contents will be interpreted. + If the field is just a label (such as the \field{category} field) + you may find it simpler to use + \csopt[\meta{field}]{identical-sort-action} instead. +\end{itemize} +The default setting is \csopt[none]{sort-suffix}. + +This option only affects the alphabetic +(\tableref{tab:sortoptionsrule}), letter +(\tableref{tab:sortoptionsletter}) and letter-number +(\tableref{tab:sortoptionsletternumber}) sort rules. For the other +types of sort methods (not including the no-sort options listed in +\tableref{tab:sortoptionsnosort}) you'll need to use +\csopt{identical-sort-action} to prevent problems occurring with +duplicate sort values. + +In the case of \csopt[non-unique]{sort-suffix}, this will only append a +suffix to the duplicate sort values (within the same hierarchical +level). The first sort value to be encountered isn't given a suffix. + +The \csopt[\meta{field}]{sort-suffix} setting will only append a suffix +if that field is set, but (if set) it will apply the suffix to all +\field{sort} values, even those that are unique. + +If you use \longarg{verbose}, then \bibgls\ will write information +in the transcript when it appends a suffix to the sort value. The +message: +\begin{alltt} +Sort value '\meta{sort}' (entry '\meta{id}') not unique for the entry's +hierarchical level. +\end{alltt} +indicates that an entry with the given \meta{sort} value has already +been found within the same hierarchical level as the currently +processed entry (whose label is given by \meta{id}). The same +hierarchical level in this context means that either both entries +don't have a parent or both entries have the same parent. (That is, +the entries are considered siblings.) + +This message will then be followed by: +\begin{alltt} +Appending suffix '\meta{suffix}' to the sort value '\meta{sort}' +for entry '\meta{id}'. +\end{alltt} +which indicates that the entry (identified by the label \meta{id}) +has been assigned the sort value given by \meta{sort}\meta{suffix}. +If any break markers are applied, this is done after the suffix has +been appended. + +For example, suppose in my document I want to write about \appfmt{makeglossaries} +(the application) and \csfmt{makeglossaries} (the command). I might +decide to define semantic commands: +\begin{codeenv} +\cs{newcommand}*\marg{\cmd{application}}[1]\marg{\ics{texttt}\marg{\idx{param}1}} +\cs{newcommand}*\marg{\cmd{command}}[1]\marg{\cs{texttt}\marg{\cs{glsbackslash} \idx{param}1}} +\end{codeenv} +In my \ext{bib} file I might have: +\begin{codeenv} +\atentry{entry}\marg{cs.makeglossaries, + \field{name}=\marg{\cmd{command}\marg{makeglossaries}}, + \field{category}=\marg{command}, + \field{description}=\marg{opens glossary files} +} +\strut +\atentry{entry}\marg{ap.makeglossaries, + \field{name}=\marg{\cmd{application}\marg{makeglossaries}}, + \field{category}=\marg{application}, + \field{description}=\marg{Perl script} +} +\end{codeenv} +If \bibgls\ is provided with the definitions of \csfmt{application} +and \csfmt{command} (by interpreting the \atentry{preamble} or a +package provided with \longarg{custom-packages}) then it will +determine that the sort value for \code{cs.makeglossaries} is +\csfmt{makeglossaries} and the sort value for +\code{ap.makeglossaries} is just \code{makeglossaries}. These are +two distinct sort values from \bibgls's point of view although the +sort rule may consider them identical if the rule ignores the +\idx{escchar} character (such as the locale sort methods), in which case, +\bibgls\ will then act according to \csopt{identical-sort-action}. + +If \bibgls\ isn't provided with these custom definitions, then it +will ignore those semantic commands and both entries will end up with +the sort value \code{makeglossaries}. The second instance will be +recognised as a duplicate and the sort value will be converted to +\code{makeglossaries1} (where the automated suffix is \code{1} and +the suffix marker, see below, is the empty string). Whereas with, +say, \csopt[.]{sort-suffix-marker}\ then the sort value would become +\code{makeglossaries.1}. + +For comparison, consider the following document: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[\styopt[indexgroup]{style}]\marg{glossaries} +\strut +\ics{cs.makeglossaries} +\strut +\cs{newcommand}*\marg{\cmd{application}}[1]\marg{\cs{texttt}\marg{\idx{param}1}} +\cs{newcommand}*\marg{\cmd{command}}[1]\marg{\cs{texttt}\marg{\cs{glsbackslash} \idx{param}1}} +\strut +\gls{newglossaryentry}\marg{cs.makeglossaries}\marg{\comment{} + \field{name}=\marg{\cmd{command}\marg{makeglossaries}}, + \field{description}=\marg{opens glossary files}} +\strut +\gls{newglossaryentry}\marg{ap.makeglossaries}\marg{\comment{} + \field{name}=\marg{\cmd{application}\marg{makeglossaries}}, + \field{description}=\marg{Perl script}} +\strut +\cmd{begin}\marg{document} +\cs{gls}\marg{cs.makeglossaries} and \cs{gls}\marg{ap.makeglossaries}. +\ics{printglossaries} +\cmd{end}\marg{document} +\end{codeenv} + +This uses \idx{makeindex}, which puts both entries in the +\qt{Symbols} group (since they both start with \idx{escchar} from the +start of \csfmt{command} and \csfmt{application}, respectively). +The ordering is \appfmt{makeglossaries}, \csfmt{makeglossaries} +because \qt{a} (second character of \csfmt{application}) comes +before \qt{c} (second character of \csfmt{command}). + +The switch to \idx{xindy} just involves adding the \styopt{xindy} +package option: +\begin{codeenv} +\cs{usepackage}[\styopt{xindy},\styopt[indexgroup]{style}]\marg{glossaries} +\end{codeenv} +This results in a glossary that only contains one entry, +\csfmt{makeglossaries}, because \idx{xindy} merges entries with +duplicate sort values and the sort values end up as duplicates +because \idx{xindy} discards the \csfmt{application} and +\csfmt{command} control sequences. Although \bibgls\ also ignores +unknown control sequences, it doesn't perform this merger. + +If I add: +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cs{providecommand}*\marg{\cmd{application}}[1]\marg{\cs{texttt}\marg{\idx{param}1}} +\cs{providecommand}\marg{\cmd{command}}[1]\marg{\cs{texttt}\marg{\cs{glsbackslash} \idx{param}1}}}} +\end{codeenv} +to the earlier \ext{bib} file (called, say, \filefmt{entries.bib}) +then the document can be altered to use \bibgls: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[\styopt{record},\styopt[indexgroup]{style}]\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[entries.bib]{src}, + \csopt[non-unique]{sort-suffix}, + \csopt[none]{identical-sort-action} +} +\strut +\cmd{begin}\marg{document} +\cs{gls}\marg{cs.makeglossaries} and \cs{gls}\marg{ap.makeglossaries}. +\cs{printunsrtglossaries} +\cmd{end}\marg{document} +\end{codeenv} +This uses the default \csopt[locale]{sort} which considers \idx{escchar} +an ignored (punctuation) character, so both \csfmt{makeglossaries} and +\appfmt{makeglossaries} are listed in the \qt{M} letter group, even +though the interpreter has determined that the sort value for +\code{cs.makeglossaries} is the literal string \csfmt{makeglossaries}. +Note that in this case \bibgls\ doesn't detect duplicate sort values +since it only uses a simple string comparison to detect duplicates +rather than using the collator. + +If I switch to using a letter-based sort rule instead, for example +\csopt[letter-nocase]{sort}, then \csfmt{makeglossaries} will be +listed in the \qt{Symbols} letter group since the leading \idx{escchar} +from the sort value \csfmt{makeglossaries} isn't ignored with this +rule. + +Now let's suppose I use \csopt[false]{interpret-preamble} to prevent +\bibgls\ from interpreting the preamble: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries.bib]{src},\csopt[false]{interpret-preamble}} +\end{codeenv} +This means that the custom commands won't be recognised and will +therefore be ignored, so both entries will have their sort values reduced to +\code{makeglosssaries}. + +The first entry to be processed is \code{cs.makeglossaries} because +it's the first to be selected. This is assigned the sort value +\code{makeglossaries}. (Note that, unless you use +\csopt[unsrt]{sort}, the initial selection order is based on the record +order. In this example, \code{cs.makeglossaries} has the first +record in the \ext{aux} file.) + +The next entry to be processed is \code{ap.makeglossaries}. This +also ends up with the sort value \code{makeglossaries} so \bibgls\ +converts this to \code{makeglossaries1} and (with verbose mode on) +the following messages are written to the transcript: +\begin{verbatim} +Sort value 'makeglossaries' (entry 'ap.makeglossaries') not unique +for the entry's hierarchical level. +Appending suffix '1' to the sort value 'makeglossaries' for entry +'ap.makeglossaries'. +\end{verbatim} +Both entries are listed in the \qt{M} letter group in the order +\csfmt{makeglossaries}, \appfmt{makeglossaries}. + +If the records are reversed: +\begin{codeenv} +\cs{gls}\marg{ap.makeglossaries} and \cs{gls}\marg{cs.makeglossaries}. +\end{codeenv} +then the sort value for \code{cs.makeglossaries} is now considered +the duplicate and the order is reversed: \appfmt{makeglossaries}, +\csfmt{makeglossaries}. + +Suppose now I modify the \ext{bib} file so that +\code{ap.makeglossaries} is defined as: +\begin{codeenv} +\atentry{entry}\marg{ap.makeglossaries, + \field{name}=\marg{\cmd{application}\marg{makeglossaries}}, + \field{category}=\marg{application}, + \field{description}=\marg{Perl script (must be used with \cs{gls}\marg{cs.makeglossaries})} +} +\end{codeenv} +and suppose the document only contains an explicit reference to +\code{ap.makeglossaries}: +\begin{codeenv} +\cmd{begin}\marg{document} +\cs{gls}\marg{ap.makeglossaries} +\cs{printunsrtglossaries} +\cmd{end}\marg{document} +\end{codeenv} +Now \code{ap.makeglossaries} is the first entry to be selected +because entries with records are always selected before any +(unrecorded) dependencies. In this case \code{cs.makeglossaries} is +only selected because it's required by \code{ap.makeglossaries}. Now +\code{ap.makeglossaries} is the first to have its sort value +assigned, and it's \code{cs.makeglossaries} that has the duplicate. +This means that the ordering in the glossary is now: +\appfmt{makeglossaries}, \csfmt{makeglossaries}. + +An oddity occurs if the glossary is moved to the start of the +document: +\begin{codeenv} +\cmd{begin}\marg{document} +\cs{printunsrtglossaries} +\cs{gls}\marg{ap.makeglossaries} +\cmd{end}\marg{document} +\end{codeenv} +In this case, the first document build: +\begin{verbatim} +pdflatex myDoc +bibgls --group --verbose myDoc +pdflatex myDoc +\end{verbatim} +leads to the ordering described above: +\appfmt{makeglossaries}, \csfmt{makeglossaries}. +However, the next document build has a new record for +\code{cs.makeglossaries} occurring in the glossary (within the +description of \code{ap.makeglossaries}) which means it's now the +first entry to be selected so the ordering switches to: +\csfmt{makeglossaries}, \appfmt{makeglossaries}. +In this type of situation you might be better off with the +\csopt[id]{identical-sort-action} option instead. + +Remember that you can temporarily switch off the indexing by locally +setting: +\begin{codeenv*} +\ics{GlsXtrSetDefaultGlsOpts}\marg{\glsopt{noindex}} +\end{codeenv*} +Since the glossary preamble is scoped, you can simply do +\begin{codeenv} +\ics{appto}\ics{glossarypreamble}\marg{\cs{GlsXtrSetDefaultGlsOpts}\marg{\glsopt{noindex}}} +\end{codeenv} +to switch off the indexing within the glossary (or use +\ics{apptoglossarypreamble}). Note that this is +different to using: +\begin{codeenv} +\ics{GlsXtrSetDefaultNumberFormat}\marg{\encap{glsignore}} +\end{codeenv} +which creates an \idx{ignoredrecord}. Even though the record is ignored +(and so won't show in the location list) the record still influences +the selection order and the record count. + +\optsection{sort-suffix-marker} + +This automatically implements the dual and secondary settings +\csopt[\meta{value}]{dual-sort-suffix-marker} and +\csopt[\meta{value}]{secondary-sort-suffix-marker}. + +If a suffix is appended to the sort value (see above) then it will +be separated by the suffix marker, which can be set with +\csopt[\meta{value}]{sort-suffix-marker} where \meta{value} is the +marker. By default the marker is empty. You can use \stringu\meta{hex} +or \cs{glshex}\meta{hex} to indicate Unicode characters outside the +\idx{ASCII} range. If, for some reason, you want to use a special +character, such as \idx{param}, you will need to precede it with +\ics{cs.string} (for example \code{\cs{cs.string}\idx{param}}) or +use the above hexadecimal markup. If you use \ics{cs.hash} it will +be treated as a literal string containing a backslash followed by a +hash character. + +\optsection{strength} + +This option automatically implements +\csopt[\meta{value}]{dual-strength} and +\csopt[\meta{value}]{secondary-strength}. + +The collation strength used by the alphabet sort methods +(\tableref{tab:sortoptionsrule}) can be set +to the following values: \optfmt{primary} (default), +\optfmt{secondary}, \optfmt{tertiary} or \optfmt{identical}. These +indicate the difference between two characters, but the exact +assignment is locale dependent. See the documentation for Java's +\href{http://docs.oracle.com/javase/8/docs/api/java/text/Collator.html}{\code{Collator} +class}~\cite{collator} for further details. + +For example, suppose the file \filefmt{entries.bib} contains: +\begin{codeenv} +\atentry{index}\marg{resume} +\atentry{index}\marg{RESUME} +\atentry{index}\marg{resumee, \field{name}=\marg{r\ics{acute}esum\cs{acute}e}} +\atentry{index}\marg{rat} +\atentry{index}\marg{rot} +\atentry{index}\marg{aardvark} +\atentry{index}\marg{zoo} +\end{codeenv} +and the document contains: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[\styopt{record}]\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[en]{sort},\csopt[entries]{src}} +\strut +\cmd{begin}\marg{document} +\cs{gls}\marg{resumee}, \cs{gls}\marg{resume}, \cs{gls}\marg{RESUME}, +\cs{gls}\marg{aardvark}, \cs{gls}\marg{rat}, \cs{gls}\marg{rot}, \cs{gls}\marg{zoo}. +\strut +\cs{printunsrtglossaries} +\cmd{end}\marg{document} +\end{codeenv} +then this uses the default \csopt[primary]{strength}, so the entries +are listed as aardvark, rat, r\'esum\'e, resume, RESUME, rot, zoo. + +If the strength is changed to \optfmt{secondary}: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[en]{sort},\csopt[entries]{src},\csopt[secondary]{strength}} +\end{codeenv} +then the entries are listed as aardvark, rat, resume, RESUME, +r\'esum\'e, rot, zoo. + +If the strength is changed to \optfmt{tertiary} or +\optfmt{identical}, there's no difference from +\csopt[secondary]{strength} for this particular example. + +This option is ignored by non-alphabet sorts (such as letter or numeric). + +\optsection{decomposition} + +This option automatically implements the dual and secondary settings +\csopt[\meta{value}]{dual-decomposition} and +\csopt[\meta{value}]{secondary-decomposition}. + +The collation decomposition used by alphabet sort methods +(\tableref{tab:sortoptionsrule}) can be set +to the following values: \optfmt{canonical} (default), +\optfmt{full} or \optfmt{none}. This determines how Unicode composed +characters are handled. The fastest mode is \optfmt{none} but is +only appropriate for languages without accents. The slowest mode is +\optfmt{full} but is the most complete for languages with \idx{non-ASCII} +characters. See the documentation for Java's +\href{http://docs.oracle.com/javase/8/docs/api/java/text/Collator.html}{\code{Collator} +class}~\cite{collator} for further details. +This option is ignored by non-alphabet sorts (such as letter or numeric). + +\optsection{letter-number-rule} + +This automatically implements the dual and secondary settings +\csopt[\meta{value}]{dual-letter-number-rule} +and +\csopt[\meta{value}]{secondary-letter-number-rule}. + +If you use one of the letter-number sort methods +(\tableref{tab:sortoptionsletternumber}), then you can determine the +comparison between a number and letter. The \meta{value} may be +one of: +\begin{itemize} +\item\optfmt{before letter}: numbers are considered less than any +letter. + +\item\optfmt{after letter}: numbers are considered greater than any +letter. + +\item\optfmt{between}: (default) numbers come between letter cases. +With the \optfmt{letternumber\dhyphen case} sort option, this will put +numbers after \idx{uppercase} and before \idx{lowercase}. This +setting doesn't make much sense with the +\optfmt{letternumber\dhyphen nocase} option but, if used, this will put +numbers before letters. The \optfmt{letternumber\dhyphen upperlower} and +\optfmt{letternumber\dhyphen lowerupper} options are more complicated. See +\sectionref{sec:letternumber} for more detail. + +\item\optfmt{first}: numbers are considered less than all +characters (including punctuation and spaces). + +\item\optfmt{last}: numbers are considered greater than all +characters (including punctuation and spaces). +\end{itemize} +Note that the reverse sort methods will invert this setting. +Remember also that the case-insensitive letter-number sort methods always +first convert the \field{sort} field to \idx{lowercase}, which means that +if you use one of them then there won't be any \idx{uppercase} +characters. + +Use \csopt{letter-number-punc-rule} to determine the relative +position of white space and punctuation. + +\optsection{letter-number-punc-rule} + +This automatically implements the dual and secondary +\csopt[\meta{value}]{dual-letter-number-punc-rule} +and +\csopt[\meta{value}]{secondary-letter-number-punc-rule}. + +If you use one of the letter-number sort methods +(\tableref{tab:sortoptionsletternumber}), then you can determine the +order of white space and punctuation. In this context, punctuation +means any character that's not considered a letter, a number +or white space. This means that characters such as combining marks +are considered punctuation. + +The \meta{value} may be one of the following: +\begin{itemize} +\item\optfmt{punc-space-first}: punctuation comes first, followed by +white space (then letters and optionally numbers according to the letter-number +rule); +\item\optfmt{punc-space-last}: punctuation followed by white space +come last (after letters and optionally numbers according to the letter-number +rule); +\item\optfmt{space-punc-first}: white space comes first, followed by +punctuation (then letters and optionally numbers according to the letter-number +rule); +\item\optfmt{space-punc-last}: white space followed by punctuation +come last (after letters and optionally numbers according to the letter-number +rule); +\item\optfmt{space-first-punc-last}: white space comes first +(followed by letters and optionally numbers according to the letter-number +rule) and punctuation comes last; +\item\optfmt{punc-first-space-last}: punctuation comes first +(followed by letters and optionally numbers according to the letter-number +rule) and white space comes last; +\item\optfmt{punc-first-space-zero}: punctuation comes first +(although numbers may come before) +and white space is replaced by the digit~\code{0} (\hex{30}); +\item\optfmt{punc-last-space-zero}: punctuation comes last +(although numbers may come after) +and white space is replaced by the digit~\code{0} (\hex{30}). +\item\optfmt{punc-first-space-zero-match-next}: punctuation comes first +(although numbers may come before) +and white space is replaced by the appropriate zero character (see below); +\item\optfmt{punc-last-space-zero-match-next}: punctuation comes last +(although numbers may come after) +and white space is replaced by the appropriate zero character (see below). +\end{itemize} +Remember that the reverse sort methods will invert order governed by this setting. + +For the \optfmt{space-zero-match-next} settings, the sort value will +have all spaces replaced with a digit that represents zero. If the +space isn't followed by a digit, the basic Latin \code{0} (\hex{30}) +will be used, otherwise \bibgls\ will try to match the zero with the +following digit group. For example, if the space is followed by +\textsuperscript{1} (\hex{B9}) the space will be replaced by +\textsuperscript{0} (\hex{2070}), resulting in the sub-string +\code{\textsuperscript{01}} (\hex{B9} \hex{2070}). + +If just the \optfmt{space-zero} +(without the \optfmt{-match-next}) is used then the space will just +be replaced with \code{0} resulting in the sub-string +\code{0\textsuperscript{1}} (\hex{30} \hex{2070}). In this case, the +\code{0} will be distinct from \textsuperscript{1} (rather than +being considered a leading zero). However, for +other numbering systems the \code{0} will be treated as a leading +zero. For example, if the space is followed by the Devanagari digit +one (\hex{0967}) then the sub-string will be \hex{30} \hex{0967} but here the +mixture is allowed to form a number (with a leading zero) as both +characters belong to the Unicode category \idx{numberdecimaldigit}. + +This means that the \optfmt{-match-next} settings are only really +needed if the sort string contains the superscript or subscript +digits that don't belong to the \qt{Number, Decimal Digit} category. +The plain \optfmt{space-zero} alternatives are more efficient as +they just perform a simple substitution. + +The \TeX\ parser library used by \bibgls\ recognises the standard +\LaTeX\ text-mode commands \ics{textsuperscript}\margm{text} and +\ics{textsubscript}\margm{text} +and will use the Unicode superscript or subscript characters if they cover every +character in \meta{text}, otherwise HTML markup is used, but that's +then stripped by \bibgls. This means that: +\begin{codeenv} +C\cs{textsubscript}\marg{10}H\cs{textsubscript}\marg{10}O\cs{textsubscript}\marg{4} +\end{codeenv} +will be converted to: +\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}} but: +\begin{codeenv} +X\cs{textsubscript}\marg{1, 2} +\end{codeenv} +will be converted to: +\begin{verbatim} +X<sub>1, 2</sub> +\end{verbatim} +which ends up as \code{X1, 2}. + + +Note that \csopt[first]{letter-number-rule} and +\csopt[last]{letter-number-rule} overrides this option when +comparing a number with white space or punctuation. + +\optsection{numeric-sort-pattern} + +If you use the custom \csopt[numberformat]{sort} or +\csopt[numberformat-reverse]{sort}, you need to +specify the format pattern with this option where +\meta{value} is a pattern recognised by Java's +\href{http://docs.oracle.com/javase/8/docs/api/java/text/DecimalFormat.html}{\code{java.text.DecimalFormat}} +class~\cite{decimalformat}. You can use \stringu\meta{hex} or +\cs{glshex}\meta{hex} to indicate Unicode characters by their +hexadecimal code. You can also use \ics{cs.hash}, \ics{cs.percent}, +\ics{cs.underscore}, \ics{cs.amp}, \ics{cs.openbrace} and +\ics{cs.closebrace} to indicate \idx{hashchar}, \idx{percentchar}, +\idx{underscorechar}, \idx{ampchar}, \idx{openbracechar} and +\idx{closebracechar}. + +Where the dual or secondary sort uses \optfmt{numberformat} +or \optfmt{numberformat-reverse}, use \csopt{dual-numeric-sort-pattern} for +\csopt{dual-sort} and \csopt{secondary-numeric-sort-pattern} +for \csopt{secondary}. + +\optsection{numeric-locale} + +If you use any of the locale-sensitive numeric sort methods +described in \sectionref{sec:numerical}, +such as \csopt[numeric]{sort}, use this option to set +the locale. The value may be: +\begin{itemize} +\item\optfmt{locale}: use Java's default locale (which is usually +the operating system's locale); +\item\optfmt{doc}: use the document's locale or, if not set, assume +\csopt[locale]{numeric-locale}; +\item\meta{lang-tag}: set to the locale identified by the given +a valid language tag \meta{lang-tag}. +\end{itemize} +Use \csopt{dual-numeric-locale} for +\csopt{dual-sort} and \csopt{secondary-numeric-locale} +for \csopt{secondary}. + +\optsection{date-sort-locale} + +If you use a date/time sort method (\tableref{tab:sortoptionsdatetime}), +then you can set the locale used by Java's date-time parser. +The default setting is \csopt[locale]{date-sort-locale}. + +The value may be \optfmt{locale} (use Java's default locale), +\optfmt{doc} (use the document's locale) or a valid language tag +\meta{lang-tag} identifying the locale. + +Use \csopt{dual-date-sort-locale} and \csopt{secondary-date-sort-locale} +for the dual and secondary. + +\optsection{date-sort-format} + +If you use a date/time sort method (\tableref{tab:sortoptionsdatetime}), +then you can set the format used by Java's date-time parser. +If omitted, \csopt[default]{date-sort-format} is assumed. +The \meta{value} may be one of: +\begin{itemize} +\item\optfmt{default}: use the locale's default format. +\item\optfmt{short}: use the locale's short format. +\item\optfmt{medium}: use the locale's medium format. +\item\optfmt{long}: use the locale's long format. +\item\optfmt{full}: use the locale's full format. +\item\meta{pattern}: provide a custom pattern. +This should match the specifications for Java's +\href{http://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html}{\code{SimpleDateFormat}} +class~\cite{simpledateformat}. You may use \stringu\meta{hex} or +\code{\cs{glshex} \meta{hex}} to indicate Unicode characters +or \ics{cs.hash}, \ics{cs.percent}, \ics{cs.underscore}, \ics{cs.amp}, +\ics{cs.openbrace} and \ics{cs.closebrace} to indicate +\idx{hashchar}, \idx{percentchar}, \idx{underscorechar}, +\idx{ampchar}, \idx{openbracechar} and~\idx{closebracechar}. +\end{itemize} + +With the custom setting, if the pattern only contains date (but not +time) information, then it must be used with \csopt[date]{sort} +or \csopt[date-reverse]{sort}. If the pattern only contains time +(but not date) information, then it must be used with +\csopt[time]{sort} or \csopt[time\dhyphen reverse]{sort}. If the pattern +contains date and time information, then it must be used with +\csopt[datetime]{sort} or \csopt[datetime-reverse]{sort}. + +For example, suppose each entry provides information about a person +and the \field{user1} field is used to store their date of birth: +\begin{codeenv} +\atentry{entry}\marg{caesar, + \field{name}=\marg{Gaius Julius Caesar}, + \field{first}=\marg{Julius Caesar}, + \field{text}=\marg{Caesar}, + \field{description}=\marg{Roman politician and general}, + \field{user1}=\marg{13 July 100 BC} +} +\strut +\atentry{entry}\marg{wellington, + \field{name}=\marg{Arthur Wellesley, 1st Duke of Wellington}, + \field{first}=\marg{Arthur Wellesley (Duke of Wellington)}, + \field{text}=\marg{Wellington}, + \field{description}=\marg{Anglo-Irish soldier and statesman}, + \field{user1}=\marg{1 May 1769 AD} +} +\end{codeenv} +Then the entries can be sorted by date of birth using: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{data in entries.bib} + \csopt[user1]{sort-field}, + \csopt[date]{sort}, + \csopt[d MMM y G]{date-sort-format} +} +\end{codeenv} + +The \code{G} (era) date pattern specifier expects a string, such as +\qt{AD}. It will match \idx{lowercase} forms, such as \qt{ad}, so if you +have \code{\cs{textsc}\marg{ad}} the interpreter will convert this to +\code{ad} (stripping the text-block command). However, in general +it's best to supply a semantic command that ensures that the +interpreted result matches the required format. + +For example, if \csfmt{era} is provided with: +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{era}}[1]\marg{\cs{textsc}\marg{\cs{MakeLowercase}\marg{\idx{param}1}}}}} +\end{codeenv} +If the definition is hidden from the interpreter +(\csopt[false]{interpret-preamble}) and the field +value contains \verb|\era{AD}| then the custom command will simply be stripped +leaving \code{AD} which can be matched by \code{G}. + +If the definition is picked up by the interpreter then the field +value will contain \code{ad} (from \ics{MakeLowercase}) but this can +be matched by \code{G}, so it isn't a problem. +However, if the definition of \csfmt{era} is changed so that the era label +supplied in the argument is converted to something that doesn't +match \code{G} then the definition should be hidden from the +interpreter. + +Here's a complete document that changes the \field{group} fields to use +the year and era: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[\styopt{record},\styopt[indexgroup]{style}]\marg{glossaries-extra} +\strut +\cs{newcommand}\marg{\gls{bibglsdategroup}}[7]\marg{\idx{param}1\idx{param}4\idx{param}7} +\cs{newcommand}\marg{\gls{bibglsdategrouptitle}}[7]\marg{\ics{number}\idx{param}1\cs{cs.space}\idx{param}4} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src}, + \csopt[user1]{sort-field}, + \csopt[date]{sort}, + \csopt[d MMM y G]{date-sort-format}, + \csopt[all]{selection} +} +\strut +\cmd{begin}\marg{document} +\cs{printunsrtglossaries} +\cmd{end}\marg{document} +\end{codeenv} +(The use of \ics{number} strips the leading zero from the year.) + +\optsection{group-formation} + +If the \field{group} field hasn't been set in +the \ext{bib} file or through options like \csopt{group}, then it is +assigned according to this option's setting during sorting if +\longarg{group} has been used. Permitted values: +\begin{itemize} +\item\optfmt{default}: the group is assigned according to +the sort method's default group formation. This is the default +setting. + +\item\optfmt{codepoint}: the group is set to +\format{bibglsunicodegroup}, where the first argument is the first +significant character (converted to \idx{lowercase} and decomposed, +if applicable) of the sort value. + +\item\optfmt{unicode category}: the group is set to +\format{bibglsunicodegroup}, where the first argument is the label +identifying the Unicode category of the first significant character +of the sort value. For example, the label \code{Ll} signifies a +\idx!{lowercase} letter and \code{Lu} signifies an \idx!{uppercase} +letter. + +\item\optfmt{unicode script}: the group is set to +\format{bibglsunicodegroup}, where the first argument is the +label identifying the Unicode script of the first significant +character of the sort value. For example, the label \code{LATIN} +indicates Latin, \code{GREEK} indicates Greek and \code{COMMON} +indicates common characters (such as mathematical Greek characters +that are often used with non-Greek scripts). + +\item\optfmt{unicode category and script}: the group is set to +\format{bibglsunicodegroup}, where the first argument is the +label corresponding to the Unicode category and script of the first +significant character of the sort value. For example, the label +\code{Ll.LATIN} indicates a \idx!{lowercase} Latin letter. +\end{itemize} +This option has no effect with \longarg{no-group} or if no sorting +is applied. Use \csopt{secondary-group-formation} for secondary +sorting and \csopt{dual-group-formation} for dual entries. +Settings other than the default can cause the groups to become +fragmented, so care is needed if you use this option. +See also \sectionref{sec:logicaldivisions}. + +\section{Secondary Glossary} +\label{sec:secondaryopts} + +The secondary glossary may only be used with \csopt[define]{action} +(within the same resource set) since it's incompatible with the copy actions. +You may use \csopt{secondary} in the first resource set and a copy +action in a subsequent resource set. + +\optsection{secondary} + +It may be that you want to display a glossary twice but with a +different order. For example, the first time alphabetically and the +second time by category. One way to do this is to have two +\gls{GlsXtrLoadResources} that both load the same \ext{bib} file with +different \csopt{label-prefix} and \csopt{sort} settings, but this +is only possible with \csopt[all]{selection} or by ensuring you +reference each entry with both label prefixes. Another method is +to use \csopt[copy]{action} but this requires a second resource +command with the same selection criteria. + +A simpler method is to use a single \gls{GlsXtrLoadResources} +with the \csopt{secondary} option. The value +(which must be supplied) should be in the format: +\begin{definition} +\meta{sort}:\meta{field}:\meta{type} +\end{definition} +or +\begin{definition} +\meta{sort}:\meta{type} +\end{definition} +If the \meta{field} is omitted, the value of \csopt{sort-field} is +used. Remember that when the primary entries are sorted, the +\field{sort} field will be set, which means that the fallback field +(such as \field{name}) won't be used in the secondary sort. In +general it's best to supply the field unless one type is sorted and the +other isn't. (The actual sort value obtained by the secondary sort +will be saved in the \field{secondarysort} field in case you require it.) + +The value of \meta{sort} is as for \csopt{sort}, but note +that in this case the sort value \optfmt{unsrt} or \optfmt{none} +means to use the same ordering as the primary entries. For +example, with \csopt[de-CH-1996]{sort}, +\csopt[none:copies]{secondary} the \code{copies} list will be +ordered according to \code{de-CH-1996} and not according to the +order in which they were read when the \ext{bib} file or files were +parsed. If \meta{sort} is \optfmt{custom}, then the rule should be +provided with \csopt{secondary-sort-rule}. + +This option will copy all the selected entries into the glossary labelled +\meta{type} sorted according to \meta{sort} (using \meta{field} as +the sort value). Note that this \emph{just copies the entry's label} +to the second glossary list rather than creating a duplicate entry, +which saves resources but it means that all the fields will be +identical. If you want groups in your glossary, the group +information for the secondary glossary will be stored in the +internal \field{secondarygroup} field. The \field{group} field will +contain the group for the primary glossary. + +In order to switch fields in \ics{printunsrtglossary}, you need at +least v1.21 of \sty{glossaries-extra} which provides +\ics{glsxtrgroupfield} to keep track of the appropriate field label. +If this command is defined, the preamble for the secondary glossary +will be adjusted to locally change the field to +\field{secondarygroup}. With older versions, the group information +in the secondary glossary will be the same as for the primary +glossary. + +(If the glossary \meta{type} doesn't exist, it will be +defined with \ics{provideignoredglossary*}\margm{type}.) +Note that if the glossary already exists and contains entries, +the existing entries aren't re-ordered. The new entries are +simply appended to the list. + +For example, suppose the \ext{bib} file contains entries like: +\begin{codeenv} +\atentry{entry}\marg{quartz, + \field{name}=\marg{quartz}, + \field{description}=\marg{hard mineral consisting of silica}, + \field{category}=\marg{mineral} +} +\strut +\atentry{entry}\marg{cabbage, + \field{name}=\marg{cabbage}, + \field{description}=\marg{vegetable with thick green or purple leaves}, + \field{category}=\marg{vegetable} +} +\strut +\atentry{entry}\marg{waterfowl, + \field{name}=\marg{waterfowl}, + \field{description}=\marg{any bird that lives in or about water}, + \field{category}=\marg{animal} +} +\end{codeenv} +and the document preamble contains: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[en-GB]{sort}, + \csopt[en-GB:category:topic]{secondary} +} +\end{codeenv} +This sorts the primary entries according to the default +\csopt{sort-field} and then sorts the entries according +to the \field{category} field and copies this list to +the \code{topic} glossary (which will be provided if not defined.) + +The secondary list can be displayed with the hypertargets switched +off to prevent duplicates. The cross-references will link to the +original glossary. + +For example: +\begin{codeenv*} +\ics{printunsrtglossary}\oarg{\printglossopt[Summary (alphabetical)]{title}} +\ics{printunsrtglossary}\oarg{\printglossopt[Summary (by topic)]{title},\printglossopt[false]{target}} +\end{codeenv*} + +The alternative (or if more than two lists are required) is to +reload the same \ext{bib} file with different label prefixes. +For example, if the entries are stored in \filefmt{entries.bib}: +\begin{codeenv} +\cs{newglossary*}\marg{nosort}\marg{Symbols (Unsorted)} +\cs{newglossary*}\marg{byname}\marg{Symbols (Letter Order)} +\cs{newglossary*}\marg{bydesc}\marg{Symbols (Ordered by Description)} +\cs{newglossary*}\marg{byid}\marg{Symbols (Ordered by Label)} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{entries.bib} + \csopt[unsrt]{sort}, + \csopt[nosort]{type} +} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{entries.bib} + \csopt[letter-case]{sort}, + \csopt[byname]{type}, + \csopt[byname.]{label-prefix} +} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{entries.bib} + \csopt[locale]{sort}, + \csopt[description]{sort-field}, + \csopt[bydesc]{type}, + \csopt[bydesc.]{label-prefix} +} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{entries.bib} + \csopt[letter]{sort}, + \csopt[id]{sort-field}, + \csopt[byid]{type}, + \csopt[byid.]{label-prefix} +} +\end{codeenv} + +\optsection{secondary-missing-sort-fallback} + +As \csopt{missing-sort-fallback} but for secondary sorting. + +\optsection{secondary-trim-sort} + +As \csopt{trim-sort} but for secondary sorting. + +\optsection{secondary-sort-replace} + +As \csopt{sort-replace} but for secondary sorting. + +\optsection{secondary-sort-rule} + +As \csopt{sort-rule} but for secondary custom sorting. + +\optsection{secondary-break-at} + +As \csopt{break-at} but for secondary entries. + +\optsection{secondary-break-marker} + +As \csopt{break-marker} but for secondary entries. + +\optsection{secondary-sort-number-pad} + +As \csopt{sort-number-pad} but for secondary entries. + +\optsection{secondary-sort-pad-plus} + +As \csopt{sort-pad-plus} but for secondary entries. + +\optsection{secondary-sort-pad-minus} + +As \csopt{sort-pad-minus} but for secondary entries. + +\optsection{secondary-identical-sort-action} + +As \csopt{identical-sort-action} but for secondary entries. + +\optsection{secondary-sort-suffix} + +As \csopt{sort-suffix} but for secondary entries. + +\optsection{secondary-sort-suffix-marker} + +As \csopt{sort-suffix-marker} but for secondary entries. + +\optsection{secondary-strength} + +As \csopt{strength} but for secondary entries. + +\optsection{secondary-decomposition} + +As \csopt{decomposition} but for secondary entries. + +\optsection{secondary-letter-number-rule} + +As \csopt{letter-number-rule} but for secondary letter-number sorting. + +\optsection{secondary-letter-number-punc-rule} + +As \csopt{letter-number-punc-rule} but for secondary letter-number sorting. + +\optsection{secondary-numeric-sort-pattern} + +As \csopt{numeric-sort-pattern} but for secondary +locale-sensitive numeric sorting. + +\optsection{secondary-numeric-locale} + +As \csopt{numeric-locale} but for secondary +locale-sensitive numeric sorting. + +\optsection{secondary-date-sort-locale} + +As \csopt{date-sort-locale} but for secondary date-time sorting. + +\optsection{secondary-date-sort-format} + +As \csopt{date-sort-format} but for secondary date-time sorting. + +\optsection{secondary-group-formation} + +As \csopt{group-formation} but for secondary sorting. + +\section{Dual Entries} +\label{sec:dualopts} + +\subsection{General Dual Settings} +\label{sec:dualoptsgeneral} + +\optsection[\subsubsection]{dual-prefix} + +This option indicates the prefix to use for the dual entries. The +default value is \idprefix{dual} (including the terminating period). +Any references to dual entries within the \ext{bib} file should use +the prefix \idprefix{dual} which will be replaced by \meta{value} +when the \ext{bib} file is parsed. + +As from version 1.8, the dual label prefix is identified +in the \ext{glstex} file with: +\begin{codeenv} +\format{bibglsdualprefixlabel} +\end{codeenv} + +\optsection[\subsubsection]{primary-dual-dependency} + +This is a boolean setting that determines whether or not primary and +dual entries should be considered mutual dependencies. The default value is +\csopt[true]{primary-dual-dependency}, which means that if a primary +has records then the dual is added as a dependency and vice versa. +The setting \csopt[false]{primary-dual-dependency} can't be used +with \csopt[none]{dual-sort} or \csopt[use]{dual-sort} (but may be +used with \csopt[combine]{dual-sort} and \csopt[none]{sort} or +\csopt[use]{sort}). + +\optsection[\subsubsection]{combine-dual-locations} + +This setting allows the location lists for each primary entry +to be merged with that of the corresponding dual entry. +The \meta{value} may be one of: +\begin{itemize} +\item\optfmt{false} This is the default setting. The location lists +aren't combined. +\item\optfmt{both} Both the primary and dual are given the combined +location list. +\item\optfmt{dual} Only the dual is given the combined location +list. The primary's location list is emptied. +\item\optfmt{primary} Only the primary is given the combined +location list. The dual's location list is emptied. +\end{itemize} + +For example, suppose the file \filefmt{entries.bib} contains: +\begin{codeenv} +\atentry{dualindexentry}\marg{array, + \field{description}=\marg{ordered list of values} +} +\strut +\atentry{dualindexentry}\marg{vector, + \field{name}=\marg{vector}, + \field{description}=\marg{column or row of values} +} +\strut +\atentry{dualindexentry}\marg{set, + \field{description}=\marg{collection of values} +} +\strut +\atentry{dualindexentry}\marg{matrix, + \field{plural}=\marg{matrices}, + \field{description}=\marg{rectangular array of values} +} +\end{codeenv} +and the document contains: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[colorlinks]\marg{hyperref} +\cmd{usepackage}[\styopt{record},\styopt{index},\styopt[indexgroup]{style}]\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src}, + \csopt[index]{type}, + \csopt[idx.]{label-prefix}, + \csopt[gls.]{dual-prefix}, + \csopt[main]{dual-type} +} +\strut +\cmd{begin}\marg{document} +\cs{gls}\marg{gls.array}, \cs{gls}\marg{gls.vector}, \cs{gls}\marg{gls.set}, \cs{gls}\marg{gls.matrix}. +\strut +\cmd{newpage} +\cs{gls}\marg{gls.array}, \cs{gls}\marg{idx.vector}, \cs{gls}\marg{idx.set}, \cs{gls}\marg{gls.matrix}. +\strut +\cmd{newpage} +\cs{gls}\marg{gls.array}, \cs{gls}\marg{gls.vector}, \cs{gls}\marg{gls.set}, \cs{gls}\marg{gls.matrix}. +\strut +\cs{printunsrtglossaries} +\cmd{end}\marg{document} +\end{codeenv} +In this case, the primary entries are placed in the \code{index} +glossary type and are assigned the prefix \idprefixfmt{idx} but only +two of the primary entries have been used in the document (both on +page~2). + +The dual entries are assigned the prefix \idprefixfmt{gls} and are +placed in the \code{main} glossary. The \code{gls.array} +and \code{gls.matrix} entries have been indexed on pages~1, 2 and~3. +The \code{gls.vector} and \code{gls.set} entries have been indexed +on pages~1 and~3. + +With the default setting, some of the locations are in the +\code{main} glossary (corresponding to \code{\cs{gls}\marg{gls.array}}, +\code{\cs{gls}\marg{gls.vector}}, \code{\cs{gls}\marg{gls.set}} and +\code{\cs{gls}\marg{gls.matrix}}) and some of the locations are in the +\code{index} glossary (corresponding to \code{\cs{gls}\marg{idx.vector}} +and \code{\cs{gls}\marg{idx.set}}). + +If the option \csopt[primary]{combine-dual-locations} is added to +the resource set, then all the locations are moved to the +\code{index} glossary. The entries in the \code{main} glossary no +longer have locations. This is actually preferable for this type +of document and it's best not to reference the primary (index) +entries as the hyperlink created by \ics{gls} will point to the +index, but these entries don't have descriptions, so it's less +useful than referencing the dual (main) entries as then the +hyperlink can point to the definition in the \code{main} glossary. + + +\subsection{Dual Fields} +\label{sec:dualoptsfields} + +\optsection[\subsubsection]{dual-type} + +This option sets the \field{type} field for all dual +entries. (The primary entries obey the \csopt{type} option.) This +will override any value of \field{type} provided in the \ext{bib} +file (or created through a mapping). The \meta{value} is required and +should be one of: +\begin{itemize} +\item \optfmt{same as entry}: sets the \field{type} to the entry +type (\idx!{lowercase} and without +the initial \code{@}). For example, if the entry was defined with +\atentry{dualentry}, the \field{type} will be set to +\optfmt{dualentry}. +If you've used \csopt{entry-type-aliases}, this refers to the target +entry type not the original entry type provided in the \ext{bib} +file. + +\item \optfmt{same as original entry}: set the \field{type} field +to the original entry type (\idx!{lowercase} and without +the initial \code{@}) before it was aliased (behaves like +\optfmt{same as entry} if the entry type wasn't aliased). + +\item \optfmt{same as base}: sets the \field{type} to the base name +of the \ext{bib} file (without the extension) that provided the +entry definition (new to v1.1); + +\item \optfmt{same as primary}: sets the \field{type} to the same as +the corresponding primary entry's \field{type} (which may have been +set with \csopt{type}). If the primary entry doesn't have the +\field{type} field set, the dual's \field{type} will remain +unchanged. + +\item \optfmt{same as parent}: sets the \field{type} to the same as +the entry's parent (new to v1.9). If the entry doesn't have a parent +or if the parent doesn't have the \field{type} field set, then +no change is made. + +\item \meta{label}: sets the \field{type} field to \meta{label}. +\end{itemize} + +Remember that the glossary with that label must have already +been defined (see \sectionref{sec:newglossary}). +For example: +\begin{codeenv} +\cs{newglossary*}\marg{english}\marg{English} +\cs{newglossary*}\marg{french}\marg{French} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[en]{sort},\csopt[fr]{dual-sort}, + \csopt[english]{type}, + \csopt[french]{dual-type}} +\end{codeenv} +Alternatively: +\begin{codeenv} +\cs{newglossary*}\marg{dictionary}\marg{Dictionary} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[en]{sort},\csopt[fr]{dual-sort}, + \csopt[dictionary]{type}, + \csopt[same as primary]{dual-type}} +\end{codeenv} + +\optsection[\subsubsection]{dual-category} + +This option sets the \field{category} field for all dual +entries. (The primary entries obey the \csopt{category} option.) This +will override any value of \field{category} provided in the \ext{bib} +file (or created through a mapping). The \meta{value} may be empty or +one of: +\begin{itemize} +\item \optfmt{same as entry}: sets the \field{category} to the entry +type (\idx{lowercase} and without +the initial \code{@}). For example, if the entry was defined with +\atentry{dualentry}, the \field{category} will be set to +\optfmt{dualentry}. +If you've used \csopt{entry-type-aliases}, this refers to the target +entry type not the original entry type provided in the \ext{bib} +file. + +\item \optfmt{same as original entry}: set the \field{category} field +to the original entry type (\idx{lowercase} and without +the initial \code{@}) before it was aliased (behaves like +\optfmt{same as entry} if the entry type wasn't aliased). + +\item \optfmt{same as base}: sets the \field{category} to the base +name of the \ext{bib} file (without the extension) that provided the +entry definition (new to v1.1); + +\item \optfmt{same as primary}: sets the \field{category} to the +same as the corresponding primary entry's \field{category} (which +may have been set with \csopt{category}). If the primary entry +doesn't have the \field{category} field set, the dual's +\field{category} will remain unchanged. + +\item \optfmt{same as type}: sets the \field{category} to the same +as the value of the entry's \field{type} field (which may have been +set with \csopt{dual-type}). If the entry doesn't have the +\field{type} field set, the \field{category} will remain unchanged. + +\item \meta{label}: sets the \field{category} field to \meta{label}. +\end{itemize} + +\optsection[\subsubsection]{dual-counter} + +As \csopt{counter} but for the dual entries. In this case +\meta{value} may be the name of the counter or +\optfmt{same as primary} which uses the counter for the primary +entry. + +\optsection[\subsubsection]{dual-short-case-change} + +As \csopt{short-case-change} but applies to the \field{dualshort} +field instead. + +\optsection[\subsubsection]{dual-long-case-change} + +As \csopt{long-case-change} but applies to the \field{duallong} +field instead. + +\optsection[\subsubsection]{dual-field} + +If this option is used, this will add \ics{glsxtrprovidestoragekey} +to the start of the \iext{glstex} file providing the key given by +\meta{value}. Any entries defined using a dual entry type, such as +\atentry{dualentry}, will be written to the \ext{glstex} file with +an extra field called \meta{value} that is set to the mirror entry. +If \meta{value} is omitted \csopt[dual]{dual-field} is assumed. If +you use a different value, you will need to redefine +\gls{GlsXtrDualField} (either locally or globally). + +For example, if the \ext{bib} file contains: +\begin{codeenv} +\atentry{dualentry}\marg{child, + \field{name}=\marg{child}, + \field{plural}=\marg{children}, + \field{description}=\marg{enfant} +} +\end{codeenv} +Then with \csopt[dual]{dual-field} (or simply \csopt{dual-field} +without a value) this will first add the line: +\begin{codeenv} +\cs{glsxtrprovidestoragekey}\marg{\field{dual}}\marg{}\marg{} +\end{codeenv} +at the start of the file and will include the line: +\begin{codeenv*} +\field{dual}=\marg{dual.child}, +\end{codeenv*} +for the primary entry (\code{child}) and the line: +\begin{codeenv} +\field{dual}=\marg{child}, +\end{codeenv} +for the dual entry (\code{dual.child}). It's then possible to +reference one entry from the other. For example, the post-description +hook could contain: +\begin{codeenv} + \cs{ifglshasfield}\marg{\field{dual}}\marg{\cs{glscurrententrylabel}} + \marg{\comment{} + \cs{space} + (\cs{glshyperlink}\marg{\cs{glscurrentfieldvalue}})\comment{} + }\comment{} + \marg{}\comment{} +\end{codeenv} +Note that this new field won't be available for use within the +\iext{bib} file (unless it was previously defined in the document +before \gls!{glsxtrresourcefile}). + +\optsection[\subsubsection]{dual-date-time-field-format} + +As \csopt{date-time-field-format} but is used for dual entries. + +\optsection[\subsubsection]{dual-date-field-format} + +As \csopt{date-field-format} but is used for dual entries. + +\optsection[\subsubsection]{dual-time-field-format} + +As \csopt{time-field-format} but is used for dual entries. + +\optsection[\subsubsection]{dual-date-time-field-locale} + +As \csopt{date-time-field-locale} but is used for dual entries. + +\optsection[\subsubsection]{dual-date-field-locale} + +As \csopt{date-field-locale} but is used for dual entries. + +\optsection[\subsubsection]{dual-time-field-locale} + +As \csopt{time-field-locale} but is used for dual entries. + +\subsection{Dual Sorting} +\label{sec:dualoptssort} + +\optsection[\subsubsection]{dual-sort} + +This option indicates how to sort the dual entries. The primary +entries are sorted with the normal entries according to +\csopt{sort}, and the dual entries are sorted according to +\csopt{dual-sort} unless \csopt[combine]{dual-sort} in which case the dual +entries will be combined with the primary entries and all the +entries will sorted together according to the \csopt{sort} option. + +If \meta{value} isn't set to \optfmt{combine} then the dual +entries are sorted separately according to \meta{value} (as per +\csopt{sort}) and the dual entries will be appended at the end of +the \iext{glstex} file. The field used by the comparator is given by +\csopt{dual-sort-field}. +If \csopt[custom]{dual-sort}, then the dual entries are sorted according to the +rule provided by \csopt{dual-sort-rule}. + +For example: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries-dual]{src}, + \csopt[en]{sort}, + \csopt[de-CH-1996]{dual-sort} +} +\end{codeenv} +This will sort the primary entries according to \optfmt{en} +(English) and the secondary entries according to \optfmt{de-CH-1996} +(Swiss German new orthography) whereas: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries-dual]{src}, + \csopt[en-GB]{sort}, + \csopt[combine]{dual-sort} +} +\end{codeenv} +will combine the dual entries with the primary entries and sort them +all according to the \optfmt{en-GB} locale (British English). + +If not set, \csopt{dual-sort} defaults to \optfmt{combine}. If +\meta{value} is omitted, \optfmt{locale} is assumed. + +\optsection[\subsubsection]{dual-sort-field} + +This option indicates the field to use when sorting dual entries +(when they haven't been combined with the primary entries). The +default value is the same as the \csopt{sort-field} value. + +\optsection[\subsubsection]{dual-missing-sort-fallback} + +As \csopt{missing-sort-fallback} but for dual sorting. + +\optsection[\subsubsection]{dual-trim-sort} + +As \csopt{trim-sort} but for dual sorting. + +\optsection[\subsubsection]{dual-sort-replace} + +As \csopt{sort-replace} but for dual sorting. + +\optsection[\subsubsection]{dual-sort-rule} + +As \csopt{sort-rule} but for \csopt[custom]{dual-sort}. + +\optsection[\subsubsection]{dual-break-at} + +As \csopt{break-at} but for dual entries. + +\optsection[\subsubsection]{dual-break-marker} + +As \csopt{break-marker} but for dual entries. + +\optsection[\subsubsection]{dual-sort-number-pad} + +As \csopt{sort-number-pad} but for dual entries. + +\optsection[\subsubsection]{dual-sort-pad-plus} + +As \csopt{sort-pad-plus} but for dual entries. + +\optsection[\subsubsection]{dual-sort-pad-minus} + +As \csopt{sort-pad-minus} but for dual entries. + +\optsection[\subsubsection]{dual-identical-sort-action} + +As \csopt{identical-sort-action} but for dual entries. + +\optsection[\subsubsection]{dual-sort-suffix} + +As \csopt{sort-suffix} but for dual entries. + +\optsection[\subsubsection]{dual-sort-suffix-marker} + +As \csopt{sort-suffix-marker} but for dual entries. + +\optsection[\subsubsection]{dual-strength} + +As \csopt{strength} but for dual entries. + +\optsection[\subsubsection]{dual-decomposition} + +As \csopt{decomposition} but for dual entries. + +\optsection[\subsubsection]{dual-letter-number-rule} + +As \csopt{letter-number-rule} but for dual entries that use a +letter-number sort. + +\optsection[\subsubsection]{dual-letter-number-punc-rule} + +As \csopt{letter-number-punc-rule} but for dual entries that use a +letter-number sort. + +\optsection[\subsubsection]{dual-numeric-sort-pattern} + +As \csopt{numeric-sort-pattern} but for dual entries that use a +locale-sensitive numeric sort. + +\optsection[\subsubsection]{dual-numeric-locale} + +As \csopt{numeric-locale} but for dual entries that use a +locale-sensitive numeric sort. + +\optsection[\subsubsection]{dual-date-sort-locale} + +As \csopt{date-sort-locale} but for dual entries that +use a date/time sort. + +\optsection[\subsubsection]{dual-date-sort-format} + +As \csopt{date-sort-format} but for dual entries that +use a date/time sort. + +\optsection[\subsubsection]{dual-group-formation} + +As \csopt{group-formation} but for dual sorting. + + +\subsection{Dual Mappings} +\label{sec:dualoptsmap} + +\optsection[\subsubsection]{dual-entry-map} + +This setting governs the behaviour of \atentry{dualentry} +definitions. The value consists of two comma-separated lists of +equal length identifying the field mapping used to create the dual +entry from the primary one. Note that the \field{alias} field +can't be mapped. + +The default setting is: +\begin{codeenv} +\csopt[ + \marg{\field{name},\field{plural},\field{description},\field{descriptionplural}}, + \marg{\field{description},\field{descriptionplural},\field{name},\field{plural}} +]{dual-entry-map} +\end{codeenv} +The dual entry is created by copying the value of the field in the +first list \meta{list1} to the field in the corresponding place in the second +list \meta{list2}. Any additional fields are copied over to the same +field. +For example: +\begin{codeenv} +\atentry{dualentry}\marg{cat, + \field{name}=\marg{cat}, + \field{description}=\marg{chat}, + \field{see}=\marg{dog} +} +\end{codeenv} +defines two entries. The primary entry is essentially like: +\begin{codeenv} +\atentry{entry}\marg{cat, + \field{name}=\marg{cat}, + \field{plural}=\marg{cat\cs{glspluralsuffix} }, + \field{description}=\marg{chat}, + \field{descriptionplural}=\marg{chat\cs{glspluralsuffix} }, + \field{see}=\marg{dog} +} +\end{codeenv} +and the dual entry is essentially like: +\begin{codeenv} +\atentry{entry}\marg{dual.cat, + \field{description}=\marg{cat}, + \field{descriptionplural}=\marg{cat\cs{glspluralsuffix} }, + \field{name}=\marg{chat}, + \field{plural}=\marg{chat\cs{glspluralsuffix} }, + \field{see}=\marg{dog} +} +\end{codeenv} +(except they're defined using \gls{bibglsnewdualentry} instead of +\gls{bibglsnewentry}, and each is considered dependent on the other.) + +The \field{see} field isn't listed in \csopt{dual-entry-map} so its +value is simply copied directly over to the \field{see} field in the +dual entry. Note that the missing \field{plural} and +\field{descriptionplural} fields have been filled in using their +fallback values. + +In general \bibgls\ doesn't try to supply missing fields, but in the +dual entry cases it needs to do this for the mapped fields. This is +because the shuffled fields might have different default values from +the \styfmt{glossaries-extra} package's point of view. For example, +\gls{longnewglossaryentry} doesn't provide a default for +\field{descriptionplural} if it hasn't been set. + +\optsection[\subsubsection]{dual-abbrv-map} + +This is like \csopt{dual-entry-map} but applies to +\atentry{dualabbreviation} rather than \atentry{dualentry}. +Note that the \field{alias} field can't be mapped. The +default setting is: +\begin{codeenv} +\csopt[ + \marg{\field{short},\field{shortplural},\field{long},\field{longplural},\field{dualshort},\field{dualshortplural}, + \field{duallong},\field{duallongplural}}, + \marg{\field{dualshort},\field{dualshortplural},\field{duallong},\field{duallongplural},\field{short},\field{shortplural}, + \field{long},\field{longplural}} +]{dual-abbrv-map} +\end{codeenv} + +This essentially flips the \field{short} field with the +\field{dualshort} field and the \field{long} field with the +\field{duallong} field. See \atentry{dualabbreviation} +for further details. + +\optsection[\subsubsection]{dual-abbrventry-map} + +This is like \csopt{dual-entry-map} but applies to +\atentry{dualabbreviationentry} rather than \atentry{dualentry}. +Note that the \field{alias} field can't be mapped. The +default setting is: +\begin{codeenv} +\csopt[ + \marg{\field{long},\field{short},\field{shortplural}}, + \marg{\field{name},\field{text},\field{plural}} +]{dual-abbrventry-map} +\end{codeenv} +See \atentry{dualabbreviationentry} for further details. + + +\optsection[\subsubsection]{dual-symbol-map} + +This is like \csopt{dual-entry-map} but applies to +\atentry{dualsymbol} rather than \atentry{dualentry}. +Note that the \field{alias} field can't be mapped. The +default setting is: +\begin{codeenv} +\csopt[ + \marg{\field{name},\field{plural},\field{symbol},\field{symbolplural}}, + \marg{\field{symbol},\field{symbolplural},\field{name},\field{plural}} +]{dual-symbol-map} +\end{codeenv} +This essentially flips the \field{name} field with the +\field{symbol} field. + +\optsection[\subsubsection]{dual-indexentry-map} + +This is like \csopt{dual-entry-map} but applies to +\atentry{dualindexentry} rather than \atentry{dualentry}. +The default setting is: +\begin{codeenv} +\csopt[ + \marg{\field{name}}, + \marg{\field{name}} +]{dual-indexentry-map} +\end{codeenv} +Note that there must always be at least one pair, even if it's the +same field, since this identifies the field to use for the backlink, +if set. + +\optsection[\subsubsection]{dual-indexsymbol-map} + +This is like \csopt{dual-entry-map} but applies to both +\atentry{dualindexsymbol} and \atentry{dualindexnumber}. +The default setting is: +\begin{codeenv} +\csopt[ + \marg{\field{symbol},\field{name},\field{symbolplural},\field{plural}}, + \marg{\field{name},\field{symbol},\field{plural},\field{symbolplural}} +]{dual-indexsymbol-map} +\end{codeenv} + +\optsection[\subsubsection]{dual-indexabbrv-map} + +This is like \csopt{dual-entry-map} but applies to both the dual +\atentry{dualindexabbreviation} and tertiary +\atentry{tertiaryindexabbreviationentry} entry types. +The default setting is: +\begin{codeenv} +\csopt[ + \marg{\field{name}}, + \marg{\field{name}} +]{dual-indexabbrv-map} +\end{codeenv} + +\subsection{Dual Back-Links} +\label{sec:dualoptsbacklinks} + +\optsection[\subsubsection]{dual-entry-backlink} + +This is a boolean setting. If \meta{boolean} is missing \optfmt{true} +is assumed. + +When used with \atentry{dualentry}, if \meta{boolean} is +\optfmt{true}, this will wrap the contents of the first mapped field +with \gls{bibglshyperlink}. The field is obtained from the first +mapping listed in \csopt{dual-entry-map}. + +For example, if the document contains: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt{dual-entry-backlink}, + \csopt[ + \marg{\field{name},\field{plural},\field{description},\field{descriptionplural}}, + \marg{\field{description},\field{descriptionplural},\field{name},\field{plural}} + ]{dual-entry-map}, + \csopt[entries-dual]{src}} +\end{codeenv} +and if the \ext{bib} file contains: +\begin{codeenv} +\atentry{dualentry}\marg{child, + \field{name}=\marg{child}, + \field{plural}=\marg{children}, + \field{description}=\marg{enfant} +} +\end{codeenv} +Then the definition of the primary entry (\code{child}) in the +\ext{glstex} file will set the \field{description} field to: +\begin{codeenv} +\gls{bibglshyperlink}\marg{enfant}\marg{dual.child} +\end{codeenv} +and the dual entry (\code{dual.child}) will have the +\field{description} field set to: +\begin{codeenv} +\gls{bibglshyperlink}\marg{child}\marg{child} +\end{codeenv} +This use of the wrapper \gls{bibglshyperlink} (rather than explicitly +using \ics{glshyperlink}) and inserting the actual field value +(rather than using commands like \ics{glsentryname}) allows it +to work with \ics{makefirstuc} if the field requires a case-change. + +The reason the \field{description} field is chosen for the modification is +because the first field listed in \meta{list1} of \csopt{dual-entry-map} +is the \field{name} field which maps to \field{description} (the +first field in the second list \meta{list2}). This means that the hyperlink for +the dual entry should be put in the \field{description} field. + +For the primary entry, the \field{name} field is looked up in the +second list from the \csopt{dual-entry-map} setting. This is the +third item in this second list, so the third item in the first list +is selected, which also happens to be the \field{description} field, +so the hyperlink for the primary entry is put in the +\field{description} field. + +\optsection[\subsubsection]{dual-abbrv-backlink} + +This is analogous to \csopt{dual-entry-backlink} but for entries +defined with \atentry{dualabbreviation} instead of +\atentry{dualentry}. + +\optsection[\subsubsection]{dual-symbol-backlink} + +This is analogous to \csopt{dual-entry-backlink} but for entries +defined with \atentry{dualsymbol} instead of \atentry{dualentry}. + +\optsection[\subsubsection]{dual-abbrventry-backlink} + +Analogous to \csopt{dual-entry-backlink} but for entries +defined with \atentry{dualabbreviationentry} instead of +\atentry{dualentry}. This setting can be problematic as the +backlinks rely on the relevant field being known to \bibgls. +Since the abbreviation style typically sets the \field{name} +field (and sometimes the \field{description} field as well), you may +find that no backlink appears. A simple workaround is to +use \csopt{dual-field} (or \csopt[dual]{dual-field}) +to store the dual label in the \field{dual} field, and then +use a style that checks for this field and adds the backlink. + +With \sty{glossaries-extra} v1.30+ you can use: +\nosecdef{GlsXtrDualBackLink} +which encapsulates \meta{text} with a hyperlink to the dual. +The \meta{label} identifies the entry that requires a backlink. +The dual's label is obtained from the field given by: +\nosecdef{GlsXtrDualField} +which defaults to \field{dual}. Note that if you assign a +different field label with \csopt{dual-field}, then you will +need to redefine \gls{GlsXtrDualField} as appropriate. + +For example: +\begin{codeenv} +\cs{renewcommand}*\marg{\ics{glsuserdescription}}[2]\marg{\comment{} + \gls{GlsXtrDualBackLink}\marg{\ics{glslonguserfont}\marg{\idx{param}1}}\marg{\idx{param}2}\comment{} +} +\cs{setabbreviationstyle}\marg{\abbrstyle{long-short-user}} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt{dual-field}} +\end{codeenv} + +\optsection[\subsubsection]{dual-entryabbrv-backlink} + +As \csopt{dual-abbrventry-backlink} but for entries +defined with \atentry{dualentryabbreviation} instead of +\atentry{dualabbreviationentry}. + +\optsection[\subsubsection]{dual-indexentry-backlink} + +This is analogous to \csopt{dual-entry-backlink} but for entries +defined with \atentry{dualindexentry} instead of +\atentry{dualentry}. + +\optsection[\subsubsection]{dual-indexsymbol-backlink} + +This is analogous to \csopt{dual-entry-backlink} but for entries +defined with \atentry{dualindexsymbol} and +\atentry{dualindexnumber}. + +\optsection[\subsubsection]{dual-indexabbrv-backlink} + +This is analogous to \csopt{dual-entry-backlink} but for entries +defined with \atentry{dualindexabbreviation} and +\atentry{tertiaryindexabbreviationentry}. + +\optsection[\subsubsection]{dual-backlink} + +Shortcut for: +\begin{flushleft}\obeylines +\csopt[\meta{boolean}]{dual-entry-backlink}, +\csopt[\meta{boolean}]{dual-abbrventry-backlink}, +\csopt[\meta{boolean}]{dual-abbrv-backlink}, +\csopt[\meta{boolean}]{dual-symbol-backlink}, +\csopt[\meta{boolean}]{dual-indexentry-backlink}, +\csopt[\meta{boolean}]{dual-indexsymbol-backlink}, +\csopt[\meta{boolean}]{dual-indexabbrv-backlink} +\end{flushleft} + +\section{Tertiary Entries} + +\optsection{tertiary-prefix} + +This option indicates the prefix to use for the tertiary entries. The +default value is \idprefix{tertiary} (including the terminating period). + +As from version 1.8, the tertiary label prefix is identified +in the \ext{glstex} file with: +\begin{codeenv} +\format{bibglstertiaryprefixlabel} +\end{codeenv} + +\optsection{tertiary-type} + +This option indicates that the tertiary entries should have +their \field{type} field set to \meta{value}. If \meta{value} is +empty the \field{type} is left unchanged. Unlike +the \csopt{type} and \csopt{dual-type} options, there are no +recognised keywords. + +\optsection{tertiary-category} + +This option indicates that the tertiary entries should have +their \field{category} field set to \meta{value}. If \meta{value} is +empty the \field{category} is left unchanged. Unlike +the \csopt{category} and \csopt{dual-category} options, there are no +recognised keywords. + +\chapter{Provided Commands} +\label{sec:bibglscs} + +When \bibgls\ creates the \iext{glstex} file, it writes some +definitions for custom commands in the form \csfmt{bibgls\ldots} which +may be changed as required. The command definitions all use +\ics{providecommand} which means that you can define the command with +\ics{newcommand} before the resource file is loaded. + +Note that if you try to redefine any of these commands after the +resource file has been loaded with \ics{renewcommand}, you will get +an error on the first \LaTeX\ run when the \ext{glstex} file doesn't +exist. You may prefer to use \ics{glsrenewcommand} instead, which +will generate a warning instead of an error. + +Since many of the commands are actually used within the \ext{glstex} +file, it's best to use \cs{newcommand} before the first +\idx{resourceset} and \cs{renewcommand} between \idxpl{resourceset} +if adjustments are necessary. + + +\section{Entry Definitions} +\label{sec:newentrydefs} + +This section lists the commands (\csfmt{bibglsnew\ldots}) used to +define entries. Note that the entry definition commands are +actually used when \TeX\ inputs the resource file, so redefining +them after the resource file is loaded won't have an effect on the +entries defined in that resource file (but will affect entries defined +in subsequent resource files). Each provided command is defined in +the \ext{glstex} file immediately before the first entry that +requires it, so only the commands that are actually needed are +provided. + +The \field{sort} key may be set within the \ext{glstex} entry +definition, but its value is usually not required in the document +unless you are using a hybrid method with \styopt[alsoindex]{record}. + +After each entry is defined, if it has any associated locations and +the default \csopt[true]{save-loclist} is set, then the +locations are added using: +\nosecformatdef{glsxtrfieldlistadd} +Any additional fields that don't have associated keys are then set (if +required) with \ics{GlsXtrSetField}. + +\cssection{bibglsnewentry} + +\formatdef{bibglsnewentry} +This command is used to define terms identified with the +\atentry{entry} type. The definition provided in the \ext{glstex} +file is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewentry}}[4]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{} +} +\end{codeenv} +This uses the starred form \ics{longnewglossaryentry*} that +doesn't automatically append \ics{nopostdesc} (which interferes with +the post-description hooks provided by category attributes). + +\cssection{bibglsnewsymbol} + +\formatdef{bibglsnewsymbol} +This command is used to define terms identified with the +\atentry{symbol} type. The definition provided in the \ext{glstex} +file is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewsymbol}}[4]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{sort}=\marg{\idx{param}1},\field{category}=\marg{symbol},\idx{param}2}\marg{\idx{param}4}\comment{} +} +\end{codeenv} +Note that this sets the \field{sort} field to the label, but this +may be overridden by the \meta{options} if the \field{sort} field +was supplied or if \bibgls\ has determined the value whilst sorting +the entries. + +This also sets the \field{category} to \optfmt{symbol}, but again this may +be overridden by \meta{options} if the entry had the \field{category} +field set in the \ext{bib} file or if the \field{category} was +overridden with \csopt[\meta{value}]{category}. + +\cssection{bibglsnewnumber} + +\formatdef{bibglsnewnumber} +This command is used to define terms identified with the +\atentry{number} type. The definition provided in the \ext{glstex} +file is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewnumber}}[4]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{sort}=\marg{\idx{param}1},\field{category}=\marg{number},\idx{param}2}\marg{\idx{param}4}\comment{} +} +\end{codeenv} +This is much the same as \gls{bibglsnewsymbol} above but sets the +\field{category} to \optfmt{number}. Again the \field{sort} and +\field{category} keys may be overridden by \meta{options}. + +\cssection{bibglsnewindex} + +\formatdef{bibglsnewindex} +This command is used to define terms identified with the +\atentry{index} type. The definition provided in the \ext{glstex} +file is: +\begin{codeenv} +\cs{providecommand}*\marg{\gls{bibglsnewindex}}[2]\marg{\comment{} + \gls{newglossaryentry}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}1},\field{category}=\marg{index},\field{description}=\marg{},\idx{param}2}\comment{} +} +\end{codeenv} +This makes the \field{name} default to the \meta{label}, assigns +the \field{category} to \code{index} and sets an empty +\field{description}. These settings may be overridden by +\meta{options}. + +Note that the \field{description} doesn't include +\ics{nopostdesc} to allow for the \idx{postdescriptionhook} used by +category attributes. + +\cssection{bibglsnewindexplural} + +\formatdef{bibglsnewindexplural} +This command is used to define terms identified with the +\atentry{indexplural} type. The definition provided in the \ext{glstex} +file is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewindexplural}}[3]\marg{\comment{} + \gls{newglossaryentry}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{category}=\marg{indexplural},\field{description}=\marg{},\idx{param}2}\comment{} +} +\end{codeenv} +This assigns the \field{category} to \code{indexplural} and sets an empty +\field{description}. These settings may be overridden by \meta{options}. + +\cssection{bibglsnewabbreviation} + +\formatdef{bibglsnewabbreviation} +This command is used to define terms identified with the +\atentry{abbreviation} type. The definition provided in the \ext{glstex} +file is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewabbreviation}}[4]\marg{\comment{} + \gls{newabbreviation}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{} +} +\end{codeenv} +Since this uses \gls{newabbreviation}, it obeys the +abbreviation style for its given \field{category} (which may have +been set in \meta{options}, either from the \field{category} field +in the \ext{bib} file or through the \csopt{category} option). +Similarly the \field{type} will obey \ics{glsxtrabbrvtype} unless +the value is supplied in the \ext{bib} file or through the +\csopt{type} option. + +\cssection{bibglsnewacronym} + +\formatdef{bibglsnewacronym} +This command is used to define terms identified with the +\atentry{acronym} type. The definition provided in the \ext{glstex} +file is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewacronym}}[4]\marg{\comment{} + \gls{newacronym}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{} +} +\end{codeenv} +This works in much the same way as \gls{bibglsnewabbreviation}. +Remember that with the \styfmt{glossaries-extra} package \gls{newacronym} +is redefined to just use \gls{newabbreviation} with the default \field{type} +set to \ics{acronymtype} and the default \field{category} set to +\code{acronym}. + +\cssection{bibglsnewdualentry} + +\formatdef{bibglsnewdualentry} +This command is used to define terms identified with the +\atentry{dualentry} type. The definition provided in the \ext{glstex} +file is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewdualentry}}[4]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{} +} +\end{codeenv} + +\cssection{bibglsnewdualindexentry} + +\formatdef{bibglsnewdualindexentry} +This command is used to define primary terms identified with the +\atentry{dualindexentry} type. The definition provided in the \ext{glstex} +file is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewdualindexentry}}[4]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{category}=\marg{index},\idx{param}2}\marg{}\comment{} +} +\end{codeenv} +Note that this definition ignores the \meta{description} argument. + +\cssection{bibglsnewdualindexentrysecondary} + +\formatdef{bibglsnewdualindexentrysecondary} +This command is used to define secondary terms identified with the +\atentry{dualindexentry} type. The definition provided in the \ext{glstex} +file is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewdualindexentrysecondary}}[4]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{} +} +\end{codeenv} + +\cssection{bibglsnewdualindexsymbol} + +\formatdef{bibglsnewdualindexsymbol} +This command is used to define primary terms identified with the +\atentry{dualindexsymbol} type. The definition provided in the \ext{glstex} +file is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewdualindexsymbol}}[5]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{category}=\marg{index},\field{symbol}=\marg{\idx{param}4},\idx{param}2}\marg{}\comment{} +} +\end{codeenv} +Note that this definition ignores the \meta{description} argument. + +\cssection{bibglsnewdualindexsymbolsecondary} + +\formatdef{bibglsnewdualindexsymbolsecondary} +This command is used to define secondary terms identified with the +\atentry{dualindexsymbol} type. The definition provided in the \ext{glstex} +file is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewdualindexsymbolsecondary}}[5]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{category}=\marg{symbol},\field{symbol}=\marg{\idx{param}4},\idx{param}2}\marg{\idx{param}5}\comment{} +} +\end{codeenv} + +\cssection{bibglsnewdualindexnumber} + +\formatdef{bibglsnewdualindexnumber} +This command is used to define primary terms identified with the +\atentry{dualindexnumber} type. The definition provided in the \ext{glstex} +file is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewdualindexnumber}}[5]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{category}=\marg{index},\field{symbol}=\marg{\idx{param}4},\idx{param}2}\marg{}\comment{} +} +\end{codeenv} +Note that this definition ignores the \meta{description} argument. + +\cssection{bibglsnewdualindexnumbersecondary} + +\formatdef{bibglsnewdualindexnumbersecondary} +This command is used to define secondary terms identified with the +\atentry{dualindexnumber} type. The definition provided in the \ext{glstex} +file is: +\begin{codeenv} +\cs{providecommand}\marg{\cs{bibglsnewdualindexnumbersecondary}}[5]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{category}=\marg{number},\field{symbol}=\marg{\idx{param}4},\idx{param}2}\marg{\idx{param}5}\comment{} +} +\end{codeenv} + +\cssection{bibglsnewdualindexabbreviation} + +\formatdef{bibglsnewdualindexabbreviation} +This command is used to define primary terms identified with the +\atentry{dualindexabbreviation} type. The default definition provided in +the \ext{glstex} file is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewdualindexabbreviation}}[7]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\comment{} + \field{name}=\marg{\cs{protect}\gls{bibglsuseabbrvfont}\marg{\idx{param}4}\marg{\cs{glscategory}\marg{\idx{param}2}}},\comment{} + \field{category}=\marg{index},\idx{param}3}\marg{}\comment{} +} +\end{codeenv} +In this case \meta{dual-label} is the dual entry's label, which is used +to fetch the category label in \gls{bibglsuseabbrvfont}. (The +\field{category} field for the dual isn't used since a custom +definition of +\gls!{bibglsnewdualindexabbreviationsecondary} may override the +value known to \bibgls.) + +Note that (as shown above) with the default +\csopt[short]{abbreviation-name-fallback} the \field{name} uses: +\nosecformatdef{bibglsuseabbrvfont} +to format the name, which ensures that it uses the same font as the +short form for the dual abbreviation. This will use +\ics{glsuseabbrvfont} if it's defined otherwise it will be defined +to replicate that command. If \csopt{abbreviation-name-fallback} is +set to some other field then the \field{name} uses: +\nosecformatdef{bibglsuselongfont} +instead, which ensures that it uses the same font as the +long form for the dual abbreviation. + +\cssection{bibglsnewdualindexabbreviationsecondary} + +\formatdef{bibglsnewdualindexabbreviationsecondary} +This command is used to define secondary terms identified with the +\atentry{dualindexabbreviation} entry type. +The definition provided in the \ext{glstex} file is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewdualindexabbreviationsecondary}}[6]\marg{\comment{} + \cs{ifstrempty}\marg{\idx{param}6}\comment{} + \marg{\gls{newabbreviation}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}4}\marg{\idx{param}5}}\comment{} + \marg{\gls{newabbreviation}\oarg{\idx{param}2,\field{description}=\marg{\idx{param}6}}\marg{\idx{param}1}\marg{\idx{param}4}\marg{\idx{param}5}}\comment{} +} +\end{codeenv} +This ensures that a missing or empty \field{description} doesn't +interfere with the abbreviation style. + +\cssection{bibglsnewdualabbreviationentry} + +\formatdef{bibglsnewdualabbreviationentry} +This command is used to define primary terms identified with the +\atentry{dualabbreviationentry} type. The definition provided in the \ext{glstex} +file is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewdualabbreviationentry}}[5]\marg{\comment{} + \gls{newabbreviation}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{} +} +\end{codeenv} +Note that this definition ignores the \meta{description} argument. + +\cssection{bibglsnewdualabbreviationentrysecondary} + +\formatdef{bibglsnewdualabbreviationentrysecondary} +This command is used to define secondary terms identified with the +\atentry{dualabbreviationentry} type. The definition provided in the \ext{glstex} +file is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewdualabbreviationentrysecondary}}[5]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\idx{param}2}\marg{\idx{param}5}\comment{} +} +\end{codeenv} +Note that this definition ignores the \meta{short} and \meta{long} +arguments (which will typically be empty unless the default mappings +are changed). + +\cssection{bibglsnewdualentryabbreviation} + +\formatdef{bibglsnewdualentryabbreviation} +This command is used to define primary terms identified with the +(now deprecated) entry type +\atentry{dualentryabbreviation}. The definition provided in the \ext{glstex} +file is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewdualentryabbreviation}}[5]\marg{\comment{} + \gls{newabbreviation}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{} +} +\end{codeenv} +Note that this definition ignores the \meta{description} argument. + +\cssection{bibglsnewdualentryabbreviationsecondary} + +\formatdef{bibglsnewdualentryabbreviationsecondary} +This command is used to define secondary terms identified with the +(now deprecated) entry type +\atentry{dualentryabbreviation}. The definition provided in the \ext{glstex} +file is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewdualentryabbreviationsecondary}}[5]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\idx{param}2}\marg{\idx{param}5}\comment{} +} +\end{codeenv} +Note that this definition ignores the \meta{short} and \meta{long} +arguments (which will typically be empty unless the default mappings +are changed). + +\cssection{bibglsnewdualsymbol} + +\formatdef{bibglsnewdualsymbol} +This command is used to define terms identified with the +\atentry{dualsymbol} type. The definition provided in the \ext{glstex} +file is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewdualsymbol}}[4]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{sort}=\marg{\idx{param}1},\field{category}=\marg{symbol},\idx{param}2}\marg{\idx{param}4}} +\end{codeenv} + +\cssection{bibglsnewdualnumber} + +\formatdef{bibglsnewdualnumber} +This command is used to define terms identified with the +\atentry{dualnumber} type. The definition provided in the \ext{glstex} +file is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewdualnumber}}[4]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{sort}=\marg{\idx{param}1},\field{category}=\marg{symbol},\idx{param}2}\marg{\idx{param}4}} +\end{codeenv} + +\cssection{bibglsnewdualabbreviation} + +\formatdef{bibglsnewdualabbreviation} +This command is used to define terms identified with the +\atentry{dualabbreviation} type where the \field{duallong} field +is swapped with the \field{long} field and the \field{dualshort} +field is swapped with the \field{short} field. The definition provided in the +\ext{glstex} file is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewdualabbreviation}}[4]\marg{\comment{} + \gls{newabbreviation}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{} +} +\end{codeenv} + +\cssection{bibglsnewdualacronym} + +\formatdef{bibglsnewdualacronym} +This command is used to define terms identified with the +\atentry{dualacronym} type. The definition provided in the \ext{glstex} +file is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewdualacronym}}[4]\marg{\comment{} + \gls{newacronym}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{} +} +\end{codeenv} +This works in much the same way as \gls{bibglsnewdualabbreviation}. +Remember that with the \styfmt{glossaries-extra} package \gls{newacronym} +is redefined to just use \gls{newabbreviation} with the default \field{type} +set to \ics{acronymtype} and the default \field{category} set to +\code{acronym}. + +\cssection{bibglsnewtertiaryindexabbreviationentry} + +\formatdef{bibglsnewtertiaryindexabbreviationentry} +This is used to define primary terms identified with the +\atentry{tertiaryindexabbreviationentry} type. It's essentially +the same as \gls!{bibglsnewdualindexabbreviation}. +The definition provided in the \ext{glstex} file is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewtertiaryindexabbreviationentry}}[7]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\comment{} + \field{name}=\marg{\cs{protect}\gls{bibglsuseabbrvfont}\marg{\idx{param}4}\marg{\cs{glscategory}\marg{\idx{param}2}}},\comment{} + \field{category}=\marg{index},\idx{param}3}{}\comment{} +} +\end{codeenv} + +\cssection{bibglsnewtertiaryindexabbreviationentrysecondary} + +\formatdef{bibglsnewtertiaryindexabbreviationentrysecondary} +This command is used to define both the secondary and tertiary terms identified with the +\atentry{tertiaryindexabbreviationentry} type. The secondary +term is an abbreviation and the tertiary term is a regular entry. +The definition written to the \ext{glstex} file is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewtertiaryindexabbreviationentrysecondary}}[8]\marg{\comment{} + \gls{newabbreviation}\oarg{\idx{param}3}\marg{\idx{param}1}\marg{\idx{param}6}\marg{\idx{param}7}\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}2}\comment{} + \marg{\field{name}=\marg{\cs{protect}\gls{bibglsuselongfont}\marg{\idx{param}7}\marg{\cs{glscategory}\marg{\idx{param}1}}},\idx{param}4}\comment{} + \marg{\idx{param}8}\comment{} +} +\end{codeenv} +The \meta{label} is the label for the secondary (abbreviation) entry +and \meta{tertiary-label} is the label for the tertiary (regular) +entry. The fifth argument (\meta{primary name}) isn't used but is +provided if required for a custom redefinition. +The \field{name} field for the tertiary is obtained from +the \meta{long} argument encapsulated by \gls{bibglsuselongfont} +to format the name, which ensures that it uses the same font as the +long form for the dual abbreviation. This will use +\ics{glsuselongfont} if it's defined otherwise it will be defined to +replicate that command. + +\cssection{bibglsnewbibtexentry} + +\formatdef{bibglsnewbibtexentry} +This command is used to define the main term identified with +\atentry{bibtexentry}. +The definition written to the \ext{glstex} file is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewbibtexentry}}[4]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{} +} +\end{codeenv} + +\cssection{bibglsnewcontributor} + +\formatdef{bibglsnewcontributor} +This command is used to define terms identified with +\atentry{contributor} (typically implicitly created through +\atentry{bibtexentry}). +The definition written to the \ext{glstex} file is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewcontributor}}[4]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{} +} +\end{codeenv} + +\cssection{bibglsnewprogenitor} + +\formatdef{bibglsnewprogenitor} +This command is used to define the main terms created by +\atentry{progenitor}. The definition is written to the \ext{glstex} +file as: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewprogenitor}}[4]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{} +} +\end{codeenv} + +\cssection{bibglsnewspawnindex} + +\formatdef{bibglsnewspawnindex} +This command is used to define the main terms created by +\atentry{spawnindex}. The definition is written to the \ext{glstex} +file as: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewspawnindex}}[4]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{} +} +\end{codeenv} + +\cssection{bibglsnewspawnedindex} + +\formatdef{bibglsnewspawnedindex} +This command is used to define the terms spawned by +\atentry{progenitor} or \atentry{spawnindex}. The definition is written +to the \ext{glstex} file as: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewspawnedindex}}[2]\marg{\comment{} + \gls{newglossaryentry}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}1},\field{category}={index},\field{description}=\marg{},\idx{param}2}\comment{} +} +\end{codeenv} + +\cssection{bibglsnewspawnindexplural} + +\formatdef{bibglsnewspawnindexplural} +This command is used to define the main terms created by +\atentry{spawnindexplural}. The definition is written to the \ext{glstex} +file as: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewspawnindexplural}}[4]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{} +} +\end{codeenv} + +\cssection{bibglsnewspawnedindexplural} + +\formatdef{bibglsnewspawnedindexplural} +This command is used to define the terms spawned by +\atentry{spawnindexplural}. +The definition is written to the \ext{glstex} file as: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewspawnedindexplural}}[3]\marg{\comment{} + \gls{newglossaryentry}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{category}=\marg{indexplural},\field{description}=\marg{},\idx{param}2}\comment{} +} +\end{codeenv} + +\cssection{bibglsnewspawnentry} + +\formatdef{bibglsnewspawnentry} +This command is used to define the main terms created by +\atentry{spawnentry}. The definition is written to the \ext{glstex} +file as: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewspawnentry}}[4]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{} +} +\end{codeenv} + +\cssection{bibglsnewspawnedentry} + +\formatdef{bibglsnewspawnedentry} +This command is used to define the terms spawned by \atentry{spawnentry}. +The definition is written to the \ext{glstex} file as: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewspawnedentry}}[4]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{} +} +\end{codeenv} + +\cssection{bibglsnewspawnabbreviation} + +\formatdef{bibglsnewspawnabbreviation} +This command is used to define the main terms created by +\atentry{spawnabbreviation}. The definition is written to the \ext{glstex} +file as: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewspawnabbreviation}}[4]\marg{\comment{} + \gls{newabbreviation}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{} +} +\end{codeenv} + +\cssection{bibglsnewspawnedabbreviation} + +\formatdef{bibglsnewspawnedabbreviation} +This command is used to define the terms spawned by \atentry{spawnabbreviation}. +The definition is written to the \ext{glstex} file as: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewspawnedabbreviation}}[4]\marg{\comment{} + \gls{newabbreviation}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{} +} +\end{codeenv} + +\cssection{bibglsnewspawnacronym} + +\formatdef{bibglsnewspawnacronym} +This command is used to define the main terms created by +\atentry{spawnacronym}. The definition is written to the \ext{glstex} +file as: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewspawnacronym}}[4]\marg{\comment{} + \gls{newacronym}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{} +} +\end{codeenv} + +\cssection{bibglsnewspawnedacronym} + +\formatdef{bibglsnewspawnedacronym} +This command is used to define the terms spawned by \atentry{spawnacronym}. +The definition is written to the \ext{glstex} file as: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewspawnedacronym}}[4]\marg{\comment{} + \gls{newacronym}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{} +} +\end{codeenv} + +\cssection{bibglsnewspawnsymbol} + +\formatdef{bibglsnewspawnsymbol} +This command is used to define the main terms created by +\atentry{spawnsymbol}. The definition is written to the \ext{glstex} +file as: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewspawnsymbol}}[4]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{} +} +\end{codeenv} + +\cssection{bibglsnewspawnedsymbol} + +\formatdef{bibglsnewspawnedsymbol} +This command is used to define the terms spawned by \atentry{spawnsymbol}. +The definition is written to the \ext{glstex} file as: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewspawnedsymbol}}[4]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{sort}=\marg{\idx{param}1},\field{category}=\marg{spawnedsymbol},\idx{param}2}\marg{\idx{param}4}} +\end{codeenv} + +\cssection{bibglsnewspawnnumber} + +\formatdef{bibglsnewspawnnumber} +This command is used to define the main terms created by +\atentry{spawnnumber}. The definition is written to the \ext{glstex} +file as: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewspawnnumber}}[4]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{} +} +\end{codeenv} + +\cssection{bibglsnewspawnednumber} + +\formatdef{bibglsnewspawnednumber} +This command is used to define the terms spawned by \atentry{spawnnumber}. +The definition is written to the \ext{glstex} file as: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewspawnednumber}}[4]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{sort}=\marg{\idx{param}1},\field{category}=\marg{spawnednumber},\idx{param}2}\marg{\idx{param}4}} +\end{codeenv} + +\cssection{bibglsnewspawndualindexentry} + +\formatdef{bibglsnewspawndualindexentry} +This command is used to define the \idx{progenitor}['s] primary term created by +\atentry{spawndualindexentry}. +The definition is written to the \ext{glstex} file as: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewspawndualindexentry}}[4]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{category}=\marg{index},\idx{param}2}{}\comment{} +} +\end{codeenv} +The \meta{description} argument is ignored. + +\cssection{bibglsnewspawndualindexentrysecondary} + +\formatdef{bibglsnewspawndualindexentrysecondary} +This command is used to define the \idx{progenitor}['s] secondary +(dual) term created by +\atentry{spawndualindexentry}. +The definition is written to the \ext{glstex} file as: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewspawndualindexentrysecondary}}[4]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{} +} +\end{codeenv} + +\section{Location Lists and Cross-References} +\label{sec:loclistdefs} + +These commands deal with the way the location lists and cross +references are formatted. The commands typically aren't used until +the entry information is displayed in the glossary, so you may +redefine these commands after the resource file has been loaded. + +\cssection{bibglsseesep} + +\formatdef{bibglsseesep} +Any entries that provide a \field{see} field (and that field hasn't +be omitted from the location list with \csopt[omit]{see}) will +have \gls{bibglsseesep} inserted between the \field{see} part and the +location list (unless there are no locations, in which case just +the \field{see} part is displayed without \gls{bibglsseesep}). + +This command is provided with: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsseesep}}\marg{, } +\end{codeenv} +You can define this before you load the \ext{bib} file: +\begin{codeenv} +\cs{newcommand}\marg{\gls{bibglsseesep}}\marg{; } +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}} +\end{codeenv} +Or you can redefine it afterwards: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}} +\cs{glsrenewcommand}\marg{\gls{bibglsseesep}}\marg{; } +\end{codeenv} + +\cssection{bibglsseealsosep} + +\formatdef{bibglsseealsosep} +This is like \gls{bibglsseesep} but is used with cross-reference +lists provided with the \field{seealso} field, if supported. + +\cssection{bibglsaliassep} + +\formatdef{bibglsaliassep} +This is like \gls{bibglsseesep} but is used with cross-reference +lists provided with the \field{alias} field. + +\cssection{bibglsusesee} + +\formatdef{bibglsusesee} +Displays the formatted cross-reference list stored in the +\field{see} field for the given entry. This just defaults to +\ics{glsxtrusesee}\margm{label}. + +\cssection{bibglsuseseealso} + +\formatdef{bibglsuseseealso} +Displays the formatted cross-reference list stored in the +\field{seealso} field for the given entry. This just defaults to +\ics{glsxtruseseealso}\margm{label}. + +\cssection{bibglsusealias} + +\formatdef{bibglsusealias} +Displays the formatted cross-reference stored in the +\field{alias} field for the given entry. This is defined to use +\ics{glsseeformat}. + +\cssection{bibglsdelimN} + +\formatdef{bibglsdelimN} +Separator between individual locations, except for the last. +This defaults to \ics{delimN}. + +\cssection{bibglslastDelimN} + +\formatdef{bibglslastDelimN} +Separator between penultimate and final individual locations. +This defaults to \code{,\idx{nbspchar}} to discourage lonely locations. + +\cssection{bibglscompact} + +\formatdef{bibglscompact} +The first argument \meta{pattern} indicates the location pattern: +\code{digit} for digits, \code{roman} for \idx!{lowercase} +Roman numerals, \code{ROMAN} for \idx!{uppercase} Roman +numerals and \code{alpha} for alphabetical locations. The actual +location is split into two parts, \meta{part1} and \meta{part2}. +The string concatenation \meta{part1}\meta{part2} forms the +actual location. + +This just does \meta{part2} by default. + +\cssection{bibglspassim} + +\formatdef{bibglspassim} +If \csopt{max-loc-diff} is greater than~1, then any ranges that have +skipped over gaps will be followed by \gls{bibglspassim}, which is +defined as: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglspassim}}\marg{ \gls{bibglspassimname}} +\end{codeenv} +You can define this before you load the \ext{bib} file: +\begin{codeenv} +\cs{newcommand}\marg{\gls{bibglspassim}}\marg{} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}} +\end{codeenv} +Or you can redefine it afterwards: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}} +\cs{glsrenewcommand}\marg{\gls{bibglspassim}}\marg{} +\end{codeenv} + +\cssection{bibglspassimname} + +\formatdef{bibglspassimname} +The default definition is obtained from the \langxml. For example, with +\file{bib2gls-en.xml} the provided definition is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglspassimname}}\marg{passim} +\end{codeenv} + +\cssection{bibglsrange} + +\formatdef{bibglsrange} +Explicit ranges formed using \glsopt[\idx{openrange}]{format} and +\glsopt[\idx{closerange}]{format} or \glsopt[\idx{openrange}\meta{csname}]{format} and +\glsopt[\idx{closerange}\meta{csname}]{format} (where \meta{csname} matches and is a +text-block command without the initial backslash) in the optional +argument of commands like \ics{gls} or \ics{glsadd} are encapsulated within +the argument of \gls{bibglsrange}. By default this simply does its +argument. This command is not used with ranges that are formed by collating +consecutive locations. + +\cssection{bibglsinterloper} + +\formatdef{bibglsinterloper} +If an explicit range conflicts with a record, a warning will be +issued and the conflicting record will be shifted to the front +of the range inside the argument of \gls{bibglsinterloper}. +The default definition just does \meta{location}\gls!{bibglsdelimN} +so that it fits neatly into the list. + +For example, suppose on page~4 of my document I start a range with: +\begin{codeenv*} +\cs{glsadd}\oarg{\glsaddopt[\idx{openrange}]{format}}\marg{sample} +\end{codeenv*} +and end it on page~9 with: +\begin{codeenv*} +\cs{glsadd}\oarg{\glsaddopt[\idx{closerange}]{format}}\marg{sample} +\end{codeenv*} +This forms an explicit range, but let's suppose on page~6 I +have: +\begin{codeenv} +\cs{gls}\oarg{\glsopt[\encap{hyperbf}]{format}}\marg{sample} +\end{codeenv} +This record conflicts with the explicit range (which doesn't include +\encap{hyperbf} in the format). This causes a warning and +the conflicting entry will be moved before the start of the +explicit range resulting in \textbf{6}, 4--9. + +Note that implicit ranges can't be formed from interlopers (nor can +implicit ranges be merged with explicit ones), +so if \code{\cs{gls}\oarg{\glsopt[\encap{hyperbf}]{format}}\marg{sample}} +also occurs on pages~7 and~8 then the result will be \textbf{6}, \textbf{7}, +\textbf{8}, 4--9. Either remove the explicit range or +remove the conflicting entries. (Alternatively, redefine +\gls{bibglsinterloper} to ignore its argument, which will +discard the conflicting entries.) + +\cssection{bibglspostlocprefix} + +\formatdef{bibglspostlocprefix} +If the \csopt{loc-prefix} option is on, \gls!{bibglslocprefix} will +be inserted at the start of location lists, and its default +definition includes \gls{bibglspostlocprefix} +placed after the prefix text. This command is provided with: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglspostlocprefix}}\marg{\cs{cs.space}} +\end{codeenv} +which puts a space between the prefix text and the location list. +You can define this before you load the \ext{bib} file: +\begin{codeenv} +\cs{newcommand}\marg{\gls{bibglspostlocprefix}}\marg{: } +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt{loc-prefix}} +\end{codeenv} +Or you can redefine it afterwards: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt{loc-prefix}} +\cs{glsrenewcommand}\marg{\gls{bibglspostlocprefix}}\marg{: } +\end{codeenv} + +\cssection{bibglslocprefix} + +\formatdef{bibglslocprefix} +If the \csopt{loc-prefix} option is on, this command will be +provided. If the glossary type has been provided by \csopt{type} +(and \csopt{dual-type} if there are any dual entries) then the +definition of \gls{bibglslocprefix} will be appended to the glossary +preamble for the given type (or types if there are dual entries). +For example, if the document has: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[main]{type},\csopt[p.,pp.]{loc-prefix},\csopt[entries]{src}} +\end{codeenv} +and there are no dual entries, then the following will be added to +the \ext{glstex} file: +\begin{codeenv} +\cs{apptoglossarypreamble}\oarg{main}\marg{\comment{} + \cs{providecommand}\marg{\gls{bibglslocprefix}}[1]\marg{\comment{} + \cs{ifcase}\idx{param}\idx{param}1 + \cmd{or} p.\gls{bibglspostlocprefix} + \cmd{else} pp.\gls{bibglspostlocprefix} + \cmd{fi} + }\comment{} +} +\end{codeenv} +However, if the \csopt{type} key is missing, then the following will +be added instead: +\begin{codeenv} +\cs{appto}\cs{glossarypreamble}\marg{\comment{} + \cs{providecommand}\marg{\gls{bibglslocprefix}}[1]\marg{\comment{} + \cs{ifcase}\idx{param}1 + \cmd{or} p.\gls{bibglspostlocprefix} + \cmd{else} pp.\gls{bibglspostlocprefix} + \cmd{fi} + }\comment{} +} +\end{codeenv} + +\cssection{bibglspagename} + +\formatdef{bibglspagename} +If \csopt[true]{loc-prefix} is used, then this command is provided +using the value of \idx{tag.page} from the \langxml. For example with \file{bib2gls-en.xml} the definition is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglspagename}}\marg{Page} +\end{codeenv} + +\cssection{bibglspagesname} + +\formatdef{bibglspagesname} +If \csopt[true]{loc-prefix} is used, then this command is provided +using the value of \idx{tag.pages} from the \langxml. For example with \file{bib2gls-en.xml} the definition is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglspagesname}}\marg{Pages} +\end{codeenv} + +\cssection{bibglslocsuffix} + +\formatdef{bibglslocsuffix} +If the \csopt{loc-suffix} option is on, this command will be +provided. If the glossary type has been provided by \csopt{type} +(and \csopt{dual-type} if there are any dual entries) then the +definition of \gls{bibglslocsuffix} will be appended to the glossary +preamble for the given type (or types if there are dual entries). + +This commands definition depends on the value provided by +\csopt{loc-suffix}. For example, with +\csopt[\ics{at}{\idx{periodchar}}]{loc-suffix} +the command is defined as: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglslocsuffix}}[1]\marg{\ics{at}.} +\end{codeenv} +(which ignores the argument). + +Whereas with \csopt[\meta{A}\dcomma\meta{B}\dcomma\meta{C}]{loc-suffix} +the command is defined as: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglslocsuffix}}[1]\marg{\cs{ifcase}\idx{param}1 \meta{A}\cmd{or} \meta{B}\cmd{else} \meta{C}\cmd{fi}} +\end{codeenv} + +Note that this is slightly different from \gls{bibglslocprefix} as +it includes the 0 case, which in this instance means that there were +no locations but there was a cross-reference. This command isn't +added when the location list is empty. + +\cssection{bibglsprimary} + +\formatdef{bibglsprimary} +When the \csopt{save-primary-locations} option is used, the primary +locations are stored in the \field{primarylocations} field +encapsulated with this command. The first argument is the number of +locations in the list. The second argument is the list of locations +formatted in the usual way. The default definition is to ignore the +first argument and simply do the second. + +\cssection{bibglslocationgroup} + +\formatdef{bibglslocationgroup} +When the \csopt{loc-counters} option is used, the locations +for each entry are grouped together according to the counter +(in the order specified in the value of \csopt{loc-counters}). +Each group of locations is encapsulated within +\gls{bibglslocationgroup}, where \meta{n} is the number +of locations within the group, \meta{counter} is the +counter name and \meta{list} is the formatted location sub-list. +By default, this simply does \meta{list}, but may be +defined (before the resources are loaded) or redefined +(after the resources are loaded) as required. + +For example: +\begin{codeenv} +\cs{newcommand}*\marg{\gls{bibglslocationgroup}}[3]\marg{\comment{} + \cs{ifnum}\idx{param}1=1 + \idx{param}2: + \cmd{else} + \idx{param}2s: + \cmd{fi} + \idx{param}3\comment{} +} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[equation,page]{loc-counters},\comment{group locations by counter} + \csopt[entries]{src}\comment{data in entries.bib} +} +\end{codeenv} +This will prefix each group with the counter name, if there's +only one location, or the counter name followed by \qt{s}, +if there are multiple locations within the group. + +There are various ways to adapt this to translate the counter +name to a different textual label, such as: +\begin{codeenv} +\cs{providecommand}\marg{\cmd{pagename}}\marg{Page} +\cs{providecommand}\marg{\cmd{pagesname}}\marg{Pages} +\cs{providecommand}\marg{\cmd{equationname}}\marg{Equation} +\cs{providecommand}\marg{\cmd{equationsname}}\marg{Equations} +\strut +\cs{newcommand}*\marg{\gls{bibglslocationgroup}}[3]\marg{\comment{} + \ics{ifnum}\idx{param}1=1 + \ics{ifcsdef}\marg{\idx{param}2name}\marg{\cs{csuse}\marg{\idx{param}2name}}\marg{\idx{param}2}: + \cmd{else} + \cs{ifcsdef}\marg{\idx{param}2sname}\marg{\cs{csuse}\marg{\idx{param}2sname}}\marg{\idx{param}2s}: + \cmd{fi} + \idx{param}3\comment{} +} +\end{codeenv} + +\cssection{bibglslocationgroupsep} + +\formatdef{bibglslocationgroupsep} +When the \csopt{loc-counters} option is set, this command +is used to separate each location sub-group. It may be defined +before the resources are loaded: +\begin{codeenv} +\cs{newcommand}*\marg{\gls{bibglslocationgroupsep}}\marg{; } +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[equation,page]{loc-counters},\comment{group locations by counter} + \csopt[entries]{src}\comment{data in entries.bib} +} +\end{codeenv} +or redefined after the resources are loaded: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[equation,page]{loc-counters},\comment{group locations by counter} + \csopt[entries]{src}\comment{data in entries.bib} +} +\strut +\cs{glsrenewcommand}*\marg{\gls{bibglslocationgroupsep}}\marg{; } +\end{codeenv} + +\cssection{bibglssupplemental} + +\formatdef{bibglssupplemental} +When the \csopt{supplemental-locations} option is used, the locations +from a supplementary document are encapsulated within the \meta{list} +part of \gls{bibglssupplemental}. The first argument \meta{n} +(ignored by default) is the number of supplementary locations. + +If multiple supplemental sources are permitted (that is, +\bibgls\ has detected that the document is using at least +version 1.36 of \sty{glossaries-extra}), then the \meta{list} +part will consist of sub-lists for each external source. In this +case, \meta{n} will be the total number of elements across +all the sub-lists. + +\cssection{bibglssupplementalsublist} + +\formatdef{bibglssupplementalsublist} +If multiple supplemental sources are permitted, this will be used +to format each sub-list, where \meta{n} (ignored by default) +is the number of elements in the sub-list, \meta{external document} +(ignored by default) is the external source and \meta{list} +is the list of supplementary locations in \meta{external document}. + +\cssection{bibglssupplementalsep} + +\formatdef{bibglssupplementalsep} +The separator between the main location list and the supplementary +location list. By default this is just \gls!{bibglsdelimN}. This may be +defined before the resources are loaded: +\begin{codeenv} +\cs{newcommand}\marg{\gls{bibglssupplementalsep}}\marg{; } +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[supplDoc]{supplemental-locations}, + \csopt[entries]{src}} +\end{codeenv} +or redefined after the resources are loaded: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[supplDoc]{supplemental-locations}, + \csopt[entries]{src}} +\strut +\cs{glsrenewcommand}\marg{\gls{bibglssupplementalsep}}\marg{; } +\end{codeenv} + +\cssection{bibglssupplementalsubsep} + +\formatdef{bibglssupplementalsubsep} +The separator between the supplementary +location sub-lists. By default this is just \gls!{bibglsdelimN}. + +\cssection{bibglshrefchar} + +\formatdef{bibglshrefchar} +Expands to a literal percent character followed by \meta{hex}. The +second argument is ignored. + +\cssection{bibglshrefunicode} + +\formatdef{bibglshrefunicode} +Expands to the second argument. The first argument is ignored. + +\section{Letter Groups} +\label{sec:lettergroupdefs} + +The commands listed in this section are provided for use with the +\longarg{group} switch and glossary styles that display the letter +group title. If these need their definitions altered, they should +be defined before the resource file is loaded if field expansion +is on (\longarg{expand-fields}) otherwise they may be redefined +afterwards. + +The base \isty{glossaries} package determines group titles through a fairly +simplistic rule. Both \idx!{makeindex} and \idx!{xindy} write the +line: +\nosecformatdef{glsgroupheading} +to the associated glossary file at the start of each new letter group. +For example, the \qt{A} letter group will be written as: +\begin{codeenv} +\gls{glsgroupheading}\marg{A} +\end{codeenv} +This is quite straightforward and the heading title can just be +\qt{A}. The \qt{Symbols} group is written as: +\begin{codeenv} +\gls{glsgroupheading}\marg{glssymbols} +\end{codeenv} +To allow for easy translation, the base \sty{glossaries} package has +the simple rule: +\begin{itemize} +\item if \csfmt{\meta{heading}groupname} exists use that; +\item otherwise just use \meta{heading}. +\end{itemize} +There's no \csfmt{Agroupname} provided, but \ics{glssymbolsgroupname} +is provided and is supported by the associated language modules, +such as \styfmt{glossaries-french}. (Similarly for the \qt{Numbers} +group.) + +The glossary styles that provide hyperlinks to the groups (such as +\glostyle{indexhypergroup}) use \meta{heading} to form the target +name. A problem arises when active characters occur in +\meta{heading}, which happens with extended characters and +\isty{inputenc}. + +The \sty{glossaries-extra} package (as from version 1.14) provides: +\nosecformatdef{glsxtrsetgrouptitle} +to set the title for a group with the given label. The internal +workings of \gls{glsgroupheading} are modified to use a slightly +altered rule: +\begin{itemize} +\item if a title has been set using +\gls{glsxtrsetgrouptitle}\margm{heading}\margm{title} for the given +\meta{heading}, use that; +\item if \csfmt{\meta{heading}groupname} exists, use that; +\item just use \meta{heading} for the title. +\end{itemize} +So if \gls{glsxtrsetgrouptitle} hasn't been used, it falls back on +the original rule. + +The problem is now how to make the indexing application use the +desired label in the argument of \gls{glsgroupheading} instead of selecting +the heading based on the first character of each sort value for each +top-level entry in that group. This can't be done with +\idx!{makeindex}, and with \idx!{xindy} it requires a custom language +module, which isn't a trivial task. + +With \bibgls, a different approach is used. The \iext{glstex} file +created isn't comparable to the \iext{gls} file created by +\idx!{makeindex} or \idx!{xindy}. There's nowhere for \bibgls\ to +write the \gls{glsgroupheading} line as it isn't creating the code +that typesets the glossary list. Instead it's creating the code that +defines the entries. The actual group heading is inserted by +\ics{printunsrtglossary} and it's only able to do this by checking if +the entry has a \field{group} field and comparing it to the previous +entry's \field{group} field. + +The behaviour of the group formation implemented by the sort +methods may be changed with \csopt{group-formation}. With any +setting other than \csopt[default]{group-formation}, the group label +is set to \format{bibglsunicodegroup} and the title is set to +\format{bibglsunicodegrouptitle} (see below) otherwise the label and +title are determined by the sort method. + +The collators used by the locale and letter-based rules save the +following information for each entry based on the first significant letter of +the \field{sort} field (if the letter is recognised as alphabetical, +according to the rule): +\begin{itemize} +\item \meta{title} The group's title. This is typically title-cased. +For example, if the rule recognises the digraph \qt{dz}, then the +title is \qt{Dz}. Exceptions to this are included in the \langxml. +If the key \idx{grouptitle.case.lc} exists, where +\meta{lc} is the \idx!{lowercase} version of \meta{title}, then the value +of that key is used instead. For example, the Dutch digraph \qt{ij} +should be converted to \qt{IJ}, so \file{bib2gls-en.xml} includes: +\begin{verbatim} +<entry key="grouptitle.case.ij">IJ</entry> +\end{verbatim} +(See the \longarg{group} switch for more details.) +\item \meta{letter} This is the actual letter at the start of the +given entry's \field{sort} field, which may be \idx!{lowercase} or may +contain diacritics that don't appear in \meta{title}. +\item \meta{id} A numeric identifier. This may be the collation key +or the code point for the given letter, depending on the sort +method. +\item \meta{type} The entry's glossary type. If not known, this will +be empty. (\bibgls\ won't know if you've modified the associated +\csfmt{bibglsnew\ldots} command to set the \field{type}. It can only +know the type if it's in the original \ext{bib} definition or is set +using resource options such as \csopt{type}.) +\end{itemize} + +The \field{group} field is then set using: +\begin{codeenv} +\field{group}=\marg{\gls{bibglslettergroup}\margm{title}\margm{letter}\margm{id}\margm{type}} +\end{codeenv} +This field needs to expand to a simple label, which \gls!{bibglslettergroup} +is designed to do. Note that non-letter groups are dealt with +separately (see below). + +\cssection{bibglssetlastgrouptitle} + +In the last resource (\ext{glstex}) file, after all the relevant +group titles have been set with the commands listed below, there's a +final title setting: +\formatdef{bibglssetlastgrouptitle} +This does nothing by default, but the arguments are set to +correspond to the group with the maximum id for that resource file. +It's provided as a convenient way of overriding the final group +title without the inconvenience of looking up the group label in the +\ext{glstex} file. If you have multiple glossaries or if you want to +override a different group, then you need to inspect the +\ext{glstex} file to work out the corresponding label (by finding +the \field{group} assignment for one of the entries in that group). + +The \meta{cs} argument is the control sequence used in the +\field{group} field to obtain the label from \meta{specs}. For +example, if the highest \meta{id} is 2147418112 from: +\begin{codeenv} +\field{group}=\marg{\gls{bibglslettergroup}\marg{Ø}\marg{Ø}\marg{2147418112}\marg{}} +\end{codeenv} +then the last group is identified with: +\begin{codeenv} +\gls{bibglssetlastgrouptitle}\marg{\gls{bibglslettergroup}}\marg{\marg{Ø}\marg{Ø}\marg{2147418112}\marg{}} +\end{codeenv} +In this case \meta{cs} is \gls{bibglslettergroup} and \meta{specs} +are the arguments for that command. If you want \gls{bibglssetlastgrouptitle} +to change the group title then you need to define it before the +\idx{resourceset}. For example: +\begin{codeenv} +\cs{newcommand}*\marg{\gls{bibglssetlastgrouptitle}}[2]\marg{\comment{} + \cs{glsxtrsetgrouptitle}\marg{\idx{param}1\idx{param}2}\marg{Foreign Words}} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}} +\end{codeenv} +If you need to change a particular group title, then it has to be +done after the \idx{resourceset}: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}} +\cs{glsxtrsetgrouptitle} + \marg{\gls{bibglslettergroup}\marg{\marg{Ø}\marg{Ø}\marg{2147418112}\marg{}}}\comment{label} + \marg{Foreign Words}\comment{title} +\end{codeenv} + +\cssection{bibglssetlettergrouptitle} + +For each \idx{lettergroup} that's detected, \bibgls\ will write the line: +\formatdef{bibglssetlettergrouptitle} +in the \ext{glstex} file, which sets the group's title using: +\begin{codeenv} +\format{glsxtrsetgrouptitle} +\end{codeenv} +where the \meta{group label} part matches the corresponding \field{group} +value. + +Note that \gls{bibglssetlettergrouptitle} only has a single +argument, but that argument contains the four arguments needed by +\gls!{bibglslettergroup} and \gls!{bibglslettergrouptitle}. +These arguments are as described above. + +If \gls{glsxtrsetgrouptitle} has been defined (\sty{glossaries-extra} +version 1.14 onwards), then \gls{bibglssetlettergrouptitle} will be +defined as: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglssetlettergrouptitle}}[1]\marg{\comment{} + \cs{glsxtrsetgrouptitle}\marg{\gls{bibglslettergroup}\idx{param}1}\marg{\gls{bibglslettergrouptitle}\idx{param}1}} +\end{codeenv} +If an earlier version of \sty{glossaries-extra} is used, then this +function can't be supported and the command will be defined to +simply ignore its argument. This will fall back on the original +method of just using \meta{title} as the label. + +Since \gls{bibglssetlettergrouptitle} is used in the \ext{glstex} file to +set the group titles, the associated commands need to be defined +before the resource file is loaded if their definitions require +modification. After the resource file has been loaded, you can +adjust the title of a specific group, but you'll need to check the +\ext{glstex} file for the appropriate arguments. For example, if the +\ext{glstex} file contains: +\begin{codeenv} +\gls{bibglssetlettergrouptitle}\marg{\marg{\AE}\marg{\ae}\marg{7274496}\marg{}} +\end{codeenv} +but you actually want the group title to appear as \qt{\AE\ (AE)} +instead of just \qt{\AE}, then after the resource file has been +loaded you can do: +\begin{codeenv} +\gls{glsxtrsetgrouptitle} + \marg{\gls{bibglslettergroup}\marg{\AE}\marg{\ae}\marg{7274496}\marg{}}\comment{label} + \marg{\AE\ (AE)}\comment{title} +\end{codeenv} + +\cssection{bibglslettergroup} + +\formatdef{bibglslettergroup} +This command is used to determine the \idx{lettergroup} label. The +default definition is \meta{type}\meta{id}, which ensures that no +problematic characters occur in the label since \meta{type} can't +contains special characters and \meta{id} is numeric. The +\meta{type} is included in case there are multiple glossaries, since +the hyperlink name must be unique. + +\cssection{bibglslettergrouptitle} + +\formatdef{bibglslettergrouptitle} +This command is used to determine the \idx{lettergroup} title. +The default definition is \ics{unexpanded}\margm{title}, which guards +against any expansion issues that may arise with characters outside +the basic Latin set. + +For example: +\begin{codeenv} +\atentry{entry}\marg{angstrom, + \field{name}=\marg{\cs{AA} ngstr\cs{umlaut}om} + \field{description}=\marg{a unit of length equal to one hundred-millionth +of a centimetre} +} +\end{codeenv} +The \field{sort} value is \qtt{\AA ngstr\"om}. With \csopt[en]{sort} +the \meta{title} part will be \code{A} but with \csopt[sv]{sort} +the \meta{title} part will be \code{\AA}. In both cases the +\meta{letter} argument will be \code{\AA}. + +Take care if you are using a script that needs encapsulating. For +example, with the \isty{CJKutf8} package the \idx{CJK} characters need to +be placed within the \env{CJK} environment, so any letter group +titles that contain \idx{CJK} characters will need special attention. + +For example, suppose the \ext{bib} file contains entries in the +form: +\begin{codeenv} +\atentry{dualentry}\marg{\meta{label}, + \field{name} = \marg{\gls{cjkname}\margm{\idx{CJK} characters}}, + \field{description} = \margm{English translation} +} +\end{codeenv} +and the document contains: +\begin{codeenv} +\cmd{usepackage}\marg{CJKutf8} +\cmd{usepackage}[\styopt{record},\styopt[indexgroup]{style},\styopt{nomain}]\marg{glossaries-extra} +\strut +\cs{newglossary*}\marg{japanese}\marg{Japanese to English} +\cs{newglossary*}\marg{english}\marg{English to Japanese} +\strut +\ics{newrobustcmd}\marg{\gls{cjkname}}[1]\marg{\cmd{begin}\marg{CJK}\marg{UTF8}\marg{min}\idx{param}1\cmd{end}\marg{CJK}} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[testcjk]{src},\comment{bib file} + \csopt[ja-JP]{sort},\comment{locale used to sort primary entries} + \csopt[en-GB]{dual-sort},\comment{locale used to sort secondary entries} + \csopt[japanese]{type},\comment{put the primary entries in the 'japanese' glossary} + \csopt[english]{dual-type},\comment{put the dual entries in the 'english' glossary} + \csopt[en.]{dual-prefix} +} +\end{codeenv} +then \idx{CJK} characters will appear in the \meta{title} argument of +\gls{bibglslettergrouptitle} which causes a problem because they need +to be encapsulated within the \env{CJK} environment. This can be more +conveniently done with the user supplied \inlinedef{cjkname}, but the \idx{CJK} +characters need to be protected from expansion so \ics{unexpanded} is +also needed. The new definition of \gls{bibglslettergrouptitle} needs +to be defined before \gls{GlsXtrLoadResources}. For example: +\begin{codeenv} +\cs{newcommand}\marg{\gls{bibglslettergrouptitle}}[4]\marg{\cs{unexpanded}\marg{\gls{cjkname}\marg{\idx{param}1}}} +\end{codeenv} +There's a slight problem here in that the English letter group titles +also end up encapsulated. An alternative approach is to use the +\meta{type} part to provide different forms. For example: +\begin{codeenv} +\cs{newcommand}*\marg{\cmd{englishlettergroup}}[1]\marg{\idx{param}1} +\cs{newcommand}*\marg{\cmd{japaneselettergroup}}[1]\marg{\gls{cjkname}\marg{\idx{param}1}} +\cs{newcommand}\marg{\gls{bibglslettergrouptitle}}[4]\marg{\comment{} + \cs{unexpanded}\marg{\cs{csuse}\marg{\idx{param}4lettergroup}\marg{\idx{param}1}}} +\end{codeenv} + +\cssection{bibglssetothergrouptitle} + +The label and title for \idxpl{symbolgroup} +are dealt with in a similar way to the \idxpl!{lettergroup}, but in this +case the title is set using: +\formatdef{bibglssetothergrouptitle} +This is defined in an analogous manner: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglssetothergrouptitle}}[1]\marg{\comment{} + \cs{glsxtrsetgrouptitle}\marg{\gls{bibglsothergroup}\idx{param}1}\marg{\gls{bibglsothergrouptitle}\idx{param}1}} +\end{codeenv} +where the group label is obtained using \gls!{bibglsothergroup} and +the group title is obtained from \gls!{bibglsothergrouptitle}. +Note that since non-alphabetic characters don't have upper or lower +case versions, there are only three arguments. The other difference +between this and the letter group version is that the \meta{id} is +given in hexadecimal format (corresponding to the character code). + +For example, suppose my \ext{bib} file contains: +\begin{codeenv} +\atentry{entry}\marg{sauthor, + \field{name}=\marg{/Author}, + \field{description} = \marg{author string} +} +\end{codeenv} +If a locale sort is used, the leading slash \code{/} will be +ignored and this entry will belong to the \qt{A} letter group using +the letter commands described above. If, instead, one of the +character code sort methods are used, such as +\csopt[letter-case]{sort}, then this entry will be identified as +belonging to a symbol (or \qt{other}) group and the title will be +set using: +\begin{codeenv} +\gls{bibglssetothergrouptitle}\marg{\marg{/}\marg{2F}\marg{}} +\end{codeenv} + +\cssection{bibglsothergroup} + +\formatdef{bibglsothergroup} +This expands to the label for \idxpl{symbolgroup}. This just +defaults to \code{glssymbols} (ignoring all arguments), which +replicates the label used when \idx!{makeindex} or \idx!{xindy} +generate the glossary files. + +\cssection{bibglsothergrouptitle} + +\formatdef{bibglsothergrouptitle} +This expands to the title for \idxpl{symbolgroup}. This just +expands to \ics{glssymbolsgroupname} by default. + +\cssection{bibglssetemptygrouptitle} + +Used when the sort value degenerates to an empty string. This command +sets the label and title. +\formatdef{bibglssetemptygrouptitle} +(Note the inner group, as with the other similar +\csfmt{bibglsset\ldots grouptitle} commands.) + +\cssection{bibglsemptygroup} + +\formatdef{bibglsemptygroup} +This expands to the label for \idxpl{emptygroup}. This +defaults to \code{glssymbols} to make it consistent with +\idxpl{nonlettergroup} (since the sort value likely contained +unknown symbol commands). + +\cssection{bibglsemptygrouptitle} + +\formatdef{bibglsemptygrouptitle} +This expands to the group title for \idx{emptygroup}. This just +expands to \ics{glssymbolsgroupname} by default. + +\cssection{bibglssetnumbergrouptitle} + +The numeric sort methods (\tableref{tab:sortoptionsnumerical}) +all create \idxpl{numbergroup} instead of letter +or symbol groups. These behave in an analogous way to the above. +\formatdef{bibglssetnumbergrouptitle} +In this case \meta{value} is the actual numeric sort value, and +\meta{id} is a decimal number obtained from converting \meta{value} +to an integer. This command is defined as: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglssetnumbergrouptitle}}[1]\marg{\comment{} + \cs{glsxtrsetgrouptitle}\marg{\gls{bibglsnumbergroup}\idx{param}1}\marg{\gls{bibglsnumbergrouptitle}\idx{param}1}} +\end{codeenv} + +\cssection{bibglsnumbergroup} + +The \idx{numbergroup} label is obtained from: +\formatdef{bibglsnumbergroup} +This just defaults to \code{glsnumbers}. + +\cssection{bibglsnumbergrouptitle} + +The \idx{numbergroup} title is obtained from: +\formatdef{bibglsnumbergrouptitle} +This just defaults to \ics{glsnumbersgroupname}. + +\cssection{bibglssetdatetimegrouptitle} + +The date-time sort methods (\tableref{tab:sortoptionsdatetime}) +create \idxpl{datetimegroup}. These behave in an analogous way to the above. +\formatdef{bibglssetdatetimegrouptitle} +This command is defined as: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglssetdatetimegrouptitle}}[1]\marg{\comment{} + \cs{glsxtrsetgrouptitle} + \marg{\gls{bibglsdatetimegroup}\idx{param}1}\comment{} + \marg{\gls{bibglsdatetimegrouptitle}\idx{param}1}\comment{} +} +\end{codeenv} + +\cssection{bibglsdatetimegroup} + +\formatdef{bibglsdatetimegroup} + +This command is used for \idx{datetimegroup} labels with \optfmt{datetime} sorting +(\tableref{tab:sortoptionsdatetime}). This has ten arguments, which means a +little trickery is needed to deal with the tenth argument. +The default definition is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsdatetimegroup}}[9]\marg{\idx{param}1\idx{param}2\idx{param}3\ics{@firstofone}} +\end{codeenv} +This forms the group label from the year \meta{YYYY}, month \meta{MM}, +day \meta{DD} and \meta{type}. + +\cssection{bibglsdatetimegrouptitle} + +\formatdef{bibglsdatetimegrouptitle} + +This command is used for \idx{datetimegroup} titles with \optfmt{datetime} sorting +(\tableref{tab:sortoptionsdatetime}). +The default definition is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsdatetimegrouptitle}}[9]\marg{\idx{param}1-\idx{param}2-\idx{param}3\ics{@gobble}} +\end{codeenv} +This sets the title to the numeric +\code{\meta{YYYY}-\meta{MM}-\meta{DD}} +but may be redefined as appropriate. + +\cssection{bibglssetdategrouptitle} + +The date sort methods (\tableref{tab:sortoptionsdatetime}) +create \idxpl{dategroup} (the time isn't included). These behave in an +analogous way to the above. +\formatdef{bibglssetdategrouptitle} +This command is defined as: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglssetdategrouptitle}}[1]\marg{\comment{} + \cs{glsxtrsetgrouptitle}\marg{\gls{bibglsdategroup}\idx{param}1}\marg{\gls{bibglsdategrouptitle}\idx{param}1}} +\end{codeenv} + +\cssection{bibglsdategroup} + +\formatdef{bibglsdategroup} + +This command is used for \idx{dategroup} labels with \optfmt{date} (no time) sorting +(\tableref{tab:sortoptionsdatetime}). The default definition is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsdategroup}}[7]\marg{\idx{param}1\idx{param}2\idx{param}4\idx{param}7} +\end{codeenv} +This forms the group label from the year, month, era and type. +In this case, the era is a textual representation not the numeric +value used in calculating the sort value. + +\cssection{bibglsdategrouptitle} + +\formatdef{bibglsdategrouptitle} +This command is used for \idx{dategroup} titles with \optfmt{date} (no time) sorting +(\tableref{tab:sortoptionsdatetime}). The default definition is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsdategrouptitle}}[7]\marg{\idx{param}1-\idx{param}2} +\end{codeenv} +This just sets the title to the numeric year-month form +\code{\meta{YYYY}-\meta{MM}}. + +\cssection{bibglssettimegrouptitle} + +The time sort methods (\tableref{tab:sortoptionsdatetime}) +create \idxpl{timegroup} (the date isn't included). These behave in an +analogous way to the above. +\formatdef{bibglssettimegrouptitle} +This command is defined as: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglssettimegrouptitle}}[1]\marg{\comment{} + \cs{glsxtrsetgrouptitle}\marg{\gls{bibglstimegroup}\idx{param}1}\marg{\gls{bibglstimegrouptitle}\idx{param}1}} +\end{codeenv} + +\cssection{bibglstimegroup} + +\formatdef{bibglstimegroup} +This command is used for \idx{timegroup} labels with \optfmt{time} (no date) sorting +(\tableref{tab:sortoptionsdatetime}). +This command is defined as: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglstimegroup}}[7]\marg{\idx{param}1\idx{param}2\idx{param}7} +\end{codeenv} + +\cssection{bibglstimegrouptitle} + +\formatdef{bibglstimegrouptitle} + +This command is used for \idx{timegroup} titles with \optfmt{time} (no date) sorting +(\tableref{tab:sortoptionsdatetime}). +This command is defined as: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglstimegrouptitle}}[7]\marg{\idx{param}1} +\end{codeenv} + +\cssection{bibglssetunicodegrouptitle} + +\formatdef{bibglssetunicodegrouptitle} +This command is used to assign the group titles when the group +formation is set to any value other than the default. For example, +this command will be used with \csopt[codepoint]{group-formation}. +The label is obtained from \gls{bibglsunicodegroup} and the title is +obtained from \gls{bibglsunicodegrouptitle}. + +\cssection{bibglsunicodegroup} + +\formatdef{bibglsunicodegroup} +The \meta{label} depends on the \csopt{group-formation} setting: +\begin{itemize} +\item\csopt[codepoint]{group-formation}: the \meta{label} is the +Unicode value of \meta{character} (converted to \idx!{lowercase} and +decomposed, if applicable); +\item\csopt[unicode category]{group-formation}: the \meta{label} is the +Unicode category of \meta{character} (for example, \code{Lu} means +an \idx!{uppercase} letter); +\item\csopt[unicode script]{group-formation}: the \meta{label} is the +Unicode script associated with \meta{character} (for example, +\code{LATIN}); +\item\csopt[unicode category and script]{group-formation}: the \meta{label} +identifies both the Unicode category and script associated with +\meta{character} (for example, \code{Lu.LATIN}). +\end{itemize} +(Similarly for \csopt{secondary-group-formation} and +\csopt{dual-group-formation}.) By default this command expands to +\meta{type}\meta{label}. + +The \meta{character} is the first significant character of the sort +value. The \meta{id} is the hexadecimal code of (possibly decomposed) +\meta{character}. The case of codepoint \meta{id} may or may not correspond +to the case of \meta{character}. + +For example, with \csopt[codepoint]{group-formation}, an unset +\field{type} and a sort value of \qt{\AA ngstr\"om} with \qt{\AA} as a +significant character distinct from \qt{A} then the \field{group} +field will be assigned using: +\begin{codeenv} +\field{group}=\marg{\gls{bibglsunicodegroup}\marg{å}\marg{Å}\marg{C5}\marg{}} +\end{codeenv} +whereas with \csopt[unicode category and script]{group-formation} it will be: +\begin{codeenv} +\field{group}=\marg{\gls{bibglsunicodegroup}\marg{Lu.LATIN}\marg{Å}\marg{C5}\marg{}} +\end{codeenv} +(\idx!{uppercase} Latin letter). + +If instead \qt{\AA} is considered equivalent to \qt{A} according to the +collator, then with \csopt[codepoint]{group-formation}, the value will be: +\begin{codeenv} +\field{group}=\marg{\gls{bibglsunicodegroup}\marg{a}\marg{Å}\marg{61}\marg{}} +\end{codeenv} +Note that the \meta{id} is now \hex{61} (the decomposed \qt{A} +converted to \idx{lowercase}) not \hex{C5}. + +\cssection{bibglsunicodegrouptitle} + +\formatdef{bibglsunicodegrouptitle} +The title for Unicode group formations is simply defined as +\code{\cs{unexpanded}\margm{label}} so you will need to change it to +something more appropriate. For example (before the \idx{resourceset}): +\begin{codeenv} +\cs{newcommand}\marg{\gls{bibglsunicodegrouptitle}}[4]\marg{\comment{} + \ifnumhex{\idx{param}3}>64 + \ifnumhex{\idx{param}3} < 91 + A-{}-Z\comment{} + \cmd{else} + \ifnumhex{\idx{param}3} > 96 + \ifnumhex{\idx{param}3} < 123 + A-{}-Z\comment{} + \cmd{fi} + \cmd{fi} + \cmd{fi} + \cmd{fi} +} +\end{codeenv} +This will make the title \qt{A--Z} if \meta{id} is greater +than 64 and less than 91 or greater than 96 and less than 123 +(and will be empty otherwise). + +Note that this setting can create an odd effect if the sorting +causes the groups to be split up. For example, if some of the sort values +start with extended or non-Latin characters this can break up the +groups. First check how the group labels are assigned using: +\begin{codeenv} +\cs{newcommand}\marg{\gls{bibglsunicodegrouptitle}}\marg{\gls{bibglsunicodegroup}} +\end{codeenv} +then adjust the definition of \gls{bibglsunicodegroup} until the +grouping is correct, and then change the definition of +\gls{bibglsunicodegrouptitle} so that the title is correct. + +\cssection{bibglshypergroup} + +\formatdef{bibglshypergroup} + +If the \iext{log} file indicates that \isty{hyperref} has been loaded +and the \longarg{group} switch is used, then this command will be +used to create the navigation information for glossary styles such +as \glostyle{indexhypergroup}. + +\section{Flattened Entries} +\label{sec:flattendefs} + +These commands relate to the way the \field{name} field is altered +when flattening lonely child entries with the \csopt{flatten-lonely} +option. + +\cssection{bibglsflattenedhomograph} + +\formatdef{bibglsflattenedhomograph} +The default definition simply does \meta{name}. + +This command is used if the child and parent name's are identical. +For example, suppose the \ext{bib} file contains: +\begin{codeenv} +\atentry{index}\marg{super.glossary, \field{name}=\marg{glossary}} +\strut +\atentry{entry}\marg{glossarycol, + \field{parent}=\marg{super.glossary}, + \field{description}=\marg{collection of glosses} +} +\strut +\atentry{entry}\marg{glossarylist, + \field{parent}=\marg{super.glossary}, + \field{description}=\marg{list of technical words} +} +\end{codeenv} +The child entries don't have a \field{name} field, so the value is assumed +to be the same as the parent's \field{name} field. Here's an example +document where both child entries are used: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[\styopt{record},\istyopt{subentrycounter},\styopt[treenoname]{style}]\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}} +\strut +\cmd{begin}\marg{document} +\cs{gls}\marg{glossarycol} (collection) vs \cs{gls}\marg{glossarylist} (list). +\strut +\cs{printunsrtglossary} +\cmd{end}\marg{document} +\end{codeenv} +This uses one of the glossary styles designed for homographs and the +glossary has the structure: +\begin{flushleft} +\textbf{glossary}\par +\quad 1) collection of glosses 1\par +\quad 2) list of technical words 1 +\end{flushleft} +If only one child entry is selected, then the result looks a little +odd. For example: +\begin{flushleft} +\textbf{glossary}\par +\quad 1) collection of glosses 1 +\end{flushleft} +With the \csopt{flatten-lonely} option, the parent is removed and +the child is moved up a hierarchical level. With +\csopt[postsort]{flatten-lonely} this would normally adjust the +name so that it appears as \meta{parent name}, \meta{child name} +but in this case it would look a little odd for the name to +appear as \qt{glossary, glossary} so instead the name is +set to: +\begin{codeenv} +\gls{bibglsflattenedhomograph}\marg{glossary}\marg{super.glossary} +\end{codeenv} +(where the first argument is the original name and the second argument is the +label of the parent entry). + +This means that the name simply appears as \qt{glossary}, even if +the \csopt[postsort]{flatten-lonely} option is used. Note that if +the parent entry is removed, the parent label won't be of much use. +You can test for existence using \ics{ifglsentryexists} in case you +want to vary the way the name is displayed according to whether or +not the parent is still present. + +\cssection{bibglsflattenedchildpresort} + +\formatdef{bibglsflattenedchildpresort} + +Used by the \csopt[presort]{flatten-lonely} option. This defaults +to just \meta{child name}. If you want to change this, remember that +you can let the interpreter know by adding the definition to +\atentry{preamble}. For example: +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\gls{bibglsflattenedchildpresort}}[2]\marg{\idx{param}1 (\idx{param}2)}}} +\end{codeenv} + +\cssection{bibglsflattenedchildpostsort} + +\formatdef{bibglsflattenedchildpostsort} + +Used by the \csopt[postsort]{flatten-lonely} option. This defaults +to \code{\meta{parent name}, \meta{child name}}. + +Note that the arguments are in the reverse order to those of the +previous command. This is done to assist the automated first letter +upper-casing. If either command is redefined to alter the ordering, +then this can confuse the case-changing mechanism, in which case you +may want to consider switching on the expansion of the \field{name} +field using: +\begin{codeenv} +\gls{glssetexpandfield}\marg{name} +\end{codeenv} +(before \gls{GlsXtrLoadResources}). + +\section{Other} + +\cssection{bibglshyperlink} + +\formatdef{bibglshyperlink} +Used by the \hyperref[sec:dualoptsbacklinks]{back link options}, +this just defaults to: +\begin{codeenv} +\ics{glshyperlink}\oargm{text}\margm{label} +\end{codeenv} + +\cssection{bibglssetwidest} + +\formatdef{bibglssetwidest} +This is used by \csopt{set-widest} to set the widest name for the +given hierarchical level where the glossary type can't be determined. +This is defined as: +\begin{codeenv} +\cs{providecommand}*\marg{\gls{bibglssetwidest}}[2]\marg{\cs{glsxtrSetWidest}\marg{}\marg{\idx{param}1}\marg{\idx{param}2}} +\end{codeenv} +if \ics{glsxtrSetWidest} has been defined, or: +\begin{codeenv} +\cs{providecommand}*\marg{\gls{bibglssetwidest}}[2]\marg{\cs{glsupdatewidest}\oarg{\idx{param}1}\marg{\idx{param}2}} +\end{codeenv} +if \ics{glsupdatewidest} is defined, otherwise it will be +defined to use \ics{glssetwidest}: +\begin{codeenv} +\cs{providecommand}*\marg{\gls{bibglssetwidest}}[2]\marg{\cs{glssetwidest}\oarg{\idx{param}1}\marg{\idx{param}2}} +\end{codeenv} +Since this isn't scoped, this will affect other glossaries. +In general, if you have more than one glossary it's best to +set the \field{type} using options like \csopt{type}. + +\cssection{bibglssetwidestfortype} + +\formatdef{bibglssetwidestfortype} +This is used by \csopt{set-widest} to set the widest name for the +given hierarchical level where the glossary type is known. This +is defined as: +\begin{codeenv} +\cs{providecommand}*\marg{\gls{bibglssetwidestfortype}}[3]\marg{\comment{} + \cs{glsxtrSetWidest}\marg{\idx{param}1}\marg{\idx{param}2}\marg{\idx{param}3}\comment{} +} +\end{codeenv} +if \ics{glsxtrSetWidest} has been defined, or: +\begin{codeenv} +\cs{providecommand}*\marg{\gls{bibglssetwidestfortype}}[3]\marg{\comment{} + \cs{apptoglossarypreamble}\oarg{\idx{param}1}\marg{\cs{glsupdatewidest}\oarg{\idx{param}2}\marg{\idx{param}3}}\comment{} +} +\end{codeenv} +if \ics{glsupdatewidest} is defined, otherwise it will be +defined to use \ics{glssetwidest}: +\begin{codeenv} +\cs{providecommand}*\marg{\gls{bibglssetwidestfortype}}[3]\marg{\comment{} + \cs{apptoglossarypreamble}\oarg{\idx{param}1}\marg{\cs{glssetwidest}\oarg{\idx{param}2}\marg{\idx{param}3}}\comment{} +} +\end{codeenv} +Since the glossary preamble is scoped, this won't affect other +glossaries. + +\cssection{bibglssetwidestfallback} + +\formatdef{bibglssetwidestfallback} +This is used by \csopt{set-widest} instead of \gls{bibglssetwidest} +when all \field{name} fields end up as an empty string when +interpreted by \bibgls. This typically means that all the +\field{name} fields contain unknown commands. This fallback command +will use: +\begin{codeenv} +\ics{glsxtrSetWidestFallback}\marg{2}\margm{glossary list} +\end{codeenv} +if defined otherwise it will use \ics{glsFindWidestLevelTwo}, which +sets the widest name for the top-level and first two sub-levels +across all the listed glossaries. + +\cssection{bibglssetwidestfortypefallback} + +\formatdef{bibglssetwidestfortypefallback} +This is used by \csopt{set-widest} instead of +\gls{bibglssetwidestfortype} +when all \field{name} fields end up as an empty string when +interpreted by \bibgls. This typically means that all the +\field{name} fields contain unknown commands. This fallback command +will append \gls{bibglssetwidestfallback} to the glossary preamble +for the given type. + +\cssection{bibglssetwidesttoplevelfallback} + +\formatdef{bibglssetwidesttoplevelfallback} +This is used by \csopt{set-widest} instead of \gls{bibglssetwidest} +when all \field{name} fields end up as an empty string when +interpreted by \bibgls. This typically means that all the +\field{name} fields contain unknown commands. This fallback command +will use: +\begin{codeenv} +\ics{glsxtrSetWidestFallback}\marg{0}\margm{glossary list} +\end{codeenv} +if defined otherwise it will use \ics{glsFindWidestTopLevelName}, +which sets the widest name for the top-level. + +\cssection{bibglssetwidesttoplevelfortypefallback} + +\formatdef{bibglssetwidesttoplevelfortypefallback} +This is used by \csopt{set-widest} instead of +\gls{bibglssetwidestfortype} +when all \field{name} fields end up as an empty string when +interpreted by \bibgls. This typically means that all the +\field{name} fields contain unknown commands. This fallback command +will append \gls{bibglssetwidesttoplevelfallback} to the glossary +preamble of the given type. + +\cssection{bibglscontributorlist} + +\formatdef{bibglscontributorlist} +This is used when \csopt{bibtex-contributor-fields} is set. The +definition depends on whether or not \ics{DTLformatlist} has been +defined: +\begin{codeenv} +\ics{ifdef}\cs{DTLformatlist} +\marg{\comment{datatool v2.28+} + \cs{providecommand}*\marg{\gls{bibglscontributorlist}}[2]\marg{\cs{DTLformatlist}\marg{\idx{param}1}} +} +\marg{\comment{datatool v2.27 or earlier} + \cs{providecommand}*\marg{\gls{bibglscontributorlist}}[2]\marg{\comment{} + \ics{def}\cmd{bibgls@sep}\marg{}\comment{} + \ics{@for}\cmd{bibgls@item}:=\idx{param}1\cmd{do}\marg{\cmd{bibgls@sep}\cmd{bibgls@item}\cs{def}\cmd{bibgls@sep}\marg{, }}\comment{} + } +} +\end{codeenv} +The second argument allows you to provide definitions like: +\begin{codeenv} +\cs{newcommand}*\marg{\gls{bibglscontributorlist}}[2]\marg{\comment{} + \cs{ifcase}\idx{param}2 + \cmd{or} + name: + \cmd{else} + names: + \cmd{fi} + \cs{DTLformatlist}\marg{\idx{param}1}\comment{} +} +\end{codeenv} + +\cssection{bibglscontributor} + +\formatdef{bibglscontributor} +This is used when \csopt{bibtex-contributor-fields} is set. The +definition depends on the value of \csopt{contributor-order}. Note that if you +have multiple resource sets, that option governs the way \bibgls's version of +\gls{bibglscontributor} behaves. The definition is written to the \ext{glstex} +using \cs{providecommand}, so \LaTeX\ will only pick up the first definition. + +\cssection{bibglsdatetime} + +\formatdef{bibglsdatetime} +Used to encapsulate date-time fields identified with +\csopt{date-time-fields}. +Since \gls{bibglsdatetime} requires more than nine arguments, the +remaining four arguments are picked up with: +\nosecdef{bibglsdatetimeremainder} +The default definitions are: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsdatetime}}[9]\marg{\gls{bibglsdatetimeremainder}} +\cs{providecommand}\marg{\gls{bibglsdatetimeremainder}}[4]\marg{\idx{param}4} +\end{codeenv} + +\cssection{bibglsdate} + +\formatdef{bibglsdate} +Used to encapsulate date fields identified with +\csopt{date-fields}. +The default definition is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsdate}}[7]\marg{\idx{param}7} +\end{codeenv} + +\cssection{bibglstime} + +\formatdef{bibglstime} +Used to encapsulate date fields identified with +\csopt{time-fields}. +The default definition is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglstime}}[7]\marg{\idx{param}7} +\end{codeenv} + +\cssection{bibglsprimaryprefixlabel} + +\formatdef{bibglsprimaryprefixlabel} +A hook to pick up the primary prefix label (identified with +\csopt{label-prefix}) if required. This does nothing by default. If +required, this command should be defined before the +\idx{resourceset} is loaded. + +\cssection{bibglsdualprefixlabel} + +\formatdef{bibglsdualprefixlabel} +A hook to pick up the dual prefix label (identified with +\csopt{dual-prefix}) if required. This does nothing by default. If +required, this command should be defined before the +\idx{resourceset} is loaded. + +\cssection{bibglstertiaryprefixlabel} + +\formatdef{bibglstertiaryprefixlabel} +A hook to pick up the tertiary prefix label (identified with +\csopt{tertiary-prefix}) if required. This does nothing by default. If +required, this command should be defined before the +\idx{resourceset} is loaded. + +\cssection{bibglsexternalprefixlabel} + +\formatdef{bibglsexternalprefixlabel} +A hook to pick up the \meta{n}th external prefix label (identified with +\csopt{ext-prefixes}) if required. This does nothing by default and +won't be used if the list of external prefixes is empty. If required, +this command should be defined before the \idx{resourceset} is +loaded. + +\cssection{bibglshashchar} + +\formatdef{bibglshashchar} +Expands to a literal hash character (\,\idx{hashchar}\,). + +\cssection{bibglsunderscorechar} + +\formatdef{bibglsunderscorechar} +Expands to a literal underscore character (\,\idx{underscorechar}\,). + +\cssection{bibglsdollarchar} + +\formatdef{bibglsdollarchar} +Expands to a literal dollar character (\,\idx{dollarchar}\,). + +\cssection{bibglsampersandchar} + +\formatdef{bibglsampersandchar} +Expands to a literal ampersand character (\,\idx{ampchar}\,). + +\cssection{bibglscircumchar} + +\formatdef{bibglscircumchar} +Expands to a literal circumflex character (\,\idx{circumchar}\,). + +\cssection{bibglsuppercase} + +\formatdef{bibglsuppercase} +Converts \meta{text} to \idx{uppercase}. This just uses +\ics{MakeTextUppercase} by default. + +\cssection{bibglslowercase} + +\formatdef{bibglslowercase} +Converts \meta{text} to \idx{lowercase}. This just uses +\ics{MakeTextLowercase} by default. + +\cssection{bibglstitlecase} + +\formatdef{bibglstitlecase} +Converts \meta{text} to \idx{titlecase}. This just uses +\ics{capitalisewords} by default. + +\cssection{bibglsfirstuc} + +\formatdef{bibglsfirstuc} +Converts the first letter of \meta{text} to \idx{uppercase}. This just uses +\ics{makefirstuc} by default. + +\chapter{Converting Existing \iext{tex} to \iext{bib}} +\label{sec:gls2bib} +\setsecdepth{0} + +If you have already been using the \styfmt{glossaries} or +\styfmt{glossaries-extra} package with a large file containing all your +definitions using commands like \gls{newglossaryentry}, then you can +use the supplementary tool \idx{convertgls2bib} to convert the definitions +to the \ext{bib} format required by \bibgls. The syntax is: +\begin{alltt} +convertgls2bib \oargm{options} \meta{tex file} \meta{bib file} +\end{alltt} +where \meta{tex file} is the \ext{tex} file and \meta{bib file} is +the \ext{bib} file. This application is less secure than \bibgls\ as +it doesn't use \idx{kpsewhich} to check \texmfcnf{openinany} and +\texmfcnf{openoutany}. Take care not to accidentally overwrite +existing \ext{bib} files as there's no check to determine if +\meta{bib file} already exists. + +The \meta{options} are: +\begin{description} +\item[\longargfmt{texenc} \meta{encoding}] The character encoding of the +\ext{tex} file. If omitted, the operating system's default encoding +is assumed (or the \idx{JVM}['s]). + +\item[\longargfmt{bibenc} \meta{encoding}] The character encoding of the +\ext{bib} file. If omitted, the same encoding as the +\ext{tex} file is assumed. + +\item[\longargfmt{space-sub} \meta{replacement}] The \ext{bib} +format doesn't allow spaces in labels. If your original +definitions in your \ext{tex} file have spaces, use this option to +replace spaces in labels. Each space will be substituted with +\meta{replacement}. The cross-referencing fields, \field{see}, +\field{seealso} and \field{alias}, will also be adjusted, but any +references using \ics{gls} etc will have to be substituted manually +(or use a global search and replace in your text editor). +If you want to strip the spaces, use an empty string for +\meta{replacement}. You'll need to delimit this according to your +operating system. For example: +\begin{verbatim} +convertgls2bib --space-sub '' entries.tex entries.bib +\end{verbatim} + +\item[\longargfmt{ignore-sort}] Ignore the \field{sort} field. +This is the default since \bibgls\ can work out a more intuitive +sort value than either \idx!{makeindex} or \idx!{xindy}. + +\item[\longargfmt{no-ignore-sort}] Don't ignore the \field{sort} field. + +\item[\longargfmt{locale} \meta{lang tag}] Identifies the \langxml\ +to use for \idx{convertgls2bib}['s] messages. + +\item[\longargfmt{silent}] Suppress all messages except for errors. + +\item[\longargfmt{verbose}] Display messages and warnings (default). + +\item[\longargfmt{debug}] Display debugging messages (stack +traces and other information in addition to \longargfmt{verbose}). + +\item[\longargfmt{help} or \shortargfmt{h}] Display help message and +quit. +\item[\longargfmt{version} or \shortargfmt{v}] Display version +information and quit. +\end{description} + +This application recognises the commands listed below. Avoid any overly +complicated code within the \ext{tex} file. The +\hyperref[sec:texparserlib]{\TeX\ parser library} isn't a \TeX\ engine! The +\ext{tex} file doesn't need to be a complete document, but if you want certain +commands recognised from packages that the \TeX\ parser library supports, +you'll need to include \ics{usepackage} in the \ext{tex} file. +In all cases below, if \meta{\keyvallist} contains: +\begin{codeenv*} +\field{see}=\marg{[\ics{seealsoname}]\meta{label(s)}} +\end{codeenv*} +this will be substituted with: +\begin{codeenv*} +\field{seealso}=\margm{label(s)} +\end{codeenv*} +For example: +\begin{codeenv} +\gls{newterm}\oarg{\field{see}=\marg{[\cs{seealsoname}]goose}}\marg{duck} +\end{codeenv} +will be written as: +\begin{codeenv} +\atentry{index}\marg{duck, + \field{seealso} = \marg{goose} +} +\end{codeenv} + +Additionally, if \meta{\keyvallist} contains: +\begin{codeenv} +\field{type}=\marg{\ics{glsdefaulttype}} +\end{codeenv} +then this field will be ignored. (This \field{type} value is +recommended in \meta{\keyvallist} when loading files with +\ics{loadglsentries}\oargm{type}\margm{file} to allow the optional +argument to set the \field{type}. With \bibgls\ you can use the +\csopt{type} option instead.) + +\cssection[\section]{glsexpandfields} +The base \styfmt{glossaries} package provides: +\formatdef{glsexpandfields} +If present, this instructs \idx{convertgls2bib} to expand all fields +except for those explicitly identified by \gls{glssetnoexpandfield}. +Remember that there are many commands that aren't recognised by +\idx{convertgls2bib} so it may not be possible to correctly expand +field values. Conversely, there are some commands that will be +expanded by \idx{convertgls2bib} that aren't expandable in \TeX\ +(such as \ics{MakeUppercase} and \ics{char}). + +\cssection[\section]{glsnoexpandfields} +The base \styfmt{glossaries} package provides: +\formatdef{glsnoexpandfields} +If present, this instructs \idx{convertgls2bib} to not expand fields +unless explicitly identified by \gls{glssetexpandfield}. + +\cssection[\section]{glssetexpandfield} +The base \styfmt{glossaries} package provides: +\formatdef{glssetexpandfield} +If present, this instructs \idx{convertgls2bib} to expand the +given field, even if \gls{glsnoexpandfields} has been used. + +\cssection[\section]{glssetnoexpandfield} +The base \styfmt{glossaries} package provides: +\formatdef{glssetnoexpandfield} +If present, this instructs \idx{convertgls2bib} to not expand the +given field, even if \gls{glsexpandfields} has been used. +Unlike the default behaviour with the \sty{glossaries} package, there are no +fields switched explicitly switched off by default with +\idx{convertgls2bib}. + +\cssection[\section]{newglossaryentry} +The base \styfmt{glossaries} package provides: +\formatdef{newglossaryentry} +This is converted to: +\begin{codeenv} +\atentry{entry}\marg{\meta{label}, + \meta{\keyvallist} +} +\end{codeenv} +\ics{newentry} is recognised as a synonym of \gls{newglossaryentry}. + +\cssection[\section]{provideglossaryentry} +The base \styfmt{glossaries} package provides: +\formatdef{provideglossaryentry} +This is converted to: +\begin{codeenv} +\atentry{entry}\marg{\meta{label}, + \meta{\keyvallist} +} +\end{codeenv} +but only if \meta{label} hasn't already been defined. + +\cssection[\section]{longnewglossaryentry} +The base \styfmt{glossaries} package provides: +\formatdef{longnewglossaryentry} +This is converted to: +\begin{codeenv} +\atentry{entry}\marg{\meta{label}, + \meta{\keyvallist}, + \field{description} = \margm{description} +} +\end{codeenv} +The starred version provided by the \styfmt{glossaries-extra} package +is also recognised. The unstarred version strips trailing spaces +from \meta{description}. (This doesn't add \ics{nopostdesc}, but +\styfmt{glossaries-extra} defaults to \styopt{nopostdot}.) + +\cssection[\section]{longprovideglossaryentry} + +The base \styfmt{glossaries} package provides: +\formatdef{longprovideglossaryentry} +As above, but only if \meta{label} hasn't already been defined. + +\cssection[\section]{newterm} + +The base \styfmt{glossaries} package provides: +\formatdef{newterm} +(when the \styopt{index} option is used). +This is converted to: +\begin{codeenv} +\atentry{index}\marg{\meta{label}, + \meta{\keyvallist} +} +\end{codeenv} +if the optional argument is present, otherwise it's just converted +to: +\begin{codeenv} +\atentry{index}\marg{\meta{label}} +\end{codeenv} + +If \longargfmt{space-sub} is used and \meta{label} contains one or +more spaces, then \field{name} will be set if not included in +\meta{\keyvallist}. For example, if \filefmt{entries.bib} +contains: +\begin{codeenv} +\gls{newterm}\marg{sea lion} +\gls{newterm}\oarg{\field{seealso}=\marg{sea lion}}\marg{seal} +\end{codeenv} +then: +\begin{verbatim} +convertgls2bib --space-sub '-' entries.bib entries.tex +\end{verbatim} +will write the terms to \filefmt{entries.tex} as: +\begin{codeenv} +\atentry{index}\marg{sea-lion, + \field{name} = \marg{sea lion} +} +\strut +\atentry{index}\marg{seal, + \field{seealso} = \marg{sea-lion} +} +\end{codeenv} +whereas just: +\begin{verbatim} +convertgls2bib entries.bib entries.tex +\end{verbatim} +will write the terms to \filefmt{entries.tex} as: +\begin{codeenv} +\atentry{index}\marg{sea lion} +\strut +\atentry{index}\marg{seal, + \field{seealso} = \marg{sea lion} +} +\end{codeenv} +which will cause a problem when the \ext{bib} file is parsed +by \bibgls\ (and will probably also cause a problem for +bibliographic management systems). + +\cssection[\section]{newabbreviation} +The \styfmt{glossaries-extra} package provides: +\formatdef{newabbreviation} +This is converted to: +\begin{codeenv} +\atentry{abbreviation}\marg{\meta{label}, + \field{short} = \margm{short}, + \field{long} = \margm{long}, + \meta{\keyvallist} +} +\end{codeenv} +if the optional argument is present, otherwise it's converted to: +\begin{codeenv} +\atentry{abbreviation}\marg{\meta{label}, + \field{short} = \margm{short}, + \field{long} = \margm{long} +} +\end{codeenv} + +\cssection[\section]{newacronym} +The base \styfmt{glossaries} package provides: +\formatdef{newacronym} +(which is redefined by \styfmt{glossaries-extra} to use +\gls{newabbreviation}). + +As above but uses \atentry{acronym} instead. + +\cssection[\section]{glsxtrnewsymbol} +The \styfmt{glossaries-extra} package provides: +\formatdef{glsxtrnewsymbol} +(when the \styopt{symbols} option is used). +This is converted to: +\begin{codeenv} +\atentry{symbol}\marg{\meta{label}, + \field{name} = \margm{symbol} +} +\end{codeenv} +if the optional argument is missing, otherwise it's converted to: +\begin{codeenv} +\atentry{symbol}\marg{\meta{label}, + \field{name} = \margm{symbol}, + \meta{\keyvallist} +} +\end{codeenv} +unless \meta{\keyvallist} contains the \field{name} field, +in which case it's converted to: +\begin{codeenv} +\atentry{symbol}\marg{\meta{label}, + \meta{\keyvallist} +} +\end{codeenv} +\ics{newsym} is recognised as a synonym for \gls{glsxtrnewsymbol}. + +\cssection[\section]{glsxtrnewnumber} + +The \styfmt{glossaries-extra} package provides: +\formatdef{glsxtrnewnumber} +(when the \styopt{numbers} option is used). +This is converted to: +\begin{codeenv} +\atentry{number}\marg{\meta{label}, + \field{name} = \margm{label} +} +\end{codeenv} +if the optional argument is missing, otherwise it's converted to: +\begin{codeenv} +\atentry{number}\marg{\meta{label}, + \field{name} = \margm{label}, + \meta{\keyvallist} +} +\end{codeenv} +if \field{name} isn't listed in \meta{\keyvallist}, +otherwise it's converted to: +\begin{codeenv} +\atentry{number}\marg{\meta{label}, + \meta{\keyvallist} +} +\end{codeenv} +\ics{newnum} is recognised as a synonym for \gls{glsxtrnewnumber}. + +\cssection[\section]{newdualentry} + +\formatdef{newdualentry} +This command isn't provided by either \styfmt{glossaries} or +\styfmt{glossaries-extra} but is used as an example in the +\sty{glossaries} user manual~\cite{glossaries} and in the sample file +\file{sample-dual.tex} that accompanies the \sty{glossaries} +package. Since this command seems to be used quite a bit (given the +number of times it crops up on sites like +\href{https://tex.stackexchange.com/}{\TeX\ on StackExchange}), +\idx{convertgls2bib} also supports it unless this command is +defined using \ics{newcommand} or \ics{renewcommand} in the +input file. In which case the default definition will be overridden. + +If the command definition isn't overridden, then it's converted to: +\begin{codeenv} +\atentry{dualabbreviationentry}\marg{\meta{label}, + \field{short} = \margm{short}, + \field{long} = \margm{long}, + \field{description} = \margm{description}, + \meta{\keyvallist} +} +\end{codeenv} +if \meta{\keyvallist} is supplied, otherwise it's converted to: +\begin{codeenv} +\atentry{dualabbreviationentry}\marg{\meta{label}, + \field{short} = \margm{short}, + \field{long} = \margm{long}, + \field{description} = \margm{description} +} +\end{codeenv} + +For example, if the original \ext{tex} file contains: +\begin{codeenv} +\cs{newcommand}*\marg{\gls{newdualentry}}[5][]\marg{\comment{} + \gls{newglossaryentry}\marg{main-\idx{param}2}\marg{\field{name}=\marg{\idx{param}4},\comment{} + \field{text}=\marg{\idx{param}3\cs{glsadd}\marg{\idx{param}2}},\comment{} + \field{description}=\marg{\idx{param}5},\comment{} + \idx{param}1 + }\comment{} + \gls{newacronym}\marg{\idx{param}2}\marg{\idx{param}3\cs{glsadd}\marg{main-\idx{param}2}}\marg{\idx{param}4}\comment{} +} +\strut +\gls{newdualentry}\marg{svm}\comment{label} + \marg{SVM}\comment{abbreviation} + \marg{support vector machine}\comment{long form} + \marg{Statistical pattern recognition technique}\comment{description} +\end{codeenv} +then the \ext{bib} file will contain: +\begin{codeenv} +\atentry{entry}\marg{main-svm, + \field{name} = \marg{support vector machine}, + \field{description} = \marg{Statistical pattern recognition technique}, + \field{text} = \marg{SVM\cs{glsadd}\marg{svm}} +} +\strut +\atentry{acronym}\marg{svm, + \field{short} = \marg{SVM\cs{glsadd}\marg{main-svm}}, + \field{long} = \marg{support vector machine} +} +\end{codeenv} +since \gls{newdualentry} was defined with \ics{newcommand}. However, +if the original file uses \ics{providecommand} or omits the +definition of \gls{newdualentry}, then the \ext{bib} file will +contain: +\begin{codeenv} +\atentry{dualabbreviationentry}\marg{svm, + \field{short} = \marg{SVM}, + \field{description} = \marg{Statistical pattern recognition technique}, + \field{long} = \marg{support vector machine} +} +\end{codeenv} + +\chapter{Examples} +\label{sec:examples} +\setsecdepth*{0} + +The example files described here can be found in the +\filefmt{examples} sub-directory. The \ext{bib} files are listed +first and then sample files that use the \ext{bib} data. +Make sure you have the latest versions of \styfmt{glossaries}, +\styfmt{mfirstuc}, \styfmt{glossaries-extra} and \bibgls\ if you +want to try these out. (The \exfile{sample-media.tex} file requires +at least \styfmt{datatool} v2.28.) If you get any undefined control +sequence or undefined style errors then you need to update your +\TeX\ distribution. Use the \longarg{group} switch when invoking +\bibgls\ for all these examples if you want the glossaries divided +into groups. The set of system calls for the document build in the +examples below may require an extra \LaTeX\ run to ensure the PDF +bookmarks are up-to-date when \sty{hyperref} is used. + +These files are just examples of how to use \bibgls. There are other +ways of defining similar entries and sometimes alternatives are +suggested. Use the code here as a starting point if you need data +like this and adapt it to a format appropriate for your +requirements. + +\filesection{no-interpret-preamble.bib} + +The \exfile{no-interpret-preamble.bib} file contains command +definitions used in some of the \field{name} fields. Although these +commands aren't used explicitly in the document, they need to be +defined when the names are displayed in the document (typically in +the glossary). These commands are much like the \gls{sortop} command +described on \glsxtrpageref{sortop} and need to be hidden +from \bibgls's interpreter. This file doesn't contain any entry +definitions and must be loaded first with +\csopt[false]{interpret-preamble}. The +\exfile{interpret-preamble.bib} or \exfile{interpret-preamble2.bib} +file can then be loaded to provide alternative definitions for +\bibgls's interpreter. + +The first command is: +\nosecdef{sortname} +This is used in the \field{name} fields for entries containing +information about a person. The aim here is for \bibgls\ to sort +according to \meta{surname}, \meta{first name(s)} but for the +glossary to display \meta{first name(s)} \meta{surname}. For names +with a \qt{von} part, there's another command: +\nosecdef{sortvonname} +which has a similar purpose. +The third command is: +\nosecdef{sortart} +This is the same as \gls{sortname} but is designed for titles, +phrases or sentences that start with an article (such as \qt{a} or +\qt{the}). Although it has the same definition as \gls{sortname} +in this file, in the interpreted files the article part is omitted +to completely ignore them in the sorting. +The fourth command is: +\nosecdef{sortmediacreator} +which again is functionally the same as \gls{sortname}. + +The names could be specified using \BibTeX's +syntax instead with \csopt{bibtex-contributor-fields} to convert it, +but the aim here is to show a variety of ways to use \bibgls. For an +example of \csopt{bibtex-contributor-fields}, see the way the +\fieldfmt{cast} field in \exfile{films.bib} is dealt with. + +Although the file only contains ASCII characters, it starts with +an encoding line to prevent \bibgls\ from searching the entire file +for it. (That's not so much of an issue with a short file, but may +cause an unnecessary delay for much longer files.) + +The contents of \filefmt{no-interpret-preamble.bib} are as follows: +\lstinputlisting[firstline=5]{../examples/no-interpret-preamble.bib} + +\filesection{interpret-preamble.bib} + +This provides definitions of \gls{sortname}, \gls{sortvonname}, +\gls{sortart} and \gls{sortmediacreator} in \atentry{preamble} +that can be picked up by the interpreter and used during sorting. +Note that in this case \gls{sortart} is defined to ignore the +article to completely ignore it from sorting. If you happen to have +\qt{a \meta{something}} and \qt{the \meta{something}} where the +\meta{something}s are identical, you may want to append the article +to disambiguate them. + +The contents of \filefmt{interpret-preamble.bib} are as follows: +\lstinputlisting[firstline=5]{../examples/interpret-preamble.bib} + +\filesection{interpret-preamble2.bib} + +An alternative to \exfile{interpret-preamble.bib} with a different +definition of \gls{sortmediacreator}. This uses \cs{renewcommand} +instead of \cs{providecommand} so \csopt[false]{write-preamble} +is required to prevent \LaTeX\ from picking up the definitions. + +The contents of \filefmt{interpret-preamble2.bib} are as follows: +\lstinputlisting[firstline=5]{../examples/interpret-preamble2.bib} + +\filesection{constants.bib} + +The \exfile{constants.bib} file contains mathematical constants. +These all use a custom entry type \atentryfmt{constant}, which must +be aliased otherwise the entries will all be ignored. The entries +all have custom fields, which also need to be aliased. +For example: +\begin{codeenv} +\csopt[constant=entry]{entry-type-aliases}, +\csopt[ + \fieldfmt{constantname}=\field{name}, + \fieldfmt{constantsymbol}=\field{symbol}, + \fieldfmt{definition}=\field{description}, + \fieldfmt{identifier}=\field{category}, + \fieldfmt{value}=\field{user1} +]{field-aliases} +\end{codeenv} +This setting means that, for example, +\begin{codeenv} +\atentryfmt{constant}\marg{root2, + \fieldfmt{constantname}=\marg{Pythagoras' constant}, + \fieldfmt{constantsymbol}=\marg{\cs{ensuremath}\marg{\ics{surd}2}}, + \fieldfmt{definition}=\marg{the square root of 2}, + \fieldfmt{value}=\marg{1.41421}, + \fieldfmt{identifier}=\marg{constant} +} +\end{codeenv} +is treated as though it was defined as: +\begin{codeenv} +\atentry{entry}\marg{root2, + \field{name}=\marg{Pythagoras' constant}, + \field{symbol}=\marg{\cs{ensuremath}\marg{\cs{surd}2}}, + \field{description}=\marg{the square root of 2}, + \field{user1}=\marg{1.41421}, + \field{category}=\marg{constant} +} +\end{codeenv} +This use of custom fields and entry types allows more flexibility. +For example, I may have another document that uses the same +\ext{bib} file but requires a different definition: +\begin{codeenv} +\atentry{number}\marg{root2, + \field{description}=\marg{Pythagoras' constant}, + \field{name}=\marg{\cs{ensuremath}\marg{\cs{surd}2}} +} +\end{codeenv} +which can be obtained with: +\begin{codeenv} +\csopt[constant=number]{entry-type-aliases}, +\csopt[ + \fieldfmt{constantname}=\field{description}, + \fieldfmt{constantsymbol}=\field{name} +]{field-aliases} +\end{codeenv} +Since the other custom fields haven't be aliased, they're ignored. + +The custom fields are: \fieldfmt{identifier} (set to \code{constant} +for all the entries), \fieldfmt{constantname} (the constant's name), +\fieldfmt{definition} (a definition of the constant), +\fieldfmt{value} (the approximate numeric value of the constant), +\fieldfmt{constantsymbol} (the symbolic representation of the +constant) and \fieldfmt{alternative} (alternative symbol). +There are three entries that don't have the custom +\fieldfmt{value} field: \code{zero} and \code{one} (the exact value +is in the \fieldfmt{constantsymbol} field in both cases) and \code{imaginary} +(where there's no real number value). + +I've provided some commands in the \atentry{preamble} for +constants that are represented by Latin and Greek letters. +These can be defined in the document before the \idx{resourceset} +if different notation is required. The upright Greek commands require +the \isty{upgreek} package. + +If it's likely that there may be a need to sort according to +\fieldfmt{definition}, then it would be better to use \gls!{sortart} +describe above: +\begin{codeenv} +\atentryfmt{constant}\marg{root2, + \fieldfmt{constantname}=\marg{Pythagoras' constant}, + \fieldfmt{constantsymbol}=\marg{\cs{ensuremath}\marg{\cs{surd}2}}, + \fieldfmt{definition}=\marg{\gls{sortart}\marg{the}\marg{square root of 2}}, + \fieldfmt{value}=\marg{1.41421}, + \fieldfmt{identifier}=\marg{constant} +} +\end{codeenv} +Remember that this would need \exfile{no-interpret-preamble.bib} to +ensure the command is recognised in the document. + +The contents of \filefmt{constants.bib} are as follows: +\lstinputlisting[firstline=5]{../examples/constants.bib} + +\filesection{chemicalformula.bib} + +The \exfile{chemicalformula.bib} file contains chemical formulae. +Each entry has a field that uses \ics{ce} provided by \sty{mhchem} +so the document will need to load that package. Since all resource +files must be loaded in the preamble, it's possible to ensure that +the package is loaded using: +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cs{usepackage}\marg{mhchem}}} +\end{codeenv} +However, it's best just to load it in the document otherwise it +won't be available before the \ext{glstex} file has been loaded. +Also, \sty{glossaries} (and therefore \sty{glossaries-extra}) must be +loaded after \sty{hyperref}, which usually needs to be loaded last +so most packages should be loaded before \sty{glossaries-extra}. +Instead, I've just put a comment in the \ext{bib} file as a +reminder. + +All entries are defined using a custom entry type +\atentryfmt{chemical}. This must be aliased using +\csopt{entry-type-aliases} or the entries will be ignored. For +example, to make \atentryfmt{chemical} behave like \atentry{symbol}: +\begin{codeenv} +\csopt[\fieldfmt{chemical}=\field{symbol}]{entry-type-aliases} +\end{codeenv} +Remember that with the \atentry{symbol} type, if the \field{sort} +field is omitted \bibgls\ will fallback on the label by default. It +can be changed to fallback on the \field{name} field instead using +\csopt[name]{symbol-sort-fallback}. This will require the use of +the interpreter if the name contains a command but \bibgls\ +recognises the \sty{mhchem} package and has a limited ability to +interpret \cs{ce}. If \atentryfmt{chemical} is changed to +\atentry{entry} instead then the fallback for the \field{sort} will be the +entry's \field{name}. + +All entries only contain custom fields, which will all be ignored by +\bibgls\ unless defined or aliased: \fieldfmt{identifier}, which is set to +\code{chemical} for all entries, \fieldfmt{formula}, which is set to the +chemical formula, and \fieldfmt{chemicalname}, which is set to the chemical +name. This allows the flexibility of determining whether the +\field{name} or \field{symbol} field should contain the chemical +formula on a per-resource basis. For example: +\begin{codeenv} +\csopt[\fieldfmt{formula}=\field{name},\fieldfmt{chemicalname}=\field{description}]{field-aliases} +\end{codeenv} +or +\begin{codeenv} +\csopt[\fieldfmt{chemicalname}=\field{name},\fieldfmt{formula}=\field{symbol}]{field-aliases} +\end{codeenv} + +The contents of \filefmt{chemicalformula.bib} are as follows: +\lstinputlisting[firstline=5]{../examples/chemicalformula.bib} + +\filesection{bacteria.bib} + +The \exfile{bacteria.bib} file contains bacteria abbreviations. +These all use the \atentry{abbreviation} entry type with a +\field{short} and \field{long} field. + +The entries all have a custom field \fieldfmt{identifier} set to +\code{bacteria}. This will be ignored by \bibgls\ unless it's +defined using \cs{glsaddkey} or \cs{glsaddstoragekey} or if it's +aliased with \csopt{field-aliases}. + +The contents of \filefmt{bacteria.bib} are as follows: +\lstinputlisting[firstline=5]{../examples/bacteria.bib} + +\filesection{baseunits.bib} + +The \exfile{baseunits.bib} file contains base \idxpl{SIunit}. The entries +are all defined using the custom \atentryfmt{unit} entry +type. This must be aliased with \csopt{entry-type-aliases} otherwise +\bibgls\ will ignore all the entries. For example: +\begin{codeenv} +\csopt[\fieldfmt{unit}=\field{symbol}]{entry-type-aliases} +\end{codeenv} +will make \bibgls\ treat the entries as though they were defined +using \atentry{symbol}. (Remember that \atentry{symbol} entry types use the label +as the fallback field for \field{sort}.) + +The entries all have custom fields \fieldfmt{unitname}, +\fieldfmt{unitsymbol} and \fieldfmt{measurement}, one of which must +be aliased or copied to \field{name} if \atentryfmt{unit} is aliased +to an entry type that requires it. The other custom fields may be aliased or +copied to \field{symbol} and \field{description} as required. The +\fieldfmt{unitsymbol} fields all use \ics{si} provided by the +\isty{siunitx} package, so that package must be loaded in the +document. This is one of the small number of packages recognised by +\bibgls, so it's possible to sort according to the symbol if +required. + +The entries also all have a custom field \fieldfmt{identifier} set to +\code{baseunit}. This will be ignored by \bibgls\ unless it's +defined using \cs{glsaddkey} or \cs{glsaddstoragekey} or if it's +aliased with \csopt{field-aliases}. + +The contents of \filefmt{baseunits.bib} are as follows: +\lstinputlisting[firstline=5]{../examples/baseunits.bib} + +\filesection{derivedunits.bib} + +The \exfile{derivedunits.bib} file is much like \exfile{baseunits.bib} +but contains derived units and in this case the custom entry type +is \atentryfmt{measurement}, which must be aliased +otherwise the entries will all be ignored. +The entries all have a custom field \fieldfmt{identifier} set to +\code{derivedunit}. This will be ignored by \bibgls\ unless it's +defined using \cs{glsaddkey} or \cs{glsaddstoragekey} or if it's +aliased with \csopt{field-aliases}. + +The contents of \filefmt{derivedunits.bib} are as follows: +\lstinputlisting[firstline=5]{../examples/derivedunits.bib} + +\filesection{people.bib} + +The \exfile{people.bib} file contains details about people. +The \field{name} fields contain custom commands provided in +\exfile{no-interpret-preamble.bib} and +\exfile{interpret-preamble.bib}. +Remember that if \exfile{no-interpret-preamble.bib} is +loaded first, the definitions provided in that file will be the one +in use in the document. The \exfile{interpret-preamble.bib} file +then needs to be loaded to provide the definitions for \bibgls's +interpreter. + +The information for each person is supplied in an \atentry{entry} +type. There are some non-standard fields: \fieldfmt{born}, +\fieldfmt{died} and \fieldfmt{othername}. These fields will be ignored +unless keys are provided (using \cs{glsaddkey} or +\cs{glsaddstoragekey}) or the fields are aliased (using +\csopt{field-aliases}). The \fieldfmt{born} and \fieldfmt{died} +fields have dates that are \emph{almost} in the default \code{en-GB} +locale format with the \idx{JRE} \idx{localeprovider}, but they include a +tilde \idx{nbspchar} to prevent awkward line breaks. By default \bibgls's +interpreter converts \idx{nbspchar} to the non-breaking space character +\hex{A0} which isn't recognised by the date format. This can easily +be fixed with the \longarg{break-space} switch which will interpret +\idx{nbspchar} as a normal breakable space (\hex{20}), so with that switch +\csopt[date]{sort} or \csopt[date-reverse]{sort} can be used on +either of those fields. However, the \idx{CLDR} has a slightly +different default format than the \idx{JRE} for dates with +\code{en-GB}, so it's probably simplest to actually specify the +required format. + +An alternative approach would be to provide a command that can be +modified in the document to adjust the date style. For example, the +\fieldfmt{born} field could be specified as: +\begin{codeenv} +\fieldfmt{born}=\marg{\cmd{formatdate}\marg{13}\marg{7}\marg{100}\marg{BC}} +\end{codeenv} +The definition provided for the document could then be, for example: +\begin{codeenv} +\cs{providecommand}\marg{\cmd{formatdate}}[4]\marg{\ics{DTMdisplaydate}\marg{\idx{param}3}\marg{\idx{param}2}\marg{\idx{param}1}\marg{-1} \idx{param}4} +\end{codeenv} +(where \ics{DTMdisplaydate} is provided by the \isty{datetime2} +package) and a definition could be provided for \bibgls's +interpreter, for example: +\begin{codeenv} +\cs{providecommand}\marg{\cmd{formatdate}}[4]\marg{\idx{param}1/\idx{param}2/\idx{param}3 \idx{param}4} +\end{codeenv} +This would need the date format set. For example, +\csopt[d/M/y G]{date-sort-format}. + +Some of the entries, such as \code{caesar}, have a \field{first} +field. In those cases the \field{first} field is slightly different +from the \field{name} field (for example, \qt{Gaius} is omitted in +\code{caesar}'s \field{first} field). The other entries don't have a +\field{first} field. They can simply have the \field{name} copied to +\field{first} with the \csopt{replicate-fields} option (so that the +full name is shown on first use) or the \field{first} field can be +ignored with \csopt{ignore-fields} (so all entries will use the +\field{text} field on first use). The \csopt{replicate-override} +option can be used to force the \field{name} field to be copied to +the \field{first} field, even if the \field{first} field is already +set. Alternatively, with \csopt[true]{replicate-override} and +\csopt[\field{first}=\field{name}]{replicate-fields}, the \field{first} field be +copied to the \field{name} field. For consistency, the \field{first} +fields use the same custom commands as used in the \field{name} +field. + +There's one name with a \qt{von} part. In this case the \field{name} +field is set to: +\begin{codeenv} +\gls{sortvonname}\marg{Manfred}\marg{von}\marg{Richthofen} +\end{codeenv} +which will come under the \qt{V} letter group since \gls{sortvonname} +is defined as \meta{von} \meta{surname}, \meta{first name(s)} + +If you prefer that this name should come under \qt{R} instead, then +you need to adjust the definition of \gls{sortvonname}: +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{sortname}}[2]\marg{\idx{param}2, \idx{param}1} +\cs{providecommand}\marg{\cmd{sortvonname}}[3]\marg{\idx{param}3, \idx{param}1 \idx{param}2}}} +\end{codeenv} +An alternative approach would be to format the names using +\BibTeX's contributor syntax and use +\csopt[name]{bibtex-contributor-fields} to convert them. + +There are also some synonyms provided with \atentry{index} entry +types that have the \field{alias} field to redirect to the main +entry. These don't include a \field{description} or any of the other +fields as that would be redundant. All the information can be found +in the main entry. + +Except for the aliases, the entries have a custom field +\fieldfmt{identifier} set to \code{person}. This will be ignored by +\bibgls\ unless it's defined using \cs{glsaddkey} or +\cs{glsaddstoragekey} or if it's aliased with \csopt{field-aliases}. + +The contents of \filefmt{people.bib} are as follows: +\lstinputlisting[firstline=5]{../examples/people.bib} + +\filesection{books.bib} + +The \exfile{books.bib} file contains details about books. +As above, the entries use custom commands provided in +\exfile{no-interpret-preamble.bib} and +\exfile{interpret-preamble.bib} or +\exfile{interpret-preamble2.bib}. +The entries all have a custom field \fieldfmt{identifier} set to +\code{book} and other custom fields \fieldfmt{author} and +\fieldfmt{year}. +These will be ignored by \bibgls\ unless they're +defined using \cs{glsaddkey} or \cs{glsaddstoragekey} or if they're +aliased with \csopt{field-aliases}. + +There are other ways in which this data could be specified. For +example, the \field{description} field could contain a brief summary +(or \qt{log line}). The \fieldfmt{author} field could use \BibTeX's +syntax instead with \csopt{bibtex-contributor-fields} to convert it. +Alternatively, the entries could be defined using standard \BibTeX\ +entry types that are all aliased to \atentry{bibtexentry}. + +The contents of \filefmt{books.bib} are as follows: +\lstinputlisting[firstline=5]{../examples/books.bib} + +\filesection{films.bib} + +The \exfile{films.bib} file contains details about films. +As above, the entries use custom commands provided in +\exfile{no-interpret-preamble.bib} and +\exfile{interpret-preamble.bib}. +The entries all have a custom field \fieldfmt{identifier} set to +\code{film} and other custom fields \fieldfmt{cast}, \fieldfmt{director} and +\fieldfmt{year}. These will be ignored by \bibgls\ unless they're +defined using \cs{glsaddkey} or \cs{glsaddstoragekey} or if they're +aliased with \csopt{field-aliases}. + +This example file references entries defined in \exfile{books.bib} +through the use of the special +\glsdisp{idx.idprefix.extn}{\idprefixfmt{ext1}} prefix. +To avoid a label conflict \exfile{films.bib} prefixes all labels +with \idprefixfmt{film} rather than relying on \csopt{label-prefix}. +This ensures that both \exfile{books.bib} and \exfile{films.bib} +can be loaded in the same resource set (otherwise they'd have to be +loaded in separate resource sets with different prefixes). Remember +that you can use \gls{glsxtrnewgls}. For example: +\begin{codeenv} +\gls{glsxtrnewgls}\marg{film.}\marg{\cmd{film}} +\end{codeenv} +This means you can do, for example, just \verb|\film{bladerunner}| +if you want to reference a film without worrying about the prefix. + +As with all the example files, there are other ways in which +to specify the data, depending on your requirements. For example, +the \fieldfmt{director} field could use \BibTeX's contributor syntax +(as the \fieldfmt{cast} field does). Some of +the films actually had more than one director but only one is listed +per film in this sample file for simplicity. Similarly, the +\fieldfmt{cast} field only contains the principle actors rather than the +complete list. The book on which the film is based +could be contained in a cross-reference field or a custom +\fieldfmt{basedon} field. + +The book \qt{Do Androids Dream of Electric Sheep?}\ referenced at the end +of the \qt{Blade Runner} film's \field{description} ends with +a question mark. (Similarly for \qt{Why Didn't They Ask Evans?}) +If the \field{description} field is simply set as: +\begin{codeenv} +\field{description}=\marg{a film starring Harrison Ford, Rutger Hauer + and Sean Young loosely based on the novel + \cs{gls}\marg{ext1.doandroidsdreamofelectricsheep}}, +\end{codeenv} +then the \styopt{postdot} package option will produce an odd +result as the inserted \idx{full-stop} immediately follows the question +mark. This is an awkward situation. One possibility is to explicitly +put the \idx{full-stop} at the end of the \field{description} field for all the +other entries and omit it for the problematic entries, but this +interferes with the possibility of a category-dependent +\idx{postdescriptionhook}. + +Another option is to put \ics{nopostdesc} in the +problematic entries. For example: +\begin{codeenv} +\field{description}=\marg{a film starring Harrison Ford, Rutger Hauer + and Sean Young loosely based on the novel + \cs{gls}\marg{ext1.doandroidsdreamofelectricsheep}\cs{nopostdesc}}, +\end{codeenv} +Be careful with this as it will completely suppress the +\idx{postdescriptionhook}. +A third possibility is to use \ics{glsxtrnopostpunc} instead: +\begin{codeenv} +\field{description}=\marg{a film starring Harrison Ford, Rutger Hauer + and Sean Young loosely based on the novel + \cs{gls}\marg{ext1.doandroidsdreamofelectricsheep}\cs{glsxtrnopostpunc}}, +\end{codeenv} +This doesn't interfere with the \idx{postdescriptionhook} but if a hook +is provided the post-punctuation may then be required. In both of +the above two cases, \csopt{strip-trailing-nopost} could be used +to remove the suppression commands from the \field{description} +fields if a hook is defined. However this doesn't deal with hooks +that only conditionally append text. + +The best solution is with \styfmt{glossaries-extra} v1.23+ which +provides \ics{glsxtrrestorepostpunc} for use in the category +\idxpl{postdescriptionhook} that counteracts \cs{glsxtrnopostpunc}. +This can be placed inside a conditional, as used in +\exfile{sample-media.tex}, and does nothing if \cs{glsxtrnopostpunc} +doesn't occur in the \field{description} field. (Note that +\cs{glsxtrrestorepostpunc} can't be used to counteract +\cs{nopostdesc}, since that completely suppresses the hook.) + +The contents of \filefmt{films.bib} are as follows: +\lstinputlisting[firstline=5]{../examples/films.bib} + +\filesection{citations.bib} + +The \exfile{citations.bib} file is actually a \BibTeX\ file, but it +can be parsed by \bibgls\ if the \BibTeX\ entry types are converted +to \atentry{bibtexentry}, which can easily be done with: +\begin{codeenv} +\csopt[\ics{GlsXtrBibTeXEntryAliases}]{entry-type-aliases} +\end{codeenv} +The field names will also need to be defined or aliased. For +example: +\begin{codeenv} +\csopt[\fieldfmt{title}=\field{name}]{field-aliases} +\end{codeenv} +If \bibgls\ is then run with \longarg{cite-as-record} any +\ics{citation} commands found in the \ext{aux} file will be treated +as ignored records. The \atentry{preamble} provides a formatting +command that's used by both \BibTeX\ and \bibgls, so \cs{providecommand} +is required rather than \cs{newcommand} as it will appear in both +the \iext{bbl} and the \iext{glstex} files. (In general it's best to +use \cs{providecommand} rather than \cs{newcommand} in the +\atentry{preamble} but in this case it's essential.) +The contents of \filefmt{citations.bib} are as follows: +\lstinputlisting[firstline=5]{../examples/citations.bib} + +\filesection{mathgreek.bib} + +The \exfile{mathgreek.bib} file contains Greek letters for use in +maths mode. These are all defined with \atentry{symbol}, which means +that by default the \field{sort} field will be obtained from the +label not from the \field{name} field. However, if you want to sort +by the \field{name} field (for example, with \csopt[name]{sort-field}) +the \TeX\ parser library recognises all the mathematical Greek letter commands +provided in the \LaTeX\ kernel. Additionally it recognises +\ics{omicron} which isn't provided by \LaTeX\ (the symbol can be +reproduced with a \idx!{lowercase} Latin \qt{o}). Note that +\isty{glossaries-extra-bib2gls} (\sty{glossaries-extra} v1.27+) +provides all the missing Greek letters (such as \cs{omicron}). + +The \ext{bib} file could just use \code{o}: +\begin{codeenv} +\atentry{symbol}\marg{omicron, + \field{name}=\marg{\cs{ensuremath}\marg{o}}, + \field{description}=\marg{omicron}, + \fieldfmt{identifier}=\marg{mathgreek} +} +\end{codeenv} +but this means that if \bibgls\ sorts according to the \field{name} +field using a letter sort, this entry will come before all the other +Greek letters since the character \qt{o} has Unicode value \hex{6F} +whereas, for example, mathematical italic small alpha ($\alpha$) +has Unicode value \hex{1D6FC}. This means that for sorting purposes +it's better to use \ics{omicron}: +\begin{codeenv} +\atentry{symbol}\marg{omicron, + \field{name}=\marg{\cs{ensuremath}\marg{\cs{omicron}}}, + \field{description}=\marg{omicron}, + \fieldfmt{identifier}=\marg{mathgreek} +} +\end{codeenv} +but \LaTeX\ needs a definition for this, so it's provided in the +\atentry{preamble}: +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cs{omicron}}\marg{o}}} +\end{codeenv} +(With \sty{glossaries-extra} v1.27+, this is no longer needed.) +The \TeX\ parser library and \sty{glossaries-extra-bib2gls} +similarly provide the missing \idx!{uppercase} +Greek letters, and these can be dealt with in the same way. + +The contents of \filefmt{mathgreek.bib} are as follows: +\lstinputlisting[firstline=5]{../examples/mathgreek.bib} + +\filesection{bigmathsymbols.bib} + +The \exfile{bigmathsymbols.bib} file contains mathematical symbols +that have a large version in display mode. As with +\exfile{mathgreek.bib} the entries are defined using +\atentry{symbol}. This example file requires the \isty{stix} package +as not all of the commands are provided by the \LaTeX\ kernel. +This file also has a preamble: +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cmd{providecommand}\marg{\cmd{bigoperatornamefmt}}[1]\marg{\comment{} + \idx{mshiftchar}\ics{displaystyle}\idx{param}1\ics{textstyle}\idx{param}1\idx{mshiftchar}} +\cmd{providecommand}\marg{\cmd{nary}}[1]\marg{\idx{mshiftchar}\idx{param}1\idx{mshiftchar}-ary}}} +\end{codeenv} +The first command \inlinedef{bigoperatornamefmt} +is used in the \field{name} field to display both the in-line and display +versions of the symbol. The \TeX\ parser library only has a limited ability to +interpret this as not all the symbols have Unicode in-line and large versions. +In some cases, such as the integral symbol $\int$, there is only a small +version. (A large version would require construction from \hex{2320}, +\hex{23AE} and \hex{2321}, which is too complicated in this context.) +However, the interpreter works well enough to guess at the widest +name if \csopt{set-widest} is used. There's no advantage in sorting +according to the \field{name} field here, unless a custom rule is +provided, as the Unicode symbols are scattered about different +blocks. Better approaches are to sort according to document use +(\csopt[use]{sort}) or to sort according to the \field{description} +field. + +The other custom command is \inlinedef{nary} to provide semantic markup for +\qt{$n$-ary}. This could be defined without an argument: +\begin{codeenv} +\cmd{providecommand}\marg{\cmd{nary}}\marg{\idx{mshiftchar}n\idx{mshiftchar}-ary} +\end{codeenv} +but providing an argument will allow \code{\csfmt{nary}\marg{n}} to work +with first letter upper-casing in the event that the +\field{description} field has a case-change applied (otherwise +it would end up as \qt{$N$-ARY}). Of course, it may be that no case-change +should be applied, but this example is just for illustrative purposes. + +As with the other sample \ext{bib} files, each entry is given a +custom \fieldfmt{identifier} field, which by default will be +ignored. In this case, \fieldfmt{identifier} is either set to +\code{naryoperator} (for $n$-ary operators) or \code{integral} +for integrals. + +The contents of \filefmt{bigmathsymbols.bib} are as follows: +\lstinputlisting[firstline=5]{../examples/bigmathsymbols.bib} + +\filesection{mathsrelations.bib} + +The \exfile{mathsrelations.bib} file contains mathematical +relational symbols. These use the maths shift character +\idx{mshiftchar} in the \field{name} field and just the symbol in +the \field{text} field. This just illustrates an alternative way of +defining symbols. Since \ics{ensuremath} isn't used, commands like +\cs{gls} must be explicitly placed in maths mode. For example, +\code{\idx{mshiftchar}\cs{gls}\marg{leq}\idx{mshiftchar}} rather than simply +\code{\cs{gls}\marg{leq}}. The custom \fieldfmt{identifier} field is +set to \code{relation}. + +The contents of \filefmt{mathsrelations.bib} are as follows: +\lstinputlisting[firstline=5]{../examples/mathsrelations.bib} + +\filesection{binaryoperators.bib} + +The \exfile{binaryoperators.bib} file contains mathematical binary +operators. The format is much like the above +\exfile{mathsrelations.bib} file. The custom \fieldfmt{identifier} +field is set to \code{binaryoperator}. + +The contents of \filefmt{binaryoperators.bib} are as follows: +\lstinputlisting[firstline=5]{../examples/binaryoperators.bib} + +\filesection{unaryoperators.bib} + +The \exfile{unaryoperators.bib} file contains mathematical unary +operators. As above, this again uses \atentry{symbol} to define the symbols, +but in this case \ics{ensuremath} is used in the \field{name} +field and there's no \field{text} field. I've also used \ics{mathord} +to ensure the symbol is treated as a unary (rather than binary) +operator, except for the \ics{forall} entry which is already defined as an +ordinary maths symbol. + +The contents of \filefmt{unaryoperators.bib} are as follows: +\lstinputlisting[firstline=5]{../examples/unaryoperators.bib} + +\filesection{mathsobjects.bib} + +The \exfile{mathsobjects.bib} file contains entries related to +mathematical objects (sets, spaces, vectors and matrices). This +provides some custom formatting commands in the preamble: +\nosecdef{setfmt} +which is used to format \meta{symbol} as a set, +\nosecdef{setcontentsfmt} +which is used to format the set contents, +\nosecdef{setmembershipfmt} +which is used to format the set membership criteria, +\nosecdef{setcardfmt} +which is used to format the cardinality of a set, +(Note this uses \ics{vert} not \textbar\ as in some of the earlier +examples.) +\nosecdef{numspacefmt} +which is used to format \meta{symbol} as a number space, +\nosecdef{transposefmt} +which is used to format matrix and vector transposes, +\nosecdef{invfmt} +which is used to format inverses, +\nosecdef{vecfmt} +which is used to format \meta{symbol} as a vector, and +\nosecdef{mtxfmt} +which is used to format \meta{symbol} as a matrix. +These commands are intended for use with \gls{glsxtrfmt}, +but \gls!{setmembershipfmt} causes a problem as it has two +arguments and \gls{glsxtrfmt} requires the control sequence to +have exactly one argument. This means employing a little trick. +A command with just one argument is provided: +\nosecdef{setmembershiponeargfmt} +that requires the actual two arguments to be supplied inside +\code{\idx!{param}1}. The outer grouping is removed and the two-argument +\gls!{setmembershipfmt} command is applied: +\begin{codeenv} +\cs{providecommand}\marg{\gls{setmembershiponeargfmt}}[1]\marg{\gls{setmembershipfmt}\idx{param}1} +\end{codeenv} +This means that the entry needs to be referenced in the document +using: +\begin{codeenv} +\gls{glsxtrfmt}\marg{setmembership}\marg{\margm{variable(s)}\margm{condition}} +\end{codeenv} +The simplest thing to do here is to provide a wrapper command in the +document, for example: +\begin{codeenv} +\cs{newcommand}*\marg{\cmd{setmembership}}[2]\marg{\gls{glsxtrfmt}\marg{setmembership}\marg{\marg{\idx{param}1}\marg{\idx{param}2}}} +\end{codeenv} +Now this can be used as: +\begin{codeenv} +\cmd{setmembership}\margm{variable(s)}\margm{condition} +\end{codeenv} + +There are essentially two types of entry defined in this file: +entries that demonstrate the formatting for the objects +and entries that represent specific objects. In the first case +there's a custom \fieldfmt{format} field +that's set to the control sequence name of the relevant semantic +command. If this field is defined or aliased then it can be used +with \gls!{glsxtrfmt} (as in the example above). + +In both cases there's a custom \fieldfmt{identifier} field that +reflects the type of object: \code{set} for sets, +\code{numberspace} for number spaces, +\code{matrix} for matrices or vectors. + +Be careful with the set cardinality example. Remember that nested +links cause problems and the \sty{glossaries-extra} manual advises +against using commands like \cs{gls} or \gls!{glsxtrfmt} within +link text and that includes within the \meta{text} argument of +\gls!{glsxtrfmt}. See \exfile{sample-maths.tex} for suggested +usage. + +Some of the \field{description} fields use \gls!{sortart}, so +\exfile{no-interpret-preamble.bib} and +\exfile{interpret-preamble.bib} are also needed. + +The contents of \filefmt{mathsobjects.bib} are as follows: +\lstinputlisting[firstline=5]{../examples/mathsobjects.bib} + +\filesection{miscsymbols.bib} + +The \exfile{miscsymbols.bib} file contains text symbols provided +by the \isty{marvosym} and \isty{ifsym} packages. The \sty{ifsym} +package needs to be loaded with the \styoptfmt{weather} option +to provide the weather commands. Unfortunately both packages define +\csfmt{Sun} and \csfmt{Lightning}, which causes a conflict. See +\exfile{sample-textsymbols.tex} for a workaround. Alternatively, +you can load \sty{ifsym} without the \styoptfmt{weather} option +and use the internal definition of \sty{ifsym}'s \csfmt{Sun} +and \csfmt{Lightning} commands: +\begin{codeenv} +\atentryfmt{icon}\marg{sun, + \fieldfmt{icon}=\marg{\ics{textweathersymbol}\marg{16}}, + \fieldfmt{description}=\marg{sunny}, + \fieldfmt{identifier}=\marg{weather} +} +\strut +\atentryfmt{icon}\marg{lightning, + \fieldfmt{icon}=\marg{\cs{textweathersymbol}\marg{26}}, + \field{description}=\marg{thunderstorm}, + \fieldfmt{identifier}=\marg{weather} +} +\end{codeenv} +This removes the conflict, and \csfmt{Sun} and \csfmt{Lightning} +are as defined by \sty{marvosym}. + +This file uses a custom entry type \atentryfmt{icon}, which must be +aliased to a recognised entry identifier otherwise the entries will +all be ignored. For example: +\begin{codeenv} +\csopt[\fieldfmt{icon}=\field{symbol}]{entry-type-aliases} +\end{codeenv} + +There are three types of symbols defined: media controls, information +and weather. They have the custom \fieldfmt{identifier} +field set to \code{mediacontrol}, \code{information} and +\code{weather}, respectively. There are two other custom fields: +\fieldfmt{icon} and \fieldfmt{icondescription}. These will need to +be aliased to \field{name} and \field{description}. + +Neither of these packages are recognised by \bibgls, which means +that \csopt{set-widest} won't be able to determine the widest name +nor is this data suitable for sorting according to the +\fieldfmt{icon} field (or its alias). Instead, either sort by label +(which is the default for \atentry{symbol}) or by the +\field{description}. If you want to use one of the +\glostyle{alttree} styles you can still use \csopt{set-widest}, but +it will have to use the fallback command. Alternatively, you can +omit \csopt{set-widest} and explicitly use +\cs{glsFindWidestTopLevelName}. + +The contents of \filefmt{miscsymbols.bib} are as follows: +\lstinputlisting[firstline=5]{../examples/miscsymbols.bib} + +\filesection{markuplanguages.bib} + +The \exfile{markuplanguages.bib} file includes a mixture of +\atentry{entry} and \atentry{abbreviation} definitions. A~custom +command is provided in \atentry{preamble} to tag the letters +in the \field{long} field that are used to form the abbreviation. +This simply does its argument and is provided in case it's not set +up in the document. If you do want to enable tagging using +\ics{GlsXtrEnableInitialTagging}, remember that this command must be +used before the abbreviations are defined, which means before +the resource file is input with \gls{GlsXtrLoadResources}. +Similarly, the abbreviation style must be set before the +abbreviations are defined. + +For convenience \atentry{string} is also used to define a \ext{bib} +variable, which may be appended to fields using the \ext{bib} +concatenation character \idx{stringconcat}. As with the other sample +\ext{bib} files, there's a custom field \fieldfmt{identifier} +which will be ignored unless defined or aliased. + +The empty braces at the start some of the fields are there to +protect against first letter uppercasing within \TeX, where it might cause a +problem. (For example, with the \catattr{glossname} attribute.) + +The contents of \filefmt{markuplanguages.bib} are as follows: +\lstinputlisting[firstline=5]{../examples/markuplanguages.bib} + +\filesection{usergroups.bib} + +The \exfile{usergroups.bib} file requires either \XeLaTeX\ or +\LuaLaTeX\ as some of the entry labels use \idx{non-ASCII} characters. +This file has a mixture of \atentry{abbreviation} and +\atentry{index} entries. It also uses \atentry{string} for +convenience and provides a custom command \csfmt{dash} in +\atentry{preamble}. Each entry is the name of a \TeX\ user group: +the international \idx{TUG} and all the local groups. +Most of them have an abbreviated name, so they're defined with +\atentry{abbreviation}. There are a few without an abbreviation, so +they're defined with \atentry{index} instead. There's one alias. +(The information was obtained from \idx{TUG}['s] +\href{http://tug.org/usergroups.html}{user groups +page}~\cite{tugusergroups}.) + +As with the other examples, there are some custom fields which will +be ignored if they aren't defined or aliased: \fieldfmt{identifier} +(set to \code{texusergroup}), \fieldfmt{language} (a comma-separated +list of language tags) and \fieldfmt{translation} (provides a +translation if the user group name isn't in English). + +Not all entries have a \fieldfmt{translation} field. It it's +omitted, then the user group name is in English, otherwise it's +in the first language listed in the \fieldfmt{language} field. +Most of the language tags are just the ISO 639-1 language code, but +a few of them include the ISO 3166-1 region code as well. + +The contents of \filefmt{usergroups.bib} are as follows: +\begin{lstlisting}[escapechar=|] +% Encoding: UTF-8 + +% Requires XeLaTeX/LuaLaTeX for non-ASCII labels + +@string{tug={\TeX\ Users Group}} + +@preamble{"\providecommand{\dash}{\,---\,}"} + +@abbreviation{TUG, + short={TUG}, + long=tug, + language={en}, + identifier={texusergroup} +} + +@abbreviation{bgTeX, + short={bgTeX}, + long={Bulgarian \LaTeX\ Users Group}, + language={bg}, + identifier={texusergroup} +} + +@abbreviation{latex-br, + short={latex-br}, + long={Grupo de Usuários}, + language={pt-BR}, + identifier={texusergroup}, + translation={Brazilian }#tug +} + +@abbreviation{CTeX, + short={CTeX}, + long={Chinese \TeX\ Society}, + identifier={texusergroup}, + language={zh} +} + +@abbreviation{CSTUG, + short={CSTUG}, + long={|Československé sdružení uživatelů TeXu|, z.~s.}, + language={cs}, + identifier={texusergroup}, + translation={Czech Republic }#tug +} + +@abbreviation{DANTE, + short={DANTE e.V.}, + long={Deutschsprachige Anwendervereinigung \TeX\ e.V.}, + language={de}, + identifier={texusergroup}, + translation={German Speaking }#tug +} + +@abbreviation{DKTUG, + short={DK-TUG}, + long={Danish }#tug, + language={da}, + identifier={texusergroup} +} + +@index{EUG, + name={Estonian User Group}, + language={et}, + identifier={texusergroup} +} + +@abbreviation{CervanTeX, + short={CervanTeX}, + long={Grupo de Usuarios de \TeX\ Hispanohablantes}, + language={es}, + identifier={texusergroup}, + translation={Spanish Speaking }#tug +} + +@abbreviation{TirantloTeX, + short={Tirant lo \TeX}, + long={Catalan }#tug, + language={ca}, + identifier={texusergroup} +} + +@abbreviation{GUTenberg, + short={GUTenberg}, + long={Groupe francophone des utilisateurs de \TeX}, + language={fr}, + identifier={texusergroup}, + translation={French Speaking }#tug +} + +@abbreviation{UKTUG, + short={UK-TUG}, + long={UK }#tug, + language={en-GB}, + identifier={texusergroup} +} + +@abbreviation{|\greekmono ɛϕτ|, + short={|\greekmono ɛϕτ|}, + long={|\greekmono Σύλλογος Ελλήνων Φίλων του| \TeX}, + language={el}, + identifier={texusergroup}, + translation={Greek \TeX\ Friends} +} + +@abbreviation{MaTeX, + short={MaTeX}, + long={Magyar \TeX\ Egyesület}, + language={hu}, + identifier={texusergroup}, + translation={Hungarian }#tug +} + +@abbreviation{ITALIC, + short={ITALIC}, + long={Irish \TeX\ and \LaTeX\ In-print Community}, + language={en-IE,en-GB}, + identifier={texusergroup} +} + +@abbreviation{ÍsTeX, + short={ÍsTeX}, + long={Vefur íslenskra \TeX\ notenda}, + language={is}, + identifier={texusergroup}, + translation={Icelandic }#tug +} + +@abbreviation{GuIT, + short={GuIT}, + long={Gruppo Utilizzatori Italiani di \TeX}, + language={it}, + identifier={texusergroup}, + translation={Italian }#tug +} + +@abbreviation{KTS, + short={KTS}, + identifier={texusergroup}, + long={Korean \TeX\ Society}, + language={ko} +} + +@index{KTUG, + alias={KTS}, + identifier={texusergroup} +} + +@index{LTVG, + name={Lietuvos \TeX'o |Vartotojų Grupė|}, + language={lt}, + identifier={texusergroup}, + translation={Lithuanian }#tug +} + +@index{mxTeX, + name={\TeX\ México}, + language={es-MX}, + identifier={texusergroup}, + translation={Mexican }#tug +} + +@abbreviation{NTG, + short={NTG}, + long={Nederlandstalige \TeX\ Gebruikersgroep}, + language={nl}, + identifier={texusergroup}, + translation={Netherlands }#tug +} + +@index{NTUG, + name={Nordic \TeX\ Users Group}, + language={da,et,fi,fo,is,nb,nn,sv}, + identifier={texusergroup} +} + +@abbreviation{GUST, + short={GUST}, + long={Polska Grupa |Użytkowników| Systemu \TeX}, + language={pl}, + identifier={texusergroup}, + translation={Polish }#tug +} + +@abbreviation{GUTpt, + short={GUTpt}, + long={Grupo de Utilizadores de \TeX}, + language={pt}, + identifier={texusergroup}, + translation={Portuguese }#tug +} + +@abbreviation{VietTUG, + short={VietTUG}, + long={Vietnamese }#tug, + language={vi}, + identifier={texusergroup} +} + +@abbreviation{LUGSA, + short={LUGSA}, + long={\LaTeX\ User Group\dash South Africa}, + language={en-ZA}, + identifier={texusergroup} +} + + +\end{lstlisting} + +\filesection{animals.bib} + +The \exfile{animals.bib} file contains entries defined using +\atentry{entry}. As with the above example \ext{bib} files, there's +a custom \fieldfmt{identifier} field that will be ignored unless +defined or aliased. + +The contents of \filefmt{animals.bib} are as follows: +\lstinputlisting[firstline=5]{../examples/animals.bib} + +\filesection{minerals.bib} + +The \exfile{minerals.bib} file contains entries defined using +\atentry{entry}. As with the above example \ext{bib} files, there's +a custom \fieldfmt{identifier} field that will be ignored unless +defined or aliased. + +The contents of \filefmt{minerals.bib} are as follows: +\lstinputlisting[firstline=5]{../examples/minerals.bib} + +\filesection{vegetables.bib} + +The \exfile{vegetables.bib} file contains entries defined using +\atentry{entry} and an entry defined with \atentry{index} with just +the \field{alias} field. As with the above example \ext{bib} files, there's +a custom \fieldfmt{identifier} field that will be ignored unless +defined or aliased. + +The contents of \filefmt{vegetables.bib} are as follows: +\lstinputlisting[firstline=5]{../examples/vegetables.bib} + +\filesection{terms.bib} + +The \exfile{terms.bib} file contains entries defined using +\atentry{index}. Unlike the above sample \ext{bib} files, there +are no custom fields here. + +The contents of \filefmt{terms.bib} are as follows: +\lstinputlisting[firstline=5]{../examples/terms.bib} + +\filesection{topics.bib} + +The \exfile{topics.bib} file contains entries defined using +\atentry{index}. Again there are no custom fields here. + +The contents of \filefmt{topics.bib} are as follows: +\lstinputlisting[firstline=5]{../examples/topics.bib} + +\filesection{sample-constants.tex} + +This example uses the \exfile{constants.bib} file. The aim here +is to just have a list of all the constants defined in the \ext{bib} +file. (There are no references in the document.) This means I need +to use: +\begin{codeenv} +\csopt[all]{selection} +\end{codeenv} +in order to select all entries. I also need to alias the custom +\atentryfmt{constant} entry type otherwise all the entries will be +ignored. I decided to make \atentryfmt{constant} behave like +\atentry{number} for semantic reasons: +\begin{codeenv} +\csopt[constant=number]{entry-type-aliases} +\end{codeenv} +The custom fields also need aliasing: +\begin{codeenv} +\csopt[ + \fieldfmt{identifier}=\field{category}, + \fieldfmt{constantsymbol}=\field{name}, + \fieldfmt{constantname}=\field{description}, + \fieldfmt{value}=\field{user1}, + \fieldfmt{definition}=\field{user2}, + \fieldfmt{alternative}=\field{user3}, +]{field-aliases} +\end{codeenv} +I decided to use the \glostyle{altlist} style, so I've instructed +\bibgls\ to determine the widest name: +\begin{codeenv} +\csopt{set-widest} +\end{codeenv} +It's always a good idea to specify the glossary type when using +\csopt{set-widest}, although in this example there's only one +glossary so it doesn't make much difference. +\begin{codeenv} +\csopt[main]{type} +\end{codeenv} +I decided to order the constants according to their (approximate) +numerical value. I've aliased the custom \fieldfmt{value} field to +\field{user1}, so I can sort by that field using a numerical +comparison: +\begin{codeenv} +\csopt[\field{user1}]{sort-field}, +\csopt[double]{sort} +\end{codeenv} +There are three entries without the \fieldfmt{user1} field (as the +custom \fieldfmt{value} field is missing in the \ext{bib} file): +\code{zero}, \code{one} and \code{imaginary}. In the case of +\code{zero} and \code{one} the exact value can be obtained from the +\field{name} field. Since I've change the default \csopt{sort-field}, I +can't use \csopt{symbol-sort-fallback}. Instead I need to use: +\begin{codeenv} +\csopt[\field{name}]{missing-sort-fallback} +\end{codeenv} + +What happens with the \code{imaginary} entry? It has no real +representation. The transcript (\ext{glg}) file shows the message: +\begin{verbatim} +Warning: Can't parse sort value 'i' for: imaginary +\end{verbatim} +With the numerical sort methods, if the field can't be parsed the +value defaults to 0. This means that both \code{zero} and +\code{imaginary} have 0 as the sort value, so the +\csopt{identical-sort-action} is implemented. The default setting +means that \bibgls\ will fallback on comparing the entry labels, so +\code{imaginary} comes before \code{zero}. + +Since I'm just using the \glostyle{alttree} style, I only need +\sty{glossary-tree}. I can improve efficiency in the document build +by preventing the other glossary style packages from being loaded +using the \styopt{nostyles} package option. This also prevents +\sty{glossary-tree} from being loaded, but I can both load it and +patch the styles with \sty{glossaries-extra-stylemods} through the +option \styopt[tree]{stylemods}. Since the default \glostyle{list} +style is no longer available, I need to set a new default with +\styopt[alttree]{style}. I also want to automatically insert a +\idx{full-stop} after the description, which can be done with +\styopt{postdot}. Don't forget that the \styopt{record} option is +always needed when using \bibgls. This means that the +\sty{glossaries-extra} package needs to be loaded as follows: +\begin{codeenv} +\cs{usepackage}\oarg{\styopt{record},\styopt{nostyles},\styopt{postdot},\styopt[tree]{stylemods},\styopt[alttree]{style}} + \marg{glossaries-extra} +\end{codeenv} +I've assigned the custom \fieldfmt{constantname} field to the +\field{description} field and the custom \fieldfmt{constantsymbol} field to the +\field{name} field. This means that by default the glossary list +will just show the symbolic representation and the constant's name. +I'd like to append the value and definition after the description. +With the base \sty{glossaries} package this would require defining a +new glossary style but with \sty{glossaries-extra} it can easily be +achieved through the \idx{postdescriptionhook}. + +I've aliased the custom \fieldfmt{identifier} field to +\field{category}, which means that all the entries will have the +\field{category} set to \code{constant}. The +\idx{postdescriptionhook} is obtained from +\idx{glsxtrpostdesccategory}, so I need to define +the command \csfmt{glsxtrpostdescconstant}. A simple definition is: +\begin{codeenv} +\cs{newcommand}\marg{\cmd{glsxtrpostdescconstant}}\marg{\comment{} + \cs{space} (approximately \cs{glsentryuseri}\marg{\cs{glscurrententrylabel}})\comment{} + : \cs{glsentryuserii}\marg{\cs{glscurrententrylabel}}\comment{} +} +\end{codeenv} +This is fine if all entries have the \field{user1} and \field{user2} +fields set. A more generic approach tests for the existence of these +fields. This can either be done with \ics{ifglshasfield}: +\begin{codeenv} +\cs{newcommand}\marg{\cmd{glsxtrpostdescconstant}}\marg{\comment{} + \cs{ifglshasfield}\marg{\field{user1}}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{ (approximately \cs{glscurrentfieldvalue})}\comment{} + \marg{}\comment{} + \cs{ifglshasfield}\marg{\field{user2}}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{: \cs{glscurrentfieldvalue}}\comment{} + \marg{}\comment{} +} +\end{codeenv} +or with \ics{glsxtrifhasfield}: +\begin{codeenv} +\cs{newcommand}\marg{\cmd{glsxtrpostdescconstant}}{\comment{} + \cs{glsxtrifhasfield}\marg{\field{useri}}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{ (approximately \cs{glscurrentfieldvalue})}\comment{} + \marg{}\comment{} + \cs{glsxtrifhasfield}\marg{\field{userii}}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{: \cs{glscurrentfieldvalue}}\comment{} + \marg{}\comment{} +} +\end{codeenv} +(Note the need to use the internal field label \field{useri} and +\field{userii} with \ics{glsxtrifhasfield}.) + +A modification can be made to also show the alternative +representation (obtained from the custom \fieldfmt{alternative} +field which has been aliased to \field{user3}): +\begin{codeenv} +\cs{newcommand}\marg{\cmd{glsxtrpostdescconstant}}{\comment{} + \cs{glsxtrifhasfield}\marg{\field{useriii}}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{ (also denoted \cs{glscurrentfieldvalue} + \cs{glsxtrifhasfield}\marg{\field{useri}}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{, approximately \cs{glscurrentfieldvalue}}\comment{} + \marg{}\comment{} + )\comment{} + }\comment{} + \marg{\comment{} + \cs{glsxtrifhasfield}\marg{\field{useri}}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{ (approximately \cs{glscurrentfieldvalue})}\comment{} + \marg{}\comment{} + }\comment{} + \cs{glsxtrifhasfield}\marg{\field{userii}}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{: \cs{glscurrentfieldvalue}}\comment{} + \marg{}\comment{} +} +\end{codeenv} +If you have at least \styfmt{glossaries-extra} v1.31, it's better to use: +\begin{codeenv} +\ics{glsdefpostdesc}\marg{constant} +\end{codeenv} +instead of: +\begin{codeenv} +\cs{newcommand}\marg{\cmd{glsxtrpostdescconstant}} +\end{codeenv} +as it can guard against accidental misspelling of the \code{glsxtrpostdesc} +part of the command name. + +The complete code is listed below. The document build is: +\begin{verbatim} +pdflatex sample-constants +bib2gls sample-constants +pdflatex sample-constants +\end{verbatim} +The complete document is shown in \figureref{fig:sample-constants.pdf}. + +\lstinputlisting[firstline=5]{../examples/sample-constants.tex} + +\begin{figure} +\figcontents +{% + \frame{\includegraphics[height=.9\textheight]{../examples/sample-constants.pdf}}% +} +{\caption{\filefmt{sample-constants.pdf}}} +{fig:sample-constants.pdf} +\end{figure} + +\filesection{sample-chemical.tex} + +This example just uses the \exfile{chemicalformula.bib} file. The aim here +is to have a list of chemical formulae referenced in the document +but not have a number list. I could use the \styopt{nonumberlist} +package option to suppress the number list display, but it's more +efficient to instruct \bibgls\ to not save the number list with: +\begin{codeenv} +\csopt[false]{save-locations} +\end{codeenv} +All entries are defined in \exfile{chemicalformula.bib} using +a custom entry type \atentryfmt{chemical} which needs to be aliased +in order for the entries to be recognised: +\begin{codeenv} +\csopt[chemical=symbol]{entry-type-aliases} +\end{codeenv} +Additionally, the entries only have custom fields, so these also +need to be aliased. In this case I want the formula in the \field{name} field +and the chemical name in the \field{description} field: +\begin{codeenv} +\csopt[\fieldfmt{formula}=\field{name},\fieldfmt{chemicalname}=\field{description}]{field-aliases} +\end{codeenv} +The \atentry{symbol} entry type falls back on the label for the +\field{sort} value by default, but I've decided +to fallback on the \field{name} field for sorting: +\begin{codeenv} +\csopt[\field{name}]{symbol-sort-fallback} +\end{codeenv} +An alternative approach would simply be to alias +\atentryfmt{chemical} to \atentry{entry} instead. + +Since the \field{name} field contains chemical formulae rather than +words, it makes more sense to use one of the letter sort methods +rather than a locale collator. In this case the names contain +mixtures of letters and numbers, so one of the letter-number sort +methods (listed in \tableref{tab:sortoptionsletternumber}) would be +appropriate. + +I want to use the \glostyle{alttreegroup} style (provided by +\sty{glossary-tree}). Since I don't require the other style +packages, I've used \styopt{nostyles} to suppress the automatic +loading and \styopt[tree]{stylemods} to both load +\sty{glossary-tree} and patch it. The \glostyle{alttreegroup} style +needs to know the widest name, so I've use \csopt{set-widest} for +convenience. The default behaviour of the tree styles is to +format the name in bold. This is done through the command +\ics{glstreenamefmt} which is defined as: +\begin{codeenv} +\cs{newcommand}*\marg{\cs{glstreenamefmt}}[1]\marg{\cs{textbf}\marg{\idx{param}1}} +\end{codeenv} +The group headings use \ics{glstreegroupheaderfmt} which defaults to +\cs{glstreenamefmt}. Since I want to keep bold headings, I need to +redefine this as well: +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{glstreenamefmt}}[1]\marg{\idx{param}1} +\cs{renewcommand}*\marg{\cs{glstreegroupheaderfmt}}[1]\marg{\cs{textbf}\marg{\idx{param}1}} +\end{codeenv} +(For a more compact layout, you could use \glostyle{mcolalttreegroup} +instead.) +I also need the \longarg{group} switch to make the sort method +automatically assign letter groups. + +The complete code is listed below. The document build is: +\begin{verbatim} +pdflatex sample-chemical +bib2gls --group sample-chemical +pdflatex sample-chemical +\end{verbatim} +The complete document is shown in \figureref{fig:sample-chemical.pdf}. + +\lstinputlisting[firstline=5]{../examples/sample-chemical.tex} + +\begin{figure} +\figcontents +{% + \frame{\includegraphics[height=.9\textheight]{../examples/sample-chemical.pdf}}% +} +{\caption{\filefmt{sample-chemical.pdf}}} +{fig:sample-chemical.pdf} +\end{figure} + +\filesection{sample-bacteria.tex} + +This example just uses the \exfile{bacteria.bib} file. The aim here +is to have a simple list of the bacteria referenced in the document. +Bacteria names are often shown in the long form on first use +(without the short form) and then the short form on subsequent use. +This can easily be done with the \abbrstyle{long-only-short-only} +style. Bacteria are usually typeset in italic. It's best to create a +semantic command for this: +\begin{codeenv} +\cs{newcommand}\marg{\cmd{bacteriafont}}[1]\marg{\cs{emph}\marg{\idx{param}1}} +\end{codeenv} +There are two methods to apply this to the bacteria entries. The +first is to redefine the formatting commands used by the +\abbrstyle{long-only-short-only} style: +\begin{codeenv} +\cs{renewcommand}*\marg{\ics{glsabbrvonlyfont}}[1]\marg{\cmd{bacteriafont}\marg{\idx{param}1}} +\cs{renewcommand}*\marg{\ics{glslongonlyfont}}[1]\marg{\cmd{bacteriafont}\marg{\idx{param}1}} +\end{codeenv} +This is fine if I don't intend to use this style for other types of +abbreviations. However, I may decide to extend the document at a +later date to include other abbreviations that need +\abbrstyle{long-only-short-only} but shouldn't be emphasized. +This can be done through the use of \idxpl{categoryattribute}. +The font used for the \field{name} in the glossary is governed by +the \catattr{glossnamefont} attribute, the font used for the +\field{description} in the glossary is governed by the +\catattr{glossdescfont} attribute and the font used by commands like +\cs{gls} in the document is governed by the \catattr{textformat} +attribute (\styfmt{glossaries-extra} v1.21+). So if I set +the \field{category} to \code{bacteria} then I can do: +\begin{codeenv} +\cs{setabbreviationstyle}\oarg{bacteria}\marg{\abbrstyle{long-only-short-only}} +\cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{textformat}}\marg{bacteriafont} +\cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{glossnamefont}}\marg{bacteriafont} +\end{codeenv} +and (if the \field{description} field is displayed in the glossary): +\begin{codeenv} +\cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{glossdescfont}}\marg{bacteriafont} +\end{codeenv} +(Note that the attribute value is the control sequence name without +the initial backslash.) + +I'd like to use the \glostyle{bookindex} style, which is +provided by the \sty{glossary-bookindex} +package.\footnote{\styfmt{glossary-bookindex} +is distributed with \styfmt{glossaries-extra} v1.21+.} This isn't loaded +automatically, but it can be loaded through the +\styopt{stylemods} package option: +\begin{codeenv} +\cmd{usepackage}[\styopt{record},\comment{use bib2gls} + \styopt{nostyles},\comment{don't load default style packages} + \styopt[bookindex]{stylemods},\comment{load glossary-bookindex.sty and patch styles} + \styopt[bookindex]{style}]\marg{glossaries-extra} +\end{codeenv} +I've used the \styopt{nostyles} package option to suppress loading +the default style packages, since I'm not using them. If you inspect +the \ext{log} file, you may notice that \sty{glossary-tree} is still +loaded. This is because it's required by \sty{glossary-bookindex} +as the \glostyle{bookindex} style is based on the \glostyle{index} +style provided by \sty{glossary-tree}. +With this style I need to use the \longarg{group} switch to instruct +the sort method to automatically create the letter groups. + +The \glostyle{bookindex} style doesn't show the \field{description} +field (which means I don't need the \catattr{glossdescfont} +attribute) and, since the \abbrstyle{long-only-short-only} style sets +the \field{name} to the short form by default, only the short form +will show in the glossary. I'd rather it was just the long form. +This could simply be done using \csopt{replicate-fields} to copy the +\field{long} field to the \field{name} field: +\begin{codeenv} +\csopt[\field{long}=\field{name}]{replicate-fields} +\end{codeenv} +Again, I want to consider the possibility of adding other types of +abbreviations and this might not be appropriate for them (for +example, I might want some abbreviations with the long form followed +by the short form in parentheses). Another +approach is to redefine \ics{glsxtrbookindexname} which is used by +the \glostyle{bookindex} style to display the name. This takes the +entry's label as the argument. The default definition is: +\begin{codeenv} +\cs{newcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\cs{glossentryname}\marg{\idx{param}1}} +\end{codeenv} +This can be changed to test for the entry's category: +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\comment{} + \ics{glsifcategory}\marg{\idx{param}1}\marg{bacteria} + \marg{\cs{glossentrynameother}\marg{\idx{param}1}\marg{\field{long}}}\comment{} + \marg{\cs{glossentryname}\marg{\idx{param}1}}\comment{} +} +\end{codeenv} +Note that I've used \ics{glossentrynameother} here rather than +\ics{glsentrylong}. This ensures that it follows the same formatting +as \ics{glossentryname} (so it will use \ics{glsnamefont} or the +\catattr{glossnamefont} attribute, the \catattr{glossname} +attribute, and the \idx{postnamehook}, if set). In this case it +picks up the \catattr{glossnamefont} attribute, which is used +instead of \cs{glsnamefont}. + +If the \field{sort} field is missing for abbreviation styles, the +fallback value is the \field{short} field (not the \field{name} +field). In this case it would be better to fallback on the +\field{long} field instead, which can be done with the +\csopt{abbreviation-sort-fallback} option: +\begin{codeenv} +\csopt[\field{long}]{abbreviation-sort-fallback} +\end{codeenv} +If I do add other types of abbreviations, they will all be sorted +according to the \field{long} form, but at least this way I can have +some \meta{long} (\meta{short}) names as well. + +The complete code is listed below. The document build is: +\begin{verbatim} +pdflatex sample-bacteria +bib2gls --group sample-bacteria +pdflatex sample-bacteria +\end{verbatim} +This simple example only references entries on the first page so all +entries just have~1 in the number list. The complete document is +shown in \figureref{fig:sample-bacteria.pdf}. + +\lstinputlisting[firstline=5]{../examples/sample-bacteria.tex} + +\begin{figure} +\figcontents +{% + \frame{\includegraphics[height=.9\textheight]{../examples/sample-bacteria.pdf}}% +} +{\caption{\filefmt{sample-bacteria.pdf}}} +{fig:sample-bacteria.pdf} +\end{figure} + +\filesection{sample-units1.tex} + +This example uses the \exfile{baseunits.bib} and +\exfile{derivedunits.bib} files. The aim here is to have a glossary +in two blocks: base units and derived units. This can be achieved by +first loading \exfile{baseunits.bib} with \csopt{group} set to the +desired group title (\qt{Base Units} in this case) and then load +\exfile{derivedunits.bib} with the \csopt{group} set to the desired +title (\qt{Derived Units} in this case). Remember that the +\field{group} field needs to be used as a label. If the group title +contains any problematic characters or commands, then it's better to +use labels: +\begin{codeenv} +\csopt[baseunits]{group} +\end{codeenv} +for the first \idx{resourceset} and +\begin{codeenv} +\csopt[derivedunits]{group} +\end{codeenv} +for the second, and then set the group titles: +\begin{codeenv} +\gls{glsxtrsetgrouptitle}\marg{baseunits}\marg{Base Units} +\gls{glsxtrsetgrouptitle}\marg{derivedunits}\marg{Derived Units} +\end{codeenv} +I've used this method to make it easier to adapt to other languages +that may need extended characters in the group titles. +The \csopt{group} option requires the \longarg{group} switch to +ensure that the \field{group} field is correctly assigned. + +The \exfile{baseunits.bib} file use a custom entry type +\atentryfmt{unit}, which must be aliased otherwise \bibgls\ +will ignore the entries. I decided to use \atentry{symbol} for +semantic reasons: +\begin{codeenv} +\csopt[unit=symbol]{entry-type-aliases} +\end{codeenv} +Similarly for the custom \atentryfmt{measurement} entry type in +\exfile{derivedunits.bib}: +\begin{codeenv} +\csopt[measurement=symbol]{entry-type-aliases} +\end{codeenv} +Remember that \atentry{symbol} uses the label as the default sort fallback, +so I've changed it to use \field{name} instead: +\begin{codeenv} +\csopt[\field{name}]{symbol-sort-fallback} +\end{codeenv} +An alternative approach would be to alias \atentryfmt{unit} +and \atentryfmt{measurement} to \atentry{entry} instead. + +Since there's no \csopt{type} set, all entries end up in the main +glossary, but since there are two resource commands the glossary +ends up with sorted blocks. + +The document doesn't include any commands like \cs{gls}, so +I've use \csopt[all]{selection} to select all entries in the \ext{bib} +files. There won't be any number lists since there are no records. +I need a glossary style that shows the \field{symbol} field so I've +used \glostyle{mcolindexgroup}. Again I've suppressed the automatic +loading of the default styles with \styopt{nostyles} and used +\styopt[mcols]{stylemods} to load \sty{glossary-mcols} and patch the +styles. Note that although I've used \styopt{nostyles}, the +\sty{glossary-tree} style is loaded as it's required by +\sty{glossary-mcols}. + +As with the previous example, the custom fields need to be aliased: +\begin{codeenv} +\csopt[ + \fieldfmt{unitname}=\field{name}, + \fieldfmt{unitsymbol}=\field{symbol}, + \fieldfmt{measurement}=\field{description} +]{field-aliases} +\end{codeenv} + +The complete document code is listed below. The document build is: +\begin{verbatim} +pdflatex sample-units1 +bib2gls --group sample-units1 +pdflatex sample-units1 +\end{verbatim} +The complete document is shown in \figureref{fig:sample-units1.pdf}. + +\lstinputlisting[firstline=5]{../examples/sample-units1.tex} + +\begin{figure} +\figcontents +{% + \frame{\includegraphics[height=.9\textheight]{../examples/sample-units1.pdf}}% +} +{\caption{\filefmt{sample-units1.pdf}}} +{fig:sample-units1.pdf} +\end{figure} + +\filesection{sample-units2.tex} + +This example is provided for comparison with +\exfile{sample-units1.tex}. Instead of having a single glossary with +sorted blocks this example has two glossaries: +\begin{codeenv} +\ics{newglossary*}\marg{baseunits}\marg{Base Units} +\cs{newglossary*}\marg{derivedunits}\marg{Derived Units} +\end{codeenv} +I've used the \styopt{section} package option to use \ics{section*} for the +glossary titles. This overrides the default \ics{chapter*} which is +used with book or report type of classes. I've also used the +\styopt{nomain} option to suppress the creation of the main glossary +as I want to define my own glossary types instead. + +As before the custom entry types need to be aliased: +\begin{codeenv} +\csopt[unit=symbol]{entry-type-aliases} +\end{codeenv} +for the first \idx{resourceset} and +\begin{codeenv} +\csopt[measurement=symbol]{entry-type-aliases} +\end{codeenv} +for the second. Similarly for the custom entry fields: +\begin{codeenv} +\csopt[ + \fieldfmt{unitname}=\field{name}, + \fieldfmt{unitsymbol}=\field{symbol}, + \fieldfmt{measurement}=\field{description} +]{field-aliases} +\end{codeenv} +The \longarg{group} switch is needed to ensure that the +\field{group} field is automatically assigned by the sort method. + +The complete document code is listed below. The document build is: +\begin{verbatim} +pdflatex sample-units2 +bib2gls --group sample-units2 +pdflatex sample-units2 +\end{verbatim} +The complete document is shown in \figureref{fig:sample-units2.pdf}. + +\lstinputlisting[firstline=5]{../examples/sample-units2.tex} + +\begin{figure} +\figcontents +{% + \frame{\includegraphics[height=.9\textheight]{../examples/sample-units2.pdf}}% +} +{\caption{\filefmt{sample-units2.pdf}}} +{fig:sample-units2.pdf} +\end{figure} + +\filesection{sample-units3.tex} + +This is another example that uses the \exfile{baseunits.bib} and +\exfile{derivedunits.bib} files. As before the custom fields need to be aliased: +\begin{codeenv} +\csopt[ + \fieldfmt{unitname}=\field{name}, + \fieldfmt{unitsymbol}=\field{symbol}, + \fieldfmt{measurement}=\field{description} +]{field-aliases} +\end{codeenv} +This time I want two glossaries containing all the units (base and +derived) where the first glossary is ordered by name and the second +is ordered by symbol. This can be done with a single resource +command that instructs \bibgls\ to make the custom \atentryfmt{unit} +and \atentryfmt{measurement} entry types behave like +\atentry{dualsymbol}: +\begin{codeenv} +\csopt[ + unit=dualsymbol, + measurement=dualsymbol +]{entry-type-aliases} +\end{codeenv} +This causes the \field{name} and \field{symbol} fields to be swapped in the +dual list. Remember that the fallback for the \field{sort} field is the label +for the symbol entry types so I need \csopt[\field{name}]{symbol-sort-fallback} +to fallback on \field{name} field instead. (Alternative, I could just sort by +the \field{name} field instead using \csopt[\field{name}]{sort-field}.) + +The primary entries can still be sorted according to the default +locale collator, but the dual entries need a sort method that's +better suited to symbols. Fortunately, \bibgls\ has some (very +limited) support for \isty{siunitx} and is able to interpret +the \ics{si} commands in the sample \ext{bib} files. Since +\idxpl{SIunit} are a mix of letters and numbers I've used one of the +letter-number methods listed in +\tableref{tab:sortoptionsletternumber}. + +I've decided to define a custom style for the first glossary. Since +it's based on the \glostyle{long3col-booktabs} style I need to +load \sty{glossary-longbooktabs}, which can conveniently be done with +the \styopt{stylemods} option. This uses \env{longtable} (provided +by \sty{longtable}, which is automatically loaded) which means +an extra \LaTeX\ call is required in the build process to ensure the +column widths are correct. Again I'm using \styopt{nostyles} to +suppress the automatic loading of the default styles, however +\sty{glossary-tree} will be loaded as it's listed in the value of +\styopt{stylemods} and \sty{glossary-long} will be loaded as it's +required by \sty{glossary-longbooktabs}. I can't use my custom style +in the \styopt{style} package option as it hasn't been defined at +that point. The default \glostyle{list} style is now unavailable +since \styopt{nostyles} has prevented it from being defined, so +I've used \styopt[alttree]{style} to ensure there's a valid default +style. + +Since my custom style is based on one of the long styles, I need to +set the length register \ics{glsdescwidth} to adjust the width of +the description column: +\begin{codeenv} +\cmd{setlength}\marg{\cs{glsdescwidth}}\marg{.4\cmd{hsize}} +\end{codeenv} +The \glostyle{long3col-booktabs} style sets up a three column +\env{longtable} so I just need to adjust the table header (to rename +the column headers) and the way each row is formatted: +\begin{codeenv} +\ics{newglossarystyle}\marg{units}\comment{style name} +\marg{\comment{base it on \glostyle{long3col-booktabs}} + \ics{setglossarystyle}\marg{long3col-booktabs}\comment{} + \cs{renewcommand}*\marg{\ics{glossaryheader}}\marg{\comment{} + \ics{toprule} + \ics{bfseries} Name \idx{colsep} + \cs{bfseries} Measurement \idx{colsep} + \cs{bfseries} Symbol + \ics{tabularnewline}\ics{midrule}\ics{endhead} + \ics{bottomrule}\ics{endfoot}}\comment{} +\comment{main entries:} + \cs{renewcommand}\marg{\ics{glossentry}}[2]\marg{\comment{} + \ics{glsentryitem}\marg{\idx{param}\idx{param}1}\ics{glstarget}\marg{\idx{param}\idx{param}1}\marg{\cs{glossentryname}\marg{\idx{param}\idx{param}1}} \idx{colsep} + \cs{glossentrydesc}\marg{\idx{param}\idx{param}1}\ics{glspostdescription} \idx{colsep} + \cs{glossentrysymbol}\marg{\idx{param}\idx{param}1}\cs{tabularnewline} + }\comment{} +} +\end{codeenv} +There are no sub-entries in this document so I haven't bothered to +redefine \ics{subglossentry}. (The tabular styles aren't appropriate +for hierarchical glossaries.) This puts the symbol into the third +column (rather than the location list, which is ignored). +This style supports the letter group separator (although it doesn't +title the groups), so if I want this I need to use the +\longarg{group} switch. + +I also need to make sure I've defined a glossary for the dual +entries: +\begin{codeenv} +\cs{newglossary*}\marg{units}\marg{Units of Measurement (by SI unit)} +\end{codeenv} +and specify the glossary types for the primary and dual entries: +\begin{codeenv} +\csopt[main]{type}, +\csopt[units]{dual-type} +\end{codeenv} +The complete document code is listed below. The document build is: +\begin{verbatim} +pdflatex sample-units3 +bib2gls --group sample-units3 +pdflatex sample-units3 +pdflatex sample-units3 +\end{verbatim} +The two pages of the document are shown in +\figureref{fig:sample-units3.pdf}. + +\lstinputlisting[firstline=5]{../examples/sample-units3.tex} + +\begin{figure} +\figcontents +{\pdftwocol{../examples/sample-units3.pdf}{2}} +{\caption{\filefmt{sample-units3.pdf}}} +{fig:sample-units3.pdf} +\end{figure} + +\filesection{sample-media.tex} + +This example uses the sample files \exfile{books.bib}, +\exfile{films.bib}, \exfile{no-interpret-preamble.bib} and +\exfile{interpret-preamble.bib}. The aim is to produce a combined +list of books and films in a single glossary. The films are based on +some of the books so some of the entries have the same name. The +default setting for identical sort values is +\csopt[id]{identical-sort-action}, which means that the ordering for +the duplicate names is based on the entry labels. This can lead to +the odd effect of sometimes having the film listed first +(\code{film.thebigsleep} comes before \code{thebigsleep}) and +sometimes having the book listed first (\code{brightonrock} comes +before \code{film.brightonrock}). + +One possible solution would be to also assign prefixes for the book +labels, but \csopt{label-prefix} is applied to all primary entries +for the given resource set and can't be applied selectively, so this +would require editing the \exfile{books.bib} file. + +A more consistent approach would be to fallback on the category. +This means that the \field{category} field needs to be set. There +are two simple ways to achieve this: use \csopt[same as base]{category} +(which sets the \field{category} to \code{books} for entries in +\exfile{books.bib} and to \code{films} for entries in +\exfile{films.bib}) or alias the custom \fieldfmt{identifier} field to +\field{category}. I've chosen the latter method and also provided +aliases for the custom \fieldfmt{year} and \fieldfmt{cast} fields: +\begin{codeenv} +\csopt[\fieldfmt{identifier}=\field{category},\fieldfmt{year}=\field{user1},\fieldfmt{cast}=\field{user2}]{field-aliases}, +\csopt[\field{category}]{identical-sort-action} +\end{codeenv} +This ensures that books always come before films with the same +title. An oddity is the film \qt{Whisky Galore!}\ which is one +character different from the book \qt{Whisky Galore} but the default +locale collator ignores punctuation so the two titles are considered +identical by the collator (but not by \csopt[non-unique]{sort-suffix}). +If a letter comparison was used instead, they would no longer be +considered identical, but in this case the film would +still be placed after the book since the film title is longer. + +Since I've set the \field{category} I can provide semantic +formatting commands (as for \exfile{sample-bacteria.tex}): +\begin{codeenv} +\cs{newcommand}*\marg{\cmd{bookfont}}[1]\marg{\cs{emph}\marg{\idx{param}1}} +\cs{newcommand}*\marg{\cmd{filmfont}}[1]\marg{\ics{textsf}\marg{\ics{em} \idx{param}1}} +\cs{glssetcategoryattribute}\marg{book}\marg{\catattr{textformat}}\marg{bookfont} +\cs{glssetcategoryattribute}\marg{book}\marg{\catattr{glossnamefont}}\marg{bookfont} +\cs{glssetcategoryattribute}\marg{film}\marg{\catattr{textformat}}\marg{filmfont} +\cs{glssetcategoryattribute}\marg{film}\marg{\catattr{glossnamefont}}\marg{filmfont} +\end{codeenv} +I've given films a slightly different format to make them easier to +distinguish from books of the same name. + +Both \exfile{books.bib} and \exfile{films.bib} had the custom +\fieldfmt{year} field, indicating the year of first publication +or release, which I've assigned to the \field{user1} field. +I can define \idxpl{postnamehook} for each category +to append the year in brackets after the name is displayed in the +glossary: +\begin{codeenv} +\cs{newcommand}*\marg{\postnamehook{book}}\marg{\comment{} + \cs{ifglshasfield}\marg{\field{user1}}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{\cs{space}(published \cs{glscurrentfieldvalue})}\comment{} + \marg{}\comment{} +} +\strut +\cs{newcommand}*\marg{\postnamehook{film}}\marg{\comment{} + \cs{ifglshasfield}\marg{\field{user1}}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{\cs{space}(released \cs{glscurrentfieldvalue})}\comment{} + \marg{}\comment{} +} +\end{codeenv} +As with the post-description hook, if you have at least +\styfmt{glossaries-extra} v1.31, it's better to use: +\begin{codeenv} +\ics{glsdefpostname}\margm{category} +\end{codeenv} +instead of: +\begin{codeenv} +\cs{newcommand}\marg{\cs{glsxtrpostnamecategory}} +\end{codeenv} +as it can guard against accidental misspelling of the \code{glsxtrpostname} +part of the command name. + +I've assigned the \fieldfmt{cast} field to the \field{user2} field, +and since this field uses \BibTeX's contributor markup I need to +convert this to a form that's easier to customize: +\begin{codeenv} +\csopt[\field{user2}]{bibtex-contributor-fields} +\end{codeenv} +I'm not sorting by this field and it would look better in the +document to list the forenames before the surname so I've also done: +\begin{codeenv} +\csopt[forenames]{contributor-order} +\end{codeenv} +Since I have at least version 2.28 of \sty{datatool-base} installed, +the list will be formatted using \ics{DTLformatlist}. If I want an +Oxford comma, I need to redefine \ics{DTLlistformatoxford} in the document: +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{DTLlistformatoxford}}\marg{,} +\end{codeenv} +If I want to change \qt{\&} to \qt{and} I also need to redefine +\ics{DTLandname}: +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{DTLandname}}\marg{and} +\end{codeenv} +If \ics{DTLformatlist} isn't defined (\sty{datatool-base} v2.27 or +earlier), the cast list will look a little odd as it uses a comma +separator between all elements of this list, including the final +pair (so there's no final \& or \qt{and}). + +I've provided a \idx{postdescriptionhook} +\ics{glsxtrpostdesccategory} to append the cast list: +\begin{codeenv} +\cs{newcommand}*\marg{\postdeschook{film}}\marg{\comment{} + \cs{ifglshasfield}\marg{\field{user2}}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{\comment{} + \cs{glsxtrrestorepostpunc} \comment{requires glossaries-extra v1.23+} + \cs{cs.space}featuring \cs{glscurrentfieldvalue} + }\comment{} + \marg{}\comment{} +} +\end{codeenv} +This uses \ics{glsxtrrestorepostpunc} to restore the +post-description punctuation if it was suppressed with +\ics{glsxtrnopostpunc}. This means that if I decide not to include +the \field{user2} field then the post-description punctuation will +be revert back to being suppressed for entries containing +\cs{glsxtrnopostpunc} in the \field{description} field. + +I haven't referenced any of the entries in the main body of the +document, so I've used \csopt[all]{selection} to select all entries. +This means that there are no number lists on the first document +build (\LaTeX+\bibgls+\LaTeX) but the next build would show locations for +the books that have been referenced by the film entries. Since this +looks a bit odd, I've added \csopt[false]{save-locations} to +prevent \bibgls\ from saving the locations. + +I've used a style that shows letter group headings so I need to use +the \longarg{group} switch. +The complete document code is listed below. The document build is: +\begin{verbatim} +pdflatex sample-media +bib2gls --group sample-media +pdflatex sample-media +\end{verbatim} +The four pages of the document are shown in +\figureref{fig:sample-media.pdf}. + +\lstinputlisting[firstline=5]{../examples/sample-media.tex} + +\begin{figure} +\figcontents +{\pdftwocol{../examples/sample-media.pdf}{4}} +{\caption{\filefmt{sample-media.pdf}}} +{fig:sample-media.pdf} +\end{figure} + +\filesection{sample-people.tex} + +This example uses the files \exfile{people.bib}, + \exfile{no-interpret-preamble.bib} and \exfile{interpret-preamble.bib}. The +aim here is to have a list of people ordered alphabetically by +surname with a brief description, the same list ordered by date of +birth and an index of all the people without their details but with +a number list indicating where that person was mentioned in the +document. The first two lists shouldn't include aliases but the +index should. Not all the entries defined in \exfile{people.bib} +are included in the document. Those that aren't either explicitly +referenced or aliased are filtered by the \csopt{selection} criteria. +I've used a style that shows letter group headings so I need to use +the \longarg{group} switch. + +Since this is just an example document all the \cs{gls} commands +only occur on page~1, which means that each number list is just +\qt{1}. A real document would have the references scattered about. +The aliases haven't actually been referenced anywhere in the +document. + +The \fieldfmt{born}, \fieldfmt{died} and \fieldfmt{othername} fields will be +ignored by default since they don't correspond to recognised keys, +so the keys either need to be defined or the fields need to be +mapped to existing keys. In this case I've decided to map them to +the \field{user1}, \field{user2} and \field{user3} fields using +\csopt{field-aliases}: +\begin{codeenv} +\csopt[\fieldfmt{born}=\field{user1},\fieldfmt{died}=\field{user2},\fieldfmt{othername}=\field{user3}]{field-aliases} +\end{codeenv} +Although the aliases haven't been referenced in the document, I've +taken into account the possibility that they might later be added. +To prevent them from showing in the first two lists I've filtered +them out. This is easy to do since the aliases are all defined using +\atentry{index} whereas the remaining (non-aliased) entries are +defined using \atentry{entry} so \csopt{match} can be used to only +select entries defined with \atentry{entry}: +\begin{codeenv} +\csopt[entrytype=entry]{match} +\end{codeenv} + +I'd like the first use of \ics{gls} to display the full name, except +for the entry that has the \field{first} field set. The remaining +entries only have \field{text} set to a shortened version of the +name so they need to have the \field{name} field copied to the +\field{first} field using \csopt{replicate-fields}: +\begin{codeenv} +\csopt[\field{name}=\marg{\field{first}}]{replicate-fields} +\end{codeenv} + +I'd like the first use to show the other name in parentheses where +provided. The simplest way to achieve this is by defining the +\idx{postlinkhook} \ics{glsxtrpostlinkcategory}. If the +\field{category} field isn't specified it will default to +\code{general} (for entries defined with \atentry{entry}), so I +could just define \csfmt{glsxtrpostlinkgeneral} but to allow for +the possibility of extending the document to incorporate other types +of entries I decided to set the \field{category} to \code{people} +through the use of the \csopt{category} option: +\begin{codeenv} +\csopt[people]{category} +\end{codeenv} + +This means that I now need to define a command called +\csfmt{glsxtrpostlinkpeople} that will be used after instances of +\cs{gls} etc where the entry has the \field{category} set to +\code{people}. This first tests if that was the first use of the +entry with \ics{glsxtrifwasfirstuse} and then tests if the +\field{user3} field is set. If so, it does a space followed by that +field's value in parentheses. The entry's label can be obtained from +\ics{glslabel}: +\begin{codeenv} +\cs{newcommand}*\marg{\postlinkhook{people}}\marg{\comment{} + \cs{glsxtrifwasfirstuse} + \marg{\comment{} + \cs{ifglshasfield}\marg{\field{user3}}\marg{\cs{glslabel}}\comment{} + \marg{\cs{space}(\cs{glscurrentfieldvalue})}\comment{} + \marg{}\comment{} + }\comment{} + \marg{}\comment{} +} +\end{codeenv} + +I'd also like to do something similar after the name when the entry +is displayed in the glossary. This means defining the \idx{postnamehook} +\ics{glsxtrpostnamecategory}, in this case +\csfmt{glsxtrpostnamepeople}. The entry's label is referenced +with \ics{glscurrententrylabel}: +\begin{codeenv} +\cs{newcommand}*\marg{\postnamehook{people}}\marg{\comment{} + \cs{ifglshasfield}\marg{\field{user3}}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{\cs{space}(\cs{glscurrentfieldvalue})}\comment{} + \marg{}\comment{} +} +\end{codeenv} +(A different command is used since \cs{gls} may occur in the +description, which would interfere with the current entry label if +they shared the same command to reference the label.) + +The \idx{postdescriptionhook} can be used to append the birth and +death dates. Although all the entries that have been selected from \exfile{people.bib} have a +\fieldfmt{died} field, I've added a check for the corresponding +\field{user3} field in case new references are added for people who are +still alive: +\begin{codeenv} +\cs{newcommand}*\marg{\postdeschook{people}}\marg{\comment{} + \cs{ifglshasfield}\marg{\field{user1}}\marg{\cs{glscurrententrylabel}} + \marg{\comment{born} + \cs{space}(\cs{glscurrentfieldvalue}\ics{comma}-{}-\cs{comma}\comment{} + \cs{ifglshasfield}\marg{user2}\marg{\cs{glscurrententrylabel}} + \marg{\comment{died} + \cs{glscurrentfieldvalue} + }\comment{} + \marg{}\comment{} + )\comment{} + }\comment{} + \marg{}\comment{} +} +\end{codeenv} + +The first list is quite straight-forward and can be created with: +\begin{codeenv} +\gls!{GlsXtrLoadResources}\oarg{ + \csopt[people]{src}, + \csopt[entrytype=entry]{match}, + \csopt[people]{category}, + \csopt[\field{name}=\marg{\field{first}}]{replicate-fields}, + \csopt[\fieldfmt{born}=\field{user1},\fieldfmt{died}=\field{user2},\fieldfmt{othername}=\field{user3}]{field-aliases} +} +\end{codeenv} +I have used the \csopt{sort} option and there's no document language, +so \bibgls\ will sort according to my locale. The custom +commands \gls{sortname} and \gls{sortvonname} ensure that the +entries are all sorted alphabetically according to the surnames. + +The second list can easily be created by adding the \csopt{secondary} +option: +\begin{codeenv} +\csopt[date:\field{user1}:bybirth]{secondary} +\end{codeenv} +This sorts according to the \field{user1} field (which was +originally the \fieldfmt{birth} field). +Note that different locales have different default date formats. +There may also be a difference in the default date format depending +on the Java \idx{localeprovider}. For example, if you switch from +using the \idx{JRE} to using the \idx{CLDR} you may find a change in +the default format. In case the format provided in the \ext{bib} +file isn't recognised, the required format can be set with: +\begin{codeenv} + \csopt[d MMM YYYY G]{secondary-date-sort-format} +\end{codeenv} + +I've changed the date group headings by redefining \gls{bibglsdategroup} and +\gls{bibglsdategrouptitle}, which means that the grouping in the +\code{bybirth} glossary will be in the form \meta{year} \meta{era}: +\begin{codeenv} +\cs{newcommand}\marg{\gls{bibglsdategroup}}[7]\marg{\idx{param}1\idx{param}4\idx{param}7} +\cs{newcommand}\marg{\gls{bibglsdategrouptitle}}[7]\marg{\cs{number}\idx{param}1\ \idx{param}4} +\end{codeenv} +I've also defined the \code{bybirth} glossary and supplied a title: +\begin{codeenv} +\cs{newglossary*}\marg{bybirth}\marg{People (Ordered by Birth)} +\end{codeenv} + +The first two glossaries have entries with fairly long names (especially those +with the \idx{postnamehook}), so the best style is the +\glostyle{altlistgroup}. The \sty{glossaries-extra-stylemods} +package patches this style to discourage page breaks occurring after +group headings, so I've also used the \styopt{stylemods} +option to automatically load that package. I'd like to use the +\glostyle{bookindex} style for the index, which is provided by +\sty{glossary-bookindex}, so I need: +\begin{codeenv} +\styopt[list,bookindex]{stylemods} +\end{codeenv} +This ensures that \sty{glossary-list} and \sty{glossary-bookindex} +are loaded and patches the list styles. + +The first two glossaries would look better with a terminating +\idx{full-stop}, so I've used the \styopt{postdot} package option. +(The \glostyle{bookindex} style doesn't use the \field{description} +field and therefore doesn't use the \idx{postdescriptionhook}.) +The index glossary type can be defined with the \styopt{index} +package option. I've set the default style to \glostyle{altlistgroup} +but this can locally be changed to \glostyle{bookindex} when I +display the index. The \styopt{record} option is needed to use +\bibgls, so the \styfmt{glossaries-extra} package is loaded with: +\begin{codeenv} +\cmd{usepackage}[\styopt{record},\comment{using bib2gls} + \styopt{index},\comment{create index glossary} + \styopt{postdot},\comment{dot after descriptions} +\comment{load glossary-list.sty and glossary-bookindex.sty and patch:} + \styopt[list,bookindex]{stylemods}, + \styopt[altlistgroup]{style}]\marg{glossaries-extra} +\end{codeenv} + +The index needs to include all the entries that have already been +defined but also needs to include the aliased entries. This means +that existing entries simply need their label copied to the +\code{index} glossary but the other entries need to be defined +so this requires setting the \csopt{action} option: +\begin{codeenv} +\csopt[define or copy]{action} +\end{codeenv} +I would also like to have groups in the index (which the +\glostyle{bookindex} style supports) so I need to specify a field +in which to save the group information using +\csopt{copy-action-group-field}: +\begin{codeenv} +\csopt[indexgroup]{copy-action-group-field} +\end{codeenv} +I need to remember to redefine \ics{glsxtrgroupfield} to this value before +displaying the index: +\begin{codeenv} +\cs{renewcommand}\marg{\cs{glsxtrgroupfield}}\marg{indexgroup} +\end{codeenv} + +The aliased entries won't be selected by default since they haven't +been used in the document, so I need to change the selection +criteria with \csopt{selection}: +\begin{codeenv} +\csopt[recorded and deps and see]{selection} +\end{codeenv} + +In the index, I'd like the surnames first. This can be done by +redefining the custom commands used in the \field{name} fields. +There's a slight complication here. These commands aren't defined on +the first \LaTeX\ run as their definitions are written to the +\ext{glstex} file by \bibgls, so I can't use \cs{renewcommand} (although +I could use \cs{glsrenewcommand}). +Instead I've provided some custom commands: +\begin{codeenv} +\cs{newcommand}*\marg{\cmd{swaptwo}}[2]\marg{\idx{param}2, \idx{param}1} +\cs{newcommand}*\marg{\cmd{swapthree}}[3]\marg{\idx{param}2 \idx{param}3, \idx{param}1} +\end{codeenv} +Now I just need to make an assignment using \ics{let}: +\begin{codeenv} +\cs{let}\gls{sortname}\cmd{swaptwo} +\cs{let}\gls{sortart}\cmd{swaptwo} +\cs{let}\gls{sortvonname}\cmd{swapthree} +\end{codeenv} +This doesn't perform any check to determine if the commands are +already defined so there won't be a problem on the first run. + +The first two glossaries shouldn't have number lists: +\begin{codeenv*} +\cs{printunsrtglossary}\oarg{\printglossopt[People (Alphabetical)]{title},\printglossopt{nonumberlist}} +\cs{printunsrtglossary}\oarg{\printglossopt[bybirth]{type},\printglossopt[false]{target},\printglossopt{nonumberlist}} +\end{codeenv*} +I'd like to use \sty{hyperref} but I have to switch off the +hypertargets for the second glossary otherwise I'll end up with +duplicate targets. This is done with \code{\printglossopt[false]{target}}. +All references using \cs{gls} etc will link to the first glossary. + +I could also do this for the index but the cross-references in the +aliased entries will link to the first glossary rather than the +relevant entry in the index. The simplest way to fix this is to +redefine \ics{glolinkprefix} to provide a different target: +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{glolinkprefix}}\marg{idx:} +\end{codeenv} +These redefinitions need to be done before the index. I've decided +to use the starred \ics{printunsrtglossary*} to localise these +changes, although that's not needed for this document since the +index comes right at the end: +\begin{codeenv*} +\cs{printunsrtglossary*} + \oarg{\printglossopt[index]{type},\printglossopt[\glostyle{bookindex}]{style}} + \marg{\comment{} + \cs{let}\gls!{sortname}\cmd{swaptwo} + \cs{let}\gls!{sortart}\cmd{swaptwo} + \cs{let}\gls!{sortvonname}\cmd{swapthree} + \cs{renewcommand}\marg{\cs{glsxtrgroupfield}}\marg{indexgroup}\comment{} + \cs{renewcommand}*\marg{\cs{glolinkprefix}}\marg{idx:}\comment{} + } +\end{codeenv*} +The complete document code is listed below. The document build is: +\begin{verbatim} +pdflatex sample-people +bib2gls --group --break-space sample-people +pdflatex sample-people +\end{verbatim} +The four pages of the document are shown in \figureref{fig:sample-people.pdf}. + +\lstinputlisting[firstline=5]{../examples/sample-people.tex} + +\begin{figure} +\figcontents +{\pdftwocol{../examples/sample-people.pdf}{4}} +{\caption{\filefmt{sample-people.pdf}}} +{fig:sample-people.pdf} +\end{figure} + +\filesection{sample-authors.tex} + +This example uses the files \exfile{people.bib}, +\exfile{books.bib}, \exfile{no-interpret-preamble.bib} and +\exfile{interpret-preamble2.bib}. The aim is to reference the books +in \exfile{books.bib} and have them listed by author. This means +finding a way of assigning each book entry a \field{parent} field that +contains the label identifying the relevant author in \exfile{people.bib}. +I've used a style that shows letter group headings so I need to use +the \longarg{group} switch. + +To recap, each author is defined in \exfile{people.bib} in the form: +\begin{codeenv} +\atentry{entry}\marg{dickens, + \field{name}=\marg{\gls{sortname}\marg{Charles}\marg{Dickens}}, + \field{text}=\marg{Dickens}, + \field{description}=\marg{English writer and social critic}, + \fieldfmt{born}=\marg{7\idx{nbspchar}February 1812 AD}, + \fieldfmt{died}=\marg{9\idx{nbspchar}June 1870 AD}, + \fieldfmt{identifier}=\marg{person} +} +\end{codeenv} +and each book is defined in \exfile{books.bib} in the form: +\begin{codeenv} +\atentry{entry}\marg{bleakhouse, + \field{name}=\marg{Bleak House}, + \field{description}=\marg{novel by Charles Dickens}, + \fieldfmt{identifier}=\marg{book}, + \fieldfmt{author}=\marg{\gls{sortmediacreator}\marg{Charles}\marg{Dickens}}, + \fieldfmt{year}=\marg{1852} +} +\end{codeenv} +There's a field here (the custom \fieldfmt{author} field) that contains +the author's name, and this can be aliased to the \field{parent} +field with \csopt{field-aliases}: +\begin{codeenv} +\csopt[\fieldfmt{author}=\field{parent}]{field-aliases} +\end{codeenv} +but the author's label in the \exfile{people.bib} +file is just the \idx!{lowercase} surname. + +Remember from \sectionref{sec:texparserlib} that the interpreter +will be used on the \field{parent} field if the value contains +\idx{escchar} or \idx{bgroupchar} or \idx{egroupchar} and +\csopt[true]{interpret-label-fields}. This means that with this +field alias and the interpreter on, \bibgls\ will attempt to +interpret the field contents. So all that's needed is to ensure that +\bibgls\ is given a definition of \gls{sortmediacreator} that +ignores the first argument and converts the second argument to lower +case. This definition is available in +\exfile{interpret-preamble2.bib} but, since this file uses +\cs{renewcommand} rather than \cs{providecommand}, +\csopt[false]{write-preamble} is required to prevent \LaTeX\ from +picking up this definition. + +As with the \exfile{sample-people.tex} example, I need to copy +the \field{name} field to the \field{first} field if that field is +missing using \csopt{replicate-fields}: +\begin{codeenv} +\csopt[\field{name}=\marg{\field{first}}]{replicate-fields} +\end{codeenv} +and I also want to provide a semantic command to format the book +title, so the field aliases also need to convert the custom +\fieldfmt{identifier} field to \field{category}: +\begin{codeenv} +\csopt[\fieldfmt{identifier}=\field{category},\fieldfmt{author}=\field{parent}]{field-aliases} +\end{codeenv} +so that the document can set the \catattr{textformat} and +\catattr{glossnamefont} attributes: +\begin{codeenv} +\cs{newcommand}*\marg{\cmd{bookfont}}[1]\marg{\cs{emph}\marg{\idx{param}1}} +\cs{glssetcategoryattribute}\marg{book}\marg{\catattr{textformat}}\marg{bookfont} +\cs{glssetcategoryattribute}\marg{book}\marg{\catattr{glossnamefont}}\marg{bookfont} +\end{codeenv} +As with \exfile{sample-media.tex}, the terminating question mark at +the end of some of the \field{name} fields can cause an awkward +situation if \cs{gls} is used at the end of a sentence. This can be +dealt with by getting \bibgls\ to make a note of the fields that +end with sentence-terminating punctuation through the use of +the \csopt{check-end-punctuation} option. In this example, the +\field{name}, \field{text} and \field{first} fields are the same for +all the books, so it's sufficient just to check the \field{name} +field: +\begin{codeenv} +\csopt[\field{name}]{check-end-punctuation} +\end{codeenv} +With \sty{glossaries-extra} v1.23+ it's easy to hook into the +\idx{postlinkhook} to check if +\fielddisp{fieldendpunc}{nameendpunc} exists: +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{glsxtrifcustomdiscardperiod}}[2]\marg{\comment{} + \cs{GlsXtrIfFieldUndef}\marg{\fielddisp{fieldendpunc}{nameendpunc}}\marg{\cs{glslabel}}\marg{\idx{param}2}\marg{\idx{param}1}\comment{} +} +\end{codeenv} +This will now cause the full stops following: +\begin{codeenv} +\cs{gls}\marg{whydidnttheyaskevans}. +\end{codeenv} +and +\begin{codeenv} +\cs{gls}\marg{doandroidsdreamofelectricsheep}. +\end{codeenv} +to be discarded. + +The complete document code is listed below. The document build is: +\begin{verbatim} +pdflatex sample-authors +bib2gls --group sample-authors +pdflatex sample-authors +\end{verbatim} +The resulting document is shown in \figureref{fig:sample-authors.pdf}. + +\lstinputlisting[firstline=5]{../examples/sample-authors.tex} + +\begin{figure} +\figcontents +{% + \frame{\includegraphics[height=.9\textheight]{../examples/sample-authors.pdf}}% +} +{\caption{\filefmt{sample-authors.pdf}}} +{fig:sample-authors.pdf} +\end{figure} + +\filesection{sample-citations.tex} + +This example uses the \BibTeX\ file \exfile{citations.bib} to create +a document that has both a bibliography created by \BibTeX\ and +glossaries created by \bibgls\ listing the authors and the titles. +There are no glossary reference commands, such as \cs{gls}, but +\bibgls\ can be run with \longarg{cite-as-record} to treat the +\ics{citation} commands (written to the \ext{aux} file by \ics{cite}) +as ignored records. Since \cs{cite} doesn't record the page number, +there are no associated locations. + +The \code{main} glossary isn't required, so I've used +\styopt{nomain} to suppress its creation. I want to use both the +\glostyle{altlist} and \glostyle{indexgroup} styles but none of the +other styles, so I've used \styopt{nostyles} to prevent the +automatic loading of the default style packages and +\styopt{stylemods} to load the \sty{glossary-tree} and +\sty{glossary-list} packages and patch the styles. A \idx{full-stop} +is automatically placed after the descriptions with +\styopt{postdot}. +\begin{codeenv} +\cs{usepackage}\oarg{\styopt{record},\comment{using bib2gls} +\styopt{nomain},\comment{don't define main glossary} +\styopt{postdot},\comment{full stop after descriptions} +\styopt{nostyles},\comment{don't load default styles} +\comment{load glossary-tree and glossary-list and patch styles:} +\styopt[tree,list]{stylemods} +}\marg{glossaries-extra} +\end{codeenv} +Next I need to create the glossaries for the list of authors and +list of titles: +\begin{codeenv} +\cs{newglossary*}\marg{contributors}\marg{Authors} +\cs{newglossary*}\marg{titles}\marg{Titles} +\end{codeenv} +The simplest way of assigning the authors to the \code{contributors} +glossary and the titles to the \code{titles} glossary is to use: +\begin{codeenv} +\csopt[contributors]{type} +\end{codeenv} +in the \idx{resourceset} and provide a +modified version of \gls{bibglsnewbibtexentry} that assigns +\field{type} after the options: +\begin{codeenv} +\cs{newcommand}\marg{\gls{bibglsnewbibtexentry}}[4]\marg{\comment{} + \gls{longnewglossaryentry}*\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2,\field{type}=\marg{titles}}\marg{\idx{param}4}\comment{} +} +\end{codeenv} +The standard \BibTeX\ entry types need aliasing to +\atentry{bibtexentry}: +\begin{codeenv} +\csopt[\ics{GlsXtrBibTeXEntryAliases}]{entry-type-aliases} +\end{codeenv} +and the \fieldfmt{title} field is aliased to \field{name}: +\begin{codeenv} +\csopt[\fieldfmt{title}=\field{name}]{field-aliases} +\end{codeenv} +(The other fields aren't required for the glossary lists.) +The \field{category} is set to the original entry type: +\begin{codeenv} +\csopt[same as original entry]{category} +\end{codeenv} +So, for example, an entry that's provided in the \ext{bib} file with +\atentryfmt{article} has the \field{category} field set to +\code{article}. (Compare this with \csopt[same as entry]{category} +which would set the \field{category} to \code{bibtexentry}.) +The spawned entries are all defined using \atentry{contributor} and +aren't aliased so both the entry type and the original entry type +are \code{contributor}. + +In order to list the titles according to category, I've use this as +the sort field: +\begin{codeenv} +\csopt[\field{category}]{sort-field} +\end{codeenv} +and setting the sort suffix to the \field{name} field sub-sorts +the \atentry{bibtexentry} types according to the title +(which was aliased to the \field{name}) and the +\atentry{contributor} types according to the author: +\begin{codeenv} +\csopt[\field{name}]{sort-suffix} +\end{codeenv} + +Next the groups identified by the labels \code{article} and \code{book} +are assigned titles. +\begin{codeenv} +\gls{glsxtrsetgrouptitle}\marg{article}\marg{Articles} +\gls{glsxtrsetgrouptitle}\marg{book}\marg{Books} +\end{codeenv} +The \field{group} field is actually set to the associated letter by the default +\csopt{sort} method. The desired labels are stored in the \field{category} +field. Since the entries are sorted by category, then they are naturally +in those sub-blocks, which means that the group titles can be set by locally +redefining \ics{glsxtrgroupfield} to \code{category}: +\begin{codeenv} +\cs{printunsrtglossary*}[\printglossopt[titles]{type},\printglossopt[indexgroup]{style}] +\marg{\comment{} + \cs{renewcommand}\marg{\cs{glsxtrgroupfield}}\marg{\field{category}}\comment{} + \cs{renewcommand}\marg{\cs{glstreenamefmt}}[1]\marg{\cs{emph}\marg{\idx{param}1}}\comment{} + \cs{renewcommand}\marg{\cs{glstreegroupheaderfmt}}[1]\marg{\ics{textbf}\marg{\idx{param}1}}\comment{} +} +\end{codeenv} +This again contradicts the advice given in +\sectionref{sec:logicaldivisions} as I'm sorting by the +\field{group} label. (Technically it's sorting by the +\field{category} label but this is being used as the group.) In this +case it's not a problem as the labels closely match the titles and +the sorting options ensure that the groups aren't broken up. + +There's no \field{description} field set for these entries, but the +\idx{postdescriptionhook} can still be used to append information. +In this case, I've appended a cross-reference to the bibliography. +Since the bibliography entry and the glossary term both have the +same label, the citation can easily be obtained with +\code{\ics{cite}\marg{\cs{glscurrententrylabel}}}: +\begin{codeenv} +\cs{newcommand}\marg{\postdeschook{article}}\marg{\cs{cite}\marg{\cs{glscurrententrylabel}}} +\cs{newcommand}\marg{\postdeschook{book}}\marg{\cs{cite}\marg{\cs{glscurrententrylabel}}} +\end{codeenv} +Note that this needs to be done for each \BibTeX\ entry type, but in +this case the \ext{bib} file only contains \atentryfmt{article} and +\atentryfmt{book} entries. (Similarly for the group titles above.) + +The list of contributors can simply be displayed with: +\begin{codeenv} +\cs{printunsrtglossary}[\printglossopt[contributors]{type},\printglossopt[altlist]{style}] +\end{codeenv} +This will only list the names as there's no description, but again +the \idx{postdescriptionhook} can be used, in this case for the \code{contributor} +category. The hook iterates +over the internal list provided by the \field{bibtexentry} field. +This allows the titles to be listed as well: +\begin{codeenv} +\cs{newcommand}\marg{\postdeschook{contributor}}\marg{\comment{} + \ics{glsxtrifhasfield}\marg{\field{bibtexentry}}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{\comment{} + \cs{glsxtrfieldforlistloop} + \marg{\cs{glscurrententrylabel}}\marg{\field{bibtexentry}}\comment{} + \marg{\csfmt{contributorhandler}}\comment{} + }\comment{} + \marg{\ics{par} No titles.}\comment{} +} +\end{codeenv} +The \idx{handler} macro displays the name of the associated +\atentry{bibtexentry} term and the citation: +\begin{codeenv} +\cs{newcommand}\marg{\csfmt{contributorhandler}}[1]\marg{\cs{par}\ics{glsentryname}\marg{\idx{param}1} \cs{cite}\marg{\idx{param}1}} +\end{codeenv} + +The complete document code is listed below. The document build is: +\begin{verbatim} +pdflatex sample-citations +bib2gls --cite-as-record sample-citations +bibtex sample-citations +pdflatex sample-citations +pdflatex sample-citations +\end{verbatim} +The resulting document is shown in \figureref{fig:sample-citations.pdf}. + +\lstinputlisting[firstline=7]{../examples/sample-citations.tex} + +\begin{figure} +\figcontents +{\pdftwocol{../examples/sample-citations.pdf}{2}} +{\caption{\filefmt{sample-citations.pdf}}} +{fig:sample-citations.pdf} +\end{figure} + +\filesection{sample-msymbols.tex} + +This example uses \exfile{bigmathsymbols.bib}, +\exfile{mathsrelations.bib}, \exfile{binaryoperators.bib}, +\exfile{unaryoperators.bib} and \exfile{mathgreek.bib}. The \isty{stix} +package is required for some of the commands used in +\exfile{bigmathsymbols.bib}, so that must be loaded in the document. + +I'm using the \glostyle{mcolalttree} style for this document, +which means that the \sty{glossary-mcols} package is required and +the styles need patching, which can be done with +the \styopt{stylemods} package option: +\begin{codeenv} +\cs{usepackage}\oarg{\styopt{record},\comment{using bib2gls} + \styopt{nostyles},\comment{don't load default styles} + \styopt{postdot},\comment{append a dot after descriptions} + \styopt[mcols]{stylemods},\comment{load glossary-mcols.sty and patch} + \styopt[mcolalttree]{style}}\marg{glossaries-extra} +\end{codeenv} + +I'm not referencing any of the entries in the document as I'm just +generating a complete list of all the defined symbols. This means I +need to tell \bibgls\ to select all entries and don't bother saving +the \field{location} field: +\begin{codeenv} +\csopt[false]{save-locations}, +\csopt[all]{selection} +\end{codeenv} +Since I'm using a style that's based on \glostyle{alttree} I need to +find the widest \field{name}, which can be done with \csopt{set-widest}. + +The simplest way of dividing the glossary into logical blocks is to +sort according to the category, but first I need to use \csopt{field-aliases} +to convert the custom \fieldfmt{identifier} field to \field{category}: +\begin{codeenv} +\csopt[\fieldfmt{identifier}=\field{category}]{field-aliases} +\end{codeenv} +and sort by the \field{category} field: +\begin{codeenv} +\csopt[\field{category}]{sort-field} +\end{codeenv} +Since this will cause identical sort values, I need to provide a +a way of ordering these identical values. Here I've decided +to fallback on the \field{description} field: +\begin{codeenv} +\csopt[\field{description}]{identical-sort-action} +\end{codeenv} +This means that entries will be ordered by \field{category} and +then \field{description}, which naturally creates blocks of symbol +types in the glossary. This only uses a simple case-sensitive string +comparison which is fine for English, but for another language it +would be better to use \csopt{sort-suffix} as in the +\exfile{sample-textsymbols.tex} file. + +Remember that I want a small vertical gap between each logical +block. These need the \field{group} field which, with the default +locale sort, is obtained from the first letter of the sort value. +In this case the sort value is obtained from the \field{category} +field, and as each category happens to start with a different +letter, this means I get the desired effect. However, in the event +that I add more entries with a new category that happens to start +with the same letter as an existing category, it's better to provide +a more future-proof method, so I've set the \field{group} field to +fetch its value from the \field{category} field: +\begin{codeenv} +\csopt[\field{category}=\field{group}]{replicate-fields} +\end{codeenv} +(Since the \csopt{field-aliases} option is always performed before +\csopt{replicate-fields}, the \field{category} field will already +have been set and is available for replicating.) + +This means that I'm essentially sorting by the \field{group} labels, +which this manual has warned against doing. In this case, it's an +acceptable break from that rule as I've used options that ensure the +groups aren't broken up during sorting and I'm not concerned with the group +titles. A method such as that used in \exfile{sample-textsymbols2.tex} +would end up with titled blocks, which I don't want here. By using +resource options such as \csopt{field-aliases} and +\csopt{replicate-fields} I can avoid the warning that's triggered +with the default \longarg{warn-non-bib-fields}. + +The complete document code is listed below. The document build is: +\begin{verbatim} +pdflatex sample-msymbols +bib2gls sample-msymbols +pdflatex sample-msymbols +\end{verbatim} +The resulting document is shown in \figureref{fig:sample-msymbols.pdf}. + +\lstinputlisting[firstline=5]{../examples/sample-msymbols.tex} + +\begin{figure} +\figcontents +{% + \frame{\includegraphics[height=.9\textheight]{../examples/sample-msymbols.pdf}}% +} +{\caption{\filefmt{sample-msymbols.pdf}}} +{fig:sample-msymbols.pdf} +\end{figure} + +\filesection{sample-maths.tex} + +This example uses \exfile{bigmathsymbols.bib} and \exfile{mathsobjects.bib}. +It has a fairly similar preamble to \exfile{sample-msymbols.tex}, +but \exfile{no-interpret-preamble.bib} and +\exfile{interpret-preamble.bib} are now needed to provide +the \gls!{sortart} command: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[no-interpret-preamble]{src}, + \csopt[false]{interpret-preamble} +} +\end{codeenv} +There's also an extra custom field to alias: +\begin{codeenv} +\csopt[\fieldfmt{identifier}=\field{category},\fieldfmt{format}=\field{user1}]{field-aliases} +\end{codeenv} +I've aliased \fieldfmt{format} to \field{user1} since \gls!{glsxtrfmt} +defaults to that field. If I decided to use a different field I also +need to remember to redefine \ics{GlsXtrFmtField} to match. + +As with \exfile{sample-msymbols.tex} I'm sorting by the +\field{category} label and this value is copied to the \field{group} +field, but again I don't have a hierarchical glossary as the logical +blocks don't have titles. + +In this document I only want to select entries that have been +indexed, so I've omitted the \csopt{selection} option I used in the +\exfile{sample-msymbols.tex} example, however +I still don't want any number lists so I still have +\csopt[false]{save-locations}. + +I want \gls!{glsxtrfmt} to index the term (which it doesn't by default) so +that means I need to redefine \ics{GlsXtrFmtDefaultOptions} +to prevent it from using \code{noindex}: +\begin{codeenv} +\cs{renewcommand}\marg{\cs{GlsXtrFmtDefaultOptions}}\marg{} +\end{codeenv} +I've provided some convenient wrapper commands that use +\gls!{glsxtrfmt*} or the non-linking \gls!{glsxtrentryfmt} that +are in the form: +\begin{codeenv} +\cs{newcommand}\marg{\cmd{set}}[2][]\marg{\gls{glsxtrfmt*}\oarg{\idx{param}1}\marg{set}\marg{\idx{param}2}} +\cs{newcommand}\marg{\cmd{nlset}}[1]\marg{\gls{glsxtrentryfmt}\marg{set}\marg{\idx{param}1}} +\end{codeenv} +The use of the starred form allows: +\begin{codeenv} +\cmd{[}\cmd{set}\marg{A} = \cs{gls}\marg{bigcup}[\idx{sbchar}\marg{i=1}\idx{spchar}n] \cmd{set}\marg{B}[\idx{sbchar}i] \cmd{]} +\end{codeenv} +which produces: +\[ \mathcal{A} = \bigcup_{i=1}^n \mathcal{B}_i \] +Note the difference if the optional arguments aren't used: +\begin{codeenv} +\cmd{[}\cmd{set}\marg{A} = \cs{gls}\marg{bigcup}\idx{sbchar}\marg{i=1}\idx{spchar}n \cmd{set}\marg{B}\idx{sbchar}i \cmd{]} +\end{codeenv} +This produces: +\[ \mathcal{A} = \bigcup{}_{i=1}^n \mathcal{B}{}_i \] + +Be careful with the set cardinality example. You might be tempted to +nest \csfmt{set} within the argument of \csfmt{setcard} but this +results in nested hyperlinks. These are unpredictable and there's no +consistent handling of them between different PDF viewers. It can +also be confusing to the reader. If +$\lvert\mathcal{B}_1\cup\mathcal{B}_2\rvert$ +shows up as what appears to be a single hyperlink, where would the +reader expect the target? This is the reason for providing the +non-linking commands like \csfmt{nlset} and \csfmt{nlsetcard}. + +The complete document code is listed below. The document build is: +\begin{verbatim} +pdflatex sample-maths +bib2gls sample-maths +pdflatex sample-maths +\end{verbatim} +The resulting document is shown in \figureref{fig:sample-maths.pdf}. + +\lstinputlisting[firstline=5]{../examples/sample-maths.tex} + +\begin{figure} +\figcontents +{% + \frame{\includegraphics[height=.9\textheight]{../examples/sample-maths.pdf}}% +} +{\caption{\filefmt{sample-maths.pdf}}} +{fig:sample-maths.pdf} +\end{figure} + +\filesection{sample-textsymbols.tex} + +This example uses \exfile{miscsymbols.bib}. +This requires both \isty{marvosym} and (with the \styoptfmt{weather} option) +\isty{ifsym}. Unfortunately both define the commands \csfmt{Sun} +and \csfmt{Lightning}, so these commands need to be undefined after +the first package is loaded and before the second. +Since I want the definitions provide by \sty{ifsym} I have to first +load \sty{marvosym}, then undefine the conflicting commands and then +load \sty{ifsym}: +\begin{codeenv} +\cs{usepackage}\marg{etoolbox} +\cs{usepackage}\marg{marvosym} +\cs{undef}\cmd{Sun} +\cs{undef}\cmd{Lightning} +\cs{usepackage}\oarg{\styoptfmt{weather}}\marg{ifsym} +\end{codeenv} +The \sty{etoolbox} package is also loaded as it provides +\ics{undef}. (An alternative is to modify the +\exfile{miscsymbols.bib} file so that it uses \sty{ifsym}'s more +generic \cs{textweathersymbol} command and omit the \styoptfmt{weather} +option when loading the package, but the method used here +demonstrates how to deal with such conflicts.) + +The custom entry type \atentryfmt{icon} must be aliased for the +entries to be recognised: +\begin{codeenv} +\csopt[icon=symbol]{entry-type-aliases} +\end{codeenv} + +Since none of the entries have a \field{name} or \field{description} +field, the custom fields \fieldfmt{icon} and +\fieldfmt{icondescription} need to be aliased to them. +The document uses the \glostyle{alttreegroup} style where the groups +are obtained from the \field{category}, which again I obtain from +the custom \fieldfmt{identifier} field using: +\begin{codeenv} +\csopt[ + \fieldfmt{identifier}=\field{category}, + \fieldfmt{icon}=\field{name}, + \fieldfmt{icondescription}=\field{description}]{field-aliases}, +\csopt[\field{category}=\field{group}]{replicate-fields} +\end{codeenv} +The \field{group} field is just a label and an appropriate title needs to be +supplied for each group label: +\begin{codeenv} +\cs{glsxtrsetgrouptitle}\marg{information}\marg{Information} +\cs{glsxtrsetgrouptitle}\marg{mediacontrol}\marg{Media Controls} +\cs{glsxtrsetgrouptitle}\marg{weather}\marg{Weather Symbols} +\end{codeenv} +This also requires sorting first by \field{category} and then +fallback on another field. The most appropriate here is the +\field{description} field, but instead of using +\csopt{identical-sort-action}, I'm using \csopt{sort-suffix}, +which works better with the default locale sort when the fallback +field consists of words or phrases. +\begin{codeenv} +\csopt[\field{category}]{sort-field}, +\csopt[\field{description}]{sort-suffix}, +\csopt[|]{sort-suffix-marker} +\end{codeenv} +Since I'm using one of the \glostyle{alttree} styles, I need to set +the widest name: +\begin{codeenv} +\csopt{set-widest} +\end{codeenv} +In this case, \bibgls\ won't be able to determine the widest name +since it doesn't recognise any of the commands, so it will have to +use the fallback command, which will use one of the commands +provided by the \sty{glossaries-extra-stylemods} package. + +This is actually not the best method as \bibgls\ can't see the group +titles as they're in the document, so it's only able to sort by the +label. While this might work for English, it can become a problem +for other languages that use extended Latin or non-Latin characters +in their alphabet. A much better method is to treat this as a +hierarchical glossary with topic titles as the top-level entries. +This is covered in the next example \exfile{sample-textsymbols2.tex}. + +The complete document code is listed below. The document build is: +\begin{verbatim} +pdflatex sample-textsymbols +bib2gls sample-textsymbols +pdflatex sample-textsymbols +\end{verbatim} +The resulting document is shown in \figureref{fig:sample-textsymbols.pdf}. + +\lstinputlisting[firstline=6]{../examples/sample-textsymbols.tex} + +\begin{figure} +\figcontents +{% + \frame{\includegraphics[height=.9\textheight]{../examples/sample-textsymbols.pdf}}% +} +{\caption{\filefmt{sample-textsymbols.pdf}}} +{fig:sample-textsymbols.pdf} +\end{figure} + +\filesection{sample-textsymbols2.tex} + +This example is a better approach than the +\exfile{sample-textsymbols.tex} example above. As with the previous +example, this requires both \isty{marvosym} and \isty{ifsym} so the +same patch is applied to avoid conflict. + +As before, the custom entry type \atentryfmt{icon} must be aliased for the +entries to be recognised: +\begin{codeenv} +\csopt[icon=symbol]{entry-type-aliases} +\end{codeenv} + +The \exfile{topics.bib} file contains terms with +labels that match the custom \fieldfmt{identifier} fields used in +the \exfile{miscsymbols.bib} file. So both files are loaded and the +\fieldfmt{identifier} field is now aliased to \field{parent}. These +parent entries represent the topics and unlike the previous example +it's now possible to sort by the topic title (obtained from the +\field{name} field) instead of by the label. +\begin{codeenv} +\csopt[topics,miscsymbols]{src}, +\csopt[ + \fieldfmt{identifier}=\field{parent}, + \fieldfmt{icon}=\field{name}, + \fieldfmt{icondescription}=\field{description}]{field-aliases}, +\end{codeenv} +There's no \csopt{sort-field} option in this example. The default +\field{sort} field is used. Since it's not set for any of the +entries, the fallback value will be used. In the case of the topic +titles (\atentry{index} and \atentry{indexplural}), I want to sort +by the \field{name}, which is the default fallback if the +\field{sort} field is missing for the index entry types. + +The default fallback for the \field{sort} field for \atentry{symbol} +entries is the label, but in this case I want to use the +\field{description} field: +\begin{codeenv} + \csopt[description]{symbol-sort-fallback} +\end{codeenv} +The best styles for this kind of glossary are the topic styles +provided by \isty{glossary-topic}. This package was only added to +\sty{glossaries-extra} v1.40, so you need to make sure you have at +least that version installed. + +In this case I've decided to use the \glostyle{topic} style. I can +use it with or without the \csopt{set-widest} option. +As with the previous example, \bibgls\ won't be able to determine +the widest name since it doesn't recognise any of the commands +contained in the \field{name} fields, so it will have to use the +fallback method, which will use one of the commands provided by the +\sty{glossaries-extra-stylemods} package. The \code{tree} option is +needed to enable the appropriate commands: +\begin{codeenv} +\cmd{usepackage}\oarg{\styopt{record}, + \styopt{nostyles}, + \styopt{postdot}, + \styopt[tree,topic]{stylemods}, + \styopt[topic]{style}}\marg{glossaries-extra} +\end{codeenv} + +The complete document code is listed below. The document build is: +\begin{verbatim} +pdflatex sample-textsymbols2 +bib2gls --group sample-textsymbols2 +pdflatex sample-textsymbols2 +\end{verbatim} +The resulting document is shown in \figureref{fig:sample-textsymbols2.pdf}. + +\lstinputlisting[firstline=5]{../examples/sample-textsymbols2.tex} + +\begin{figure} +\figcontents +{% + \frame{\includegraphics[height=.9\textheight]{../examples/sample-textsymbols2.pdf}}% +} +{\caption{\filefmt{sample-textsymbols2.pdf}}} +{fig:sample-textsymbols2.pdf} +\end{figure} + +\filesection{sample-markuplanguages.tex} + +This example uses \exfile{markuplanguages.bib}. Since the file +includes abbreviations, any commands that must be used before +abbreviations are defined need to go before +\gls!{GlsXtrLoadResources}. This includes the abbreviation style, +which I've set to \abbrstyle{long-short-desc}: +\begin{codeenv} +\cs{setabbreviationstyle}\oarg{markuplanguage}\marg{\abbrstyle{long-short-desc}} +\end{codeenv} +This style sets the \field{name} field using +\ics{glsxtrlongshortdescname}, which defaults to the long form +followed by the short form in parentheses. I decided to switch this +round so that the short form is shown first, which conveniently +matches the default \csopt{abbreviation-sort-fallback}. +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{glsxtrlongshortdescname}}\marg{\comment{} + \cs{protect}\ics{glsabbrvfont}\marg{\ics{the}\ics{glsshorttok}}\cs{space} + \ics{glsxtrparen}\marg{\ics{glslongfont}\marg{\cs{the}\ics{glslongtok}}}\comment{} +} +\end{codeenv} +(The long form is still shown before the short form on the first use +of \cs{gls} in the document. The switch in the above code only +affects how the term is displayed in the glossary.) + +This redefinition must be done before the abbreviations are defined +as it's expanded when the \field{name} field is set. (Note the need +to protect commands that shouldn't be expanded.) If I decide not to change +the \field{name} format in this way, I would then need to use +\csopt[long]{abbreviation-sort-fallback}. + +I also decided to make use of the custom command \csfmt{abbrvtag} +that marks up the letters in the \field{long} field used to obtain +the abbreviation. As with the abbreviation style, this must be +done before the abbreviations are defined: +\begin{codeenv} +\cs{GlsXtrEnableInitialTagging}\marg{markuplanguage}\marg{\cmd{abbrvtag}} +\end{codeenv} +If you accidentally place it after \gls{GlsXtrLoadResources}, you'll +encounter an error on the second \LaTeX\ run (but not the first). +This is because \ics{GlsXtrEnableInitialTagging} requires that the +supplied command (\csfmt{abbrvtag} in this case) be undefined. On +the first \LaTeX\ it's undefined, but on the second it picks up +the \atentry{preamble} definition, which is now in the resource file. + +The tagging format is governed by \ics{glsxtrtagfont} which +underlines its argument by default. I've redefined it to also +convert the letter to \idx{uppercase}: +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{glsxtrtagfont}}[1]\marg{\ics{underline}\marg{\cs{MakeTextUppercase}\marg{\idx{param}1}}} +\end{codeenv} +Note that in the \code{mathml} case, the first tag consists of more +than one letter: +\begin{codeenv} +\field{long}=\marg{\cmd{abbrvtag}\marg{m\cs{NoCaseChange}\marg{ath}}ematical }\idx{stringconcat}markuplang +\end{codeenv} +Here \ics{NoCaseChange} prevents \ics{MakeTextUppercase} +from applying the case change. + +The default \csopt{selection} criteria includes entries that have +been indexed and any cross-references. Some of the +\field{description} fields include \ics{glsxtrshort}, which \bibgls\ picks +up and the referenced entry is included in the dependency list. +However, I don't want any indexing +performed by commands occurring in the glossary. This can be dealt +with in one of two ways: either switch the format to \encap{glsignore} +or suppress the indexing by changing the default options with +\ics{GlsXtrSetDefaultGlsOpts}. In this case I decided to turn the +records into ignored records: +\begin{codeenv} +\ics{GlsXtrSetDefaultNumberFormat}\marg{\encap{glsignore}} +\end{codeenv} +This means that some of the entries won't have location lists, so +I've defined a \idx{postdescriptionhook} that inserts a \idx{full-stop} after the +\field{description} if there's no location otherwise it inserts a +comma: +\begin{codeenv} +\cs{newcommand}\marg{\postdeschook{markuplanguage}}\marg{\comment{} + \cs{glsxtrifhasfield}\marg{\field{location}}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{,}\comment{} + \marg{.}\comment{} +} +\end{codeenv} +I've used \csopt{loc-suffix} to append a \idx{full-stop} after the +location lists. This doesn't affect the entries that haven't been +indexed. + +I decided to convert the first letter of the \field{name} field to +\idx{uppercase}. Since the \field{name} is implicitly set for +abbreviations based on the style, I've decided to implement this +through the \catattr{glossname} attribute rather than using +\csopt{name-case-change}: +\begin{codeenv} +\cs{glssetcategoryattribute}\marg{markuplanguage}\marg{\catattr{glossname}}\marg{firstuc} +\end{codeenv} +If this line causes an error when the glossary is displayed that goes +away if it's commented out, make sure you have at least version 2.06 +of \sty{mfirstuc}. For most of the entries, this doesn't make a +difference as they already start with a capital. It's only the +\code{markdown} entry that's actually affected. + +The description case change is dealt with by \bibgls\ instead: +\begin{codeenv} +\csopt[firstuc]{description-case-change} +\end{codeenv} +This works better than the \catattr{glossdesc} attribute as \bibgls\ can +convert commands like \ics{glstext} into \ics{Glstext} which +\ics{makefirstuc} can't do. (Although in this particular example, +there's no difference as both instances of \cs{glstext} already +produce \idx{uppercase} text.) + +The complete document code is listed below. The document build is: +\begin{verbatim} +pdflatex sample-markuplanguages +bib2gls --group sample-markuplanguages +pdflatex sample-markuplanguages +\end{verbatim} +The resulting document is shown in \figureref{fig:sample-markuplanguages.pdf}. + +\lstinputlisting[firstline=5]{../examples/sample-markuplanguages.tex} + +\begin{figure} +\figcontents +{% + \frame{\includegraphics[height=.9\textheight]{../examples/sample-markuplanguages.pdf}}% +} +{\caption{\filefmt{sample-markuplanguages.pdf}}} +{fig:sample-markuplanguages.pdf} +\end{figure} + + +\filesection{sample-usergroups.tex} + +This example uses \exfile{usergroups.bib}. This requires \XeLaTeX\ +or \LuaLaTeX\ as the \ext{bib} file includes \idx{non-ASCII} labels. +The entries include fields in different languages, the main one +being English. If an entry has a non-English \field{name} or +\field{long} field, it also includes the custom field +\fieldfmt{translation} that provides an (approximate) translation. +If this field is present, the language is given by the first element +of the custom \fieldfmt{language} field. + +In this case, I'm providing keys for the custom +\fieldfmt{language} and \fieldfmt{translation} fields, and, for a bit +of variety from the other examples, I'm ignoring the custom +\fieldfmt{identifier} field. The custom keys are provided with +\ics{glsaddstoragekey}: +\begin{codeenv} +\cs{glsaddstoragekey}\marg{language}\marg{}\marg{\cmd{glsentrylanguage}} +\cs{glsaddstoragekey}\marg{translation}\marg{}\marg{\cmd{glsentrytranslation}} +\end{codeenv} +The \ext{bib} file includes abbreviations. Remember that the +abbreviation style must be set before the resource file is loaded: +\begin{codeenv} +\cs{setabbreviationstyle}\oarg{tug}\marg{\abbrstyle{long-short-user}} +\end{codeenv} +For this example, I'm explicitly setting the \field{category} field +to \code{tug}: +\begin{codeenv} +\csopt[tug]{category} +\end{codeenv} +Some of the fields end with a \idx{full-stop}. This isn't a problem with +the \field{long} field as the first use follows the long form with +the short form in parentheses, but it will be a problem on +subsequent use if the \field{short} field ends with a \idx{full-stop}. +This means I need to check for end-of-sentence punctuation +for the \field{short} field. It's also a good idea to do this for +the \field{name} field for the non-abbreviations. +\begin{codeenv} +\csopt[\field{name},\field{short}]{check-end-punctuation} +\end{codeenv} +It's now possible to discard a \idx{full-stop} that follows +\ics{gls}: +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{glsxtrifcustomdiscardperiod}}[2]\marg{\comment{} + \ics{ifglshasshort}\marg{\cs{glslabel}}\comment{} + \marg{\comment{} + \cs{glsxtrifwasfirstuse}\marg{}\comment{} + \marg{\comment{} + \cs{GlsXtrIfFieldUndef}\marg{\fielddisp{fieldendpunc}{shortendpunc}}\marg{\cs{glslabel}}\marg{\idx{param}2}\marg{\idx{param}1}\comment{} + }\comment{} + }\comment{} + \marg{\comment{} + \cs{GlsXtrIfFieldUndef}\marg{\fielddisp{fieldendpunc}{nameendpunc}}\marg{\cs{glslabel}}\marg{\idx{param}2}\marg{\idx{param}1}\comment{} + }\comment{} +} +\end{codeenv} +This first tests if the entry that's just been referenced has a +\field{short} field. If it has, then the next test is to check if +that was the first use for that entry. If it was, nothing is done. +If it wasn't, then \cs{GlsXtrIfFieldUndef} is used to determine +if \fielddisp{fieldendpunc}{shortendpunc} has been set. If it has +been set then the period discard function is performed. If the +entry doesn't have a \field{short} field, then the +\fielddisp{fieldendpunc}{nameendpunc} field needs checking instead. + +Since the document requires \XeLaTeX\ or \LuaLaTeX\ and has some +\idx{non-ASCII} characters, it needs \sty{fontspec} and an +appropriate font. In this case I've chosen \qt{Linux Libertine O}. +If you don't have it installed, you'll need to change it. +\begin{verbatim} +\usepackage{fontspec} +\setmainfont{Linux Libertine O} +\end{verbatim} +Since it's a multilingual document I also need \sty{polyglossia} +with the main language set to \code{english}: +\begin{codeenv} +\cmd{usepackage}\marg{polyglossia} +\ics{setmainlanguage}\oarg{variant=uk}\marg{english} +\end{codeenv} +Now comes the difficult bit. The document needs to determine what +other languages need to be loaded. The \sty{tracklang} package +provides a convenient interface when dealing with language tags. +This is automatically loaded by \styfmt{glossaries} but I've loaded +it here explicitly as a reminder: +\begin{verbatim} +\usepackage{tracklang} +\end{verbatim} +Once the \hyperref[sec:resourcesets]{resource file} has been loaded, I need to +iterate over all the defined entries and check if the \fieldfmt{translation} +field has been set. If it has, then the first language tag in the +\fieldfmt{language} field will supply the language, but this needs to be +converted from the \idx{IETF} language tag to a language name recognised by +\sty{polyglossia}. + +Iterating over all entries can be done with \ics{forglsentries} +but remember that no entries will be defined before \bibgls\ has +been run, so this does nothing on the first \LaTeX\ run. +\begin{codeenv} +\cs{forglsentries}\marg{\cmd{thislabel}}\marg{\comment{} + \cs{glsxtrifhasfield}\marg{translation}\marg{\cmd{thislabel}}\comment{} + \marg{\comment{} + \comment{requires glossaries-extra v1.24} + \cs{glsxtrforcsvfield}\marg{\cmd{thislabel}}\marg{language}\marg{\cmd{addfirstlang}}\comment{} + }\comment{} + \marg{}\comment{} +} +\end{codeenv} +Within the outer (\cs{forglsentries}) loop, there's a check +for the \fieldfmt{translation} field using \ics{glsxtrifhasfield}. +If it's present, then the first element of the \fieldfmt{language} +field is required. The simplest way to get this is to use +\ics{glsxtrforcsvfield} which iterates over all elements of the +given field (\fieldfmt{language} in this case) and break out of the +loop (with \ics{glsxtrendfor}) once the language has been found. + +The \idx{handler} function (\csfmt{addfirstlang}) is defined so that it +adds the given language tag as a tracked language using +\ics{TrackLocale}. This command sets +\ics{TrackLangLastTrackedDialect} to the associated +(\sty{tracklang}) dialect label for convenience. This dialect label +can then be converted to the root language label using +\ics{TrackedLanguageFromDialect}. If this language is supported +by \sty{polyglossia}, then there should be a file called +\metafilefmt{gloss-}{language}{.ldf}. + +Some of the entries use the same language, so it's necessary to +check if the language has already been defined before loading it. +There's also a problem in that the language file should not be +loaded in a scoped context, but both \ics{glsxtrforcsvfield} +and the unstarred \ics{glsxtrifhasfield} add implicit grouping. +To solve both problems, an internal \sty{etoolbox} list is +defined: +\begin{verbatim} +\newcommand{\langlist}{}% +\end{verbatim} +and \ics{xifinlist} is used to first check if the language label is +already in the list before adding it. Since this part of the code is +scoped, the global \ics{listxadd} is used to add the language label +to the list. + +Next the \field{useri} field is set to +\encapdisp{textlanguage}{text\meta{language}} +which is the name of the control sequence used with +\sty{polyglossia} to switch language for a short block of text. This means that +\gls{glsxtrentryfmt}\margm{text} can be used to format \meta{text} +in the relevant language. Finally, \ics{glsxtrendfor} is used to +break out of the loop. +\begin{codeenv} +\cs{newcommand}*\marg{\cmd{addfirstlang}}[1]\marg{\comment{} + \cs{TrackLocale}\marg{\idx{param}1}\comment{} + \ics{edef}\cmd{thislanguage}\marg{\comment{} + \cs{TrackedLanguageFromDialect}\cs{TrackLangLastTrackedDialect}}\comment{} + \ics{IfFileExists}\marg{gloss-\cmd{thislanguage}.ldf}\comment{} + \marg{\comment{} + \ics{xifinlist}\marg{\cmd{thislanguage}}\marg{\cmd{langlist}}\marg{}\comment{} + \marg{\ics{listxadd}\marg{\cmd{langlist}}\marg{\cmd{thislanguage}}}\comment{} + \ics{xGlsXtrSetField}\marg{\cmd{thislabel}}\marg{\field{useri}}\marg{\encapdisp{textlanguage}{text\cmd{thislanguage}}}\comment{} + \ics{glsxtrendfor} + }\comment{} + \marg{}\comment{} +} +\end{codeenv} +Once the \ics{forglsentries} loop has found the appropriate +languages, it's now necessary to iterate over the internal list +\csfmt{langlist} and set the language: +\begin{codeenv} +\ics{forlistloop}\marg{\ics{setotherlanguage}}\marg{\cmd{langlist}} +\end{codeenv} +The \abbrstyle{long-short-user} style now needs to be adjusted +to ensure that it picks up the appropriate language change. +By default this style checks the \field{useri} field, so this needs +to be changed to \fieldfmt{translation} by redefining +\ics{glsxtruserfield}: +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{glsxtruserfield}}\marg{translation} +\end{codeenv} +The command that governs the format of the parenthetical material +(\ics{glsxtruserparen}) also needs adjusting. I've changed the +space before the parenthesis to \ics{cs.space} because some of the +long fields end with a \idx{full-stop} and this corrects the +spacing. The \fieldfmt{translation} field is in English, +so this needs to be encapsulated with \icsdisp{textlanguage}{textenglish} +in case the surrounding text is in a different language. +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{glsxtruserparen}}[2]\marg{\comment{} + \cs{cs.space} + \cs{glsxtrparen}\marg{\idx{param}1\comment{} + \cs{ifglshasfield}\marg{\cs{glsxtruserfield}}\marg{\idx{param}2}\marg{, + \csdisp{textlanguage}{textenglish}\marg{\cs{glscurrentfieldvalue}}}\marg{}}\comment{} +} +\end{codeenv} +Next I've defined a convenient command for use in the \catattr{textformat} +attributes for the custom \code{tug} category: +\begin{codeenv} +\cs{newcommand}*\marg{\cmd{tugtextformat}}[1]\marg{\comment{} + \cs{glsxtrentryfmt}\marg{\cs{glslabel}}\marg{\idx{param}1}\comment{} +} +\end{codeenv} +This uses \gls{glsxtrentryfmt} to encapsulate the given text +in the appropriate language command (if provided). When this is set +as the \catattr{textformat} attribute, it will be used instead of +\ics{glstextformat}, which means that the entry label can be +referenced with \cs{glslabel}. + +There's a similar command for use in the \catattr{glossnamefont} +attribute. This is used in the glossary, so the label is referenced +with \cs{glscurrententrylabel}: +\begin{codeenv} +\cs{newcommand}*\marg{\cmd{tugnameformat}}[1]\marg{\comment{} + \cs{glsxtrentryfmt}\marg{\cs{glscurrententrylabel}}\marg{\idx{param}1}\comment{} +} +\end{codeenv} +The attributes can now be set to the relevant control sequence name: +\begin{codeenv} +\cs{glssetcategoryattribute}\marg{tug}\marg{\catattr{textformat}}\marg{tugtextformat} +\cs{glssetcategoryattribute}\marg{tug}\marg{\catattr{glossnamefont}}\marg{tugnameformat} +\end{codeenv} + +The document uses the \glostyle{bookindex} style, which is set in +the package options: +\begin{codeenv} +\cmd{usepackage}\oarg{\styopt{record}, + \styopt{nostyles}, + \styopt[bookindex]{stylemods}, + \styopt[bookindex]{style} +}\marg{glossaries-extra} +\end{codeenv} +The \glostyle{bookindex} style ignores the \field{description} field, so I've +provided a \idx{postnamehook} to append it in parentheses (with the +translation, if provided): +\begin{codeenv} +\cs{newcommand}\marg{\postnamehook{tug}}\marg{\comment{} + \ics{ifglshasdesc}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{\cs{cs.space}(\cs{glossentrydesc}\marg{\cs{glscurrententrylabel}}\comment{} + \cs{glsxtrifhasfield}\marg{translation}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{, \csdisp{textlanguage}{textenglish}\marg{\cs{glscurrentfieldvalue}}}\comment{} + \marg{}\comment{} + )}\comment{} + \marg{\comment{} + \cs{glsxtrifhasfield}\marg{translation}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{\cs{cs.space}(\csdisp{textlanguage}{textenglish}\marg{\cs{glscurrentfieldvalue}})}\comment{} + \marg{}\comment{} + }\comment{} +} +\end{codeenv} +Remember that this hook is included within the \field{name} font +(provided by the \catattr{glossnamefont} attribute in this case) +so \csdisp{textlanguage}{textenglish} is again used to switch the language to +English for the translation. + +The complete document code is listed below. The document build is: +\begin{verbatim} +xelatex sample-usergroups +bib2gls --group sample-usergroups +xelatex sample-usergroups +xelatex sample-usergroups +\end{verbatim} +The two pages of the document are shown in +\figureref{fig:sample-usergroups.pdf}. Since the entries have all +been referenced on page~1, the location lists are all simply~\qt{1}. + +%\lstinputlisting[firstline=5]{../examples/sample-usergroups.tex} +\begin{lstlisting}[escapechar=|] +\documentclass{scrreprt} + +\usepackage{fontspec} +\setmainfont{Linux Libertine O} + +\usepackage{polyglossia} +\setmainlanguage[variant=uk]{english} +\usepackage{tracklang} +\usepackage{etoolbox} + +\usepackage[record,% use bib2gls + nostyles,% don't load default styles + stylemods={bookindex}, + style={bookindex} +]{glossaries-extra} + +\glsaddstoragekey{language}{}{\glsentrylanguage} +\glsaddstoragekey{translation}{}{\glsentrytranslation} + +\setabbreviationstyle[tug]{long-short-user} + +\GlsXtrLoadResources[ + src={usergroups}, % data in usergroups.bib + check-end-punctuation={name,short}, + category=tug +] + +\renewcommand*{\glsxtrifcustomdiscardperiod}[2]{% + \ifglshasshort{\glslabel}% + {% + \glsxtrifwasfirstuse{}% + {% + \GlsXtrIfFieldUndef{shortendpunc}{\glslabel}{#2}{#1}% + }% + }% + {% + \GlsXtrIfFieldUndef{nameendpunc}{\glslabel}{#2}{#1}% + }% +} + +\newcommand{\langlist}{}% + +\newcommand*{\addfirstlang}[1]{% + \TrackLocale{#1}% + \edef\thislanguage{% + \TrackedLanguageFromDialect\TrackLangLastTrackedDialect}% + \IfFileExists{gloss-\thislanguage.ldf}% + {% + \xifinlist{\thislanguage}{\langlist}{}% + {\listxadd{\langlist}{\thislanguage}}% + \xGlsXtrSetField{\thislabel}{useri}{text\thislanguage}% + \glsxtrendfor + }% + {}% +} + +\forglsentries{\thislabel}{% + \glsxtrifhasfield{translation}{\thislabel}% + {% + % requires glossaries-extra v1.24 + \glsxtrforcsvfield{\thislabel}{language}{\addfirstlang}% + }% + {}% +} + +\forlistloop{\setotherlanguage}{\langlist} + +\renewcommand*{\glsxtruserfield}{translation} + +\renewcommand*{\glsxtruserparen}[2]{% + \ + \glsxtrparen{#1% + \ifglshasfield{\glsxtruserfield}{#2}{, + \textenglish{\glscurrentfieldvalue}}{}}% +} + +\newcommand*{\tugtextformat}[1]{% + \glsxtrentryfmt{\glslabel}{#1}% +} + +\newcommand*{\tugnameformat}[1]{% + \glsxtrentryfmt{\glscurrententrylabel}{#1}% +} + +\glssetcategoryattribute{tug}{textformat}{tugtextformat} +\glssetcategoryattribute{tug}{glossnamefont}{tugnameformat} + +\newcommand{\glsxtrpostnametug}{% + \ifglshasdesc{\glscurrententrylabel}% + {\ (\glossentrydesc{\glscurrententrylabel}% + \glsxtrifhasfield{translation}{\glscurrententrylabel}% + {, \textenglish{\glscurrentfieldvalue}}% + {}% + )}% + {% + \glsxtrifhasfield{translation}{\glscurrententrylabel}% + {\ (\textenglish{\glscurrentfieldvalue})}% + {}% + }% +} + +\begin{document} +\chapter{Sample} +\section{First Use} +\gls{TUG}. \gls{bgTeX}. \gls{latex-br}. \gls{CTeX}. +\gls{CSTUG}. \gls{DANTE}. \gls{DKTUG}. \gls{EUG}. +\gls{CervanTeX}. \gls{TirantloTeX}. \gls{GUTenberg}. +\gls{UKTUG}. \gls{|\greekmono ɛϕτ|}. \gls{MaTeX}. \gls{ITALIC}. +\gls{ÍsTeX}. \gls{GuIT}. \gls{KTS}. \gls{LTVG}. +\gls{mxTeX}. \gls{NTG}. \gls{NTUG}. \gls{GUST}. \gls{GUTpt}. +\gls{VietTUG}. \gls{LUGSA}. + +\section{Next Use} + +\gls{TUG}. \gls{bgTeX}. \gls{latex-br}. \gls{CTeX}. +\gls{CSTUG}. \gls{DANTE}. \gls{DKTUG}. \gls{EUG}. +\gls{CervanTeX}. \gls{TirantloTeX}. \gls{GUTenberg}. +\gls{UKTUG}. \gls{|\greekmono ɛϕτ|}. \gls{MaTeX}. \gls{ITALIC}. +\gls{ÍsTeX}. \gls{GuIT}. \gls{KTS}. \gls{LTVG}. +\gls{mxTeX}. \gls{NTG}. \gls{NTUG}. \gls{GUST}. \gls{GUTpt}. +\gls{VietTUG}. \gls{LUGSA}. + +\printunsrtglossaries +\end{document} +\end{lstlisting} + +\begin{figure} +\figcontents +{\pdftwocol{../examples/sample-usergroups.pdf}{2}} +{\caption{\filefmt{sample-usergroups.pdf}}} +{fig:sample-usergroups.pdf} +\end{figure} + +\filesection{sample-multi1.tex} + +This example uses \exfile{bacteria.bib}, +\exfile{markuplanguages.bib}, \exfile{vegetables.bib}, \exfile{minerals.bib}, +\exfile{animals.bib}, \exfile{chemicalformula.bib}, +\exfile{baseunits.bib} and \exfile{derivedunits.bib}. +Since there's one or more UTF-8 character, the document requires +UTF-8 support: +\begin{verbatim} +\usepackage[T1]{fontenc} +\usepackage[utf8]{inputenc} +\end{verbatim} + +The aim of this example document is to have a separate glossary +(without number lists) for each type of data (bacteria, markup +languages, vegetables, minerals, animals, chemical formula, base +units and derived units) and also an +index listing all referenced entries with number lists as well as +aliased entries that haven't explicitly been used but the +cross-reference term as been indexed. This requires: +\begin{codeenv} +\csopt[recorded and deps and see]{selection} +\end{codeenv} +to ensure the aliased entries are selected. + +Since I don't need the default \code{main} glossary (I'm providing +my own custom glossaries) I've used the \styopt{nomain} option to +suppress its automatic creation, but I do want the \code{index} +glossary so I've used the \styopt{index} package option. As with the +other examples, I've used \styopt{nostyles} to suppress the creation +of the default styles and used \styopt{stylemods} to load the +particular style packages that I need and use +\sty{glossaries-extra-stylemods} to patch them. The index needs to +be in an unnumbered chapter, which is the default for book-like +styles, but I want the other glossaries in unnumbered sections so +I've used the \styopt{section} option. I just need to remember to +switch this before displaying the index: +\begin{codeenv} +\cmd{usepackage}\oarg{\styopt{record},\comment{use bib2gls} + \styopt{section},\comment{use \ics{section*} for glossary headings} + \styopt{postdot},\comment{insert dot after descriptions in glossaries} + \styopt{nomain},\comment{don't create 'main' glossary} + \styopt{index},\comment{create 'index' glossary} + \styopt{nostyles},\comment{don't load default styles} +\comment{load and patch required style packages:} + \styopt[list,mcols,tree,bookindex]{stylemods} +}\marg{glossaries-extra} +\end{codeenv} +The remaining glossaries need defining: +\begin{codeenv} +\cs{newglossary*}\marg{bacteria}\marg{Bacteria} +\cs{newglossary*}\marg{markuplanguage}\marg{Markup Languages} +\cs{newglossary*}\marg{vegetable}\marg{Vegetables} +\cs{newglossary*}\marg{mineral}\marg{Minerals} +\cs{newglossary*}\marg{animal}\marg{Animals} +\cs{newglossary*}\marg{chemical}\marg{Chemical Formula} +\cs{newglossary*}\marg{baseunit}\marg{SI Units} +\cs{newglossary*}\marg{derivedunit}\marg{Derived Units} +\end{codeenv} +As with \exfile{sample-bacteria.tex} and \exfile{sample-markuplanguages.tex} +I need to set the abbreviation styles before the abbreviations are +defined: +\begin{codeenv} +\cs{setabbreviationstyle}\oarg{bacteria}\marg{\abbrstyle{long-only-short-only}} +\cs{setabbreviationstyle}\oarg{markuplanguage}\marg{\abbrstyle{long-short-desc}} +\end{codeenv} +Unlike the \exfile{sample-markuplanguages.tex} example, I'm not interested +in tagging the initials in this case, but I still want to change the +way the \field{name} field is set with the +\abbrstyle{long-short-desc} abbreviation style: +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{glsxtrlongshortdescname}}\marg{\comment{} + \cs{protect}\cs{glsabbrvfont}\marg{\cs{the}\cs{glsshorttok}}\cs{space} + \cs{glsxtrparen}\marg{\cs{glslongfont}\marg{\cs{the}\cs{glslongtok}}}\comment{} +} +\end{codeenv} +Remember that this also needs to be set before the abbreviations are +defined. The \catattr{textformat} and \catattr{glossnamefont} +attributes may be set after definition: +\begin{codeenv} +\cs{newcommand}\marg{\cmd{bacteriafont}}[1]\marg{\cs{emph}\marg{\idx{param}1}} +\cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{textformat}}\marg{bacteriafont} +\cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{glossnamefont}}\marg{bacteriafont} +\end{codeenv} +The description font also needs to be set since this will contain +the long form: +\begin{codeenv} +\cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{glossdescfont}}\marg{bacteriafont} +\end{codeenv} + +The \code{markuplanguage} glossary contains descriptions and some +long names, so it's better suited to the \glostyle{altlist} style, +in which case the descriptions would look better if they started +with a capital letter: +\begin{codeenv} +\cs{glssetcategoryattribute}\marg{markuplanguage}\marg{\catattr{glossdesc}}\marg{firstuc} +\end{codeenv} +Remember that the \glostyle{altlist} style uses the +\env{description} environment, which is governed by the document +class (and may be modified by list-related packages). In this case, +one of the KOMA-Script classes is used, so the list items are +typeset in sans-serif. + +There are various ways of dealing with the duplicated data in the +index, such as using the \csopt{secondary} option or having a +separate resource set with a copy \csopt{action}. In this case, I've +decided to use a dual entry system. Since the entries aren't defined +using any dual types, I've used \csopt{entry-type-aliases} to +make \bibgls\ treat them as though they were, and I also need to +alias the custom \atentryfmt{chemical}, \atentryfmt{unit} and +\atentryfmt{measurement} entry types: +\begin{codeenv} +\csopt[ + abbreviation=dualindexabbreviation, + entry=dualindexentry, + symbol=dualindexsymbol, + unit=dualindexsymbol, + measurement=dualindexsymbol, + chemical=dualindexsymbol + ]{entry-type-aliases} +\end{codeenv} +Note that I haven't aliased the \atentry{index} types as I only want +these in the index and not replicated in a separate glossary. + +The primary entries for the \atentry{dualindexabbreviation} type +ignore the short form. It would be useful to store it. This could be +done by copying the \field{short} field with +\csopt{replicate-fields}. For example, +\csopt[\field{short}=\field{symbol}]{replicate-fields}. However, this will cause the +\field{symbol} field to be set for both the primary and dual +entries, which will cause an unwanted duplication if the dual +entries are displayed using a glossary style that shows the +\field{symbol} field. Another field (such as \field{user1}) could be +used instead or \gls{bibglsnewdualindexabbreviation} could be +defined before \gls{GlsXtrLoadResources}: +\begin{codeenv} +\cs{newcommand}\marg{\gls{bibglsnewdualindexabbreviation}}[7]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\comment{} + \field{name}=\marg{\cs{protect}\gls{bibglsuselongfont}\marg{\idx{param}4}\marg{\cs{glscategory}\marg{\idx{param}2}}},\comment{} + \field{symbol}=\marg{\cs{protect}\gls{bibglsuseabbrvfont}\marg{\idx{param}5}\marg{\cs{glscategory}\marg{\idx{param}2}}},\comment{} + \field{category}=\marg{index},\idx{param}3}\marg{}\comment{} +} +\end{codeenv} +However, this will affect all \atentry{dualindexabbreviation} entry +types, but it's not necessary for the bacteria abbreviations. +Instead it's simpler to just keep a record of the dual label so that +the short form can be obtained from the dual entry: +\begin{codeenv} +\csopt{dual-field} +\end{codeenv} + +By default, the \atentry{dualindexabbreviation} entry type falls back on the +\field{short} field if the \field{name} is omitted. In this case I +want it to fall back on the \field{long} field instead. +\begin{codeenv} +\csopt[long]{abbreviation-name-fallback} +\end{codeenv} +Remember that the sort fallback for abbreviations is still \field{short} (but can be +changed with \csopt{abbreviation-sort-fallback}), but I've changed +the sort fallback for symbols: +\begin{codeenv} +\csopt[name]{symbol-sort-fallback} +\end{codeenv} +I also need to alias the custom fields (especially for those in the +\exfile{chemicalformula.bib}, \exfile{baseunits.bib} and +\exfile{derivedunits.bib} files): +\begin{codeenv} +\csopt[ + \fieldfmt{identifier}=\field{category}, + \fieldfmt{formula}=\field{symbol}, + \fieldfmt{chemicalname}=\field{name}, + \fieldfmt{unitname}=\field{name}, + \fieldfmt{unitsymbol}=\field{symbol}, + \fieldfmt{measurement}=\field{description} +]{field-aliases} +\end{codeenv} +There's a slight problem here. This ensures that the entries defined +in \exfile{chemicalformula.bib} have a \field{name} and +\field{symbol} field, which are swapped round for the dual +(according to the default \csopt{dual-indexsymbol-map}) but these +entries don't have a \field{description} field. Since I'd like to +use the \glostyle{mcolalttreegroup} style, this will end up with +the odd appearance of the formula (stored in the \field{name} field for the +dual) followed by the chemical name (stored in the \field{symbol} +field for the dual) in parenthesis. This is the default \meta{name} +(\meta{symbol}) \meta{description} format for the style. I've fixed +this by locally redefining \ics{glsxtralttreeSymbolDescLocation} for +just that glossary: +\begin{codeenv} +\cs{printunsrtglossary*}\oarg{\printglossopt[chemical]{type},\printglossopt[mcolalttreegroup]{style}} +\marg{\comment{} + \cs{renewcommand}\cs{glsxtralttreeSymbolDescLocation}[2]\marg{\comment{} + \ics{glossentrysymbol}\marg{\idx{param}1}\cs{glspostdescription}\ics{glsxtrAltTreePar} + }\comment{} + \cs{renewcommand}*\marg{\cs{glstreenamefmt}}[1]\marg{\idx{param}1}\comment{} + \cs{renewcommand}*\marg{\cs{glstreegroupheaderfmt}}[1]\marg{\cs{textbf}\marg{\idx{param}1}}\comment{} +} +\end{codeenv} +I've also redefined \cs{glstreenamefmt} to prevent the names +appearing in bold, which means I also need to redefine +\cs{glstreegroupheaderfmt} to keep the headers bold. + +All the \atentryfmt{dualindex\meta{type}} entry types provide a primary +entry that behaves like \atentry{index}. The secondary behaves like +\atentryfmt{\meta{type}}. This means that the primaries are +conveniently gathered together with all the unaliased \atentry{index} +entries, so the primary entry type needs to be set to \code{index}: +\begin{codeenv} +\csopt[index]{type} +\end{codeenv} +The dual entry type depends on the entry's category. Since I've +defined my custom glossaries with a label that matches the +custom \fieldfmt{identifier} field, I can both alias this custom field +to the \field{category} field and also set \csopt{dual-type} so that +it matches the category: +\begin{codeenv} +\csopt[\fieldfmt{identifier}=\field{category}]{field-aliases}, +\csopt[same as category]{dual-type} +\end{codeenv} +The primary entries (in the \code{index} glossary) need to be sorted +alphabetically, and since the document is in English I'm sorting +according to that language (identified by the language code +\code{en}), but I also want to make sure that all the primary +entries are sorted by the \field{name} field to avoid discrepancies +in the fallback value for the \field{sort} field: +\begin{codeenv} +\csopt[en]{sort}, +\csopt[name]{sort-field} +\end{codeenv} +With \csopt[long]{abbreviation-name-fallback} now set, +this means that \emph{Coxiella burnetii} comes after +\emph{Clostridium tetani} in the index. I haven't changed the sort +field for the dual entries, so in that case the +\csopt{abbreviation-sort-fallback} and \csopt{symbol-sort-fallback} +settings will be used with the duals. This means that +\emph{C.\ burnetii} is between \emph{C.\ botulinum} and \emph{C.\ +perfringens} rather than after \emph{C.\ tetani}. + +I'd like to sort the dual entries according to a letter-number rule +(as for the above \exfile{sample-chemical.tex} and \exfile{sample-units3.tex} +examples) +but this would order \qt{b\'ilinite} after \qt{biotite} in the +\code{minerals} glossary, so instead I'm also using the English sort +rule for the duals, but with the numbers padded: +\begin{codeenv} +\csopt[en]{dual-sort}, +\csopt[2]{dual-sort-number-pad}, +\end{codeenv} +This method doesn't work as well as the method used in +\exfile{sample-chemical.tex} as it doesn't separate the capitals, +digits and \idx!{lowercase} characters in the way that can be achieved with the +letter-number methods. An improvement can be made by changing the +break-points. I could use \csopt[upper-upper]{dual-break-at} but +this would put \qt{seal} before \qt{sea lion} in the \code{animal} +glossary, so instead I've used: +\begin{codeenv} +\csopt[upper-upper-word]{dual-break-at} +\end{codeenv} +This now puts \qt{sea lion} before \qt{seal}. Unfortunately the word +break points will cause a break at the markers used to indicate +positive and negative numbers that are inserted with +\csopt{dual-sort-number-pad}, so these need to be changed to +something that won't cause them to be discarded: +\begin{codeenv} +\csopt[0]{dual-sort-pad-minus}, +\csopt[1]{dual-sort-pad-plus} +\end{codeenv} + +The document loads \sty{hyperref} which means that all the \cs{gls} +references will create hyperlinks. Since the primaries are in the +index, the default prefixes mean that, for example, +\code{\cs{gls}\marg{svg}} links to the \qt{scalable vector graphics} item in +the index rather than to the abbreviation \qt{SVG} in the +\code{markuplanguage} glossary. There are two alternatives: change +\code{\cs{gls}\marg{svg}} to \code{\cs{gls}\marg{dual.svg}} or change the +default prefixes, which is the more convenient approach and is the one used +here: +\begin{codeenv} +\csopt[idx.]{label-prefix}, +\csopt[\empty]{dual-prefix} +\end{codeenv} +Now \code{\cs{gls}\marg{svg}} refers to the dual abbreviation \qt{SVG} and +\code{\cs{gls}\marg{idx.svg}} refers to the primary entry \qt{scalable vector +graphics}. Unfortunately this means that the records created with +\code{\cs{gls}\marg{svg}} now refer to the dual abbreviation and will end up +being displayed in the glossary instead of the index. This can be +fixed with: +\begin{codeenv} +\csopt[primary]{combine-dual-locations} +\end{codeenv} +Which transfers the dual entry locations to the corresponding +primary. + +The other problem is the cross-references in the \field{description} +fields. Since the labels don't start with \qt{\idprefix{dual}} \bibgls\ +will assume they refer to the primary entries, which means that +\qt{\idprefixfmt{idx}} (the value of \csopt{label-prefix}) will be +inserted. This means that they'll link to the index rather than the +glossary entry. It also means that the cross-references where the +dual is an abbreviation won't behave like an abbreviation as the +reference is to the primary (non-abbreviation) entry. This can be +fixed by setting \csopt{cs-label-prefix} to the same value as +\csopt{dual-prefix}: +\begin{codeenv} +\csopt[\empty]{cs-label-prefix} +\end{codeenv} +The index is displayed using the \glostyle{bookindex} style. This +doesn't show the description or symbol by default, but it would be +useful to include the symbol in parentheses after the name. This can +be done by redefining \ics{glsxtrbookindexname}: +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\comment{} + \cs{glossentryname}\marg{\idx{param}1}\comment{} + \cs{ifglshassymbol}\marg{\idx{param}1}\marg{\cs{space}(\cs{glossentrysymbol}\marg{\idx{param}1})}\marg{}\comment{} +} +\end{codeenv} +However the chemical forumlae look a little odd in parentheses +(especially those that contain parenthetical parts) but this can be +fixed by adding a category check: +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\comment{} + \cs{glossentryname}\marg{\idx{param}1}\comment{} + \cs{ifglshassymbol}\marg{\idx{param}1}\comment{} + \marg{\comment{} + \cs{glsifcategory}\marg{\idx{param}1}\marg{chemical}\comment{} + \marg{, \cs{glossentrysymbol}\marg{\idx{param}1}}\comment{} + \marg{\cs{space}(\cs{glossentrysymbol}\marg{\idx{param}1})}\comment{} + }\comment{} + \marg{}\comment{} +} +\end{codeenv} +Unfortunately \ics{glossentrysymbol} doesn't pick up the +\catattr{glossnamefont} attribute, so if the short form of the +abbreviations is saved in the \field{symbol} field, using one of the +methods discussed above, then the custom \csfmt{bacteriafont} won't +be applied. A simple solution is to use \ics{glossentrynameother} +instead: +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\comment{} + \cs{glossentryname}\marg{\idx{param}1}\comment{} + \cs{ifglshassymbol}\marg{\idx{param}1}\comment{} + \marg{\comment{} + \cs{glsifcategory}\marg{\idx{param}1}\marg{chemical}\comment{} + \marg{, \cs{glossentrysymbol}\marg{\idx{param}1}}\comment{} + \marg{\cs{space}(\cs{glossentrynameother}\marg{\idx{param}1}\marg{\field{symbol}})}\comment{} + }\comment{} + \marg{}\comment{} +} +\end{codeenv} +However, since I decided not to store the short form in the +\field{symbol} field and just saved the dual entry label instead, I +need to lookup the short form from the dual entry: +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\comment{} + \cs{glossentryname}\marg{\idx{param}1}\comment{} + \cs{ifglshassymbol}\marg{\idx{param}1}\comment{} + \marg{\comment{} + \cs{glsifcategory}\marg{\idx{param}1}\marg{chemical}\comment{} + \marg{, \ics{glossentrysymbol}\marg{\idx{param}1}}\comment{} + \marg{\cs{space}(\ics{glossentrynameother}\marg{\idx{param}1}\marg{\field{symbol}})}\comment{} + }\comment{} + \marg{\comment{} + \cs{glsifcategory}\marg{\idx{param}1}\marg{markuplanguage}\comment{} + \marg{\comment{} + \cs{glsxtrifhasfield}\marg{\field{short}}\marg{\cs{glsxtrusefield}\marg{\idx{param}1}\marg{\field{dual}}}\comment{} + \marg{\cs{space}(\cs{glscurrentfieldvalue})}\comment{} + \marg{}\comment{} + }\comment{} + \marg{}\comment{} + }\comment{} +} +\end{codeenv} +Not all of the markup languages are abbreviations so this uses +\ics{glsxtrifhasfield} to check if the \field{short} field is set. +The dual entry's label is easily obtained because \csopt{dual-field} +has provided the \fieldfmt{dual} internal field and set it to the +corresponding label. + +It's sometimes useful for the index to include a reference to the +term's definition. This can be done by making use of +\idx{glsextrapostnamehook}, which can be redefined before the +glossaries to automatically record each entry: +\begin{codeenv} +\cs{renewcommand}\marg{\cs{glsextrapostnamehook}}[1]\marg{\cs{glsadd}\oarg{\glsaddopt[\encap{hyperbf}]{format}}\marg{\idx{param}1}} +\end{codeenv} +This needs to be redefined to ignore its argument before the index, +to avoid the redundant index record: +\begin{codeenv} +\cs{renewcommand}\marg{\cs{glsextrapostnamehook}}[1]\marg{} +\end{codeenv} +Remember that if any records are added within a glossary, an extra +\LaTeX\ and \bibgls\ call are required to ensure that the location list +is correct, so the document build is: +\begin{verbatim} +pdflatex sample-multi1 +bib2gls --group sample-multi1 +pdflatex sample-multi1 +bib2gls --group sample-multi1 +pdflatex sample-multi1 +\end{verbatim} +The complete document code is listed below. +The resulting document is shown in \figureref{fig:sample-multi1.pdf} +and \figureref{fig:sample-multi1.pdf2}. + +\lstinputlisting[firstline=5]{../examples/sample-multi1.tex} + +\begin{figure} +\figcontents +{\pdftwocol{../examples/sample-multi1.pdf}{4}} +{\caption{\filefmt{sample-multi1.pdf} (pages~1 to~4)}} +{fig:sample-multi1.pdf} +\end{figure} + +\begin{figure} +\figcontents +{\pdftwocol[5]{../examples/sample-multi1.pdf}{8}} +{\caption{\filefmt{sample-multi1.pdf} (pages~5 to 8)}} +{fig:sample-multi1.pdf2} +\end{figure} + +\filesection{sample-multi2.tex} + +This example is an alternative approach to +\exfile{sample-multi1.tex}. Instead of using dual entry types to +define entries that appear in both a glossary and the index, this +example makes use of \csopt{record-label-prefix} to reselect the +recorded entries for the index. This is more complicated but it +allows the entries that have natural word ordering to use a locale +sort method while the entries that are symbolic can use one of the +letter-number sort methods. + +This document uses some additional \ext{bib} files to the previous +example, so it has extra glossaries, which all need to be defined: +\begin{codeenv} +\cs{newglossary*}\marg{bacteria}\marg{Bacteria} +\cs{newglossary*}\marg{markuplanguage}\marg{Markup Languages} +\cs{newglossary*}\marg{vegetable}\marg{Vegetables} +\cs{newglossary*}\marg{mineral}\marg{Minerals} +\cs{newglossary*}\marg{animal}\marg{Animals} +\cs{newglossary*}\marg{chemical}\marg{Chemical Formula} +\cs{newglossary*}\marg{baseunit}\marg{SI Units} +\cs{newglossary*}\marg{measurement}\marg{Measurements} +\cs{newglossary*}\marg{film}\marg{Films} +\cs{newglossary*}\marg{book}\marg{Books} +\cs{newglossary*}\marg{person}\marg{People} +\cs{newglossary*}\marg{mediacontrol}\marg{Media Control Symbols} +\cs{newglossary*}\marg{information}\marg{Information Symbols} +\cs{newglossary*}\marg{weather}\marg{Weather Symbols} +\end{codeenv} +Note that this is a total of 15~glossaries (including the +\code{index}). With the basic \ics{cs.makeglossaries} method, this would +require 16 write registers (including the write register used to +create the indexing style file), and a total of $15\times3 + 1 = 46$ +associated files. (This doesn't include the standard \ext{aux} file +and the \ext{out} file created by \sty{hyperref}.) With \bibgls, no +additional write registers are required and the number of associated +\bibgls\ files is equal to the number of resource commands plus the +transcript file (in this example, $9+1=10$). + +Since this document requires \exfile{people.bib}, \exfile{books.bib} +and \exfile{films.bib} it also requires the files that +supply the definitions of the custom commands +(\exfile{no-interpret-preamble.bib} and either +\exfile{interpret-preamble.bib} or \exfile{interpret-preamble2.bib}) +to ensure the custom commands are provided both for the document and +for \bibgls's interpreter. + +The first resource set to be loaded simply reads +\exfile{no-interpret-preamble.bib} with the preamble interpreter +switched off: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[no-interpret-preamble]{src}, + \csopt[false]{interpret-preamble} +} +\end{codeenv} +This ensures that \LaTeX\ can pick up the provided commands and +prevents them from being added to the interpreter. + +The \exfile{people.bib} file is the next to be loaded with +\exfile{interpret-preamble.bib}. This is loaded separately from the +other resources as this needs the \field{name} field to be copied to +\field{first} (if not already set), as in the +\exfile{sample-people.tex} file. By having a separate resource set, +this setting doesn't affect the other entries. I've also converted +the date fields so that I can customise the format in the document. +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[interpret-preamble,people]{src}, + \csopt[ + \fieldfmt{identifier}=\field{category}, + \fieldfmt{born}=\field{user1}, + \fieldfmt{died}=\field{user2}, + \fieldfmt{othername}=\field{user3} + ]{field-aliases}, + \csopt[\field{name}=\marg{\field{first}}]{replicate-fields}, + \csopt[person]{type}, + \csopt[false]{save-locations} + \csopt[\field{user1},\field{user2}]{date-fields}, + \csopt[d MMM y G]{date-field-format} +} +\end{codeenv} +As with the \exfile{sample-people.tex} document, I need to use the +\longarg{break-space} switch to convert the \idx{nbspchar} to a +normal breakable space so that it matches the given format. I've +loaded the \sty{datetime2} package:\footnote{The +\styoptfmt{en-GB} option to \sty{datetime2} also requires that +\styfmt{datetime2-english} must be installed.} +\begin{verbatim} +\usepackage[en-GB]{datetime2} +\end{verbatim} +so that I can use \ics{DTMdisplaydate} to adjust the formatting: +\begin{codeenv} +\cs{newcommand}*\marg{\gls{bibglsdate}}[7]\marg{\cs{DTMdisplaydate}\marg{\idx{param}1}\marg{\idx{param}2}\marg{\idx{param}3}\marg{\idx{param}4}} +\end{codeenv} +This needs to go before the \idx{resourceset} is loaded. Note that +the \styoptfmt{en-GB} option identifies the document locale as +\code{en-GB} (since there are no language packages loaded). + +Note that unlike \exfile{sample-people.tex} which had +\csopt[people]{category}, this document obtains the \field{category} field +from the custom \fieldfmt{identifier} field, which in this case +has the value \code{person}. This means that the category hooks from +\exfile{sample-people.tex} need to be renamed to reflect the +different category label: +\begin{codeenv} +\cs{newcommand}*\marg{\postlinkhook{person}}{\comment{} + \cs{glsxtrifwasfirstuse} + \marg{\comment{} + \cs{ifglshasfield}\marg{\field{user3}}\marg{\cs{glslabel}}\comment{} + \marg{\cs{space}(\cs{glscurrentfieldvalue})}\comment{} + \marg{}\comment{} + }\comment{} + \marg{}\comment{} +} +\strut +\cs{newcommand}*\marg{\postnamehook{person}}\marg{\comment{} + \cs{ifglshasfield}\marg{\field{user3}}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{\cs{space}(\cs{glscurrentfieldvalue})}\comment{} + \marg{}\comment{} +} +\strut +\cs{newcommand}*\marg{\postdeschook{person}}\marg{\comment{} + \cs{ifglshasfield}\marg{\field{user1}}\marg{\cs{glscurrententrylabel}} + \marg{\comment{born} + \cs{space}(\cs{glscurrentfieldvalue}\cs{comma}-{}-\cs{comma}\comment{} + \cs{ifglshasfield}\marg{\field{user2}}\marg{\cs{glscurrententrylabel}} + \marg{\comment{died} + \cs{glscurrentfieldvalue} + }\comment{} + \marg{}\comment{} + )\comment{} + }\comment{} + \marg{}\comment{} +} +\end{codeenv} +The other \ext{bib} files that require locale sorting can now be +loaded, but remember that the abbreviation style settings must be +set first since this resource set includes abbreviations: +\begin{codeenv} +\cs{setabbreviationstyle}\oarg{bacteria}\marg{\abbrstyle{long-only-short-only}} +\cs{setabbreviationstyle}\oarg{markuplanguage}\marg{\abbrstyle{long-short-desc}} +\strut +\cs{renewcommand}*\marg{\cs{glsxtrlongshortdescname}}\marg{\comment{} + \cs{protect}\cs{glsabbrvfont}\marg{\cs{the}\cs{glsshorttok}}\cs{space} + \glsxtrparen{\glslongfont{\the\glslongtok}}% +} +\end{codeenv} +Now the resource set can be loaded: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[bacteria,markuplanguages,vegetables, + minerals,animals,books,films]{src}, + \csopt[\fieldfmt{identifier}=\field{category}]{field-aliases}, + \csopt[same as category]{type}, + \csopt[false]{save-locations} +} +\end{codeenv} +The semantic markup command and attributes are as for +\exfile{sample-multi1.tex}: +\begin{codeenv} +\cs{newcommand}\marg{\cmd{bacteriafont}}[1]\marg{\cs{emph}\marg{\idx{param}1}} +\cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{textformat}}\marg{bacteriafont} +\cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{glossnamefont}}\marg{bacteriafont} +\cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{glossdescfont}}\marg{bacteriafont} +\cs{glssetcategoryattribute}\marg{markuplanguage}\marg{\catattr{glossdesc}}\marg{firstuc} +\end{codeenv} +Similarly for the books: +\begin{codeenv} +\cs{newcommand}\marg{\cmd{bookfont}}[1]\marg{\cs{emph}\marg{\idx{param}1}} +\cs{glssetcategoryattribute}\marg{book}\marg{\catattr{textformat}}\marg{bookfont} +\cs{glssetcategoryattribute}\marg{book}\marg{\catattr{glossnamefont}}\marg{bookfont} +\end{codeenv} +(as for \exfile{sample-media.tex}) and for films: +\begin{codeenv} +\cs{newcommand}\marg{\cmd{filmfont}}[1]\marg{\cs{emph}\marg{\idx{param}1}} +\cs{glssetcategoryattribute}\marg{film}\marg{\catattr{textformat}}\marg{filmfont} +\cs{glssetcategoryattribute}\marg{film}\marg{\catattr{glossnamefont}}\marg{filmfont} +\end{codeenv} + +Next come the chemical formulae: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[chemicalformula]{src}, + \csopt[chemical=symbol]{entry-type-aliases}, + \csopt[ + \fieldfmt{identifier}=\field{category}, + \fieldfmt{formula}=\field{name}, + \fieldfmt{chemicalname}=\field{description} + ]{field-aliases}, + \csopt[chemical]{type}, + \csopt{set-widest}, + \csopt[letternumber-case]{sort}, + \csopt[\field{name}]{symbol-sort-fallback}, + \csopt[false]{save-locations} +} +\end{codeenv} +and the \idxpl{SIunit}, which are now combined into a single +glossary: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[baseunits,derivedunits]{src}, + \csopt[\fieldfmt{measurement}=\field{symbol},\fieldfmt{unit}=\field{symbol}]{entry-type-aliases}, + \csopt[ + \fieldfmt{unitname}=\field{description}, + \fieldfmt{unitsymbol}=\field{symbol}, + \fieldfmt{measurement}=\field{name} + ]{field-aliases}, + \csopt[measurement]{category}, + \csopt[measurement]{type}, + \csopt{set-widest}, + \csopt[\field{name}]{symbol-sort-fallback}, + \csopt[false]{save-locations} +} +\end{codeenv} +Here the \field{name} field is obtained from the custom +\fieldfmt{measurement} field. Since this contains a word, the +default locale sort is appropriate. I've locally redefined +\ics{glsxtralttreeSymbolDescLocation} to place the symbol in +parentheses after the description: +\begin{codeenv} +\cs{printunsrtglossary*}\oarg{\printglossopt[measurement]{type},\printglossopt[alttree]{style},\printglossopt{nogroupskip}} +\marg{\comment{} + \cs{renewcommand}\marg{\cs{glsxtralttreeSymbolDescLocation}}[2]\marg{\comment{} + \cs{glossentrydesc}\marg{\idx{param}1}\comment{} + \cs{ifglshassymbol}\marg{\idx{param}1}\marg{\cs{space}(\cs{glossentrysymbol}\marg{\idx{param}1})}\marg{}\comment{} + \cs{glspostdescription} + \cs{glsxtrAltTreePar} + }\comment{} +} +\end{codeenv} + +The base units are replicated in the \code{baseunit} glossary, this +time with the \field{name} field obtained from the custom +\fieldfmt{unitsymbol} field. This means that I need to find a way to +prevent duplicate labels. The simplest method is to use +\csopt{duplicate-label-suffix}: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[baseunits]{src}, + \csopt[unit=symbol]{entry-type-aliases}, + \csopt[ + \fieldfmt{unitname}=\field{description}, + \fieldfmt{unitsymbol}=\field{name} + ]{field-aliases}, + \csopt[measurement]{category}, + \csopt[baseunit]{type}, + \csopt[.copy]{duplicate-label-suffix}, + \csopt[\field{name}]{symbol-sort-fallback}, + \csopt[false]{save-locations} +} +\end{codeenv} +I can't use \csopt{set-widest} here as it won't pick up the modified +label and will instead use the label from the original entry. +Instead I've used \cs{glsFindWidestTopLevelName} to find it: +\begin{codeenv} +\cs{printunsrtglossary*}\oarg{\printglossopt[baseunit]{type},\printglossopt[alttree]{style},\printglossopt{nogroupskip}} +\marg{\comment{} + \cs{glsFindWidestTopLevelName}\oarg{baseunit}\comment{} +} +\end{codeenv} + +The text symbols from \exfile{miscsymbols.bib} are all loaded in a +single \idx{resourceset}, where the \field{type} field can be +obtained from the \field{category}, which in turns is obtained from +the custom \fieldfmt{identifier} field. Since \bibgls\ doesn't +recognise any of the symbol commands, I'm sorting according to the +\field{description} field. (Even if \bibgls\ could determine a +Unicode value for each of the symbols, sorting by the description +makes more sense in this case.) +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[miscsymbols]{src}, + \csopt[ + \fieldfmt{identifier}=\field{category}, + \fieldfmt{icon}=\field{name}, + \fieldfmt{icondescription}=\field{description} + ]{field-aliases}, + \csopt[icon=symbol]{entry-type-aliases}, + \csopt[same as category]{type}, + \csopt[\field{description}]{sort-field}, + \csopt[false]{save-locations}, + \csopt{set-widest} +} +\end{codeenv} + +Finally, all recorded and cross-referenced terms are needed for the +index. This includes entries that have already been defined in the +earlier \idxpl{resourceset} (so a guard against duplicates is +necessary) but it also includes entries from the \exfile{terms.bib} +file that haven't yet been dealt with. I'd like the index to start +with a \idx{symbolgroup} containing the icons from +\exfile{miscsymbols.bib}. This needs to be dealt with separately from +the rest of the index to keep them together in a single group: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[miscsymbols]{src}, + \csopt[recorded no deps]{selection}, + \csopt[.copy]{duplicate-label-suffix}, + \csopt[icon=index]{entry-type-aliases}, + \csopt[ + \fieldfmt{identifier}=\field{category}, + \fieldfmt{icondescription}=\field{symbol}, + \fieldfmt{icon}=\field{name} + ]{field-aliases}, + \csopt[index]{type}, + \csopt[\field{symbol}]{sort-field}, + \csopt[glssymbols]{group} +} +\end{codeenv} +Since I know that there are no parents or cross-references in this +set of entries I've used \csopt[recorded no deps]{selection} to skip +the dependency checks. In this \idx{resourceset}, the \field{name} +field has the symbol command (obtained from the custom +\fieldfmt{icon} field), and the \field{symbol} field has the symbol +description (obtained from the custom \fieldfmt{icondescription} +field), which is used as the sort field. I've set the \field{group} +label to \code{glssymbols}, which keeps all these entries in a +single group and the title will be obtained from +\ics{glssymbolsgroupname}. + +Before loading the final \idx{resourceset} \ics{glsxtrlongshortdescname} needs +to be changed +so that the abbreviations using the \abbrstyle{long-short-desc} +style (that is, the abbreviations with the \field{category} set to +\code{markuplanguage}) have the \field{name} field set to +\meta{long} (\meta{short}): +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{glsxtrlongshortdescname}}\marg{\comment{} + \cs{protect}\cs{glslongfont}\marg{\cs{the}\cs{glslongtok}}\cs{space} + \cs{glsxtrparen}\marg{\cs{glsabbrvfont}\marg{\cs{the}\cs{glsshorttok}}}\comment{} +} +\end{codeenv} +The \abbrstyle{long-only-short-only} style has a similar command, +but it was only introduced to \sty{glossaries-extra} version 1.25: +\begin{codeenv} +\cs{renewcommand}*\marg{\ics{glsxtronlyname}}{\comment{} + \cs{protect}\cs{glsabbrvonlyfont}\marg{\cs{the}\cs{glslongtok}}\comment{} +} +\end{codeenv} + +The abbreviations all need to be sorted according to the long form: +\begin{codeenv} +\csopt[\field{long}]{abbreviation-sort-fallback} +\end{codeenv} +The custom entry types and fields again need to be aliased +\begin{codeenv} +\csopt[ + chemical=index, + measurement=entry, + unit=dualentry, + icon=index +]{entry-type-aliases}, +\csopt[ + \fieldfmt{identifier}=\field{category}, + \fieldfmt{formula}=\field{symbol}, + \fieldfmt{chemicalname}=\field{name}, + \fieldfmt{unitname}=\field{description}, + \fieldfmt{unitsymbol}=\field{symbol}, + \fieldfmt{measurement}=\field{name}, + \fieldfmt{icon}=\field{symbol}, + \fieldfmt{icondescription}=\field{name} + ]{field-aliases} +\end{codeenv} +The chemical formulae and icons are now defined using +\atentry{index} with the \field{name} field set to a word form +(chemical name and icon description). This means +they're appropriate for alphabetical sorting. (Both \atentry{entry} +and \atentry{symbol} require the \field{description} field, which is +why I've aliased \atentryfmt{chemical} and \atentryfmt{icon} +to \atentry{index} here.) The custom \atentryfmt{measurement} entry +type has a \field{description} field (obtained from +\fieldfmt{unitname}), so that's aliased to \atentry{entry} as again +the \field{name} field is suitable for alphabetical sorting. + +I've aliased \atentryfmt{unit} to \atentry{dualentry} +rather than \atentry{symbol} as I want both the unit name and the +measurement in the index and I've combined their location lists: +\begin{codeenv} +\csopt[both]{combine-dual-locations} +\end{codeenv} +Both primary and dual entries need to go in the \code{index} +glossary: +\begin{codeenv} +\csopt[index]{type}, +\csopt[index]{dual-type} +\end{codeenv} + +All \ext{bib} files used in the previous \idxpl{resourceset} are needed +as well as the \exfile{terms.bib} file: +\begin{codeenv} +\csopt[terms,bacteria,markuplanguages,vegetables,minerals, + animals,chemicalformula,baseunits,derivedunits,people, + films,books,miscsymbols]{src} +\end{codeenv} +but this time I also want to select entries that haven't been +recorded but have a cross-reference to a recorded entry: +\begin{codeenv} +\csopt{selection}[recorded and deps and see] +\end{codeenv} +Again it's necessary to provide a way to avoid duplicate entry +labels, which can be done with +\begin{codeenv} +\csopt[.copy]{duplicate-label-suffix}, +\end{codeenv} +as above. However, this will cause the cross-references (from the +\field{alias} fields) to link to the glossary rather than the index. +This may or may not confuse the reader. For consistency, it may be +more suitable to have the cross-reference in the index link to the +aliased entry in the index rather than in the glossary. I've +therefore instead used: +\begin{codeenv} + \csopt[idx.]{label-prefix}, + \csopt[idx.]{record-label-prefix}, +\end{codeenv} +This means that the entries defined in \exfile{terms.bib} need to be +referenced with this prefix. + +All instances of \cs{gls} will link to the original entry, so all +entries except for those in the \exfile{terms.bib} file will link to +the relevant glossary. Those in the \exfile{terms.bib} file will +link to the index. It's possible to disable the hyperlinks for those +entries, but the reader may find it useful to jump to the index to +look up other locations for that entry in the document. + +To deal with the identical book and film titles, I'm again using the +\field{category} to resolve identical sort values: +\begin{codeenv} +\csopt[\field{category}]{identical-sort-action} +\end{codeenv} +For the people who have a \field{first} field, I've decided that +this would be more appropriate for the index as it's more compact +than the \field{name}, so here I've done the reverse to earlier and copied the +\field{first} field (if supplied) into the \field{name} field, but +since the \field{name} field is already provided the override +setting needs to be on: +\begin{codeenv} +\csopt{replicate-override}, +\csopt[\field{first}=\field{name}]{replicate-fields} +\end{codeenv} +As with \exfile{sample-people.tex} I've provided some custom +commands to make it easier to locally redefine \gls{sortname} and +\gls{sortvonname}: +\begin{codeenv} +\cs{newcommand}*\marg{\cmd{swaptwo}}[2]\marg{\idx{param}2, \idx{param}1} +\cs{newcommand}*\marg{\cmd{swapthree}}[3]\marg{\idx{param}2 \idx{param}3, \idx{param}1} +\end{codeenv} +I've redefined \ics{glsxtrbookindexname} in a similar manner to +\exfile{sample-multi1.tex} but it has some modifications: +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\comment{} + \cs{glossentryname}\marg{\idx{param}1}\comment{} + \cs{ifglshassymbol}\marg{\idx{param}1}\comment{} + \marg{\comment{} + \cs{glsifcategory}\marg{\idx{param}1}\marg{chemical}\comment{} + \marg{, \cs{glossentrysymbol}\marg{\idx{param}1}}\comment{} + \marg{\cs{space}(\cs{glossentrynameother}\marg{\idx{param}1}\marg{\field{symbol}})}\comment{} + }\comment{} + \marg{\comment{} + \cs{glsifcategory}\marg{\idx{param}1}\marg{film}\comment{} + \marg{\cs{cs.space}(film)}\comment{} + \marg{}\comment{} + }\comment{} +} +\end{codeenv} +This appends \qt{(film)} to film names. I've chosen this method +rather than using the \idx{postnamehook} as I only want this in the +index and not in the list of films. + +For some of the entries that are referenced in the document, I've +appended information in parentheses: +\begin{codeenv} +\cs{gls}\marg{Al2SO43} (\ics{glsdesc}\marg{Al2SO43}) +\end{codeenv} +This is all right for odd instances, but if this always needs to be done +on first use, then it's better to use the \idx{postlinkhook}, which +is what I've done for the icons for comparison: +\begin{codeenv} +\cs{newcommand}*\marg{\postlinkhook{mediacontrol}}\marg{\comment{} + \ics{glsxtrpostlinkAddDescOnFirstUse} +} +\strut +\cs{newcommand}*\marg{\postlinkhook{information}}\marg{\comment{} + \cs{glsxtrpostlinkAddDescOnFirstUse} +} +\strut +\cs{newcommand}*\marg{\postlinkhook{weather}}\marg{\comment{} + \cs{glsxtrpostlinkAddDescOnFirstUse} +} +\end{codeenv} + +I've also provided some custom commands to make it easier to reference +entries without worrying about the prefixes: +\begin{codeenv} +\cs{newcommand}\marg{\csfmt{unit}}\marg{\ics{glssymbol}} +\cs{newcommand}\marg{\csfmt{measurement}}\marg{\cs{gls}} +\gls{glsxtrnewgls}\marg{film.}\marg{\csfmt{film}} +\end{codeenv} + +As with \exfile{sample-multi1.tex}, it would be useful to include +the page where the entries are defined in their corresponding lists. +Again this can be done by redefining the general purpose +non-category post-name hook \ics{glsextrapostnamehook}: +\begin{codeenv} +\cs{newcommand}*\marg{\cs{glsextrapostnamehook}}[1]\marg{\comment{} + \cs{glsadd}\oarg{\glsaddopt[\encap{hyperbf}]{format}}\marg{\idx{param}1}\comment{} +} +\end{codeenv} +This needs resetting before the index, since it's redundant to +record an entry in the index. This will require an extra +\bibgls+\LaTeX\ system call as this code can't be performed until +the glossaries have been created. + +The complete document code is listed below. The document build is: +\begin{verbatim} +pdflatex sample-multi2 +bib2gls --group --break-space sample-multi2 +pdflatex sample-multi2 +bib2gls --group --break-space sample-multi2 +pdflatex sample-multi2 +\end{verbatim} +The resulting document is shown in \figureref{fig:sample-multi2.pdf}, +\figureref{fig:sample-multi2.pdf2} and \figureref{fig:sample-multi2.pdf3}. + +\lstinputlisting[firstline=5]{../examples/sample-multi2.tex} + +\begin{figure} +\figcontents +{\pdftwocol{../examples/sample-multi2.pdf}{4}} +{\caption{\filefmt{sample-multi2.pdf} (pages~1 to~4)}} +{fig:sample-multi2.pdf} +\end{figure} + +\begin{figure} +\figcontents +{\pdftwocol[5]{../examples/sample-multi2.pdf}{8}} +{\caption{\filefmt{sample-multi2.pdf} (pages~5 to 8)}} +{fig:sample-multi2.pdf2} +\end{figure} + +\begin{figure} +\figcontents +{\pdftwocol[9]{../examples/sample-multi2.pdf}{12}} +{\caption{\filefmt{sample-multi2.pdf} (pages~9 and 12)}} +{fig:sample-multi2.pdf3} +\end{figure} + +\printstyoptsummary +\printcommandsummary +%\printcommandtopic + +\bibliographystyle{plain} +\bibliography{bib2gls-cite} + +\renewcommand*{\glsxtrbookindexsubname}[1]{% + \glsifcategory{#1}{command}% + {% + \glsxtrifhasfield{useri}{#1}% + {\glossentrynameother{#1}{useri}}% + {\glossentryname{#1}}% + }% + {\glossentryname{#1}}% +} +\renewcommand*{\glsxtrbookindexprelocation}[1]{% + \glsxtrifhasfield{location}{#1}% + {\nobreak\cleaders\hbox to .44em{\hss\textcolor{lightgray}{.}\hss}\hfill}% + {\glsxtrprelocation}% +} +\renewcommand{\printunsrtglossaryentryprocesshook}[1]{% + \glsxtrifhasfield*{progenitor}{#1}{\printunsrtglossaryskipentry}{}% +} +\renewcommand*{\unicodecategoryfmt}[1]{\textsf{#1}} +\printunsrtglossary[type=index] +\end{document} diff --git a/support/bib2gls/src/convertgls2bib.pod b/support/bib2gls/src/convertgls2bib.pod new file mode 100644 index 0000000000..d5617dc00e --- /dev/null +++ b/support/bib2gls/src/convertgls2bib.pod @@ -0,0 +1,94 @@ +=head1 SYNOPSIS + +B<convertgls2bib> [I<option>]+ I<auxfile> + +=head1 DESCRIPTION + +Converts a B<.tex> file containing glossary definitions using +commands like B<\newglossaryentry> and B<\newacronym> to +a B<.bib> file in the format required for B<bib2gls>. + +=head1 OPTIONS + +=over 4 + +=item B<--help> or B<-h> + +Display help message and exit. + +=item B<--version> or B<-v> + +Display version information and exit. + +=item B<--silent> + +Suppress all messages except for errors. + +=item B<--verbose> + +Display messages. + +=item B<--debug> + +Display debugging messages. + +=item B<--texenc> I<name> + +Set the character encoding to I<name> for the input B<.tex> files. + +=item B<--bibenc> I<name> + +Set the character encoding to I<name> for the output B<.bib> files. + +=item B<--ignore-sort> + +Ignore the B<sort> field (default). + +=item B<--no-ignore-sort> + +Don't ignore the B<sort> field. + +=item B<--space-sub> I<value> + +Substitute spaces in labels with I<value>. + +=item B<--locale> I<lang tag> + +Use the language resource files associated with the given language +tag I<lang tag>. If there isn't an appropriate file, the B<en> +(English) file will be used. + +=back + +=head1 REQUIRES + +Java 7 and a TeX distribution. + +=head1 LICENSE + +License GPLv3+: GNU GPL version 3 or later +<http://gnu.org/licenses/gpl.html> +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. + +=head1 RECOMMENDED READING + +The bib2gls manual: + + texdoc bib2gls + +The glossaries-extra manual: + + texdoc glossaries-extra + +The glossaries manual: + + texdoc glossaries + +=head1 AUTHOR + +Nicola L. C. Talbot, +L<http://www.dickimaw-books.com/> + +=cut + |