diff options
author | Karl Berry <karl@freefriends.org> | 2020-03-24 20:54:02 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2020-03-24 20:54:02 +0000 |
commit | 6c9767fa3ed5fdd16f7045079d4c7144ed22a89f (patch) | |
tree | 4eca6f8d4fe7d6bf796ba912efa35692c4daae20 /Master/texmf-dist/source | |
parent | 7e0670894cc9e548cbe17d5bda9e242f239638fc (diff) |
bib2gls (24mar20)
git-svn-id: svn://tug.org/texlive/trunk@54525 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source')
-rw-r--r-- | Master/texmf-dist/source/support/bib2gls/src/bib2gls-src.zip | bin | 195429 -> 198175 bytes | |||
-rw-r--r-- | Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib | 134 | ||||
-rw-r--r-- | Master/texmf-dist/source/support/bib2gls/src/bib2gls.pod | 59 | ||||
-rw-r--r-- | Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex | 732 | ||||
-rw-r--r-- | Master/texmf-dist/source/support/bib2gls/src/gls2bib-src.zip | bin | 32315 -> 32329 bytes | |||
-rw-r--r-- | Master/texmf-dist/source/support/bib2gls/src/texparser-src.zip | bin | 833795 -> 833840 bytes |
6 files changed, 860 insertions, 65 deletions
diff --git a/Master/texmf-dist/source/support/bib2gls/src/bib2gls-src.zip b/Master/texmf-dist/source/support/bib2gls/src/bib2gls-src.zip Binary files differindex 835a36dbc4a..0a4bb261e9c 100644 --- a/Master/texmf-dist/source/support/bib2gls/src/bib2gls-src.zip +++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls-src.zip diff --git a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib index 915cc0d1101..cd69e4802ce 100644 --- a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib +++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib @@ -2658,6 +2658,13 @@ field\dhyphen locale}}, parent={resourceoptions} } +@resourceoption{opt.custom-sort-fallbacks, + name={\csoptfmt{custom\dhyphen sort\dhyphen fallbacks}}, + user1={\margm{\keyvallist}}, + category={resourceoption}, + parent={resourceoptions} +} + @resourceoption{opt.entry-sort-fallback, name={\csoptfmt{entry\dhyphen sort\dhyphen fallback}}, user1={\meta{field}}, @@ -2693,6 +2700,13 @@ field\dhyphen locale}}, parent={resourceoptions} } +@resourceoption{opt.field-concat-sep, + name={\csoptfmt{field\dhyphen concat\dhyphen sep}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + @resourceoption{opt.trim-sort, name={\csoptfmt{trim\dhyphen sort}}, user1={\meta{boolean}}, @@ -5105,6 +5119,11 @@ pages (not available in multi-column or certain other contexts)}, category={environment} } +@glsenvironment{env.printunsrtglossarywrap, + name={\envfmt{print\-unsrt\-glossary\-wrap}}, + category={environment} +} + @topic{abbreviationstyles, name={abbreviation styles}, text={abbreviation style}, @@ -7589,8 +7608,8 @@ long form on \idx{firstuse}. The default definition just uses package={glossaries}, category={packageoption}, parent={packageoptions}, - description={automatically sets \styopt[true]{entrycounter} and - indicates the master counter for \counter{glossaryentry}} + description={automatically sets the option \styopt[true]{entrycounter} + and indicates the master counter for \counter{glossaryentry}} } @packageoption{styopt.subentrycounter, @@ -9351,6 +9370,20 @@ primary formats, if enabled.}, parent={commandlineoptions} } +@switch{switch.provide-glossaries, + name={\longargfmt{provide\dhyphen glossaries}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.no-provide-glossaries, + name={\longargfmt{no\dhyphen provide\dhyphen glossaries}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + @switch{switch.gls2bib.help, name={\longargfmt{help}}, symbol={\shortargfmt{h}}, @@ -9922,6 +9955,14 @@ primary formats, if enabled.}, name={\filefmt{constants.bib}} } +@samplefile{file.sample-hierarchical.tex, + name={\filefmt{sample\dhyphen hierarchical.tex}} +} + +@samplefile{file.sample-nested.tex, + name={\filefmt{sample\dhyphen nested.tex}} +} + @samplefile{file.sample-constants.tex, name={\filefmt{sample\dhyphen constants.tex}} } @@ -13157,6 +13198,20 @@ usual delay}, category={command} } +@glscommand{printunsrtinnerglossary, + name={\csfmt{print\-unsrt\-inner\-glos\-sary}}, + user1={\oargm{options}\margm{pre code}\margm{post code}}, + description={similar to \cs{printunsrtglossary} but only contains + the code that would typically be placed inside the \env{theglossary} + environment. This command should either be placed inside the + \env{printunsrtglossarywrap} environment or inside the handler macro + used by \cs{printunsrtglossary}. This command is unsuitable for + certain glossary styles, particularly tabular-like styles}, + topics={glossrefs,loop}, + note={\styfmt{glossaries-extra} v1.44+}, + category={command} +} + @glscommand{printunsrtglossary*, name={\csfmt{print\-unsrt\-glos\-sary*}}, user1={\oargm{options}\margm{code}}, @@ -13168,6 +13223,29 @@ usual delay}, category={command} } +@glscommand{printunsrtglossaryhandler, + name={\csfmt{print\-unsrt\-glos\-sary\-handler}}, + user1={\margm{label}}, + description={used by \cs{printunsrtglossary} and + \cs{printunsrtinnerglossary} to handler each entry within the + loop. By default this simply does \cs{glsxtrunsrtdo}}, + topics={glossrefs,loop}, + note={\styfmt{glossaries-extra} v1.12+}, + category={command} +} + +@glscommand{glsxtrunsrtdo, + name={\csfmt{gls\-xtr\-unsrt\-do}}, + user1={\margm{label}}, + description={displays the entry given by \meta{label} using + \cs{glossentry} or \cs{subglossentry} depending on the entry's + hierarchical level (taking \printglossopt{leveloffset} into + account)}, + topics={glossrefs,loop}, + note={\styfmt{glossaries-extra} v1.12+}, + category={command} +} + @glscommand{printunsrtglossaries, name={\csfmt{print\-unsrt\-glos\-saries}}, user1={}, @@ -13367,6 +13445,30 @@ hasn't been defined}, category={commandoption}, } +@printglossoption{printgloss.groups, + parent = {printunsrtglossary}, + name = {\csoptfmt{groups}}, + user1 = {\margm{boolean}}, + description = {controls whether or not \cs{printunsrtglossary} + (or \cs{printunsrtinnerglossary}) + should insert letter group markup. There's no visible difference + for glossary styles that don't support letter groups (and + \styopt{nogroupskip} is in effect) or if there's no group + information (for example, \longarg{no-group} has been used)}, + category={commandoption}, +} + +@printglossoption{printgloss.leveloffset, + parent = {printunsrtglossary}, + name = {\csoptfmt{level\-offset}}, + user1 = {\margm{n}}, + description = {makes the glossary style act as though each entry's + hierarchical level is \meta{offset} more than it actually is + where \meta{offset} is either \meta{n} or is locally incremented + by \meta{n} if \meta{n} starts with \code{++}}, + category={commandoption}, +} + @glscommand{glsxtrsetglossarylabel, name={\csfmt{gls\-xtr\-set\-glos\-sary\-label}}, user1={\margm{label}}, @@ -14982,13 +15084,24 @@ paragraph break that retains the hanging indent}, @glscommand{ifglossaryexists, name={\csfmt{if\-glossary\-exists}}, user1={\margm{type}\margm{true}\margm{false}}, - description={tests if the glossary given by \meta{type} exists - and does \meta{true} if it does exists, otherwise does \meta{false}}, + description={tests if the glossary identified by \meta{type} exists + and does \meta{true} if it does exists, otherwise does + \meta{false}. The unstarred form treats ignored glossaries as + non-existent}, topics={conditional,glossrefs}, note={\styfmt{glossaries}}, category={command} } +@glscommand{ifglossaryexists*, + name={\csfmt{if\-glossary\-exists*}}, + user1={\margm{type}\margm{true}\margm{false}}, + description={the starred form of \cs{ifglossaryexists} treats ignored glossaries as existing}, + topics={conditional,glossrefs}, + note={\styfmt{glossaries} v4.46+ (or \styfmt{glossaries-extra} v1.44+)}, + category={command} +} + @glscommand{ifignoredglossary, name={\csfmt{if\-ignored\-glossary}}, user1={\margm{type}\margm{true}\margm{false}}, @@ -15502,7 +15615,18 @@ number is hexadecimal)}, user1={\margm{character}}, description={puts a breve accent over \meta{character}}, note={kernel command\texparserdefnote}, - category={command} + category={command}, + annote={accent} +} + +@command{uhex, + name={\csfmt{u}}, + user1={\meta{hex}}, + description={identifies a character by its hexadecimal code in the + values of some (but not all) resource options}, + note={\bibgls}, + category={command}, + annote={hex code} } @command{acute, diff --git a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.pod b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.pod index 0740dac9281..bf82acc2c2c 100644 --- a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.pod +++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.pod @@ -78,37 +78,37 @@ Don't try interpreting (La)TeX commands. =item B<--break-space> -Interpret tilde character and \nobreakspace as a normal space. +Interpret C<~> (tilde) character and C<\nobreakspace> as a normal space. =item B<--no-break-space> -Interpret tilde and \nobreakspace as a non-breaking space (default). +Interpret C<~> (tilde) and C<\nobreakspace> as a non-breaking space (default). =item B<--cite-as-record> -Treat B<\citation> as an ignored record. +Treat C<\citation> as an ignored record. =item B<--no-cite-as-record> -Don't check for instances of B<\citation> in the B<.aux> file (default). +Don't check for instances of C<\citation> in the F<.aux> file (default). =item B<--warn-non-bib-fields> -Warn if internal non-bib fields are found in the .bib file. +Warn if internal non-bib fields are found in the F<.bib> file. =item B<--no-warn-non-bib-fields> -Don't warn if internal non-bib fields are found in the .bib file. +Don't warn if internal non-bib fields are found in the F<.bib> file. The use of these internal fields can cause unexpected results, so only use this option if you have taken appropriate precautions. =item B<--warn-unknown-entry-types> -Warn if any unknown entry types are found in the .bib file. +Warn if any unknown entry types are found in the F<.bib> file. =item B<--no-warn-unknown-entry-types> -Don't warn if any unknown entry types are found in the .bib file. +Don't warn if any unknown entry types are found in the F<.bib> file. =item B<--merge-wrglossary-records> @@ -121,8 +121,8 @@ Don't merge an entry's B<wrglossary> records. =item B<--merge-nameref-on> I<rule> -Rule for merging locations created with the record=nameref package option -(requires glossaries-extra.sty version 1.37+). The I<rule> may be +Rule for merging locations created with the B<record=nameref> package option +(requires F<glossaries-extra.sty> version 1.37+). The I<rule> may be one of: B<hcounter>, B<href>, B<title> or B<location>. =item B<--force-cross-resource-refs> or B<-x> @@ -135,16 +135,16 @@ Don't force cross-resource referencing mode on (default). =item B<--support-unicode-script> -Text superscript (\textsuperscript) or subscripts (\textsubscript) +Text superscript (C<\textsuperscript>) or subscripts (C<\textsubscript>) will use Unicode superscript/subscript characters if available. -For example, \textsuperscript{2} will be converted to U+00B2 +For example, C<\textsuperscript{2}> will be converted to U+00B2 (superscript two). =item B<--no-support-unicode-script> -Text superscript (\textsuperscript) or subscripts (\textsubscript) +Text superscript (C<\textsuperscript>) or subscripts (C<\textsubscript>) won't be converted to Unicode superscript/subscript characters. -For example, \textsuperscript{2} will be converted to <sup>2</sup> +For example, C<\textsuperscript{2}> will be converted to C<E<lt>supE<gt>2E<lt>/supE<gt>> and the markup will be stripped leaving just the character 2. =item B<--packages> I<list> (or B<-p> I<list>) @@ -182,7 +182,7 @@ packages may be used in B<--packages> or B<--ignore-packages>. =item B<--mfirstuc-protection> I<fields>|B<all> (or B<-u> I<fields>|B<all>) Insert an empty group if fields start with certain problematic -commands to protect against case-changing commands like \Gls. +commands to protect against case-changing commands like C<\Gls>. The default is to do this for all fields. To do this for only a subset of fields, set I<fields> to a comma-separated list of fields @@ -194,12 +194,12 @@ Switch off the auto-insertion of an empty group for all fields. =item B<--mfirstuc-math-protection> -Switch on the auto-insertion of an empty group for math-shift ($). +Switch on the auto-insertion of an empty group for math-shift (C<$>). This option will be overridden by B<--no-mfirstuc-protection>. =item B<--no-mfirstuc-math-protection> -Switch off the auto-insertion of an empty group for math-shift ($). +Switch off the auto-insertion of an empty group for math-shift (C<$>). =item B<--nested-link-check> I<list>|B<none> @@ -228,11 +228,11 @@ Set location format mappings. =item B<--group> or B<-g> -Add 'group' field to entries. +Add B<group> field to entries. =item B<--no-group> -Don't add 'group' field to entries (default). +Don't add B<group> field to entries (default). =item B<--record-count> or B<-c> @@ -278,11 +278,24 @@ This option cancels B<--trim-only-fields> and B<--trim-fields>. =item B<--expand-fields> -Don't write B<\glsnoexpandfields> to the B<.glstex> file. +Don't write C<\glsnoexpandfields> to the F<.glstex> file. =item B<--no-expand-fields> -Write B<\glsnoexpandfields> to the B<.glstex> file (default). +Write C<\glsnoexpandfields> to the F<.glstex> file (default). + +=item B<--provide-glossaries> + +Write C<\provideignoredglossary*> to the F<.glstex> file to provide +unknown glossaries. + +=item B<--no-provide-glossaries> + +Don't write C<\provideignoredglossary*> to the F<.glstex> file to +provide unknown glossaries except in documented situations +(B<master>, B<secondary> and B<trigger-type> resource options). +This setting is the default. + =back @@ -293,7 +306,7 @@ Java 7 or later and a TeX distribution. =head1 LICENSE License GPLv3+: GNU GPL version 3 or later -<http://gnu.org/licenses/gpl.html> +L<http://gnu.org/licenses/gpl.html> This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. @@ -314,7 +327,7 @@ The glossaries manual: =head1 AUTHOR Nicola L. C. Talbot, -L<http://www.dickimaw-books.com/> +L<https://www.dickimaw-books.com/> =cut diff --git a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex index f8fa262b5bf..7b888ea485a 100644 --- a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex +++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex @@ -151,7 +151,7 @@ }, max-loc-diff={2}, see=omit,seealso=omit,alias=omit, - field-aliases={topics=adoptparents}, + field-aliases={topics=adoptparents,annote=user2}, replicate-fields={name=nametitle,progeny=unsortedprogeny}, field-case-change={nametitle=title}, interpret-fields={nametitle}, @@ -296,7 +296,7 @@ \glsxtrnewglslike{idx.}{\idx}{\idxpl}{\Idx}{\Idxpl} \newcommand{\idxlink}[3][]{\glslink[#1]{idx.#2}{#3}} -\newcommand{\stringu}{\idx{cs.string}\idx{u}} +\newcommand{\stringu}{\idx{cs.string}\idx{uhex}} \newcommand*{\filefmt}[1]{\texorpdfstring{\texttt{#1}}{#1}} \newcommand*{\metafilefmt}[3]{% @@ -1080,6 +1080,8 @@ \newcommand*{\atentryref}[1]{\gls[format=glsignore]{entry.#1}} +\newcommand*{\entryref}[1]{\glslink[format=glsignore]{entry.#1}{\entryfmt{#1}}} + \newcommand{\convertglsbibarg}[2][\subsection]{\argsection[#1]{gls2bib.#2}} \newcommand{\argsection}[2][\section]{% @@ -1891,22 +1893,29 @@ Although \idxpl{ignoredglossary} can't be used with \cs{printglossary}, they can be used with \cs{printunsrtglossary}, which is designed to work without any indexing, but you need to explicitly set the title in the optional argument to override the -default. The \idxpl{ignoredglossary} still can't be used in +default. \Idxpl{ignoredglossary} still can't be used in \cs{printunsrtglossaries}, since they're not included in the list that this command iterates over. -So \cs{newignoredglossary} is useful with \bibgls\ if you're happy -to use \cs{printunsrtglossary} as it reduces the overall number of -internal control sequences. Since there is now the possibility of -targets (created within \cs{printunsrtglossary}), it's useful to +So \cs{newignoredglossary} (or \cs{provideignoredglossary}) is +useful with \bibgls\ if you're happy to use \cs{printunsrtglossary} +with the \printglossopt{type} and \printglossopt{title} options as it reduces the overall +number of internal control sequences. \Idxpl{ignoredglossary} are +also useful for stand-alone definitions (\ics{glsxtrglossentry}) or +with \ics{printunsrtinnerglossary} as no title is required in those +cases (see \exfile{sample-nested.tex} for an example). + +Since there is now the possibility of targets (created within \cs{printunsrtglossary} or +\cs{printunsrtinnerglossary} or \cs{glsxtrglossentry}), it's convenient to have an \idx{ignoredglossary} that doesn't suppress the hyperlinks, which can be obtained with the starred form \ics{newignoredglossary*} -provided by \styfmt{glossaries-extra}. +provided by \styfmt{glossaries-extra} (or \cs{provideignoredglossary*}). Some resource options, such as \csopt{master}, \csopt{secondary} and \csopt{trigger-type}, need to ensure that a required glossary is defined. In this case, \bibgls\ uses -\ics{provideignoredglossary*} in the \iext{glstex} file. If you +\ics{provideignoredglossary*} in the \iext{glstex} file +even if \longarg{no-provide-glossaries} is set. If you haven't already defined that glossary in the document with \cs{newglossary*}, you'll need to set the title in the optional argument of \cs{printunsrtglossary} if you don't want the default. The glossary @@ -1915,6 +1924,27 @@ provided in the \ext{glstex} file) but \cs{printunsrtglossary} will just give a warning if the type is undefined so it won't interrupt the document build. +If you want \bibgls\ to automatically provide unknown glossaries for +all entries that have the \field{type} field set (unrelated to the +\csopt{master}, \csopt{secondary} and \csopt{trigger-type} options) +then use the \longarg{provide-glossaries} switch. + +The base \sty{glossaries} package provides a command that can be +used to test the existence of a glossary: +\begin{codeenv} +\ics{ifglossaryexists}\margm{label}\margm{true}\margm{false} +\end{codeenv} +The unstarred version considers ignored glossaries as non-existent +(and so will do \meta{false} for an ignored glossary). As from +v4.46, this command now has a starred version +\ics{ifglossaryexists*} that considers ignored glossaries as +existing (and so will do \meta{true} for an ignored glossary). In +the event that you have an older version of \sty{glossaries}, the +\sty{glossaries-extra} package (v1.44+) will provide the starred +form if it hasn't been defined. (In general, it's best to have +up-to-date versions of both \sty{glossaries} and +\sty{glossaries-extra}.) + \section{Resource Sets} \label{sec:resourcesets} @@ -3785,6 +3815,30 @@ bib2gls --trim-except-fields short --trim-except-fields long myDoc Don't trim any leading or trailing spaces from field values (but see the above note about \sty{xkeyval}). This is the default setting. +\argsection{provide-glossaries} + +This setting will make \bibgls\ add the line +\begin{codeenv} +\ics{provideignoredglossary*}\margm{type} +\end{codeenv} +to the \ext{glstex} file before an entry is defined where that entry +has the \field{type} field set to an unknown glossary type (\bibgls\ +can detect from the \ext{aux} file all glossaries that have been +defined with \cs{newglossary} but not those defined with \cs{newignoredglossary}). + +This ensures that the glossary exists, but the use of +\ics{provideignoredglossary} (rather than \cs{newignoredglossary}) +will prevent an error if the glossary has already been defined. + +\argsection{no-provide-glossaries} + +This setting prevents \bibgls\ from providing unknown glossaries, +except in a few documented situations (the \csopt{master}, +\csopt{trigger-type} and \csopt{secondary} options). This is the +default since it's a useful way of detecting misspelt glossary +labels. It's harder to detect the problem if a misspelt label has +caused an entry to be added to a hidden glossary. + \argsection{record-count} Switch on record counting. This will ensure that when each entry @@ -4441,7 +4495,7 @@ For example: \end{codeenv} If the \field{sort} field is missing the default is obtained from -the \field{name} field (unless overridden by +the \field{name} field (unless overridden by options like \csopt{entry-sort-fallback}). For hierarchical entries, if the \field{name} field is omitted it will be obtained from the parent's \field{name}. @@ -4465,7 +4519,7 @@ designed specifically for symbols, so in the previous example, the The required fields are \field{name} or \field{parent}. The \field{description} field is required if the \field{name} field is missing. If the \field{sort} field is omitted, the default sort is -given by the entry label (unless overridden by +given by the entry label (unless overridden by options like \csopt{symbol-sort-fallback}). Note that this is different from \atentry{entry} where the sort defaults to \field{name} if omitted. @@ -4529,7 +4583,8 @@ entry.) If the name contains any characters that can't be used in the label, you must use the \field{name} field. If the \field{sort} field is missing the default is obtained from the \field{name}. Note that the \atentry{index} entry type is \emph{not} governed by -\csopt{entry-sort-fallback}. This allows \atentry{index} and +\csopt{entry-sort-fallback} (but it is governed by +\csopt{custom-sort-fallbacks}). This allows \atentry{index} and \atentry{entry} to have different fallbacks if the \field{sort} field is missing. @@ -4554,7 +4609,8 @@ field with the plural suffix appended. If the \field{text} field is missing, it's obtained from the original entry label. If the \field{sort} field is missing the default is obtained from the \field{name} field. (As with \atentry{index}, \atentry{indexplural} -is \emph{not} governed by \csopt{entry-sort-fallback}.) +is \emph{not} governed by \csopt{entry-sort-fallback}, but it is +governed by \csopt{custom-sort-fallbacks}.) All fields are optional. For example: \begin{codeenv} \atentry{indexplural}\marg{goose, @@ -7232,6 +7288,21 @@ setting but parents are added even if they haven't been referenced in the document. The other dependent entries are omitted if they haven't been referenced in the document. +\item \optfmt{deps but not recorded}: this first selects entries as +though \optfmt{recorded and deps} had been used, but after all +ancestors and dependencies have been added it then removes all +entries that have records. This means that you end up with only the +unrecorded dependencies. (Recorded entries will need to be selected +in a different resource set.) + +\item \optfmt{ancestors but not recorded}: this first selects +entries as though \optfmt{recorded and ancestors} had been used, but +after all ancestors have been added it then removes all entries that +have records. This means that you end up with only the unrecorded +ancestors. (Recorded entries will need to be selected +in a different resource set.) See the \exfile{sample-nested.tex} +example document. + \item \optfmt{all}: add all entries found in the \ext{bib} files supplied in the \csopt{src} option. \end{itemize} @@ -8197,7 +8268,8 @@ or \csopt{category} options haven't been used, the corresponding value will default to \optfmt{master}. The \catattr{targeturl} and \catattr{targetname} category attributes will automatically be set, and the glossary type will be provided using -\code{\ics{provideignoredglossary*}\margm{type}}. +\code{\ics{provideignoredglossary*}\margm{type}} (even if +\longarg{no-provide-glossaries} is set). The above \filefmt{myarticle.tex} can be changed to: \begin{codeenv} @@ -9110,6 +9182,7 @@ the keywords allowed by \csopt{type}). You can define the glossary before loading the resource, but it's not required as \bibgls\ will write \code{\ics{provideignoredglossary*}\margm{type}} to the \ext{glstex} file +even if \longarg{no-provide-glossaries} is set (see \sectionref{sec:newglossary}). \optsection[\subsubsection]{progenitor-type} @@ -9146,7 +9219,8 @@ missing and it's required for some reason (for example, with fallback on a different field, then you can use this option to specify the field. For example, \csopt[long]{abbreviation-name-fallback}. -The \meta{field} value must be a known field label. +The \meta{field} value must be a known field (not an internal field) +but can't be the \field{sort} field. \optsection[\subsubsection]{ignore-fields} @@ -10064,7 +10138,7 @@ contains definitions like: } \end{codeenv} Instead of having a list of terms (glossary), suppose I want to have -standalone definitions, where the term appears in a section heading. +stand-alone definitions, where the term appears in a section heading. I could define a command like this: \begin{codeenv} \cs{newcommand}\marg{\cmd{definition}}[1]\marg{\comment{} @@ -10232,7 +10306,7 @@ by \csopt{time-fields}. The \meta{value} is as for \csopt{date-sort-locale}. \subsection{Prefix Fields} -\label{sec:prefixes} +\label{sec:prefixfields} If you use the \isty{glossaries-prefix} package, the prefix set of fields become available (\field{prefix}, @@ -12763,15 +12837,20 @@ list that's the exact reverse of the underlying non-reversed can affect the order. \begin{table}[p] -\caption{Summary of Available Sort Options: No Actual Sorting} +\caption{Summary of Available Sort Options: No Sort Field} \label{tab:sortoptionsnosort} \centering \begin{tabular}{ll} \optfmt{none} or \optfmt{unsrt} & don't sort\tabularnewline \optfmt{random} & shuffle entries\tabularnewline \optfmt{use} & order of use\tabularnewline -\optfmt{use-reverse} & reverse order of use +\optfmt{use-reverse} & reverse order of use\tabularnewline +\optfmt{recordcount}\textsuperscript\textdagger & order of record count\tabularnewline +\optfmt{recordcount-reverse}\textsuperscript\textdagger & reverse order of record count \end{tabular} +\par +\medskip +\textsuperscript\textdagger Requires \longarg{record-count} switch. \end{table} \begin{table}[p] @@ -12885,12 +12964,15 @@ sort\tabularnewline \end{tabular} \end{table} -\subsubsection{No Sort} +\subsubsection{No Sort Field} -The sort methods listed in \tableref{tab:sortoptionsnosort} +Most of the sort methods listed in \tableref{tab:sortoptionsnosort} don't actually perform any sorting. This may cause a problem for hierarchical entries. In some cases this can lead to detached child entries or an attempt to define a child entry before its parent. +The methods listed in this section all ignore the \csopt{sort-field} +setting and all the various sort fallback settings, except where +noted below. \begin{itemize} \item \optfmt{none} (or \optfmt{unsrt}): don't sort the entries. @@ -12916,8 +12998,103 @@ first use of that term that's used as the sort value. \item \optfmt{use-reverse}: reverses the order that would be obtained with \csopt[use]{sort} without reference to hierarchy. +\item \optfmt{recordcount}: order of record count (starting from 0). This order is +determined by the total number of records written to the \iext{aux} +file for each entry. Unlike the above methods, this performs a hierarchical sort. +If letter groups are enabled with \longarg{group}, this method will assign the entries to +the \idx{numbergroup}. + +This option requires the \longarg{record-count} switch. Although +that switch makes \bibgls\ write the total record count to the +\ext{glstex} file in the \field{recordcount} internal field (so that it +can be accessed in the document), \bibgls\ doesn't actually have a +field itself that contains the information. So although this option +behaves much like \csopt[integer]{sort} it's not possible to select +a field containing the required value. In the event of two or more +entries having the same record count, the +\csopt{identical-sort-action} option is used to determine the +relative ordering between them. + +\item \optfmt{recordcount-reverse}: reverse order of record count +(ending with 0). All the above notes applying to +\optfmt{recordcount} also apply here. + \end{itemize} +Suppose the file \filefmt{entries.bib} contains +definitions of a set of symbols that don't have any intuitive +ordering (for example, they are all pictographs) then there may be +no point in trying to order them, in which case you can do: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[none]{sort}} +\end{codeenv} +Alternatively, you could list them in order of use: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[use]{sort}} +\end{codeenv} +or by frequency of use. For example, starting with entries that +don't have any records followed by the least used entries (a rarely-used symbol +may be harder to remember and most likely to be looked up in the glossary): +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[recordcount]{sort}} +\end{codeenv} +Or starting with the most used entries: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[recordcount-reverse]{sort}} +\end{codeenv} +It all depends on what's likely to be most useful to the reader. + +Consider the following: +\begin{codeenv} +\ics{newglossary*}\marg{frequent}\marg{Most Frequently Used Terms} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[use]{sort}, + \csopt[recordcount-reverse:frequent]{secondary} +} +\cs{newcommand}\marg{\csfmt{filterhook}}[1]\marg{\comment{} + \ics{GlsXtrIfFieldCmpNum}*\marg{\field{recordcount}}\marg{\idx{hashchar}1}\marg{>}\marg{10}\comment{} + \marg{}\comment{} + \marg{\ics{printunsrtglossaryskipentry}}\comment{} +} +\csfmt{begin}\marg{document} +\cs{printunsrtglossary*}\oarg{\printglossopt[false]{target},\printglossopt[frequent]{type}}\marg{\comment{} + \cs{let}\ics{printunsrtglossaryentryprocesshook}\csfmt{filterhook} +} +\comment{Main body of the document \ldots} +\cs{printunsrtglossary} +\csfmt{end}\marg{document} +\end{codeenv} +This has a summary at the start of the document that only contains +entries that have at least 10 records and is ordered according to +the total number of records (starting with the most frequently used +entry). The main glossary at the end of the document is ordered +according to use and contains all selected entries. + +Compare this with the following: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[use]{sort}} +\cs{newcommand}\marg{\csfmt{filterhook}}[1]\marg{\comment{} + \ics{GlsXtrIfFieldCmpNum}*\marg{\field{recordcount}}\marg{\idx{hashchar}1}\marg{>}\marg{10}\comment{} + \marg{}\comment{} + \marg{\ics{printunsrtglossaryskipentry}}\comment{} +} +\csfmt{begin}\marg{document} +\cs{printunsrtglossary*}\oarg{\printglossopt[false]{target}, + \printglossopt[Most Frequently Used Terms]{title}}\marg{\comment{} + \cs{let}\ics{printunsrtglossaryentryprocesshook}\csfmt{filterhook} +} +\comment{Main body of the document \ldots} +\cs{printunsrtglossary} +\csfmt{end}\marg{document} +\end{codeenv} +This again has a summary at the start of the document that only +contains entries that have at least 10 records but is now ordered +according to use. + +Both examples assume there are no child entries as the filtering can +cause parent entries to be omitted. Both examples require +\longarg{record-count} but only the first example sorts according to +the record count. + \subsubsection{Alphabet} The sort methods listed in \tableref{tab:sortoptionsrule} are for @@ -12936,7 +13113,7 @@ given by the \idx{IETF} language tag \meta{lang tag}. \item \optfmt{locale}: equivalent to \csopt[\meta{lang tag}]{sort} where \meta{lang tag} is obtained -from the \idx{JRE} (which usually matches the +from the \idx{JRE}['s] default locale (which usually matches the operating system's locale). \item \optfmt{locale-reverse}: equivalent to @@ -13382,7 +13559,7 @@ results in the order: \code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}}, \code{C\textsubscript{5}H\textsubscript{4}NCOOH}. -Remember that the associated settings are reversed +Remember that the associated settings are reversed as well. So \csopt[before letter]{letter-number-rule} results in numbers \emph{after} letters. @@ -13478,7 +13655,7 @@ decimal sort values. \item \optfmt{double}: double-precision sort. This is for non-locale decimal sort values. -\item \optfmt{float-reverse}: as above but reverses the order. +\item \optfmt{double-reverse}: as above but reverses the order. \item \optfmt{numeric}: locale-sensitive numeric sort. Use \csopt{numeric-locale} to set the locale. @@ -13638,13 +13815,20 @@ Example: \begin{codeenv} \gls{GlsXtrLoadResources}\oarg{ \csopt[entries-terms]{src},\comment{data in entries-terms.bib} - \csopt[category]{sort-field},\comment{sort by 'category' field} + \csopt[symbol]{sort-field},\comment{sort by 'symbol' field} \csopt[letter-case]{sort}\comment{case-sensitive letter sort} } \end{codeenv} -This sorts the entries according to the \field{category} field using +This sorts the entries according to the \field{symbol} field using a case-sensitive letter comparison. +\begin{important} +In general it's better to use the default \csopt[sort]{sort-field} +and adjust the fallbacks instead. The \csopt{sort-field} option is +provided if you want to use a specific field regardless of the entry +type. +\end{important} + If an entry is missing a value for \meta{field}, then the value of the fallback field will be used instead. If \csopt{missing-sort-fallback} is set, then that's used as the fallback, otherwise it depends on the @@ -13656,6 +13840,11 @@ setting, the fallback for the \field{sort} field is governed not only by the entry type but also by some associated settings: \begin{itemize} +\item If the entry's original type (before being aliased with +\csopt{entry-type-aliases}) is identified in +\csopt{custom-sort-fallbacks}, then if the \field{sort} field is missing +the value is obtained from the supplied custom mapping. + \item If the entry is defined using \atentry{entry} (or a dual form that acts like \atentry{entry}), then if the \field{sort} field is missing the value is obtained from the field identified by @@ -13698,9 +13887,21 @@ follows: \meta{fallback-field}. If \meta{fallback-field} is missing, then \bibgls\ will query the entry type's fallback for \meta{fallback-field} (not for \meta{sort-field}). + +The \meta{fallback-field} must be a known field but not an internal +field. It can't be the \field{sort} field. (Take care not to cause +an infinite loop if \csopt{sort-field} has been changed.) Unlike the +other sort fallback options such as \csopt{entry-sort-fallback}, the +\meta{fallback-field} can't be a keyword (to identify the label) and can't be a +composite. + \item If the entry type has a fallback rule for \meta{sort-field}, then that rule is used. When \csopt[sort]{sort-field} this means: \begin{itemize} +\item If the entry's original entry type has been identified in +\csopt{custom-sort-fallbacks}, then \bibgls\ will fallback on the +designated custom setting. + \item If the entry was defined using one of the index types (such as \atentry{index}), then \bibgls\ will fallback on the \field{name} field. @@ -13736,6 +13937,121 @@ separately from primaries, and use \csopt{secondary-missing-sort-fallback} for \csopt{secondary} sorting. +\optsection{custom-sort-fallbacks} + +The value should be a \keyvallist\ in the form +\meta{entrytype}\dequals\meta{field} where \meta{entrytype} is the +\emph{original} entry type (before being aliased with +\csopt{entry-type-aliases}). This will override any of the sort fallback +options listed below for entries whose original entry type matches +\meta{entrytype}. + +The \meta{field} may be a known field but not an internal field. For +obvious reasons, it can't be the \field{sort} field (since +\meta{field} is the fallback a missing \field{sort} field). It may also be one of the +keywords: \optfmt{id} (for the entry's label) or \optfmt{original id} +(for the entry's original label). The \meta{field} may also be a +composite in the form \optfmt{\meta{field1}+\meta{field2}+\ldots} +which indicates that the sort value should be obtained by +concatenating the values of the given fields, where the separator is +given by \csopt{field-concat-sep}. + +For example, if the \ext{bib} file contains: +\begin{codeenv} +\atentryfmt{unit}\marg{ohm, + \field{name}=\marg{\cs{si}\marg{\csfmt{ohm}}}, + \field{description}=\marg{electrical resistance} +} +\strut +\atentryfmt{constant}\marg{pi, + \field{name}=\marg{\cs{ensuremath}\marg{\cs{pi}}}, + \field{description}=\marg{the ratio of the length of the circumference + of a circle to its diameter}, + \field{user1}=\marg{3.14159} +} +\strut +\atentry{symbol}\marg{fx, + \field{name}=\marg{\cs{ensuremath}\marg{f(x)}}, + \field{description}=\marg{a function of \idx{mshiftchar}x\idx{mshiftchar}} +} +\strut +\atentry{number}\marg{zero, + \field{name}=\marg{0}, + \field{description}=\marg{nothing or no quantity} +} +\end{codeenv} +Then the resource options: +\begin{codeenv} +\csopt[\entryfmt{unit}=\entryref{symbol},\entryfmt{constant}=\entryref{number}]{entry-type-aliases}, +\csopt[\entryfmt{unit}=\field{name},\entryfmt{constant}=\field{user1}]{custom-sort-fallbacks} +\end{codeenv} +will treat the custom \atentryfmt{unit} and \atentryfmt{constant} +entries as though they had been defined with \atentry{symbol} +and \atentry{number}, respectively, but the fallback for the +\field{sort} field is different: the \code{ohm} entry will use the +\field{name} field for the sort fallback (because its original entry +type was \entryfmt{unit}), the \code{pi} entry will use the +\field{user1} field for the sort fallback (because its original +entry type was \entryfmt{constant}) and the \code{fx} and +\code{zero} entries will use the label for the sort fallback (since +neither \entryfmt{symbol} nor \entryfmt{number} were identified in +\csopt{custom-sort-fallbacks} so the \csopt{symbol-sort-fallback} is +used). + +If an entry hasn't had its entry type aliased then \meta{entrytype} +is its actual entry type. For example, consider the following +definitions: +\begin{codeenv} +\atentry{abbreviation}\marg{svm, + \field{short}=\marg{SVM}, + \field{long}=\marg{support vector machine} +} +\atentry{acronym}\marg{laser, + \field{short}=\marg{laser}, + \field{long}=\marg{light amplification by stimulated emission of radiation} +} +\end{codeenv} +Then \csopt[short]{abbreviation-sort-fallback} will make both +entries fallback on the \field{short} field (since +\csopt{abbreviation-sort-fallback} applies to both \atentry{acronym} +and \atentry{abbreviation}), but the option: +\begin{codeenv} +\csopt[\entryref{abbreviation}=\field{long},\entryref{acronym}=\field{short}]{custom-sort-fallbacks} +\end{codeenv} +will make the entry defined with \atentry{abbreviation} fallback on +the \field{long} field and the entry defined with \atentry{acronym} +will fallback on the \field{short} field. + +Since the default setting is \csopt[short]{abbreviation-sort-fallback} +this only needs to be: +\begin{codeenv} +\csopt[\entryref{abbreviation}=\field{long}]{custom-sort-fallbacks} +\end{codeenv} +In this case, the entry defined with \atentry{abbreviation} (\qt{SVM}) will use +the setting given in \csopt{custom-sort-fallbacks}, but the entry +defined with \atentry{acronym} (\qt{laser}) will use the setting given by +\csopt{abbreviation-sort-fallback} since \atentry{acronym} hasn't +been identified in \csopt{custom-sort-fallbacks}. + +This option also covers dual entries. For example: +\begin{codeenv} +\csopt[ + \entryref{dualindexnumber}=\field{description}, + \entryfmt{dualindexnumbersecondary}=\field{user1} +]{custom-sort-fallbacks} +\end{codeenv} +Note that the entry type for the dual is in the form +\code{\meta{primary entry type}secondary}. + +\begin{important} +The \csopt{custom-sort-fallbacks} setting is only used when \bibgls\ +tries to access the \field{sort} field for an entry (whose original +entry type has been identified in this setting) and finds that the field +hasn't been set. This means that this setting has no effect if you +explicitly set the \field{sort} field or if you change the field +used for sorting (\csopt{sort-field}). +\end{important} + \optsection{entry-sort-fallback} The regular entry types (such as \atentry{entry} and @@ -13744,7 +14060,17 @@ field if the \field{sort} field is missing (assuming \csopt[sort]{sort-field}). If you prefer to fallback on a different field, then you can use this option to specify the field. -Note that \csopt{missing-sort-fallback} overrides this setting. +Note that \csopt{missing-sort-fallback} and +\csopt{custom-sort-fallbacks} override this setting. + +The \meta{field} may be a known field but not an internal +field. It can't be the \field{sort} field. It may also be +one of the keywords: \optfmt{id} (for the entry's label) or +\optfmt{original id} (for the entry's original label). The +\meta{field} may also be a composite in the form +\optfmt{\meta{field1}+\meta{field2}+\ldots} which indicates that the +sort value should be obtained by concatenating the values of given fields, +where the separator is given by \csopt{field-concat-sep}. This setting doesn't affect the index type of entries, such as \atentry{index} or \atentry{indexplural}. This is useful if your @@ -13761,7 +14087,7 @@ my file \filefmt{entries.bib} contains: \strut \atentry{entry}\marg{glossarylist, \field{parent}=\marg{glossary}, - \field{description}={list of technical words} + \field{description}=\marg{list of technical words} } \strut \atentry{entry}\marg{glosscol, @@ -13842,9 +14168,19 @@ specify the field. For example, \csopt[long]{abbreviation-sort-fallback}. Note that if you use \csopt[name]{sort-field}, then the fallback field will be given by \csopt{abbreviation-name-fallback} if the \field{name} field is -omitted. The \meta{field} value must be a known field label. +omitted. -Note that \csopt{missing-sort-fallback} overrides this setting. +The \meta{field} may be a known field but not an internal +field. It can't be the \field{sort} field. It may also be +one of the keywords: \optfmt{id} (for the entry's label) or +\optfmt{original id} (for the entry's original label). The +\meta{field} may also be a composite in the form +\optfmt{\meta{field1}+\meta{field2}+\ldots} which indicates that the +sort value should be obtained by concatenating the values of given fields, +where the separator is given by \csopt{field-concat-sep}. + +Note that \csopt{missing-sort-fallback} and +\csopt{custom-sort-fallbacks} override this setting. \begin{important} The \csopt{abbreviation-sort-fallback} setting is only used when \bibgls\ @@ -13857,14 +14193,23 @@ for sorting (\csopt{sort-field}). \optsection{symbol-sort-fallback} The entry types that define symbols (such as \atentry{symbol} and -\atentry{number}) will, by default, fallback on the label if the +\atentry{number}) will, by default, fallback on the entry's original label if the \field{sort} field is missing (assuming the default \csopt[sort]{sort-field}). If you prefer to fallback on a different field, then you can use this option to specify the field. For -example, \csopt[name]{symbol-sort-fallback}. The \meta{field} value -must be a known field label. +example, \csopt[name]{symbol-sort-fallback}. + +The \meta{field} may be a known field but not an internal +field. It can't be the \field{sort} field. It may also be +one of the keywords: \optfmt{id} (for the entry's label) or +\optfmt{original id} (for the entry's original label). The +\meta{field} may also be a composite in the form +\optfmt{\meta{field1}+\meta{field2}+\ldots} which indicates that the +sort value should be obtained by concatenating the values of given fields, +where the separator is given by \csopt{field-concat-sep}. -Note that \csopt{missing-sort-fallback} overrides this setting. +Note that \csopt{missing-sort-fallback} and +\csopt{custom-sort-fallbacks} override this setting. \begin{important} The \csopt{symbol-sort-fallback} setting is only used when \bibgls\ @@ -13882,7 +14227,17 @@ fallback on the \field{name} if the \csopt[sort]{sort-field}). If you prefer to fallback on a different field, then you can use this option to specify the field. -Note that \csopt{missing-sort-fallback} overrides this setting. +The \meta{field} may be a known field but not an internal +field. It can't be the \field{sort} field. It may also be +one of the keywords: \optfmt{id} (for the entry's label) or +\optfmt{original id} (for the entry's original label). The +\meta{field} may also be a composite in the form +\optfmt{\meta{field1}+\meta{field2}+\ldots} which indicates that the +sort value should be obtained by concatenating the values of given fields, +where the separator is given by \csopt{field-concat-sep}. + +Note that \csopt{missing-sort-fallback} and +\csopt{custom-sort-fallbacks} override this setting. \begin{important} The \csopt{bibtexentry-sort-fallback} setting is only used when @@ -13893,6 +14248,60 @@ explicitly set the \field{sort} field or if you change the field used for sorting (\csopt{sort-field}). \end{important} +\optsection{field-concat-sep} + +This option sets the field concatenation separator to \meta{value}. +The default is a space. An empty value indicates no separator. You +may use \ics{uhex}\meta{hex} to indicate a character by its hexadecimal +code. For example, suppose the \ext{bib} file contains: +\begin{codeenv} +\atentry{abbreviation}\marg{ac, + \field{short}=\marg{AC}, + \field{long}=\marg{alternating current} +} +\atentry{index}\marg{acacia} +\end{codeenv} +Then the resource option: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[letter-nocase]{sort}, + \csopt[\field{short}+\field{long}]{abbreviation-sort-fallback} +} +\end{codeenv} +will set the \code{ac} sort value to \qt{AC alternating current}. +That is, the \field{short} value concatenated with the \field{long} +value using the default space separator. With the +\optfmt{letter-nocase} sort method, this will put the \code{ac} +entry before the \code{acacia} entry (because the space character +comes before \qt{a}). + +If the resource options are changed to: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[letter-nocase]{sort}, + \csopt[\empty]{field-concat-sep}, + \csopt[\field{short}+\field{long}]{abbreviation-sort-fallback} +} +\end{codeenv} +This will obtain the sort value for abbreviations from a +concatenation of the \meta{short} and \meta{long} values without a +separator. This means that the \code{ac} sort value will be +\qt{ACalternating current} and so the \code{ac} entry will +come after the \code{acacia} entry (since \qt{l} comes after \qt{c}). + +This setting is only used for the sort fallback options that allow +field concatenation (such as \csopt{entry-sort-fallback} but not +\csopt{missing-sort-fallback}). + +Note that due to the way that the \keyvallist\ parser trims leading and +trailing spaces, you can't simply do \csopt[\space]{field-concat-sep} +to indicate a space character as the value will end up as an empty +string. You can instead do \csopt[\stringu20]{field-concat-sep} but +since this is the default value there shouldn't be much need for it. + +Remember that the separator may be replaced with a break point +marker depending on the sort method and \csopt{break-at} setting. + \optsection{trim-sort} If the interpreter is used to determine the sort value, this setting @@ -15040,7 +15449,8 @@ in the secondary glossary will be the same as for the primary glossary. (If the glossary \meta{type} doesn't exist, it will be -defined with \ics{provideignoredglossary*}\margm{type}.) +defined with \ics{provideignoredglossary*}\margm{type} +even if \longarg{no-provide-glossaries} is set.) Note that if the glossary already exists and contains entries, the existing entries aren't re-ordered. The new entries are simply appended to the list. @@ -19777,6 +20187,251 @@ The \exfile{topics.bib} file contains entries defined using The contents of \filefmt{topics.bib} are as follows: \lstinputlisting[firstline=5]{../examples/topics.bib} +\filesection{sample-hierarchical.tex} + +This example uses the \exfile{terms.bib}, \exfile{animals.bib}, +\exfile{minerals.bib} and \exfile{vegetables.bib} files to create a +hierarchical glossary. These are specified with the resource option: +\begin{codeenv} +\csopt[{terms,animals,minerals,vegetables}]{src} +\end{codeenv} +The custom \fieldfmt{identifier} field is +aliased to the \field{parent} field since it conveniently matches +the labels of the animal, mineral and vegetable entries in the +\exfile{terms.bib} file: +\begin{codeenv} +\csopt[{identifier=parent}]{field-aliases} +\end{codeenv} +The default \csopt{selection} setting means that only those terms +referenced in the document and their dependencies are selected. The +referenced entries simply have \qt{1} in the \idx{locationlist} as +it's only a trivial single-paged example. + +The dependencies that haven't actually been referenced in the +document don't have a \idx{locationlist}. (The \qt{seal} entry is a +dependency, but it's also been referenced in the document, so it has a +\idx{locationlist}.) The \qt{quartz}, \qt{beryl} and \qt{marrow} +entries are dependencies because they occur in the description of +some of the referenced entries. Normally this would mean that they +have no \idx{locationlist} after the first \LaTeX+\bibgls+\LaTeX\ +build but once the glossary has been created the references to those +dependent entries in the descriptions will create records and so on +the next \bibgls+\LaTeX\ they will also have \idxpl{locationlist}. +This would make the complete document build: +\begin{verbatim} +pdflatex sample-hierarchical +bib2gls --group sample-hierarchical +pdflatex sample-hierarchical +bib2gls --group sample-hierarchical +pdflatex sample-hierarchical +\end{verbatim} +However, in this example I've decided to ignore any records created +in the glossary: +\begin{codeenv} +\ics{GlsXtrSetDefaultNumberFormat}\marg{\encap{glsignore}} +\end{codeenv} +This means that the document build is the usual \LaTeX+\bibgls+\LaTeX. + +I've used the \glostyle{treegroup} style so I need to invoke +\bibgls\ with the \longarg{group} switch. This creates letter groups +for the top-level entries. Note that sub-entries never have letter groups. + +The complete code is listed below. The document build is: +\begin{verbatim} +pdflatex sample-hierarchical +bib2gls --group sample-hierarchical +pdflatex sample-hierarchical +\end{verbatim} +The complete document is shown in \figureref{fig:sample-hierarchical.pdf}. + +\lstinputlisting[firstline=5]{../examples/sample-hierarchical.tex} + +\begin{figure} +\figcontents +{% + \frame{\includegraphics[height=.9\textheight]{../examples/sample-hierarchical.pdf}}% +} +{\caption{\filefmt{sample-hierarchical.pdf}}} +{fig:sample-hierarchical.pdf} +\end{figure} + +\filesection{sample-nested.tex} + +As discussed in \sectionref{sec:logicaldivisions} there are three +ways of creating logical divisions when displaying the entries +through the use of the \field{type}, \field{group} and \field{parent} fields. +In general, hierarchical glossaries are created with +the \field{parent} field and an appropriate glossary style (as in +the previous \exfile{sample-hierarchical.tex} example). + +This example creates a hierarchical effect but the entries don't +actually have a hierarchical structure as none of them have the +\field{parent} field set. Instead, what were the child entries in +\exfile{sample-hierarchical.tex} now have the \field{type} field +set. The hierarchical effect is achieved with +\ics{printunsrtinnerglossary} (which requires at least +\sty{glossaries-extra} v1.44). + +\begin{important} +The \ics{printunsrtinnerglossary} command is unsuitable for use +with tabular-like styles, such as \glostyle{long}, and can be +problematic with \glostyle{list} styles. However, those styles +aren't suitable for hierarchical glossaries anyway. +\end{important} + +Normally, hierarchy is achieve through definitions like: +\begin{codeenv} +\atentry{index}\marg{animal} +\atentry{entry}\marg{duck,\field{name}=\marg{duck}, + \field{description}=\marg{a waterbird with webbed feet}, + \field{parent}=\marg{animal} +} +\end{codeenv} +The previous example did this by loading both the \exfile{terms.bib} +and \exfile{animals.bib} files and aliasing the custom +\fieldfmt{identifier} field to \field{parent}. In this example, the +custom field is aliased to \field{type}, which effectively makes the +definitions behave like: +\begin{codeenv} +\atentry{index}\marg{animal} +\atentry{entry}\marg{duck,\field{name}=\marg{duck}, + \field{description}=\marg{a waterbird with webbed feet}, + \field{type}=\marg{animal} +} +\end{codeenv} +The aim here is for the \code{animal} entry to be placed in the main +glossary so that it's listed with \cs{printunsrtglossary}. The +\code{duck} entry is placed in a glossary that has a label +(\code{animal}) that matches the label of the \qt{parent} entry +(even though it's technically not a parent). This new glossary +(\code{animal}) can be automatically defined by invoking \bibgls\ +with the \longarg{provide-glossaries} switch. + +This example document defines a custom handler function that +will do the current entry as normal (with \cs{glsxtrunsrtdo}) but +will then check for the existence of a glossary that has the same +label as the current entry. This requires the starred version of +\ics{ifglossaryexists} to included ignored glossaries in the +existence check. If the glossary exists, it's then displayed using +\ics{printunsrtinnerglossary}: +\begin{codeenv} +\cs{newcommand}\marg{\csfmt{nestedhandler}}[1]\marg{\comment{} + \cs{glsxtrunsrtdo}\marg{\idx{hashchar}1}\comment{} + \ics{ifglossaryexists*}\marg{\idx{hashchar}1}\comment{} + \marg{\comment{} + \cs{printunsrtinnerglossary}\oarg{\printglossopt[\idx{hashchar}1]{type},\printglossopt[++1]{leveloffset},\printglossopt[false]{groups}} + \marg{}\marg{}\comment{} + }\comment{} + \marg{}\comment{} +} +\end{codeenv} +The \printglossopt{leveloffset} option is required to achieve a +hierarchical effect (provided the glossary style supports it) and +the \printglossopt[false]{groups} option is needed to prevent letter +groups showing for the nested glossary, which would otherwise create +a strange effect. (This example uses the \glostyle{treegroup} style, +which provides a hierarchical glossary with letter groups.) + +The \cs{printunsrtglossary} handler macro then needs to be set to +this custom macro when the main glossary is displayed: +\begin{codeenv} +\cs{printunsrtglossary*}\marg{\cs{let}\cs{printunsrtglossaryhandler}\csfmt{nestedhandler}} +\end{codeenv} +The main difficulty comes with ensuring that all the necessary +entries are selected. Now that the custom \fieldfmt{identifier} +field has been aliased to \field{type} rather than \field{parent}, +the \code{animal} entry is no longer considered a dependent. The +\code{duck} entry has been referenced in the document with \cs{gls} +but the \code{animal} entry hasn't. The previous example ensured +that the \code{animal} entry was selected because it was a parent of +a selected entry. If the same resource options are used in this +example, the main glossary will be empty, which means that the +nested glossaries won't be displayed either. + +One way to ensure that the \code{animal}, \code{mineral} and +\code{vegetable} entries are selected is to identify the \field{type} +field as a dependency field: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[{terms,animals,minerals,vegetables}]{src}, + \csopt[{identifier=type}]{field-aliases}, + \csopt[{type}]{dependency-fields} +} +\end{codeenv} +This will achieve the same effect as the +\exfile{sample-hierarchical.tex} document, but it's a far more +convoluted method. The reason this example document is listed here +is to demonstrate a sightly modified hierarchical effect that can't +be achieved through the normal method. + +Suppose that, for some strange reason, I want the \qt{animal}, +\qt{mineral} and \qt{vegetable} entries to be listed in a different +order (say, reverse alphabetical). The other entries (\qt{duck} etc) +need to be sorted in normal alphabetical order. + +The \csopt{sort} option applies the same sort method to all +hierarchical levels. The sort \emph{value} chosen for particular entries +can be altered through the use of fallbacks (such as the +\csopt{entry-sort-fallback} or \csopt{symbol-sort-fallback} options) +and a letter comparator may be used to resolve identical sort +values (\csopt{identical-sort-action}), but the same sort algorithm +is applied to all entries in the same set (primary, secondary or dual +within the same resource set). The only way to apply different sort +methods is to separate the entries into different resource sets (or +use dual or secondary sorting). + +This can be achieved by having one resource set for the main entries +with one sort method and another resource set for all the other +entries with a different sort method: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[terms]{src},\csopt[en-reverse]{sort}} + +\gls{GlsXtrLoadResources}\oarg{\csopt[animals,minerals,vegetables]{src},\csopt[en]{sort}, + \csopt[{identifier=type}]{field-aliases},\csopt[{type}]{dependency-fields} +} +\end{codeenv} +This works when cross-resource dependencies are permitted (see +\sectionref{sec:resourcesets}). In the event that cross-resource +dependencies aren't permitted, the selection criteria is more +complicated: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[terms,animals,minerals,vegetables]{src}, + \csopt[en-reverse]{sort}, + \csopt[{identifier=parent}]{field-aliases}, + \csopt[ancestors but not recorded]{selection} +} + +\gls{GlsXtrLoadResources}\oarg{ + \csopt[animals,minerals,vegetables]{src}, + \csopt[{identifier=type}]{field-aliases}, + \csopt[{type}]{dependency-fields} + \csopt[en]{sort} +} +\end{codeenv} +Fortunately in this example, cross-resource dependencies are +permitted so the simpler alternative works. (If they're not +permitted, the \bibgls\ transcript file will contain +\qt{Cross-resource references can't be supported for resource set +\meta{filename}}.) + +The complete code is listed below. The document build is: +\begin{verbatim} +pdflatex sample-nested +bib2gls --group --provide-glossaries sample-nested +pdflatex sample-nested +\end{verbatim} +The complete document is shown in \figureref{fig:sample-nested.pdf}. + +\lstinputlisting[firstline=5]{../examples/sample-nested.tex} + +\begin{figure} +\figcontents +{% + \frame{\includegraphics[height=.9\textheight]{../examples/sample-nested.pdf}}% +} +{\caption{\filefmt{sample-nested.pdf}}} +{fig:sample-nested.pdf} +\end{figure} + \filesection{sample-constants.tex} This example uses the \exfile{constants.bib} file. The aim here @@ -23145,6 +23800,9 @@ The resulting document is shown in \figureref{fig:sample-multi2.pdf}, }% } \renewcommand*{\unicodecategoryfmt}[1]{\textsf{#1}} -\renewcommand*{\bibglspassim}{} +\glsrenewcommand*{\bibglspassim}{} +\newcommand{\glsxtrpostnamecommand}{% + \glsxtrifhasfield{userii}{\glscurrententrylabel}{ (\glscurrentfieldvalue)}{}% +} \printunsrtglossary[type=index] \end{document} diff --git a/Master/texmf-dist/source/support/bib2gls/src/gls2bib-src.zip b/Master/texmf-dist/source/support/bib2gls/src/gls2bib-src.zip Binary files differindex ec9be43bf55..6b26a7c7a37 100644 --- a/Master/texmf-dist/source/support/bib2gls/src/gls2bib-src.zip +++ b/Master/texmf-dist/source/support/bib2gls/src/gls2bib-src.zip diff --git a/Master/texmf-dist/source/support/bib2gls/src/texparser-src.zip b/Master/texmf-dist/source/support/bib2gls/src/texparser-src.zip Binary files differindex 1718e13e127..5af125b78b5 100644 --- a/Master/texmf-dist/source/support/bib2gls/src/texparser-src.zip +++ b/Master/texmf-dist/source/support/bib2gls/src/texparser-src.zip |