summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex')
-rw-r--r--Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex2449
1 files changed, 2217 insertions, 232 deletions
diff --git a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex
index fcb6fd34bae..f7ba9c27ef0 100644
--- a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex
+++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex
@@ -2,12 +2,13 @@
% arara: bib2gls: {group: on} if missing("glstex") || changed("bib") || found("log", "Warning: Glossary entry")
% arara: bibtex
% arara: lualatex if changed("glstex") || missing("toc")
-% arara: bib2gls: {group: on}
+% arara: bib2gls: {group: on, packages: [mfirstuc-english]}
% arara: lualatex
% arara: lualatex if found ("log", "Rerun")
\documentclass[titlepage=false,index=totoc,bibliography=totoc,
fontsize=12pt,captions=tableheading]{scrreprt}
+\usepackage[autooneside=false]{scrlayer-scrpage}
\usepackage{pifont}
% Need support for extended characters
@@ -26,6 +27,8 @@
\newcommand{\insularG}{{\freeserif\char"A77D}}
\newcommand{\insularg}{{\freeserif\char"1D79}}
\newcommand{\longs}{\char"017F}
+\newcommand{\Wynn}{\char"01F7}
+\newcommand{\wynn}{\char"01BF}
\usepackage[x11names]{xcolor}
\usepackage{alltt}
@@ -37,6 +40,7 @@
\usepackage{amsmath}
\usepackage{accents}
\usepackage{tikz}
+\usepackage{tcolorbox}
\usepackage{datetime2}
\usepackage{listings}
\usepackage[hidelinks]{hyperref}
@@ -59,6 +63,7 @@
\glsxtrprovidestoragekey{note}{}{}
\glsxtrprovidestoragekey{package}{}{}
+\glsxtrprovidestoragekey{nametitle}{}{}
\providecommand{\omicron}{o}
@@ -98,6 +103,7 @@
\newcommand{\glsxtrpostnamecounter}{\space counter}
\newcommand*{\csfmtfont}[1]{\texttt{#1}}
+\newcommand*{\csfmtcolourfont}[1]{\texttt{\textcolor{cs}{#1}}}
\newcommand*{\csfmt}[1]{%
\texorpdfstring
@@ -105,9 +111,47 @@
{\string\\#1}%
}
-\setabbreviationstyle[common]{short-nolong}
+\newcommand{\texparserdefprefix}{}
+\newcommand{\texparserdefnotetarget}{%
+ \raisebox{2ex}{\hypertarget{\texparserdefprefix texparserdef}{}}%
+ \textsuperscript{*}Indicates command is
+ recognised by \bibgls's interpreter although it may have
+ a slightly different implementation.
+}
+\newcommand{\texparserdefnote}{\hyperlink{\texparserdefprefix texparserdef}{*}}
+
+\setabbreviationstyle{long-short-sc}
+\setabbreviationstyle[common]{short-sc-nolong}
+
+\glsxtrprovidestoragekey{unsortedprogeny}{}{}
\GlsXtrLoadResources[
+ entry-type-aliases={
+ bibglscommand=dualindexentry,
+ mainglscommand=spawndualindexentry,
+ glscommand=spawnentry,
+ abbrvstylecommand=spawnentry,
+ glostylecommand=spawnentry,
+ resourceoption=dualindexentry,
+ packageoption=dualindexentry,
+ field=dualindexentry,
+ entrytype=dualindexentry,
+ switch=dualindexentry,
+ samplefile=dualindexentry,
+ examplecommand=dualindexentry,
+ examplesymbol=symbol,
+ exampleabbreviation=abbreviation,
+ exampleentry=entry
+ },
+ field-aliases={topics=adoptparents},
+ replicate-fields={name=nametitle,progeny=unsortedprogeny},
+ field-case-change={nametitle=title},
+ interpret-fields={nametitle},
+ no-case-change-cs={fieldfmt,abbrstylefmt,glostylefmt},
+ short-case-change={lc},
+ dual-short-case-change={lc},
+ unknown-entry-alias={index},
+ save-original-entrytype,
label-prefix={idx.},
save-loclist=false,
sort={letternumber-nocase},
@@ -115,11 +159,20 @@
type={index},
dual-field={dualid},
match-action={add},
- match={{category}={.*field}},
+ match-op={or},
+ match={
+ {category}={.*field},
+ {original entrytype}={.*(gls|style)command},
+ {original entrytype}={.*option},
+ {original entrytype}={abbreviationstyle},
+ {original entrytype}={glossarystyle},
+ },
dual-prefix={},
dual-type={main},
combine-dual-locations={primary},
selection={recorded and deps and see},
+ symbol-sort-fallback={name},
+ sort-label-list={progeny:letter-nocase:glsxtrentryparentname},
strip-missing-parents,
save-child-count
]
@@ -146,7 +199,8 @@
\newcommand{\frontmatter}{%
\clearpage\pagenumbering{roman}%
- \pagestyle{headings}%
+ \pagestyle{scrheadings}%
+ \automark[section]{chapter}%
\mainmatterfalse
}
\newcommand{\mainmatter}{%
@@ -155,6 +209,27 @@
\mainmattertrue
}
+\newcommand{\rightleftmark}[2]{\ifstrequal{#1}{#2}{#1}{#1: #2}}
+\makeatletter
+\newcommand{\setsecdepth}{\@ifstar\s@setsecdepth\@setsecdepth}
+\newcommand{\s@setsecdepth}[1]{%
+ \setcounter{secnumdepth}{#1}%
+ \automark[section]{chapter}%
+ \let\@rightmark\rightleftmark
+}
+\newcommand{\@setsecdepth}[1]{%
+ \setcounter{secnumdepth}{#1}%
+ \ifnum#1 > 0
+ \automark[section]{chapter}%
+ \else
+ \automark{chapter}%
+ \fi
+ \let\@rightmark\@secondoftwo
+}
+\makeatother
+
+\newtcolorbox{important}{colback=red!5!white,colframe=red}
+
\newcommand{\bibgls}{\appfmt{bib2gls}}
\newcommand*{\BibTeX}{\hologo{BibTeX}}
@@ -308,19 +383,29 @@
\newcommand{\glsxtrpostdescenvironment}{environment}
\newcommand*{\abbrstyle}[1]{%
- \texorpdfstring{\idx{#1}}{#1}%
+ \texorpdfstring{\idx{abbrstyle.#1}}{#1}%
+}
+
+\newcommand*{\topicabbrstyle}[1]{%
+ %\texorpdfstring{\idx[prefix=topic.]{abbrstyle.#1}}{#1}%
+ \texorpdfstring{\idx{abbrstyle.#1}}{#1}%
}
\newcommand*{\glostyle}[1]{%
\texorpdfstring{\idx{glostyle.#1}}{#1}%
}
+\newcommand*{\topicglostyle}[1]{%
+ %\texorpdfstring{\idx[prefix=topic.]{glostyle.#1}}{#1}%
+ \texorpdfstring{\idx{glostyle.#1}}{#1}%
+}
+
\newcommand*{\iglostyle}[1]{%
\texorpdfstring{\idx[noindex=false]{glostyle.#1}}{#1}%
}
\newcommand*{\catattr}[1]{%
- \texorpdfstring{\idx{#1}}{#1}%
+ \texorpdfstring{\idx{catattr.#1}}{#1}%
}
\newcommand*{\counter}[1]{%
@@ -502,11 +587,22 @@
\renewenvironment{theglossary}%
{%
\setlength{\glsdescwidth}{\dimexpr\linewidth-\maxnamewidth-4\tabcolsep}%
- \begin{tabular}{l>{\raggedright}p{\glsdescwidth}}%
+ \begin{longtable}{l>{\raggedright}p{\glsdescwidth}}%
}%
- {\end{tabular}}%
+ {\end{longtable}}%
\renewcommand*{\glossaryheader}{%
- \bfseries Field & \bfseries Description\tabularnewline}%
+ \noalign{\xdef\dofieldtabcaption{%
+ \noexpand\caption\expandonce\fieldtablelotcaption
+ {\expandonce\fieldtablecaption}}}%
+ \dofieldtabcaption
+ \fieldtablecaptionlabel
+ \fieldtablepostcaption\tabularnewline
+ \bfseries Field & \bfseries Description\tabularnewline
+ \endfirsthead
+ \caption*{\fieldtablecaption\ (Continued)}\tabularnewline
+ \bfseries Field & \bfseries Description\tabularnewline
+ \endhead
+ }%
\renewcommand*{\glsgroupheading}[1]{}%
\renewcommand{\glossentry}[2]{%
\glsadd{##1}%
@@ -529,11 +625,36 @@
\newlength\maxnamewidth
-\newcommand*{\printfields}[1]{%
+%\printfields[postcaption]{category list}[lot caption]{caption}{label}
+\newcommand*{\printfields}[2][]{%
+ \ifstrempty{#1}%
+ {%
+ \def\fieldtablepostcaption{}%
+ }%
+ {%
+ \def\fieldtablepostcaption{%
+ \tabularnewline
+ \multicolumn{2}{p{\linewidth}}{#1}%
+ \tabularnewline
+ }%
+ }%
+ \def\fieldcategories{#2}%
+ \innerprintfields
+}
+
+\newcommand*{\innerprintfields}[3][]{%
\printunsrtglossary*[style=fieldstyle]{%
\renewcommand*\glossarysection[2][]{}%
+ \ifstrempty{#1}%
+ {%
+ \def\fieldtablelotcaption{}%
+ }%
+ {%
+ \def\fieldtablelotcaption{[#1]}%
+ }%
+ \def\fieldtablecaption{#2}%
+ \def\fieldtablecaptionlabel{\label{#3}}%
\setlength{\maxnamewidth}{0pt}%
- \def\fieldcategories{#1}%
\let\printunsrtglossaryentryprocesshook\fieldhook
}%
}
@@ -550,6 +671,24 @@
}%
}
+\newcommand{\summarysubheaderfont}[1]{\textbf{\sffamily #1}}
+
+\newcommand{\summaryoptionhandler}[1]{%
+ \par\smallskip\nopagebreak
+ \par\noindent\hspace{1em}%
+ \code{\gls{#1}\glsxtrifhasfield{useri}{#1}{=\glscurrentfieldvalue}{}}%
+ \glsxtrifhasfield{note}{#1}%
+ {\nolinebreak\hfill\mbox{\footnotesize\glscurrentfieldvalue}}%
+ {}%
+ \nopagebreak\par\hangindent2em\noindent\hspace{2em}\Glossentrydesc{#1}%
+}
+
+\newrobustcmd{\donote}[1]{%
+ \glsxtrifhasfield{note}{#1}%
+ {\nolinebreak\hfill\mbox{\normalfont\footnotesize\glscurrentfieldvalue}}%
+ {}%
+}
+
\newglossarystyle{commandsummary}%
{%
\setglossarystyle{index}%
@@ -564,51 +703,62 @@
\glstreeitem \glstarget{cs.##1}{\strut}%
\glsxtrifhasfield{dualid}{##1}%
{%
- \glshyperlink{\glscurrentfieldvalue}%
+ {%
+ \let\csfmtfont\csfmtcolourfont
+ \glshyperlink{\glscurrentfieldvalue}%
+ }%
\glsxtrifhasfield{useri}{##1}{\glscurrentfieldvalue}{}%
- \glsxtrifhasfield{note}{##1}%
- {\nolinebreak\hfill\mbox{\footnotesize\glscurrentfieldvalue}}%
- {}%
+ \donote{##1}%
\nopagebreak\par\hspace{10pt}%
\Glossentrydesc{\glscurrentfieldvalue}%
\ifglshasdesc{\glscurrentfieldvalue}{\@. }{}%
}%
{%
- \gls[hyper=false]{##1}%
+ {\let\csfmtfont\csfmtcolourfont\gls[hyper=false]{##1}}%
\glsxtrifhasfield{useri}{##1}{\glscurrentfieldvalue}{}%
- \glsxtrifhasfield{note}{##1}%
- {\nolinebreak\hfill\mbox{\footnotesize\glscurrentfieldvalue}}%
- {}%
+ \donote{##1}%
\nopagebreak\par\hspace{10pt}%
\Glossentrydesc{##1}%
\ifglshasdesc{##1}{\@. }{}%
}%
- \GlsXtrIfHasNonZeroChildCount{##1}%
- {This command has \glscurrentfieldvalue\ forms:}{}%
+ \GlsXtrIfFieldEqStr{originalentrytype}{##1}{glscommand}%
+ {%
+ % Does this entry have options?
+ \GlsXtrIfHasNonZeroChildCount{##1}%
+ {%
+ \glspar\medskip\glspar
+ \summarysubheaderfont{Options:}
+ \glsxtrfieldforlistloop{##1}{childlist}{\summaryoptionhandler}%
+ }%
+ {}%
+ }%
+ {%
+ \GlsXtrIfHasNonZeroChildCount{##1}%
+ {This command has \glscurrentfieldvalue\ forms:}{}%
+ }%
+ %\listtopics{##1}%
\par\medskip
}%
\renewcommand*{\subglossentry}[3]{%
\glstreesubitem \glstarget{cs.##2}{\strut}%
\glsxtrifhasfield{dualid}{##2}%
{%
- \glshyperlink{\glscurrentfieldvalue}%
+ {%
+ \let\csfmtfont\csfmtcolourfont
+ \glshyperlink{\glscurrentfieldvalue}%
+ }%
\glsxtrifhasfield{useri}{##2}{\glscurrentfieldvalue}{}%
- \glsxtrifhasfield{note}{##2}%
- {\nolinebreak\hfill\mbox{\footnotesize\glscurrentfieldvalue}}%
- {}%
+ \donote{##2}%
\nopagebreak\par\hspace{20pt}%
- \Glossentrydesc{\glscurrentfieldvalue}%
- \ifglshasdesc{\glscurrentfieldvalue}{.}{}%
+ \ifglshasdesc{\glscurrentfieldvalue}%
+ {\Glossentrydesc{\glscurrentfieldvalue}.}{}%
}%
{%
- \gls[hyper=false]{##2}%
+ {\let\csfmtfont\csfmtcolourfont\gls[hyper=false]{##2}}%
\glsxtrifhasfield{useri}{##2}{\glscurrentfieldvalue}{}%
- \glsxtrifhasfield{note}{##2}%
- {\nolinebreak\hfill\mbox{\footnotesize\glscurrentfieldvalue}}%
- {}%
+ \donote{##2}%
\nopagebreak\par\hspace{20pt}%
- \Glossentrydesc{##2}%
- \ifglshasdesc{##2}{.}{}%
+ \ifglshasdesc{##2}{\Glossentrydesc{##2}.}{}%
}%
\par\medskip
}%
@@ -617,22 +767,226 @@
\newcommand*{\commandsummaryhook}[1]{%
\edef\currentcategory{\glscategory{#1}}%
\ifdefstring{\currentcategory}{command}%
- {}%
+ {%
+ \glsxtrifhasfield*{progenitor}{#1}%
+ {\printunsrtglossaryskipentry}{}%
+ }%
{\printunsrtglossaryskipentry}%
}
\newcommand*{\printcommandsummary}{%
\printunsrtglossary*[type=index,
style=commandsummary,
- title={Command Summary}
+ title={General Command Summary},
]%
{%
+ \def\glossarypreamble{This is an alphabetical summary of
+ commands referenced in this document. See the
+ relevent user guides for further details.\endgraf\medskip
+ \texparserdefnotetarget}%
\let\printunsrtglossaryentryprocesshook\commandsummaryhook
\let\csref\cs
\glsxtrlocalsetgrouptitle{glssymbols}{}%
}%
}
+\newcommand{\topicxrhandler}[1]{%
+ \glsxtrifhasfield{parent}{#1}%
+ {%
+ \let\field\fieldfmt
+ \hyperlink
+ {topic.\glscurrentfieldvalue}%
+ {\glsentryname{\glscurrentfieldvalue}}%
+ }%
+ {%
+ \hyperlink{topic.#1}{\glsentryname{#1}}%
+ }%
+}
+
+% \iffirstprogeny{entry label}{topic label}{true}{false}
+\makeatletter
+\newcommand{\iffirstprogeny}[2]{%
+ \let\doiffirstprogeny\@secondoftwo
+ \def\firstprogeny{}%
+ \glsxtrifhasfield*{unsortedprogeny}{#1}%
+ {%
+ \edef\suppliedprogeny{#2}%
+ \@for\thisprogeny:=\glscurrentfieldvalue\do{%
+ \let\firstprogeny\thisprogeny
+ \ifdefequal{\thisprogeny}{\suppliedprogeny}%
+ {\let\doiffirstprogeny\@firstoftwo}%
+ {\let\doiffirstprogeny\@secondoftwo}%
+ \@endfortrue
+ }%
+ }%
+ {}%
+ \doiffirstprogeny
+}
+\makeatother
+
+\newcommand{\ifstylecommand}[1]{%
+ \letcs\doifstylecommand{@firstoftwo}%
+ \GlsXtrIfFieldEqStr{originalentrytype}{#1}{abbrvstylecommand}%
+ {}%
+ {%
+ \GlsXtrIfFieldEqStr{originalentrytype}{#1}{glostylecommand}%
+ {}%
+ {\global\letcs\doifstylecommand{@secondoftwo}}%
+ }%
+ \doifstylecommand
+}
+
+\newcommand{\listtopics}[1]{%
+ \glsxtrifhasfield{progeny}{#1}%
+ {%
+ \ifdefequal\glscurrentfieldvalue\glscurrententrylabel
+ {}%
+ {%
+ \par\nopagebreak\medskip\par\footnotesize
+ \sloppy
+ \ifstylecommand{#1}%
+ {\summarysubheaderfont{Styles:}}%
+ {\summarysubheaderfont{Topics:}}%
+ \space
+ \let\DTLlistformatitem\topicxrhandler
+ \DTLformatlist{\glscurrentfieldvalue}.\par
+ }%
+ }%
+ {}%
+}
+
+\newglossarystyle{commandtopic}%
+{%
+ \setglossarystyle{index}%
+ %\renewcommand*{\glossaryheader}{\raggedright}%
+ \renewcommand*{\glsgroupheading}[1]{}%
+ \renewcommand*{\glossentry}[2]{%
+ \glsfieldfetch{##1}{nametitle}{\thisvalue}%
+ \section*{%
+ \raisebox{2ex}%
+ {\pdfbookmark[1]{\thisvalue}{topic.##1}\hypertarget{topic.##1}{}}%
+ \glsdisp{##1}{\thisvalue}\donote{##1}%
+ }%
+ \expandafter\sectionmark\expandafter{\thisvalue}%
+ \ifglshasdesc{##1}{\Glossentrydesc{##1}.}{}%
+ \glsxtrifhasfield{seealso}{##1}%
+ {%
+ \par\smallskip
+ \emph{See also:}
+ \let\DTLlistformatitem\topicxrhandler
+ \DTLformatlist{\glscurrentfieldvalue}.%
+ \par\medskip\par
+ }%
+ {}%
+ }%
+ \renewcommand*{\subglossentry}[3]{%
+ \glsifcategory{##2}{command}%
+ {%
+ \glsdohypertarget{topic.##2}{\strut}%
+ \glsxtrifhasfield*{progenitor}{##2}%
+ {\let\originallabel\glscurrentfieldvalue}%
+ {\def\originallabel{##2}}%
+%
+ \ifstylecommand{##2}%
+ {%
+ \iffirstprogeny{\originallabel}{##2}%
+ {\letcs\dothisentry{@firstofone}}%
+ {%
+ \glspar
+ \ifdefempty\firstprogeny
+ {%
+ {\let\csfmtfont\csfmtcolourfont\gls[noindex]{\originallabel}}%
+ \glsxtrifhasfield{useri}{##2}{\glscurrentfieldvalue}{}%
+ }%
+ {%
+ {\let\csfmtfont\csfmtcolourfont
+ \hyperlink{topic.\firstprogeny}{\glsentryname{\firstprogeny}}}%
+ \glsxtrifhasfield{useri}{##2}{\glscurrentfieldvalue}{}%
+ \glsxtrifhasfield{parent}{\firstprogeny}%
+ {\hfill
+ {\footnotesize\emph{see} \hyperlink{topic.\glscurrentfieldvalue}%
+ {\glsentryname{\glscurrentfieldvalue}}.}}
+ {}%
+ }%
+ \letcs\dothisentry{@gobble}%
+ }%
+ }%
+ {\letcs\dothisentry{@firstofone}}%
+ \dothisentry
+ {%
+ \par\smallskip\par
+ % hyperlink to index:
+ {\let\csfmtfont\csfmtcolourfont\gls[format=glsignore]{\originallabel}}%
+ \glsxtrifhasfield{useri}{##2}{\glscurrentfieldvalue}{}%
+ \glsxtrifhasfield{note}{##2}%
+ {\nolinebreak\hfill\mbox{\footnotesize\glscurrentfieldvalue}}%
+ {}%
+ \nopagebreak\par\smallskip\par\nopagebreak
+ \ifglshasdesc{##2}{\Glossentrydesc{##2}.}{}%
+ % Topics
+ \listtopics\originallabel
+ \par\smallskip
+ }%
+ }%
+ {%
+ \glsfieldfetch{##2}{nametitle}{\thisvalue}%
+ \subsection*{%
+ \raisebox{2ex}%
+ {\hypertarget{topic.##2}{}\pdfbookmark[2]{\thisvalue}{topic.##2}}%
+ \glsdisp{##2}{\thisvalue}\donote{##2}%
+ }%
+ \expandafter\subsectionmark\expandafter{\thisvalue}%
+ \ifglshasdesc{##2}{\Glossentrydesc{##2}.\glspar\nopagebreak\smallskip}{}%
+ }%
+ }%
+}
+
+\newcommand*{\commandtopichook}[1]{%
+ \glsxtrifhasfield*{progenitor}{#1}%
+ {}%
+ {%
+ \GlsXtrIfFieldEqStr*{originalentrytype}{#1}{topic}%
+ {}%
+ {%
+ \glsxtrifhasfield*{parent}{#1}%
+ {%
+ \GlsXtrIfFieldEqStr*{originalentrytype}{\glscurrentfieldvalue}{topic}%
+ {}%
+ {\printunsrtglossaryskipentry}%
+ }%
+ {\printunsrtglossaryskipentry}%
+ }%
+ }%
+}
+
+\newcommand*{\printcommandtopic}{%
+ \setsecdepth*{0}%
+ \automark[subsection]{section}%
+ \printunsrtglossary*[type=index,
+ style=commandtopic,
+ title={Summary by Topic of Glossary Commands},
+ label={sec:topics},
+ nogroupskip,
+ nonumberlist
+ ]%
+ {%
+ \def\texparserdefprefix{topic.}%
+ \def\glossarypreamble{This is a summary of commands provided
+ by \styfmt{glossaries}, \styfmt{glossaries-extra} and
+ their supplementary packages that may be useful to
+ \bibgls\ users. Commands specific to other indexing methods
+ aren't listed unless they've been referenced in this manual.
+ See the appropriate user guides for further details.
+ \endgraf\medskip
+ \texparserdefnotetarget}%
+ \let\abbrstyle\topicabbrstyle
+ \let\glostyle\topicglostyle
+ \let\printunsrtglossaryentryprocesshook\commandtopichook
+ \let\csref\cs
+ }%
+ \setsecdepth{0}%
+}
+
\newglossarystyle{styoptsummary}%
{%
\setglossarystyle{mcolindex}%
@@ -701,6 +1055,8 @@
{\glsadd{entry.#2}\glsxtrglossentry{entry.#2}}%
}
+\newcommand{\entrydef}[1]{\glsadd{entry.#1}\glsxtrglossentry{entry.#1}}
+
\newcommand*{\atentry}[2][]{%
\texorpdfstring
{\gls[#1]{entry.#2}}%
@@ -953,14 +1309,16 @@ first \LaTeX\ run due to the unknown references being replaced with
?? which can be significantly shorter than the actual text produced
when the reference is known.
-Note that \bibgls\ is a Java application, and requires at least Java~7
-(although the latest version is recommended). Additionally,
-\sty{glossaries-extra} must be at least version 1.12.
-(Although again the latest version is recommended.)
-This application was developed in response to the question
-\qt{\href{http://tex.stackexchange.com/q/342544}{Is there a program for
-managing glossary tags?}} on \TeX\ on StackExchange~\cite{tex.sx}. The \ext{bib}
-file can be managed in an application such as JabRef.
+Note that \bibgls\ is a Java application, and requires at least
+Java~8.\footnote{The \code{List.sort} method used to sort the
+entries was only introduced to Java~8.} Additionally,
+\sty{glossaries-extra} must be at least version 1.12. (Although
+the latest version is recommended.) This application was
+developed in response to the question
+\qt{\href{http://tex.stackexchange.com/q/342544}{Is there a program
+for managing glossary tags?}} on \TeX\ on
+StackExchange~\cite{tex.sx}. The \ext{bib} file can be managed in an
+application such as JabRef.
If you already have a \ext{tex} file containing
entry definitions using commands like \gls{newglossaryentry}
@@ -1191,6 +1549,283 @@ application (so the resource option list would need
it's best to avoid this hybrid method unless you have a particular
set of \idx{xindy} rules that can't be replicated with \bibgls.
+\section{Logical Divisions: \field{type} vs \field{group} vs \field{parent}}
+\label{sec:logicaldivisions}
+
+If you have a document with many terms that need listing, it's
+likely that you may want to divide the terms into separate blocks or
+units for easier reading. There are three fields that are used
+for this.
+\begin{description}
+\item[\field{type}] The highest division is the glossary to which
+the entry belongs. The glossary must first be defined (see
+\sectionref{sec:newglossary}) with an associated label used to
+identify it. The title is assigned to the glossary when it is
+defined or it can be overridden with the \printglossopt{title} key.
+The glossary is displayed using \cs{printunsrtglossary} and the
+title is placed in a sectioning command by default.
+
+\begin{important}
+\bibgls\ does not provide any means of sorting glossary types. If
+you use \ics{printunsrtglossaries} the order will be according to
+the order in which the glossaries were defined. You may use
+\cs{printunsrtglossary} to list individual glossaries in your own
+preferred order.
+\end{important}
+
+\item[\field{group}] The entries within a glossary can form groups
+as a by-product of the sorting method. This must be enabled with the
+\longarg{group} switch and isn't available for the sort methods
+listed in \tableref{tab:sortoptionsnosort}. The group label is
+stored in the \field{group} field. This is an internal field that
+typically shouldn't be set in the \ext{bib} file.
+
+You can specify your own custom groups but if you do so you must
+ensure that the terms are ordered in such a way that they are
+gathered according to group. This is typically done by splitting the
+glossary into blocks using a separate \gls{GlsXtrLoadResources} with
+the \csopt{group} option set. You control the order of the groups by
+your ordering of \gls{GlsXtrLoadResources}. The group title can be
+assigned using \gls{glsxtrsetgrouptitle} within the document.
+
+\begin{important}
+\bibgls\ does not sort by group title. At most it can sort by the
+group label (by changing the \csopt{sort-field}) but this is usually
+an indication that you actually have a hierarchical glossary and you
+ought to be using the \field{parent} field instead. (Compare
+\exfile{sample-textsymbols.tex} and
+\exfile{sample-textsymbols2.tex}.)
+\end{important}
+
+\item[\field{parent}] An entry may have one or more sub-entries.
+Most of the sort methods will produce a hierarchical ordering that
+ensures that the sub-entries are listed immediately after their
+parent entry. The parent entry is identified by the \field{parent}
+field which should contain the parent's label.
+
+\begin{important}
+\bibgls\ sorts the parent and child entries using the same
+comparator. The sort methods listed
+in \tableref{tab:sortoptionsnosort} disregard the hierarchical
+level, which can result in child entries becoming detached from
+their parent entry. The other methods sort hierarchically using
+the same comparator but take the hierarchical level into account.
+\end{important}
+
+\end{description}
+
+Suppose you have a mixture of terms, abbreviations and symbols, then
+you might want to have three glossaries that are listed in the table
+of contents. In this case, you use the \field{type} field or the
+\field{type} resource option. The ordering of the glossaries is
+determined by the ordering of the \cs{printunsrtglossary}
+commands within the document. For example:
+\begin{codeenv}
+\cs{printunsrtglossary}
+\cs{printunsrtglossary}\oarg{\printglossopt[abbreviations]{type}}
+\cs{printunsrtglossary}\oarg{\printglossopt[symbols]{type}}
+\end{codeenv}
+
+Suppose that your list of terms spans many pages and you feel it
+would be helpful to the reader to split it up into letter groups
+then you would need to run \bibgls\ with the \longarg{group} switch
+and use a glossary style that supports letter groups for that
+glossary. For example:
+\begin{codeenv}
+\cs{printunsrtglossary}\oarg{\printglossopt[indexgroup]{style}}
+\end{codeenv}
+
+Suppose that your list of symbols consists of pictographs, Latin characters
+and Greek characters and you want them grouped together
+in that order. Then you would use a separate
+\gls{GlsXtrLoadResources} for each block and assign your own custom
+group. This means ensuring that each \idx{resourceset} only selects
+the terms for that group. The simplest way of doing this is to
+have a separate \ext{bib} file for each set. For example:
+\begin{codeenv}
+\gls{glsxtrsetgrouptitle}\marg{pictographs}\marg{Pictographs}
+\gls{glsxtrsetgrouptitle}\marg{latinsymbols}\marg{Latin Characters}
+\gls{glsxtrsetgrouptitle}\marg{greeksymbols}\marg{Greek Characters}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[generalsymbols]{src},\comment{data in generalsymbols.bib}
+ \csopt[pictographs]{group},
+ \csopt[symbols]{type}
+}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[latinsymbols]{src},\comment{data in latinsymbols.bib}
+ \csopt[latin]{group},
+ \csopt[symbols]{type}
+}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[greeksymbols]{src},\comment{data in greeksymbols.bib}
+ \csopt[greek]{group},
+ \csopt[symbols]{type}
+}
+\end{codeenv}
+
+Suppose instead that you have many of these logical blocks and you
+want them ordered according to the block title. In this case you
+have a hierarchical glossary and you need to use the \field{parent}
+field. You then need to select an appropriate \idx{glossarystyle}.
+
+If you only want to have a single \ext{bib} file that contains all
+your entries and you want to share it across multiple documents then
+the most flexible approach is to use custom fields and entry types
+that can be aliased according to the needs of the
+\idxpl{resourceset}.
+
+For example, the file \filefmt{entries.bib}:
+\begin{codeenv}
+\comment{Encoding: UTF-8}
+\strut
+\atentryfmt{indexplural}\marg{latin,\field{text}=\marg{Latin character}}
+\atentryfmt{indexplural}\marg{greek,\field{text}=\marg{Greek character}}
+\atentryfmt{indexplural}\marg{pictograph}
+\strut
+\atentry{symbol}\marg{fx,
+ \field{name}=\marg{\cs{ensuremath}\marg{f(x)}},
+ \field{description}=\marg{function of \idx{mshiftchar}x\idx{mshiftchar}},
+ \fieldfmt{identifier}=\marg{latin}
+}
+\strut
+\atentry{symbol}\marg{f\idx{aposchar}x,
+ \field{name}={\cs{ensuremath}\marg{f\idx{aposchar}(x)}},
+ \field{description}=\marg{derivative of \cs{gls}\marg{fx}},
+ \fieldfmt{identifier}=\marg{latin}
+}
+\strut
+\atentry{symbol}\marg{pi,
+ \field{name}=\marg{\cs{ensuremath}\marg{\cs{pi}}},
+ \field{description}=\marg{ratio of circumference to diameter},
+ \fieldfmt{identifier}=\marg{greek}
+}
+\strut
+\atentry{symbol}\marg{heart,
+ \field{name}=\marg{\cs{ensuremath}\marg{\ics{heartsuit}}},
+ \field{description}=\marg{heart},
+ \fieldfmt{identifier}=\marg{pictograph}
+}
+\strut
+\atentry{symbol}\marg{diamond,
+ \field{name}=\marg{\cs{ensuremath}\marg{\ics{diamondsuit}}},
+ \field{description}=\marg{diamond},
+ \fieldfmt{identifier}=\marg{pictograph}
+}
+\strut
+\atentry{abbreviation}\marg{html,
+ \field{short}=\marg{html},
+ \field{long}=\marg{hypertext markup language},
+ \fieldfmt{identifier}=\marg{markuplanguage}
+}
+\strut
+\atentry{abbreviation}\marg{xml,
+ \field{short}=\marg{xml},
+ \field{long}=\marg{extensible markup language},
+ \fieldfmt{identifier}=\marg{markuplanguage}
+}
+\strut
+\atentry{entry}\marg{duck,
+ \field{name}=\marg{duck},
+ \field{description}=\marg{a waterbird with webbed feet},
+ \fieldfmt{identifier}=\marg{animal}
+}
+\strut
+\atentry{entry}\marg{parrot,
+ \field{name}=\marg{parrot},
+ \field{description}=\marg{mainly tropical bird with bright plumage},
+ \fieldfmt{identifier}=\marg{animal}
+}
+\end{codeenv}
+This has a custom field \fieldfmt{identifier}. This will be ignored
+by \bibgls\ unless defined or aliased in the document.
+
+Here's an example document that creates three glossary types (the
+default \code{main} glossary and the glossaries created with the
+\styopt{abbreviations} and \styopt{symbols} options). They are
+listed in the order of \cs{printunsrtglossary} and their titles are
+added to the table of contents.
+
+The custom \fieldfmt{identifier} fields are ignored for the
+main and abbreviation glossaries, but they are aliased for the
+symbols to the \field{group} field. Since I've split the symbols
+glossary into blocks with each block only containing entries that
+have the same \field{group} value, this isn't a problem. It also
+won't trigger a warning with \longarg{warn-non-bib-fields} as it's
+being aliased rather than set in the \ext{bib} file. The blocks
+appear in the same order as the corresponding \gls{GlsXtrLoadResources}
+commands. The title for each block is provided in the document
+using \gls{glsxtrsetgrouptitle}.
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\oarg{\styopt{record},\styopt{abbreviations},\styopt{symbols}}\marg{glossaries-extra}
+\strut
+\cs{renewcommand}\marg{\gls{GlsXtrDefaultResourceOptions}}\marg{
+ \csopt[all]{selection},\csopt[entries]{src},\csopt[false]{save-locations}}
+\strut
+\gls{GlsXtrLoadResources}\oarg{\csopt[main]{type},\csopt[entrytype=entry]{match}}
+\gls{GlsXtrLoadResources}\oarg{\csopt[abbreviations]{type},
+ \csopt[entrytype=abbreviation]{match}}
+\strut
+\gls{glsxtrsetgrouptitle}\marg{pictograph}\marg{Pictographs}
+\gls{GlsXtrLoadResources}\oarg{\csopt[symbols]{type},
+ \csopt[identifier=\field{group}]{field-aliases},
+ \csopt[\field{group}=pictograph]{match}}
+\strut
+\gls{glsxtrsetgrouptitle}\marg{latin}\marg{Latin Characters}
+\gls{GlsXtrLoadResources}\oarg{\csopt[symbols]{type},
+ \csopt[identifier=\field{group}]{field-aliases},
+ \csopt[\field{group}=latin]{match}}
+\strut
+\gls{glsxtrsetgrouptitle}\marg{greek}\marg{Greek Characters}
+\gls{GlsXtrLoadResources}\oarg{\csopt[symbols]{type},
+ \csopt[identifier=\field{group}]{field-aliases},
+ \csopt[\field{group}=greek]{match}}
+\strut
+\cmd{begin}\marg{document}
+\cs{tableofcontents}
+\cs{printunsrtglossary}\oarg{\printglossopt[abbreviations]{type}}
+\cs{printunsrtglossary}
+\cs{printunsrtglossary}\oarg{\printglossopt[symbols]{type},\printglossopt[\glostyle{treegroup}]{style}}
+\cmd{end}\marg{document}
+\end{codeenv}
+
+In the above example document, the symbols list is divided into
+three groups, listed in the order: Pictographs, Latin characters and
+Greek characters. If you want these titles ordered alphabetically
+then you need a hierarchical structure instead. This can be obtained
+by aliasing the custom \fieldfmt{identifier} field to
+\field{parent}:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\oarg{\styopt{record},\styopt[topic]{stylemods},\styopt{abbreviations},\styopt{symbols}}\marg{glossaries-extra}
+\strut
+\cs{renewcommand}\marg{\gls{GlsXtrDefaultResourceOptions}}\marg{\comment{}
+ \csopt[all]{selection},\csopt[entries]{src},\csopt[false]{save-locations}}
+\strut
+\gls{GlsXtrLoadResources}\oarg{\csopt[main]{type},\csopt[entrytype=entry]{match}}
+\gls{GlsXtrLoadResources}\oarg{\csopt[abbreviations]{type},
+ \csopt[entrytype=abbreviation]{match}}
+\strut
+\gls{GlsXtrLoadResources}\oarg{\csopt[symbols]{type},
+ \csopt[identifier=\field{parent}]{field-aliases},
+ \csopt[entrytype=symbol,entrytype=indexplural]{match}}
+\strut
+\cmd{begin}\marg{document}
+\cs{tableofcontents}
+\cs{printunsrtglossary}\oarg{\printglossopt[abbreviations]{type}}
+\cs{printunsrtglossary}
+\cs{printunsrtglossary}\oarg{\printglossopt[symbols]{type},\printglossopt[\glostyle{topic}]{style}}
+\cmd{end}\marg{document}
+\end{codeenv}
+The style used for the symbols list is now \glostyle{topic} rather
+than \glostyle{treegroup}. This results in a slightly different
+appearance. You can select the most appropriate style according to
+your needs (see the gallery of predefined
+styles~\cite{glossarystylesgallery}). The topic ordering is now:
+Greek characters, Latin characters and Pictographs.
+
\section{Defining a New Glossary}
\label{sec:newglossary}
@@ -1287,7 +1922,10 @@ at this point.
\item[Stage 2 (Parsing)] All the \iext{bib} files associated with
the \idx{resourceset} are parsed. Entry aliases (identified by
-\csopt{entry-type-aliases}) are performed. Preamble information (provided by
+\csopt{entry-type-aliases}) are performed. The
+\hyperref[sec:multientry]{multi-entry types}, such as
+\atentry{bibtexentry} and \atentry{progenitor}, spawn their
+associated primary entries. Preamble information (provided by
\atentry{preamble}) is saved but is not interpreted at this stage.
The transcript will show the message
\begin{alltt}
@@ -1308,39 +1946,73 @@ the corresponding set of \ext{bib} files:
\item Field checks and modifications are performed:
\begin{itemize}
\item field aliases are performed (\csopt{field-aliases});
+
\item ignored fields (identified by \csopt{ignore-fields}) are
removed;
+
\item case-changes (for example, \csopt{short-case-change}) are
- performed, except for the \field{name} field;
+ performed, except for the \field{name} field and fields identified
+ with \csopt{field-case-change};
+
\item suffixes are appended if required (for example, with
\csopt{short-plural-suffix});
+
\item field replications are made (\csopt{replicate-fields}),
and any of the above case-change or suffixes required
on the replicated fields are performed;
- \item the \field{group} field is assigned if \csopt{group} is set;
+
+ \item the \field{group} field is assigned if \csopt[\meta{label}]{group}
+ is set;
+
\item any variables (identified by \atentry{string}) are expanded
(if not already done in any of the previous steps);
+
\item any fields that have been identified by
\csopt{bibtex-contributor-fields} are converted;
+
+ \item any fields that have been identified with
+ \csopt{encapsulate-fields} are converted;
+
+ \item any fields that have been identified with
+ \csopt{encapsulate-fields*} are converted;
+
\item any fields that must be converted into a label form
(\csopt{labelify} or \csopt{labelify-list}) are processed;
+
\item any fields identified by \csopt{dependency-fields} are parsed for
dependent entries;
+
\item any fields whose value must be a label are interpreted
if \csopt{interpret-label-fields} is set;
+
\item the \field{parent} field is adjusted according to the label prefix
settings (\csopt{label-prefix} etc);
+
\item \ics{makefirstuc} protection is applied according to
\longarg{mfirstuc-protection} and \longarg{mfirstuc-math-protection};
+
\item fields are parsed for commands like \cs{gls} or
\cs{glshyperlink} and also checked for nested links if
\longarg{nested-link-check} is set;
+
\item the \field{description} field is adjusted according to
\csopt{strip-trailing-nopost};
+
\item end punctuation is checked according to
\csopt{check-end-punctuation};
+
\item \field{name} case-change is performed if
- \csopt{name-case-change} is set.
+ \csopt{name-case-change} is set;
+
+ \item if \csopt[true]{copy-alias-to-see} the \field{alias} is copied
+ to the \field{see} field;
+
+ \item general field case changes identified by
+ \csopt{field-case-change} are performed;
+
+ \item any fields that have been identified with
+ \csopt{interpret-fields} are replaced with their interpreted
+ values.
\end{itemize}
\item The dual version (if appropriate) is created.
\item Records are added to the entry's location list (or transferred
@@ -1610,10 +2282,10 @@ for \csopt{src} and determine if the corresponding \ext{bib} file or
files are newer than the \ext{tex} file.
It's not possible to determine if the location lists require
-updating, just as it's not possible to do this for the table of
-contents, list of figures, list of tables etc. (Or, if it could be
-implemented, the required code would make the document build far more
-complicated.)
+updating, just as it's not possible to do this for the
+\idx{toc}, list of figures, list of tables etc. (Or, if it could
+be implemented, the required code would make the document build far
+more complicated.)
In general, the basic algorithm is:
\begin{enumerate}
@@ -1778,6 +2450,18 @@ and will expand some things that aren't expanded by \LaTeX\
that would be expanded by \LaTeX\ (such as commands defined
in terms of complicated internals).
+If you get a \idx{StackOverflowError} while a field is being
+interpreted (with a long stack trace that contains repeated file names and
+line numbers) then it's likely you have an infinite loop. For
+example, this can be triggered if a field contains \csfmt{foo} that
+has been defined as:
+\begin{codeenv}
+\cs{def}\cmd{foo}\marg{\cmd{foo}}
+\end{codeenv}
+This will obviously also cause an error in the \LaTeX\ document as
+well (unless the document has a different definition that doesn't
+have this unbounded recursion).
+
The \file{texparserlib.jar} library is not a \TeX\ engine and there
are plenty of situations where it doesn't work. In particular, in
this case it's being used in a fragmented context without knowing
@@ -1825,7 +2509,7 @@ Glsentryshort,Glsentrylong,Glsentryfirst,Glsentrysymbol,%
Glsentryuseri,Glsentryuserii,Glsentryuseriii,Glsentryuseriv,%
Glsentryuserv,Glsentryuservi,Glsentryplural,Glsentryfirstplural,Glsentryshortpl,%
Glsentrylongpl,Glsentrysymbolplural,bibglshashchar,bibglsunderscorechar,%
-bibglsdollarchar,bibglsampersandchar,bibglscircumchar,glsbackslash,glstildechar,%
+bibglsdollarchar,bibglsampersandchar,bibglscircumchar,glsbackslash,glstildechar,glsopenbrace,glsclosebrace,glspercentchar,%
glsxtrusefield,Glsxtrusefield,GLSxtrusefield,glsentrytitlecase,%
glsxtrhiernamesep,glsxtrhiername,Glsxtrhiername,GlsXtrhiername,%
GLSxtrhiername,GLSXTRhiername}
@@ -1856,7 +2540,7 @@ rule that recognises these Unicode characters (for example,
\csopt[\cs{glshex}2694 \string< \cs{glshex}2693 \string< \cs{glshex}26BD]{sort-rule}).
\TeX\ syntax can be quite complicated and, in some cases, far too
-complicated for simple regular expressions. The \TeX\ parser library performs
+complicated for simple \idxpl!{regex}. The \TeX\ parser library performs
better than a simple pattern match, and that's the purpose of
\file{texparserlib.jar} and why it's used by \bibgls\ (and by
\idx{convertgls2bib}). When the \longarg{debug} mode is on, any
@@ -2008,6 +2692,10 @@ If \csopt[false]{interpret-preamble} had been used, \csfmt{card}
wouldn't be recognised and would be discarded leaving just \qtt{S}
as the sort value.
+(Note that if \ics{vert} is used instead of \textbar\ then it would
+be converted into the mathematical operator \hex{2223} and result in
+a different order.)
+
For the \code{i} entry, the code is:
\begin{verbatim}
{}$\imaginary$
@@ -2124,8 +2812,7 @@ support for locales than the native \idx{JRE}. For example:
\begin{verbatim}
java.locale.providers=CLDR,JRE
\end{verbatim}
-This isn't available for Java~7, and should be enabled by default
-for the proposed Java~9. The property
+This should be enabled by default for Java~9. The property
can either be set in a script that runs \bibgls, for example,
\begin{verbatim}
java -Djava.locale.providers=CLDR,JRE,SPI -jar "$jarpath" "$@"
@@ -2146,8 +2833,7 @@ set JAVA_TOOL_OPTIONS=-Djava.locale.providers=CLDR,JRE,SPI
\chapter{Command Line Options}
\label{sec:switches}
-
-\setcounter{secnumdepth}{0}
+\setsecdepth{0}
The syntax of \bibgls\ is:
\begin{alltt}
@@ -2306,6 +2992,43 @@ This switch is most useful in conjunction with
Don't check for instances of \ics{citation} in the \ext{aux} file
(default).
+\argsection{warn-non-bib-fields}
+
+If any internal fields are found in the \ext{bib} file, this setting
+will issue a warning as their use can cause unexpected results.
+The fields checked for are those listed in Tables~\ref{tab:internalfields}
+and \ref{tab:baseinternalfields} with a few exceptions, notably
+\field{type} and \field{sort}. Ideally you shouldn't need to use
+\field{sort} as there should be an appropriate fallback set up to
+use if \field{sort} isn't set, such as the label for symbols or the
+name for terms or the short form for abbreviations.
+
+This is the default setting and was added as some users were
+confused over which fields could be used in the \ext{bib} file.
+The use of these fields can break \bibgls's normal behaviour and
+cause unexpected results.
+
+The check is performed before field aliasing, so it's possible to
+alias a field to an internal field, such as \field{group}, without
+triggering this warning. If you do this you need to make sure you
+have taken appropriate precautions to avoid unexpected results.
+
+\argsection{no-warn-non-bib-fields}
+
+Switches off the check for non-bib fields. If you use this option
+you need to make sure you have taken appropriate precautions to
+avoid unexpected results.
+
+\argsection{warn-unknown-entry-types}
+
+If any unknown entry types are found in the \ext{bib} file, \bibgls\
+will issue a warning with this option set (default).
+
+\argsection{no-warn-unknown-entry-types}
+
+This option will suppress the warning if an unknown entry types are
+found in the \ext{bib} file.
+
\argsection{merge-wrglossary-records}
For use with the \styopt{indexcounter} package option
@@ -2711,9 +3434,10 @@ and \encap{hyperbf} or \encap{hyperit} for a primary reference.)
\argsection{group}
The \styfmt{glossaries-extra} \styopt{record} package option
-automatically creates a new field called \field{group}. If the
-\longarg{group} switch is used then, when sorting, \bibgls\ will try
-to determine the letter group for each entry and add it to the
+automatically creates a new internal field called \field{group}. If the
+\longarg{group} switch is used with the default \csopt[auto]{group}
+option then, when sorting, \bibgls\ will try
+to determine the letter group for each entry and assign it to the
\field{group} field. (Some \csopt{sort} options ignore this
setting.) This value will be picked up by \ics{printunsrtglossary}
if group headings are required (for example with the
@@ -2723,6 +3447,18 @@ if group headings are required (for example with the
the glossary, there's no need to use this switch. Note that this
switch doesn't automatically select an appropriate glossary style.
+\begin{important}
+The \field{group} field should typically not be set in the \ext{bib}
+file and will trigger a warning if found. The explicit use of the
+\field{group} key will override \bibgls's normal group formation behaviour,
+which can cause unexpected results. The custom use of the
+\field{group} field requires some care. As a general rule, if you
+find yourself wanting to use the \field{group} field in the \ext{bib} file,
+then the chances are that what you actually have is a hierarchical
+glossary (list of topics) and what you really need is the \field{parent} field.
+Compare the example files \exfile{sample-textsymbols.tex} and
+\exfile{sample-textsymbols2.tex}. See also \sectionref{sec:logicaldivisions}.
+\end{important}
There are eight types of groups:
\begin{description}
\item[\idx{lettergroup}] The first non-ignored character of the
@@ -2768,13 +3504,14 @@ The group label is obtained from \gls!{bibglsdategroup}.
comparisons (where the date is omitted).
The group label is obtained from \gls!{bibglstimegroup}.
-\item[\idx{customgroup}] The group label is explicitly set either in
-the \ext{bib} file or using the \csopt[\meta{label}]{group} resource
-option. You will need to use \gls{glsxtrsetgrouptitle} to provide an
-associated title if the \meta{label} isn't the same as the title.
-Remember that the label can't contain any active characters, so you
-can't use non-ASCII characters in \meta{label} with \sty{inputenc}
-(but you can use non-ASCII alphanumerics with \sty{fontspec}).
+\item[\idx{customgroup}] The group label is explicitly set either by
+aliasing a field (with \csopt{field-aliases}) or by using the
+\csopt[\meta{label}]{group} resource option. You will need to use
+\gls{glsxtrsetgrouptitle} in the document to provide an associated title if the
+\meta{label} isn't the same as the title. Remember that the label
+can't contain any active characters, so you can't use non-ASCII
+characters in \meta{label} with \sty{inputenc} (but you can use
+non-ASCII alphanumerics with \sty{fontspec}).
\end{description}
@@ -2896,9 +3633,10 @@ hyper-group styles, and make sure you have an up-to-date version of
\argsection{no-group}
-Don't use the \field{group} field. (Default.)
-The glossary won't have groups even if a group style, such as
-\glostyle{indexgroup}, is used.
+Don't automatically set the \field{group} field with
+\csopt[auto]{group} (default). The glossary won't have groups even if a
+group style, such as \glostyle{indexgroup}, is used (unless the
+\field{group} field is set to a custom value).
\argsection{tex-encoding}
@@ -3055,7 +3793,7 @@ switch off record counting.
\chapter{\iext{bib} Format}
\label{sec:bib}
-\setcounter{secnumdepth}{1}
+\setsecdepth{1}
\bibgls\ recognises certain entry types. Any unrecognised types will
be ignored and a warning will be written to the transcript file.
@@ -3142,7 +3880,13 @@ treated as a comment character and other unwanted material
should be omitted. Avoid using comments within field values.
Comments are best placed outside of entry definitions.
-The most common type of comment is the encoding comment, described above.
+The most common type of comment is the encoding comment, described
+above. \BibTeX's \entrydef{comment} is also supported by \bibgls\
+for general comments, but not for the encoding. For example, JabRef
+uses \atentryfmt{Comment} for metadata.
+\begin{codeenv}
+\atentryfmt{Comment}\marg{jabref-meta: databaseType:bib2gls;}
+\end{codeenv}
\section{Fields}
\label{sec:fields}
@@ -3151,22 +3895,34 @@ Each entry type may have required fields, optional fields and
ignored fields. These are set using a \keyvallist\ within
\code{@\meta{entry-type}\marg{\meta{id},\meta{fields}}} in the
\ext{bib} file. Most keys recognised by
-\gls{newglossaryentry} may be used as a field. In general, you
+\gls{newglossaryentry} may be used as a field unless \bibgls\
+considers them an internal field (see below). In general, you
shouldn't need to use the \field{sort} field.
+If an optional field is missing and \bibgls\ needs to access it for
+some reason, \bibgls\ will try to fallback on another value. The
+actual fallback value depends on the entry type. The most common
+fallback is that used if the \field{sort} field is missing, which is
+typically the case. This approach allows different entry types to
+have different fields used for sorting.
+
Predefined fields for use in \ext{bib} files are listed in
Tables~\ref{tab:fields}, \ref{tab:bib2glsfields},
\ref{tab:prefixfields} and~\ref{tab:accsuppfields}. If you add any
custom keys in your document using \ics{glsaddkey} or
\ics{glsaddstoragekey}, those commands must be placed before the
first use of \gls{GlsXtrLoadResources} to ensure that \bibgls\
-recognises them as a field name.
-
-Internal fields that may be set by \bibgls\ when it creates the \iext{glstex}
-files are listed in Table~\ref{tab:internalfields}. These typically
-shouldn't be set in the \ext{bib} file. Some of these fields can be set
-for a particular document using a resource option, such as
-\csopt{type} or \csopt{category}.
+recognises them as a valid field name.
+
+Internal fields that may be assigned within the document (the
+\LaTeX\ assignment code having been written by \bibgls\ in the
+\iext{glstex} file) are listed in Table~\ref{tab:internalfields}.
+These typically shouldn't be used in the \ext{bib} file. Some of
+these fields can be set for a particular document using a resource
+option, such as \csopt{type} or \csopt{group}. With
+\longarg{warn-non-bib-fields} set, \bibgls\ will check for internal
+fields that can cause interference with its normal operations and
+will warn if any are found in the \ext{bib} file.
There are also some fields that are set and used by
\styfmt{glossaries} or \styfmt{glossaries-extra} listed in
@@ -3184,11 +3940,6 @@ convenient than using \ics{input} or \ics{loadglsentries}, which
requires all the keys used in the file to be defined, regardless of
whether or not you actually need them in the document.
-If an optional field is missing and \bibgls\ needs to access it for
-some reason (for example, for sorting), \bibgls\ will try to
-fallback on another value. The actual fallback value depends on the
-entry type.
-
Other entries can be cross-referenced using the \field{see},
\field{seealso} or \field{alias} fields or
by using commands like \ics{gls} or \ics{glsxtrp} in any of the
@@ -3226,67 +3977,68 @@ but it doesn't add any information to the cross-referencing part of the
location list. The option may be used in combination with the \field{see} or
\field{seealso} fields.
-\begin{table}[hbtp]
-\caption{Fields Provided by \styfmt{glossaries-extra}}\label{tab:fields}
-\centering
-\printfields{basefield,extrafield}%
-\end{table}
-
-\begin{table}[hbtp]
-\caption{Fields Provided by \bibgls}\label{tab:bib2glsfields}
-\centering
-\printfields{bib2glsfield}%
-\end{table}
+\clearpage
-\begin{table}[hbtp]
-\caption[Fields Provided by \styfmt{glossaries-prefix}]{Fields
-Provided by \isty{glossaries-prefix}}\label{tab:prefixfields}
-\centering
-\printfields{prefixfield}%
-\end{table}
+\printfields
+ {basefield,extrafield}
+ {Fields Provided by \styfmt{glossaries-extra}}
+ {tab:fields}
-\begin{table}[hbtp]
-\caption[Fields Provided by \styfmt{glossaries-accsupp}]{Fields
-Provided by \isty{glossaries-accsupp}}
-\label{tab:accsuppfields}
-{\centering
-\printfields{accessfield}%
-\par}
-\medskip
-Don't load \isty{glossaries-accsupp} directly (with \ics{usepackage}) when using
-\styfmt{glossaries-extra}. Load using the \styopt{accsupp} package
-option instead.
-\begin{codeenv}
-\cs{usepackage}\oarg{\styopt{record},\styopt{accsupp}}\marg{glossaries-extra}
-\end{codeenv}
-\end{table}
+\clearpage
-\begin{table}[hbtp]
-\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
-set in the resource command or by \bibgls.\par
-\bigskip
-\centering
-\printfields{internalfield}%
-\end{table}
-
-\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}%
-\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}
+\printfields
+ {bib2glsfield}
+ {Fields Provided by \bibgls}
+ {tab:bib2glsfields}
+
+\printfields
+ {prefixfield}%
+ [Fields Provided by \styfmt{glossaries-prefix}]%
+ {Fields Provided by \isty{glossaries-prefix}}
+ {tab:prefixfields}
+
+\printfields
+ [%
+ Don't load \isty{glossaries-accsupp} directly (with \ics{usepackage})
+ when using \styfmt{glossaries-extra}. Load using the \styopt{accsupp}
+ package option instead.
+%\begin{codeenv}
+%\cs{usepackage}\oarg{\styopt{record},\styopt{accsupp}}\marg{glossaries-extra}
+%\end{codeenv}
+ ]%
+ {accessfield}%
+ [Fields Provided by \styfmt{glossaries-accsupp}]%
+ {Fields Provided by \isty{glossaries-accsupp}}
+ {tab:accsuppfields}
+
+\printfields
+ [%
+ You may define and assign \field{bibtextype} as a key (although it's more
+ likely to be aliased). Don't define any of the others listed in this
+ table, and don't use any of them in the \ext{bib} file. A possible
+ exception is the \field{type} field, but it's more flexible to set
+ that through a resource option. The explicit use of \field{group}
+ within a \ext{bib} file can cause unpredictable
+ results and is best set through a resource option or by \bibgls.
+ In general, you shouldn't need to set the \field{sort} field as
+ appropriate fallbacks should produce useful sort values.%
+ ]%
+ {internalfield}%
+ [Fields Set by \bibgls]%
+ {Fields Sometimes Set by \bibgls\ in the \iext{glstex} File}%
+ {tab:internalfields}
+
+\printfields
+ [%
+ Don't define any of these as keys and don't use any of them in the \ext{bib}
+ file.%
+ ]%
+ {baseinternalfield}%
+ [Internal Fields Set by \styfmt{glossaries} or \styfmt{glossaries-extra}
+ or \bibgls]%
+ {Internal Fields Set by \isty{glossaries} or \isty{glossaries-extra}
+ or \bibgls}%
+ {tab:baseinternalfields}
\clearpage
@@ -3406,6 +4158,10 @@ there's no difference. If they don't match then in the first example
the document definitions will take precedence (but the interpreter
will use the \atentry{preamble} definitions) and in the second
example the \atentry{preamble} definitions will take precedence.
+For example, the document may define \csfmt{card} as:
+\begin{codeenv}
+\cs{newcommand}\marg{\cmd{card}}[1]\marg{\ics{vert}\cmd{set}\marg{\idx{param}1}\cs{vert}}
+\end{codeenv}
\item Make use of \gls{glsxtrfmt} provided by \styfmt{glossaries-extra} which
allows you to store the name of the formatting command in a field.
@@ -3619,10 +4375,11 @@ For example:
}
\end{codeenv}
-If the \field{sort} field is missing the default is obtained from the
-\field{name} field. (A different field can be selected for the sort value with
-\csopt{sort-field}.) For hierarchical entries, if the \field{name} field is
-omitted it will be obtained from the parent's \field{name}.
+If the \field{sort} field is missing the default is obtained from
+the \field{name} field (unless overridden by
+\csopt{entry-sort-fallback}). For hierarchical entries, if the
+\field{name} field is omitted it will be obtained from the parent's
+\field{name}.
Terms defined using \atentry{entry} will be written to the output
(\ext{glstex}) file using the command \gls!{bibglsnewentry}.
@@ -3706,6 +4463,10 @@ behaviour of \atentry{entry}, which fetches the name from the parent
entry.) If the name contains any characters that can't be used in
the label, you must use the \field{name} field. If the \field{sort}
field is missing the default is obtained from the \field{name}.
+Note that the \atentry{index} entry type is \emph{not} governed by
+\csopt{entry-sort-fallback}. This allows \atentry{index} and
+\atentry{entry} to have different fallbacks if the \field{sort}
+field is missing.
Example:
\begin{codeenv}
@@ -3727,7 +4488,9 @@ missing, is obtained from the \field{plural} field. If the
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:
+\field{name} field. (As with \atentry{index}, \atentry{indexplural}
+is \emph{not} governed by \csopt{entry-sort-fallback}.)
+All fields are optional. For example:
\begin{codeenv}
\atentry{indexplural}\marg{goose,
\field{plural} = \marg{geese}
@@ -5109,10 +5872,12 @@ way the entries are sorted and on the \csopt{dual-sort} setting.
\section{Multi-Entry Types}
\label{sec:multientry}
-A multi-entry type is a primary entry that may spawn multiple
+A multi-entry type is an entry that may spawn multiple
primary entries. This means that both the main entry and the
spawned entries are sorted together along with all the other primary
-entries.
+entries. In the case of \atentry{spawndualindexentry}, the main and
+spawned entries are primary. The main entry's dual is created as per
+\atentry{dualindexentry}.
\entrysection{bibtexentry}
@@ -5129,7 +5894,9 @@ and \atentryfmt{book} as though they were both
\end{codeenv}
For convenience, \isty{glossaries-extra-bib2gls} v1.29+
provides \ics{GlsXtrBibTeXEntryAliases} which covers all the
-standard \BibTeX\ entry types. If you use
+standard \BibTeX\ entry types. Alternatively, you can use
+\csopt[bibtexentry]{unknown-entry-alias} to alias all entries
+that aren't recognised by \bibgls. If you use
\csopt[same as original entry]{category}, the \field{category}
field will be set to the original entry type (for example,
\code{article} or \code{book}). Similarly you can use
@@ -5313,6 +6080,290 @@ pdflatex myDoc
pdflatex myDoc
\end{codeenv}
+\entrysection{progenitor}
+
+The \atentryfmt{progenitor} type of entries are the only place where
+the \field{adoptparents} field is permitted. The value should be a
+comma-separated list of labels. The \field{adoptparents} field
+must be set and must contain a least one label. If the value
+contains any of the characters \idx{backslashchar} (backslash),
+\idx{bgroupchar} (open brace) or \idx{egroupchar} (close brace) then
+the field will be interpreted (if the default \longarg{interpret} settings
+is on).
+
+Since entries are spawned before fields are processed, the
+\field{adoptparents} field is parsed before any field aliases
+(\csopt{field-aliases}) or replication (\csopt{replicate-fields})
+takes place. However, if the \field{adoptparents} field isn't found,
+\bibgls\ will check for a simple mapping in both the
+\csopt{field-aliases} and \csopt{replicate-fields} settings.
+
+This entry type creates a main \idx[textformat=emph]{progenitor}
+term (with all the given fields except \field{adoptparents})
+and $n$ spawned \idx[textformat=emph]{progeny} terms, where
+$n$ is the number of elements in the \field{adoptparents} field,
+that are dependent on the main term.
+
+Each of the spawned \idx{progeny} entries have the field identified by
+\csopt{adopted-parent-field} (\field{parent} by default) set to the
+corresponding element in the \field{adoptparents} field.
+
+All fields from the original definition are copied except for the
+\field{adoptparents}, \field{alias} and \field{parent} fields. The
+\field{parent} field is never copied, regardless of the value of
+\csopt{adopted-parent-field}. If the adopted parent field is
+changed to one that's contained in the original entry, it's value
+will be from \field{adoptparents} not the value from the original
+entry.
+
+The copied fields follow the same conditions as normal
+entries. (For example, unknown fields are ignored, case-changes are
+applied, if appropriate, and the \field{type} field must reference a
+valid glossary, if set.) If \csopt{progenitor-type} is set, then
+this assignment is made after the \idx{progeny} are created
+and only applies to the main \idx{progenitor} entry. The
+type for the \idx{progeny} can be set with \csopt{progeny-type}.
+For example, \csopt[same as parent]{progeny-type} will ensure
+that the \idx{progeny} are in the same glossary type as
+their parent entry.
+
+For example, an entry defined as:
+\begin{codeenv}
+\atentry{progenitor}\marg{\meta{id},
+ \field{adoptparents} = \marg{\meta{parent-1 id},\ldots,\meta{parent-N id}},
+ \meta{field-name-1} = \margm{text},
+ \ldots
+ \meta{field-name-n} = \margm{text}
+}
+\end{codeenv}
+is essentially like:
+\begin{codeenv}
+\atentry{index}\marg{\meta{id},
+ \field{progeny} = \marg{\meta{parent-1 id}.\meta{id},\ldots,\meta{parent-N id}.\meta{id}},
+ \meta{field-name-1} = \margm{text},
+ \ldots
+ \meta{field-name-n} = \margm{text}
+}
+\strut
+\atentry{index}\marg{\meta{parent-1 id}.\meta{id},
+ \field{progenitor} = \margm{id},
+ \field{parent} = \margm{parent-1 id},
+ \meta{field-name-1} = \margm{text},
+ \ldots
+ \meta{field-name-n} = \margm{text}
+}
+\strut
+\ldots
+\strut
+\atentry{index}\marg{\meta{parent-N id}.\meta{id},
+ \field{progenitor} = \margm{id},
+ \field{parent} = \margm{parent-N id},
+ \meta{field-name-1} = \margm{text},
+ \ldots
+ \meta{field-name-n} = \margm{text}
+}
+\end{codeenv}
+This creates the main (\idx{progenitor}) \meta{id} entry, which
+contains all the fields (except for \field{adoptparents}) that were
+in the original \atentry{progenitor} definition and has the new
+field \field{progeny} set to the comma-separated list of spawned
+entry labels. The main entries are defined in the \ext{glstex} file
+with \gls{bibglsnewprogenitor}.
+
+In addition to the main \meta{id} entry, the above also creates the
+spawned \idx{progeny} entries \code{\meta{parent-1 id}.\meta{id}}, \ldots,
+\code{\meta{parent-N id}.\meta{id}} that are dependent on the main
+\meta{id} entry.
+
+The spawned entries have the \field{parent} field set to the
+corresponding label obtained from the \field{adoptparents} list.
+This parent entry must also be defined, as usual for the
+\field{parent} field. (This restriction obviously doesn't apply if
+\csopt{adopted-parent-field} is changed from the default
+\field{parent}.) The spawned entries are defined in the \ext{glstex}
+file with \gls{bibglsnewspawnedindex}
+
+If the main \idx{progenitor} entry is referenced in the document
+then (assuming the default selection criteria) the spawned entries
+will also be automatically selected. You can check for the existence
+of the \field{progenitor} field using \cs{glsxtrifhasfield} and
+fetch the \field{location} field from the main entry, if required.
+
+Although the spawned entries are considered dependents of the main
+entry, the reverse doesn't apply. If a spawned entry is referenced
+in the document (with \code{\meta{parent-id}.\meta{id}}) then the
+main entry and its other spawned entries aren't automatically
+selected.
+
+For example, suppose the file \filefmt{entries.bib} contains:
+\begin{codeenv}
+\atentry{indexplural}\marg{stylesheet, \field{text}=\marg{stylesheet language}}
+\strut
+\atentry{index}\marg{webdesign, \field{name}=\marg{web design}}
+\strut
+\atentry{indexplural}\marg{markup, \field{text}=\marg{markup language}}
+\strut
+\atentry{progenitor}\marg{xml,
+ \field{name}=\marg{XML},
+ \field{adoptparents}=\marg{markup}
+}
+\strut
+\atentry{progenitor}\marg{css,
+ \field{name}=\marg{CSS},
+ \field{adoptparents}=\marg{stylesheet,webdesign}
+}
+\strut
+\atentry{progenitor}\marg{html,
+ \field{name}=\marg{HTML},
+ \field{adoptparents}=\marg{markup,webdesign}
+}
+\strut
+\atentry{progenitor}\marg{xsl,
+ \field{name}=\marg{XSL},
+ \field{adoptparents}=\marg{stylesheet}
+}
+\end{codeenv}
+and if the document contains:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\oarg{\styopt{record},\styopt[tree]{stylemods},\styopt[index]{style}}\marg{glossaries-extra}
+\strut
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[all]{selection}}
+\strut
+\cs{newcommand}*\marg{\cs{glstreenamefmt}}[1]\marg{\idx{param}1}
+\cmd{begin}\marg{document}
+\cs{printunsrtglossaries}
+\cmd{end}\marg{document}
+\end{codeenv}
+Then the resulting list will be:
+\begin{quote}
+\setlength{\parindent}{0pt}%
+\setlength{\parskip}{0pt plus 0.3pt}%
+\glstreeitem CSS\par
+\glstreeitem HTML\par
+\glstreeitem markup language\par
+\glstreesubitem HTML\par
+\glstreesubitem XML\par
+\glstreeitem stylesheet language\par
+\glstreesubitem CSS\par
+\glstreesubitem XSL\par
+\glstreeitem web design\par
+\glstreesubitem CSS\par
+\glstreesubitem HTML\par
+\glstreeitem XML\par
+\glstreeitem XSL\par
+\end{quote}
+This allows the HTML and CSS entries to be listed under multiple
+parents.
+
+The following \atentryfmt{spawn\meta{single-type}} commands are all forms
+of \atentry{progenitor} that create the given
+\atentryfmt{\meta{single-type}} of entry. The spawned entries are actually
+created with the private entry type \atentryfmt{spawned\meta{type}}. In the
+case of \atentry{progenitor}, the spawned entries are defined as
+a \atentryfmt{spawnedindex} entry. These special
+\atentryfmt{spawned\meta{type}} entry types aren't intended for use
+in the \ext{bib} file, but if you reference the entry type (for
+example, with \csopt[same as entry]{category}) you will get
+\atentryfmt{spawned\meta{type}} as the entry type. The
+original entry type for the spawned entries is the same as
+the original entry for the main \atentry{progenitor} entry.
+
+There is currently only one form of dual \atentry{progenitor} entry and that's
+\atentry{spawndualindexentry}. Only the main \idx{progenitor} entry
+is a dual entry. The spawned \idx{progeny} are all \atentry{index}
+primary entries.
+
+\entrysection{spawnindex}
+
+As \atentry{progenitor}, but the main entries are defined in the
+\ext{glstex} file with \gls{bibglsnewspawnindex} and the
+spawned entries are defined with \gls{bibglsnewspawnedindex}.
+
+\entrysection{spawnindexplural}
+
+As \atentry{progenitor}, except that it creates
+\atentry{indexplural} terms instead of \atentry{index}.
+As with \atentry{indexplural}, if the \field{name} field isn't set,
+it's assigned to the same value as the \field{plural} field (or the
+fallback for the \field{plural}, if not defined).
+
+The main entries are defined in the
+\ext{glstex} file with \gls{bibglsnewspawnindexplural} and the
+spawned entries are defined with \gls{bibglsnewspawnedindexplural}.
+
+\entrysection{spawnentry}
+
+As \atentry{progenitor}, except that it creates
+\atentry{entry} terms instead of \atentry{index}.
+As with \atentry{entry}, the \field{description} field is required
+and either \field{name} or \field{parent}.
+
+The main entries are defined in the
+\ext{glstex} file with \gls{bibglsnewspawnentry} and the
+spawned entries are defined with \gls{bibglsnewspawnedentry}.
+
+\entrysection{spawnabbreviation}
+
+As \atentry{progenitor}, except that it creates
+\atentry{abbreviation} terms instead of \atentry{index}.
+As with \atentry{abbreviation}, the \field{short} and \field{long}
+fields are required.
+
+The main entries are defined in the
+\ext{glstex} file with \gls{bibglsnewspawnabbreviation} and the
+spawned entries are defined with \gls{bibglsnewspawnedabbreviation}.
+
+\entrysection{spawnacronym}
+
+As \atentry{progenitor}, except that it creates
+\atentry{acronym} terms instead of \atentry{index}.
+As with \atentry{acronym}, the \field{short} and \field{long}
+fields are required.
+
+The main entries are defined in the
+\ext{glstex} file with \gls{bibglsnewspawnacronym} and the
+spawned entries are defined with \gls{bibglsnewspawnedacronym}.
+
+\entrysection{spawnsymbol}
+
+As \atentry{progenitor}, except that it creates
+\atentry{symbol} terms instead of \atentry{index}.
+As with \atentry{symbol}, the required fields are \field{name} or
+\field{parent}, and the \field{description} field is required if the
+\field{name} field is missing.
+
+The main entries are defined in the
+\ext{glstex} file with \gls{bibglsnewspawnsymbol} and the
+spawned entries are defined with \gls{bibglsnewspawnedsymbol}.
+
+\entrysection{spawnnumber}
+
+As \atentry{progenitor}, except that it creates
+\atentry{number} terms instead of \atentry{index}.
+As with \atentry{number}, the required fields are \field{name} or
+\field{parent}, and the \field{description} field is required if the
+\field{name} field is missing.
+
+The main entries are defined in the
+\ext{glstex} file with \gls{bibglsnewspawnnumber} and the
+spawned entries are defined with \gls{bibglsnewspawnednumber}.
+
+\entrysection{spawndualindexentry}
+
+As \atentry{progenitor}, except that the main (\idx{progenitor})
+entry behaves like \atentry{dualindexentry}. The spawned
+\idx{progeny} behave like \atentry{index} are so are all considered primary
+entries. The \field{adoptparents} field should therefore reference
+primary entries with the default \csopt[parent]{adopted-parent-field}.
+
+The main primary and secondary (dual) entries are defined in the
+\ext{glstex} file with
+\gls{bibglsnewspawndualindexentry} and
+\gls{bibglsnewspawndualindexentrysecondary}. The spawned
+\idx{progeny} are defined with \gls{bibglsnewspawnedindex}.
+
\chapter{Resource File Options}
\label{sec:resourceopts}
@@ -5382,6 +6433,34 @@ doesn't parse the options, but just writes the information to the
\ext{aux} file. This means that any invalid options will be reported
by \bibgls\ not by \sty{glossaries-extra}.
+As from \sty{glossaries-extra} v1.40 you can provide a default set
+of options by redefining:
+\nosecdef{GlsXtrDefaultResourceOptions}
+This command will be inserted at the start of the options list for
+all resource commands (and will expand as it's written to
+the \ext{aux} file). For example:
+\begin{codeenv}
+\cs{renewcommand}\marg{\gls{GlsXtrDefaultResourceOptions}}\marg{\comment{}
+ \csopt[all]{selection},\csopt[entries]{src}}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[symbols]{type},
+ \csopt[entrytype=symbol]{match}}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[abbreviations]{type},
+ \csopt[entrytype=abbreviation]{match}}
+\end{codeenv}
+This acts like:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[all]{selection},\csopt[entries]{src},
+ \csopt[symbols]{type},
+ \csopt[entrytype=symbol]{match}}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[all]{selection},\csopt[entries]{src},
+ \csopt[abbreviations]{type},
+ \csopt[entrytype=abbreviation]{match}}
+\end{codeenv}
+
If you have multiple \ext{bib} files you can either select them all
using \csopt[\meta{bib list}]{src} in a single
\gls{glsxtrresourcefile} call, if they all require the same settings,
@@ -5710,6 +6789,9 @@ one mapping. For example:
This option isn't cumulative. Multiple instances of
\csopt{entry-type-aliases} override previous instances.
If \meta{\keyvallist} is empty there will be no mappings.
+You can save the original entry type in the
+\field{originalentrytype} field with
+\csopt{save-original-entrytype}.
Here's another example entry in a \ext{bib} file:
\begin{codeenv}
@@ -5752,6 +6834,14 @@ treats the entry as though it had been defined as:
}
\end{codeenv}
+\optsection{unknown-entry-alias}
+
+If this option is set, the \meta{value} is used as the alias for any
+unknown entry types (after any aliases provided with
+\csopt{entry-type-aliases} have been applied). If the value is
+missing or empty, unknown entry types will be ignored with a
+warning.
+
\optsection{action}
This governs how the entries are written in the \iext{glstex} file.
@@ -6076,7 +7166,8 @@ be selected.
\optsection{match}
It's possible to filter the selection by matching field values.
-If \meta{\keyvallist} is empty no filtering will be applied, otherwise
+The value is required for this key but may be empty, which indicates
+that the setting is switched off, otherwise
\meta{\keyvallist} should be a \meta{key}=\meta{regexp} list, where
\meta{key} is the name of a field or \optfmt{id} for the entry's
label or \optfmt{entrytype} for the \bibgls\ entry type (as in
@@ -6085,7 +7176,7 @@ field identifying the glossary label). If you've used
\csopt{entry-type-aliases}, this refers to the target entry type not
the original entry type specified in the \ext{bib} file.
-The \meta{regex} part should be a regular expression conforming
+The \meta{regex} part should be a \idx{regex} conforming
to
\href{http://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html}{Java's
Pattern class}~\cite{pattern}. The pattern is anchored
@@ -6153,11 +7244,11 @@ The default is \csopt[and]{match-op}.
\optsection{not-match}
If \csopt[\meta{\keyvallist}]{match} would cause an entry to be
-selected then \csopt[\meta{\keyvallist}]{not-match} would cause
-that entry to be ignored. If \meta{\keyvallist} is missing, the
-filtering is removed. If you have both \csopt{match} and
-\csopt{not-match} in the same resource set, the last one listed
-takes precedence.
+selected then \csopt[\meta{\keyvallist}]{not-match} would cause that
+entry to be ignored. The value is required for this key but may be
+empty, which indicates that the setting is switched off. If you
+have both \csopt{match} and \csopt{not-match} in the same resource
+set, the last one listed takes precedence.
\optsection{match-action}
@@ -7052,7 +8143,9 @@ This option should take a comma-separated list of recognised field names as the
value. (If a field is present in both \csopt{labelify} and
\csopt{labelify-list}, then \csopt{labelify-list} takes precedence.)
Note that if this setting is on, \idxpl{crossresourceref} aren't
-permitted.
+permitted. The value is required for this key but may be empty,
+which indicates an empty set of fields (that is, the setting is
+switched off).
Each listed field will be converted into a string suitable
for use as a label. (Not necessarily a glossary entry label, but
@@ -7157,9 +8250,13 @@ depending on whether or not \sty{fontspec} was detected.
This option takes a comma-separated list as a value with each
element in the list in the form \code{\margm{regex}\margm{replacement}}
-where \meta{regex} is a regular expression (that conforms to \href{http://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html}{Java's
+where \meta{regex} is a \idx{regex} (that conforms to \href{http://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html}{Java's
Pattern class}~\cite{pattern}) and \meta{replacement}
-is the replacement text. Remember that the argument of
+is the replacement text. The value is required for this key but
+may be empty, which indicates that the
+setting is switched off.
+
+Remember that the argument of
\gls{GlsXtrLoadResources} is expanded when written to the \ext{aux}
file so take care to protect any special characters. For example, to
match a literal \idx{full-stop} use \cs{cs.string}\idx{cs.period}
@@ -7509,12 +8606,14 @@ using \ics{GlsXtrSetField} after the entry definition.
The \meta{list} should be a comma-separated list of fields that
have values in the form \code{\oargm{tag}\meta{id-list}} where
-\meta{id-list} is a comma-separated list of entry labels. This
-makes those fields act like the \field{see} field by
+\meta{id-list} is a comma-separated list of entry labels. The value
+is required for this key but may be empty, which indicates an empty
+set of fields (that is, the setting is switched off).
+
+This setting makes those fields act like the \field{see} field by
identifying the listed entries as dependencies, but the information
-isn't added to the cross-reference part of the location list.
-This action is performed after \csopt{labelify-list}, if that's also
-set.
+isn't added to the cross-reference part of the location list. This
+action is performed after \csopt{labelify-list}, if that's also set.
For example, suppose the file \filefmt{entries-en.bib} contains:
\begin{codeenv}
@@ -7640,14 +8739,16 @@ O \cs{gls}\marg{gato} sentou-se no \cs{gls}\marg{tapete}.
\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}.
+The \csopt{group} option will set the \field{group} field to \meta{label}
+unless \meta{label} is \optfmt{auto}. If \csopt[auto]{group} then if
+the \longarg{group} switch is used the value of the \field{group}
+field is set automatically during the sorting (see also \csopt{group-formation}
+and \sectionref{sec:logicaldivisions}). If the \longarg{no-group}
+setting is on then \csopt[auto]{group} does nothing.
+
+The corresponding group title can be set with
+\gls{glsxtrsetgrouptitle} in the document if the title is different
+from the label. The default behaviour is \csopt[auto]{group}.
For example:
\begin{codeenv}
@@ -7772,6 +8873,15 @@ The \meta{value} may be one of:
to the same value as the \field{category} field
(\field{type} unchanged if \field{category} not set);
+\item \optfmt{same as parent}: sets the \field{type} to the same as
+the entry's parent (new to v1.9). If the entry doesn't have a parent
+or if the parent doesn't have the \field{type} field set, then
+no change is made. Entries should always have the same type
+as their parent, but it's possible for spawned entries to
+pick up the \field{type} field from their \idx{progenitor} entry
+(if it was explicitly set in the \ext{bib} file),
+which may be inappropriate.
+
\item\meta{label} sets the \field{type} field to the glossary
identified by \meta{label}.
\end{itemize}
@@ -7826,6 +8936,30 @@ it's not required as \bibgls\ will write
\code{\ics{provideignoredglossary*}\margm{type}} to the \ext{glstex} file
(see \sectionref{sec:newglossary}).
+\optsection[\subsubsection]{progenitor-type}
+
+This sets the default \field{type} field for the main term defined by
+\atentry{progenitor}-like entries. The \meta{value} is as for
+\csopt{type}. This doesn't change the \field{type} for the spawned
+\idx{progeny}.
+
+\optsection[\subsubsection]{progeny-type}
+
+This sets the default \field{type} field for the \idx{progeny} term
+spawned by
+\atentry{progenitor}-like entries. The \meta{value} is as for
+\csopt{type}. This doesn't change the \field{type} for the main
+\idx{progenitor}. Remember that with the default
+\csopt[parent]{adopted-parent-field} setting, the given type
+should match the type of the parent entry.
+
+\optsection[\subsubsection]{adopted-parent-field}
+
+This identifies the target field to be set to the corresponding
+value of the \field{adoptparents} list by the \idx{progeny}
+entries spawned by the \atentry{progenitor} type of entry.
+The default is \field{parent}.
+
\optsection[\subsubsection]{abbreviation-name-fallback}
The entry types that define abbreviations (such as
@@ -7911,12 +9045,17 @@ The value of one field can be copied to other fields using
this option where each \meta{key}\dequals\meta{value} pair
is in the form
\code{\meta{field1}\dequals\marg{\meta{field2},\meta{field3},\ldots}}
-where all values are field names. This copies the contents
+where all values are field names. The value is required for this key
+but may be empty, which indicates that the setting is switched off.
+
+This option copies the contents
of \meta{field1} to \meta{field2}, \meta{field3}, \ldots\
(only if the target field isn't already set with
\csopt[false]{replicate-override}). This action is
performed after \csopt{ignore-fields} (see
-\sectionref{sec:resourcesets}).
+\sectionref{sec:resourcesets}). If the source field is missing, the
+\csopt{replicate-missing-field-action} setting determines the
+action.
For example, suppose \filefmt{people.bib} contains:
\begin{codeenv}
@@ -7998,6 +9137,18 @@ This is a boolean option. The default setting is
\csopt{replicate-fields} will override the existing value if the
target field is already set.
+\optsection[\subsubsection]{replicate-missing-field-action}
+
+This option indicates what to do if a source field identified in
+\csopt{replicate-fields} is missing. The value may be one of:
+\begin{itemize}
+\item \optfmt{skip}: skip the replication of the missing field
+(default);
+\item \optfmt{fallback}: use the fallback for the missing field, if
+one is available (otherwise skip);
+\item \optfmt{empty}: make the target field empty.
+\end{itemize}
+
\optsection[\subsubsection]{counter}
The \csopt{counter} option assigns the default counter to use
@@ -8053,6 +9204,14 @@ style. For example:
If set, the value of the \field{alias} field is copied to
the \field{see} field. The default setting is \csopt[false]{copy-alias-to-see}.
+\optsection[\subsubsection]{save-original-entrytype}
+
+If this is set to \optfmt{true}, the original entry type
+(without the leading \idx{atchar}) is stored in the
+\field{originalentrytype} field. If no entry aliasing has been
+applied (with \csopt{entry-type-aliases}) the field will be set to
+the actual entry type.
+
\subsection{Field Adjustments}
\label{sec:fieldmods}
@@ -8240,7 +9399,8 @@ recognised by \bibgls' interpreter (such as those listed in
\tableref{tab:bibglsdefs}).
\end{itemize}
The final \code{:\meta{csname}} part may be omitted if no command
-need be applied. (That is, sort by label.)
+need be applied. (That is, sort by label.) The value is required for this key but
+may be empty, which indicates the setting is switched off.
The sorting options are as those for the main list. For example,
for entries in the primary list the break point is obtained from the
@@ -8546,7 +9706,10 @@ order isn't what you expect, check the transcript file for messages.
\optsection[\subsubsection]{bibtex-contributor-fields}
This option indicates that the listed fields all use \BibTeX's name
-syntax (as used in \BibTeX's \code{author} and \code{editor} fields).
+syntax (as used in \BibTeX's \code{author} and \code{editor} fields). The value is required for this key but
+may be empty, which indicates an empty set of fields (that is, the
+setting is switched off).
+
The values of these fields will be converted into the form:
\begin{codeenv}
\gls{bibglscontributorlist}\margm{contributor list}\margm{n}
@@ -8651,6 +9814,142 @@ The second resource set will use the default
\csopt[von]{bibtex-contributor-fields} setting when obtaining the
sort value.
+\optsection[\subsubsection]{encapsulate-fields}
+
+This option should take a comma-separated list of
+\optfmt{\meta{field}\dequals\meta{cs-name-1arg}} values, where
+\meta{cs-name-1arg} is the name of a control sequence that takes
+one argument. The value is required for this key but
+may be empty, which indicates an empty set (that is, the
+setting is switched off).
+
+During the processing stage, each field identified in
+the list (if defined) will have its value replaced with:
+\begin{codeenv}
+\cmd{\meta{cs-name-1arg}}\margm{value}
+\end{codeenv}
+where \meta{value} was its previous value. An
+empty list switches off encapsulation (the default).
+
+This action overrides any previous use of \csopt{encapsulate-fields}
+within the same \idx{resourceset} and is always performed before
+\csopt{encapsulate-fields*}, regardless of the order in the
+\idx{resourceset}['s] list of options.
+
+\optsection[\subsubsection]{encapsulate-fields*}
+
+This option should take a comma-separated list of
+\optfmt{\meta{field}\dequals\meta{cs-name-2arg}} values, where
+\meta{cs-name-2arg} is the name of a control sequence that takes two
+arguments. The value is required for this key but
+may be empty, which indicates an empty set (that is, the
+setting is switched off).
+
+During the processing stage, each field identified in the
+list (if defined) will have its value replaced with:
+\begin{codeenv}
+\cmd{\meta{cs-name-2arg}}\margm{value}\margm{label}
+\end{codeenv}
+where \meta{value} was its previous value and \meta{label} is the
+entry's label (including prefix, if appropriate). An
+empty list switches off encapsulation (the default).
+
+This action overrides any previous use of
+\csopt{encapsulate-fields*} within the same \idx{resourceset}, and
+is always performed after \csopt{encapsulate-fields}, regardless of
+the order in the \idx{resourceset}['s] list of options, so if the
+same field is listed in both settings, its value will end up as:
+\begin{codeenv}
+\cmd{\meta{cs-name-2arg}}\marg{\cmd{\meta{cs-name-1arg}}\margm{value}}\margm{label}
+\end{codeenv}
+
+\optsection[\subsubsection]{interpret-fields}
+
+This option indicates that the listed fields should be replaced by
+their interpreted values. The value is required for this key but
+may be empty, which indicates an empty set of fields (that is, the
+setting is switched off). Other fields not listed may still be
+interpreted depending on other settings. As with the \field{sort}
+field, any special characters are replaced with commands like
+\ics{glsbackslash} and \ics{bibglsdollarchar}. This option is
+applied after \csopt{field-case-change} (if set).
+
+For example, suppose I have a file \filefmt{entries.bib} that
+contains definitions like:
+\begin{codeenv}
+\atentry{symbol}\marg{pi,
+ \field{name}=\marg{\cs{ensuremath}\marg{\ics{pi}}},
+ \field{description}=\marg{the ratio of a circle's circumference to its diameter},
+}
+\strut
+\atentry{symbol}\marg{sigma,
+ \field{name} = \marg{\cs{ensuremath}\marg{\ics{sigma}}},
+ \field{description} = \marg{standard deviation}
+}
+\end{codeenv}
+Instead of having a list of terms (glossary), suppose I want to have
+standalone definitions, where the term appears in a section heading.
+I could define a command like this:
+\begin{codeenv}
+\cs{newcommand}\marg{\cmd{definition}}[1]\marg{\comment{}
+ \cs{ifglsentryexists}\marg{\idx{param}1}\comment{}
+ \marg{\comment{}
+ \cs{section}\oarg{\cs{glsentryname}\marg{\idx{param}}}\marg{\cs{glsadd}\marg{\idx{param}1}\ics{glsxtrglossentry}\marg{\idx{param}1}}\comment{}
+ \ics{Glossentrydesc}\marg{\idx{param}1}\cs{glspostdescription}
+ }\comment{}
+ \marg{\cs{section}\oarg{Missing `\idx{param}1'}\marg{\cs{glsadd}\marg{\idx{param}1}}}\comment{}
+}
+\end{codeenv}
+which can be used in the document:
+\begin{codeenv}
+\ics{tableofcontents}
+\cmd{definition}\marg{pi}
+\cmd{definition}\marg{sigma}
+\end{codeenv}
+A problem with this definition of my custom command occurs if I add
+\sty{hyperref} to the document, because this tries to write \cs{pi}
+and \cs{sigma} to the PDF bookmarks, which doesn't work because
+those commands can't be automatically converted to characters
+permitted in a PDF string. This leads to a warning from
+\sty{hyperref}:
+\begin{alltt}
+Token not allowed in a PDF string (Unicode)
+\end{alltt}
+Ideally I'd like to be able to convert these symbols to Unicode so
+that they can appear in the bookmarks. Since \bibgls' interpreter
+recognises these commands, I can get it to make the conversion
+instead of trying to implement a method within \TeX:
+\begin{codeenv}
+\cs{glsaddstoragekey}\marg{pdfname}\marg{}\marg{\cmd{pdfname}}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries]{src},
+ \csopt[\field{name}=\fieldfmt{pdfname}]{replicate-fields},
+ \csopt[fallback]{replicate-missing-field-action},
+ \csopt[\fieldfmt{pdfname}]{interpret-fields}
+}
+\end{codeenv}
+This first copies the \field{name} field to the custom
+\fieldfmt{pdfname} and then interprets the copy. This leaves
+the \field{name} field with the \LaTeX\ code to produce the symbol
+in the document, but the \fieldfmt{pdfname} field ends up with all markup
+stripped by the interpreter and the \cs{pi} and \cs{sigma} are
+converted to the Unicode characters \hex{1D70B} (mathematical italic
+small pi) and \hex{1D70E} (mathematical italic small sigma). With
+\XeLaTeX\ or \LuaLaTeX\ these characters can be written to the PDF
+bookmarks by adjusting the definition of the custom command:
+\begin{codeenv}
+\cs{newcommand}\marg{\cmd{definition}}[1]\marg{\comment{}
+ \cs{ifglsentryexists}\marg{\idx{param}1}\comment{}
+ \marg{\comment{}
+ \cs{section}
+ \oarg{\ics{texorpdfstring}\marg{\cs{glsentryname}\marg{\idx{param}1}}\marg{\cmd{pdfname}\marg{\idx{param}1}}}
+ \marg{\cs{glsadd}\marg{\idx{param}1}\cs{glsxtrglossentry}\marg{\idx{param}1}}\comment{}
+ \cs{Glossentrydesc}\marg{\idx{param}1}\cs{glspostdescription}
+ }\comment{}
+ \marg{\cs{section}\oarg{Missing `\idx{param}1'}\marg{\cs{glsadd}\marg{\idx{param}1}}}%
+}
+\end{codeenv}
+
\optsection[\subsubsection]{date-time-fields}
This option indicates that the listed fields all contain
@@ -8661,7 +9960,7 @@ fields parsed according to \csopt{dual-date-time-field-format} and
\csopt{dual-date-time-field-locale}. If the field value is missing
or doesn't match the given pattern it remains unchanged, otherwise
it's converted into the form:
-\nosecdef{bibglsdatetime}
+\formatdef{bibglsdatetime}
where \meta{original} is the value of the field before conversion.
If the interpreter is on, the value will be interpreted before
being parsed if it contains \idx{escchar}, \idx{mshiftchar},
@@ -8674,7 +9973,7 @@ being parsed if it contains \idx{escchar}, \idx{mshiftchar},
As \csopt{date-time-fields} but for fields that only contain date
(not time) information. If parsed correctly, the field is converted
to:
-\nosecdef{bibglsdate}
+\formatdef{bibglsdate}
The fields are parsed according to
\csopt{date-field-format} and
\csopt{date-field-locale} for primary entries and according to
@@ -8686,7 +9985,7 @@ The fields are parsed according to
As \csopt{date-time-fields} but for fields that only contain time
(not date) information. If parsed correctly, the field is converted
to:
-\nosecdef{bibglstime}
+\formatdef{bibglstime}
The fields are parsed according to
\csopt{time-field-format} and
\csopt{time-field-locale} for primary entries and according to
@@ -8930,9 +10229,11 @@ are skipped until a word-boundary is found.
skipped. If the option is \optfmt{title} then the subsequent tokens
are skipped until a word-boundary is found.
- \item If the control sequence is \ics{NoCaseChange}, then the
+ \item If the control sequence is \ics{NoCaseChange} or is in the
+ \csopt{no-case-change-cs} list, then the
control sequence and its argument is ignored. With \optfmt{firstuc}
and \optfmt{title}, if \code{\ics{NoCaseChange}\margm{text}}
+ (but not any \csopt{no-case-change-cs} command)
occurs at the start of a word, then \bibgls\ will act as though
the word hasn't started yet (so the next token will be considered
for a \idx{case-change}). This is different to the way \ics{makefirstuc}
@@ -9222,6 +10523,26 @@ HT\cs{textcolor}\marg{RED}\marg{ML}
which is incorrect. Instead, provide a command that hides the label
(such as the \csfmt{strong} example described on page~\glsxtrpageref{strong}).
+\optsection[\subsubsection]{no-case-change-cs}
+
+Instructs the non-\TeX\ case-changing options (where \bibgls, not
+\TeX, performs the modification) to treat the commands whose control
+sequence names are given in the comma-separated \meta{list} in the
+same way as it treats \cs{ensuremath} etc. That is, the case-change
+is omitted for the argument that follows any of those commands.
+
+For example, this manual defines some semantic commands such as
+\csfmt{fieldfmt} (to format field names), \csfmt{abbrstylefmt}
+(to format abbreviation style names) and \csfmt{glostylefmt} (to format
+glossary style names). These occur in some of the section
+and subsection headings in the \hyperref[sec:topics]{topic summary}
+which are converted to \idx{titlecase} (see \csopt{field-case-change}).
+These formatting commands shouldn't have their argument changed so they
+are identified with:
+\begin{codeenv}
+\csopt[fieldfmt,abbrstylefmt,glostylefmt]{no-case-change-cs}
+\end{codeenv}
+
\optsection[\subsubsection]{word-boundaries}
Governs how the \optfmt{title} \idx{case-change} option
@@ -9281,6 +10602,43 @@ the \field{name} field is missing no action is performed.
Applies a case-change to the \field{description} field (if present).
This option may take one of the values described above.
+\optsection[\subsubsection]{field-case-change}
+
+A general case-change instruction. The value should be a
+comma-separated list of \code{\meta{field}\dequals\meta{setting}} for each
+field that needs a case-change applied. The value is required for this key but
+may be empty, which indicates this option is switched off.
+
+The \meta{setting} should be
+the same as the permitted values for the above options. This
+option is applied after all fields have been parsed but before
+\csopt{interpret-fields}. If the
+specified field is missing, the fallback for that field (if known) is copied
+into the field. For example:
+\begin{codeenv}
+\csopt[\field{user1}=uc,\field{user2}={firstuc}]{field-case-change}
+\end{codeenv}
+This manual provides a custom storage key called
+\fieldfmt{nametitle}:
+\begin{codeenv}
+\cs{glsxtrprovidestoragekey}\marg{\fieldfmt{nametitle}}\marg{}\marg{}
+\end{codeenv}
+The resource options copy the \field{name} value to this custom
+field and convert \fieldfmt{nametitle} to \idx{titlecase}:
+\begin{codeenv}
+\csopt[\field{name}=\fieldfmt{nametitle}]{replicate-fields},
+\csopt[\fieldfmt{nametitle}=title]{field-case-change},
+\end{codeenv}
+This means that the \hyperref[sec:topics]{topic summary}
+(page~\pageref{sec:topics}) can fetch the value of
+\fieldfmt{nametitle} instead of \field{name}, which provides an
+expandable \idx{titlecase} form that's suitable for the PDF
+bookmarks.
+
+This option isn't cumulative. If used multiple times in the same
+\idx{resourceset}, the last instance will be the one used. If
+the \keyvallist\ is missing, no general case-changing is applied
+(the default).
\section{Plurals}
\label{sec:plurals}
@@ -9588,7 +10946,7 @@ provided by \styfmt{glossaries}. For example:
\cs{glsfieldfetch}\marg{gls.sample}\marg{loclist}\marg{\cmd{loclist}}\comment{fetch location list}
\cs{glsnoidxloclist}\marg{\cmd{loclist}}\comment{iterate over locations}
\end{codeenv}
-This uses \ics{glsnoidxloclisthandler} as the list's handler
+This uses \ics{glsnoidxloclisthandler} as the list's \idx{handler}
macro, which simply displays each location separated by \ics{delimN}.
(See also
\href{http://www.dickimaw-books.com/latex/admin/html/foreachtips.shtml}{Iteration
@@ -9742,7 +11100,7 @@ You can switch from using the \field{location} field to the
\cs{renewcommand}\marg{\cs{GlsXtrLocationField}}\marg{primarylocations}\comment{}
}
\end{codeenv}
-Remember that the handler used by \cs{printunsrtglossary} will
+Remember that the \idx{handler} used by \cs{printunsrtglossary} will
fallback on the \field{loclist} field if the field identified
by \cs{GlsXtrLocationField} is missing or empty. You may want to
consider using \csopt[false]{save-loclist} to prevent this.
@@ -9985,7 +11343,7 @@ considered consecutive.
then the locations aren't considered consecutive.
\item\label{itm.csmatch} If both \meta{location-1} and \meta{location-2} match the
pattern (line break for clarity only)\footnote{The Java class \code{\csfmt{p}\marg{javaDigit}}
-used in the regular expression will match any digits in the
+used in the \idx{regex} will match any digits in the
Unicode \idx{numberdecimaldigit} category not just the digits in the Basic Latin set. Similarly \code{\csfmt{p}\marg{javaAlphabetic}} will also match alphabetic
characters outside the Basic Latin set.}
\begin{verbatim}
@@ -10209,6 +11567,51 @@ empty string. To remove the suffix formation use
The default is \csopt[none]{suffixFF}.
+\optsection{compact-ranges}
+
+The \meta{value} may be an integer \meta{n} or \optfmt{false} (equivalent to
+\csopt[0]{compact-ranges}) or \optfmt{true} (equivalent to
+\csopt[3]{compact-ranges}). If no \meta{value} is specified,
+\optfmt{true} is assumed.
+
+This setting allows location ranges such as 184--189 to appear
+more compactly as 184--9. The end location is encapsulated
+in the command \gls{bibglscompact}, so the range would actually
+become:
+\begin{codeenv}
+184\ics{delimR}\gls{bibglscompact}\marg{digit}\marg{18}\marg{9}
+\end{codeenv}
+If the location is in the form \code{\meta{cs}\margm{loc}}
+(where \meta{cs} is a command)
+then \gls{bibglscompact} will be inside the argument.
+For example, if the range would normally be:
+\begin{codeenv}
+\cmd{custom}\marg{184}\ics{delimR}\cmd{custom}\marg{189}
+\end{codeenv}
+then it would become:
+\begin{codeenv}
+\cmd{custom}\marg{184}\ics{delimR}\cmd{custom}\marg{\gls{bibglscompact}\marg{digit}\marg{18}\marg{9}}
+\end{codeenv}
+The numerical value given in \csopt[\meta{n}]{compact-ranges}
+indicates that compaction should only occur if the actual location
+consists of at least \meta{n} characters, for $\meta{n} \geq 2$.
+Any value of \meta{n} less than 2 will switch off compaction.
+
+For example, \code{189} consists of 3 characters, so it will be
+compacted with \csopt[3]{compact-ranges} but not with
+\csopt[4]{compact-ranges}. Whereas \code{\csfmt{custom}\marg{89}}
+would only be compacted with \csopt[2]{compact-ranges}
+because \code{89} only consists of 2 characters.
+
+The compaction isn't limited to decimal digits but it will only
+occur if both the start and end location have the same number of
+characters. For example, xvi--xviii can't be compacted because
+the start consists of three characters and the end consists
+of five characters, whereas xxv--xxx can be compacted to xxv--x,
+which may look a little strange. In this case, you may want to
+consider changing the definition of \cs{bibglscompact} so that
+it only performs the compaction for digits.
+
\optsection{see}
If an entry has a \field{see} field, this can be placed before or
@@ -10932,7 +12335,50 @@ and also \csopt{sort-label-list} for sorting field values that
contain a comma-separated list of entry labels (such as the
\field{see} or \field{seealso} fields).
-Remember that you can have \atentry{preamble} definitions that
+The sort methods that use a comparison function (that is, all the
+sort methods except those listed in \tableref{tab:sortoptionsnosort})
+require a sort value for each entry. The function compares these
+values to determine the order. By default, this sort value is
+obtained from the \field{sort} field but for greater flexibility
+it's best to not actually set this field. \bibgls\ has a set of fallbacks
+that it uses if a field it needs to access is missing. These
+fallbacks depend on the entry type and resource settings.
+
+For example, if a term defined with \atentry{index} doesn't have the
+\field{sort} field set then \bibgls\ will use the value given by the
+\field{name} field because \field{name} is the fallback field for
+\field{sort} for \atentry{index} entries. If the \field{name} field
+isn't set either then \bibgls\ will use the fallback for that field.
+In the case of \atentry{index} that's the entry's label. If the
+\field{sort} field is explicitly set then there's no need to use the
+fallback.
+
+If, on the other hand, a term defined with \atentry{symbol} doesn't
+have the \field{sort} field set then \bibgls\ will use the value
+from the field identified by \csopt{symbol-sort-fallback}, which is
+the entry's label by default (not the \field{name} field).
+
+This means that if I don't explicitly set the \field{sort} field for
+any entries then I can, for example, sort terms defined with
+\atentry{index} by \field{name} and those defined with
+\atentry{symbol} by \field{description} with the setting:
+\begin{codeenv}
+\csopt[description]{symbol-sort-fallback}
+\end{codeenv}
+
+If the field used to obtain the sort value is changed
+(with \csopt{sort-field}) then the \field{sort} field won't be
+queried. This reduces the flexibility of selecting the most
+appropriate field for given entry types. For example,
+\csopt[name]{sort-field} will force all entries to be sorted by the
+\field{name} field, which may not be appropriate for symbols.
+
+\begin{important}
+If you choose a field whose value must be a label (such as
+\field{parent} or \field{group}) then the sort value will be that label.
+\end{important}
+
+You can have \atentry{preamble} definitions that
can be hidden from \bibgls's interpreter. For example,
\exfile{no-interpret-preamble.bib} might contain:
\begin{codeenv}
@@ -11902,12 +13348,19 @@ setting, the fallback for the \field{sort} field is governed not
only by the entry type but also by some associated settings:
\begin{itemize}
-\item For entries types like \atentry{entry} or \atentry{index},
-then if the \field{sort} field is missing the value is obtained from
-the \field{name} field. If that field is also missing, then the
-value is obtained from the particular entry type's fallback for the
-\field{name} field. (For example, \field{parent} for
-\atentry{entry}.)
+\item If the entry is defined using \atentry{entry} (or a dual form
+that acts like \atentry{entry}), then if the \field{sort} field is
+missing the value is obtained from the field identified by
+\csopt{entry-sort-fallback}. If that field is also missing then
+that field's fallback is used.
+
+\item For the index entry types like \atentry{index} or
+\atentry{indexplural}, then if the \field{sort} field is missing the
+value is obtained from the \field{name} field. If that field is also
+missing, then the value is obtained from the particular entry type's
+fallback for the \field{name} field. (For example, the entry's label
+for \atentry{index} or the \field{plural} field for
+\atentry{indexplural}.)
\item If the entry is defined with an abbreviation type (for
example, \atentry{abbreviation} or \atentry{acronym}) then if the
@@ -11940,16 +13393,26 @@ missing, then \bibgls\ will query the entry type's fallback for
\item If the entry type has a fallback rule for \meta{sort-field},
then that rule is used. When \csopt[sort]{sort-field} this means:
\begin{itemize}
+\item If the entry was defined using one of the index types (such as
+\atentry{index}), then \bibgls\ will fallback on the \field{name}
+field.
+
+\item If the entry was defined using the \atentry{entry} type (or a
+dual form that acts like \atentry{entry}), then \bibgls\ will
+fallback on the field given by \csopt{entry-sort-fallback}.
+
\item If the entry was defined using
-one of the symbol types, then \bibgls\
-will fallback on the value given by \csopt{symbol-sort-fallback}.
+one of the symbol types (such as \atentry{symbol}), then \bibgls\
+will fallback on the field given by \csopt{symbol-sort-fallback}.
+
\item If the entry was defined using
-one of the abbreviation types, then \bibgls\
-will fallback on the value given by
+one of the abbreviation types (such as \atentry{abbreviation}), then \bibgls\
+will fallback on the field given by
\csopt{abbreviation-sort-fallback}.
+
\item If the entry was defined using \atentry{bibtexentry} (but not
the spawned \atentry{contributor} entries), then \bibgls\ will
-fallback on the value given by
+fallback on the field given by
\csopt{bibtexentry-sort-fallback}.
\end{itemize}
If \meta{sort-field} is not \field{sort}, then there may not be a
@@ -11965,6 +13428,101 @@ separately from primaries, and use
\csopt{secondary-missing-sort-fallback} for \csopt{secondary}
sorting.
+\optsection{entry-sort-fallback}
+
+The regular entry types (such as \atentry{entry} and
+\atentry{dualentry}) will, by default, fallback on the \field{name}
+field if the \field{sort} field is missing (assuming
+\csopt[sort]{sort-field}). If you prefer to
+fallback on a different field, then you can use this option to
+specify the field.
+Note that \csopt{missing-sort-fallback} overrides this setting.
+
+This setting doesn't affect the index type of entries, such as
+\atentry{index} or \atentry{indexplural}. This is useful if your
+glossary contains homographs (terms with the same spelling) which
+can't be distinguished by the sort comparators. For example, suppose
+my file \filefmt{entries.bib} contains:
+\begin{codeenv}
+\atentry{index}\marg{pagelist,
+ \field{name}=\marg{page list},
+ \field{description}=\marg{a list of individual pages or page ranges}
+}
+\strut
+\atentry{index}\marg{glossary}
+\strut
+\atentry{entry}\marg{glossarylist,
+ \field{parent}=\marg{glossary},
+ \field{description}={list of technical words}
+}
+\strut
+\atentry{entry}\marg{glosscol,
+ \field{parent}=\marg{glossary},
+ \field{description}=\marg{collection of glosses}
+}
+\end{codeenv}
+Now first consider a document that uses the default settings:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\oarg{\styopt{record},\styopt{subentrycounter},\styopt[\glostyle{treenoname}]{style}}\marg{glossaries-extra}
+\strut
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}}
+\strut
+\cmd{begin}\marg{document}
+A test document describing \cs{glspl}\marg{pagelist} and
+\cs{gls}\marg{glosscol} (collection) vs \cs{gls}\marg{glossarylist} (list).
+\strut
+\cs{printunsrtglossary}
+\cmd{end}\marg{document}
+\end{codeenv}
+The default behaviour for \atentry{entry} if the \field{sort} field
+is missing is to fallback on the \field{name} field. If the
+\field{name} field is missing (as with \code{glossarylist} and
+\code{glosscol}), then the value is obtained from the
+\field{name} field from the parent entry. The parent entry for these
+homographs is the \code{glossary} entry, which was defined with
+\atentry{index} and doesn't have the \field{name} field. For the
+\atentry{index} entries, if \field{name} is missing the value is
+obtained from the label.
+
+Therefore both \code{glossarylist} and \code{glosscol} end
+up with the same sort value: \code{glossary}. This triggers a
+message in verbose mode (\longarg{verbose}) which can be found
+in the transcript file:
+\begin{verbatim}
+Identical sort values for 'glossarylist' and 'glosscol'
+Falling back on ID
+\end{verbatim}
+So the actual sort values used are \qt{glossarylist} and
+\qt{glosscol}. This puts the \code{glossarylist} entry
+before the \code{glosscol} entry.
+
+Now suppose a minor modification is made to the document:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}
+ \oarg{
+ \csopt[entries]{src},
+ \csopt[description]{entry-sort-fallback}
+ }
+\end{codeenv}
+This means that when the sort function fails to find the
+\field{sort} field for the terms defined with \atentry{entry}, it
+will fallback on the \field{description} field. This doesn't affect
+the terms defined with \atentry{index}, which still fallback on the
+\field{name} field. This time there's no message in the transcript
+file and the \code{glosscol} entry now comes before the
+\code{glossarylist} entry.
+
+\begin{important}
+The \csopt{entry-sort-fallback} setting is only used when \bibgls\
+tries to access the \field{sort} field for a term defined with
+\atentry{entry} and finds that the field hasn't been set. This means
+that this setting has no effect if you explicitly set the \field{sort}
+field or if you change the field used for sorting
+(\csopt{sort-field}).
+\end{important}
+
\optsection{abbreviation-sort-fallback}
The entry types that define abbreviations (such as
@@ -11980,6 +13538,14 @@ omitted. The \meta{field} value must be a known field label.
Note that \csopt{missing-sort-fallback} overrides this setting.
+\begin{important}
+The \csopt{abbreviation-sort-fallback} setting is only used when \bibgls\
+tries to access the \field{sort} field for an abbreviation and finds
+that the field hasn't been set. This means that this setting has no effect
+if you explicitly set the \field{sort} field or if you change the field used
+for sorting (\csopt{sort-field}).
+\end{important}
+
\optsection{symbol-sort-fallback}
The entry types that define symbols (such as \atentry{symbol} and
@@ -11992,6 +13558,14 @@ must be a known field label.
Note that \csopt{missing-sort-fallback} overrides this setting.
+\begin{important}
+The \csopt{symbol-sort-fallback} setting is only used when \bibgls\
+tries to access the \field{sort} field for a symbol and finds
+that the field hasn't been set. This means that this setting has no effect
+if you explicitly set the \field{sort} field or if you change the field used
+for sorting (\csopt{sort-field}).
+\end{important}
+
\optsection{bibtexentry-sort-fallback}
The main \atentry{bibtexentry} entry types will, by default,
@@ -12002,6 +13576,15 @@ field, then you can use this option to specify the field.
Note that \csopt{missing-sort-fallback} overrides this setting.
+\begin{important}
+The \csopt{bibtexentry-sort-fallback} setting is only used when
+\bibgls\ tries to access the \field{sort} field for a main entry
+defined with \atentry{bibtexentry} and finds that the field hasn't
+been set. This means that this setting has no effect if you
+explicitly set the \field{sort} field or if you change the field used for
+sorting (\csopt{sort-field}).
+\end{important}
+
\optsection{trim-sort}
If the interpreter is used to determine the sort value, this setting
@@ -12013,8 +13596,11 @@ and \csopt[\meta{boolean}]{secondary-trim-sort}.
\optsection{sort-replace}
-This option may be used to perform regular expression substitutions
+This option may be used to perform \idx{regex} substitutions
on the sort value and has the same syntax as \csopt{labelify-replace}.
+The value is required for this key but may be empty, which indicates
+that the setting is switched off.
+
This action is done after the interpreter parses the
sort value (if applicable) and before \csopt{sort-number-pad} (if
applicable). For example, suppose the sort value is:
@@ -13036,7 +14622,8 @@ the year and era:
If the \field{group} field hasn't been set in
the \ext{bib} file or through options like \csopt{group}, then it is
-assigned according to this option's setting during sorting. Permitted values:
+assigned according to this option's setting during sorting if
+\longarg{group} has been used. Permitted values:
\begin{itemize}
\item\optfmt{default}: the group is assigned according to
the sort method's default group formation. This is the default
@@ -13071,6 +14658,9 @@ significant character of the sort value. For example, the label
This option has no effect with \longarg{no-group} or if no sorting
is applied. Use \csopt{secondary-group-formation} for secondary
sorting and \csopt{dual-group-formation} for dual entries.
+Settings other than the default can cause the groups to become
+fragmented, so care is needed if you use this option.
+See also \sectionref{sec:logicaldivisions}.
\section{Secondary Glossary}
\label{sec:secondaryopts}
@@ -13469,6 +15059,11 @@ set with \csopt{type}). If the primary entry doesn't have the
\field{type} field set, the dual's \field{type} will remain
unchanged.
+\item \optfmt{same as parent}: sets the \field{type} to the same as
+the entry's parent (new to v1.9). If the entry doesn't have a parent
+or if the parent doesn't have the \field{type} field set, then
+no change is made.
+
\item \meta{label}: sets the \field{type} field to \meta{label}.
\end{itemize}
@@ -14562,6 +16157,205 @@ The definition written to the \ext{glstex} file is:
}
\end{codeenv}
+\cssection{bibglsnewprogenitor}
+
+\formatdef{bibglsnewprogenitor}
+This command is used to define the main terms created by
+\atentry{progenitor}. The definition is written to the \ext{glstex}
+file as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewprogenitor}}[4]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{}
+}
+\end{codeenv}
+
+\cssection{bibglsnewspawnindex}
+
+\formatdef{bibglsnewspawnindex}
+This command is used to define the main terms created by
+\atentry{spawnindex}. The definition is written to the \ext{glstex}
+file as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewspawnindex}}[4]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{}
+}
+\end{codeenv}
+
+\cssection{bibglsnewspawnedindex}
+
+\formatdef{bibglsnewspawnedindex}
+This command is used to define the terms spawned by
+\atentry{progenitor} or \atentry{spawnindex}. The definition is written
+to the \ext{glstex} file as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewspawnedindex}}[2]\marg{\comment{}
+ \gls{newglossaryentry}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}1},\field{category}={index},\field{description}=\marg{},\idx{param}2}\comment{}
+}
+\end{codeenv}
+
+\cssection{bibglsnewspawnindexplural}
+
+\formatdef{bibglsnewspawnindexplural}
+This command is used to define the main terms created by
+\atentry{spawnindexplural}. The definition is written to the \ext{glstex}
+file as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewspawnindexplural}}[4]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{}
+}
+\end{codeenv}
+
+\cssection{bibglsnewspawnedindexplural}
+
+\formatdef{bibglsnewspawnedindexplural}
+This command is used to define the terms spawned by
+\atentry{spawnindexplural}.
+The definition is written to the \ext{glstex} file as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewspawnedindexplural}}[3]\marg{\comment{}
+ \gls{newglossaryentry}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{category}=\marg{indexplural},\field{description}=\marg{},\idx{param}2}\comment{}
+}
+\end{codeenv}
+
+\cssection{bibglsnewspawnentry}
+
+\formatdef{bibglsnewspawnentry}
+This command is used to define the main terms created by
+\atentry{spawnentry}. The definition is written to the \ext{glstex}
+file as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewspawnentry}}[4]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{}
+}
+\end{codeenv}
+
+\cssection{bibglsnewspawnedentry}
+
+\formatdef{bibglsnewspawnedentry}
+This command is used to define the terms spawned by \atentry{spawnentry}.
+The definition is written to the \ext{glstex} file as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewspawnedentry}}[4]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{}
+}
+\end{codeenv}
+
+\cssection{bibglsnewspawnabbreviation}
+
+\formatdef{bibglsnewspawnabbreviation}
+This command is used to define the main terms created by
+\atentry{spawnabbreviation}. The definition is written to the \ext{glstex}
+file as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewspawnabbreviation}}[4]\marg{\comment{}
+ \gls{newabbreviation}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{}
+}
+\end{codeenv}
+
+\cssection{bibglsnewspawnedabbreviation}
+
+\formatdef{bibglsnewspawnedabbreviation}
+This command is used to define the terms spawned by \atentry{spawnabbreviation}.
+The definition is written to the \ext{glstex} file as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewspawnedabbreviation}}[4]\marg{\comment{}
+ \gls{newabbreviation}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{}
+}
+\end{codeenv}
+
+\cssection{bibglsnewspawnacronym}
+
+\formatdef{bibglsnewspawnacronym}
+This command is used to define the main terms created by
+\atentry{spawnacronym}. The definition is written to the \ext{glstex}
+file as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewspawnacronym}}[4]\marg{\comment{}
+ \gls{newacronym}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{}
+}
+\end{codeenv}
+
+\cssection{bibglsnewspawnedacronym}
+
+\formatdef{bibglsnewspawnedacronym}
+This command is used to define the terms spawned by \atentry{spawnacronym}.
+The definition is written to the \ext{glstex} file as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewspawnedacronym}}[4]\marg{\comment{}
+ \gls{newacronym}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{}
+}
+\end{codeenv}
+
+\cssection{bibglsnewspawnsymbol}
+
+\formatdef{bibglsnewspawnsymbol}
+This command is used to define the main terms created by
+\atentry{spawnsymbol}. The definition is written to the \ext{glstex}
+file as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewspawnsymbol}}[4]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{}
+}
+\end{codeenv}
+
+\cssection{bibglsnewspawnedsymbol}
+
+\formatdef{bibglsnewspawnedsymbol}
+This command is used to define the terms spawned by \atentry{spawnsymbol}.
+The definition is written to the \ext{glstex} file as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewspawnedsymbol}}[4]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{sort}=\marg{\idx{param}1},\field{category}=\marg{spawnedsymbol},\idx{param}2}\marg{\idx{param}4}}
+\end{codeenv}
+
+\cssection{bibglsnewspawnnumber}
+
+\formatdef{bibglsnewspawnnumber}
+This command is used to define the main terms created by
+\atentry{spawnnumber}. The definition is written to the \ext{glstex}
+file as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewspawnnumber}}[4]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{}
+}
+\end{codeenv}
+
+\cssection{bibglsnewspawnednumber}
+
+\formatdef{bibglsnewspawnednumber}
+This command is used to define the terms spawned by \atentry{spawnnumber}.
+The definition is written to the \ext{glstex} file as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewspawnednumber}}[4]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{sort}=\marg{\idx{param}1},\field{category}=\marg{spawnednumber},\idx{param}2}\marg{\idx{param}4}}
+\end{codeenv}
+
+\cssection{bibglsnewspawndualindexentry}
+
+\formatdef{bibglsnewspawndualindexentry}
+This command is used to define the \idx{progenitor}['s] primary term created by
+\atentry{spawndualindexentry}.
+The definition is written to the \ext{glstex} file as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewspawndualindexentry}}[4]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{category}=\marg{index},\idx{param}2}{}\comment{}
+}
+\end{codeenv}
+The \meta{description} argument is ignored.
+
+\cssection{bibglsnewspawndualindexentrysecondary}
+
+\formatdef{bibglsnewspawndualindexentrysecondary}
+This command is used to define the \idx{progenitor}['s] secondary
+(dual) term created by
+\atentry{spawndualindexentry}.
+The definition is written to the \ext{glstex} file as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewspawndualindexentrysecondary}}[4]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{}
+}
+\end{codeenv}
+
\section{Location Lists and Cross-References}
\label{sec:loclistdefs}
@@ -14639,6 +16433,19 @@ This defaults to \ics{delimN}.
Separator between penultimate and final individual locations.
This defaults to \code{,\idx{nbspchar}} to discourage lonely locations.
+\cssection{bibglscompact}
+
+\formatdef{bibglscompact}
+The first argument \meta{pattern} indicates the location pattern:
+\code{digit} for digits, \code{roman} for \idx!{lowercase}
+Roman numerals, \code{ROMAN} for \idx!{uppercase} Roman
+numerals and \code{alpha} for alphabetical locations. The actual
+location is split into two parts, \meta{part1} and \meta{part2}.
+The string concatenation \meta{part1}\meta{part2} forms the
+actual location.
+
+This just does \meta{part2} by default.
+
\cssection{bibglspassim}
\formatdef{bibglspassim}
@@ -15218,7 +17025,7 @@ For example, suppose the \ext{bib} file contains entries in the
form:
\begin{codeenv}
\atentry{dualentry}\marg{\meta{label},
- \field{name} = \marg{\ics{cjkname}\margm{\idx{CJK} characters}},
+ \field{name} = \marg{\gls{cjkname}\margm{\idx{CJK} characters}},
\field{description} = \margm{English translation}
}
\end{codeenv}
@@ -15230,7 +17037,7 @@ and the document contains:
\cs{newglossary*}\marg{japanese}\marg{Japanese to English}
\cs{newglossary*}\marg{english}\marg{English to Japanese}
\strut
-\ics{newrobustcmd}\marg{\cmd{cjkname}}[1]\marg{\cmd{begin}\marg{CJK}\marg{UTF8}\marg{min}\idx{param}1\cmd{end}\marg{CJK}}
+\ics{newrobustcmd}\marg{\gls{cjkname}}[1]\marg{\cmd{begin}\marg{CJK}\marg{UTF8}\marg{min}\idx{param}1\cmd{end}\marg{CJK}}
\strut
\gls{GlsXtrLoadResources}\oarg{
\csopt[testcjk]{src},\comment{bib file}
@@ -15244,19 +17051,19 @@ and the document contains:
then \idx{CJK} characters will appear in the \meta{title} argument of
\gls{bibglslettergrouptitle} which causes a problem because they need
to be encapsulated within the \env{CJK} environment. This can be more
-conveniently done with the user supplied \csfmt{cjkname}, but the \idx{CJK}
+conveniently done with the user supplied \inlinedef{cjkname}, but the \idx{CJK}
characters need to be protected from expansion so \ics{unexpanded} is
also needed. The new definition of \gls{bibglslettergrouptitle} needs
to be defined before \gls{GlsXtrLoadResources}. For example:
\begin{codeenv}
-\cs{newcommand}\marg{\gls{bibglslettergrouptitle}}[4]\marg{\cs{unexpanded}\marg{\cmd{cjkname}\marg{\idx{param}1}}}
+\cs{newcommand}\marg{\gls{bibglslettergrouptitle}}[4]\marg{\cs{unexpanded}\marg{\gls{cjkname}\marg{\idx{param}1}}}
\end{codeenv}
There's a slight problem here in that the English letter group titles
also end up encapsulated. An alternative approach is to use the
\meta{type} part to provide different forms. For example:
\begin{codeenv}
\cs{newcommand}*\marg{\cmd{englishlettergroup}}[1]\marg{\idx{param}1}
-\cs{newcommand}*\marg{\cmd{japaneselettergroup}}[1]\marg{\cmd{cjkname}\marg{\idx{param}1}}
+\cs{newcommand}*\marg{\cmd{japaneselettergroup}}[1]\marg{\gls{cjkname}\marg{\idx{param}1}}
\cs{newcommand}\marg{\gls{bibglslettergrouptitle}}[4]\marg{\comment{}
\cs{unexpanded}\marg{\cs{csuse}\marg{\idx{param}4lettergroup}\marg{\idx{param}1}}}
\end{codeenv}
@@ -15829,6 +17636,40 @@ have multiple resource sets, that option governs the way \bibgls's version of
\gls{bibglscontributor} behaves. The definition is written to the \ext{glstex}
using \cs{providecommand}, so \LaTeX\ will only pick up the first definition.
+\cssection{bibglsdatetime}
+
+\formatdef{bibglsdatetime}
+Used to encapsulate date-time fields identified with
+\csopt{date-time-fields}.
+Since \gls{bibglsdatetime} requires more than nine arguments, the
+remaining four arguments are picked up with:
+\nosecdef{bibglsdatetimeremainder}
+The default definitions are:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsdatetime}}[9]\marg{\gls{bibglsdatetimeremainder}}
+\cs{providecommand}\marg{\gls{bibglsdatetimeremainder}}[4]\marg{\idx{param}4}
+\end{codeenv}
+
+\cssection{bibglsdate}
+
+\formatdef{bibglsdate}
+Used to encapsulate date fields identified with
+\csopt{date-fields}.
+The default definition is:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsdate}}[7]\marg{\idx{param}7}
+\end{codeenv}
+
+\cssection{bibglstime}
+
+\formatdef{bibglstime}
+Used to encapsulate date fields identified with
+\csopt{time-fields}.
+The default definition is:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglstime}}[7]\marg{\idx{param}7}
+\end{codeenv}
+
\cssection{bibglsprimaryprefixlabel}
\formatdef{bibglsprimaryprefixlabel}
@@ -15913,6 +17754,7 @@ Converts the first letter of \meta{text} to \idx{uppercase}. This just uses
\chapter{Converting Existing \iext{tex} to \iext{bib}}
\label{sec:gls2bib}
+\setsecdepth{0}
If you have already been using the \styfmt{glossaries} or
\styfmt{glossaries-extra} package with a large file containing all your
@@ -15960,6 +17802,9 @@ sort value than either \idx!{makeindex} or \idx!{xindy}.
\item[\longargfmt{no-ignore-sort}] Don't ignore the \field{sort} field.
+\item[\longargfmt{locale} \meta{lang tag}] Identifies the \langxml\
+to use for \idx{convertgls2bib}['s] messages.
+
\item[\longargfmt{silent}] Suppress all messages except for errors.
\item[\longargfmt{verbose}] Display messages and warnings (default).
@@ -16293,7 +18138,7 @@ contain:
\chapter{Examples}
\label{sec:examples}
-\setcounter{secnumdepth}{0}
+\setsecdepth*{0}
The example files described here can be found in the
\filefmt{examples} sub-directory. The \ext{bib} files are listed
@@ -16975,6 +18820,8 @@ which is used to format the set contents,
which is used to format the set membership criteria,
\nosecdef{setcardfmt}
which is used to format the cardinality of a set,
+(Note this uses \ics{vert} not \textbar\ as in some of the earlier
+examples.)
\nosecdef{numspacefmt}
which is used to format \meta{symbol} as a number space,
\nosecdef{transposefmt}
@@ -17399,6 +19246,14 @@ are no custom fields here.
The contents of \filefmt{terms.bib} are as follows:
\lstinputlisting[firstline=5]{../examples/terms.bib}
+\filesection{topics.bib}
+
+The \exfile{topics.bib} file contains entries defined using
+\atentry{index}. Again there are no custom fields here.
+
+The contents of \filefmt{topics.bib} are as follows:
+\lstinputlisting[firstline=5]{../examples/topics.bib}
+
\filesection{sample-constants.tex}
This example uses the \exfile{constants.bib} file. The aim here
@@ -17643,6 +19498,8 @@ redefine this as well:
\end{codeenv}
(For a more compact layout, you could use \glostyle{mcolalttreegroup}
instead.)
+I also need the \longarg{group} switch to make the sort method
+automatically assign letter groups.
The complete code is listed below. The document build is:
\begin{verbatim}
@@ -17724,6 +19581,8 @@ the \ext{log} file, you may notice that \sty{glossary-tree} is still
loaded. This is because it's required by \sty{glossary-bookindex}
as the \glostyle{bookindex} style is based on the \glostyle{index}
style provided by \sty{glossary-tree}.
+With this style I need to use the \longarg{group} switch to instruct
+the sort method to automatically create the letter groups.
The \glostyle{bookindex} style doesn't show the \field{description}
field (which means I don't need the \catattr{glossdescfont}
@@ -17820,6 +19679,8 @@ for the second, and then set the group titles:
\end{codeenv}
I've used this method to make it easier to adapt to other languages
that may need extended characters in the group titles.
+The \csopt{group} option requires the \longarg{group} switch to
+ensure that the \field{group} field is correctly assigned.
The \exfile{baseunits.bib} file use a custom entry type
\atentryfmt{unit}, which must be aliased otherwise \bibgls\
@@ -17915,6 +19776,8 @@ for the second. Similarly for the custom entry fields:
\fieldfmt{measurement}=\field{description}
]{field-aliases}
\end{codeenv}
+The \longarg{group} switch is needed to ensure that the
+\field{group} field is automatically assigned by the sort method.
The complete document code is listed below. The document build is:
\begin{verbatim}
@@ -18022,6 +19885,9 @@ There are no sub-entries in this document so I haven't bothered to
redefine \ics{subglossentry}. (The tabular styles aren't appropriate
for hierarchical glossaries.) This puts the symbol into the third
column (rather than the location list, which is ignored).
+This style supports the letter group separator (although it doesn't
+title the groups), so if I want this I need to use the
+\longarg{group} switch.
I also need to make sure I've defined a glossary for the dual
entries:
@@ -18191,6 +20057,8 @@ the books that have been referenced by the film entries. Since this
looks a bit odd, I've added \csopt[false]{save-locations} to
prevent \bibgls\ from saving the locations.
+I've used a style that shows letter group headings so I need to use
+the \longarg{group} switch.
The complete document code is listed below. The document build is:
\begin{verbatim}
pdflatex sample-media
@@ -18221,6 +20089,8 @@ document. The first two lists shouldn't include aliases but the
index should. Not all the entries defined in \exfile{people.bib}
are included in the document. Those that aren't either explicitly
referenced or aliased are filtered by the \csopt{selection} criteria.
+I've used a style that shows letter group headings so I need to use
+the \longarg{group} switch.
Since this is just an example document all the \cs{gls} commands
only occur on page~1, which means that each number list is just
@@ -18508,6 +20378,8 @@ This example uses the files \exfile{people.bib},
in \exfile{books.bib} and have them listed by author. This means
finding a way of assigning each book entry a \field{parent} field that
contains the label identifying the relevant author in \exfile{people.bib}.
+I've used a style that shows letter group headings so I need to use
+the \longarg{group} switch.
To recap, each author is defined in \exfile{people.bib} in the form:
\begin{codeenv}
@@ -18723,6 +20595,13 @@ redefining \ics{glsxtrgroupfield} to \code{category}:
\cs{renewcommand}\marg{\cs{glstreegroupheaderfmt}}[1]\marg{\ics{textbf}\marg{\idx{param}1}}\comment{}
}
\end{codeenv}
+This again contradicts the advice given in
+\sectionref{sec:logicaldivisions} as I'm sorting by the
+\field{group} label. (Technically it's sorting by the
+\field{category} label but this is being used as the group.) In this
+case it's not a problem as the labels closely match the titles and
+the sorting options ensure that the groups aren't broken up.
+
There's no \field{description} field set for these entries, but the
\idx{postdescriptionhook} can still be used to append information.
In this case, I've appended a cross-reference to the bibliography.
@@ -18757,7 +20636,7 @@ This allows the titles to be listed as well:
\marg{\ics{par} No titles.}\comment{}
}
\end{codeenv}
-The handler macro displays the name of the associated
+The \idx{handler} macro displays the name of the associated
\atentry{bibtexentry} term and the citation:
\begin{codeenv}
\cs{newcommand}\marg{\csfmt{contributorhandler}}[1]\marg{\cs{par}\ics{glsentryname}\marg{\idx{param}1} \cs{cite}\marg{\idx{param}1}}
@@ -18766,7 +20645,7 @@ The handler macro displays the name of the associated
The complete document code is listed below. The document build is:
\begin{verbatim}
pdflatex sample-citations
-bib2gls --group --cite-as-record sample-citations
+bib2gls --cite-as-record sample-citations
bibtex sample-citations
pdflatex sample-citations
pdflatex sample-citations
@@ -18801,11 +20680,6 @@ the \styopt{stylemods} package option:
\styopt[mcols]{stylemods},\comment{load glossary-mcols.sty and patch}
\styopt[mcolalttree]{style}}\marg{glossaries-extra}
\end{codeenv}
-I'm not using a group-based style which suggests that I don't need the
-\longarg{group} switch. However, although I don't want group titles,
-I still want a slight gap between logical groups, which means that I
-still need this switch. If I added the \styopt{nogroupskip} package
-option, then I can omit \longarg{group}.
I'm not referencing any of the entries in the document as I'm just
generating a complete list of all the defined symbols. This means I
@@ -18818,22 +20692,28 @@ the \field{location} field:
Since I'm using a style that's based on \glostyle{alttree} I need to
find the widest \field{name}, which can be done with \csopt{set-widest}.
-I've used \csopt{field-aliases} to convert the custom
-\fieldfmt{identifier} field to \field{category}, which means I can
-also sort by that field:
+The simplest way of dividing the glossary into logical blocks is to
+sort according to the category, but first I need to use \csopt{field-aliases}
+to convert the custom \fieldfmt{identifier} field to \field{category}:
\begin{codeenv}
-\csopt[\field{category}]{sort-field},
\csopt[\fieldfmt{identifier}=\field{category}]{field-aliases}
\end{codeenv}
+and sort by the \field{category} field:
+\begin{codeenv}
+\csopt[\field{category}]{sort-field}
+\end{codeenv}
Since this will cause identical sort values, I need to provide a
-fallback. Here I've decided to fallback on the \field{description}
-field:
+a way of ordering these identical values. Here I've decided
+to fallback on the \field{description} field:
\begin{codeenv}
\csopt[\field{description}]{identical-sort-action}
\end{codeenv}
This means that entries will be ordered by \field{category} and
then \field{description}, which naturally creates blocks of symbol
-types in the glossary.
+types in the glossary. This only uses a simple case-sensitive string
+comparison which is fine for English, but for another language it
+would be better to use \csopt{sort-suffix} as in the
+\exfile{sample-textsymbols.tex} file.
Remember that I want a small vertical gap between each logical
block. These need the \field{group} field which, with the default
@@ -18850,15 +20730,22 @@ fetch its value from the \field{category} field:
\end{codeenv}
(Since the \csopt{field-aliases} option is always performed before
\csopt{replicate-fields}, the \field{category} field will already
-have been set and is available for replicating.) This means that the
-\field{group} label is the same as the \field{category} label rather
-than just the first letter. (For a quick check, change the glossary
-style to \glostyle{mcolalttreegroup} to display the group titles.)
+have been set and is available for replicating.)
+
+This means that I'm essentially sorting by the \field{group} labels,
+which this manual has warned against doing. In this case, it's an
+acceptable break from that rule as I've used options that ensure the
+groups aren't broken up during sorting and I'm not concerned with the group
+titles. A method such as that used in \exfile{sample-textsymbols2.tex}
+would end up with titled blocks, which I don't want here. By using
+resource options such as \csopt{field-aliases} and
+\csopt{replicate-fields} I can avoid the warning that's triggered
+with the default \longarg{warn-non-bib-fields}.
The complete document code is listed below. The document build is:
\begin{verbatim}
pdflatex sample-msymbols
-bib2gls --group sample-msymbols
+bib2gls sample-msymbols
pdflatex sample-msymbols
\end{verbatim}
The resulting document is shown in \figureref{fig:sample-msymbols.pdf}.
@@ -18895,6 +20782,11 @@ I've aliased \fieldfmt{format} to \field{user1} since \gls!{glsxtrfmt}
defaults to that field. If I decided to use a different field I also
need to remember to redefine \ics{GlsXtrFmtField} to match.
+As with \exfile{sample-msymbols.tex} I'm sorting by the
+\field{category} label and this value is copied to the \field{group}
+field, but again I don't have a hierarchical glossary as the logical
+blocks don't have titles.
+
In this document I only want to select entries that have been
indexed, so I've omitted the \csopt{selection} option I used in the
\exfile{sample-msymbols.tex} example, however
@@ -18931,7 +20823,8 @@ Be careful with the set cardinality example. You might be tempted to
nest \csfmt{set} within the argument of \csfmt{setcard} but this
results in nested hyperlinks. These are unpredictable and there's no
consistent handling of them between different PDF viewers. It can
-also be confusing to the reader. If $|\mathcal{B}_1\cup\mathcal{B}_2|$
+also be confusing to the reader. If
+$\lvert\mathcal{B}_1\cup\mathcal{B}_2\rvert$
shows up as what appears to be a single hyperlink, where would the
reader expect the target? This is the reason for providing the
non-linking commands like \csfmt{nlset} and \csfmt{nlsetcard}.
@@ -18939,7 +20832,7 @@ non-linking commands like \csfmt{nlset} and \csfmt{nlsetcard}.
The complete document code is listed below. The document build is:
\begin{verbatim}
pdflatex sample-maths
-bib2gls --group sample-maths
+bib2gls sample-maths
pdflatex sample-maths
\end{verbatim}
The resulting document is shown in \figureref{fig:sample-maths.pdf}.
@@ -18957,8 +20850,8 @@ The resulting document is shown in \figureref{fig:sample-maths.pdf}.
\filesection{sample-textsymbols.tex}
-This example uses \exfile{miscsymbols.bib}. This requires both
-\isty{marvosym} and (with the \styoptfmt{weather} option)
+This example uses \exfile{miscsymbols.bib}.
+This requires both \isty{marvosym} and (with the \styoptfmt{weather} option)
\isty{ifsym}. Unfortunately both define the commands \csfmt{Sun}
and \csfmt{Lightning}, so these commands need to be undefined after
the first package is loaded and before the second.
@@ -18982,7 +20875,7 @@ demonstrates how to deal with such conflicts.)
The custom entry type \atentryfmt{icon} must be aliased for the
entries to be recognised:
\begin{codeenv}
-\csopt[unit=symbol]{entry-type-aliases}
+\csopt[icon=symbol]{entry-type-aliases}
\end{codeenv}
Since none of the entries have a \field{name} or \field{description}
@@ -19026,15 +20919,23 @@ since it doesn't recognise any of the commands, so it will have to
use the fallback command, which will use one of the commands
provided by the \sty{glossaries-extra-stylemods} package.
+This is actually not the best method as \bibgls\ can't see the group
+titles as they're in the document, so it's only able to sort by the
+label. While this might work for English, it can become a problem
+for other languages that use extended Latin or non-Latin characters
+in their alphabet. A much better method is to treat this as a
+hierarchical glossary with topic titles as the top-level entries.
+This is covered in the next example \exfile{sample-textsymbols2.tex}.
+
The complete document code is listed below. The document build is:
\begin{verbatim}
pdflatex sample-textsymbols
-bib2gls --group sample-textsymbols
+bib2gls sample-textsymbols
pdflatex sample-textsymbols
\end{verbatim}
The resulting document is shown in \figureref{fig:sample-textsymbols.pdf}.
-\lstinputlisting[firstline=5]{../examples/sample-textsymbols.tex}
+\lstinputlisting[firstline=6]{../examples/sample-textsymbols.tex}
\begin{figure}
\figcontents
@@ -19045,6 +20946,86 @@ The resulting document is shown in \figureref{fig:sample-textsymbols.pdf}.
{fig:sample-textsymbols.pdf}
\end{figure}
+\filesection{sample-textsymbols2.tex}
+
+This example is a better approach than the
+\exfile{sample-textsymbols.tex} example above. As with the previous
+example, this requires both \isty{marvosym} and \isty{ifsym} so the
+same patch is applied to avoid conflict.
+
+As before, the custom entry type \atentryfmt{icon} must be aliased for the
+entries to be recognised:
+\begin{codeenv}
+\csopt[icon=symbol]{entry-type-aliases}
+\end{codeenv}
+
+The \exfile{topics.bib} file contains terms with
+labels that match the custom \fieldfmt{identifier} fields used in
+the \exfile{miscsymbols.bib} file. So both files are loaded and the
+\fieldfmt{identifier} field is now aliased to \field{parent}. These
+parent entries represent the topics and unlike the previous example
+it's now possible to sort by the topic title (obtained from the
+\field{name} field) instead of by the label.
+\begin{codeenv}
+\csopt[topics,miscsymbols]{src},
+\csopt[
+ \fieldfmt{identifier}=\field{parent},
+ \fieldfmt{icon}=\field{name},
+ \fieldfmt{icondescription}=\field{description}]{field-aliases},
+\end{codeenv}
+There's no \csopt{sort-field} option in this example. The default
+\field{sort} field is used. Since it's not set for any of the
+entries, the fallback value will be used. In the case of the topic
+titles (\atentry{index} and \atentry{indexplural}), I want to sort
+by the \field{name}, which is the default fallback if the
+\field{sort} field is missing for the index entry types.
+
+The default fallback for the \field{sort} field for \atentry{symbol}
+entries is the label, but in this case I want to use the
+\field{description} field:
+\begin{codeenv}
+ \csopt[description]{symbol-sort-fallback}
+\end{codeenv}
+The best styles for this kind of glossary are the topic styles
+provided by \isty{glossary-topic}. This package was only added to
+\sty{glossaries-extra} v1.40, so you need to make sure you have at
+least that version installed.
+
+In this case I've decided to use the \glostyle{topic} style. I can
+use it with or without the \csopt{set-widest} option.
+As with the previous example, \bibgls\ won't be able to determine
+the widest name since it doesn't recognise any of the commands
+contained in the \field{name} fields, so it will have to use the
+fallback method, which will use one of the commands provided by the
+\sty{glossaries-extra-stylemods} package. The \code{tree} option is
+needed to enable the appropriate commands:
+\begin{codeenv}
+\cmd{usepackage}\oarg{\styopt{record},
+ \styopt{nostyles},
+ \styopt{postdot},
+ \styopt[tree,topic]{stylemods},
+ \styopt[topic]{style}}\marg{glossaries-extra}
+\end{codeenv}
+
+The complete document code is listed below. The document build is:
+\begin{verbatim}
+pdflatex sample-textsymbols2
+bib2gls --group sample-textsymbols2
+pdflatex sample-textsymbols2
+\end{verbatim}
+The resulting document is shown in \figureref{fig:sample-textsymbols2.pdf}.
+
+\lstinputlisting[firstline=5]{../examples/sample-textsymbols2.tex}
+
+\begin{figure}
+\figcontents
+{%
+ \frame{\includegraphics[height=.9\textheight]{../examples/sample-textsymbols2.pdf}}%
+}
+{\caption{\filefmt{sample-textsymbols2.pdf}}}
+{fig:sample-textsymbols2.pdf}
+\end{figure}
+
\filesection{sample-markuplanguages.tex}
This example uses \exfile{markuplanguages.bib}. Since the file
@@ -19291,7 +21272,7 @@ field is required. The simplest way to get this is to use
given field (\fieldfmt{language} in this case) and break out of the
loop (with \ics{glsxtrendfor}) once the language has been found.
-The handler function (\csfmt{addfirstlang}) is defined so that it
+The \idx{handler} function (\csfmt{addfirstlang}) is defined so that it
adds the given language tag as a tracked language using
\ics{TrackLocale}. This command sets
\ics{TrackLangLastTrackedDialect} to the associated
@@ -20541,6 +22522,7 @@ The resulting document is shown in \figureref{fig:sample-multi2.pdf},
\printstyoptsummary
\printcommandsummary
+%\printcommandtopic
\bibliographystyle{plain}
\bibliography{bib2gls-cite}
@@ -20559,6 +22541,9 @@ The resulting document is shown in \figureref{fig:sample-multi2.pdf},
{\nobreak\cleaders\hbox to .44em{\hss\textcolor{lightgray}{.}\hss}\hfill}%
{\glsxtrprelocation}%
}
+\renewcommand{\printunsrtglossaryentryprocesshook}[1]{%
+ \glsxtrifhasfield*{progenitor}{#1}{\printunsrtglossaryskipentry}{}%
+}
\renewcommand*{\unicodecategoryfmt}[1]{\textsf{#1}}
\printunsrtglossary[type=index]
\end{document}