diff options
Diffstat (limited to 'Master/texmf-dist/source/support')
| -rw-r--r-- | Master/texmf-dist/source/support/bib2gls/src/bib2gls-begin.tex | 5589 | ||||
| -rw-r--r-- | Master/texmf-dist/source/support/bib2gls/src/bib2gls-cite.bib | 25 | ||||
| -rw-r--r-- | Master/texmf-dist/source/support/bib2gls/src/bib2gls-src.zip | bin | 145301 -> 148576 bytes | |||
| -rw-r--r-- | Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib | 2740 | ||||
| -rw-r--r-- | Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex | 2453 | ||||
| -rw-r--r-- | Master/texmf-dist/source/support/bib2gls/src/gls2bib-src.zip | bin | 21988 -> 22027 bytes | |||
| -rw-r--r-- | Master/texmf-dist/source/support/bib2gls/src/texparser-src.zip | bin | 789935 -> 795469 bytes |
7 files changed, 9688 insertions, 1119 deletions
diff --git a/Master/texmf-dist/source/support/bib2gls/src/bib2gls-begin.tex b/Master/texmf-dist/source/support/bib2gls/src/bib2gls-begin.tex new file mode 100644 index 00000000000..b705a748509 --- /dev/null +++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls-begin.tex @@ -0,0 +1,5589 @@ +% arara: xelatex +% arara: bib2gls: {group: on} +% arara: bibtex +% arara: xelatex +% arara: bib2gls if found ("log", "has not been defined") +% arara: xelatex if found ("log", "has not been defined") +% arara: xelatex 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{datetime2} +\usepackage{siunitx} +\usepackage{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}% +} + +\GlsXtrLoadResources[ + src={bib2gls}, + max-loc-diff=3, + entry-type-aliases={dualindexentry=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}}}} + +\newenvironment{result}% +{% + \renewcommand{\glslinkpresetkeys}{\setkeys{glslink}{hyper=false,local}}% + \glsresetentrycounter + \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}} +\newenvironment{codeenv} + {% + \renewcommand{\glslinkpresetkeys}{\setkeys{glslink}{noindex}}% + \def\cmd{\char`\\}% + \def\comment##1{\textcolor{comment}{\%\ ##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}}% + \begin{flushleft}\textcolor{lightgray}{\hrulefill}\par\nopagebreak + \medskip\nopagebreak + \ttfamily\obeylines\frenchspacing\@vobeyspaces} + {\nopagebreak\textcolor{lightgray}{\hrulefill}% + \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} + +\newcommand{\ext}{\gls} + +\newcommand*{\iext}[1]{% + \glsxtrtitleorpdforheading{\idx{#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]{#2}}{#2}% +} + +\newcommand*{\glostyle}[1]{% + \texorpdfstring{\idx{glostyle.#1}}{#1}% +} + +\newcommand*{\catattr}[1]{% + \texorpdfstring{\idx{#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}{\cs} + +\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 +} + +\newenvironment{important}{% + \setlength{\fboxrule}{4pt}% + \setlength\borderedboxwidth{\linewidth}% + \addtolength\borderedboxwidth{-2\fboxsep}% + \addtolength\borderedboxwidth{-2\fboxrule}% + \begin{lrbox}{\borderedboxcontents}% + \begin{minipage}{\borderedboxwidth}% + \raggedright + \setlength\parindent{1em}% + \noindent\ignorespaces +}% +{% + \end{minipage}% + \end{lrbox}% + \par\vskip10pt\noindent + \fcolorbox{red}{white}{\usebox{\borderedboxcontents}}\par\vskip10pt + \noindent\ignorespacesafterend +} + +\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}). + +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 +\cmd{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}. + +\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. +\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}). + +\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. 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 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 the sixth field 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 defined 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. 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. + +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{} + \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{} + \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 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 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}) 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 table of contents, 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{robust}, \idx{fragile} and \idx{expandable} commands. +In general, it's better not to use commands like \gls{gls} in +headings or captions (see \sectionref{sec:headings}) and 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 switch this feature off 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}). + +If you only want \gls{gls} to show the short form but not the long +form, use one of the \code{-nolong} styles (such as +\abbrstyle{short-nolong}). If you only want the +long form and not the short form, use one of the \code{-noshort} +styles (such as \abbrstyle{long-noshort}). If you want only the long +form on \idx{firstuse} and only the short form subsequently +then use one of the \code{-only} styles, such as +\abbrstyle{long-only-short-only}. + +If you want a 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}}. + +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. + +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{Plural Abbreviations} +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} + +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. +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{\gls[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} + +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{\gls[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}. + +\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 (as 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} + +\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 table of contents 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 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. The sub-group +heading is displayed by some styles, such as the +\glostyle{indexgroup} style. 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} + +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 a 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} setting 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 table of contents. 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{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}{hierarchical.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 table of contents 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 table of contents 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 table of contents now +includes \code{\gls{gls}\marg{html}}. Since the table of contents +occurs at the start of the document, this is now the \idx{firstuse} +of \code{html}, so the full form is shown in the table of contents, +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 table of contents 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 table of contents: +\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 +table of contents 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 table of contents, +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 table of contents. If you don't want this, +you can defer making these modifications until after the table of +contents. Alternatively, use: +\nosecformatdef{glsxtrRevertTocMarks} +which makes \gls{glsxtrifinmark} expand to \meta{false} in the table +of contents. 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{doublequotechar}) +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{doublequotechar} 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} + \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 the document changes 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} + +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. + +\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/Master/texmf-dist/source/support/bib2gls/src/bib2gls-cite.bib b/Master/texmf-dist/source/support/bib2gls/src/bib2gls-cite.bib index da1a2047b4b..4e0b1560036 100644 --- a/Master/texmf-dist/source/support/bib2gls/src/bib2gls-cite.bib +++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls-cite.bib @@ -4,14 +4,21 @@ author = "Nicola Talbot", title = "The \sty{glossaries} package", note = {\url{https://ctan.org/pkg/glossaries}}, - year = 2017 + year = 2018 } @misc{glossaries-extra, author = "Nicola Talbot", title = "The \sty{glossaries-extra} package", note = {\url{https://ctan.org/pkg/glossaries-extra}}, - year = 2017 + year = 2018 +} + +@misc{accsupp, + author = "Heiko Oberdiek", + title = "The \sty{accsupp} package", + note = {\url{https://ctan.org/pkg/accsupp}}, + year = 2018 } @misc{tex.sx, @@ -78,6 +85,20 @@ System Property}, year = 2018 } +@misc{gallery, + author = {Nicola Talbot}, + title = {{Dickimaw Books} Gallery}, + note = {\url{https://www.dickimaw-books.com/gallery/}}, + year = 2018 +} + +@misc{glossarystylesgallery, + author = {Nicola Talbot}, + title = {Gallery (All Styles Provided by \sty{glossaries})}, + note = {\url{https://www.dickimaw-books.com/gallery/glossaries-styles/}}, + year = 2018 +} + @inbook{iterationtips, author = "Nicola L. C. Talbot", title = "{\LaTeX} for Administrative Work", diff --git a/Master/texmf-dist/source/support/bib2gls/src/bib2gls-src.zip b/Master/texmf-dist/source/support/bib2gls/src/bib2gls-src.zip Binary files differindex 9e7fa0e837b..f1a37da9094 100644 --- a/Master/texmf-dist/source/support/bib2gls/src/bib2gls-src.zip +++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls-src.zip diff --git a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib index 32d6885d164..ab94db210f5 100644 --- a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib +++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib @@ -1,6 +1,8 @@ % Encoding: UTF-8 -@preamble{"\providecommand{\dhyphen}{-}"} +@preamble{"\providecommand{\dhyphen}{-} +\providecommand{\csfmt}[1]{\texttt{\glsbackslash #1}}% +\providecommand{\derivfn}[1]{f'(#1)}"} @abbreviation{IETF, short = {IETF}, @@ -34,6 +36,12 @@ category={common} } +@abbreviation{ASCII, + short = {ASCII}, + long = {American Standard Code for Information Interchange}, + category={common} +} + @dualindexentry{bibglsnewentry, name={\csfmt{bib\-gls\-new\-entry}}, user1={\margm{label}\margm{options}\margm{name}\margm{description}}, @@ -62,6 +70,13 @@ category={command} } +@dualindexentry{bibglsnewindexplural, + name={\csfmt{bib\-gls\-new\-index\-plural}}, + user1={\margm{label}\margm{options}\margm{name}}, + description={defines terms provided with \gls[noindex]{dual.entry.index}}, + category={command} +} + @dualindexentry{bibglsnewabbreviation, name={\csfmt{bib\-gls\-new\-abbreviation}}, user1={\margm{label}\margm{options}\margm{short}\margm{long}}, @@ -276,7 +291,7 @@ @dualindexentry{bibglsseesep, name={\csfmt{bib\-gls\-see\-sep}}, user1={}, - description={separator between \gls[noindex]{dual.field.see} + description={separator between \field{see} cross-references and location list}, category={command} } @@ -284,14 +299,14 @@ @dualindexentry{bibglsaliassep, name={\csfmt{bib\-gls\-alias\-sep}}, user1={}, - description={separator between \gls[noindex]{dual.field.alias} + description={separator between \field{alias} cross-reference and location list}, category={command} } @dualindexentry{bibglsseealsosep, name={\csfmt{bib\-gls\-see\-also\-sep}}, user1={}, - description={separator between \gls[noindex]{dual.field.seealso} + description={separator between \field{seealso} cross-references and location list}, category={command} } @@ -440,6 +455,13 @@ given label}, category={command} } +@dualindexentry{bibglssetlastgrouptitle, + name={\csfmt{bib\-gls\-set\-last\-group\-title}}, + user1={\margm{cs}\margm{group specs}}, + description={sets the last group title}, + category={command} +} + @dualindexentry{bibglssetlettergrouptitle, name={\csfmt{bib\-gls\-set\-letter\-group\-title}}, user1={\marg{\margm{title}\margm{letter}\margm{id}\margm{type}}}, @@ -807,11 +829,22 @@ name}, @dualindexentry{longnewglossaryentry, name={\csfmt{long\-new\-glossary\-entry}}, user1={\margm{label}\margm{\keyvallist}\margm{description}}, - description={defines a new glossary entry}, + description={defines a new glossary entry and appends + \csfmt{leavemode}\csfmt{unskip}\gls{nopostdesc} at the end of +\meta{description}}, note={provided by \styfmt{glossaries}}, category={command} } +@index{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}}, + note={provided by \styfmt{glossaries-extra} v1.12+}, + category={command} +} + @dualindexentry{provideglossaryentry, name={\csfmt{provide\-glossary\-entry}}, user1={\margm{label}\margm{\keyvallist}}, @@ -834,8 +867,9 @@ name}, name={\csfmt{new\-term}}, user1={\oargm{\keyvallist}\margm{label}}, description={defines a new glossary entry where the - \gls[noindex]{dual.field.description} field defaults to empty}, - note={provided by \styfmt{glossaries}}, + \field{description} field defaults to empty}, + note={provided by the \styfmt{glossaries}'s \styopt{index} package +option}, category={command} } @@ -851,7 +885,7 @@ name}, name={\csfmt{new\-acronym}}, user1={\oargm{\keyvallist}\margm{label}\margm{short}\margm{long}}, description={defines a new abbreviation with the - \gls[noindex]{dual.field.category} set to \code{acronym}}, + \field{category} set to \code{acronym}}, note={provided by \styfmt{glossaries}}, category={command} } @@ -860,7 +894,8 @@ name}, name={\csfmt{gls\-xtr\-new\-symbol}}, user1={\oargm{\keyvallist}\margm{label}\margm{symbol}}, description={defines a new symbol}, - note={provided by \styfmt{glossaries-extra}}, + note={provided by \styfmt{glossaries-extra}'s \styopt{symbols} +package option}, category={command} } @@ -868,7 +903,8 @@ name}, name={\csfmt{gls\-xtr\-new\-number}}, user1={\oargm{\keyvallist}\margm{label}}, description={defines a new number}, - note={provided by \styfmt{glossaries-extra}}, + note={provided by \styfmt{glossaries-extra}'s \styopt{numbers} +package option}, category={command} } @@ -918,6 +954,27 @@ location obtained from the \field{indexcounter} field}, category={command} } +@dualindexentry{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 \gls{GlsXtrDualField}}, + note={internal command provided by + \styfmt{glossaries-extra-bib2gls} v1.30+}, + category={command} +} + +@dualindexentry{GlsXtrDualField, + name={\csfmt{Gls\-Xtr\-Dual\-Field}}, + user1={}, + description={The field used to store the dual label. This defaults + to \gls{field.dual} but will need to be redefined if a different + value is given by \csopt{dual-field}}, + note={internal command provided by + \styfmt{glossaries-extra-bib2gls} v1.30+}, + category={command} +} + @dualindexentry{glsxtrfmt, name={\csfmt{gls\-xtr\-fmt}}, user1={\oargm{options}\margm{label}\margm{text}}, @@ -946,6 +1003,18 @@ location obtained from the \field{indexcounter} field}, category={command} } +@index{glsxtrfmtdisplay, + name={\csfmt{gls\-xtr\-fmt\-display}}, + user1={\margm{cs-name}\margm{text}\oargm{insert}}, + description={used by \cs{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 \gls{glsxtrfmt} and the final optional argument of the +starred version \gls{glsxtrfmt*}}, + note={provided by \styfmt{glossaries-extra}}, + category={command} +} + @dualindexentry{glsxtrresourcefile, name={\csfmt{gls\-xtr\-resource\-file}}, user1={\oargm{options}\margm{filename}}, @@ -1087,6 +1156,27 @@ location obtained from the \field{indexcounter} field}, parent={resourceoptions} } +@dualindexentry{opt.sort-replace, + name={\csoptfmt{sort\dhyphen replace}}, + user1={\meta{list}}, + category={resourceoption}, + parent={resourceoptions} +} + +@dualindexentry{opt.dual-sort-replace, + name={\csoptfmt{dual\dhyphen sort\dhyphen replace}}, + user1={\meta{list}}, + category={resourceoption}, + parent={resourceoptions} +} + +@dualindexentry{opt.secondary-sort-replace, + name={\csoptfmt{secondary\dhyphen sort\dhyphen replace}}, + user1={\meta{list}}, + category={resourceoption}, + parent={resourceoptions} +} + @dualindexentry{opt.action, name={\csoptfmt{action}}, user1={\meta{value}}, @@ -1440,7 +1530,7 @@ field\dhyphen locale}}, @dualindexentry{opt.save-child-count, name={\csoptfmt{save\dhyphen child\dhyphen count}}, - user1={\meta{value}}, + user1={\meta{boolean}}, category={resourceoption}, parent={resourceoptions} } @@ -2287,7 +2377,7 @@ cs}\margm{Glspl-like cs}}, name={\csfmt{gls\-no\-idx\-display\-loc}}, user1={\margm{prefix}\margm{counter}\margm{format}\margm{location}}, description={handler used to display the number list stored in - the \gls[noindex]{dual.field.loclist} field}, + the \field{loclist} field}, note={provided by \styfmt{glossaries}}, category={command} } @@ -2307,6 +2397,27 @@ cs}\margm{Glspl-like cs}}, description={adds the given item to the given field that contains an \styfmt{etoolbox} internal list}, note={provided by \styfmt{glossaries-extra} v1.12+}, + seealso={glsxtrfieldifinlist,glsxtrfieldforlistloop,glsxtrfielddolistloop}, + category={command} +} + +@index{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}, + note={provided by \styfmt{glossaries-extra} v1.12+}, + seealso={glsxtrfieldxifinlist,glsxtrfieldlistadd,glsxtrfieldforlistloop,glsxtrfielddolistloop}, + category={command} +} + +@index{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}, + note={provided by \styfmt{glossaries-extra} v1.12+}, + seealso={glsxtrfieldifinlist}, category={command} } @@ -2326,6 +2437,14 @@ cs}\margm{Glspl-like cs}}, category={command} } +@index{Alpha, + name={\csfmt{Alpha}}, + user1={}, + description={Greek letter alpha $\Alpha$}, + note={provided by \styfmt{glossaries-extra-bib2gls}}, + category={command} +} + @index{bigoperatornamefmt, name={\csfmt{bigoperatornamefmt}}, user1={\margm{text}}, @@ -2511,12 +2630,24 @@ cs}\margm{Glspl-like cs}}, parent={fileformats} } +@index{toc, + name={\extfmt{toc}}, + category={fileformat}, + parent={fileformats} +} + @index{glstex, name={\extfmt{glstex}}, category={fileformat}, parent={fileformats} } +@index{bbl, + name={\extfmt{bbl}}, + category={fileformat}, + parent={fileformats} +} + @index{applications, name={applications}, text={applications} @@ -2821,6 +2952,12 @@ cs}\margm{Glspl-like cs}}, parent={packages} } +@index{slantsc, + name={\styfmt{slantsc}}, + category={package}, + parent={packages} +} + @index{babel, name={\styfmt{babel}}, category={package}, @@ -2875,17 +3012,40 @@ cs}\margm{Glspl-like cs}}, parent={packages} } +@index{soul, + name={\styfmt{soul}}, + category={package}, + parent={packages} +} + +@index{xcolor, + name={\styfmt{xcolor}}, + category={package}, + parent={packages} +} + @index{tracklang, name={\styfmt{tracklang}}, category={package}, parent={packages} } +@index{accsupp, + name={\styfmt{accsupp}}, + category={package}, + parent={packages} +} + @index{stringconcat, name={\code{\#} (string concatenation)}, text={\code{\#}} } +@index{atchar, + name={\code{@} (bib entry identifier)}, + text={\code{@}} +} + @index{param, name={\code{\#} (parameter)}, text={\code{\#}} @@ -2981,7 +3141,11 @@ cs}\margm{Glspl-like cs}}, } @index{cs.circum, - name={\csfmt{\char`\^}} + name={\csfmt{\char`\^}}, + user1={\margm{character}}, + description={puts a circumflex accent over \meta{character}}, + note={kernel command}, + category={command} } @index{mshiftchar, @@ -3022,6 +3186,10 @@ cs}\margm{Glspl-like cs}}, text={\code{\glstildechar}} } +@index{doublequotechar, + name = {\code{"}} +} + @index{cs.tilde, name={\csfmt{\glstildechar}} } @@ -3056,9 +3224,28 @@ cs}\margm{Glspl-like cs}}, category={command} } +@index{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={provided by \styfmt{etoolbox}}, + category={command} +} + @index{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={provided by \styfmt{etoolbox}}, + category={command} +} + +@index{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={provided by \styfmt{etoolbox}}, @@ -3074,6 +3261,15 @@ cs}\margm{Glspl-like cs}}, category={command} } +@index{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={provided by \styfmt{etoolbox}}, + category={command} +} + @index{marvosym, name={\styfmt{marvosym}}, category={package}, @@ -3113,67 +3309,119 @@ cs}\margm{Glspl-like cs}}, category={environment} } +@index{env.tabular, + name={\envfmt{tabular}}, + category={environment} +} + +@index{supertabular, + name={\styfmt{supertabular}}, + category={package}, + parent={packages} +} + +@index{env.supertabular, + name={\envfmt{supertabular}}, + category={environment} +} + +@index{env.theglossary, + name={\envfmt{theglossary}}, + category={environment} +} + @index{abbreviationstyles, name={abbreviation styles}, text={abbreviation style} } +@index{long-noshort, + name={\abbrstylefmt{long\dhyphen noshort}}, + category={abbreviationstyle}, + parent={abbreviationstyles} +} + @index{long-noshort-desc, - name={\abbrstylefmt{long-noshort-desc}}, + name={\abbrstylefmt{long\dhyphen noshort\dhyphen desc}}, category={abbreviationstyle}, parent={abbreviationstyles} } @index{long-short-sc, - name={\abbrstylefmt{long-short-sc}}, + name={\abbrstylefmt{long\dhyphen short\dhyphen sc}}, category={abbreviationstyle}, parent={abbreviationstyles} } @index{long-short-sm, - name={\abbrstylefmt{long-short-sm}}, + name={\abbrstylefmt{long\dhyphen short\dhyphen sm}}, + category={abbreviationstyle}, + parent={abbreviationstyles} +} + +@index{long-short-em, + name={\abbrstylefmt{long\dhyphen short\dhyphen em}}, category={abbreviationstyle}, parent={abbreviationstyles} } @index{long-short, - name={\abbrstylefmt{long-short}}, + name={\abbrstylefmt{long\dhyphen short}}, category={abbreviationstyle}, parent={abbreviationstyles} } @index{long-short-user, - name={\abbrstylefmt{long-short-user}}, + name={\abbrstylefmt{long\dhyphen short\dhyphen user}}, category={abbreviationstyle}, parent={abbreviationstyles} } @index{long-short-desc, - name={\abbrstylefmt{long-short-desc}}, + name={\abbrstylefmt{long\dhyphen short\dhyphen desc}}, category={abbreviationstyle}, parent={abbreviationstyles} } @index{long-short-user-desc, - name={\abbrstylefmt{long-short-user-desc}}, + name={\abbrstylefmt{long\dhyphen short\dhyphen user\dhyphen desc}}, + category={abbreviationstyle}, + parent={abbreviationstyles} +} + +@index{long-hyphen-short-hyphen, + name={\abbrstylefmt{long\dhyphen hyphen\dhyphen short\dhyphen +hyphen}}, category={abbreviationstyle}, parent={abbreviationstyles} } @index{long-postshort-user-desc, - name={\abbrstylefmt{long-postshort-user-desc}}, + name={\abbrstylefmt{long\dhyphen postshort\dhyphen user\dhyphen desc}}, category={abbreviationstyle}, parent={abbreviationstyles} } @index{short-long, - name={\abbrstylefmt{short-long}}, + name={\abbrstylefmt{short\dhyphen long}}, + category={abbreviationstyle}, + parent={abbreviationstyles} +} + +@index{short-nolong, + name={\abbrstylefmt{short\dhyphen nolong}}, + category={abbreviationstyle}, + parent={abbreviationstyles} +} + +@index{short-sc-nolong, + name={\abbrstylefmt{short\dhyphen sc\dhyphen nolong}}, category={abbreviationstyle}, parent={abbreviationstyles} } @index{long-only-short-only, - name={\abbrstylefmt{long-only-short-only}}, + name={\abbrstylefmt{long\dhyphen only\dhyphen short\dhyphen only}}, category={abbreviationstyle}, parent={abbreviationstyles} } @@ -3201,6 +3449,30 @@ cs}\margm{Glspl-like cs}}, parent={glossarystyle} } +@index{glostyle.tree, + name={\glostylefmt{tree}}, + category={glossarystyle}, + parent={glossarystyle} +} + +@index{glostyle.treegroup, + name={\glostylefmt{treegroup}}, + category={glossarystyle}, + parent={glossarystyle} +} + +@index{glostyle.treenoname, + name={\glostylefmt{treenoname}}, + category={glossarystyle}, + parent={glossarystyle} +} + +@index{glostyle.treenonamegroup, + name={\glostylefmt{treenonamegroup}}, + category={glossarystyle}, + parent={glossarystyle} +} + @index{glostyle.alttree, name={\glostylefmt{alttree}}, category={glossarystyle}, @@ -3272,68 +3544,164 @@ cs}\margm{Glspl-like cs}}, text={category attribute} } +@index{attribute, + name = {attributes}, + text = {attribute}, + alias = {categoryattribute} +} + @index{recordcount, - name={\catattrfmt{recordcount}}, + name={\catattrfmt{record\-count}}, category={categoryattribute}, parent={categoryattribute} } @index{glossname, - name={\catattrfmt{glossname}}, + name={\catattrfmt{gloss\-name}}, category={categoryattribute}, parent={categoryattribute} } @index{glossnamefont, - name={\catattrfmt{glossnamefont}}, + name={\catattrfmt{gloss\-name\-font}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@index{glossdesc, + name={\catattrfmt{gloss\-desc}}, category={categoryattribute}, parent={categoryattribute} } @index{glossdescfont, - name={\catattrfmt{glossdescfont}}, + name={\catattrfmt{gloss\-desc\-font}}, category={categoryattribute}, parent={categoryattribute} } @index{textformat, - name={\catattrfmt{textformat}}, + name={\catattrfmt{text\-format}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@index{headuc, + name={\catattrfmt{headuc}}, category={categoryattribute}, parent={categoryattribute} } @index{aposplural, - name={\catattrfmt{aposplural}}, + name={\catattrfmt{apos\-plural}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@index{accessaposplural, + name={\catattrfmt{access\-apos\-plural}}, category={categoryattribute}, parent={categoryattribute} } @index{noshortplural, - name={\catattrfmt{noshortplural}}, + name={\catattrfmt{no\-short\-plural}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@index{accessnoshortplural, + name={\catattrfmt{access\-no\-short\-plural}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@index{nameshortaccess, + name={\catattrfmt{name\-short\-access}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@index{firstshortaccess, + name={\catattrfmt{first\-short\-access}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@index{textshortaccess, + name={\catattrfmt{text\-short\-access}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@index{markwords, + name={\catattrfmt{mark\-words}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@index{markshortwords, + name={\catattrfmt{mark\-short\-words}}, category={categoryattribute}, parent={categoryattribute} } @index{targeturl, - name={\catattrfmt{targeturl}}, + name={\catattrfmt{target\-url}}, category={categoryattribute}, parent={categoryattribute} } @index{targetname, - name={\catattrfmt{targetname}}, + name={\catattrfmt{target\-name}}, category={categoryattribute}, parent={categoryattribute} } @index{externallocation, - name={\catattrfmt{externallocation}}, + name={\catattrfmt{external\-location}}, category={categoryattribute}, parent={categoryattribute} } @index{discardperiod, - name={\catattrfmt{discardperiod}}, + name={\catattrfmt{discard\-period}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@index{pluraldiscardperiod, + name={\catattrfmt{plural\-discard\-period}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@index{retainfirstuseperiod, + name={\catattrfmt{retain\-first\-use\-period}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@index{insertdots, + name={\catattrfmt{insert\-dots}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@index{accessinsertdots, + name={\catattrfmt{access\-insert\-dots}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@index{tagging, + name={\catattrfmt{tagging}}, + category={categoryattribute}, + parent={categoryattribute} +} + +@index{nohyperfirst, + name={\catattrfmt{no\-hyper\-first}}, category={categoryattribute}, parent={categoryattribute} } @@ -3358,6 +3726,16 @@ cs}\margm{Glspl-like cs}}, category={counter} } +@index{ctr.glossaryentry, + name={\counterfmt{glossaryentry}}, + category={counter} +} + +@index{ctr.glossarysubentry, + name={\counterfmt{glossarysubentry}}, + category={counter} +} + @index{labelprefixes, name={label prefixes}, text={label prefix}, @@ -3387,134 +3765,680 @@ cs}\margm{Glspl-like cs}}, text={package option} } -@index{styopt.record, +@dualindexentry{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 performed by + \bibgls) and \styoptfmt{alsoindex} (\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} } -@index{styopt.automake, - name={\styoptfmt{automake}}, +@dualindexentry{styopt.accsupp, + name={\styoptfmt{accsupp}}, + description={load the \sty{glossaries-accsupp} package to provide + accessibility support}, + package={glossaries,glossaries-extra}, category={packageoption}, parent={packageoptions} } -@index{styopt.shortcuts, - name={\styoptfmt{shortcuts}}, +@dualindexentry{styopt.abbreviations, + name={\styoptfmt{abbreviations}}, + description={creates the \code{abbreviations} glossary}, + package={glossaries-extra}, category={packageoption}, parent={packageoptions} } -@index{styopt.accsupp, - name={\styoptfmt{accsupp}}, +@dualindexentry{styopt.symbols, + name={\styoptfmt{symbols}}, + package={glossaries,glossaries-extra}, + description={defines the \code{symbols} glossary; with + \styfmt{glossaries-extra} additionally defines + \gls{glsxtrnewsymbol}}, category={packageoption}, parent={packageoptions} } -@index{styopt.abbreviations, - name={\styoptfmt{abbreviations}}, +@dualindexentry{styopt.numbers, + name={\styoptfmt{numbers}}, + package={glossaries,glossaries-extra}, + description={defines the \code{numbers} glossary; with + \styfmt{glossaries-extra} additionally defines + \gls{glsxtrnewnumber}}, category={packageoption}, parent={packageoptions} } -@index{styopt.symbols, - name={\styoptfmt{symbols}}, +@dualindexentry{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} } -@index{styopt.numbers, - name={\styoptfmt{numbers}}, +@dualindexentry{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} +} + +@dualindexentry{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} +} + +@dualindexentry{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} } -@index{styopt.sort, - name={\styoptfmt{sort}}, +@dualindexentry{styopt.postdot, + name={\styoptfmt{postdot}}, + package={glossaries-extra}, + description={equivalent to \styopt[dot]{postpunc}}, category={packageoption}, parent={packageoptions} } -@index{styopt.undefaction, - name={\styoptfmt{undefaction}}, +@dualindexentry{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})} +} + +@dualindexentry{styopt.indexcounter, + name={\styoptfmt{index\-counter}}, + description={creates the \gls{ctr.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} +} + +@dualindexentry{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)} +} + +@dualindexentry{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} +} + +@dualindexentry{styopt.stylemods, + name={\styoptfmt{stylemods}}, + user1={\meta{value}}, + description={load the \gls{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} } -@index{styopt.nomain, +@dualindexentry{styopt.nowarn, + name={\styoptfmt{nowarn}}, + package={glossaries}, + category={packageoption}, + parent={packageoptions}, + description={suppresses all \styfmt{glossaries}-related warnings} +} + +@dualindexentry{styopt.nolangwarn, + name={\styoptfmt{nolangwarn}}, + package={glossaries}, + category={packageoption}, + parent={packageoptions}, + description={suppresses warnings generated by missing language modules} +} + +@dualindexentry{styopt.noredefwarn, + name={\styoptfmt{noredefwarn}}, + package={glossaries}, + category={packageoption}, + parent={packageoptions}, + description={suppresses warnings if overriding glossary commands + provided by another class or package} +} + +@dualindexentry{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})} +} + +@dualindexentry{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})} +} + +@dualindexentry{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} +} + +@dualindexentry{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} +} + +@dualindexentry{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} +} + +@dualindexentry{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})} +} + +@dualindexentry{styopt.notranslate, + name={\styoptfmt{notranslate}}, + package={glossaries}, + category={packageoption}, + parent={packageoptions}, + description={equivalent to \styopt[false]{translate}} +} + +@dualindexentry{styopt.nohypertypes, + name={\styoptfmt{nohypertypes}}, + user1={\meta{list}}, + package={glossaries}, + category={packageoption}, + parent={packageoptions}, + description={suppress hyperlinks for the listed glossary types} +} + +@dualindexentry{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)} +} + +@dualindexentry{styopt.indexonlyfirst, + name={\styoptfmt{indexonlyfirst}}, + user1={\meta{boolean}}, + package={glossaries}, + category={packageoption}, + parent={packageoptions}, + description={if true, only performs indexing on first use} +} + +@dualindexentry{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)} +} + +@dualindexentry{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 table of contents} +} + +@dualindexentry{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 TOC entry} +} + +@dualindexentry{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 \gls{chapter} has been defined. The starred or + unstarred version is determined by \gls{styopt.numberedsection}} +} + +@dualindexentry{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 upper case with \cs{MakeTextUppercase}} +} + +@dualindexentry{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} +} + +@dualindexentry{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})} +} + +@dualindexentry{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}} +} + +@dualindexentry{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}} +} + +@dualindexentry{styopt.style, + name={\styoptfmt{style}}, + user1={\meta{name}}, + package={glossaries}, + description={sets the default glossary style to \meta{name}}, category={packageoption}, parent={packageoptions} } -@index{styopt.nonumberlist, - name={\styoptfmt{nonumberlist}}, +@dualindexentry{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} } -@index{styopt.nogroupskip, - name={\styoptfmt{nogroupskip}}, +@dualindexentry{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} } -@index{styopt.xindy, - name={\styoptfmt{xindy}}, +@dualindexentry{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} } -@index{styopt.nopostdot, - name={\styoptfmt{nopostdot}}, +@dualindexentry{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} +} + +@dualindexentry{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 \gls{styopt.stylemods} or with \gls{usepackage})}, category={packageoption}, parent={packageoptions} } -@index{styopt.postdot, - name={\styoptfmt{postdot}}, +@dualindexentry{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} +} + +@dualindexentry{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 + \gls{printglossary}, \gls{printunsrtglossary} and + \gls{printnoidxglossary} is boolean); with \bibgls\ you can use + \csopt[false]{save-locations} instead}, category={packageoption}, parent={packageoptions} } -@index{styopt.counter, +@dualindexentry{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} +} + +@dualindexentry{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} } -@index{styopt.indexcounter, - name={\styoptfmt{index\-counter}}, +@dualindexentry{styopt.nogroupskip, + name={\styoptfmt{nogroupskip}}, + user1={\meta{boolean}}, + description={if true, suppresses the visual separation between + letter groups}, + package={glossaries}, category={packageoption}, parent={packageoptions} } -@index{styopt.index, - name={\styoptfmt{index}}, +@dualindexentry{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} } -@index{styopt.nostyles, - name={\styoptfmt{nostyles}}, +@dualindexentry{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} } -@index{styopt.stylemods, - name={\styoptfmt{stylemods}}, +@dualindexentry{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} } -@index{styopt.style, - name={\styoptfmt{style}}, +@dualindexentry{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} } -@index{styopt.section, - name={\styoptfmt{section}}, +@dualindexentry{styopt.xindygloss, + name={\styoptfmt{xindygloss}}, + package={glossaries}, + category={packageoption}, + parent={packageoptions}, + note={not relevant with \bibgls}, + description={equivalent to \styopt[\empty]{xindy}} +} + +@dualindexentry{styopt.xindynoglsnumbers, + name={\styoptfmt{xindynoglsnumbers}}, + package={glossaries}, + category={packageoption}, + parent={packageoptions}, + note={not relevant with \bibgls}, + description={equivalent to \styopt[glsnumbers=false]{xindy}} +} + +@dualindexentry{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} +} + +@dualindexentry{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}} +} + +@dualindexentry{styopt.acronyms, + name={\styoptfmt{acronyms}}, + package={glossaries}, + category={packageoption}, + parent={packageoptions}, + description={equivalent to \styopt[true]{acronym}} +} + +@dualindexentry{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})} +} + +@dualindexentry{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 \gls{ac} + shortcuts that use \styfmt{glossaries-extra}'s new abbreviation + commands), \styoptfmt{abbreviations}\extstyopt\ (provides \gls{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} +} + +@dualindexentry{styopt.index, + name={\styoptfmt{index}}, + package={glossaries}, + description={defines the \code{index} glossary and \gls{newterm}}, category={packageoption}, parent={packageoptions} } @@ -3726,7 +4650,7 @@ cs}\margm{Glspl-like cs}}, @dualindexentry{field.duallong, name={\fieldfmt{duallong}}, description={The long form of a dual - abbreviation mapped by \gls{dual.entry.dualabbreviation}.}, + abbreviation mapped by \atentry{dualabbreviation}.}, note={provided by \appfmt{bib2gls}}, category={bib2glsfield}, parent={fields} @@ -3735,7 +4659,7 @@ cs}\margm{Glspl-like cs}}, @dualindexentry{field.duallongplural, name={\fieldfmt{duallongplural}}, description={The plural long form of a dual - abbreviation mapped by \gls{dual.entry.dualabbreviation}.}, + abbreviation mapped by \atentry{dualabbreviation}.}, note={provided by \appfmt{bib2gls}}, category={bib2glsfield}, parent={fields} @@ -3744,7 +4668,7 @@ cs}\margm{Glspl-like cs}}, @dualindexentry{field.dualshort, name={\fieldfmt{dualshort}}, description={The short form of a dual - abbreviation mapped by \gls{dual.entry.dualabbreviation}.}, + abbreviation mapped by \atentry{dualabbreviation}.}, note={provided by \appfmt{bib2gls}}, category={bib2glsfield}, parent={fields} @@ -3753,7 +4677,7 @@ cs}\margm{Glspl-like cs}}, @dualindexentry{field.dualshortplural, name={\fieldfmt{dualshortplural}}, description={The plural short form of a dual abbreviation - mapped by \gls{dual.entry.dualabbreviation}.}, + mapped by \atentry{dualabbreviation}.}, note={provided by \appfmt{bib2gls}}, category={bib2glsfield}, parent={fields} @@ -3761,7 +4685,7 @@ cs}\margm{Glspl-like cs}}, @dualindexentry{field.prefix, name={\fieldfmt{prefix}}, - description={The prefix associated with the \gls[noindex]{dual.field.text} + description={The prefix associated with the \field{text} field.}, note={provided by \styfmt{glossaries-prefix}}, category={prefixfield}, @@ -3770,7 +4694,7 @@ cs}\margm{Glspl-like cs}}, @dualindexentry{field.prefixfirst, name={\fieldfmt{prefixfirst}}, - description={The prefix associated with the \gls[noindex]{dual.field.first} + description={The prefix associated with the \field{first} field.}, note={provided by \styfmt{glossaries-prefix}}, category={prefixfield}, @@ -3780,7 +4704,7 @@ field.}, @dualindexentry{field.prefixfirstplural, name={\fieldfmt{prefixfirstplural}}, description={The prefix associated with the - \gls[noindex]{dual.field.firstplural} field.}, + \field{firstplural} field.}, note={provided by \styfmt{glossaries-prefix}}, category={prefixfield}, parent={fields} @@ -3789,7 +4713,7 @@ field.}, @dualindexentry{field.prefixplural, name={\fieldfmt{prefixplural}}, description={The prefix associated with the - \gls[noindex]{dual.field.plural} field.}, + \field{plural} field.}, note={provided by \styfmt{glossaries-prefix}}, category={prefixfield}, parent={fields} @@ -3797,7 +4721,7 @@ field.}, @dualindexentry{field.access, name={\fieldfmt{access}}, - description={The replacement text for the \gls[noindex]{dual.field.name} field.}, + description={The replacement text for the \field{name} field.}, note={provided by \styfmt{glossaries-accsupp}}, category={accessfield}, parent={fields} @@ -3806,7 +4730,7 @@ field.}, @dualindexentry{field.descriptionaccess, name={\fieldfmt{descriptionaccess}}, description={The replacement text for the - \gls[noindex]{dual.field.description} field.}, + \field{description} field.}, note={provided by \styfmt{glossaries-accsupp}}, category={accessfield}, parent={fields} @@ -3815,7 +4739,7 @@ field.}, @dualindexentry{field.descriptionpluralaccess, name={\fieldfmt{descriptionpluralaccess}}, description={The replacement text for the - \gls[noindex]{dual.field.descriptionplural} field.}, + \field{descriptionplural} field.}, note={provided by \styfmt{glossaries-accsupp}}, category={accessfield}, parent={fields} @@ -3823,7 +4747,7 @@ field.}, @dualindexentry{field.firstaccess, name={\fieldfmt{firstaccess}}, - description={The replacement text for the \gls[noindex]{dual.field.first} field.}, + description={The replacement text for the \field{first} field.}, note={provided by \styfmt{glossaries-accsupp}}, category={accessfield}, parent={fields} @@ -3832,7 +4756,7 @@ field.}, @dualindexentry{field.firstpluralaccess, name={\fieldfmt{firstpluralaccess}}, description={The replacement text for the - \gls[noindex]{dual.field.firstplural} field.}, + \field{firstplural} field.}, note={provided by \styfmt{glossaries-accsupp}}, category={accessfield}, parent={fields} @@ -3840,7 +4764,7 @@ field.}, @dualindexentry{field.longaccess, name={\fieldfmt{longaccess}}, - description={The replacement text for the \gls[noindex]{dual.field.long} field.}, + description={The replacement text for the \field{long} field.}, note={provided by \styfmt{glossaries-accsupp}}, category={accessfield}, parent={fields} @@ -3849,7 +4773,7 @@ field.}, @dualindexentry{field.longpluralaccess, name={\fieldfmt{longpluralaccess}}, description={The replacement text for the - \gls[noindex]{dual.field.longplural} field.}, + \field{longplural} field.}, note={provided by \styfmt{glossaries-accsupp}}, category={accessfield}, parent={fields} @@ -3857,7 +4781,7 @@ field.}, @dualindexentry{field.pluralaccess, name={\fieldfmt{pluralaccess}}, - description={The replacement text for the \gls[noindex]{dual.field.plural} field.}, + description={The replacement text for the \field{plural} field.}, note={provided by \styfmt{glossaries-accsupp}}, category={accessfield}, parent={fields} @@ -3865,7 +4789,7 @@ field.}, @dualindexentry{field.shortaccess, name={\fieldfmt{shortaccess}}, - description={The replacement text for the \gls[noindex]{dual.field.short} field.}, + description={The replacement text for the \field{short} field.}, note={provided by \styfmt{glossaries-accsupp}}, category={accessfield}, parent={fields} @@ -3874,7 +4798,7 @@ field.}, @dualindexentry{field.shortpluralaccess, name={\fieldfmt{shortpluralaccess}}, description={The replacement text for the - \gls[noindex]{dual.field.shortplural} field.}, + \field{shortplural} field.}, note={provided by \styfmt{glossaries-accsupp}}, category={accessfield}, parent={fields} @@ -3882,7 +4806,7 @@ field.}, @dualindexentry{field.symbolaccess, name={\fieldfmt{symbolaccess}}, - description={The replacement text for the \gls[noindex]{dual.field.symbol} field.}, + description={The replacement text for the \field{symbol} field.}, note={provided by \styfmt{glossaries-accsupp}}, category={accessfield}, parent={fields} @@ -3891,7 +4815,7 @@ field.}, @dualindexentry{field.symbolpluralaccess, name={\fieldfmt{symbolpluralaccess}}, description={The replacement text for the - \gls[noindex]{dual.field.symbolplural} field.}, + \field{symbolplural} field.}, note={provided by \styfmt{glossaries-accsupp}}, category={accessfield}, parent={fields} @@ -3900,7 +4824,7 @@ field.}, @dualindexentry{field.textaccess, name={\fieldfmt{textaccess}}, description={The replacement text for the - \gls[noindex]{dual.field.text} field.}, + \field{text} field.}, note={provided by \styfmt{glossaries-accsupp}}, category={accessfield}, parent={fields} @@ -3920,6 +4844,15 @@ field.}, parent={internalfields} } +@dualindexentry{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} +} + @dualindexentry{field.indexcounter, name={\fieldfmt{index\-counter}}, description={Stores the location corresponding to the matching @@ -4008,6 +4941,15 @@ field.}, parent={internalfields} } +@dualindexentry{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} +} + @dualindexentry{field.sort, name={\fieldfmt{sort}}, description={The sort value obtained by the comparator.}, @@ -4088,7 +5030,7 @@ field.}, @dualindexentry{field.desc, name={\fieldfmt{desc}}, - description={Corresponds to \gls[noindex]{dual.field.description} key.}, + description={Corresponds to \field{description} key.}, note={internal field set by \styfmt{glossaries}}, category={baseinternalfield}, parent={internalfields} @@ -4096,7 +5038,7 @@ field.}, @dualindexentry{field.descplural, name={\fieldfmt{descplural}}, - description={Corresponds to \gls[noindex]{dual.field.descriptionplural} key.}, + description={Corresponds to \field{descriptionplural} key.}, note={internal field set by \styfmt{glossaries}}, category={baseinternalfield}, parent={internalfields} @@ -4104,7 +5046,7 @@ field.}, @dualindexentry{field.firstpl, name={\fieldfmt{firstpl}}, - description={Corresponds to \gls[noindex]{dual.field.firstplural} key.}, + description={Corresponds to \field{firstplural} key.}, note={internal field set by \styfmt{glossaries}}, category={baseinternalfield}, parent={internalfields} @@ -4137,7 +5079,7 @@ field.}, @dualindexentry{field.longpl, name={\fieldfmt{longpl}}, - description={Corresponds to \gls[noindex]{dual.field.longplural} key.}, + description={Corresponds to \field{longplural} key.}, note={internal field set by \styfmt{glossaries}}, category={baseinternalfield}, parent={internalfields} @@ -4189,7 +5131,7 @@ field.}, @dualindexentry{field.shortpl, name={\fieldfmt{shortpl}}, - description={Corresponds to \gls[noindex]{dual.field.shortplural} key.}, + description={Corresponds to \field{shortplural} key.}, note={internal field set by \styfmt{glossaries}}, category={baseinternalfield}, parent={internalfields} @@ -4197,7 +5139,7 @@ field.}, @dualindexentry{field.sortvalue, name={\fieldfmt{sortvalue}}, - description={Original \gls[noindex]{dual.field.sort} value + description={Original \field{sort} value (before sanitizing and escaping special characters).}, note={internal field set by \styfmt{glossaries}}, category={baseinternalfield}, @@ -4215,7 +5157,7 @@ field.}, @dualindexentry{field.useri, name={\fieldfmt{useri}}, - description={Corresponds to \gls[noindex]{dual.field.user1} key.}, + description={Corresponds to \field{user1} key.}, note={internal field set by \styfmt{glossaries}}, category={baseinternalfield}, parent={internalfields} @@ -4223,7 +5165,7 @@ field.}, @dualindexentry{field.userii, name={\fieldfmt{userii}}, - description={Corresponds to \gls[noindex]{dual.field.user2} key.}, + description={Corresponds to \field{user2} key.}, note={internal field set by \styfmt{glossaries}}, category={baseinternalfield}, parent={internalfields} @@ -4231,7 +5173,7 @@ field.}, @dualindexentry{field.useriii, name={\fieldfmt{useriii}}, - description={Corresponds to \gls[noindex]{dual.field.user3} key.}, + description={Corresponds to \field{user3} key.}, note={internal field set by \styfmt{glossaries}}, category={baseinternalfield}, parent={internalfields} @@ -4239,7 +5181,7 @@ field.}, @dualindexentry{field.useriv, name={\fieldfmt{useriv}}, - description={Corresponds to \gls[noindex]{dual.field.user4} key.}, + description={Corresponds to \field{user4} key.}, note={internal field set by \styfmt{glossaries}}, category={baseinternalfield}, parent={internalfields} @@ -4247,7 +5189,7 @@ field.}, @dualindexentry{field.userv, name={\fieldfmt{userv}}, - description={Corresponds to \gls[noindex]{dual.field.user5} key.}, + description={Corresponds to \field{user5} key.}, note={internal field set by \styfmt{glossaries}}, category={baseinternalfield}, parent={internalfields} @@ -4255,7 +5197,7 @@ field.}, @dualindexentry{field.uservi, name={\fieldfmt{uservi}}, - description={Corresponds to \gls[noindex]{dual.field.user6} key.}, + description={Corresponds to \field{user6} key.}, note={internal field set by \styfmt{glossaries}}, category={baseinternalfield}, parent={internalfields} @@ -4318,6 +5260,12 @@ field.}, parent={entrytypes} } +@dualindexentry{entry.indexplural, + name={\atentryfmt{indexplural}}, + category={entrytype}, + parent={entrytypes} +} + @dualindexentry{entry.abbreviation, name={\atentryfmt{abbreviation}}, category={entrytype}, @@ -4806,6 +5754,14 @@ field.}, name={ignored record} } +@index{record, + seealso={ignoredrecord} +} + +@index{locationlist, + name = {location list} +} + @index{postlinkhook, name={post-link hook} } @@ -4852,6 +5808,62 @@ field.}, 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{moving-argument, + name={moving argument} +} + +@index{uppercase, + name={upper case} +} + +@index{lowercase, + name={lower case} +} + +@index{case-change, + name = {case change}, + seealso = {uppercase,lowercase} +} + @index{unicodecategories, name={Unicode categories}, text={Unicode category}, @@ -4976,6 +5988,14 @@ field.}, name={\filefmt{sample\dhyphen authors.tex}} } +@dualindexentry{file.sample-citations.tex, + name={\filefmt{sample\dhyphen citations.tex}} +} + +@dualindexentry{file.citations.bib, + name={\filefmt{citations.bib}} +} + @dualindexentry{file.bacteria.bib, name={\filefmt{bacteria.bib}} } @@ -5127,6 +6147,7 @@ field.}, description={iterates over the items the given field, which contains an \styfmt{etoolbox} internal list}, note={provided by \styfmt{glossaries-extra}}, + seealso={glsxtrfieldforlistloop,glsxtrfieldifinlist,glsxtrfieldlistadd}, category={command} } @@ -5137,6 +6158,7 @@ field.}, an \styfmt{etoolbox} internal list, using the given handler}, note={provided by \styfmt{glossaries-extra}, use at least v1.29 to avoid a bug}, + seealso={glsxtrfielddolistloop,glsxtrfieldifinlist,glsxtrfieldlistadd}, category={command} } @@ -5198,7 +6220,16 @@ post-name hook}, name={\csfmt{gls\-entry\-text}}, user1={\margm{label}}, description={expands to the value of the - \gls[noindex]{dual.field.text} field}, + \field{text} field}, + note={provided by \styfmt{glossaries}}, + category={command} +} + +@index{glsentryplural, + name={\csfmt{gls\-entry\-plural}}, + user1={\margm{label}}, + description={expands to the value of the + \field{plural} field}, note={provided by \styfmt{glossaries}}, category={command} } @@ -5207,11 +6238,135 @@ post-name hook}, name={\csfmt{gls\-entry\-name}}, user1={\margm{label}}, description={expands to the value of the - \gls[noindex]{dual.field.name} field}, + \field{name} field}, + note={provided by \styfmt{glossaries}}, + category={command} +} + +@index{Glsentryname, + name={\csfmt{Gls\-entry\-name}}, + user1={\margm{label}}, + description={displays the value of the + \field{name} field with the first character + converted to upper case}, + note={provided by \styfmt{glossaries}}, + category={command} +} + +@index{glsentrydesc, + name={\csfmt{gls\-entry\-desc}}, + user1={\margm{label}}, + description={expands to the value of the + \field{description} field}, + note={provided by \styfmt{glossaries}}, + category={command} +} + +@index{glsentrysymbol, + name={\csfmt{gls\-entry\-symbol}}, + user1={\margm{label}}, + description={expands to the value of the + \field{symbol} field}, note={provided by \styfmt{glossaries}}, category={command} } +@index{glsentryuseri, + name={\csfmt{gls\-entry\-useri}}, + user1={\margm{label}}, + description={expands to the value of the + \field{user1} field}, + note={provided by \styfmt{glossaries}}, + category={command} +} + +@index{glsentryuserii, + name={\csfmt{gls\-entry\-userii}}, + user1={\margm{label}}, + description={expands to the value of the + \field{user2} field}, + note={provided by \styfmt{glossaries}}, + category={command} +} + +@index{glsentryuseriii, + name={\csfmt{gls\-entry\-useriii}}, + user1={\margm{label}}, + description={expands to the value of the + \field{user3} field}, + note={provided by \styfmt{glossaries}}, + category={command} +} + +@index{glsentryuseriv, + name={\csfmt{gls\-entry\-useriv}}, + user1={\margm{label}}, + description={expands to the value of the + \field{user4} field}, + note={provided by \styfmt{glossaries}}, + category={command} +} + +@index{glsentryuserv, + name={\csfmt{gls\-entry\-userv}}, + user1={\margm{label}}, + description={expands to the value of the + \field{user5} field}, + note={provided by \styfmt{glossaries}}, + category={command} +} + +@index{glsentryuservi, + name={\csfmt{gls\-entry\-uservi}}, + user1={\margm{label}}, + description={expands to the value of the + \field{user6} field}, + note={provided by \styfmt{glossaries}}, + category={command} +} + +@index{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}, + note={provided by \styfmt{glossaries-extra}}, + category={command} +} + +@index{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}, + note={provided by \styfmt{glossaries-extra}}, + category={command} +} + +@index{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}, + note={provided by \styfmt{glossaries-extra}}, + category={command} +} + +@index{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}, + note={provided by \styfmt{glossaries-extra} v1.31+}, + category={command} +} + @index{glspluralsuffix, name={\csfmt{gls\-plural\-suffix}}, user1={}, @@ -5248,6 +6403,30 @@ post-name hook}, category={command} } +@index{glsdefpostlink, + name={\csfmt{gls\-def\-post\-link}}, + user1={\margm{category}\margm{definition}}, + description={define the post-link hook for the given category}, + note={provided by \styfmt{glossaries-extra} v1.31+}, + category={command} +} + +@index{glsdefpostname, + name={\csfmt{gls\-def\-post\-name}}, + user1={\margm{category}\margm{definition}}, + description={define the post-name hook for the given category}, + note={provided by \styfmt{glossaries-extra} v1.31+}, + category={command} +} + +@index{glsdefpostdesc, + name={\csfmt{gls\-def\-post\-desc}}, + user1={\margm{category}\margm{definition}}, + description={define the post-description hook for the given category}, + note={provided by \styfmt{glossaries-extra} v1.31+}, + category={command} +} + @index{glsxtrifwasfirstuse, name={\csfmt{glsxtr\-if\-was\-first\-use}}, user1={\margm{true}\margm{false}}, @@ -5260,7 +6439,7 @@ post-name hook}, @index{glslabel, name={\csfmt{glslabel}}, user1={}, - description={only for use in the post-link hooks this + description={only for use in the post-link hooks, this expands to the label of the entry that was last referenced}, note={provided by \styfmt{glossaries}}, category={command} @@ -5276,12 +6455,22 @@ label of the current entry}, category={command} } +@index{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}, + note={provided by \styfmt{glossaries}}, + category={command} +} + @index{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}, - note={provided by \styfmt{glossaries-extra}}, + note={provided by \styfmt{glossaries-extra} v1.12+}, category={command} } @@ -5291,7 +6480,7 @@ label of the current entry}, description={assigns the given \meta{value} to the field identified by \meta{field label} for the entry identified by \meta{entry label}}, - note={provided by \styfmt{glossaries-extra}}, + note={provided by \styfmt{glossaries-extra} v1.12+}, category={command} } @@ -5328,6 +6517,33 @@ label of the current entry}, category={command} } +@index{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}, + note={provided by \styfmt{glossaries-extra} v1.21+}, + category={command} +} + +@index{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)}, + note={provided by \styfmt{glossaries-extra} v1.31+}, + category={command} +} + +@index{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}}, + note={provided by \styfmt{glossaries-extra} v1.31+}, + category={command} +} + @index{ifglshasfield, name={\csfmt{if\-gls\-has\-field}}, user1={\margm{field label}\margm{entry label}\margm{true}\margm{false}}, @@ -5338,6 +6554,99 @@ label of the current entry}, category={command} } +@index{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}}, + note={provided by \styfmt{glossaries}}, + seealso={ifglshasdesc,glsxtrifhasfield,GlsXtrIfFieldUndef}, + category={command} +} + +@index{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}, + note={provided by \styfmt{glossaries}}, + seealso={ifglshassymbol,ifglshasdescsuppressed}, + category={command} +} + +@index{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}}, + note={provided by \styfmt{glossaries}}, + seealso={ifglshasdesc}, + category={command} +} + +@index{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}, + note={provided by \styfmt{glossaries}}, + category={command} +} + +@index{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}, + note={provided by \styfmt{glossaries}}, + category={command} +} + +@index{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}}, + note={provided by \styfmt{glossaries-extra} v1.31+}, + seealso={GlsXtrIfFieldEqNum}, + category={command} +} + +@index{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}}, + note={provided by \styfmt{glossaries-extra} v1.31+}, + seealso={GlsXtrIfFieldNonZero}, + category={command} +} + +@dualindexentry{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}}, + note={provided by \styfmt{glossaries-extra-bib2gls} v1.31+}, + seealso={GlsXtrIfFieldNonZero}, + category={command} +} + @dualindexentry{glsxtrifcustomdiscardperiod, name={\csfmt{gls\-xtr\-if\-custom\-discard\-period}}, user1={\margm{true}\margm{false}}, @@ -5453,25 +6762,25 @@ label of the current entry}, @index{newsym, name={\csfmt{newsym}}, user1={\margm{label}\margm{\keyvallist}\margm{symbol}}, - description={equivalent to \cs{glsxtrnewsymbol}}, + description={equivalent to \gls{glsxtrnewsymbol}}, note={provided by \styfmt{glossaries-extra}'s - \gls{styopt.shortcuts} package option}, + \styopt{shortcuts} package option}, category={command} } @index{newnum, name={\csfmt{newnum}}, user1={\margm{label}\margm{\keyvallist}}, - description={equivalent to \cs{glsxtrnewnumber}}, + description={equivalent to \gls{glsxtrnewnumber}}, note={provided by \styfmt{glossaries-extra}'s -\gls{styopt.shortcuts} package option}, + \styopt{shortcuts} package option}, category={command} } @index{acronymtype, name={\csfmt{acronym\-type}}, user1={}, - description={expands to the default glossary type when using + description={expands to the default acronym glossary type when using \cs{newacronym}}, note={provided by \styfmt{glossaries}}, category={command} @@ -5661,6 +6970,15 @@ label of the current entry}, category={command} } +@index{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}, + note={provided by \styfmt{glossaries-extra} v1.31+}, + category={command} +} + @index{glsadd.thevalue, name={\csoptfmt{thevalue}}, category={commandoption}, @@ -5679,6 +6997,46 @@ label of the current entry}, parent={glsadd} } +@index{glsadd.counter, + name={\csoptfmt{counter}}, + category={commandoption}, + parent={glsadd} +} + +@index{theglossaryentry, + name={\csfmt{theglossaryentry}}, + description={textual representation of the \counter{glossaryentry} +counter, which is defined with the \styopt{entrycounter} option}, + note={provided by \styfmt{glossaries}}, + category={command} +} + +@index{theHglossaryentry, + name={\csfmt{theHglossaryentry}}, + description={hypertarget associated with the \counter{glossaryentry} +counter, which is defined with the \styopt{entrycounter} option}, + note={provided by \styfmt{glossaries}}, + category={command} +} + +@index{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}}, + note={provided by \styfmt{glossaries}}, + category={command} +} + +@index{currentglossary, + name={\csfmt{currentglossary}}, + description={defined within the glossary to the current glossary +type, this has no meaning outside of the glossary list}, + note={provided by \styfmt{glossaries}}, + category={command} +} + @index{frontmatter, name={\csfmt{front\-matter}}, user1={}, @@ -5774,6 +7132,31 @@ hyperlinks enabled otherwise just does \meta{text}}, category={command} } +@index{textbf, + name={\csfmt{textbf}}, + user1={\margm{text}}, + description={displays the given text in bold}, + note={kernel command}, + category={command} +} + +@index{textit, + name={\csfmt{textit}}, + user1={\margm{text}}, + description={displays the given text in italic}, + note={kernel command}, + seealso={emph}, + category={command} +} + +@index{footnote, + name={\csfmt{footnote}}, + user1={\oargm{number}\margm{text}}, + description={displays the given text as a footnote}, + note={kernel command}, + category={command} +} + @index{index, name={\csfmt{index}}, user1={\margm{text}}, @@ -5785,7 +7168,7 @@ by \gls{makeindex} or \gls{xindy}}, } @index{glsignore, - name={\csfmt{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}}, @@ -5833,7 +7216,10 @@ by \gls{makeindex} or \gls{xindy}}, @index{ensuremath, name={\csfmt{ensuremath}}, user1={\margm{maths}}, - description={ensures the argument is in math mode}, + 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}, category={command} } @@ -5996,6 +7382,14 @@ usual delay}, category={command} } +@index{caption, + name={\csfmt{caption}}, + user1={\oargm{list title}\margm{title}}, + description={caption title}, + note={kernel command}, + category={command} +} + @index{boldsymbol, name={\csfmt{boldsymbol}}, user1={\margm{symbol}}, @@ -6066,6 +7460,109 @@ usual delay}, category={command} } +@index{printunsrtglossaryentryprocesshook, + name={\csfmt{print\-unsrt\-glos\-sary\-entry\-process\-hook}}, + user1={\margm{label}}, + description={performed at each iteration of the internal loop used +by \gls{printunsrtglossary}}, + note={provided by \styfmt{glossaries-extra} v1.21+}, + category={command} +} + +@index{printunsrtglossaryskipentry, + name={\csfmt{print\-unsrt\-glos\-sary\-skip\-entry}}, + description={only allowed within + \gls{printunsrtglossaryentryprocesshook} this command + indicates that the current entry should be skipped}, + note={provided by \styfmt{glossaries-extra} v1.21+}, + category={command} +} + +@index{printunsrtglossarypredoglossary, + name={\csfmt{print\-unsrt\-glos\-sary\-pre\-do\-glos\-sary}}, + description={hook performed by \gls{printunsrtglossary}}, + note={provided by \styfmt{glossaries-extra} v1.21+}, + category={command} +} + +@index{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}, + note={provided by \styfmt{glossaries-extra}}, + category={command} +} + +@index{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}}, + note={provided by \styfmt{glossaries-extra}}, + category={command} +} + +@index{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} which should be fully expandable}, + note={provided by \styfmt{glossaries-extra} v1.21+}, + category={command} +} + +@index{printgloss.type, + parent = {printunsrtglossary}, + name = {\csoptfmt{type}}, + category={commandoption}, +} + +@index{printgloss.style, + parent = {printunsrtglossary}, + name = {\csoptfmt{style}}, + category={commandoption}, +} + +@index{printgloss.title, + parent = {printunsrtglossary}, + name = {\csoptfmt{title}}, + category={commandoption}, +} + +@index{printgloss.toctitle, + parent = {printunsrtglossary}, + name = {\csoptfmt{toctitle}}, + category={commandoption}, +} + +@index{printgloss.target, + parent = {printunsrtglossary}, + name = {\csoptfmt{target}}, + category={commandoption}, +} + +@index{printgloss.targetnameprefix, + parent = {printunsrtglossary}, + name = {\csoptfmt{target\-name\-prefix}}, + category={commandoption}, +} + +@index{printgloss.prefix, + parent = {printunsrtglossary}, + name = {\csoptfmt{prefix}}, + category={commandoption}, +} + +@index{printgloss.nonumberlist, + parent = {printunsrtglossary}, + name = {\csoptfmt{no\-number\-list}}, + category={commandoption}, +} + @index{cs.makeglossaries, name={\csfmt{make\-glos\-saries}}, user1={}, @@ -6092,6 +7589,23 @@ usual delay}, category={command} } +@index{printnoidxglossary, + name={\csfmt{print\-noidx\-glos\-sary}}, + user1={\oargm{options}}, + description={uses \TeX\ to sort, collate and list the glossary}, + note={provided by \styfmt{glossaries}}, + category={command} +} + +@index{printnoidxglossaries, + name={\csfmt{print\-noidx\-glos\-saries}}, + user1={}, + description={iterates over all non-ignored defined glossaries + and performs \cs{printnoidxglossary} for each one}, + note={provided by \styfmt{glossaries}}, + category={command} +} + @index{makefirstuc, name={\csfmt{make\-first\-uc}}, user1={\margm{text}}, @@ -6104,16 +7618,25 @@ usual delay}, name={\csfmt{ac}}, user1={\oargm{options}\margm{label}\oargm{insert}}, description={equivalent to \cs{gls}}, - note={provided by \styfmt{glossaries-extra} \gls{styopt.shortcuts} package + note={provided by \styfmt{glossaries-extra} \styopt{shortcuts} package option}, category={command} } +@index{ab, + name={\csfmt{ab}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={equivalent to \cs{gls}}, + note={provided by \styfmt{glossaries-extra} + \styopt[abbreviations]{shortcuts} package option}, + category={command} +} + @index{glsxtrp, name={\csfmt{glsxtrp}}, user1={\margm{field}\margm{label}}, description={displays the given field for the entry given by label}, - note={provided by \styfmt{glossaries-extra}}, + note={provided by \styfmt{glossaries-extra} v1.07+}, category={command} } @@ -6122,7 +7645,7 @@ option}, user1={}, description={expands to the internal label of the field used to store the control sequence name for use with \cs{glsxtrfmt}}, - note={provided by \styfmt{glossaries-extra}}, + note={provided by \styfmt{glossaries-extra} v1.12}, category={command} } @@ -6130,8 +7653,8 @@ option}, name={\csfmt{gls\-xtr\-use\-see}}, user1={\margm{label}}, description={applies \cs{glsseeformat} to the entry's - \gls[noindex]{dual.field.see} field if not empty}, - note={provided by \styfmt{glossaries-extra}}, + \field{see} field if not empty}, + note={provided by \styfmt{glossaries-extra} v1.06+}, category={command} } @@ -6139,8 +7662,8 @@ option}, name={\csfmt{gls\-xtr\-use\-seealso}}, user1={\margm{label}}, description={applies \cs{glsseeformat} to the entry's - \gls[noindex]{dual.field.seealso} field if not empty}, - note={provided by \styfmt{glossaries-extra}}, + \field{seealso} field if not empty}, + note={provided by \styfmt{glossaries-extra} v1.16+}, category={command} } @@ -6148,7 +7671,7 @@ option}, name={\csfmt{gls\-xtr\-set\-alias\-noindex}}, user1={}, description={hooks into the alias \gls{gls.noindex} setting}, - note={provided by \styfmt{glossaries-extra}}, + note={provided by \styfmt{glossaries-extra} v1.12+}, category={command} } @@ -6156,8 +7679,9 @@ option}, 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}, - note={provided by \styfmt{glossaries-extra}}, + given in \meta{xr list} as a list of \qt{see also} +cross-references}, + note={provided by \styfmt{glossaries-extra} v1.16+}, category={command} } @@ -6165,7 +7689,7 @@ option}, name={\csfmt{gls\-xtr\-index\-seealso}}, user1={\margm{label}\margm{xr list}}, description={indexes a \qt{see also} cross-reference}, - note={provided by \styfmt{glossaries-extra}}, + note={provided by \styfmt{glossaries-extra} v1.16+}, category={command} } @@ -6177,6 +7701,15 @@ option}, category={command} } +@index{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}, + note={provided by \styfmt{glossaries-extra} v1.16+}, + category={command} +} + @index{setabbreviationstyle, name={\csfmt{setabbreviationstyle}}, user1={\oargm{category}\margm{style-name}}, @@ -6196,6 +7729,14 @@ defined}, category={command} } +@index{glscapturedgroup, + name={\csfmt{glscapturedgroup}}, + user1={}, + description={expands to \cs{cs.string}\gls{dollarchar}}, + note={provided by \styfmt{glossaries-extra-bib2gls} v1.31+}, + category={command} +} + @index{GlsXtrBibTeXEntryAliases, name={\csfmt{Gls\-Xtr\-Bib\-TeX\-Entry\-Aliases}}, user1={}, @@ -6327,7 +7868,7 @@ packages}, user1={}, description={hook used after the description is displayed in the glossary for entries that have the - \gls[noindex]{dual.field.category} set to \code{abbreviation}}, + \field{category} set to \code{abbreviation}}, note={provided by \styfmt{glossaries-extra}}, category={command} } @@ -6337,7 +7878,7 @@ packages}, user1={}, description={hook used after the description is displayed in the glossary for entries that have the - \gls[noindex]{dual.field.category} set to \code{symbol}}, + \field{category} set to \code{symbol}}, note={provided by \styfmt{glossaries-extra}}, category={command} } @@ -6347,7 +7888,7 @@ packages}, user1={}, description={hook used after the description is displayed in the glossary for entries that have the - \gls[noindex]{dual.field.category} set to \code{general}}, + \field{category} set to \code{general}}, note={provided by \styfmt{glossaries-extra}}, category={command} } @@ -6357,7 +7898,7 @@ packages}, user1={}, description={hook used after the description is displayed in the glossary for entries that have the - \gls[noindex]{dual.field.category} set to \meta{category}}, + \field{category} set to \meta{category}}, note={common category hooks such as \cs{glsxtrpostdescgeneral} are provided by \styfmt{glossaries-extra}, custom categories need the hook defined}, @@ -6369,7 +7910,7 @@ packages}, user1={}, description={hook used after the name is displayed in the glossary for entries that have the - \gls[noindex]{dual.field.category} set to \meta{category}}, + \field{category} set to \meta{category}}, note={user needs to define hook for use with \styfmt{glossaries-extra}}, category={command} @@ -6380,7 +7921,7 @@ packages}, user1={}, description={hook used after commands like \cs{gls} for entries that have the - \gls[noindex]{dual.field.category} set to \meta{category}}, + \field{category} set to \meta{category}}, note={user needs to define hook for use with \styfmt{glossaries-extra}}, category={command} @@ -6400,6 +7941,17 @@ packages}, description={links to the entry's location in the glossary with the given link text without altering the first use flag}, note={provided by \styfmt{glossaries}}, + seealso={glsdisp}, + category={command} +} + +@index{glsdisp, + name={\csfmt{glsdisp}}, + user1={\oargm{options}\margm{label}\oargm{text}}, + description={links to the entry's location in the glossary with + the given link text and marks the entry as having been used}, + note={provided by \styfmt{glossaries}}, + seealso={glslink}, category={command} } @@ -6425,9 +7977,38 @@ packages}, category={command} } +@index{glsxtrfull, + name={\csfmt{glsxtrfull}}, + user1={\oargm{options}\margm{label}}, + description={links to the entry's location 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}, + note={provided by \styfmt{glossaries-extra}}, + category={command} +} + +@index{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}, + note={provided by \styfmt{glossaries-extra} v1.17+}, + category={command} +} + +@index{glsxtrwordsep, + name={\csfmt{glsxtrwordsep}}, + description={used to mark spaces between each word in the long form of an +abbreviation by the \catattr{markwords} attribute}, + note={provided by \styfmt{glossaries-extra} v1.17+}, + category={command} +} + @index{glstext, name={\csfmt{glstext}}, - user1={\oargm{options}\margm{label}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, description={links to the entry's location in the glossary with the link text obtained from the \field{text} field without altering the first use flag}, @@ -6437,7 +8018,7 @@ packages}, @index{glsname, name={\csfmt{glsname}}, - user1={\oargm{options}\margm{label}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, description={links to the entry's location in the glossary with the link text obtained from the \field{name} field without altering the first use flag}, @@ -6447,7 +8028,7 @@ packages}, @index{glsfirst, name={\csfmt{glsfirst}}, - user1={\oargm{options}\margm{label}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, description={links to the entry's location in the glossary with the link text obtained from the \field{first} field without altering the first use flag}, @@ -6457,7 +8038,7 @@ packages}, @index{glssymbol, name={\csfmt{glssymbol}}, - user1={\oargm{options}\margm{label}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, description={links to the entry's location in the glossary with the link text obtained from the \field{symbol} field without altering the first use flag}, @@ -6465,6 +8046,76 @@ packages}, category={command} } +@index{glsdesc, + name={\csfmt{glsdesc}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={links to the entry's location in the glossary with + the link text obtained from the \field{description} field + without altering the first use flag}, + note={provided by \styfmt{glossaries}}, + category={command} +} + +@index{glsuseri, + name={\csfmt{glsuseri}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={links to the entry's location in the glossary with + the link text obtained from the \field{user1} field + without altering the first use flag}, + note={provided by \styfmt{glossaries}}, + category={command} +} + +@index{glsuserii, + name={\csfmt{glsuserii}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={links to the entry's location in the glossary with + the link text obtained from the \field{user2} field + without altering the first use flag}, + note={provided by \styfmt{glossaries}}, + category={command} +} + +@index{glsuseriii, + name={\csfmt{glsuseriii}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={links to the entry's location in the glossary with + the link text obtained from the \field{user3} field + without altering the first use flag}, + note={provided by \styfmt{glossaries}}, + category={command} +} + +@index{glsuseriv, + name={\csfmt{glsuseriv}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={links to the entry's location in the glossary with + the link text obtained from the \field{user4} field + without altering the first use flag}, + note={provided by \styfmt{glossaries}}, + category={command} +} + +@index{glsuserv, + name={\csfmt{glsuserv}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={links to the entry's location in the glossary with + the link text obtained from the \field{user5} field + without altering the first use flag}, + note={provided by \styfmt{glossaries}}, + category={command} +} + +@index{glsuservi, + name={\csfmt{glsuservi}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={links to the entry's location in the glossary with + the link text obtained from the \field{user6} field + without altering the first use flag}, + note={provided by \styfmt{glossaries}}, + category={command} +} + @dualindexentry{rgls, name={\csfmt{rgls}}, user1={\oargm{options}\margm{label}\oargm{insert}}, @@ -6505,10 +8156,10 @@ packages}, name={\csfmt{gls}}, user1={\oargm{options}\margm{label}\oargm{insert}}, description={on first use displays the first use text - (the value of the \gls[noindex]{dual.field.first} field + (the value of the \field{first} field for general entries) and on subsequent use displays the subsequent use text (the value of the - \gls[noindex]{dual.field.text} field + \field{text} field for general entries) where the text is optionally hyperlinked to the relevant place in the glossary}, note={provided by \styfmt{glossaries}}, @@ -6533,6 +8184,24 @@ packages}, parent={gls} } +@index{gls.textformat, + name={\csoptfmt{text\-format}}, + category={commandoption}, + parent={gls} +} + +@index{gls.prefix, + name={\csoptfmt{prefix}}, + category={commandoption}, + parent={gls} +} + +@index{gls.hyperoutside, + name={\csoptfmt{hyperoutside}}, + category={commandoption}, + parent={gls} +} + @index{glspl, name={\csfmt{glspl}}, user1={\oargm{options}\margm{label}\oargm{insert}}, @@ -6558,12 +8227,38 @@ packages}, category={command} } +@index{GLS, + name={\csfmt{GLS}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={as \cs{gls} but converts the link text to upper case}, + note={provided by \styfmt{glossaries}}, + category={command} +} + +@index{GLSpl, + name={\csfmt{GLSpl}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={as \cs{GLS} but shows the plural form}, + note={provided by \styfmt{glossaries}}, + category={command} +} + +@index{pgls, + name={\csfmt{pgls}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={does \meta{prefix}\gls{gls}\oargm{options}\margm{label}\oargm{insert}, + where the \meta{prefix} is obtained from the appropriate prefix + field}, + note={provided by \styfmt{glossaries-prefix}}, + category={command} +} + @index{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}, - note={provided by \styfmt{glossaries}}, + note={provided by \styfmt{glossary-tree}}, category={command} } @@ -6574,7 +8269,17 @@ packages}, wider than the current value}, note={provided by \styfmt{glossaries-extra-stylemods} version 1.23+}, - seealso={glssetwidest}, + seealso={glssetwidest,eglsupdatewidest}, + category={command} +} + +@index{eglsupdatewidest, + name={\csfmt{egls\-update\-widest}}, + user1={\oargm{level}\margm{text}}, + description={as \cs{glsupdatewidest} but expands \meta{text}}, + note={provided by \styfmt{glossaries-extra-stylemods} version +1.23+}, + seealso={glssetwidest,glsupdatewidest}, category={command} } @@ -6615,11 +8320,41 @@ glossaries}, category={command} } +@index{glsabbrvscfont, + name={\csfmt{gls\-abbrv\-sc\-font}}, + user1={\margm{text}}, + description={used with \qt{sc} abbreviation styles to format the +short form using \gls{textsc}}, + note={provided by \styfmt{glossaries-extra} v1.17+}, + category={command} +} + +@index{glsxtrifinmark, + name={\csfmt{gls\-xtr\-if\-in\-mark}}, + user1={\margm{true}\margm{true}}, + description={used by commands like \gls{glsfmtshort}, this expands +to \meta{true} in page headings and the table of contents, + otherwise it expands to \meta{false}}, + note={provided by \styfmt{glossaries-extra} v1.07+}, + category={command} +} + +@index{glsxtrRevertTocMarks, + name={\csfmt{gls\-xtr\-Revert\-Toc\-Marks}}, + description={restores original behaviour of \gls{tableofcontents} + so that \gls{glsxtrifinmark} expands to \meta{false} in the table +of contents}, + note={provided by \styfmt{glossaries-extra} v1.07+}, + category={command} +} + @index{glstreenamefmt, name={\csfmt{gls\-tree\-name\-fmt}}, user1={\margm{text}}, description={used with the tree styles to format the entry's name}, - note={provided by \styfmt{glossary-tree}}, + note={provided by \styfmt{glossary-tree} v4.08+ and redefined by +\styfmt{glossaries-extra-stylemods} v1.31+}, + seealso={glstreegroupheaderfmt,glstreenavigationfmt,glstreedefaultnamefmt}, category={command} } @@ -6628,7 +8363,27 @@ glossaries}, user1={\margm{text}}, description={used with the tree styles to format the group headings}, - note={provided by \styfmt{glossary-tree}}, + note={provided by \styfmt{glossary-tree} v4.22+ and redefined + by \styfmt{glossaries-extra-stylemods} v1.31+}, + category={command} +} + +@index{glstreenavigationfmt, + name={\csfmt{gls\-tree\-navigation\-fmt}}, + user1={\margm{text}}, + description={used with the tree styles to format the navigation +elements}, + note={provided by \styfmt{glossary-tree} v4.22+ and redefined + by \styfmt{glossaries-extra-stylemods} v1.31+}, + category={command} +} + +@index{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}}, + note={provided by \styfmt{glossaries-extra-stylemods} v1.31+}, category={command} } @@ -6695,6 +8450,15 @@ indexing}, category={command} } +@index{Glossentrydesc, + name={\csfmt{Gloss\-entry\-desc}}, + user1={\margm{label}}, + description={like \cs{glossentrydesc} but converts the first +letter to uppercase}, + note={provided by \styfmt{glossaries}}, + category={command} +} + @index{glossentrysymbol, name={\csfmt{gloss\-entry\-symbol}}, user1={\margm{label}}, @@ -6703,6 +8467,27 @@ indexing}, category={command} } +@index{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 +\gls{styopt.nopostdot} package option for \sty{glossaries} +and the \styopt{postpunc} option for \sty{glossaries-extra}}, + note={provided by \styfmt{glossaries} and modified by +\styfmt{glossaries-extra}}, + category={command} +} + +@index{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}, + note={provided by \styfmt{glossaries-accsupp}}, + category={command} +} + @index{forglsentries, name={\csfmt{for\-gls\-entries}}, user1={\oargm{glossary-list}\margm{cs}\margm{body}}, @@ -6747,7 +8532,87 @@ indexing}, @index{glstextformat, name={\csfmt{glstextformat}}, user1={\margm{text}}, - description={used by commands like \cs{gls} to format the link-text}, + description={used by commands like \cs{gls} to format the + \idx{link-text}}, + note={provided by \styfmt{glossaries}}, + category={command} +} + +@index{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}, + note={provided by \styfmt{glossaries-extra} v1.04+}, + category={command} +} + +@index{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}, + note={provided by \styfmt{glossaries-extra} v1.30+}, + category={command} +} + +@index{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}}, + note={provided by \styfmt{glossaries-extra} v1.30+}, + category={command} +} + +@index{GlsXtrStartUnsetBuffering, + name={\csfmt{Gls\-Xtr\-Start\-Unset\-Buffer\-ing}}, + description={starts buffering calls to \cs{glsunset} + for use in code where the boolean switch causes a problem. + The buffer can later be processed and cleared with + \gls{GlsXtrStopUnsetBuffering}. The starred form + (added to v1.31) avoids duplicate labels in the buffer's + internal list}, + note={provided by \styfmt{glossaries-extra} v1.30+}, + category={command} +} + +@index{GlsXtrStopUnsetBuffering, + name={\csfmt{Gls\-Xtr\-Stop\-Unset\-Buffer\-ing}}, + description={unsets (locally with the starred form) + all the entry whose labels are stored in the + buffer that was started with + \gls{GlsXtrStartUnsetBuffering} and clears the buffer}, + note={provided by \styfmt{glossaries-extra} v1.30+}, + category={command} +} + +@index{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 + \gls{GlsXtrStartUnsetBuffering} and implements + \meta{cs}\margm{label} at each iteration}, + note={provided by \styfmt{glossaries-extra} v1.31+}, + category={command} +} + +@index{glsunset, + name={\csfmt{gls\-unset}}, + user1 = {\margm{label}}, + description={unsets the \idx{firstuseflag} so that the entry is +marked as having been used}, + note={provided by \styfmt{glossaries}}, + category={command} +} + +@index{glsreset, + name={\csfmt{gls\-reset}}, + user1 = {\margm{label}}, + description={resets the \idx{firstuseflag} so that the entry is +marked as not used}, note={provided by \styfmt{glossaries}}, category={command} } @@ -6907,6 +8772,22 @@ has three or more items}, category={command} } +@index{acute, + name={\csfmt{'}}, + user1={\margm{character}}, + description={puts an acute accent over \meta{character}}, + note={kernel command}, + category={command} +} + +@index{umlaut, + name={\csfmt{"}}, + user1={\margm{character}}, + description={puts an umlaut accent over \meta{character}}, + note={kernel command}, + category={command} +} + @index{textsuperscript, name={\csfmt{textsuperscript}}, user1={\margm{text}}, @@ -7044,6 +8925,7 @@ by \meta{name}}, user1={\margm{id}}, description={creates a label that can be referenced with \ics{ref} or \ics{pageref}}, + seealso={ref,pageref}, note={kernel command}, category={command} } @@ -7062,6 +8944,14 @@ occurred}, user1={\margm{id}}, description={cross-reference the location where \cs{label}\margm{id} occurred}, + seealso={label}, + note={kernel command}, + category={command} +} + +@index{par, + name={\csfmt{par}}, + description={paragraph break}, note={kernel command}, category={command} } @@ -7084,3 +8974,557 @@ name} and the displayed \meta{text}}, category={command} } +@index{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}}, + seealso={ref}, + note={provided by \styfmt{glossaries} v3.0+}, + category={command} +} + +@index{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}, + note={provided by \styfmt{glossaries-extra} v1.11}, + category={command} +} + +@index{glsxtrglossentry, + name={\csfmt{gls\-xtr\-gloss\-entry}}, + user1={\margm{label}}, + description={displays the given entry name including a hypertarget (if +\sty{hyperref} has been loaded) as the destination for commands like +\gls{gls}}, + note={provided by \styfmt{glossaries-extra} v1.21}, + category={command} +} + +@index{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)}, + note={provided by \styfmt{glossaries-extra} v1.22+}, + category={command} +} + +@index{glsshowtarget, + name={\csfmt{gls\-show\-target}}, + user1={\margm{label}}, + description={used to show the target name when the +\styopt[showtargets]{debug} option is on}, + note={provided by \styfmt{glossaries} v4.32+}, + category={command} +} + +@index{GlsEntryCounterLabelPrefix, + name={\csfmt{Gls\-Entry\-Counter\-Label\-Prefix}}, + description={used as a prefix in the \gls{label} command + automatically implemented by the \styopt{entrycounter} + and \styopt{subentrycounter} options}, + note={provided by \styfmt{glossaries} v4.38+}, + category={command} +} + +@index{GlsXtrStandaloneGlossaryType, + name={\csfmt{Gls\-Xtr\-Stand\-alone\-Glossary\-Type}}, + description={expands to the label for \gls{currentglossary} + within \gls{glsxtrglossentry} and \gls{glsxtrglossentryother}}, + note={provided by \styfmt{glossaries-extra} v1.31+}, + category={command} +} + +@index{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}, + note={provided by \styfmt{glossaries-extra} v1.31+}, + category={command} +} + +@index{glsresetentrycounter, + name={\csfmt{gls\-reset\-entry\-counter}}, + description={resets the \counter{glossaryentry} counter if the +\styopt{entrycounter} setting is on}, + note={provided by \styfmt{glossaries}}, + category={command} +} + +@index{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}, + note={provided by \styfmt{glossaries}}, + category={command} +} + +@index{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}, + note={provided by \styfmt{glossaries-extra}}, + category={command} +} + +@index{glstreepredesc, + name={\csfmt{gls\-tree\-pre\-desc}}, + user1={\margm{label}}, + description={separator used before the description for the + \glostyle{tree} styles}, + note={provided by \styfmt{glossary-tree} v4.26+}, + category={command} +} + +@index{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}, + note={provided by \styfmt{glossaries-extra-stylemods} v1.31+}, + category={command} +} + +@index{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}, + note={provided by \styfmt{glossaries-extra}}, + category={command} +} + +@index{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}, + note={provided by \styfmt{glossaries-extra}}, + category={command} +} + +@index{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}, + note={provided by \styfmt{glossaries-extra}}, + category={command} +} + +@index{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}, + note={provided by \styfmt{glossaries-extra}}, + category={command} +} + +@index{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}, + note={provided by \styfmt{glossaries-extra}}, + category={command} +} + +@index{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}, + note={provided by \styfmt{glossaries-extra}}, + category={command} +} + +@index{tableofcontents, + name={\csfmt{table\-of\-contents}}, + description={displays the table of contents (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}, + category={command} +} + +@index{underline, + name={\csfmt{under\-line}}, + user1={\margm{text}}, + description={underlines the given text}, + note={kernel command}, + category={command} +} + +@index{ul, + name={\csfmt{ul}}, + user1={\margm{text}}, + description={underlines the given text}, + note={provided by \styfmt{soul}}, + category={command} +} + +@index{ding, + name={\csfmt{ding}}, + user1={\margm{number}}, + description={displays the symbol associated with the given number}, + note={provided by \styfmt{pifont}}, + category={command} +} + +@index{exampleterms, + name = {example terms} +} + +@entry{ex1.duck, + parent={exampleterms}, + name={duck}, + description={a waterbird with webbed feet}, + identifier={animal} +} + +@entry{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} +} + +@entry{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} +} + +@entry{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} +} + +@entry{ex.fleuron, + parent={exampleterms}, + name = {fleuron}, + symbol = {\ding{167}}, + category = {ornament}, + description = {typographic ornament} +} + +@entry{ex.pi, + parent={exampleterms}, + name = {Archimedes' constant}, + symbol = {\ensuremath{\pi}}, + category = {constant}, + description = {ratio of a circle's circumference to its diameter} +} + +@entry{ex.thetai, + parent = {exampleterms}, + name = {theta parameter}, + symbol = {\ensuremath{\theta_i}}, + description = {one of the model parameters} +} + +@abbreviation{ex.tug, + parent={exampleterms}, + category = {longshortem}, + short = {TUG}, + long = {\TeX\ Users Group} +} + +@abbreviation{ex.ascii, + short = {ascii}, + long = {American Standard Code for Information Interchange}, + category={shortsc} +} + +@abbreviation{ex.svm, + parent={exampleterms}, + short = {SVM}, + long = {support vector machine} +} + +@abbreviation{ex.ssl, + parent={exampleterms}, + category = {markwordsexample}, + short = {SSL}, + long = {Secure Sockets Layer} +} + +@abbreviation{ex.xml, + parent={exampleterms}, + category = {taggingexample}, + short = {XML}, + long = {e\itag{x}tensible \itag{m}arkup \itag{l}anguage} +} + +@abbreviation{ex.dante, + parent={exampleterms}, + category = {discardperiodexample}, + short = {DANTE e.V.}, + long = {Deutschsprachige Anwendervereinigung \TeX\ e.V.} +} + +@abbreviation{ex.gp, + parent={exampleterms}, + category = {discardperiodexample}, + short = {G.P.}, + long = {General Practitioner} +} + +@abbreviation{ex2.gp, + parent={exampleterms}, + category = {initialism}, + short = {GP}, + long = {General Practitioner} +} + +@abbreviation{ex.rna, + parent={exampleterms}, + short = {RNA}, + long = {ribonukleins\"aure}, + user1 = {ribonucleic acid}, + category = {abbrvtrans} +} + +@entry{ex.length, + parent={exampleterms}, + name = {length}, + symbol = {\si{\metre}}, + description = {measurement between two points} +} + +@entry{ex.area, + parent={exampleterms}, + name = {area}, + symbol = {\si{\metre\squared}}, + description = {measurement of a surface} +} + +@symbol{ex2.length, + parent={exampleterms}, + description = {length}, + name = {\si{\metre}} +} + +@symbol{ex2.area, + parent={exampleterms}, + description = {area}, + name = {\si{\metre\squared}} +} + +@symbol{ex.deriv, + parent={exampleterms}, + description = {derivative}, + name = {\ensuremath{\derivfn{x}}}, + user1 = {derivfn} +} + +@index{hom.bow1, + name={bow}, + description={(rhymes with toe)}, + category = {homograph} +} + +@entry{hom.bowknot, + parent={hom.bow1}, + description = {a knot tied with two loops and loose ends}, + category = {homograph} +} + +@entry{hom.bowweapon, + parent={hom.bow1}, + description = {a weapon for shooting arrows, made of curved wood + joined at both ends with taut string}, + category = {homograph} +} + +@index{hom.bow2, + name={bow}, + description={(rhymes with cow)}, + category = {homograph} +} + +@index{hom.bowbend, + parent={hom.bow2}, + description={bend head or upper body}, + category = {homograph} +} + +@index{hom.bowpressure, + parent={hom.bow2}, + description={give in to pressure}, + category = {homograph} +} + +@index{hom.bow3, + name={bow}, + description={(also bows) the front end of a ship}, + category = {homograph} +} + +@index{hom.glossary, + name={glossary}, + category = {homograph} +} + +@entry{hom.glossarycol, + parent = {hom.glossary}, + description = {collection of glosses}, + category = {homograph} +} + +@entry{hom.glossarylist, + parent = {hom.glossary}, + description = {list of technical words}, + category = {homograph} +} + +@entry{hier.animal, + name = {animal}, + description = {living organism with a nervous system and sense organs + that can move independently}, + category = {hierarchical} +} + +@entry{hier.bird, + parent = {hier.animal}, + name = {bird}, + description = {warm-blooded egg-laying animal with feathers, wings + and a beak}, + category = {hierarchical} +} + +@entry{hier.duck, + parent = {hier.bird}, + name = {duck}, + description={a waterbird with webbed feet}, + category = {hierarchical} +} + +@entry{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} +} + +@entry{hier.mineral, + name = {mineral}, + description = {natural inorganic substance}, + category = {hierarchical} +} + +@entry{hier.calcite, + parent = {hier.mineral}, + name = {calcite}, + description = {a carbonate mineral}, + category = {hierarchical} +} + +@entry{hier.quartz, + parent = {hier.mineral}, + name = {quartz}, + description = {hard mineral consisting of silica}, + category = {hierarchical} +} + +@entry{hier.amethyst, + parent = {hier.quartz}, + name = {amethyst}, + description = {a purple type of quartz}, + category = {hierarchical} +} + +@entry{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} +} + +@entry{ex2.amethyst, + name = {amethyst}, + description = {a purple type of quartz}, + symbol = {\ce{SiO2}}, + user3={A}, + user4={A}, + category = {standalone} +} + +@entry{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} +} + +@entry{ex3.duck, + name={duck}, + user3={D}, + user4={D}, + description={a waterbird with webbed feet}, + category={standalone} +} + +@entry{standalone.pi, + name = {\ensuremath{\pi}}, + description = {Archimedes' constant}, + user3={glssymbols}, + user4={greek}, + category = {standalone} +} + +@entry{standalone.area, + name = {\ensuremath{A}}, + description = {area}, + user3={glssymbols}, + user4={A}, + category = {standalone} +} + +@entry{standalone.radius, + name = {\ensuremath{r}}, + description = {radius}, + user3={glssymbols}, + user4={R}, + category = {standalone} +} + +@entry{standalone.circumference, + name = {\ensuremath{C}}, + user3={glssymbols}, + user4={C}, + description = {circumference}, + category = {standalone} +} + diff --git a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex index 4f3dc88f5cf..39cd070365a 100644 --- a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex +++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex @@ -9,6 +9,8 @@ \documentclass[titlepage=false,index=totoc,bibliography=totoc, fontsize=12pt,captions=tableheading]{scrreprt} +\usepackage{pifont} + % Need support for extended characters % and need a mono font that supports hyphenation \usepackage[no-math]{fontspec} @@ -27,7 +29,6 @@ \usepackage{etoolbox} \usepackage{hologo} -\usepackage{xcolor} \usepackage{amsmath} \usepackage{accents} \usepackage{tikz} @@ -41,12 +42,15 @@ entrycounter,% enable entry counting subentrycounter,% enable entry counting %debug=showtargets,% debugging information - stylemods=bookindex,% adjust predefined styles and load glossary-bookindex.sty + stylemods={mcols,bookindex},% adjust predefined styles and load glossary-mcols.sty and glossary-bookindex.sty style=bookindex ] {glossaries-extra} +\renewcommand*{\glsshowtarget}[1]{\texttt{\small [#1]}} + \glsxtrprovidestoragekey{note}{}{} +\glsxtrprovidestoragekey{package}{}{} \providecommand{\omicron}{o} @@ -85,12 +89,19 @@ \newcommand{\glsxtrpostnameenvironment}{\space environment} \newcommand{\glsxtrpostnamecounter}{\space counter} +\newcommand*{\csfmt}[1]{% + \texorpdfstring + {\texttt{\char`\\ #1}}% + {\string\\#1}% +} + \setabbreviationstyle[common]{short-nolong} \GlsXtrLoadResources[ 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}, @@ -177,15 +188,10 @@ \let\-\empty } -\newcommand*{\csfmt}[1]{% - \texorpdfstring - {\texttt{\char`\\ #1}}% - {\string\\#1}% -} - % 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}} @@ -206,6 +212,7 @@ {\string\\jobname-#1.glstex}% } +\newcommand{\extstyopt}{\textsuperscript{\textdagger}} \newcommand*{\appfmt}[1]{\texorpdfstring{\texttt{#1}}{#1}} \newcommand*{\styfmt}[1]{\texorpdfstring{\textsf{#1}}{#1}} @@ -297,7 +304,7 @@ \newcommand*{\styopt}[2][]{% \texorpdfstring% {% - \idx{styopt.#2}\styoptfmt{\ifblank{#1}{}{\dequals\marg{#1}}}% + \gls{styopt.#2}\styoptfmt{\ifblank{#1}{}{\dequals\marg{#1}}}% }% {#2\ifblank{#1}{}{=#1}}% } @@ -513,6 +520,69 @@ }% } +\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}}% @@ -672,14 +742,12 @@ files} \DTMsetstyle{pdf} \protected@edef\x{\endgroup \noexpand\hypersetup{% - pdfinfo={ - Title={\@title}, - Author={\@author}, - CreationDate={\DTMuse{creation}}, - ModDate={\DTMuse{moddate}}, - }% - %\noexpand\pdfinfo{/CreationDate (\DTMuse{creation}) - %/ModDate (\DTMuse{moddate})} + pdfinfo={ + Title={\@title}, + Author={\@author}, + CreationDate={\DTMuse{creation}}, + ModDate={\DTMuse{moddate}}, + }% }% }\x @@ -726,6 +794,11 @@ 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 \filefmt{bib2gls-begin.pdf} 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 @@ -757,8 +830,13 @@ 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 this method as that command works +You can't use \ics{glsaddall} with \bibgls\ as that command works by iterating over all defined entries and calling \ics{glsadd}\margm{label}. On the first \LaTeX\ run there are no entries defined, so \ics{glsaddall} does nothing. If you want to @@ -1557,7 +1635,7 @@ For example, suppose the \ext{bib} file includes: 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 -upper case when displaying the glossary. See also +\idx{uppercase} when displaying the glossary. See also \longarg{mfirstuc-protection} and \longarg{mfirstuc-math-protection}.) @@ -1611,7 +1689,7 @@ texparserlib: {}$\mtx{M}$ -> M 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 upper case letter \qtt{M}, decimal value 77). +character \hex{4D} (Latin \idx!{uppercase} letter \qtt{M}, decimal value 77). For the \code{v} entry, the code is: \begin{verbatim} @@ -1623,7 +1701,7 @@ texparserlib: \marg{}\$\csfmt{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 lower case letter \qtt{v}, decimal value 118) and +(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: @@ -1636,7 +1714,7 @@ 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 upper case letter \qtt{S}, decimal value~83). +character \hex{53} (Latin \idx!{uppercase} letter \qtt{S}, decimal value~83). For the \code{card} entry, the code is: \begin{verbatim} @@ -1652,7 +1730,7 @@ 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 upper case letter \qtt{S}, decimal value 83) and +\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} @@ -1701,7 +1779,7 @@ letter.) If \csopt[letter-nocase]{sort} is used instead then, after conversion by the interpreter, the sort values will all be changed to -lower case. The order is now: \code{i} ($\imaginary$), +\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 @@ -1721,7 +1799,7 @@ M -> 'm' (M) [109] S -> 's' (S) [115] v -> '\usebox\varrow' (V) [118 8407] \end{alltt} -Note that the letter groups are upper case not lower case. +Note that the letter groups are \idx{uppercase} not \idx{lowercase}. Again the \code{card} entry doesn't have an associated letter group. @@ -1846,6 +1924,14 @@ written to the transcript file, which can be inspected afterwards. 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} @@ -1916,7 +2002,12 @@ for more details. \argsection{no-interpret} Switch off the interpreter mode. See \sectionref{sec:texparserlib} -for more details. +for more details about the interpreter. If the interpreter is off, +the transcript (\iext{log}) file won't be parsed, so if you need +\bibgls\ to know that you are using \sty{fontspec} but you don't +want the interpreter on then you must use +\longarg{packages}\code{ fontspec} to indicate that UTF-8 is +natively supported. \argsection{no-break-space} @@ -2138,7 +2229,7 @@ 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 \verb|$x$| and the glossary style automatically tries to -convert the first letter of the name to upper case, then this will +convert the first letter of the name to \idx{uppercase}, then this will cause a problem. With \longarg{mfirstuc-math-protection} set, \bibgls\ will @@ -2349,7 +2440,7 @@ can't use non-ASCII characters in \meta{label} with \sty{inputenc} \end{description} The \idx{lettergroup} titles will typically have the first character -converted to upper case for the alphabet sort methods +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 @@ -2364,8 +2455,8 @@ by the following line in the \langxml: <entry key="grouptitle.case.ij">IJ</entry> \end{verbatim} If there isn't a \code{grouptitle.case.\meta{lc}} key (where -\meta{lc} is the lower case version), then only the first character -will be converted to upper case otherwise the value supplied by the +\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 @@ -2380,7 +2471,7 @@ 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 upper case. The case-sensitive ordering +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 @@ -2808,6 +2899,12 @@ option instead. \caption[Fields Set by \bibgls]{Fields Sometimes Set by \bibgls\ in the \iext{glstex} File} \label{tab:internalfields} +You may define and assign \field{bibtextype} (although it's more +likely to be aliased). Don't define any of others, and don't use any +of them in the \ext{bib} file, except for \field{group}, +\field{sort} or \field{type} although those three are best +assigned in the resource command or by \bibgls.\par +\bigskip \centering \printfields{internalfield}% \end{table} @@ -2815,8 +2912,12 @@ the \iext{glstex} File} \begin{table}[hbtp] \caption[Internal Fields Set by \styfmt{glossaries} or \styfmt{glossaries-extra} or \bibgls]{Internal Fields Set by -\styfmt{glossaries} or \styfmt{glossaries-extra} or \bibgls\ -(don't use in \ext{bib} files)}\label{tab:baseinternalfields} +\styfmt{glossaries} or \styfmt{glossaries-extra} or \bibgls}% +\label{tab:baseinternalfields} +\medskip +Don't define any of these and don't use any of them in the \ext{bib} +file.\par +\bigskip \centering \printfields{baseinternalfield}% \end{table} @@ -3255,6 +3356,52 @@ Example: Terms that are defined using \atentry{index} will be written to the output file using the command \csref{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. All fields are optional. For example: +\begin{verbatim} +@indexplural{goose, + plural = {geese} +} + +@indexplural{duck} + +@indexplural{chateau, + text = {ch\^ateau}, + plural = {ch\^ateaux} +} +\end{verbatim} +This is equivalent to: +\begin{verbatim} +@indexplural{goose, + name = {geese}, + text = {goose}, + plural = {geese} +} + +@indexplural{duck, + name = {ducks}, + text = {duck}, + plural = {ducks} +} + +@indexplural{chateau, + name = {ch\^ateaux}, + text = {ch\^ateau}, + plural = {ch\^ateaux} +} +\end{verbatim} + +Terms that are defined using \atentry{indexplural} will be written to the output +file using the command \csref{bibglsnewindexplural}. + \entrysection{abbreviation} The \atentry{abbreviation} entry type is designed for abbreviations. @@ -3304,7 +3451,7 @@ instead do: \setabbreviationstyle{long-short-sc} \GlsXtrLoadResources[src={entries-abbrv.bib},ignore-fields={description}] \end{verbatim} -or to convert the short value to upper case and use the +or to convert the short value to \idx{uppercase} and use the \abbrstyle{long-short-sm} style instead: \begin{verbatim} \setabbreviationstyle{long-short-sm} @@ -4661,7 +4808,7 @@ 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 lower case). +\atentry{bibtexentry} and converted to \idx!{lowercase}). For example \code{article} or \code{book}. You can iterate over these internal list fields using @@ -5564,6 +5711,101 @@ 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{verbatim} +@index{birds} +@index{duck,parent={birds}} +@index{goose,plural={geese},parent={birds}} +@index{swan,parent={birds}} + +@index{minerals} +@index{quartz,parent={minerals}} +@index{corundum,parent={minerals}} +@index{amethyst,parent={minerals}} +@index{gypsum,parent={minerals}} +@index{gold,parent={minerals}} +\end{verbatim} +and the document contains: +\begin{verbatim} +\documentclass{article} + +\usepackage[record,style=indexgroup]{glossaries-extra} + +\GlsXtrLoadResources[src={entries},save-child-count] + +\begin{document} +\gls{duck} and \gls{goose}. +\gls{quartz}, \gls{corundum}, \gls{amethyst}. + +\printunsrtglossaries +\end{document} +\end{verbatim} +Then the \ext{glstex} file will contain: +\begin{verbatim} +\GlsXtrSetField{birds}{childcount}{2} +\GlsXtrSetField{duck}{childcount}{0} +\glsxtrfieldlistadd{birds}{childlist}{duck} +\GlsXtrSetField{goose}{childcount}{0} +\glsxtrfieldlistadd{birds}{childlist}{goose} +\GlsXtrSetField{minerals}{childcount}{3} +\GlsXtrSetField{amethyst}{childcount}{0} +\glsxtrfieldlistadd{minerals}{childlist}{amethyst} +\GlsXtrSetField{corundum}{childcount}{0} +\glsxtrfieldlistadd{minerals}{childlist}{corundum} +\GlsXtrSetField{quartz}{childcount}{0} +\glsxtrfieldlistadd{minerals}{childlist}{quartz} +\end{verbatim} +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{verbatim} +\GlsXtrLoadResources[src={entries},category=general,save-child-count] + +\renewcommand{\glsxtrpostdescgeneral}{% + \glsxtrifhasfield{childcount}{\glscurrententrylabel} + { (child count: \glscurrentfieldvalue.)}% + {}% +} +\end{verbatim} +\ics{glsxtrifhasfield} requires at least \sty{glossaries-extra} v1.19. +It's slightly more efficient that \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}. @@ -5924,6 +6166,124 @@ In the above, the location list 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{verbatim} +@entry{ubik, + name={Ubik}, + description={novel by Philip K. Dick}, + identifier={book}, + author={\sortmediacreator{Philip K.}{Dick}}, + year={1969} +} +\end{verbatim} +then the field alias +\begin{codeenv} +\csopt[author=parent]{field-aliases} +\end{codeenv} +will treat +\begin{verbatim} + author={\sortmediacreator{Philip K.}{Dick}}, +\end{verbatim} +as though it had been defined as +\begin{verbatim} + parent={\sortmediacreator{Philip K.}{Dick}}, +\end{verbatim} +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{verbatim} +\providecommand*{\sortmediacreator}[2]{#2 #1} +\end{verbatim} +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{verbatim} +@index{DickPhilipK, + name={\sortmediacreator{Philip K.}{Dick}} +} +\end{verbatim} +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} @@ -6161,7 +6521,7 @@ supplementary resource files (omitting the primary \end{verbatim} \section{Field and Label Options} -\label{sec:labelopts} +\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 @@ -6169,197 +6529,10 @@ 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}. -\optsection{group} - -The \csopt{group} option may only be used with the \longarg{group} switch. -This will set the \field{group} field to \meta{label} unless -\meta{label} is \optfmt{auto}, in which case the value is -set automatically during the sorting (see also -\csopt{group-formation}). -The corresponding title can be set -with \gls{glsxtrsetgrouptitle} if the title is different from the -label. The default behaviour is \csopt[auto]{group}. - -For example: -\begin{verbatim} -\GlsXtrLoadResources[sort=integer,group={Constants}, - src={entries-constants}% data in entries-constants.bib -] -\GlsXtrLoadResources[sort=letter-case,group={Variables}, - src={entries-variables}% data in entries-variables.bib -] -\end{verbatim} -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{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 -(lower case 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 (lower case 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 lower case to ensure consistency. - -For example, if the \ext{bib} file contains: -\begin{verbatim} -@entry{bird, - name={bird}, - description = {feathered animal} -} - -@index{duck} - -@index{goose,plural="geese"} - -@dualentry{dog, - name={dog}, - description={chien} -} -\end{verbatim} -then if the document contains -\begin{verbatim} -\GlsXtrLoadResources[category={same as entry},src={entries}] -\end{verbatim} -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{verbatim} -\GlsXtrLoadResources[category={animals},src={entries}] -\end{verbatim} -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, -such as \csref{bibglsnewindex}, that are used to actually define the -entries. - -For example, if the document contains -\begin{verbatim} -\newcommand{\bibglsnewdualentry}[4]{% - \longnewglossaryentry*{#1}{name={#3},#2,category={dual}}{#4}% -} - -\GlsXtrLoadResources[category={animals},src={entries}] -\end{verbatim} -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{type} - -The \meta{value} may be one of: -\begin{itemize} - \item \optfmt{same as entry} set the \field{type} field - to the entry type (lower case and without the initial \code{@}); - - \item \optfmt{same as original entry} set the \field{type} - to the original entry type (lower case 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\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{verbatim} -\usepackage[record,symbols]{glossaries-extra} - -\GlsXtrLoadResources[src={entries-symbols},type=symbols] -\end{verbatim} - -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{verbatim} -\usepackage[record,nomain]{glossaries-extra} - -\newglossary*{dictionary}{Dictionary} - -\GlsXtrLoadResources[src={entries-symbols},type=dictionary] -\end{verbatim} -(The \styopt{nomain} option was added to suppress the -creation of the default \code{main} glossary.) - -\optsection{trigger-type} - -The record counting commands, such as \ics{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 -\ics{provideignoredglossary*}\margm{type} to the \ext{glstex} file -(see \sectionref{sec:newglossary}). +\subsection{Label Options} +\label{sec:labelopts} -\optsection{interpret-label-fields} +\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 @@ -6381,7 +6554,7 @@ 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{labelify} +\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 @@ -6465,7 +6638,7 @@ to retain the original: ] \end{verbatim} -\optsection{labelify-list} +\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 @@ -6488,7 +6661,7 @@ or \end{verbatim} depending on whether or not \sty{fontspec} was detected. -\optsection{labelify-replace} +\optsection[\subsubsection]{labelify-replace} This option takes a comma-separated list as a value with each element in the list in the form \margm{regex}\margm{replacement} @@ -6500,7 +6673,24 @@ file so take care to protect any special characters. For example, to match a literal \idx{full-stop} use \cs{cs.string}\ics{cs.period} rather than just \ics{cs.period} (backslash dot). -Both \csopt{labelify} and \csopt{labelify-list} use this setting to +In the \meta{replacement} part, you can use +\ics{glscapturedgroup}\meta{n} to reference a captured sub-sequence. +For example: +\begin{verbatim} +\csopt[{([A-Z])\string\.}{\glscapturedgroup1}]{labelify-replace} +\end{verbatim} +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\u|). 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{verbatim} @@ -6551,125 +6741,462 @@ or \end{verbatim} depending on whether or not \sty{fontspec} was detected. -\optsection{strip-missing-parents} +\optsection[\subsubsection]{label-prefix} -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). +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{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. -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} +For example, if the \ext{bib} file contains +\begin{verbatim} +@entry{bird, + name={bird}, + description = {feathered animal, such as a \gls{duck} or \gls {goose}} +} -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}. +@entry{waterfowl, + name={waterfowl}, + description={Any \gls{bird} that lives in or about water}, + see={[see also]{duck,goose}} +} -\optsection{missing-parents} +@index{duck} -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}; +@index{goose,plural="geese"} +\end{verbatim} +Then if this \ext{bib} file is loaded with \csopt[gls.]{label-prefix} +it's as though the entries had been defined as: +\begin{verbatim} +@entry{gls.bird, + name={bird}, + description = {feathered animal, such as a \gls{gls.duck} or +\gls{gls.goose}} +} -\item \optfmt{warn}: this is equivalent to the default -\csopt[false]{strip-missing-parents}; +@entry{gls.waterfowl, + name={waterfowl}, + description={Any \gls{gls.bird} that lives in or about water}, + see={[see also]{gls.duck,gls.goose}} +} -\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}. +@index{gls.duck,name={duck}} + +@index{gls.goose,name={goose},plural="geese"} +\end{verbatim} + +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}, \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{verbatim} +\glsxtr@record{bird}{}{page}{glsnumberformat}{1} +\glsxtr@record{waterfowl}{}{page}{glsnumberformat}{1} +\glsxtr@record{idx.duck}{}{page}{glsnumberformat}{1} +\glsxtr@record{idx.goose}{}{page}{glsnumberformat}{1} +\end{verbatim} +The use of \csopt[idx.]{record-label-prefix} makes \bibgls\ act as +though the records were given as: +\begin{verbatim} +\glsxtr@record{idx.bird}{}{page}{glsnumberformat}{1} +\glsxtr@record{idx.waterfowl}{}{page}{glsnumberformat}{1} +\glsxtr@record{idx.duck}{}{page}{glsnumberformat}{1} +\glsxtr@record{idx.goose}{}{page}{glsnumberformat}{1} +\end{verbatim} + + +\optsection[\subsubsection]{cs-label-prefix} + +If you have commands such as \ics{gls}\margm{label} or +\ics{glstext}\marg{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{verbatim} +@entry{bird, + name={bird}, + description = {feathered animal, such as a \gls{duck} or \gls{goose}} +} +\end{verbatim} +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{verbatim} +description = {feathered animal, such as a \gls{idx.duck} or +\gls{idx.goose}} +\end{verbatim} +However with \csopt[gls.]{cs-label-prefix} the \field{description} +field will be converted to +\begin{verbatim} +description = {feathered animal, such as a \gls{gls.duck} or +\gls{gls.goose}} +\end{verbatim} +regardless of the \csopt{label-prefix} setting. Whereas if the +original entry definition is +\begin{verbatim} +@entry{bird, + name={bird}, + description = {feathered animal, such as a \gls{dual.duck} or +\gls{dual.goose}} +} +\end{verbatim} +then \idprefix{dual} will be replaced by the value of the +\csopt{dual-prefix} option regardless of the \csopt{cs-label-prefix} +setting. -For example, consider the \exfile{books.bib} file which contains -entries like +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}). + +For example, suppose the file \filefmt{entries-terms.bib} contains: \begin{verbatim} -@entry{ubik, - name={Ubik}, - description={novel by Philip K. Dick}, - identifier={book}, - author={\sortmediacreator{Philip K.}{Dick}}, - year={1969} +@entry{set, + name={set}, + description={collection of values, denoted \gls{ext1.set}} } \end{verbatim} -then the field alias -\begin{codeenv} -\csopt[author=parent]{field-aliases} -\end{codeenv} -will treat +and the file \filefmt{entries-symbols.bib} contains: \begin{verbatim} - author={\sortmediacreator{Philip K.}{Dick}}, +@symbol{set, + name={\ensuremath{\mathcal{S}}}, + description={a \gls{ext1.set}} +} \end{verbatim} -as though it had been defined as + +These files both contain an entry with the label \code{set} +but the \field{description} field includes \verb|\gls{ext1.set}| which is +referencing the entry from the other file. These +two files can be loaded without conflict using: \begin{verbatim} - parent={\sortmediacreator{Philip K.}{Dick}}, +\usepackage[record,symbols]{glossaries-extra} + +\GlsXtrLoadResources[src={entries-terms}, + label-prefix={gls.}, + ext-prefixes={sym.} +] + +\GlsXtrLoadResources[src={entries-symbols}, + type=symbols, + label-prefix={sym.}, + ext-prefixes={gls.} +] \end{verbatim} -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: + +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{verbatim} -\providecommand*{\sortmediacreator}[2]{#2 #1} +collection of values, denoted \gls{sym.set} \end{verbatim} -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: +The \code{set} entry +from \filefmt{entries-symbols.bib} will be defined with the label +\code{sym.set} and the description will be \begin{verbatim} -@index{DickPhilipK, - name={\sortmediacreator{Philip K.}{Dick}} +a \gls{gls.set} +\end{verbatim} + +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{verbatim} +@entry{set, + name={set}, + description={collection of values, denoted \gls{ext1.S}} } \end{verbatim} -This is an alternative approach to the \exfile{sample-authors.tex} -document from the \hyperref[sec:examples]{examples chapter}. +and \filefmt{entries-symbols.bib} could contain: +\begin{verbatim} +@symbol{S, + name={\ensuremath{\mathcal{S}}}, + description={a \gls{ext1.set}} +} +\end{verbatim} +Now they can be combined with: +\begin{verbatim} +\GlsXtrLoadResources[src={entries-terms,entries-symbols}] +\end{verbatim} +which will simply strip the \glsdisp{idx.idprefix.extn}{\idprefixfmt{ext1}} +prefix from the cross-references. Alternatively: +\begin{verbatim} +\GlsXtrLoadResources[src={entries-terms,entries-symbols}, + label-prefix={gls.}, + ext-prefixes={gls.} +] +\end{verbatim} +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{missing-parent-category} +\optsection[\subsubsection]{save-original-id} -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: +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. + +\subsection{Assignments} +\label{sec:fieldassignments} + +\optsection[\subsubsection]{group} + +The \csopt{group} option may only be used with the \longarg{group} switch. +This will set the \field{group} field to \meta{label} unless +\meta{label} is \optfmt{auto}, in which case the value is +set automatically during the sorting (see also +\csopt{group-formation}). +The corresponding title can be set +with \gls{glsxtrsetgrouptitle} if the title is different from the +label. The default behaviour is \csopt[auto]{group}. + +For example: +\begin{verbatim} +\GlsXtrLoadResources[sort=integer,group={Constants}, + src={entries-constants}% data in entries-constants.bib +] +\GlsXtrLoadResources[sort=letter-case,group={Variables}, + src={entries-variables}% data in entries-variables.bib +] +\end{verbatim} +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 \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). +\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} -The default setting is \csopt[no value]{missing-parent-category}. +This will override any +\field{category} fields supplied in the \ext{bib} file. -\optsection{abbreviation-name-fallback} +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{verbatim} +@entry{bird, + name={bird}, + description = {feathered animal} +} + +@index{duck} + +@index{goose,plural="geese"} + +@dualentry{dog, + name={dog}, + description={chien} +} +\end{verbatim} +then if the document contains +\begin{verbatim} +\GlsXtrLoadResources[category={same as entry},src={entries}] +\end{verbatim} +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{verbatim} +\GlsXtrLoadResources[category={animals},src={entries}] +\end{verbatim} +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, +such as \csref{bibglsnewindex}, that are used to actually define the +entries. + +For example, if the document contains +\begin{verbatim} +\newcommand{\bibglsnewdualentry}[4]{% + \longnewglossaryentry*{#1}{name={#3},#2,category={dual}}{#4}% +} + +\GlsXtrLoadResources[category={animals},src={entries}] +\end{verbatim} +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\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{verbatim} +\usepackage[record,symbols]{glossaries-extra} + +\GlsXtrLoadResources[src={entries-symbols},type=symbols] +\end{verbatim} + +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{verbatim} +\usepackage[record,nomain]{glossaries-extra} + +\newglossary*{dictionary}{Dictionary} + +\GlsXtrLoadResources[src={entries-symbols},type=dictionary] +\end{verbatim} +(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 \ics{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 +\ics{provideignoredglossary*}\margm{type} to the \ext{glstex} file +(see \sectionref{sec:newglossary}). + +\optsection[\subsubsection]{abbreviation-name-fallback} The entry types that define abbreviations (such as \atentry{abbreviation} and \atentry{acronym}) will, by default, @@ -6681,7 +7208,7 @@ specify the field. For example, \csopt[long]{abbreviation-name-fallback}. The \meta{field} value must be a known field label. -\optsection{ignore-fields} +\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 @@ -6710,7 +7237,7 @@ 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{field-aliases} +\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 @@ -6748,7 +7275,7 @@ keys: ] \end{verbatim} -\optsection{replicate-fields} +\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 @@ -6833,14 +7360,236 @@ make a difference. The same result occurs with: ] \end{verbatim} -\optsection{replicate-override} +\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{bibtex-contributor-fields} +\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{alltt} +\ics{printunsrtglossary*}\oarg{type=copies,style=indexgroup} + \marg{\cs{renewcommand}\marg{\cs{glsxtrgroupfield}}\marg{dupgroup}} +\end{alltt} + +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{verbatim} +\printunsrtglossary[nogroupskip,style=index] +\printunsrtglossary[type=copies,style=indexgroup] +\end{verbatim} + +\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}. + +\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} +when adjusting the \field{description} field. 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{verbatim} +description={sample\nopostdesc} +\end{verbatim} +since it's at the end. It will also be stripped from +\begin{verbatim} +description={sample\nopostdesc } +\end{verbatim} +since the trailing space is ignored as it follows a control +word. It won't be stripped from +\begin{verbatim} +description={sample\nopostdesc{} } +\end{verbatim} +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{verbatim} +description={sample\nopostdesc\relax} +\end{verbatim} +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 \code{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 \code{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{verbatim} +@entry{whydidnttheyaskevans, + name={Why Didn't They Ask Evans?}, + description={novel by Agatha Christie}, + identifier={book}, + author={\sortmediacreator{Agatha}{Christie}}, + year={1934} +} +\end{verbatim} +With \csopt[name]{check-end-punctuation}, this entry will be +assigned an internal field called +\fielddisp{fieldendpunc}{namendpunc} set to \code{?}\ +as that's included in \code{sentence.terminators} and is found +at the end of the \field{name} field: +\begin{verbatim} +\GlsXtrSetField{whydidnttheyaskevans}{nameendpunc}{?} +\end{verbatim} +(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{verbatim} +Agatha Christie wrote \gls{whydidnttheyaskevans}. +\end{verbatim} +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{verbatim} +\renewcommand*{\glsxtrifcustomdiscardperiod}[2]{% + \GlsXtrIfFieldUndef{nameendpunc}{\glslabel}{#2}{#1}% +} +\end{verbatim} +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]{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). @@ -6888,7 +7637,7 @@ With one of the locale sort methods and with the default Smith|John|Doe|Jane|von|Duck|Dickie \end{verbatim} -\optsection{contributor-order} +\optsection[\subsubsection]{contributor-order} The \gls{bibglscontributor} command is defined in \bibgls's interpreter and its definition is dependent on this @@ -6948,7 +7697,7 @@ The second resource set will use the default \csopt[von]{bibtex-contributor-fields} setting when obtaining the sort value. -\optsection{date-time-fields} +\optsection[\subsubsection]{date-time-fields} This option indicates that the listed fields all contain date and time information. Primary entries will have these fields @@ -6966,7 +7715,7 @@ being parsed if it contains \idx{escchar}, \idx{mshiftchar}, \idx{nbspchar} is converted to the non-breaking space character \hex{A0} unless \longarg{break-space} is used.) -\optsection{date-fields} +\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 @@ -6978,7 +7727,7 @@ The fields are parsed according to \csopt{dual-date-field-format} and \csopt{dual-date-field-locale} for dual entries. -\optsection{time-fields} +\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 @@ -6990,7 +7739,7 @@ The fields are parsed according to \csopt{dual-time-field-format} and \csopt{dual-time-field-locale} for dual entries. -\optsection{date-time-field-format} +\optsection[\subsubsection]{date-time-field-format} This option also sets \csopt[\meta{value}]{dual-date-time-field-format}. @@ -6998,7 +7747,7 @@ 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{date-field-format} +\optsection[\subsubsection]{date-field-format} This option also sets \csopt[\meta{value}]{dual-date-field-format}. @@ -7006,7 +7755,7 @@ 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{time-field-format} +\optsection[\subsubsection]{time-field-format} This option also sets \csopt[\meta{value}]{dual-time-field-format}. @@ -7014,7 +7763,7 @@ 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{date-time-field-locale} +\optsection[\subsubsection]{date-time-field-locale} This option also sets \csopt[\meta{value}]{dual-date-time-field-locale}. @@ -7022,7 +7771,7 @@ 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{date-field-locale} +\optsection[\subsubsection]{date-field-locale} This option also sets \csopt[\meta{value}]{dual-date-field-locale}. @@ -7030,7 +7779,7 @@ 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{time-field-locale} +\optsection[\subsubsection]{time-field-locale} This option also sets \csopt[\meta{value}]{dual-time-field-locale}. @@ -7038,291 +7787,30 @@ The value is the locale used when parsing fields identified by \csopt{time-fields}. The \meta{value} is as for \csopt{date-sort-locale}. -\optsection{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{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{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. - -For example, if the \ext{bib} file contains -\begin{verbatim} -@entry{bird, - name={bird}, - description = {feathered animal, such as a \gls{duck} or \gls {goose}} -} - -@entry{waterfowl, - name={waterfowl}, - description={Any \gls{bird} that lives in or about water}, - see={[see also]{duck,goose}} -} - -@index{duck} - -@index{goose,plural="geese"} -\end{verbatim} -Then if this \ext{bib} file is loaded with \csopt[gls.]{label-prefix} -it's as though the entries had been defined as: -\begin{verbatim} -@entry{gls.bird, - name={bird}, - description = {feathered animal, such as a \gls{gls.duck} or -\gls{gls.goose}} -} - -@entry{gls.waterfowl, - name={waterfowl}, - description={Any \gls{gls.bird} that lives in or about water}, - see={[see also]{gls.duck,gls.goose}} -} - -@index{gls.duck,name={duck}} - -@index{gls.goose,name={goose},plural="geese"} -\end{verbatim} - -Remember to use this prefix when you reference the terms in the -document with commands like \ics{gls}. - -\optsection{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}, \meta{id}\code{.copy2} for -the second duplicate, etc. +\subsection{Case-Changing} +\label{sec:fieldcase} -\optsection{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{verbatim} -\glsxtr@record{bird}{}{page}{glsnumberformat}{1} -\glsxtr@record{waterfowl}{}{page}{glsnumberformat}{1} -\glsxtr@record{idx.duck}{}{page}{glsnumberformat}{1} -\glsxtr@record{idx.goose}{}{page}{glsnumberformat}{1} -\end{verbatim} -The use of \csopt[idx.]{record-label-prefix} makes \bibgls\ act as -though the records were given as: -\begin{verbatim} -\glsxtr@record{idx.bird}{}{page}{glsnumberformat}{1} -\glsxtr@record{idx.waterfowl}{}{page}{glsnumberformat}{1} -\glsxtr@record{idx.duck}{}{page}{glsnumberformat}{1} -\glsxtr@record{idx.goose}{}{page}{glsnumberformat}{1} -\end{verbatim} - - -\optsection{cs-label-prefix} - -If you have commands such as \ics{gls}\margm{label} or -\ics{glstext}\marg{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{verbatim} -@entry{bird, - name={bird}, - description = {feathered animal, such as a \gls{duck} or \gls{goose}} -} -\end{verbatim} -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{verbatim} -description = {feathered animal, such as a \gls{idx.duck} or -\gls{idx.goose}} -\end{verbatim} -However with \csopt[gls.]{cs-label-prefix} the \field{description} -field will be converted to -\begin{verbatim} -description = {feathered animal, such as a \gls{gls.duck} or -\gls{gls.goose}} -\end{verbatim} -regardless of the \csopt{label-prefix} setting. Whereas if the -original entry definition is -\begin{verbatim} -@entry{bird, - name={bird}, - description = {feathered animal, such as a \gls{dual.duck} or -\gls{dual.goose}} -} -\end{verbatim} -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{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}). - -For example, suppose the file \filefmt{entries-terms.bib} contains: -\begin{verbatim} -@entry{set, - name={set}, - description={collection of values, denoted \gls{ext1.set}} -} -\end{verbatim} -and the file \filefmt{entries-symbols.bib} contains: -\begin{verbatim} -@symbol{set, - name={\ensuremath{\mathcal{S}}}, - description={a \gls{ext1.set}} -} -\end{verbatim} - -These files both contain an entry with the label \code{set} -but the \field{description} field includes \verb|\gls{ext1.set}| which is -referencing the entry from the other file. These -two files can be loaded without conflict using: -\begin{verbatim} -\usepackage[record,symbols]{glossaries-extra} - -\GlsXtrLoadResources[src={entries-terms}, - label-prefix={gls.}, - ext-prefixes={sym.} -] - -\GlsXtrLoadResources[src={entries-symbols}, - type=symbols, - label-prefix={sym.}, - ext-prefixes={gls.} -] -\end{verbatim} - -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{verbatim} -collection of values, denoted \gls{sym.set} -\end{verbatim} -The \code{set} entry -from \filefmt{entries-symbols.bib} will be defined with the label -\code{sym.set} and the description will be -\begin{verbatim} -a \gls{gls.set} -\end{verbatim} - -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{verbatim} -@entry{set, - name={set}, - description={collection of values, denoted \gls{ext1.S}} -} -\end{verbatim} -and \filefmt{entries-symbols.bib} could contain: -\begin{verbatim} -@symbol{S, - name={\ensuremath{\mathcal{S}}}, - description={a \gls{ext1.set}} -} -\end{verbatim} -Now they can be combined with: -\begin{verbatim} -\GlsXtrLoadResources[src={entries-terms,entries-symbols}] -\end{verbatim} -which will simply strip the \glsdisp{idx.idprefix.extn}{\idprefixfmt{ext1}} -prefix from the cross-references. Alternatively: -\begin{verbatim} -\GlsXtrLoadResources[src={entries-terms,entries-symbols}, - label-prefix={gls.}, - ext-prefixes={gls.} -] -\end{verbatim} -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{short-case-change} +\optsection[\subsubsection]{short-case-change} The value of the \field{short} field may be automatically converted -to upper or lower case. This option may take one of the following +to \idxlink{uppercase}{upper} or \idx{lowercase}. This option may take one of the following values: \begin{itemize} \item \optfmt{none}: don't apply any case-changing (default); -\item \optfmt{lc}: convert to lower case (ignoring +\item \optfmt{lc}: convert to \idx{lowercase} (ignoring \idx{mshiftchar}\meta{maths}\idx{mshiftchar}, \ics{ensuremath}\margm{maths} and \ics{si}\margm{text}); -\item \optfmt{uc}: convert to upper case (ignoring +\item \optfmt{uc}: convert to \idx{uppercase} (ignoring \idx{mshiftchar}\meta{maths}\idx{mshiftchar}, \ics{ensuremath}\margm{maths} and \ics{si}\margm{text}); -\item \optfmt{lc-cs}: convert to lower case using +\item \optfmt{lc-cs}: convert to \idx{lowercase} using \ics{MakeTextLowercase}; -\item \optfmt{uc-cs}: convert to upper case using +\item \optfmt{uc-cs}: convert to \idx{uppercase} using \ics{MakeTextUppercase}; -\item \optfmt{firstuc-cs}: convert to first letter upper case using +\item \optfmt{firstuc-cs}: convert to first letter \idx{uppercase} using \ics{makefirstuc}; \item \optfmt{firstuc}: convert the first alphabetical letter (or -group) to upper case. This uses the following rules: +group) to \idx{uppercase}. This uses the following rules: \begin{enumerate} \item if \idx{mshiftchar}\meta{maths}\idx{mshiftchar} then stop (no case change); \item if \ics{NoCaseChange}\margm{text} or @@ -7332,7 +7820,7 @@ group) to upper case. This uses the following rules: \item if \csfmt{}\meta{csname} isn't followed by a group (and it's not \ics{protect}), then stop (no case change applied); \item if \margm{text} (a group) then convert the entire contents of -\meta{text} to upper case and stop; +\meta{text} to \idx{uppercase} and stop; \item if \meta{character} is an alphabetic character then change it to its title case and stop; \item otherwise skip and move on to the next token. @@ -7481,308 +7969,22 @@ the result is See \csopt{dual-short-case-change} to adjust the \field{dualshort} field. -\optsection{name-case-change} +\optsection[\subsubsection]{name-case-change} As \csopt{short-case-change} but is applied to the \field{name} field. If the \field{text} field hasn't been set, the \field{name} -value is first copied to the \field{text} field. +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{description-case-change} +\optsection[\subsubsection]{description-case-change} As \csopt{short-case-change} but is applied to the \field{description} field. -\optsection{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{strip-trailing-nopost} - -This option is always performed before \csopt{post-description-dot} -when adjusting the \field{description} field. 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{verbatim} -description={sample\nopostdesc} -\end{verbatim} -since it's at the end. It will also be stripped from -\begin{verbatim} -description={sample\nopostdesc } -\end{verbatim} -since the trailing space is ignored as it follows a control -word. It won't be stripped from -\begin{verbatim} -description={sample\nopostdesc{} } -\end{verbatim} -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{verbatim} -description={sample\nopostdesc\relax} -\end{verbatim} -because again it's not at the end. - -\optsection{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 \code{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 \code{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{verbatim} -@entry{whydidnttheyaskevans, - name={Why Didn't They Ask Evans?}, - description={novel by Agatha Christie}, - identifier={book}, - author={\sortmediacreator{Agatha}{Christie}}, - year={1934} -} -\end{verbatim} -With \csopt[name]{check-end-punctuation}, this entry will be -assigned an internal field called -\fielddisp{fieldendpunc}{namendpunc} set to \code{?}\ -as that's included in \code{sentence.terminators} and is found -at the end of the \field{name} field: -\begin{verbatim} -\GlsXtrSetField{whydidnttheyaskevans}{nameendpunc}{?} -\end{verbatim} -(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{verbatim} -Agatha Christie wrote \gls{whydidnttheyaskevans}. -\end{verbatim} -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{verbatim} -\renewcommand*{\glsxtrifcustomdiscardperiod}[2]{% - \GlsXtrIfFieldUndef{nameendpunc}{\glslabel}{#2}{#1}% -} -\end{verbatim} -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{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{alltt} -\ics{printunsrtglossary*}\oarg{type=copies,style=indexgroup} - \marg{\cs{renewcommand}\marg{\cs{glsxtrgroupfield}}\marg{dupgroup}} -\end{alltt} - -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{verbatim} -\printunsrtglossary[nogroupskip,style=index] -\printunsrtglossary[type=copies,style=indexgroup] -\end{verbatim} - -\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. - -The assignment is done using \ics{GlsXtrSetField} so there's -no associated key. -For example, suppose \filefmt{entries.bib} contains: -\begin{verbatim} -@index{birds} -@index{duck,parent={birds}} -@index{goose,plural={geese},parent={birds}} -@index{swan,parent={birds}} - -@index{minerals} -@index{quartz,parent={minerals}} -@index{corundum,parent={minerals}} -@index{amethyst,parent={minerals}} -@index{gypsum,parent={minerals}} -@index{gold,parent={minerals}} -\end{verbatim} -and the document contains: -\begin{verbatim} -\documentclass{article} - -\usepackage[record,style=indexgroup]{glossaries-extra} - -\GlsXtrLoadResources[src={entries},save-child-count] - -\begin{document} -\gls{duck} and \gls{goose}. -\gls{quartz}, \gls{corundum}, \gls{amethyst}. - -\printunsrtglossaries -\end{document} -\end{verbatim} -Then the \ext{glstex} file will contain: -\begin{verbatim} -\GlsXtrSetField{birds}{childcount}{2} -\GlsXtrSetField{duck}{childcount}{0} -\GlsXtrSetField{goose}{childcount}{0} -\GlsXtrSetField{minerals}{childcount}{3} -\GlsXtrSetField{amethyst}{childcount}{0} -\GlsXtrSetField{corundum}{childcount}{0} -\GlsXtrSetField{quartz}{childcount}{0} -\end{verbatim} -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{verbatim} -\GlsXtrLoadResources[src={entries},category=general,save-child-count] - -\renewcommand{\glsxtrpostdescgeneral}{% - \glsxtrifhasfield{childcount}{\glscurrententrylabel} - { (child count: \glscurrentfieldvalue.)}% - {}% -} -\end{verbatim} -(\ics{glsxtrifhasfield} requires at least \sty{glossaries-extra} v1.19. -It's slightly more efficient that \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.) - -\optsection{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{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}. - \section{Plurals} \label{sec:plurals} @@ -8022,7 +8224,7 @@ 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 lower case Roman first, then digits, +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 @@ -8202,16 +8404,16 @@ $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 lower case Roman numeral, which is converted to +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 upper case Roman numeral, which is converted to +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 lower case letter from \code{a} to -\code{z} or an upper case letter from \code{A} to \code{Z}. +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 @@ -9243,15 +9445,15 @@ rule provided by \csopt{sort-rule}. The sort methods listed in \tableref{tab:sortoptionsletter} use letter case comparators. These simply compare the character codes. The \optfmt{-nocase} options first convert the -\field{sort} field to lower case before performing the sort. +\field{sort} field to \idx{lowercase} before performing the sort. 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. Upper case -and lower case are in separate letter groups. +\item \optfmt{letter-case}: case-sensitive letter sort. +\Idx{uppercase} and \idx{lowercase} are in separate letter groups. Example: \code{Africa} (letter group \qt{A}), \code{Brazil} @@ -9261,7 +9463,8 @@ Example: \item \optfmt{letter-case-reverse}: reverse case-sensitive letter sort. \item \optfmt{letter-nocase}: case-insensitive letter sort. (All -upper case characters will have first been converted to lower case.) +\idx{uppercase} characters will have first been converted to +\idx{lowercase}.) Example: \code{aardvark} (letter group \qt{A}), \code{Africa} @@ -9272,9 +9475,9 @@ Example: \item \optfmt{letter-nocase-reverse}: reverse case-insensitive letter sort. \item \optfmt{letter-upperlower}: each character pair is first -compared according to their lower case values. If these are equal, +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 upper case comes first. +case in the same letter group but the \idx{uppercase} comes first. Example: \code{Africa} (letter group \qt{A}), \code{aardvark} (letter group @@ -9284,9 +9487,9 @@ Example: \item \optfmt{letter-upperlower-reverse}: reverse upper-lower letter sort. \item \optfmt{letter-lowerupper}: each character pair is first -compared according to their lower case 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 lower case comes 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}), @@ -9459,7 +9662,7 @@ letter-number sort. \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 upper case characters in +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}, @@ -9478,7 +9681,8 @@ letter-number sort. \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} -as it will segregate the upper and lower case characters if there +as it will segregate the \idxlink{uppercase}{upper} and +\idx{lowercase} characters if there are any numerical sub-strings. Example: \code{CH\textsubscript{2}O}, @@ -9492,9 +9696,9 @@ are any numerical sub-strings. Example: \code{Co\textsubscript{2}O\textsubscript{3}}. The \csopt[between]{letter-number-rule} setting enforces numbers -after upper-case (for the case-sensitive and upper-lower methods) -which makes the \code{\textsubscript{5}} come after the upper case -\code{O} and forces the lower case characters to come after it. +after \idx{uppercase} (for the case-sensitive and upper-lower methods) +which makes the \code{\textsubscript{5}} come after the \idx{uppercase} +\code{O} and forces the \idx{lowercase} characters to come after it. Compare this with \csopt[before letter]{letter-number-rule} which results in the order: @@ -9527,16 +9731,16 @@ Example: \code{CH\textsubscript{2}O}. The algorithm is reversed which means that when two letters are -compared then, if both letters have the same lower case version, -the upper-lower rule is reversed and lower case comes before -upper case. This means that \code{o} comes before \code{O}. -If their lower case versions aren't identical, the letter -with the higher lower case Unicode value comes first. This means +compared then, if both letters have the same \idx{lowercase} version, +the upper-lower rule is reversed and \idx{lowercase} comes before +\idx{uppercase}. This means that \code{o} comes before \code{O}. +If their \idx{lowercase} versions aren't identical, the letter +with the higher \idx{lowercase} Unicode value comes first. This means that both \code{o} and \code{O} come before \code{l} which comes before \code{H}. So far, this gives the order: \code{o}, \code{O}, \code{l}, \code{H}. The \csopt[between]{letter-number-rule} setting inserts numbers between -upper and lower case letters. This puts the numbers (in reverse +\idxlink{uppercase}{upper} and \idx{lowercase} letters. This puts the numbers (in reverse order) between \code{o} and \code{O}. Compare this with \csopt[before letter]{letter-number-rule} which @@ -9573,9 +9777,9 @@ Example: \code{CO}. The \csopt[between]{letter-number-rule} setting enforces numbers -after lower-case (for the lower-upper method) +after \idx{lowercase} (for the lower-upper method) so the \code{\textsubscript{5}} is put after \code{o}, and forces -the upper case characters after the numbers. +the \idx{uppercase} characters after the numbers. Compare this with \csopt[before letter]{letter-number-rule} which results in the order: @@ -9925,6 +10129,26 @@ 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 regular expression substitutions +on the sort value and has the same syntax as \csopt{labelify-replace}. +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{verbatim} +\ensuremath{\approx 3.14} +\end{verbatim} +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 @@ -10080,6 +10304,16 @@ 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 command) +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} @@ -10093,12 +10327,12 @@ For example, the sort value \qt{Tom, Dick, and Harry} becomes characters. \item \optfmt{character}: break after each character. \item \optfmt{sentence}: break after each sentence. -\item \optfmt{upper-notlower}: break after any upper case character -that's not followed by a lower case character. For example, +\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 upper case character -that's followed by an upper case character. +\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}. @@ -10106,7 +10340,8 @@ according to \optfmt{upper-notlower} and then according to 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. +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. @@ -10616,9 +10851,10 @@ letter. letter. \item\optfmt{between}: (default) numbers come between letter cases. With the \optfmt{-case} or \optfmt{-upperlower} sort options, -this will put numbers after upper case and before lower case. +this will put numbers after \idx{uppercase} and before +\idx{lowercase}. With the \optfmt{-lowerupper} sort option, this will put numbers -after lower case and before upper case. This setting doesn't make +after \idx{lowercase} and before \idx{uppercase}. This setting doesn't make much sense with the \optfmt{-nocase} option but, if used, this will put numbers before letters. \item\optfmt{first}: numbers are considered less than all @@ -10628,8 +10864,8 @@ 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 lower case, which means that -if you use one of them then there won't be any upper case +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 @@ -10846,7 +11082,7 @@ Then the entries can be sorted by date of birth using: \end{verbatim} The \code{G} (era) date pattern specifier expects a string, such as -\qt{AD}. It will match lower case forms, such as \qt{ad}, so if you +\qt{AD}. It will match \idx{lowercase} forms, such as \qt{ad}, so if you have \verb|\textsc{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 @@ -10905,15 +11141,15 @@ setting. \item\optfmt{codepoint}: the group is set to \icswithargs{bibglsunicodegroup}, where the first argument is the -first significant character (converted to lower case and decomposed, +first significant character (converted to \idx{lowercase} and decomposed, if applicable) of the sort value. \item\optfmt{unicode category}: the group is set to \icswithargs{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 lower case letter and \code{Lu} signifies an upper case -letter. +signifies a \idx!{lowercase} letter and \code{Lu} signifies an +\idx!{uppercase} letter. \item\optfmt{unicode script}: the group is set to \icswithargs{bibglsunicodegroup}, where the first argument is the @@ -10927,7 +11163,7 @@ that are often used with non-Greek scripts). \icswithargs{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 lower case Latin letter. +\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 @@ -11094,6 +11330,10 @@ As \csopt{missing-sort-fallback} but for secondary sorting. 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. @@ -11303,7 +11543,7 @@ file (or created through a mapping). The \meta{value} is required. The \meta{value} may be: \begin{itemize} \item \optfmt{same as entry}: sets the \field{type} to the entry -type (lower case and without +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}. @@ -11312,7 +11552,7 @@ 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 (lower case and without +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). @@ -11361,7 +11601,7 @@ file (or created through a mapping). The \meta{value} may be empty. The \meta{value} may be: \begin{itemize} \item \optfmt{same as entry}: sets the \field{category} to the entry -type (lower case and without +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}. @@ -11370,7 +11610,7 @@ 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 (lower case and without +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). @@ -11411,7 +11651,9 @@ to the start of the \iext{glstex} file providing the key given by \meta{value}. Any entries defined using \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 \code{dual} is assumed. +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{verbatim} @@ -11531,6 +11773,10 @@ As \csopt{missing-sort-fallback} but for dual sorting. 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}. @@ -11820,13 +12066,39 @@ defined with \atentry{dualsymbol} instead of \atentry{dualentry}. Analogous to \csopt{dual-entry-backlink} but for entries defined with \atentry{dualabbreviationentry} instead of -\atentry{dualentry}. +\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{verbatim} +\renewcommand*{\glsuserdescription}[2]{% + \GlsXtrDualBackLink{\glslonguserfont{#1}}{#2}% +} +\setabbreviationstyle{long-short-user} +\GlsXtrLoadResources[src={entries},dual-field] +\end{verbatim} \optsection[\subsubsection]{dual-entryabbrv-backlink} -Analogous to \csopt{dual-entry-backlink} but for entries +As \csopt{dual-abbrventry-backlink} but for entries defined with \atentry{dualentryabbreviation} instead of -\atentry{dualentry}. +\atentry{dualabbreviationentry}. \optsection[\subsubsection]{dual-indexentry-backlink} @@ -11919,7 +12191,7 @@ file is: \longnewglossaryentry*{#1}{name={#3},#2}{#4}% } \end{verbatim} -This uses the starred form of \gls{longnewglossaryentry} that +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). @@ -11970,15 +12242,29 @@ file is: \newglossaryentry{#1}{name={#1},category={index},description={},#2}% } \end{verbatim} -This makes the \field{name} default to the \meta{label}, assigns the +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 post-description hook used by +\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{verbatim} +\providecommand{\bibglsnewindexplural}[3]{% + \newglossaryentry{#1}{name={#3},category={indexplural},description={},#2}% +} +\end{verbatim} +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} @@ -12771,7 +13057,7 @@ according to the rule): 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 \code{grouptitle.case.\meta{lc}} exists, where -\meta{lc} is the lower case version of \meta{title}, then the value +\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} @@ -12779,7 +13065,7 @@ should be converted to \qt{IJ}, so \file{bib2gls-en.xml} includes: \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 lower case or may +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 @@ -12799,6 +13085,51 @@ This field needs to expand to a simple label, which \csref{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{verbatim} +\bibglssetlastgrouptitle{\bibglslettergroup}{{Ø}{Ø}{2147418112}{}} +\end{verbatim} +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{verbatim} +\newcommand*{\bibglssetlastgrouptitle}[2]{% + \glsxtrsetgrouptitle{#1#2}{Foreign Words}} + +\GlsXtrLoadResources[sec={entries}] +\end{verbatim} +If you need to change a particular group title, then it has to be +done after the \idx{resourceset}: +\begin{verbatim} +\GlsXtrLoadResources[sec={entries}] + +\glsxtrsetgrouptitle + {\bibglslettergroup{{Ø}{Ø}{2147418112}{}}}% label + {Foreign Words}% title +\end{verbatim} + \cssection{bibglssetlettergrouptitle} For each \idx{lettergroup} that's detected, \bibgls\ will write the line: @@ -13105,11 +13436,11 @@ obtained from \cs{bibglsunicodegrouptitle}. 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 lower case and +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 upper case letter); +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}); @@ -13136,7 +13467,7 @@ whereas with \csopt[unicode category and script]{group-formation} it will be: \begin{verbatim} group={\bibglsunicodegroup{Lu.LATIN}{Å}{C5}{}} \end{verbatim} -(upper case Latin letter). +(\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: @@ -14358,6 +14689,30 @@ doesn't occur in the \field{description} field. (Note that 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} +entry-type-aliases=\marg{\ics{GlsXtrBibTeXEntryAliases}} +\end{codeenv} +The field names will also need to be defined or aliased. For +example: +\begin{codeenv} +field-aliases=\marg{title=name} +\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 @@ -14368,7 +14723,7 @@ 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 lower case Latin \qt{o}). Note that +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}). @@ -14400,7 +14755,7 @@ but \LaTeX\ needs a definition for this, so it's provided in the \end{verbatim} (With \sty{glossaries-extra} v1.27+, this is no longer needed.) The \TeX\ parser library and \sty{glossaries-extra-bib2gls} -similarly provide the missing upper case +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: @@ -16042,7 +16397,7 @@ field with \csopt{field-aliases}: \csopt[author=parent]{field-aliases} \end{codeenv} but the author's label in the \exfile{people.bib} -file is just the lower case surname. +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 @@ -16117,8 +16472,6 @@ The resulting document is shown in \figureref{fig:sample-authors.pdf}. \lstinputlisting[firstline=5]{../examples/sample-authors.tex} -\lstinputlisting[firstline=5]{../examples/sample-authors.tex} - \begin{figure} \figcontents {% @@ -16128,6 +16481,167 @@ The resulting document is shown in \figureref{fig: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{verbatim} +\usepackage[record,% using bib2gls +nomain,% don't define main glossary +postdot,% full stop after descriptions +nostyles,% don't load default styles +% load glossary-tree and glossary-list and patch styles: +stylemods={tree,list} +]{glossaries-extra} +\end{verbatim} +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 \ics{bibglsnewbibtexentry} that assigns +\field{type} after the options: +\begin{codeenv} +\cs{newcommand}\marg{\cs{bibglsnewbibtexentry}}[4]\marg{\idx{commentchar} + \gls{longnewglossaryentry}*\marg{\idx{param}1}\marg{name=\marg{\idx{param}3},\idx{param}2,type=\marg{titles}}\marg{\idx{param}4}\idx{commentchar} +} +\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[title=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[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[name]{sort-suffix} +\end{codeenv} + +Next the groups identified by the labels \code{article} and \code{book} +are assigned titles. +\begin{codeenv} +\cs{glsxtrsetgrouptitle}\marg{article}\marg{Articles} +\cs{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*}[type=titles,style=indexgroup] +\marg{\idx{commentchar} + \cs{renewcommand}\marg{\cs{glsxtrgroupfield}}\marg{category}\idx{commentchar} + \cs{renewcommand}\marg{\cs{glstreenamefmt}}[1]\marg{\cs{emph}\marg{\idx{param}1}}\idx{commentchar} + \cs{renewcommand}\marg{\cs{glstreegroupheaderfmt}}[1]\marg{\ics{textbf}\marg{\idx{param}1}}\idx{commentchar} +} +\end{codeenv} +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}[type=contributors,style=altlist] +\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{\idx{commentchar} + \ics{glsxtrifhasfield}\marg{bibtexentry}\marg{\cs{glscurrententrylabel}}\idx{commentchar} + \marg{\idx{commentchar} + \cs{glsxtrfieldforlistloop} + \marg{\cs{glscurrententrylabel}}\marg{bibtexentry}\idx{commentchar} + \marg{\csfmt{contributorhandler}}\idx{commentchar} + }\idx{commentchar} + \marg{\ics{par} No titles.}\idx{commentchar} +} +\end{codeenv} +The 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 --group --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}, @@ -16430,7 +16944,7 @@ 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 uppercase: +convert the letter to \idx{uppercase}: \begin{verbatim} \renewcommand*{\glsxtrtagfont}[1]{\underline{\MakeTextUppercase{#1}}} \end{verbatim} @@ -16471,7 +16985,7 @@ 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 -uppercase. Since the \field{name} is implicitly set for +\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}: @@ -17149,7 +17663,7 @@ rule for the duals, but with the numbers padded: \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 lower case characters in the way that can be achieved with the +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} @@ -17865,6 +18379,7 @@ The resulting document is shown in \figureref{fig:sample-multi2.pdf}, {fig:sample-multi2.pdf3} \end{figure} +\printstyoptsummary \printcommandsummary \bibliographystyle{plain} diff --git a/Master/texmf-dist/source/support/bib2gls/src/gls2bib-src.zip b/Master/texmf-dist/source/support/bib2gls/src/gls2bib-src.zip Binary files differindex a1c68c3145c..b97f4db2a6f 100644 --- a/Master/texmf-dist/source/support/bib2gls/src/gls2bib-src.zip +++ b/Master/texmf-dist/source/support/bib2gls/src/gls2bib-src.zip diff --git a/Master/texmf-dist/source/support/bib2gls/src/texparser-src.zip b/Master/texmf-dist/source/support/bib2gls/src/texparser-src.zip Binary files differindex 0852ab1d89a..605e8238ebd 100644 --- a/Master/texmf-dist/source/support/bib2gls/src/texparser-src.zip +++ b/Master/texmf-dist/source/support/bib2gls/src/texparser-src.zip |