diff options
Diffstat (limited to 'Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex')
-rw-r--r-- | Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex | 2453 |
1 files changed, 1484 insertions, 969 deletions
diff --git a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex index 4f3dc88f5cf..39cd070365a 100644 --- a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex +++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex @@ -9,6 +9,8 @@ \documentclass[titlepage=false,index=totoc,bibliography=totoc, fontsize=12pt,captions=tableheading]{scrreprt} +\usepackage{pifont} + % Need support for extended characters % and need a mono font that supports hyphenation \usepackage[no-math]{fontspec} @@ -27,7 +29,6 @@ \usepackage{etoolbox} \usepackage{hologo} -\usepackage{xcolor} \usepackage{amsmath} \usepackage{accents} \usepackage{tikz} @@ -41,12 +42,15 @@ entrycounter,% enable entry counting subentrycounter,% enable entry counting %debug=showtargets,% debugging information - stylemods=bookindex,% adjust predefined styles and load glossary-bookindex.sty + stylemods={mcols,bookindex},% adjust predefined styles and load glossary-mcols.sty and glossary-bookindex.sty style=bookindex ] {glossaries-extra} +\renewcommand*{\glsshowtarget}[1]{\texttt{\small [#1]}} + \glsxtrprovidestoragekey{note}{}{} +\glsxtrprovidestoragekey{package}{}{} \providecommand{\omicron}{o} @@ -85,12 +89,19 @@ \newcommand{\glsxtrpostnameenvironment}{\space environment} \newcommand{\glsxtrpostnamecounter}{\space counter} +\newcommand*{\csfmt}[1]{% + \texorpdfstring + {\texttt{\char`\\ #1}}% + {\string\\#1}% +} + \setabbreviationstyle[common]{short-nolong} \GlsXtrLoadResources[ label-prefix={idx.}, save-loclist=false, sort={letternumber-nocase}, + sort-replace={{\glshex2423}{ },{\string\\([a-zA-Z])}{\glscapturedgroup1}}, type={index}, dual-field={dualid}, match-action={add}, @@ -177,15 +188,10 @@ \let\-\empty } -\newcommand*{\csfmt}[1]{% - \texorpdfstring - {\texttt{\char`\\ #1}}% - {\string\\#1}% -} - % Provide commands that work like \gls[#1]{idx.#2}[#3] \glsxtrnewglslike{idx.}{\idx}{\idxpl}{\Idx}{\Idxpl} +\newcommand{\idxlink}[3][]{\glslink[#1]{idx.#2}{#3}} \newcommand{\stringu}{\idx{cs.string}\idx{u}} @@ -206,6 +212,7 @@ {\string\\jobname-#1.glstex}% } +\newcommand{\extstyopt}{\textsuperscript{\textdagger}} \newcommand*{\appfmt}[1]{\texorpdfstring{\texttt{#1}}{#1}} \newcommand*{\styfmt}[1]{\texorpdfstring{\textsf{#1}}{#1}} @@ -297,7 +304,7 @@ \newcommand*{\styopt}[2][]{% \texorpdfstring% {% - \idx{styopt.#2}\styoptfmt{\ifblank{#1}{}{\dequals\marg{#1}}}% + \gls{styopt.#2}\styoptfmt{\ifblank{#1}{}{\dequals\marg{#1}}}% }% {#2\ifblank{#1}{}{=#1}}% } @@ -513,6 +520,69 @@ }% } +\newglossarystyle{styoptsummary}% +{% + \setglossarystyle{mcolindex}% + \renewcommand{\glossarypreamble}{% + Most options are in the form \meta{option}=\meta{value} and + may have a default if \meta{value} is omitted, + but some options don't have values and should not have + one assigned. For boolean options, + if the value is omitted \styoptfmt{true} is assumed. + \extstyopt Indicates a value that's only provided by + \styfmt{glossaries-extra} and not by the base + \styfmt{glossaries} package. \par + }% + \renewcommand*{\glossaryheader}{}% + \renewcommand*{\glsgroupheading}[1]{% + \glsxtrgetgrouptitle{##1}{\thisgrptitle}% + \glsxtrbookindexbookmark{\thisgrptitle}{styopt.##1}% + \glsxtrbookindexformatheader{\thisgrptitle}% + \nopagebreak\indexspace\nopagebreak\csuse{@afterheading}% + }% + \renewcommand*{\glossentry}[2]{% + \item \glstarget{##1}{\strut}% + \glsxtrifhasfield{dualid}{##1}% + {% + \glshyperlink{\glscurrentfieldvalue}% + }% + {% + \gls[hyper=false]{##1}% + }% + \glsxtrifhasfield{useri}{##1}{=\glscurrentfieldvalue}{}% + \nopagebreak\par\hspace{10pt}% + \Glossentrydesc{##1}.% + \glsxtrifhasfield{package}{##1}% + {\nopagebreak\par \ding{43}Provided by + \ifdefstring{\glscurrentfieldvalue}{glossaries,glossaries-extra} + {\styfmt{glossaries} and modified by \styfmt{glossaries-extra}}% + {\styfmt{\glscurrentfieldvalue}}.}% + {}% + \glsxtrifhasfield{note}{##1}% + {\space \xmakefirstuc{\glscurrentfieldvalue}.}% + {}% + \par\medskip + }% +} + +\newcommand*{\styoptsummaryhook}[1]{% + \edef\currentcategory{\glscategory{#1}}% + \ifdefstring{\currentcategory}{packageoption}% + {}% + {\printunsrtglossaryskipentry}% +} + +\newcommand*{\printstyoptsummary}{% + \printunsrtglossary*[type=main, + style=styoptsummary, + title={Package Option Summary} + ]% + {% + \let\printunsrtglossaryentryprocesshook\styoptsummaryhook + \glsxtrlocalsetgrouptitle{glssymbols}{@}% + }% +} + \newcommand{\entrysection}[2][\subsection]{% #1[\texorpdfstring{\glsxtrheadname{entry.#2}}{\glsentryname{entry.#2}}] {\glsadd{entry.#2}\glsxtrglossentry{entry.#2}}% @@ -672,14 +742,12 @@ files} \DTMsetstyle{pdf} \protected@edef\x{\endgroup \noexpand\hypersetup{% - pdfinfo={ - Title={\@title}, - Author={\@author}, - CreationDate={\DTMuse{creation}}, - ModDate={\DTMuse{moddate}}, - }% - %\noexpand\pdfinfo{/CreationDate (\DTMuse{creation}) - %/ModDate (\DTMuse{moddate})} + pdfinfo={ + Title={\@title}, + Author={\@author}, + CreationDate={\DTMuse{creation}}, + ModDate={\DTMuse{moddate}}, + }% }% }\x @@ -726,6 +794,11 @@ entry definitions using commands like \gls{newglossaryentry} then you can use the supplementary tool \idx{convertgls2bib} to convert the entries to the \ext{bib} format required by \bibgls. See \sectionref{sec:gls2bib} for further details. + +The supplementary file \filefmt{bib2gls-begin.pdf} is an +introductory guide to the \sty{glossaries-extra} package, which you +may prefer to start with if you are unfamiliar with the +\sty{glossaries} and \sty{glossaries-extra} packages. \end{abstract} \frontmatter @@ -757,8 +830,13 @@ from the \ext{bib} file. Since \bibgls\ can also perform hierarchical sorting and can collate location lists, it doubles as an indexing application, which means that the \idx{makeglossaries} step can be skipped. +Note that \bibgls\ doesn't warn you if an entry that's referenced +in the document doesn't exist in any of the supplied \ext{bib} +files, but instead relies on the \styfmt{glossaries-extra} package +to generate the warning. So at the end of the document build check +the \ext{log} file for warnings. -You can't use \ics{glsaddall} with this method as that command works +You can't use \ics{glsaddall} with \bibgls\ as that command works by iterating over all defined entries and calling \ics{glsadd}\margm{label}. On the first \LaTeX\ run there are no entries defined, so \ics{glsaddall} does nothing. If you want to @@ -1557,7 +1635,7 @@ For example, suppose the \ext{bib} file includes: protects against the possibility that the \catattr{glossname} category attribute might be set to \optfmt{firstuc}, which automatically converts the first letter of the name to -upper case when displaying the glossary. See also +\idx{uppercase} when displaying the glossary. See also \longarg{mfirstuc-protection} and \longarg{mfirstuc-math-protection}.) @@ -1611,7 +1689,7 @@ texparserlib: {}$\mtx{M}$ -> M So the \field{sort} value for this entry is set to \qtt{M}. The font change (caused by math-mode and \ics{boldsymbol}) has been ignored. The sort value therefore consists of a single Unicode -character \hex{4D} (Latin upper case letter \qtt{M}, decimal value 77). +character \hex{4D} (Latin \idx!{uppercase} letter \qtt{M}, decimal value 77). For the \code{v} entry, the code is: \begin{verbatim} @@ -1623,7 +1701,7 @@ texparserlib: \marg{}\$\csfmt{vec}\marg{v}\$ -> \usebox\varrow \end{alltt} So the \field{sort} value for this entry is set to \qtt{\usebox\varrow}, which consists of two Unicode characters \hex{76} -(Latin lower case letter \qtt{v}, decimal value 118) and +(Latin \idx!{lowercase} letter \qtt{v}, decimal value 118) and \hex{20D7} (combining right arrow above, decimal value 8407). For the \code{set} entry, the code is: @@ -1636,7 +1714,7 @@ texparserlib: {}$\set{S}$ -> S \end{verbatim} So the \field{sort} value for this entry is set to \qtt{S} (again ignoring the font change). This consists of a single Unicode -character \hex{53} (Latin upper case letter \qtt{S}, decimal value~83). +character \hex{53} (Latin \idx!{uppercase} letter \qtt{S}, decimal value~83). For the \code{card} entry, the code is: \begin{verbatim} @@ -1652,7 +1730,7 @@ in \atentry{preamble} have been included, but the font change has been discarded). In this case the sort value consists of three Unicode characters \hex{7C} (vertical line, decimal value 124), -\hex{53} (Latin upper case letter \qtt{S}, decimal value 83) and +\hex{53} (Latin \idx!{uppercase} letter \qtt{S}, decimal value 83) and \hex{7C} again. If \csopt[false]{interpret-preamble} had been used, \csfmt{card} wouldn't be recognised and would be discarded leaving just \qtt{S} @@ -1701,7 +1779,7 @@ letter.) If \csopt[letter-nocase]{sort} is used instead then, after conversion by the interpreter, the sort values will all be changed to -lower case. The order is now: \code{i} ($\imaginary$), +\idx{lowercase}. The order is now: \code{i} ($\imaginary$), \code{M} ($\mtx{M}$), \code{S} ($\set{S}$), \code{v} ($\vec{v}$) and \code{card} ($\card{S}$). The transcript (with \longarg{verbose}) now shows @@ -1721,7 +1799,7 @@ M -> 'm' (M) [109] S -> 's' (S) [115] v -> '\usebox\varrow' (V) [118 8407] \end{alltt} -Note that the letter groups are upper case not lower case. +Note that the letter groups are \idx{uppercase} not \idx{lowercase}. Again the \code{card} entry doesn't have an associated letter group. @@ -1846,6 +1924,14 @@ written to the transcript file, which can be inspected afterwards. Specify the preferred \langxml, where \meta{lang} is a valid \idx{IETF} language tag. This option requires an appropriate \metafilefmt{bib2gls-}{lang}{.xml} resource file otherwise \bibgls\ will fallback on English. +This also sets the default document locale when \csopt[doc]{sort} is +used and the document doesn't have any language support. +Note that \csopt[locale]{sort} uses the \idx{JVM}['s] default +locale and is not governed by this switch. + +If a document doesn't have any locale support or has support +for more than one language then it's best to explicitly set +the required locale in the appropriate \idx{resourceset}. \argsection{log-file} @@ -1916,7 +2002,12 @@ for more details. \argsection{no-interpret} Switch off the interpreter mode. See \sectionref{sec:texparserlib} -for more details. +for more details about the interpreter. If the interpreter is off, +the transcript (\iext{log}) file won't be parsed, so if you need +\bibgls\ to know that you are using \sty{fontspec} but you don't +want the interpreter on then you must use +\longarg{packages}\code{ fontspec} to indicate that UTF-8 is +natively supported. \argsection{no-break-space} @@ -2138,7 +2229,7 @@ This works in the same way as \longarg{mfirstuc-protection} but guards against fields starting with inline maths (\idx{mshiftchar}\ldots\idx{mshiftchar}). For example, if the \field{name} field starts with \verb|$x$| and the glossary style automatically tries to -convert the first letter of the name to upper case, then this will +convert the first letter of the name to \idx{uppercase}, then this will cause a problem. With \longarg{mfirstuc-math-protection} set, \bibgls\ will @@ -2349,7 +2440,7 @@ can't use non-ASCII characters in \meta{label} with \sty{inputenc} \end{description} The \idx{lettergroup} titles will typically have the first character -converted to upper case for the alphabet sort methods +converted to \idx{uppercase} for the alphabet sort methods (\tableref{tab:sortoptionsrule}). A \qt{letter} may not necessarily be a single character (depending on the sort rule), but may be composed of multiple characters, such as a \idx{digraph} (two @@ -2364,8 +2455,8 @@ by the following line in the \langxml: <entry key="grouptitle.case.ij">IJ</entry> \end{verbatim} If there isn't a \code{grouptitle.case.\meta{lc}} key (where -\meta{lc} is the lower case version), then only the first character -will be converted to upper case otherwise the value supplied by the +\meta{lc} is the \idx!{lowercase} version), then only the first character +will be converted to \idx{uppercase} otherwise the value supplied by the resource file is used. This resource key is only checked for the alphabetical comparisons listed in \tableref{tab:sortoptionsrule}. If the initial part of the sort @@ -2380,7 +2471,7 @@ alphabetical\footnote{according to Java's \code{Character.isAlphabetic(int)} method} then it will be a \idx{lettergroup} otherwise it's a \idx{nonlettergroup}. The case-insensitive ordering (such as \csopt[letter-nocase]{sort}) will convert the -letter group character to upper case. The case-sensitive ordering +letter group character to \idx{uppercase}. The case-sensitive ordering (such as \csopt[letter-case]{sort}) won't change the case. Glossary styles with navigational links to groups (such as @@ -2808,6 +2899,12 @@ option instead. \caption[Fields Set by \bibgls]{Fields Sometimes Set by \bibgls\ in the \iext{glstex} File} \label{tab:internalfields} +You may define and assign \field{bibtextype} (although it's more +likely to be aliased). Don't define any of others, and don't use any +of them in the \ext{bib} file, except for \field{group}, +\field{sort} or \field{type} although those three are best +assigned in the resource command or by \bibgls.\par +\bigskip \centering \printfields{internalfield}% \end{table} @@ -2815,8 +2912,12 @@ the \iext{glstex} File} \begin{table}[hbtp] \caption[Internal Fields Set by \styfmt{glossaries} or \styfmt{glossaries-extra} or \bibgls]{Internal Fields Set by -\styfmt{glossaries} or \styfmt{glossaries-extra} or \bibgls\ -(don't use in \ext{bib} files)}\label{tab:baseinternalfields} +\styfmt{glossaries} or \styfmt{glossaries-extra} or \bibgls}% +\label{tab:baseinternalfields} +\medskip +Don't define any of these and don't use any of them in the \ext{bib} +file.\par +\bigskip \centering \printfields{baseinternalfield}% \end{table} @@ -3255,6 +3356,52 @@ Example: Terms that are defined using \atentry{index} will be written to the output file using the command \csref{bibglsnewindex}. +\entrysection{indexplural} + +The \atentry{indexplural} entry type is similar to the +\atentry{index} entry type except that the \field{name} field if +missing is obtained from the \field{plural} field. If the +\field{plural} field is missing it's obtained from the \field{text} +field with the plural suffix appended. If the \field{text} field is +missing, it's obtained from the original entry label. If the +\field{sort} field is missing the default is obtained from the +\field{name} field. All fields are optional. For example: +\begin{verbatim} +@indexplural{goose, + plural = {geese} +} + +@indexplural{duck} + +@indexplural{chateau, + text = {ch\^ateau}, + plural = {ch\^ateaux} +} +\end{verbatim} +This is equivalent to: +\begin{verbatim} +@indexplural{goose, + name = {geese}, + text = {goose}, + plural = {geese} +} + +@indexplural{duck, + name = {ducks}, + text = {duck}, + plural = {ducks} +} + +@indexplural{chateau, + name = {ch\^ateaux}, + text = {ch\^ateau}, + plural = {ch\^ateaux} +} +\end{verbatim} + +Terms that are defined using \atentry{indexplural} will be written to the output +file using the command \csref{bibglsnewindexplural}. + \entrysection{abbreviation} The \atentry{abbreviation} entry type is designed for abbreviations. @@ -3304,7 +3451,7 @@ instead do: \setabbreviationstyle{long-short-sc} \GlsXtrLoadResources[src={entries-abbrv.bib},ignore-fields={description}] \end{verbatim} -or to convert the short value to upper case and use the +or to convert the short value to \idx{uppercase} and use the \abbrstyle{long-short-sm} style instead: \begin{verbatim} \setabbreviationstyle{long-short-sm} @@ -4661,7 +4808,7 @@ for each selected \atentry{bibtexentry} associated with that contributor. The second line provides the internal list field \field{bibtexentry@entrytype}, where \meta{entry-type} is the original entry type (before it was aliased to -\atentry{bibtexentry} and converted to lower case). +\atentry{bibtexentry} and converted to \idx!{lowercase}). For example \code{article} or \code{book}. You can iterate over these internal list fields using @@ -5564,6 +5711,101 @@ that tertiary entries are created when dual entries are defined in the \ext{glstex} file, so this will increase the total number of entries. +\section{Hierarchical Options} +\label{sec:hierarchicalopts} + +\optsection{save-child-count} + +This is a boolean option. The default setting is +\csopt[false]{save-child-count}. +If \csopt[true]{save-child-count}, +each entry will be assigned a field called \field{childcount} with +the value equal to the number of child entries that have been +selected. As from version 1.5, this option also creates +the \field{childlist} field for entries that have children +selected. This field is in \sty{etoolbox}'s internal list +format and can be iterated over using \ics{glsxtrfieldforlistloop}. + +The assignment is done using \ics{GlsXtrSetField} so there's +no associated key. You can test if the field is set and non-zero +using: +\nosecformatdef{GlsXtrIfHasNonZeroChildCount} +which is provided with \sty{glossaries-extra-bib2gls} v1.31+. +Within \meta{true}, you can access the actual value with +\ics{glscurrentfieldvalue}. If \csopt[false]{save-child-count}, +this command will do \meta{false} as the \field{childcount} field +won't be set. + +For example, suppose \filefmt{entries.bib} contains: +\begin{verbatim} +@index{birds} +@index{duck,parent={birds}} +@index{goose,plural={geese},parent={birds}} +@index{swan,parent={birds}} + +@index{minerals} +@index{quartz,parent={minerals}} +@index{corundum,parent={minerals}} +@index{amethyst,parent={minerals}} +@index{gypsum,parent={minerals}} +@index{gold,parent={minerals}} +\end{verbatim} +and the document contains: +\begin{verbatim} +\documentclass{article} + +\usepackage[record,style=indexgroup]{glossaries-extra} + +\GlsXtrLoadResources[src={entries},save-child-count] + +\begin{document} +\gls{duck} and \gls{goose}. +\gls{quartz}, \gls{corundum}, \gls{amethyst}. + +\printunsrtglossaries +\end{document} +\end{verbatim} +Then the \ext{glstex} file will contain: +\begin{verbatim} +\GlsXtrSetField{birds}{childcount}{2} +\GlsXtrSetField{duck}{childcount}{0} +\glsxtrfieldlistadd{birds}{childlist}{duck} +\GlsXtrSetField{goose}{childcount}{0} +\glsxtrfieldlistadd{birds}{childlist}{goose} +\GlsXtrSetField{minerals}{childcount}{3} +\GlsXtrSetField{amethyst}{childcount}{0} +\glsxtrfieldlistadd{minerals}{childlist}{amethyst} +\GlsXtrSetField{corundum}{childcount}{0} +\glsxtrfieldlistadd{minerals}{childlist}{corundum} +\GlsXtrSetField{quartz}{childcount}{0} +\glsxtrfieldlistadd{minerals}{childlist}{quartz} +\end{verbatim} +Note that although \code{birds} has three children defined in the +\ext{bib} file, only two have been selected, so the child count is +set to 2. Similarly the \code{minerals} entry has five children +defined in the \ext{bib} file, but only three have been selected, so +the child count is 3. + +The following uses the post-description hook to show the child count +in parentheses: +\begin{verbatim} +\GlsXtrLoadResources[src={entries},category=general,save-child-count] + +\renewcommand{\glsxtrpostdescgeneral}{% + \glsxtrifhasfield{childcount}{\glscurrententrylabel} + { (child count: \glscurrentfieldvalue.)}% + {}% +} +\end{verbatim} +\ics{glsxtrifhasfield} requires at least \sty{glossaries-extra} v1.19. +It's slightly more efficient that \ics{ifglshasfield} provided by +the base \styfmt{glossaries} package, and it doesn't complain if the +entry or field don't exist, but note that \ics{glsxtrifhasfield} +implicitly scopes its content. Use the starred version to omit the +grouping. With \sty{glossaries-extra} v1.31+ you can perform a +numerical test with \ics{GlsXtrIfFieldNonZero} or +\ics{GlsXtrIfFieldEqNum}. + \optsection{flatten} This is a boolean option. The default value is \csopt[false]{flatten}. @@ -5924,6 +6166,124 @@ In the above, the location list includes records and cross-references obtained from the \field{see} or \field{seealso} fields. See \csopt{flatten-lonely} for further details. +\optsection{strip-missing-parents} + +The \sty{glossaries} package requires that all child entries must be +defined after the parent entry. An error occurs otherwise, so +\bibgls\ will omit the \field{parent} field if it can't be found in +the given \idx{resourceset}. However, when the default +\csopt[false]{strip-missing-parents} is on, this omission only occurs +while writing the definitions in the \ext{glstex} file (after +selection and sorting). + +Sorting is performed hierarchically and the \field{group} field is set +accordingly for the top-level entries (but not for child entries), +which means that an entry with a \field{parent} field will be +treated by the sort method as a child entry. This can lead to a +strange result, which \bibgls\ warns about: +\begin{alltt} +Parent '\meta{parent id}' not found for entry \meta{child-id} +\end{alltt} + +This is the default behaviour as it may simply be a result of a +typing mistake in the \field{parent} field. If you actually want +missing parents to be stripped before sorting (but after the +selection process) then use \csopt[true]{strip-missing-parents}. If +you want all parents stripped then use \csopt{flatten} or +\csopt[parent]{ignore-fields} instead. As from version 1.4, if you +want \bibgls\ to create the missing parents, then you can use +\csopt[create]{missing-parents}. + +\optsection{missing-parents} + +As an alternative to \csopt{strip-missing-parents}, as from version +1.4 you can now use \csopt[\meta{value}]{missing-parents} where +\meta{value} may be one of: +\begin{itemize} +\item \optfmt{strip}: this is equivalent to +\csopt[true]{strip-missing-parents}; + +\item \optfmt{warn}: this is equivalent to the default +\csopt[false]{strip-missing-parents}; + +\item \optfmt{create}: this will create a new \atentry{index} +entry with the missing parent's label (after it's been processed by +options such as \csopt{labelify}) with the \field{name} obtained +from the \emph{original} value of the \field{parent} field (before being +processed by options like \csopt{labelify}). +If the child entry has the \field{type} field set, then the new +parent entry will be given the same value. The \field{category} for +the new parent entry can be assigned with +\csopt{missing-parent-category}. +\end{itemize} + +For example, consider the \exfile{books.bib} file which contains +entries like +\begin{verbatim} +@entry{ubik, + name={Ubik}, + description={novel by Philip K. Dick}, + identifier={book}, + author={\sortmediacreator{Philip K.}{Dick}}, + year={1969} +} +\end{verbatim} +then the field alias +\begin{codeenv} +\csopt[author=parent]{field-aliases} +\end{codeenv} +will treat +\begin{verbatim} + author={\sortmediacreator{Philip K.}{Dick}}, +\end{verbatim} +as though it had been defined as +\begin{verbatim} + parent={\sortmediacreator{Philip K.}{Dick}}, +\end{verbatim} +This can be converted into a label with the options: +\begin{codeenv} + \csopt[parent]{labelify}, + \csopt[ + \marg{[ \cs{cs.string}\csfmt{.}]}\marg{} + ]{labelify-replace} +\end{codeenv} +If the interpreter has been provided with the definition: +\begin{verbatim} +\providecommand*{\sortmediacreator}[2]{#2 #1} +\end{verbatim} +then the \field{parent} field for the \code{ubik} entry +will become \code{DickPhilipK} but the original value is stored +internally when \csopt[create]{missing-parents} is set so that it +can be used as the \field{name} if the parent needs to be created. +Once all the entries have been processed, if \code{ubik} has been +selected but no entry can be found with the label \code{DickPhilipK} +then a new entry will be added as though it had been defined with: +\begin{verbatim} +@index{DickPhilipK, + name={\sortmediacreator{Philip K.}{Dick}} +} +\end{verbatim} +This is an alternative approach to the \exfile{sample-authors.tex} +document from the \hyperref[sec:examples]{examples chapter}. + +\optsection{missing-parent-category} + +If a missing parent entry is created through the use of +\csopt[create]{missing-parents} then the \field{category} field can +be assigned to the new parent entry with this option. The +\meta{value} may be one of: +\begin{itemize} + \item \code{same as child}: the parent entry's \field{category} + field is set to the same value as the child's (if set); + \item \code{same as base}: the parent entry's \field{category} is + set to the base name of the \ext{bib} file that provided the + child entry's definition; + \item \code{no value}: don't set the \field{category} field; + \item \meta{label}: the parent entry's \field{category} field is set to + \meta{label} (which shouldn't contain any special characters). +\end{itemize} +The default setting is \csopt[no value]{missing-parent-category}. + \section{Master Documents} \label{sec:master} @@ -6161,7 +6521,7 @@ supplementary resource files (omitting the primary \end{verbatim} \section{Field and Label Options} -\label{sec:labelopts} +\label{sec:fieldlabelopts} The options in this section may be used to set or adjust field values or labels. Some field values are expected to be labels (such @@ -6169,197 +6529,10 @@ as \field{group}). These labels must not contain special characters or commands, but it's possible to convert a field value into a valid label using options such as \csopt{labelify}. -\optsection{group} - -The \csopt{group} option may only be used with the \longarg{group} switch. -This will set the \field{group} field to \meta{label} unless -\meta{label} is \optfmt{auto}, in which case the value is -set automatically during the sorting (see also -\csopt{group-formation}). -The corresponding title can be set -with \gls{glsxtrsetgrouptitle} if the title is different from the -label. The default behaviour is \csopt[auto]{group}. - -For example: -\begin{verbatim} -\GlsXtrLoadResources[sort=integer,group={Constants}, - src={entries-constants}% data in entries-constants.bib -] -\GlsXtrLoadResources[sort=letter-case,group={Variables}, - src={entries-variables}% data in entries-variables.bib -] -\end{verbatim} -In this case, if the \field{type} field hasn't been set in the \ext{bib} files, -these entries will be added to the same glossary, but will -be grouped according to each instance of \gls{GlsXtrLoadResources}, -with the provided group label. - - -\optsection{category} - -The selected entries may all have their \field{category} field -changed before writing their definitions to the \ext{glstex} file. -The \meta{value} may be: -\begin{itemize} -\item \optfmt{same as entry}: set the -\field{category} to the \ext{bib} entry type used to define it -(lower case and without the initial \code{@}) after any aliasing, -if applicable; - -\item \optfmt{same as original entry}: (new to v1.4) set the \field{category} -to the original entry type (lower case and without -the initial \code{@}) before it was aliased (behaves like -\optfmt{same as entry} if the entry type wasn't aliased); - -\item \optfmt{same as base}: (new to v1.1) set the \field{category} -to the base name of the \ext{bib} file (without the extension) -that provided the entry definition; - -\item \optfmt{same as type}: set the \field{category} to the same -value as the \field{type} field (if that field has been provided -either in the \ext{bib} file or through the \csopt{type} option); - -\item \meta{label}: the \field{category} is set to -\meta{label} (which mustn't contain any special characters). -\end{itemize} -This will override any -\field{category} fields supplied in the \ext{bib} file. - -When used with \csopt{entry-type-aliases}, the option \csopt[same as -entry]{category} refers to the \emph{target} entry type whereas -\csopt[same as original entry]{category} refers to the -\emph{original} entry type given in the \ext{bib} file. In both -cases, the value is converted to lower case to ensure consistency. - -For example, if the \ext{bib} file contains: -\begin{verbatim} -@entry{bird, - name={bird}, - description = {feathered animal} -} - -@index{duck} - -@index{goose,plural="geese"} - -@dualentry{dog, - name={dog}, - description={chien} -} -\end{verbatim} -then if the document contains -\begin{verbatim} -\GlsXtrLoadResources[category={same as entry},src={entries}] -\end{verbatim} -this will set the \field{category} of the \code{bird} term to -\optfmt{entry} (since it was defined with \atentry{entry}), the \field{category} of the \code{duck} and -\code{goose} terms to \optfmt{index} (since they were defined -with \atentry{index}), and the \field{category} of the \code{dog} -term to \optfmt{dualentry} (since it was -defined with \atentry{dualentry}). Note that the dual entry -\code{dual.dog} doesn't have the category set, since that's -governed by \csopt{dual-category} instead. - -If, instead, the document contains -\begin{verbatim} -\GlsXtrLoadResources[category={animals},src={entries}] -\end{verbatim} -then the \field{category} of all the primary selected entries will -be set to \optfmt{animals}. Again the dual entry \code{dual.dog} -doesn't have the \field{category} set. - -Note that the categories may be overridden by the commands, -such as \csref{bibglsnewindex}, that are used to actually define the -entries. - -For example, if the document contains -\begin{verbatim} -\newcommand{\bibglsnewdualentry}[4]{% - \longnewglossaryentry*{#1}{name={#3},#2,category={dual}}{#4}% -} - -\GlsXtrLoadResources[category={animals},src={entries}] -\end{verbatim} -then both the \code{dog} and \code{dual.dog} entries will -have their \field{category} field set to \optfmt{dual} since the -new definition of \gls{bibglsnewdualentry} has overridden -the \csopt[animals]{category} option. - -\optsection{type} - -The \meta{value} may be one of: -\begin{itemize} - \item \optfmt{same as entry} set the \field{type} field - to the entry type (lower case and without the initial \code{@}); - - \item \optfmt{same as original entry} set the \field{type} - to the original entry type (lower case and without - the initial \code{@}) before it was aliased (behaves like - \optfmt{same as entry} if the entry type wasn't aliased); - - \optfmt{same as base} set the \field{type} field - to the base name of the corresponding \ext{bib} file - (without the extension); - - \item \optfmt{same as category} set the \field{type} field - to the same value as the \field{category} field - (\field{type} unchanged if \field{category} not set); - - \item\meta{label} sets the \field{type} field to the glossary - identified by \meta{label}. -\end{itemize} -When used with \csopt{entry-type-aliases}, the option \csopt[same as -entry]{type} refers to the \emph{target} entry type and \csopt[same -as original entry]{type} refers to the \emph{original} entry type -given in the \ext{bib} file. It's not possible to have both -\csopt[same as type]{category} and \csopt[same as category]{type}. - -Note that this setting only changes the \field{type} field for -primary entries. Use \csopt{dual-type} for dual entries. - -For example: -\begin{verbatim} -\usepackage[record,symbols]{glossaries-extra} - -\GlsXtrLoadResources[src={entries-symbols},type=symbols] -\end{verbatim} - -Make sure that the glossary type has already been defined -(see \sectionref{sec:newglossary}). In the above, the -\styopt{symbols} option defines the \code{symbols} glossary. -If you want to use a custom glossary, you need to provide it. For -example: -\begin{verbatim} -\usepackage[record,nomain]{glossaries-extra} - -\newglossary*{dictionary}{Dictionary} - -\GlsXtrLoadResources[src={entries-symbols},type=dictionary] -\end{verbatim} -(The \styopt{nomain} option was added to suppress the -creation of the default \code{main} glossary.) - -\optsection{trigger-type} - -The record counting commands, such as \ics{rgls}, use the special -format \ics{glstriggerrecordformat}, which \bibgls\ also treats -as an \idx{ignoredrecord}. This means the entry will still be -identified as having a record for selection purposes, which is -necessary for the entry to be defined for use in the document, but -in order to prevent it from appearing in the glossary you need to -transfer the entry with \csopt[\meta{type}]{trigger-type}. -This will override the \csopt{type}, \csopt{dual-type}, -\csopt{tertiary-type} and the type specification in -\csopt{secondary}. - -The provided value \meta{type} must be a glossary label (not one of -the keywords allowed by \csopt{type}). -You can define the glossary before loading the resource, but -it's not required as \bibgls\ will write -\ics{provideignoredglossary*}\margm{type} to the \ext{glstex} file -(see \sectionref{sec:newglossary}). +\subsection{Label Options} +\label{sec:labelopts} -\optsection{interpret-label-fields} +\optsection[\subsubsection]{interpret-label-fields} This is a boolean option that determines whether or not the fields that may only contain labels should have their values interpreted @@ -6381,7 +6554,7 @@ can't be used in labels and may be used more generally for other fields. The \csopt{labelify} and \csopt{labelify-list} options are performed before \csopt{interpret-label-fields}. -\optsection{labelify} +\optsection[\subsubsection]{labelify} This option should take a comma-separated list of recognised field names as the value. (If a field is present in both \csopt{labelify} and @@ -6465,7 +6638,7 @@ to retain the original: ] \end{verbatim} -\optsection{labelify-list} +\optsection[\subsubsection]{labelify-list} This option is like \csopt{labelify} but it retains commas, as it's designed for fields that should be converted into a comma-separated @@ -6488,7 +6661,7 @@ or \end{verbatim} depending on whether or not \sty{fontspec} was detected. -\optsection{labelify-replace} +\optsection[\subsubsection]{labelify-replace} This option takes a comma-separated list as a value with each element in the list in the form \margm{regex}\margm{replacement} @@ -6500,7 +6673,24 @@ file so take care to protect any special characters. For example, to match a literal \idx{full-stop} use \cs{cs.string}\ics{cs.period} rather than just \ics{cs.period} (backslash dot). -Both \csopt{labelify} and \csopt{labelify-list} use this setting to +In the \meta{replacement} part, you can use +\ics{glscapturedgroup}\meta{n} to reference a captured sub-sequence. +For example: +\begin{verbatim} +\csopt[{([A-Z])\string\.}{\glscapturedgroup1}]{labelify-replace} +\end{verbatim} +This removes any \idx{full-stop} that follows any of the characters +A,\ldots,Z. Alternatively, you can just use \verb|\string\$| +instead of \cs{glscapturedgroup}. If you want a literal dollar +character, you need to use \cs{glshex}\code{24} (or +\verb|\string\u|). This isn't recommended for labels (since special +characters are automatically stripped), but +\csopt{sort-replace} follows the same rules as +\csopt{labelify-replace}, and it may be needed +for that. + +Both \csopt{labelify} and \csopt{labelify-list} use the +\csopt{labelify-replace} setting to perform substitutions. For example, to replace the sub-string \qt{ and } (including spaces) with a comma: \begin{verbatim} @@ -6551,125 +6741,462 @@ or \end{verbatim} depending on whether or not \sty{fontspec} was detected. -\optsection{strip-missing-parents} +\optsection[\subsubsection]{label-prefix} -The \sty{glossaries} package requires that all child entries must be -defined after the parent entry. An error occurs otherwise, so -\bibgls\ will omit the \field{parent} field if it can't be found in -the given \idx{resourceset}. However, when the default -\csopt[false]{strip-missing-parents} is on, this omission only occurs -while writing the definitions in the \ext{glstex} file (after -selection and sorting). +The \csopt{label-prefix} option prepends \meta{tag} to each +entry's label. This \meta{tag} will also be inserted in front of any +cross-references, unless they start with \idprefix{dual} or +\idprefix{extn} (where \meta{n} is an integer). Use +\csopt{dual-prefix} to change the dual label prefixes and +\csopt{ext-prefixes} to change the external label prefixes. -Sorting is performed hierarchically and the \field{group} field is set -accordingly for the top-level entries (but not for child entries), -which means that an entry with a \field{parent} field will be -treated by the sort method as a child entry. This can lead to a -strange result, which \bibgls\ warns about: -\begin{alltt} -Parent '\meta{parent id}' not found for entry \meta{child-id} -\end{alltt} +For example, if the \ext{bib} file contains +\begin{verbatim} +@entry{bird, + name={bird}, + description = {feathered animal, such as a \gls{duck} or \gls {goose}} +} -This is the default behaviour as it may simply be a result of a -typing mistake in the \field{parent} field. If you actually want -missing parents to be stripped before sorting (but after the -selection process) then use \csopt[true]{strip-missing-parents}. If -you want all parents stripped then use \csopt{flatten} or -\csopt[parent]{ignore-fields} instead. As from version 1.4, if you -want \bibgls\ to create the missing parents, then you can use -\csopt[create]{missing-parents}. +@entry{waterfowl, + name={waterfowl}, + description={Any \gls{bird} that lives in or about water}, + see={[see also]{duck,goose}} +} -\optsection{missing-parents} +@index{duck} -As an alternative to \csopt{strip-missing-parents}, as from version -1.4 you can now use \csopt[\meta{value}]{missing-parents} where -\meta{value} may be one of: -\begin{itemize} -\item \optfmt{strip}: this is equivalent to -\csopt[true]{strip-missing-parents}; +@index{goose,plural="geese"} +\end{verbatim} +Then if this \ext{bib} file is loaded with \csopt[gls.]{label-prefix} +it's as though the entries had been defined as: +\begin{verbatim} +@entry{gls.bird, + name={bird}, + description = {feathered animal, such as a \gls{gls.duck} or +\gls{gls.goose}} +} -\item \optfmt{warn}: this is equivalent to the default -\csopt[false]{strip-missing-parents}; +@entry{gls.waterfowl, + name={waterfowl}, + description={Any \gls{gls.bird} that lives in or about water}, + see={[see also]{gls.duck,gls.goose}} +} -\item \optfmt{create}: this will create a new \atentry{index} -entry with the missing parent's label (after it's been processed by -options such as \csopt{labelify}) with the \field{name} obtained -from the \emph{original} value of the \field{parent} field (before being -processed by options like \csopt{labelify}). -If the child entry has the \field{type} field set, then the new -parent entry will be given the same value. The \field{category} for -the new parent entry can be assigned with -\csopt{missing-parent-category}. +@index{gls.duck,name={duck}} + +@index{gls.goose,name={goose},plural="geese"} +\end{verbatim} + +Remember to use this prefix when you reference the terms in the +document with commands like \ics{gls}. + +\optsection[\subsubsection]{duplicate-label-suffix} + +The \sty{glossaries} package doesn't permit entries with duplicate +labels (even if they're in different glossaries). If you +have multiple \idxpl{resourceset} and an entry that's selected +in one \idx{resourceset} is also selected in another, by +default, \bibgls\ will issue a warning, but it will still write the +entry definition to the \ext{glstex} file, which means you'll also +get a warning from \sty{glossaries-extra} and the duplicate +definition will be ignored, but associated internal fields +set with commands like \cs{GlsXtrSetField} may still be set. + +If you actually want the duplicate, you need to specify a +suffix with \csopt{duplicate-label-suffix}. This suffix is only +set just before writing the entry definition to the \ext{glstex} +file, so it doesn't affect selection criteria nor can label +substitutions be performed in any cross-references. Options such as +\csopt{set-widest} that reference entry labels are incompatible +as they will use the unsuffixed label. + +The actual suffix is formed from \meta{value}\meta{n} where \meta{n} +is an integer that's incremented in the event of multiple +duplicates. For example, \csopt[.copy]{duplicate-label-suffix} will +change the label to \meta{id}\code{.copy1} for the first duplicate +of the entry whose label is \meta{id}, \meta{id}\code{.copy2} for +the second duplicate, etc. + +\optsection[\subsubsection]{record-label-prefix} + +If set, this option will cause \bibgls\ to pretend that each record +label starts with \meta{tag}, if it doesn't already. For example, suppose +the records in the \ext{aux} file are: +\begin{verbatim} +\glsxtr@record{bird}{}{page}{glsnumberformat}{1} +\glsxtr@record{waterfowl}{}{page}{glsnumberformat}{1} +\glsxtr@record{idx.duck}{}{page}{glsnumberformat}{1} +\glsxtr@record{idx.goose}{}{page}{glsnumberformat}{1} +\end{verbatim} +The use of \csopt[idx.]{record-label-prefix} makes \bibgls\ act as +though the records were given as: +\begin{verbatim} +\glsxtr@record{idx.bird}{}{page}{glsnumberformat}{1} +\glsxtr@record{idx.waterfowl}{}{page}{glsnumberformat}{1} +\glsxtr@record{idx.duck}{}{page}{glsnumberformat}{1} +\glsxtr@record{idx.goose}{}{page}{glsnumberformat}{1} +\end{verbatim} + + +\optsection[\subsubsection]{cs-label-prefix} + +If you have commands such as \ics{gls}\margm{label} or +\ics{glstext}\marg{label} in field +values (in situations where nested link text won't cause a problem) +the \meta{label} will be converted as follows: +\begin{itemize} +\item if \meta{label} starts with \idprefix{dual} then +\idprefix{dual} will be replaced by the \csopt{dual-prefix} value; +\item if \meta{label} starts with \idprefix{tertiary} then +\idprefix{tertiary} will be replaced by the \csopt{tertiary-prefix} value; +\item if \meta{label} starts with \idprefix{extn} then +\idprefix{extn} will be replaced by the corresponding +\csopt{ext-prefixes} setting (if \idx{crossresourceref} mode is +enabled, see \sectionref{sec:resourcesets}); +\item if \meta{label} doesn't start with one of the above recognised +prefixes then, if \csopt{cs-label-prefix} has been used the supplied +value will be inserted otherwise the \csopt{label-prefix} setting +will be inserted. \end{itemize} +For example, given +\begin{verbatim} +@entry{bird, + name={bird}, + description = {feathered animal, such as a \gls{duck} or \gls{goose}} +} +\end{verbatim} +then if \csopt[idx.]{label-prefix} is set but \csopt{cs-label-prefix} +isn't included in the resource option list this will convert the +\field{description} field to: +\begin{verbatim} +description = {feathered animal, such as a \gls{idx.duck} or +\gls{idx.goose}} +\end{verbatim} +However with \csopt[gls.]{cs-label-prefix} the \field{description} +field will be converted to +\begin{verbatim} +description = {feathered animal, such as a \gls{gls.duck} or +\gls{gls.goose}} +\end{verbatim} +regardless of the \csopt{label-prefix} setting. Whereas if the +original entry definition is +\begin{verbatim} +@entry{bird, + name={bird}, + description = {feathered animal, such as a \gls{dual.duck} or +\gls{dual.goose}} +} +\end{verbatim} +then \idprefix{dual} will be replaced by the value of the +\csopt{dual-prefix} option regardless of the \csopt{cs-label-prefix} +setting. -For example, consider the \exfile{books.bib} file which contains -entries like +The \csopt{cs-label-prefix} setting doesn't affect labels in the +fields that have an entry label or label list as the value +(\field{parent}, \field{alias}, \field{see} and \field{seealso}). + +\optsection[\subsubsection]{ext-prefixes} + +Any cross-references in the \iext{bib} file that start with +\idprefix{extn} (where \meta{n} is a positive integer) will be +substituted with the \meta{n}th tag listed in the comma-separated +\meta{list}. If there aren't that many items in the list, the +\idprefix{extn} will simply be removed. The default setting is +an empty list, which will strip all \idprefix{extn} prefixes. +Remember that \idx{crossresourceref} mode needs to be enabled for +this option to work (see \sectionref{sec:resourcesets}). + +For example, suppose the file \filefmt{entries-terms.bib} contains: \begin{verbatim} -@entry{ubik, - name={Ubik}, - description={novel by Philip K. Dick}, - identifier={book}, - author={\sortmediacreator{Philip K.}{Dick}}, - year={1969} +@entry{set, + name={set}, + description={collection of values, denoted \gls{ext1.set}} } \end{verbatim} -then the field alias -\begin{codeenv} -\csopt[author=parent]{field-aliases} -\end{codeenv} -will treat +and the file \filefmt{entries-symbols.bib} contains: \begin{verbatim} - author={\sortmediacreator{Philip K.}{Dick}}, +@symbol{set, + name={\ensuremath{\mathcal{S}}}, + description={a \gls{ext1.set}} +} \end{verbatim} -as though it had been defined as + +These files both contain an entry with the label \code{set} +but the \field{description} field includes \verb|\gls{ext1.set}| which is +referencing the entry from the other file. These +two files can be loaded without conflict using: \begin{verbatim} - parent={\sortmediacreator{Philip K.}{Dick}}, +\usepackage[record,symbols]{glossaries-extra} + +\GlsXtrLoadResources[src={entries-terms}, + label-prefix={gls.}, + ext-prefixes={sym.} +] + +\GlsXtrLoadResources[src={entries-symbols}, + type=symbols, + label-prefix={sym.}, + ext-prefixes={gls.} +] \end{verbatim} -This can be converted into a label with the options: -\begin{codeenv} - \csopt[parent]{labelify}, - \csopt[ - \marg{[ \cs{cs.string}\csfmt{.}]}\marg{} - ]{labelify-replace} -\end{codeenv} -If the interpreter has been provided with the definition: + +Now the \code{set} entry from \filefmt{entries-terms.bib} +will be defined with the label \code{gls.set} and the +description will be \begin{verbatim} -\providecommand*{\sortmediacreator}[2]{#2 #1} +collection of values, denoted \gls{sym.set} \end{verbatim} -then the \field{parent} field for the \code{ubik} entry -will become \code{DickPhilipK} but the original value is stored -internally when \csopt[create]{missing-parents} is set so that it -can be used as the \field{name} if the parent needs to be created. -Once all the entries have been processed, if \code{ubik} has been -selected but no entry can be found with the label \code{DickPhilipK} -then a new entry will be added as though it had been defined with: +The \code{set} entry +from \filefmt{entries-symbols.bib} will be defined with the label +\code{sym.set} and the description will be \begin{verbatim} -@index{DickPhilipK, - name={\sortmediacreator{Philip K.}{Dick}} +a \gls{gls.set} +\end{verbatim} + +Note that in this case the \ext{bib} files have to be loaded +as two separate resources. They can't be combined into a +single \csopt{src} list as the labels aren't unique. + +If you want to allow the flexibility to choose between +loading them together or separately, you'll have to give them +unique labels. For example, \filefmt{entries-terms.bib} could +contain: +\begin{verbatim} +@entry{set, + name={set}, + description={collection of values, denoted \gls{ext1.S}} } \end{verbatim} -This is an alternative approach to the \exfile{sample-authors.tex} -document from the \hyperref[sec:examples]{examples chapter}. +and \filefmt{entries-symbols.bib} could contain: +\begin{verbatim} +@symbol{S, + name={\ensuremath{\mathcal{S}}}, + description={a \gls{ext1.set}} +} +\end{verbatim} +Now they can be combined with: +\begin{verbatim} +\GlsXtrLoadResources[src={entries-terms,entries-symbols}] +\end{verbatim} +which will simply strip the \glsdisp{idx.idprefix.extn}{\idprefixfmt{ext1}} +prefix from the cross-references. Alternatively: +\begin{verbatim} +\GlsXtrLoadResources[src={entries-terms,entries-symbols}, + label-prefix={gls.}, + ext-prefixes={gls.} +] +\end{verbatim} +which will insert the supplied \csopt{label-prefix} at the +start of the labels in the entry definitions and will replace +the \idprefixfmt{ext1} prefix with \idprefixfmt{gls} in the +cross-references. -\optsection{missing-parent-category} +\optsection[\subsubsection]{save-original-id} -If a missing parent entry is created through the use of -\csopt[create]{missing-parents} then the \field{category} field can -be assigned to the new parent entry with this option. The -\meta{value} may be one of: +The \meta{value} may be either the keyword \code{false} or +the name of an internal field in which to store the entry's original +label (as given in the \ext{bib} file). The default setting is +\csopt[false]{save-original-id}. If \meta{value} is omitted, +\csopt[originalid]{save-original-id} is assumed. + +If \meta{value} is a known field, it will be set after the field +aliases, otherwise it will simply be added to the \ext{glstex} file +using \ics{GlsXtrSetField} after the entry definition. + +\subsection{Assignments} +\label{sec:fieldassignments} + +\optsection[\subsubsection]{group} + +The \csopt{group} option may only be used with the \longarg{group} switch. +This will set the \field{group} field to \meta{label} unless +\meta{label} is \optfmt{auto}, in which case the value is +set automatically during the sorting (see also +\csopt{group-formation}). +The corresponding title can be set +with \gls{glsxtrsetgrouptitle} if the title is different from the +label. The default behaviour is \csopt[auto]{group}. + +For example: +\begin{verbatim} +\GlsXtrLoadResources[sort=integer,group={Constants}, + src={entries-constants}% data in entries-constants.bib +] +\GlsXtrLoadResources[sort=letter-case,group={Variables}, + src={entries-variables}% data in entries-variables.bib +] +\end{verbatim} +In this case, if the \field{type} field hasn't been set in the \ext{bib} files, +these entries will be added to the same glossary, but will +be grouped according to each instance of \gls{GlsXtrLoadResources}, +with the provided group label. + + +\optsection[\subsubsection]{category} + +The selected entries may all have their \field{category} field +changed before writing their definitions to the \ext{glstex} file. +The \meta{value} may be: \begin{itemize} - \item \code{same as child}: the parent entry's \field{category} - field is set to the same value as the child's (if set); - \item \code{same as base}: the parent entry's \field{category} is - set to the base name of the \ext{bib} file that provided the - child entry's definition; - \item \code{no value}: don't set the \field{category} field; - \item \meta{label}: the parent entry's \field{category} field is set to - \meta{label} (which shouldn't contain any special characters). +\item \optfmt{same as entry}: set the +\field{category} to the \ext{bib} entry type used to define it +(\idx!{lowercase} and without the initial \code{@}) after any aliasing, +if applicable; + +\item \optfmt{same as original entry}: (new to v1.4) set the \field{category} +to the original entry type (\idx!{lowercase} and without +the initial \code{@}) before it was aliased (behaves like +\optfmt{same as entry} if the entry type wasn't aliased); + +\item \optfmt{same as base}: (new to v1.1) set the \field{category} +to the base name of the \ext{bib} file (without the extension) +that provided the entry definition; + +\item \optfmt{same as type}: set the \field{category} to the same +value as the \field{type} field (if that field has been provided +either in the \ext{bib} file or through the \csopt{type} option); + +\item \meta{label}: the \field{category} is set to +\meta{label} (which mustn't contain any special characters). \end{itemize} -The default setting is \csopt[no value]{missing-parent-category}. +This will override any +\field{category} fields supplied in the \ext{bib} file. -\optsection{abbreviation-name-fallback} +When used with \csopt{entry-type-aliases}, the option \csopt[same as +entry]{category} refers to the \emph{target} entry type whereas +\csopt[same as original entry]{category} refers to the +\emph{original} entry type given in the \ext{bib} file. In both +cases, the value is converted to \idx!{lowercase} to ensure consistency. + +For example, if the \ext{bib} file contains: +\begin{verbatim} +@entry{bird, + name={bird}, + description = {feathered animal} +} + +@index{duck} + +@index{goose,plural="geese"} + +@dualentry{dog, + name={dog}, + description={chien} +} +\end{verbatim} +then if the document contains +\begin{verbatim} +\GlsXtrLoadResources[category={same as entry},src={entries}] +\end{verbatim} +this will set the \field{category} of the \code{bird} term to +\optfmt{entry} (since it was defined with \atentry{entry}), the \field{category} of the \code{duck} and +\code{goose} terms to \optfmt{index} (since they were defined +with \atentry{index}), and the \field{category} of the \code{dog} +term to \optfmt{dualentry} (since it was +defined with \atentry{dualentry}). Note that the dual entry +\code{dual.dog} doesn't have the category set, since that's +governed by \csopt{dual-category} instead. + +If, instead, the document contains +\begin{verbatim} +\GlsXtrLoadResources[category={animals},src={entries}] +\end{verbatim} +then the \field{category} of all the primary selected entries will +be set to \optfmt{animals}. Again the dual entry \code{dual.dog} +doesn't have the \field{category} set. + +Note that the categories may be overridden by the commands, +such as \csref{bibglsnewindex}, that are used to actually define the +entries. + +For example, if the document contains +\begin{verbatim} +\newcommand{\bibglsnewdualentry}[4]{% + \longnewglossaryentry*{#1}{name={#3},#2,category={dual}}{#4}% +} + +\GlsXtrLoadResources[category={animals},src={entries}] +\end{verbatim} +then both the \code{dog} and \code{dual.dog} entries will +have their \field{category} field set to \optfmt{dual} since the +new definition of \gls{bibglsnewdualentry} has overridden +the \csopt[animals]{category} option. + +\optsection[\subsubsection]{type} + +The \meta{value} may be one of: +\begin{itemize} + \item \optfmt{same as entry} set the \field{type} field + to the entry type (\idx!{lowercase} and without the initial \code{@}); + + \item \optfmt{same as original entry} set the \field{type} + to the original entry type (\idx!{lowercase} and without + the initial \code{@}) before it was aliased (behaves like + \optfmt{same as entry} if the entry type wasn't aliased); + + \optfmt{same as base} set the \field{type} field + to the base name of the corresponding \ext{bib} file + (without the extension); + + \item \optfmt{same as category} set the \field{type} field + to the same value as the \field{category} field + (\field{type} unchanged if \field{category} not set); + + \item\meta{label} sets the \field{type} field to the glossary + identified by \meta{label}. +\end{itemize} +When used with \csopt{entry-type-aliases}, the option \csopt[same as +entry]{type} refers to the \emph{target} entry type and \csopt[same +as original entry]{type} refers to the \emph{original} entry type +given in the \ext{bib} file. It's not possible to have both +\csopt[same as type]{category} and \csopt[same as category]{type}. + +Note that this setting only changes the \field{type} field for +primary entries. Use \csopt{dual-type} for dual entries. + +For example: +\begin{verbatim} +\usepackage[record,symbols]{glossaries-extra} + +\GlsXtrLoadResources[src={entries-symbols},type=symbols] +\end{verbatim} + +Make sure that the glossary type has already been defined +(see \sectionref{sec:newglossary}). In the above, the +\styopt{symbols} option defines the \code{symbols} glossary. +If you want to use a custom glossary, you need to provide it. For +example: +\begin{verbatim} +\usepackage[record,nomain]{glossaries-extra} + +\newglossary*{dictionary}{Dictionary} + +\GlsXtrLoadResources[src={entries-symbols},type=dictionary] +\end{verbatim} +(The \styopt{nomain} option was added to suppress the +creation of the default \code{main} glossary.) + +\optsection[\subsubsection]{trigger-type} + +The record counting commands, such as \ics{rgls}, use the special +format \ics{glstriggerrecordformat}, which \bibgls\ also treats +as an \idx{ignoredrecord}. This means the entry will still be +identified as having a record for selection purposes, which is +necessary for the entry to be defined for use in the document, but +in order to prevent it from appearing in the glossary you need to +transfer the entry with \csopt[\meta{type}]{trigger-type}. +This will override the \csopt{type}, \csopt{dual-type}, +\csopt{tertiary-type} and the type specification in +\csopt{secondary}. + +The provided value \meta{type} must be a glossary label (not one of +the keywords allowed by \csopt{type}). +You can define the glossary before loading the resource, but +it's not required as \bibgls\ will write +\ics{provideignoredglossary*}\margm{type} to the \ext{glstex} file +(see \sectionref{sec:newglossary}). + +\optsection[\subsubsection]{abbreviation-name-fallback} The entry types that define abbreviations (such as \atentry{abbreviation} and \atentry{acronym}) will, by default, @@ -6681,7 +7208,7 @@ specify the field. For example, \csopt[long]{abbreviation-name-fallback}. The \meta{field} value must be a known field label. -\optsection{ignore-fields} +\optsection[\subsubsection]{ignore-fields} The \csopt{ignore-fields} key indicates that you want \bibgls\ to skip the fields listed in the supplied comma-separated \meta{list} of field @@ -6710,7 +7237,7 @@ If you want to maintain the dependency and ancestor relationship but omit the \field{parent} field when writing the entries to the \ext{glstex} file, you need to use \csopt{flatten} instead. -\optsection{field-aliases} +\optsection[\subsubsection]{field-aliases} You can instruct \bibgls\ to treat one field as though it was another using this option. The value should be a comma-separated @@ -6748,7 +7275,7 @@ keys: ] \end{verbatim} -\optsection{replicate-fields} +\optsection[\subsubsection]{replicate-fields} The value of one field can be copied to other fields using this option where each \meta{key}\dequals\meta{value} pair @@ -6833,14 +7360,236 @@ make a difference. The same result occurs with: ] \end{verbatim} -\optsection{replicate-override} +\optsection[\subsubsection]{replicate-override} This is a boolean option. The default setting is \csopt[false]{replicate-override}. If \optfmt{true}, \csopt{replicate-fields} will override the existing value if the target field is already set. -\optsection{bibtex-contributor-fields} +\optsection[\subsubsection]{counter} + +The \csopt{counter} option assigns the default counter to use +for the selected entries. (This can be overridden with the +\glsopt{counter} key when using commands like \csfmt{gls}.) +The value must be the name of a counter. Since \bibgls\ doesn't know +which counters are defined within the document, there's no check to +determine if the value is valid (except for ensuring that +\meta{value} is non-empty). + +Note that this will require an extra \LaTeX\ and \bibgls\ call since +the counter can't be used for the indexing until the entry has been +defined. + +\optsection[\subsubsection]{copy-action-group-field} + +This option may only be used when invoking \bibgls\ with the +\longarg{group} (or \shortargfmt{g}) switch. If an action +other than the default \csopt[define]{action} is set, +this option can be used to identify a field in which to save +the letter group information +where \meta{value} is the name of the field. This just uses +\cs{GlsXtrSetField}. You will need to redefine +\ics{glsxtrgroupfield} to \meta{value} before displaying the glossary. +For example, if \csopt[dupgroup]{copy-action-group-field}, +\csopt[copy]{action} and \csopt[copies]{type} are set in +the resource options and \code{copies} identifies a custom +glossary: +\begin{alltt} +\ics{printunsrtglossary*}\oarg{type=copies,style=indexgroup} + \marg{\cs{renewcommand}\marg{\cs{glsxtrgroupfield}}\marg{dupgroup}} +\end{alltt} + +This option is ignored when used with \csopt[define]{action}. +This option is not used by \csopt{secondary} which will +always save the group information in the \field{secondarygroup} +field. When used with \csopt[define or copy]{action}, entries +that are defined will have both \field{group} and +the field given by \csopt{copy-action-group-field} set. + +Note that you may do \csopt[group]{copy-action-group-field} which +will override the \field{group} field from the original definition. +This may be useful if you don't use grouping in the primary +glossary. That is, you use \code{nogroupskip} and a non-group +style. For example: +\begin{verbatim} +\printunsrtglossary[nogroupskip,style=index] +\printunsrtglossary[type=copies,style=indexgroup] +\end{verbatim} + +\optsection[\subsubsection]{copy-alias-to-see} + +If set, the value of the \field{alias} field is copied to +the \field{see} field. The default setting is \csopt[false]{copy-alias-to-see}. + +\subsection{Field Adjustments} +\label{sec:fieldmods} + +\optsection[\subsubsection]{post-description-dot} + +The \styopt{postdot} package option (or \styopt[false]{nopostdot}) +can be used to append a \idx{full-stop} (\idx{periodchar})\ to the +end of all the descriptions. This can be awkward if some of the +descriptions end with punctuation characters. This resource option +can be used instead. The \meta{value} may be one of: +\begin{itemize} +\item\optfmt{none}: don't append a \idx{full-stop} (default); +\item\optfmt{all}: append a \idx{full-stop} to all \field{description} + fields in this resource set; +\item\optfmt{check}: selectively append a \idx{full-stop} (see below). +\end{itemize} +Note that if you have dual entries and you use this option to +append a \idx{full-stop}, then it will be copied over to the mapped field. +This is different to the \styopt{postdot} option which doesn't +add the dot to the field but incorporates it in the +\idx{postdescriptionhook}. This means that a dot inserted with +\csopt{post-description-dot} will come before the +\idx{postdescriptionhook} whereas with \styopt{postdot} the +punctuation comes after any category-specific hook. + +The \csopt[check]{post-description-dot} setting determines whether +to append the dot as follows: +\begin{itemize} +\item If the \field{description} field ends with +\ics{nopostdesc} or \ics{glsxtrnopostpunc}, then a dot isn't appended. +\item If the \field{description} field doesn't end with a regular +(ungrouped letter or other) character, then a dot is appended. +(For example, if the description ends with a control sequence +or an end group token.) +\item If the \field{description} field ends with a character +that belongs to the Unicode category \idx{punctuationclose} +or \idx{punctuationfinalquote} then the token preceding +that character is checked. +\item If the \field{description} field doesn't end with +a character that belongs to the Unicode category +\idx{punctuationother} then the dot is added. +\end{itemize} +Note that the interpreter isn't used during the check. +If the \field{description} ends with a command then a dot will be +appended (unless it's \cs{glsxtrnopostpunc} or \cs{nopostdesc}) even if +that command expands in such a way that it ends with a terminating +punctuation character. This option only applies to the +\field{description} field. + +\optsection[\subsubsection]{strip-trailing-nopost} + +This option is always performed before \csopt{post-description-dot} +when adjusting the \field{description} field. The default +setting is \csopt[false]{strip-trailing-nopost}. If +\optfmt{true} any trailing ungrouped \ics{nopostdesc} or \ics{glsxtrnopostpunc} +found in the \field{description} field will be removed. +Note that the command (possibly followed by ignored space) must be +at the very end of the description for it to be removed. A +description should not contain both commands. This option +only applies to the \field{description} field. + +For example, \cs{nopostdesc} will be stripped from: +\begin{verbatim} +description={sample\nopostdesc} +\end{verbatim} +since it's at the end. It will also be stripped from +\begin{verbatim} +description={sample\nopostdesc } +\end{verbatim} +since the trailing space is ignored as it follows a control +word. It won't be stripped from +\begin{verbatim} +description={sample\nopostdesc{} } +\end{verbatim} +because the final space is now significant, but even without the +space it still won't be stripped as the field ends with +an empty group not with \cs{nopostdesc}. Similarly it won't be +stripped from +\begin{verbatim} +description={sample\nopostdesc\relax} +\end{verbatim} +because again it's not at the end. + +\optsection[\subsubsection]{check-end-punctuation} + +This options checks the end of all the fields given in \meta{list} for +end of sentence punctuation. This is determined as follows, for each +\meta{field} in the comma-separated \meta{list}: +\begin{itemize} +\item if the last character is of type \idx{punctuationclose} +or \idx{punctuationfinalquote}, check the character that comes +before it; +\item if the character is of type \idx{punctuationother}, then check +if it's listed in the entry given by \code{sentence.terminators} +in \bibgls's \langxml. +\end{itemize} +If a sentence terminator is found, an internal field is created +called \field{fieldendpunc} that contains the punctuation +character. Fields whose values must be labels (such as +\field{parent}, \field{category} and \field{type}) aren't checked, +even if they're included in \meta{list}. + +The default \code{sentence.terminators} is defined in \file{bib2gls-en.xml} +as: +\begin{verbatim} +<entry key="sentence.terminators">.?!</entry> +\end{verbatim} +Any character that isn't of type \idx{punctuationother} won't +match. + +For example, the sample \exfile{books.bib} file contains: +\begin{verbatim} +@entry{whydidnttheyaskevans, + name={Why Didn't They Ask Evans?}, + description={novel by Agatha Christie}, + identifier={book}, + author={\sortmediacreator{Agatha}{Christie}}, + year={1934} +} +\end{verbatim} +With \csopt[name]{check-end-punctuation}, this entry will be +assigned an internal field called +\fielddisp{fieldendpunc}{namendpunc} set to \code{?}\ +as that's included in \code{sentence.terminators} and is found +at the end of the \field{name} field: +\begin{verbatim} +\GlsXtrSetField{whydidnttheyaskevans}{nameendpunc}{?} +\end{verbatim} +(Note that \csopt[first,text]{check-end-punctuation} won't match +as there's no \field{first} or \field{text} field supplied.) + +If you have a field that ends with an abbreviation followed by a +\idx{full-stop}, this will be considered an end of sentence terminator, but +the main purpose of this option is to provide a way to deal with +cases like +\begin{verbatim} +Agatha Christie wrote \gls{whydidnttheyaskevans}. +\end{verbatim} +where the end of sentence punctuation following \cs{gls} needs to be +discarded. This is needed regardless of whether or not +the link text ends with an abbreviation or is a complete sentence. + +It's then possible to hook into the \idx{postlinkhook} \qt{discard +period} check. By default this just checks the category attributes +that govern whether or not to discard a following period, but +(with \styfmt{glossaries-extra} v1.23+) it's possible to provide +an additional check by redefining +\nosecdef{glsxtrifcustomdiscardperiod} +This should expand to \meta{true} if the check should be performed +otherwise it should expand to \meta{false}. You can reference the +label using \cs{glslabel}. For example: +\begin{verbatim} +\renewcommand*{\glsxtrifcustomdiscardperiod}[2]{% + \GlsXtrIfFieldUndef{nameendpunc}{\glslabel}{#2}{#1}% +} +\end{verbatim} +This uses \ics{GlsXtrIfFieldUndef} rather than +\ics{glsxtrifhasfield*} since there's no need to access the field's +value. (The unstarred form \ics{glsxtrifhasfield} can't be used +as it introduces implicit scoping, which would interfere with the +punctuation lookahead.) The other difference between +\ics{GlsXtrIfFieldUndef} and the other \csfmt{\ldots hasfield} tests +is the case where the field is set to an empty value. In this case +the field is defined (so \ics{GlsXtrIfFieldUndef} does the +\meta{false} argument) but it's considered unset (so commands like +\ics{ifglshasfield} do the \meta{false} argument). + +\optsection[\subsubsection]{bibtex-contributor-fields} This option indicates that the listed fields all use \BibTeX's name syntax (as used in \BibTeX's \code{author} and \code{editor} fields). @@ -6888,7 +7637,7 @@ With one of the locale sort methods and with the default Smith|John|Doe|Jane|von|Duck|Dickie \end{verbatim} -\optsection{contributor-order} +\optsection[\subsubsection]{contributor-order} The \gls{bibglscontributor} command is defined in \bibgls's interpreter and its definition is dependent on this @@ -6948,7 +7697,7 @@ The second resource set will use the default \csopt[von]{bibtex-contributor-fields} setting when obtaining the sort value. -\optsection{date-time-fields} +\optsection[\subsubsection]{date-time-fields} This option indicates that the listed fields all contain date and time information. Primary entries will have these fields @@ -6966,7 +7715,7 @@ being parsed if it contains \idx{escchar}, \idx{mshiftchar}, \idx{nbspchar} is converted to the non-breaking space character \hex{A0} unless \longarg{break-space} is used.) -\optsection{date-fields} +\optsection[\subsubsection]{date-fields} As \csopt{date-time-fields} but for fields that only contain date (not time) information. If parsed correctly, the field is converted @@ -6978,7 +7727,7 @@ The fields are parsed according to \csopt{dual-date-field-format} and \csopt{dual-date-field-locale} for dual entries. -\optsection{time-fields} +\optsection[\subsubsection]{time-fields} As \csopt{date-time-fields} but for fields that only contain time (not date) information. If parsed correctly, the field is converted @@ -6990,7 +7739,7 @@ The fields are parsed according to \csopt{dual-time-field-format} and \csopt{dual-time-field-locale} for dual entries. -\optsection{date-time-field-format} +\optsection[\subsubsection]{date-time-field-format} This option also sets \csopt[\meta{value}]{dual-date-time-field-format}. @@ -6998,7 +7747,7 @@ The value is the format pattern used when parsing fields identified by \csopt{date-time-fields}. The \meta{value} is as for \csopt{date-sort-format}. -\optsection{date-field-format} +\optsection[\subsubsection]{date-field-format} This option also sets \csopt[\meta{value}]{dual-date-field-format}. @@ -7006,7 +7755,7 @@ The value is the format pattern used when parsing fields identified by \csopt{date-fields}. The \meta{value} is as for \csopt{date-sort-format}. -\optsection{time-field-format} +\optsection[\subsubsection]{time-field-format} This option also sets \csopt[\meta{value}]{dual-time-field-format}. @@ -7014,7 +7763,7 @@ The value is the format pattern used when parsing fields identified by \csopt{time-fields}. The \meta{value} is as for \csopt{date-sort-format}. -\optsection{date-time-field-locale} +\optsection[\subsubsection]{date-time-field-locale} This option also sets \csopt[\meta{value}]{dual-date-time-field-locale}. @@ -7022,7 +7771,7 @@ The value is the locale used when parsing fields identified by \csopt{date-time-fields}. The \meta{value} is as for \csopt{date-sort-locale}. -\optsection{date-field-locale} +\optsection[\subsubsection]{date-field-locale} This option also sets \csopt[\meta{value}]{dual-date-field-locale}. @@ -7030,7 +7779,7 @@ The value is the locale used when parsing fields identified by \csopt{date-fields}. The \meta{value} is as for \csopt{date-sort-locale}. -\optsection{time-field-locale} +\optsection[\subsubsection]{time-field-locale} This option also sets \csopt[\meta{value}]{dual-time-field-locale}. @@ -7038,291 +7787,30 @@ The value is the locale used when parsing fields identified by \csopt{time-fields}. The \meta{value} is as for \csopt{date-sort-locale}. -\optsection{counter} - -The \csopt{counter} option assigns the default counter to use -for the selected entries. (This can be overridden with the -\glsopt{counter} key when using commands like \csfmt{gls}.) -The value must be the name of a counter. Since \bibgls\ doesn't know -which counters are defined within the document, there's no check to -determine if the value is valid (except for ensuring that -\meta{value} is non-empty). - -Note that this will require an extra \LaTeX\ and \bibgls\ call since -the counter can't be used for the indexing until the entry has been -defined. - -\optsection{label-prefix} - -The \csopt{label-prefix} option prepends \meta{tag} to each -entry's label. This \meta{tag} will also be inserted in front of any -cross-references, unless they start with \idprefix{dual} or -\idprefix{extn} (where \meta{n} is an integer). Use -\csopt{dual-prefix} to change the dual label prefixes and -\csopt{ext-prefixes} to change the external label prefixes. - -For example, if the \ext{bib} file contains -\begin{verbatim} -@entry{bird, - name={bird}, - description = {feathered animal, such as a \gls{duck} or \gls {goose}} -} - -@entry{waterfowl, - name={waterfowl}, - description={Any \gls{bird} that lives in or about water}, - see={[see also]{duck,goose}} -} - -@index{duck} - -@index{goose,plural="geese"} -\end{verbatim} -Then if this \ext{bib} file is loaded with \csopt[gls.]{label-prefix} -it's as though the entries had been defined as: -\begin{verbatim} -@entry{gls.bird, - name={bird}, - description = {feathered animal, such as a \gls{gls.duck} or -\gls{gls.goose}} -} - -@entry{gls.waterfowl, - name={waterfowl}, - description={Any \gls{gls.bird} that lives in or about water}, - see={[see also]{gls.duck,gls.goose}} -} - -@index{gls.duck,name={duck}} - -@index{gls.goose,name={goose},plural="geese"} -\end{verbatim} - -Remember to use this prefix when you reference the terms in the -document with commands like \ics{gls}. - -\optsection{duplicate-label-suffix} - -The \sty{glossaries} package doesn't permit entries with duplicate -labels (even if they're in different glossaries). If you -have multiple \idxpl{resourceset} and an entry that's selected -in one \idx{resourceset} is also selected in another, by -default, \bibgls\ will issue a warning, but it will still write the -entry definition to the \ext{glstex} file, which means you'll also -get a warning from \sty{glossaries-extra} and the duplicate -definition will be ignored, but associated internal fields -set with commands like \cs{GlsXtrSetField} may still be set. - -If you actually want the duplicate, you need to specify a -suffix with \csopt{duplicate-label-suffix}. This suffix is only -set just before writing the entry definition to the \ext{glstex} -file, so it doesn't affect selection criteria nor can label -substitutions be performed in any cross-references. Options such as -\csopt{set-widest} that reference entry labels are incompatible -as they will use the unsuffixed label. - -The actual suffix is formed from \meta{value}\meta{n} where \meta{n} -is an integer that's incremented in the event of multiple -duplicates. For example, \csopt[.copy]{duplicate-label-suffix} will -change the label to \meta{id}\code{.copy1} for the first duplicate -of the entry whose label is \meta{id}, \meta{id}\code{.copy2} for -the second duplicate, etc. +\subsection{Case-Changing} +\label{sec:fieldcase} -\optsection{record-label-prefix} - -If set, this option will cause \bibgls\ to pretend that each record -label starts with \meta{tag}, if it doesn't already. For example, suppose -the records in the \ext{aux} file are: -\begin{verbatim} -\glsxtr@record{bird}{}{page}{glsnumberformat}{1} -\glsxtr@record{waterfowl}{}{page}{glsnumberformat}{1} -\glsxtr@record{idx.duck}{}{page}{glsnumberformat}{1} -\glsxtr@record{idx.goose}{}{page}{glsnumberformat}{1} -\end{verbatim} -The use of \csopt[idx.]{record-label-prefix} makes \bibgls\ act as -though the records were given as: -\begin{verbatim} -\glsxtr@record{idx.bird}{}{page}{glsnumberformat}{1} -\glsxtr@record{idx.waterfowl}{}{page}{glsnumberformat}{1} -\glsxtr@record{idx.duck}{}{page}{glsnumberformat}{1} -\glsxtr@record{idx.goose}{}{page}{glsnumberformat}{1} -\end{verbatim} - - -\optsection{cs-label-prefix} - -If you have commands such as \ics{gls}\margm{label} or -\ics{glstext}\marg{label} in field -values (in situations where nested link text won't cause a problem) -the \meta{label} will be converted as follows: -\begin{itemize} -\item if \meta{label} starts with \idprefix{dual} then -\idprefix{dual} will be replaced by the \csopt{dual-prefix} value; -\item if \meta{label} starts with \idprefix{tertiary} then -\idprefix{tertiary} will be replaced by the \csopt{tertiary-prefix} value; -\item if \meta{label} starts with \idprefix{extn} then -\idprefix{extn} will be replaced by the corresponding -\csopt{ext-prefixes} setting (if \idx{crossresourceref} mode is -enabled, see \sectionref{sec:resourcesets}); -\item if \meta{label} doesn't start with one of the above recognised -prefixes then, if \csopt{cs-label-prefix} has been used the supplied -value will be inserted otherwise the \csopt{label-prefix} setting -will be inserted. -\end{itemize} -For example, given -\begin{verbatim} -@entry{bird, - name={bird}, - description = {feathered animal, such as a \gls{duck} or \gls{goose}} -} -\end{verbatim} -then if \csopt[idx.]{label-prefix} is set but \csopt{cs-label-prefix} -isn't included in the resource option list this will convert the -\field{description} field to: -\begin{verbatim} -description = {feathered animal, such as a \gls{idx.duck} or -\gls{idx.goose}} -\end{verbatim} -However with \csopt[gls.]{cs-label-prefix} the \field{description} -field will be converted to -\begin{verbatim} -description = {feathered animal, such as a \gls{gls.duck} or -\gls{gls.goose}} -\end{verbatim} -regardless of the \csopt{label-prefix} setting. Whereas if the -original entry definition is -\begin{verbatim} -@entry{bird, - name={bird}, - description = {feathered animal, such as a \gls{dual.duck} or -\gls{dual.goose}} -} -\end{verbatim} -then \idprefix{dual} will be replaced by the value of the -\csopt{dual-prefix} option regardless of the \csopt{cs-label-prefix} -setting. - -The \csopt{cs-label-prefix} setting doesn't affect labels in the -fields that have an entry label or label list as the value -(\field{parent}, \field{alias}, \field{see} and \field{seealso}). - -\optsection{ext-prefixes} - -Any cross-references in the \iext{bib} file that start with -\idprefix{extn} (where \meta{n} is a positive integer) will be -substituted with the \meta{n}th tag listed in the comma-separated -\meta{list}. If there aren't that many items in the list, the -\idprefix{extn} will simply be removed. The default setting is -an empty list, which will strip all \idprefix{extn} prefixes. -Remember that \idx{crossresourceref} mode needs to be enabled for -this option to work (see \sectionref{sec:resourcesets}). - -For example, suppose the file \filefmt{entries-terms.bib} contains: -\begin{verbatim} -@entry{set, - name={set}, - description={collection of values, denoted \gls{ext1.set}} -} -\end{verbatim} -and the file \filefmt{entries-symbols.bib} contains: -\begin{verbatim} -@symbol{set, - name={\ensuremath{\mathcal{S}}}, - description={a \gls{ext1.set}} -} -\end{verbatim} - -These files both contain an entry with the label \code{set} -but the \field{description} field includes \verb|\gls{ext1.set}| which is -referencing the entry from the other file. These -two files can be loaded without conflict using: -\begin{verbatim} -\usepackage[record,symbols]{glossaries-extra} - -\GlsXtrLoadResources[src={entries-terms}, - label-prefix={gls.}, - ext-prefixes={sym.} -] - -\GlsXtrLoadResources[src={entries-symbols}, - type=symbols, - label-prefix={sym.}, - ext-prefixes={gls.} -] -\end{verbatim} - -Now the \code{set} entry from \filefmt{entries-terms.bib} -will be defined with the label \code{gls.set} and the -description will be -\begin{verbatim} -collection of values, denoted \gls{sym.set} -\end{verbatim} -The \code{set} entry -from \filefmt{entries-symbols.bib} will be defined with the label -\code{sym.set} and the description will be -\begin{verbatim} -a \gls{gls.set} -\end{verbatim} - -Note that in this case the \ext{bib} files have to be loaded -as two separate resources. They can't be combined into a -single \csopt{src} list as the labels aren't unique. - -If you want to allow the flexibility to choose between -loading them together or separately, you'll have to give them -unique labels. For example, \filefmt{entries-terms.bib} could -contain: -\begin{verbatim} -@entry{set, - name={set}, - description={collection of values, denoted \gls{ext1.S}} -} -\end{verbatim} -and \filefmt{entries-symbols.bib} could contain: -\begin{verbatim} -@symbol{S, - name={\ensuremath{\mathcal{S}}}, - description={a \gls{ext1.set}} -} -\end{verbatim} -Now they can be combined with: -\begin{verbatim} -\GlsXtrLoadResources[src={entries-terms,entries-symbols}] -\end{verbatim} -which will simply strip the \glsdisp{idx.idprefix.extn}{\idprefixfmt{ext1}} -prefix from the cross-references. Alternatively: -\begin{verbatim} -\GlsXtrLoadResources[src={entries-terms,entries-symbols}, - label-prefix={gls.}, - ext-prefixes={gls.} -] -\end{verbatim} -which will insert the supplied \csopt{label-prefix} at the -start of the labels in the entry definitions and will replace -the \idprefixfmt{ext1} prefix with \idprefixfmt{gls} in the -cross-references. - -\optsection{short-case-change} +\optsection[\subsubsection]{short-case-change} The value of the \field{short} field may be automatically converted -to upper or lower case. This option may take one of the following +to \idxlink{uppercase}{upper} or \idx{lowercase}. This option may take one of the following values: \begin{itemize} \item \optfmt{none}: don't apply any case-changing (default); -\item \optfmt{lc}: convert to lower case (ignoring +\item \optfmt{lc}: convert to \idx{lowercase} (ignoring \idx{mshiftchar}\meta{maths}\idx{mshiftchar}, \ics{ensuremath}\margm{maths} and \ics{si}\margm{text}); -\item \optfmt{uc}: convert to upper case (ignoring +\item \optfmt{uc}: convert to \idx{uppercase} (ignoring \idx{mshiftchar}\meta{maths}\idx{mshiftchar}, \ics{ensuremath}\margm{maths} and \ics{si}\margm{text}); -\item \optfmt{lc-cs}: convert to lower case using +\item \optfmt{lc-cs}: convert to \idx{lowercase} using \ics{MakeTextLowercase}; -\item \optfmt{uc-cs}: convert to upper case using +\item \optfmt{uc-cs}: convert to \idx{uppercase} using \ics{MakeTextUppercase}; -\item \optfmt{firstuc-cs}: convert to first letter upper case using +\item \optfmt{firstuc-cs}: convert to first letter \idx{uppercase} using \ics{makefirstuc}; \item \optfmt{firstuc}: convert the first alphabetical letter (or -group) to upper case. This uses the following rules: +group) to \idx{uppercase}. This uses the following rules: \begin{enumerate} \item if \idx{mshiftchar}\meta{maths}\idx{mshiftchar} then stop (no case change); \item if \ics{NoCaseChange}\margm{text} or @@ -7332,7 +7820,7 @@ group) to upper case. This uses the following rules: \item if \csfmt{}\meta{csname} isn't followed by a group (and it's not \ics{protect}), then stop (no case change applied); \item if \margm{text} (a group) then convert the entire contents of -\meta{text} to upper case and stop; +\meta{text} to \idx{uppercase} and stop; \item if \meta{character} is an alphabetic character then change it to its title case and stop; \item otherwise skip and move on to the next token. @@ -7481,308 +7969,22 @@ the result is See \csopt{dual-short-case-change} to adjust the \field{dualshort} field. -\optsection{name-case-change} +\optsection[\subsubsection]{name-case-change} As \csopt{short-case-change} but is applied to the \field{name} field. If the \field{text} field hasn't been set, the \field{name} -value is first copied to the \field{text} field. +value is first copied to the \field{text} field. If the \field{name} +field hasn't been set (for example, with the \atentry{index} entry +type), it's copied from the fallback value (which +depends on the entry type) unless the entry type is +\atentry{abbreviation} or \atentry{acronym}, in which case if +the \field{name} field is missing no action is performed. -\optsection{description-case-change} +\optsection[\subsubsection]{description-case-change} As \csopt{short-case-change} but is applied to the \field{description} field. -\optsection{post-description-dot} - -The \styopt{postdot} package option (or \styopt[false]{nopostdot}) -can be used to append a \idx{full-stop} (\idx{periodchar})\ to the -end of all the descriptions. This can be awkward if some of the -descriptions end with punctuation characters. This resource option -can be used instead. The \meta{value} may be one of: -\begin{itemize} -\item\optfmt{none}: don't append a \idx{full-stop} (default); -\item\optfmt{all}: append a \idx{full-stop} to all \field{description} - fields in this resource set; -\item\optfmt{check}: selectively append a \idx{full-stop} (see below). -\end{itemize} -Note that if you have dual entries and you use this option to -append a \idx{full-stop}, then it will be copied over to the mapped field. -This is different to the \styopt{postdot} option which doesn't -add the dot to the field but incorporates it in the -\idx{postdescriptionhook}. This means that a dot inserted with -\csopt{post-description-dot} will come before the -\idx{postdescriptionhook} whereas with \styopt{postdot} the -punctuation comes after any category-specific hook. - -The \csopt[check]{post-description-dot} setting determines whether -to append the dot as follows: -\begin{itemize} -\item If the \field{description} field ends with -\ics{nopostdesc} or \ics{glsxtrnopostpunc}, then a dot isn't appended. -\item If the \field{description} field doesn't end with a regular -(ungrouped letter or other) character, then a dot is appended. -(For example, if the description ends with a control sequence -or an end group token.) -\item If the \field{description} field ends with a character -that belongs to the Unicode category \idx{punctuationclose} -or \idx{punctuationfinalquote} then the token preceding -that character is checked. -\item If the \field{description} field doesn't end with -a character that belongs to the Unicode category -\idx{punctuationother} then the dot is added. -\end{itemize} -Note that the interpreter isn't used during the check. -If the \field{description} ends with a command then a dot will be -appended (unless it's \cs{glsxtrnopostpunc} or \cs{nopostdesc}) even if -that command expands in such a way that it ends with a terminating -punctuation character. This option only applies to the -\field{description} field. - -\optsection{strip-trailing-nopost} - -This option is always performed before \csopt{post-description-dot} -when adjusting the \field{description} field. The default -setting is \csopt[false]{strip-trailing-nopost}. If -\optfmt{true} any trailing ungrouped \ics{nopostdesc} or \ics{glsxtrnopostpunc} -found in the \field{description} field will be removed. -Note that the command (possibly followed by ignored space) must be -at the very end of the description for it to be removed. A -description should not contain both commands. This option -only applies to the \field{description} field. - -For example, \cs{nopostdesc} will be stripped from: -\begin{verbatim} -description={sample\nopostdesc} -\end{verbatim} -since it's at the end. It will also be stripped from -\begin{verbatim} -description={sample\nopostdesc } -\end{verbatim} -since the trailing space is ignored as it follows a control -word. It won't be stripped from -\begin{verbatim} -description={sample\nopostdesc{} } -\end{verbatim} -because the final space is now significant, but even without the -space it still won't be stripped as the field ends with -an empty group not with \cs{nopostdesc}. Similarly it won't be -stripped from -\begin{verbatim} -description={sample\nopostdesc\relax} -\end{verbatim} -because again it's not at the end. - -\optsection{check-end-punctuation} - -This options checks the end of all the fields given in \meta{list} for -end of sentence punctuation. This is determined as follows, for each -\meta{field} in the comma-separated \meta{list}: -\begin{itemize} -\item if the last character is of type \idx{punctuationclose} -or \idx{punctuationfinalquote}, check the character that comes -before it; -\item if the character is of type \idx{punctuationother}, then check -if it's listed in the entry given by \code{sentence.terminators} -in \bibgls's \langxml. -\end{itemize} -If a sentence terminator is found, an internal field is created -called \field{fieldendpunc} that contains the punctuation -character. Fields whose values must be labels (such as -\field{parent}, \field{category} and \field{type}) aren't checked, -even if they're included in \meta{list}. - -The default \code{sentence.terminators} is defined in \file{bib2gls-en.xml} -as: -\begin{verbatim} -<entry key="sentence.terminators">.?!</entry> -\end{verbatim} -Any character that isn't of type \idx{punctuationother} won't -match. - -For example, the sample \exfile{books.bib} file contains: -\begin{verbatim} -@entry{whydidnttheyaskevans, - name={Why Didn't They Ask Evans?}, - description={novel by Agatha Christie}, - identifier={book}, - author={\sortmediacreator{Agatha}{Christie}}, - year={1934} -} -\end{verbatim} -With \csopt[name]{check-end-punctuation}, this entry will be -assigned an internal field called -\fielddisp{fieldendpunc}{namendpunc} set to \code{?}\ -as that's included in \code{sentence.terminators} and is found -at the end of the \field{name} field: -\begin{verbatim} -\GlsXtrSetField{whydidnttheyaskevans}{nameendpunc}{?} -\end{verbatim} -(Note that \csopt[first,text]{check-end-punctuation} won't match -as there's no \field{first} or \field{text} field supplied.) - -If you have a field that ends with an abbreviation followed by a -\idx{full-stop}, this will be considered an end of sentence terminator, but -the main purpose of this option is to provide a way to deal with -cases like -\begin{verbatim} -Agatha Christie wrote \gls{whydidnttheyaskevans}. -\end{verbatim} -where the end of sentence punctuation following \cs{gls} needs to be -discarded. This is needed regardless of whether or not -the link text ends with an abbreviation or is a complete sentence. - -It's then possible to hook into the \idx{postlinkhook} \qt{discard -period} check. By default this just checks the category attributes -that govern whether or not to discard a following period, but -(with \styfmt{glossaries-extra} v1.23+) it's possible to provide -an additional check by redefining -\nosecdef{glsxtrifcustomdiscardperiod} -This should expand to \meta{true} if the check should be performed -otherwise it should expand to \meta{false}. You can reference the -label using \cs{glslabel}. For example: -\begin{verbatim} -\renewcommand*{\glsxtrifcustomdiscardperiod}[2]{% - \GlsXtrIfFieldUndef{nameendpunc}{\glslabel}{#2}{#1}% -} -\end{verbatim} -This uses \ics{GlsXtrIfFieldUndef} rather than -\ics{glsxtrifhasfield*} since there's no need to access the field's -value. (The unstarred form \ics{glsxtrifhasfield} can't be used -as it introduces implicit scoping, which would interfere with the -punctuation lookahead.) The other difference between -\ics{GlsXtrIfFieldUndef} and the other \csfmt{\ldots hasfield} tests -is the case where the field is set to an empty value. In this case -the field is defined (so \ics{GlsXtrIfFieldUndef} does the -\meta{false} argument) but it's considered unset (so commands like -\ics{ifglshasfield} do the \meta{false} argument). - -\optsection{copy-action-group-field} - -This option may only be used when invoking \bibgls\ with the -\longarg{group} (or \shortargfmt{g}) switch. If an action -other than the default \csopt[define]{action} is set, -this option can be used to identify a field in which to save -the letter group information -where \meta{value} is the name of the field. This just uses -\cs{GlsXtrSetField}. You will need to redefine -\ics{glsxtrgroupfield} to \meta{value} before displaying the glossary. -For example, if \csopt[dupgroup]{copy-action-group-field}, -\csopt[copy]{action} and \csopt[copies]{type} are set in -the resource options and \code{copies} identifies a custom -glossary: -\begin{alltt} -\ics{printunsrtglossary*}\oarg{type=copies,style=indexgroup} - \marg{\cs{renewcommand}\marg{\cs{glsxtrgroupfield}}\marg{dupgroup}} -\end{alltt} - -This option is ignored when used with \csopt[define]{action}. -This option is not used by \csopt{secondary} which will -always save the group information in the \field{secondarygroup} -field. When used with \csopt[define or copy]{action}, entries -that are defined will have both \field{group} and -the field given by \csopt{copy-action-group-field} set. - -Note that you may do \csopt[group]{copy-action-group-field} which -will override the \field{group} field from the original definition. -This may be useful if you don't use grouping in the primary -glossary. That is, you use \code{nogroupskip} and a non-group -style. For example: -\begin{verbatim} -\printunsrtglossary[nogroupskip,style=index] -\printunsrtglossary[type=copies,style=indexgroup] -\end{verbatim} - -\optsection{save-child-count} - -This is a boolean option. The default setting is -\csopt[false]{save-child-count}. -If \csopt[true]{save-child-count}, -each entry will be assigned a field called \field{childcount} with -the value equal to the number of child entries that have been -selected. - -The assignment is done using \ics{GlsXtrSetField} so there's -no associated key. -For example, suppose \filefmt{entries.bib} contains: -\begin{verbatim} -@index{birds} -@index{duck,parent={birds}} -@index{goose,plural={geese},parent={birds}} -@index{swan,parent={birds}} - -@index{minerals} -@index{quartz,parent={minerals}} -@index{corundum,parent={minerals}} -@index{amethyst,parent={minerals}} -@index{gypsum,parent={minerals}} -@index{gold,parent={minerals}} -\end{verbatim} -and the document contains: -\begin{verbatim} -\documentclass{article} - -\usepackage[record,style=indexgroup]{glossaries-extra} - -\GlsXtrLoadResources[src={entries},save-child-count] - -\begin{document} -\gls{duck} and \gls{goose}. -\gls{quartz}, \gls{corundum}, \gls{amethyst}. - -\printunsrtglossaries -\end{document} -\end{verbatim} -Then the \ext{glstex} file will contain: -\begin{verbatim} -\GlsXtrSetField{birds}{childcount}{2} -\GlsXtrSetField{duck}{childcount}{0} -\GlsXtrSetField{goose}{childcount}{0} -\GlsXtrSetField{minerals}{childcount}{3} -\GlsXtrSetField{amethyst}{childcount}{0} -\GlsXtrSetField{corundum}{childcount}{0} -\GlsXtrSetField{quartz}{childcount}{0} -\end{verbatim} -Note that although \code{birds} has three children defined in the -\ext{bib} file, only two have been selected, so the child count is -set to 2. Similarly the \code{minerals} entry has five children -defined in the \ext{bib} file, but only three have been selected, so -the child count is 3. - -The following uses the post-description hook to show the child count -in parentheses: -\begin{verbatim} -\GlsXtrLoadResources[src={entries},category=general,save-child-count] - -\renewcommand{\glsxtrpostdescgeneral}{% - \glsxtrifhasfield{childcount}{\glscurrententrylabel} - { (child count: \glscurrentfieldvalue.)}% - {}% -} -\end{verbatim} -(\ics{glsxtrifhasfield} requires at least \sty{glossaries-extra} v1.19. -It's slightly more efficient that \ics{ifglshasfield} provided by -the base \styfmt{glossaries} package, and it doesn't complain if the -entry or field don't exist, but note that \ics{glsxtrifhasfield} -implicitly scopes its content. Use the starred version to omit the -grouping.) - -\optsection{save-original-id} - -The \meta{value} may be either the keyword \code{false} or -the name of an internal field in which to store the entry's original -label (as given in the \ext{bib} file). The default setting is -\csopt[false]{save-original-id}. If \meta{value} is omitted, -\csopt[originalid]{save-original-id} is assumed. - -If \meta{value} is a known field, it will be set after the field -aliases, otherwise it will simply be added to the \ext{glstex} file -using \ics{GlsXtrSetField} after the entry definition. - -\optsection{copy-alias-to-see} - -If set, the value of the \field{alias} field is copied to -the \field{see} field. The default setting is \csopt[false]{copy-alias-to-see}. - \section{Plurals} \label{sec:plurals} @@ -8022,7 +8224,7 @@ The locations are always listed in the order in which they were indexed, (except for the cross-reference which may be placed at the start or end of the list or omitted). This is different to \idx!{xindy} and \idx!{makeindex} where you can -specify the ordering (such as lower case Roman first, then digits, +specify the ordering (such as \idx!{lowercase} Roman first, then digits, etc), but unlike those applications, \bibgls\ allows any location, although it may not be able to work out an integer representation. (With \idx!{xindy}, you can define new location formats, but you need @@ -8202,16 +8404,16 @@ $d$ is the value of \optfmt{max-loc-diff} then the locations are consecutive otherwise they're not consecutive. \end{enumerate} \item\label{itm:rommatch} The next pattern matches for \meta{prefix}\meta{sep}\meta{n} -where \meta{n} is a lower case Roman numeral, which is converted to +where \meta{n} is a \idx!{lowercase} Roman numeral, which is converted to a decimal value and the test is performed in the same way as the above \hyperref[itm:decmatch]{decimal test}. \item\label{itm:Rommatch} The next pattern matches for \meta{prefix}\meta{sep}\meta{n} -where \meta{n} is an upper case Roman numeral, which is converted to +where \meta{n} is an \idx!{uppercase} Roman numeral, which is converted to a decimal value and the test is performed in the same way as the above \hyperref[itm:decmatch]{decimal test}. \item\label{itm:alphmatch} The next pattern matches for \meta{prefix}\meta{sep}\meta{c} -where \meta{c} is either a lower case letter from \code{a} to -\code{z} or an upper case letter from \code{A} to \code{Z}. +where \meta{c} is either a \idx!{lowercase} letter from \code{a} to +\code{z} or an \idx!{uppercase} letter from \code{A} to \code{Z}. The character is converted to its code point and the test is performed in the same way as the \hyperref[itm:decmatch]{decimal pattern} above. \item\label{itm:nomatch} If none of the above, the locations aren't considered @@ -9243,15 +9445,15 @@ rule provided by \csopt{sort-rule}. The sort methods listed in \tableref{tab:sortoptionsletter} use letter case comparators. These simply compare the character codes. The \optfmt{-nocase} options first convert the -\field{sort} field to lower case before performing the sort. +\field{sort} field to \idx{lowercase} before performing the sort. Punctuation isn't ignored. Use \csopt[\meta{lang tag}]{sort} with \csopt[none]{break-at} to emulate \idx!{xindy}['s] locale letter ordering. The examples below show the ordering of the list \code{antelope}, \code{bee}, \code{Africa}, \code{aardvark} and \code{Brazil}. \begin{itemize} -\item \optfmt{letter-case}: case-sensitive letter sort. Upper case -and lower case are in separate letter groups. +\item \optfmt{letter-case}: case-sensitive letter sort. +\Idx{uppercase} and \idx{lowercase} are in separate letter groups. Example: \code{Africa} (letter group \qt{A}), \code{Brazil} @@ -9261,7 +9463,8 @@ Example: \item \optfmt{letter-case-reverse}: reverse case-sensitive letter sort. \item \optfmt{letter-nocase}: case-insensitive letter sort. (All -upper case characters will have first been converted to lower case.) +\idx{uppercase} characters will have first been converted to +\idx{lowercase}.) Example: \code{aardvark} (letter group \qt{A}), \code{Africa} @@ -9272,9 +9475,9 @@ Example: \item \optfmt{letter-nocase-reverse}: reverse case-insensitive letter sort. \item \optfmt{letter-upperlower}: each character pair is first -compared according to their lower case values. If these are equal, +compared according to their \idx{lowercase} values. If these are equal, then they are compared according to case. This puts upper and lower -case in the same letter group but the upper case comes first. +case in the same letter group but the \idx{uppercase} comes first. Example: \code{Africa} (letter group \qt{A}), \code{aardvark} (letter group @@ -9284,9 +9487,9 @@ Example: \item \optfmt{letter-upperlower-reverse}: reverse upper-lower letter sort. \item \optfmt{letter-lowerupper}: each character pair is first -compared according to their lower case values. If these are equal, -then they are compared according to case. This puts upper and lower -case in the same letter group but the lower case comes first. +compared according to their \idx{lowercase} values. If these are equal, +then they are compared according to case. This puts +\idxlink{uppercase}{upper} and \idx{lowercase} in the same letter group but the \idx{lowercase} comes first. Example: \code{aardvark} (letter group \qt{A}), \code{antelope} (letter group \qt{A}), @@ -9459,7 +9662,7 @@ letter-number sort. \item \optfmt{letternumber-nocase}: case-insensitive letter-number sort. The sort value is first converted to lower case. Note that \csopt[between]{letter-number-rule} doesn't make -sense in this context as there won't be any upper case characters in +sense in this context as there won't be any \idx!{uppercase} characters in the sort value, so numbers will always come before letters. Example: \code{C\textsubscript{5}H\textsubscript{4}NCOOH}, @@ -9478,7 +9681,8 @@ letter-number sort. \item \optfmt{letternumber-upperlower}: upper-lower letter-number sort. This behaves slightly differently to \optfmt{letter-upperlower} when used with \csopt[between]{letter-number-rule} -as it will segregate the upper and lower case characters if there +as it will segregate the \idxlink{uppercase}{upper} and +\idx{lowercase} characters if there are any numerical sub-strings. Example: \code{CH\textsubscript{2}O}, @@ -9492,9 +9696,9 @@ are any numerical sub-strings. Example: \code{Co\textsubscript{2}O\textsubscript{3}}. The \csopt[between]{letter-number-rule} setting enforces numbers -after upper-case (for the case-sensitive and upper-lower methods) -which makes the \code{\textsubscript{5}} come after the upper case -\code{O} and forces the lower case characters to come after it. +after \idx{uppercase} (for the case-sensitive and upper-lower methods) +which makes the \code{\textsubscript{5}} come after the \idx{uppercase} +\code{O} and forces the \idx{lowercase} characters to come after it. Compare this with \csopt[before letter]{letter-number-rule} which results in the order: @@ -9527,16 +9731,16 @@ Example: \code{CH\textsubscript{2}O}. The algorithm is reversed which means that when two letters are -compared then, if both letters have the same lower case version, -the upper-lower rule is reversed and lower case comes before -upper case. This means that \code{o} comes before \code{O}. -If their lower case versions aren't identical, the letter -with the higher lower case Unicode value comes first. This means +compared then, if both letters have the same \idx{lowercase} version, +the upper-lower rule is reversed and \idx{lowercase} comes before +\idx{uppercase}. This means that \code{o} comes before \code{O}. +If their \idx{lowercase} versions aren't identical, the letter +with the higher \idx{lowercase} Unicode value comes first. This means that both \code{o} and \code{O} come before \code{l} which comes before \code{H}. So far, this gives the order: \code{o}, \code{O}, \code{l}, \code{H}. The \csopt[between]{letter-number-rule} setting inserts numbers between -upper and lower case letters. This puts the numbers (in reverse +\idxlink{uppercase}{upper} and \idx{lowercase} letters. This puts the numbers (in reverse order) between \code{o} and \code{O}. Compare this with \csopt[before letter]{letter-number-rule} which @@ -9573,9 +9777,9 @@ Example: \code{CO}. The \csopt[between]{letter-number-rule} setting enforces numbers -after lower-case (for the lower-upper method) +after \idx{lowercase} (for the lower-upper method) so the \code{\textsubscript{5}} is put after \code{o}, and forces -the upper case characters after the numbers. +the \idx{uppercase} characters after the numbers. Compare this with \csopt[before letter]{letter-number-rule} which results in the order: @@ -9925,6 +10129,26 @@ trailing spaces. The default setting is \csopt[true]{trim-sort}. This option automatically sets \csopt[\meta{boolean}]{dual-trim-sort} and \csopt[\meta{boolean}]{secondary-trim-sort}. +\optsection{sort-replace} + +This option may be used to perform regular expression substitutions +on the sort value and has the same syntax as \csopt{labelify-replace}. +This action is done after the interpreter parses the +sort value (if applicable) and before \csopt{sort-number-pad} (if +applicable). For example, suppose the sort value is +\begin{verbatim} +\ensuremath{\approx 3.14} +\end{verbatim} +then the interpreter will convert this to $\mathtt{\approx}$\texttt{3.14} but +\begin{codeenv} +\csopt[\marg{\cs{glshex}2248}\marg{}]{sort-replace} +\end{codeenv} +can be used to strip the $\approx$ symbol (\hex{2248}) so that the value can +now be parsed as a number if \csopt[double]{sort} has been used. + +Use \csopt{dual-sort-replace} for dual +and \csopt{secondary-sort-replace} for secondary sort methods. + \optsection{sort-rule} If the \csopt[custom]{sort} option is used, the sort rule must be @@ -10080,6 +10304,16 @@ and \qt{seal} becomes \verb"seal|". The default marker is \verb"|" which is commonly placed in collation rules before digits but after the ignored characters, such as spaces and hyphens. +Note that this action removes non-letters, so for example, +if the sort value is \verb"# (parameter)" then it will be converted +to \verb"parameter|" (hash, space and parentheses removed). +If you only want to break at spaces (optionally following a command) +use the following instead: +\begin{codeenv} + \csopt[none]{break-at}, + \csopt[\marg{,? +}\marg{|}]{sort-replace} +\end{codeenv} + You can change the construction of the break points with \csopt[\meta{option}]{break-at} where \meta{option} may be one of: \begin{itemize} @@ -10093,12 +10327,12 @@ For example, the sort value \qt{Tom, Dick, and Harry} becomes characters. \item \optfmt{character}: break after each character. \item \optfmt{sentence}: break after each sentence. -\item \optfmt{upper-notlower}: break after any upper case character -that's not followed by a lower case character. For example, +\item \optfmt{upper-notlower}: break after any \idx{uppercase} character +that's not followed by a \idx{lowercase} character. For example, \qt{MathML} becomes \verb"MathM|L|" and \qt{W3C} becomes \verb"W|3C|". -\item \optfmt{upper-upper}: break after any upper case character -that's followed by an upper case character. +\item \optfmt{upper-upper}: break after any \idx{uppercase} character +that's followed by an \idx{uppercase} character. \item \optfmt{upper-notlower-word}: first applies break-points according to \optfmt{upper-notlower} and then according to \optfmt{word}. @@ -10106,7 +10340,8 @@ according to \optfmt{upper-notlower} and then according to according to \optfmt{upper-upper} and then according to \optfmt{word}. \item \optfmt{none}: don't create break points. Use this option to -emulate \idx{makeindex} or \idx{xindy}'s letter ordering. +emulate \idx{makeindex} or \idx{xindy}'s letter ordering, or combine +with \csopt{sort-replace} to insert custom break points. \end{itemize} This option is ignored when used with the non-alphabetic \csopt{sort} options. @@ -10616,9 +10851,10 @@ letter. letter. \item\optfmt{between}: (default) numbers come between letter cases. With the \optfmt{-case} or \optfmt{-upperlower} sort options, -this will put numbers after upper case and before lower case. +this will put numbers after \idx{uppercase} and before +\idx{lowercase}. With the \optfmt{-lowerupper} sort option, this will put numbers -after lower case and before upper case. This setting doesn't make +after \idx{lowercase} and before \idx{uppercase}. This setting doesn't make much sense with the \optfmt{-nocase} option but, if used, this will put numbers before letters. \item\optfmt{first}: numbers are considered less than all @@ -10628,8 +10864,8 @@ characters (including punctuation and spaces). \end{itemize} Note that the reverse sort methods will invert this setting. Remember also that the case-insensitive letter-number sort methods always -first convert the \field{sort} field to lower case, which means that -if you use one of them then there won't be any upper case +first convert the \field{sort} field to \idx{lowercase}, which means that +if you use one of them then there won't be any \idx{uppercase} characters. Use \csopt{letter-number-punc-rule} to determine the relative @@ -10846,7 +11082,7 @@ Then the entries can be sorted by date of birth using: \end{verbatim} The \code{G} (era) date pattern specifier expects a string, such as -\qt{AD}. It will match lower case forms, such as \qt{ad}, so if you +\qt{AD}. It will match \idx{lowercase} forms, such as \qt{ad}, so if you have \verb|\textsc{ad}| the interpreter will convert this to \code{ad} (stripping the text-block command). However, in general it's best to supply a semantic command that ensures that the @@ -10905,15 +11141,15 @@ setting. \item\optfmt{codepoint}: the group is set to \icswithargs{bibglsunicodegroup}, where the first argument is the -first significant character (converted to lower case and decomposed, +first significant character (converted to \idx{lowercase} and decomposed, if applicable) of the sort value. \item\optfmt{unicode category}: the group is set to \icswithargs{bibglsunicodegroup}, where the first argument is the label identifying the Unicode category of the first significant character of the sort value. For example, the label \code{Ll} -signifies a lower case letter and \code{Lu} signifies an upper case -letter. +signifies a \idx!{lowercase} letter and \code{Lu} signifies an +\idx!{uppercase} letter. \item\optfmt{unicode script}: the group is set to \icswithargs{bibglsunicodegroup}, where the first argument is the @@ -10927,7 +11163,7 @@ that are often used with non-Greek scripts). \icswithargs{bibglsunicodegroup}, where the first argument is the label corresponding to the Unicode category and script of the first significant character of the sort value. For example, the label -\code{Ll.LATIN} indicates a lower case Latin letter. +\code{Ll.LATIN} indicates a \idx!{lowercase} Latin letter. \end{itemize} This option has no effect with \longarg{no-group} or if no sorting is applied. Use \csopt{secondary-group-formation} for secondary @@ -11094,6 +11330,10 @@ As \csopt{missing-sort-fallback} but for secondary sorting. As \csopt{trim-sort} but for secondary sorting. +\optsection{secondary-sort-replace} + +As \csopt{sort-replace} but for secondary sorting. + \optsection{secondary-sort-rule} As \csopt{sort-rule} but for secondary custom sorting. @@ -11303,7 +11543,7 @@ file (or created through a mapping). The \meta{value} is required. The \meta{value} may be: \begin{itemize} \item \optfmt{same as entry}: sets the \field{type} to the entry -type (lower case and without +type (\idx!{lowercase} and without the initial \code{@}). For example, if the entry was defined with \atentry{dualentry}, the \field{type} will be set to \optfmt{dualentry}. @@ -11312,7 +11552,7 @@ entry type not the original entry type provided in the \ext{bib} file. \item \optfmt{same as original entry}: set the \field{type} field -to the original entry type (lower case and without +to the original entry type (\idx!{lowercase} and without the initial \code{@}) before it was aliased (behaves like \optfmt{same as entry} if the entry type wasn't aliased). @@ -11361,7 +11601,7 @@ file (or created through a mapping). The \meta{value} may be empty. The \meta{value} may be: \begin{itemize} \item \optfmt{same as entry}: sets the \field{category} to the entry -type (lower case and without +type (\idx{lowercase} and without the initial \code{@}). For example, if the entry was defined with \atentry{dualentry}, the \field{category} will be set to \optfmt{dualentry}. @@ -11370,7 +11610,7 @@ entry type not the original entry type provided in the \ext{bib} file. \item \optfmt{same as original entry}: set the \field{category} field -to the original entry type (lower case and without +to the original entry type (\idx{lowercase} and without the initial \code{@}) before it was aliased (behaves like \optfmt{same as entry} if the entry type wasn't aliased). @@ -11411,7 +11651,9 @@ to the start of the \iext{glstex} file providing the key given by \meta{value}. Any entries defined using \atentry{dualentry} will be written to the \ext{glstex} file with an extra field called \meta{value} that is set to the mirror entry. If \meta{value} is -omitted \code{dual} is assumed. +omitted \csopt[dual]{dual-field} is assumed. If you use a different +value, you will need to redefine \gls{GlsXtrDualField} (either +locally or globally). For example, if the \ext{bib} file contains \begin{verbatim} @@ -11531,6 +11773,10 @@ As \csopt{missing-sort-fallback} but for dual sorting. As \csopt{trim-sort} but for dual sorting. +\optsection[\subsubsection]{dual-sort-replace} + +As \csopt{sort-replace} but for dual sorting. + \optsection[\subsubsection]{dual-sort-rule} As \csopt{sort-rule} but for \csopt[custom]{dual-sort}. @@ -11820,13 +12066,39 @@ defined with \atentry{dualsymbol} instead of \atentry{dualentry}. Analogous to \csopt{dual-entry-backlink} but for entries defined with \atentry{dualabbreviationentry} instead of -\atentry{dualentry}. +\atentry{dualentry}. This setting can be problematic as the +backlinks rely on the relevant field being known to \bibgls. +Since the abbreviation style typically sets the \field{name} +field (and sometimes the \field{description} field as well), you may +find that no backlink appears. A simple workaround is to +use \csopt{dual-field} (or \csopt[dual]{dual-field}) +to store the dual label in the \field{dual} field, and then +use a style that checks for this field and adds the backlink. + +With \sty{glossaries-extra} v1.30+ you can use +\nosecdef{GlsXtrDualBackLink} +which encapsulates \meta{text} with a hyperlink to the dual. +The \meta{label} identifies the entry that requires a backlink. +The dual's label is obtained from the field given by +\nosecdef{GlsXtrDualField} +which defaults to \field{dual}. Note that if you assign a +different field label with \csopt{dual-field}, then you will +need to redefine \gls{GlsXtrDualField} as appropriate. + +For example: +\begin{verbatim} +\renewcommand*{\glsuserdescription}[2]{% + \GlsXtrDualBackLink{\glslonguserfont{#1}}{#2}% +} +\setabbreviationstyle{long-short-user} +\GlsXtrLoadResources[src={entries},dual-field] +\end{verbatim} \optsection[\subsubsection]{dual-entryabbrv-backlink} -Analogous to \csopt{dual-entry-backlink} but for entries +As \csopt{dual-abbrventry-backlink} but for entries defined with \atentry{dualentryabbreviation} instead of -\atentry{dualentry}. +\atentry{dualabbreviationentry}. \optsection[\subsubsection]{dual-indexentry-backlink} @@ -11919,7 +12191,7 @@ file is: \longnewglossaryentry*{#1}{name={#3},#2}{#4}% } \end{verbatim} -This uses the starred form of \gls{longnewglossaryentry} that +This uses the starred form \ics{longnewglossaryentry*} that doesn't automatically append \ics{nopostdesc} (which interferes with the post-description hooks provided by category attributes). @@ -11970,15 +12242,29 @@ file is: \newglossaryentry{#1}{name={#1},category={index},description={},#2}% } \end{verbatim} -This makes the \field{name} default to the \meta{label}, assigns the +This makes the \field{name} default to the \meta{label}, assigns the \field{category} to \code{index} and sets an empty \field{description}. These settings may be overridden by \meta{options}. Note that the \field{description} doesn't include -\ics{nopostdesc} to allow for the post-description hook used by +\ics{nopostdesc} to allow for the \idx{postdescriptionhook} used by category attributes. +\cssection{bibglsnewindexplural} + +\formatdef{bibglsnewindexplural} +This command is used to define terms identified with the +\atentry{indexplural} type. The definition provided in the \ext{glstex} +file is: +\begin{verbatim} +\providecommand{\bibglsnewindexplural}[3]{% + \newglossaryentry{#1}{name={#3},category={indexplural},description={},#2}% +} +\end{verbatim} +This assigns the \field{category} to \code{indexplural} and sets an empty +\field{description}. These settings may be overridden by \meta{options}. + \cssection{bibglsnewabbreviation} \formatdef{bibglsnewabbreviation} @@ -12771,7 +13057,7 @@ according to the rule): For example, if the rule recognises the digraph \qt{dz}, then the title is \qt{Dz}. Exceptions to this are included in the \langxml. If the key \code{grouptitle.case.\meta{lc}} exists, where -\meta{lc} is the lower case version of \meta{title}, then the value +\meta{lc} is the \idx!{lowercase} version of \meta{title}, then the value of that key is used instead. For example, the Dutch digraph \qt{ij} should be converted to \qt{IJ}, so \file{bib2gls-en.xml} includes: \begin{verbatim} @@ -12779,7 +13065,7 @@ should be converted to \qt{IJ}, so \file{bib2gls-en.xml} includes: \end{verbatim} (See the \longarg{group} switch for more details.) \item \meta{letter} This is the actual letter at the start of the -given entry's \field{sort} field, which may be lower case or may +given entry's \field{sort} field, which may be \idx!{lowercase} or may contain diacritics that don't appear in \meta{title}. \item \meta{id} A numeric identifier. This may be the collation key or the code point for the given letter, depending on the sort @@ -12799,6 +13085,51 @@ This field needs to expand to a simple label, which \csref{bibglslettergroup} is designed to do. Note that non-letter groups are dealt with separately (see below). +\cssection{bibglssetlastgrouptitle} + +In the last resource (\ext{glstex}) file, after all the relevant +group titles have been set with the commands listed below, there's a +final title setting: +\formatdef{bibglssetlastgrouptitle} +This does nothing by default, but the arguments are set to +correspond to the group with the maximum id for that resource file. +It's provided as a convenient way of overriding the final group +title without the inconvenience of looking up the group label in the +\ext{glstex} file. If you have multiple glossaries or if you want to +override a different group, then you need to inspect the +\ext{glstex} file to work out the corresponding label (by finding +the \field{group} assignment for one of the entries in that group). + +The \meta{cs} argument is the control sequence used in the +\field{group} field to obtain the label from \meta{specs}. For +example, if the highest \meta{id} is 2147418112 from +\begin{codeenv} +\field{group}=\marg{\gls{bibglslettergroup}\marg{Ø}\marg{Ø}\marg{2147418112}\marg{}} +\end{codeenv} +then the last group is identified with +\begin{verbatim} +\bibglssetlastgrouptitle{\bibglslettergroup}{{Ø}{Ø}{2147418112}{}} +\end{verbatim} +In this case \meta{cs} is \gls{bibglslettergroup} and \meta{specs} +are the arguments for that command. If you want \gls{bibglssetlastgrouptitle} +to change the group title then you need to define it before the +\idx{resourceset}. For example: +\begin{verbatim} +\newcommand*{\bibglssetlastgrouptitle}[2]{% + \glsxtrsetgrouptitle{#1#2}{Foreign Words}} + +\GlsXtrLoadResources[sec={entries}] +\end{verbatim} +If you need to change a particular group title, then it has to be +done after the \idx{resourceset}: +\begin{verbatim} +\GlsXtrLoadResources[sec={entries}] + +\glsxtrsetgrouptitle + {\bibglslettergroup{{Ø}{Ø}{2147418112}{}}}% label + {Foreign Words}% title +\end{verbatim} + \cssection{bibglssetlettergrouptitle} For each \idx{lettergroup} that's detected, \bibgls\ will write the line: @@ -13105,11 +13436,11 @@ obtained from \cs{bibglsunicodegrouptitle}. The \meta{label} depends on the \csopt{group-formation} setting: \begin{itemize} \item\csopt[codepoint]{group-formation}: the \meta{label} is the -Unicode value of \meta{character} (converted to lower case and +Unicode value of \meta{character} (converted to \idx!{lowercase} and decomposed, if applicable); \item\csopt[unicode category]{group-formation}: the \meta{label} is the Unicode category of \meta{character} (for example, \code{Lu} means -an upper case letter); +an \idx!{uppercase} letter); \item\csopt[unicode script]{group-formation}: the \meta{label} is the Unicode script associated with \meta{character} (for example, \code{LATIN}); @@ -13136,7 +13467,7 @@ whereas with \csopt[unicode category and script]{group-formation} it will be: \begin{verbatim} group={\bibglsunicodegroup{Lu.LATIN}{Å}{C5}{}} \end{verbatim} -(upper case Latin letter). +(\idx!{uppercase} Latin letter). If instead \qt{\AA} is considered equivalent to \qt{A} according to the collator, then with \csopt[codepoint]{group-formation}, the value will be: @@ -14358,6 +14689,30 @@ doesn't occur in the \field{description} field. (Note that The contents of \filefmt{films.bib} are as follows: \lstinputlisting[firstline=5]{../examples/films.bib} +\filesection{citations.bib} + +The \exfile{citations.bib} file is actually a \BibTeX\ file, but it +can be parsed by \bibgls\ if the \BibTeX\ entry types are converted +to \atentry{bibtexentry}, which can easily be done with +\begin{codeenv} +entry-type-aliases=\marg{\ics{GlsXtrBibTeXEntryAliases}} +\end{codeenv} +The field names will also need to be defined or aliased. For +example: +\begin{codeenv} +field-aliases=\marg{title=name} +\end{codeenv} +If \bibgls\ is then run with \longarg{cite-as-record} any +\ics{citation} commands found in the \ext{aux} file will be treated +as ignored records. The \atentry{preamble} provides a formatting +command that's used by both \BibTeX\ and \bibgls, so \cs{providecommand} +is required rather than \cs{newcommand} as it will appear in both +the \iext{bbl} and the \iext{glstex} files. (In general it's best to +use \cs{providecommand} rather than \cs{newcommand} in the +\atentry{preamble} but in this case it's essential.) +The contents of \filefmt{citations.bib} are as follows: +\lstinputlisting[firstline=5]{../examples/citations.bib} + \filesection{mathgreek.bib} The \exfile{mathgreek.bib} file contains Greek letters for use in @@ -14368,7 +14723,7 @@ by the \field{name} field (for example, with \csopt[name]{sort-field}) the \TeX\ parser library recognises all the mathematical Greek letter commands provided in the \LaTeX\ kernel. Additionally it recognises \ics{omicron} which isn't provided by \LaTeX\ (the symbol can be -reproduced with a lower case Latin \qt{o}). Note that +reproduced with a \idx!{lowercase} Latin \qt{o}). Note that \isty{glossaries-extra-bib2gls} (\sty{glossaries-extra} v1.27+) provides all the missing Greek letters (such as \cs{omicron}). @@ -14400,7 +14755,7 @@ but \LaTeX\ needs a definition for this, so it's provided in the \end{verbatim} (With \sty{glossaries-extra} v1.27+, this is no longer needed.) The \TeX\ parser library and \sty{glossaries-extra-bib2gls} -similarly provide the missing upper case +similarly provide the missing \idx!{uppercase} Greek letters, and these can be dealt with in the same way. The contents of \filefmt{mathgreek.bib} are as follows: @@ -16042,7 +16397,7 @@ field with \csopt{field-aliases}: \csopt[author=parent]{field-aliases} \end{codeenv} but the author's label in the \exfile{people.bib} -file is just the lower case surname. +file is just the \idx!{lowercase} surname. Remember from \sectionref{sec:texparserlib} that the interpreter will be used on the \field{parent} field if the value contains @@ -16117,8 +16472,6 @@ The resulting document is shown in \figureref{fig:sample-authors.pdf}. \lstinputlisting[firstline=5]{../examples/sample-authors.tex} -\lstinputlisting[firstline=5]{../examples/sample-authors.tex} - \begin{figure} \figcontents {% @@ -16128,6 +16481,167 @@ The resulting document is shown in \figureref{fig:sample-authors.pdf}. {fig:sample-authors.pdf} \end{figure} +\filesection{sample-citations.tex} + +This example uses the \BibTeX\ file \exfile{citations.bib} to create +a document that has both a bibliography created by \BibTeX\ and +glossaries created by \bibgls\ listing the authors and the titles. +There are no glossary reference commands, such as \cs{gls}, but +\bibgls\ can be run with \longarg{cite-as-record} to treat the +\ics{citation} commands (written to the \ext{aux} file by \ics{cite}) +as ignored records. Since \cs{cite} doesn't record the page number, +there are no associated locations. + +The \code{main} glossary isn't required, so I've used +\styopt{nomain} to suppress its creation. I want to use both the +\glostyle{altlist} and \glostyle{indexgroup} styles but none of the +other styles, so I've used \styopt{nostyles} to prevent the +automatic loading of the default style packages and +\styopt{stylemods} to load the \sty{glossary-tree} and +\sty{glossary-list} packages and patch the styles. A \idx{full-stop} +is automatically placed after the descriptions with +\styopt{postdot}. +\begin{verbatim} +\usepackage[record,% using bib2gls +nomain,% don't define main glossary +postdot,% full stop after descriptions +nostyles,% don't load default styles +% load glossary-tree and glossary-list and patch styles: +stylemods={tree,list} +]{glossaries-extra} +\end{verbatim} +Next I need to create the glossaries for the list of authors and +list of titles: +\begin{codeenv} +\cs{newglossary*}\marg{contributors}\marg{Authors} +\cs{newglossary*}\marg{titles}\marg{Titles} +\end{codeenv} +The simplest way of assigning the authors to the \code{contributors} +glossary and the titles to the \code{titles} glossary is to use +\begin{codeenv} +\csopt[contributors]{type} +\end{codeenv} +in the \idx{resourceset} and provide a +modified version of \ics{bibglsnewbibtexentry} that assigns +\field{type} after the options: +\begin{codeenv} +\cs{newcommand}\marg{\cs{bibglsnewbibtexentry}}[4]\marg{\idx{commentchar} + \gls{longnewglossaryentry}*\marg{\idx{param}1}\marg{name=\marg{\idx{param}3},\idx{param}2,type=\marg{titles}}\marg{\idx{param}4}\idx{commentchar} +} +\end{codeenv} +The standard \BibTeX\ entry types need aliasing to +\atentry{bibtexentry}: +\begin{codeenv} +\csopt[\ics{GlsXtrBibTeXEntryAliases}]{entry-type-aliases} +\end{codeenv} +and the \fieldfmt{title} field is aliased to \field{name}: +\begin{codeenv} +\csopt[title=name]{field-aliases} +\end{codeenv} +(The other fields aren't required for the glossary lists.) +The \field{category} is set to the original entry type: +\begin{codeenv} +\csopt[same as original entry]{category} +\end{codeenv} +So, for example, an entry that's provided in the \ext{bib} file with +\atentryfmt{article} has the \field{category} field set to +\code{article}. (Compare this with \csopt[same as entry]{category} +which would set the \field{category} to \code{bibtexentry}.) +The spawned entries are all defined using \atentry{contributor} and +aren't aliased so both the entry type and the original entry type +are \code{contributor}. + +In order to list the titles according to category, I've use this as +the sort field: +\begin{codeenv} +\csopt[category]{sort-field} +\end{codeenv} +and setting the sort suffix to the \field{name} field sub-sorts +the \atentry{bibtexentry} types according to the title +(which was aliased to the \field{name}) and the +\atentry{contributor} types according to the author: +\begin{codeenv} +\csopt[name]{sort-suffix} +\end{codeenv} + +Next the groups identified by the labels \code{article} and \code{book} +are assigned titles. +\begin{codeenv} +\cs{glsxtrsetgrouptitle}\marg{article}\marg{Articles} +\cs{glsxtrsetgrouptitle}\marg{book}\marg{Books} +\end{codeenv} +The \field{group} field is actually set to the associated letter by the default +\csopt{sort} method. The desired labels are stored in the \field{category} +field. Since the entries are sorted by category, then they are naturally +in those sub-blocks, which means that the group titles can be set by locally +redefining \ics{glsxtrgroupfield} to \code{category}: +\begin{codeenv} +\cs{printunsrtglossary*}[type=titles,style=indexgroup] +\marg{\idx{commentchar} + \cs{renewcommand}\marg{\cs{glsxtrgroupfield}}\marg{category}\idx{commentchar} + \cs{renewcommand}\marg{\cs{glstreenamefmt}}[1]\marg{\cs{emph}\marg{\idx{param}1}}\idx{commentchar} + \cs{renewcommand}\marg{\cs{glstreegroupheaderfmt}}[1]\marg{\ics{textbf}\marg{\idx{param}1}}\idx{commentchar} +} +\end{codeenv} +There's no \field{description} field set for these entries, but the +\idx{postdescriptionhook} can still be used to append information. +In this case, I've appended a cross-reference to the bibliography. +Since the bibliography entry and the glossary term both have the +same label, the citation can easily be obtained with +\code{\ics{cite}\marg{\cs{glscurrententrylabel}}}: +\begin{codeenv} +\cs{newcommand}\marg{\postdeschook{article}}\marg{\cs{cite}\marg{\cs{glscurrententrylabel}}} +\cs{newcommand}\marg{\postdeschook{book}}\marg{\cs{cite}\marg{\cs{glscurrententrylabel}}} +\end{codeenv} +Note that this needs to be done for each \BibTeX\ entry type, but in +this case the \ext{bib} file only contains \atentryfmt{article} and +\atentryfmt{book} entries. (Similarly for the group titles above.) + +The list of contributors can simply be displayed with: +\begin{codeenv} +\cs{printunsrtglossary}[type=contributors,style=altlist] +\end{codeenv} +This will only list the names as there's no description, but again +the \idx{postdescriptionhook} can be used, in this case for the \code{contributor} +category. The hook iterates +over the internal list provided by the \field{bibtexentry} field. +This allows the titles to be listed as well: +\begin{codeenv} +\cs{newcommand}\marg{\postdeschook{contributor}}\marg{\idx{commentchar} + \ics{glsxtrifhasfield}\marg{bibtexentry}\marg{\cs{glscurrententrylabel}}\idx{commentchar} + \marg{\idx{commentchar} + \cs{glsxtrfieldforlistloop} + \marg{\cs{glscurrententrylabel}}\marg{bibtexentry}\idx{commentchar} + \marg{\csfmt{contributorhandler}}\idx{commentchar} + }\idx{commentchar} + \marg{\ics{par} No titles.}\idx{commentchar} +} +\end{codeenv} +The handler macro displays the name of the associated +\atentry{bibtexentry} term and the citation: +\begin{codeenv} +\cs{newcommand}\marg{\csfmt{contributorhandler}}[1]\marg{\cs{par}\ics{glsentryname}\marg{\idx{param}1} \cs{cite}\marg{\idx{param}1}} +\end{codeenv} + +The complete document code is listed below. The document build is: +\begin{verbatim} +pdflatex sample-citations +bib2gls --group --cite-as-record sample-citations +bibtex sample-citations +pdflatex sample-citations +pdflatex sample-citations +\end{verbatim} +The resulting document is shown in \figureref{fig:sample-citations.pdf}. + +\lstinputlisting[firstline=7]{../examples/sample-citations.tex} + +\begin{figure} +\figcontents +{\pdftwocol{../examples/sample-citations.pdf}{2}} +{\caption{\filefmt{sample-citations.pdf}}} +{fig:sample-citations.pdf} +\end{figure} + \filesection{sample-msymbols.tex} This example uses \exfile{bigmathsymbols.bib}, @@ -16430,7 +16944,7 @@ the \atentry{preamble} definition, which is now in the resource file. The tagging format is governed by \ics{glsxtrtagfont} which underlines its argument by default. I've redefined it to also -convert the letter to uppercase: +convert the letter to \idx{uppercase}: \begin{verbatim} \renewcommand*{\glsxtrtagfont}[1]{\underline{\MakeTextUppercase{#1}}} \end{verbatim} @@ -16471,7 +16985,7 @@ location lists. This doesn't affect the entries that haven't been indexed. I decided to convert the first letter of the \field{name} field to -uppercase. Since the \field{name} is implicitly set for +\idx{uppercase}. Since the \field{name} is implicitly set for abbreviations based on the style, I've decided to implement this through the \catattr{glossname} attribute rather than using \csopt{name-case-change}: @@ -17149,7 +17663,7 @@ rule for the duals, but with the numbers padded: \end{codeenv} This method doesn't work as well as the method used in \exfile{sample-chemical.tex} as it doesn't separate the capitals, -digits and lower case characters in the way that can be achieved with the +digits and \idx!{lowercase} characters in the way that can be achieved with the letter-number methods. An improvement can be made by changing the break-points. I could use \csopt[upper-upper]{dual-break-at} but this would put \qt{seal} before \qt{sea lion} in the \code{animal} @@ -17865,6 +18379,7 @@ The resulting document is shown in \figureref{fig:sample-multi2.pdf}, {fig:sample-multi2.pdf3} \end{figure} +\printstyoptsummary \printcommandsummary \bibliographystyle{plain} |