summaryrefslogtreecommitdiff
path: root/support/bib2gls/src/bib2gls.tex
diff options
context:
space:
mode:
Diffstat (limited to 'support/bib2gls/src/bib2gls.tex')
-rw-r--r--support/bib2gls/src/bib2gls.tex841
1 files changed, 721 insertions, 120 deletions
diff --git a/support/bib2gls/src/bib2gls.tex b/support/bib2gls/src/bib2gls.tex
index f7ba9c27ef..f8fa262b5b 100644
--- a/support/bib2gls/src/bib2gls.tex
+++ b/support/bib2gls/src/bib2gls.tex
@@ -51,6 +51,7 @@
entrycounter,% enable entry counting
subentrycounter,% enable entry counting
%debug=showtargets,% debugging information
+ %debug=showwrgloss,% debugging information
stylemods={mcols,bookindex},% adjust predefined styles and load glossary-mcols.sty and glossary-bookindex.sty
style=bookindex
]
@@ -92,8 +93,8 @@
\newcommand{\bibglsseealsosep}{\glstreesubitem}
-\renewcommand*{\glsseesep}{, \glstreesubitem\qquad}
-\renewcommand*{\glsseelastsep}{\glstreesubitem\qquad\andname\space}
+\renewcommand*{\glsseesep}{, \glstreesubitem\quad}
+\renewcommand*{\glsseelastsep}{\glstreesubitem\quad\strut\llap{\andname\space}}
\newcommand{\glsxtrpostnameabbreviation}{%
\space(\glsentrylong{\glscurrententrylabel})%
@@ -125,6 +126,11 @@
\glsxtrprovidestoragekey{unsortedprogeny}{}{}
+\newcommand*{\longargfmt}[1]{%
+ \texorpdfstring{\texttt{\longswitch #1}}%
+ {\string-\string-#1}%
+}
+
\GlsXtrLoadResources[
entry-type-aliases={
bibglscommand=dualindexentry,
@@ -143,6 +149,8 @@
exampleabbreviation=abbreviation,
exampleentry=entry
},
+ max-loc-diff={2},
+ see=omit,seealso=omit,alias=omit,
field-aliases={topics=adoptparents},
replicate-fields={name=nametitle,progeny=unsortedprogeny},
field-case-change={nametitle=title},
@@ -170,7 +178,7 @@
dual-prefix={},
dual-type={main},
combine-dual-locations={primary},
- selection={recorded and deps and see},
+ selection={recorded and deps and see not also},
symbol-sort-fallback={name},
sort-label-list={progeny:letter-nocase:glsxtrentryparentname},
strip-missing-parents,
@@ -294,6 +302,10 @@
\newcommand*{\metafilefmt}[3]{%
\filefmt{#1}\discretionary{}{}{}\meta{#2}\discretionary{}{}{}\filefmt{#3}%
}
+\newcommand*{\metametafilefmt}[5]{%
+ \filefmt{#1}\discretionary{}{}{}\meta{#2}\discretionary{}{}{}\filefmt{#3}%
+ \discretionary{}{}{}\meta{#4}\discretionary{}{}{}\filefmt{#5}%
+}
\newcommand*{\primaryresourcefmt}{%
\texorpdfstring
@@ -1011,7 +1023,7 @@
\item \glstarget{##1}{\strut}%
\glsxtrifhasfield{dualid}{##1}%
{%
- \glshyperlink{\glscurrentfieldvalue}%
+ \gls{\glscurrentfieldvalue}%
}%
{%
\gls[hyper=false]{##1}%
@@ -1068,6 +1080,8 @@
\newcommand*{\atentryref}[1]{\gls[format=glsignore]{entry.#1}}
+\newcommand{\convertglsbibarg}[2][\subsection]{\argsection[#1]{gls2bib.#2}}
+
\newcommand{\argsection}[2][\section]{%
\def\switcharg{}%
\def\switchalt{}%
@@ -1093,11 +1107,6 @@
\newrobustcmd{\longswitch}{\string-{}\string-}
-\newcommand*{\longargfmt}[1]{%
- \texorpdfstring{\texttt{\longswitch #1}}%
- {\string-\string-#1}%
-}
-
\newcommand*{\shortargfmt}[1]{%
\texorpdfstring{\texttt{\string-#1}}%
{\string-#1}%
@@ -1109,6 +1118,12 @@
{\string-\string-#1}%
}
+\newcommand*{\convertglsbiblongarg}[1]{%
+ \texorpdfstring
+ {\gls{switch.gls2bib.#1}}%
+ {\string-\string-#1}%
+}
+
\newcommand*{\longargpageref}[1]{%
\longarg{#1} (page~\glsxtrpageref{switch.#1})}%
@@ -1248,20 +1263,22 @@ files}
\newenvironment{codeenv}
{%
+ \GlsXtrStartUnsetBuffering
\renewcommand{\glslinkpresetkeys}{\setkeys{glslink}{noindex}}%
\setupcodeenvfmts
\begin{flushleft}\ttfamily\obeylines\frenchspacing\@vobeyspaces
\parindent\z@\parfillskip\@flushglue\parskip\z@skip
}
- {\end{flushleft}\ignorespacesafterend}
+ {\end{flushleft}\GlsXtrDiscardUnsetBuffering\ignorespacesafterend}
\newenvironment{codeenv*}
{%
+ \GlsXtrStartUnsetBuffering
\setupcodeenvfmts
\begin{flushleft}\ttfamily\obeylines\frenchspacing\@vobeyspaces
\parindent\z@\parfillskip\@flushglue\parskip\z@skip
}
- {\end{flushleft}\ignorespacesafterend}
+ {\end{flushleft}\GlsXtrDiscardUnsetBuffering\ignorespacesafterend}
\begingroup
\renewcommand{\addr}[1]{}
@@ -1299,7 +1316,7 @@ required by not defining unnecessary commands.
Since \bibgls\ can also sort and collate the recorded locations
present in the \ext{aux} file, it can simultaneously by-pass the
-need to use \idx{makeindex} or \idx{xindy}, although \bibgls\
+need to use \idx!{makeindex} or \idx!{xindy}, although \bibgls\
can be used together with an external indexing application if required. (For
example, if a custom \idx{xindy} rule is needed.)
@@ -1327,7 +1344,7 @@ to convert the entries to the \ext{bib} format required by
\bibgls. See \sectionref{sec:gls2bib} for further details.
The supplementary file \introguide\ is an
-introductory guide to the \sty{glossaries-extra} package, which you
+introductory guide to the \isty{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}
@@ -1414,7 +1431,7 @@ example, the file \filefmt{entries.bib} might contain:
}
\strut
\atentry{symbol}\marg{v,
- \field{name}=\marg{\idx{mshiftchar}\cs{vec}\marg{v}\idx{mshiftchar}},
+ \field{name}=\marg{\idx!{mshiftchar}\cs{vec}\marg{v}\idx!{mshiftchar}},
\field{text}=\marg{\cs{vec}\marg{v}},
\field{description}=\marg{a vector}
}
@@ -2012,7 +2029,9 @@ the corresponding set of \ext{bib} files:
\item any fields that have been identified with
\csopt{interpret-fields} are replaced with their interpreted
- values.
+ values;
+
+ \item check for \field{nonumberlist}.
\end{itemize}
\item The dual version (if appropriate) is created.
\item Records are added to the entry's location list (or transferred
@@ -2112,8 +2131,8 @@ been recorded because $B$ hasn't been recorded and is in a different
\idx{resourceset}.
If the \idx{crossresourceref} mode is enabled then stage~3 and
-stage~4 are processed in separate loops, otherwise they are
-processed in the same loop.
+stage~4 are processed in separate \idxpl{loop}, otherwise they are
+processed in the same \idx{loop}.
\section{Indexing}
@@ -2442,7 +2461,7 @@ the library will still be used to parse the \ext{aux} and \ext{bib}
files. Note that the \field{see} field doesn't use the interpreter
with \csopt[true]{interpret-label-fields} as
it may legitimately contain \LaTeX\ code in the optional tag part
-(such as \cs{seealsoname}).
+(such as \cs{seealsoname} or \cs{alsoname}).
The parser has a different concept of expansion to \TeX\
and will expand some things that aren't expanded by \LaTeX\
@@ -2452,7 +2471,7 @@ in terms of complicated internals).
If you get a \idx{StackOverflowError} while a field is being
interpreted (with a long stack trace that contains repeated file names and
-line numbers) then it's likely you have an infinite loop. For
+line numbers) then it's likely you have an infinite \idx{loop}. For
example, this can be triggered if a field contains \csfmt{foo} that
has been defined as:
\begin{codeenv}
@@ -2543,7 +2562,7 @@ rule that recognises these Unicode characters (for example,
complicated for simple \idxpl!{regex}. The \TeX\ parser library performs
better than a simple pattern match, and that's the purpose of
\file{texparserlib.jar} and why it's used by \bibgls\ (and by
-\idx{convertgls2bib}). When the \longarg{debug} mode is on, any
+\idx!{convertgls2bib}). When the \longarg{debug} mode is on, any
warnings or errors triggered by the interpreter will be written to
the transcript prefixed with \code{texparserlib:} (the results of
the conversions will be included in the transcript as informational
@@ -2968,12 +2987,13 @@ for more details about the interpreter.
\argsection{no-break-space}
The interpreter treats a tilde character \idx{nbspchar} as a non-breakable
-space (default).
+space (default). Similarly \ics{nobreakspace} produces a
+non-breakable space character (\hex{00A0}).
\argsection{break-space}
The interpreter treats a tilde character \idx{nbspchar} as a normal
-space.
+space. Similarly \ics{nobreakspace} just produces a space.
\argsection{cite-as-record}
@@ -3680,7 +3700,7 @@ line in the \ext{bib} file or the \csopt{charset} resource option.
By default, \gls{newglossaryentry} and similar commands expand field values
(except for \field{name}, \field{symbol} and \field{description}).
This is useful if constructing field values programmatically
-(for example in a loop) but can cause a problem if certain fragile
+(for example in a \idx!{loop}) but can cause a problem if certain fragile
commands are included in the field.
The switch \longarg{no-expand-fields} makes \bibgls\ write
@@ -3703,23 +3723,67 @@ before the entries are defined (that is, before using
\argsection{trim-fields}
-Trim leading and trailing spaces from field values. For example,
+Trim leading and trailing spaces from all field values. For example,
if the \ext{bib} file contains:
\begin{codeenv}
\atentry{entry}\marg{sample,
- \field{name} = \marg{ sample },
+ \field{name} = \marg{sample},
\field{description} = \marg{
an example
}
}
\end{codeenv}
-This will cause spurious spaces. Using \longarg{trim-fields} will
-automatically trim the values before writing the \iext{glstex} file.
+This will cause spurious spaces in the \field{description} field.
+Using \longarg{trim-fields} will automatically trim the values
+before writing the \iext{glstex} file.
+
+Note that even without this trimming option on, fields that are
+set as keys within \cs{longnewglossaryentry} or the optional
+argument of \cs{newabbreviation} will automatically have the leading and
+trailing spaces internally trimmed by the \isty{xkeyval} package, so
+this trimming action only affects fields that aren't set in this
+way, such as the \field{description}, \field{long} and \field{short}
+fields. If you specifically require a space at the start or end of a
+field then use a spacing command, such as \cs{cs.space} or \cs{space}
+or \idx{nbspchar}.
+
+\argsection{trim-only-fields}
+
+Only trim leading and trailing spaces from the fields identified in
+the comma-separated \meta{list}. This option has a cumulative effect
+but is cancelled by \longarg{no-trim-fields} (which switches off all
+trimming) and by \longarg{trim-fields} (which switches on trimming
+for all fields). This option may not be used with
+\longarg{trim-except-fields}.
+
+For example, to only trim the \field{description} field:
+\begin{verbatim}
+bib2gls --trim-only-fields description myDoc
+\end{verbatim}
+
+\argsection{trim-except-fields}
+
+Trim all leading and trailing spaces from fields except those identified in
+the comma-separated \meta{list}. This option has a cumulative effect
+but is cancelled by \longarg{no-trim-fields} (which switches off all
+trimming) and by \longarg{trim-fields} (which switches on trimming
+for all fields). This option may not be used with
+\longarg{trim-only-fields}. See the above note about \sty{xkeyval}.
+
+For example, to trim all fields except \field{short} and
+\field{long}:
+\begin{verbatim}
+bib2gls --trim-except-fields short,long myDoc
+\end{verbatim}
+Or
+\begin{verbatim}
+bib2gls --trim-except-fields short --trim-except-fields long myDoc
+\end{verbatim}
\argsection{no-trim-fields}
-Don't trim any leading or trailing spaces from field values.
-This is the default setting.
+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{record-count}
@@ -3965,7 +4029,7 @@ Note that the \field{seealso} field doesn't allow for the optional
\oargm{tag} part. If you need a different tag, either use \field{see}
or change the definition of \ics{seealsoname} or
\ics{glsxtruseseealsoformat}. Note that, unless you are using
-\idx{xindy}, \ics{glsxtrindexseealso} just does
+\idx!{xindy}, \ics{glsxtrindexseealso} just does
\ics{glssee}\oarg{\ics{seealsoname}}, and so will be treated as \field{see}
rather than \field{seealso} by \bibgls. Again, it's better to just
use the \field{seealso} field directly.
@@ -4000,7 +4064,8 @@ location list. The option may be used in combination with the \field{see} or
\printfields
[%
Don't load \isty{glossaries-accsupp} directly (with \ics{usepackage})
- when using \styfmt{glossaries-extra}. Load using the \styopt{accsupp}
+ when using \styfmt{glossaries-extra}. Load using the
+ \glsadd{idx.accsupp}\styopt{accsupp}
package option instead.
%\begin{codeenv}
%\cs{usepackage}\oarg{\styopt{record},\styopt{accsupp}}\marg{glossaries-extra}
@@ -4702,6 +4767,11 @@ functionally like \atentry{symbol}) or
is functionally like \code{@}\meta{primary} and the dual is
functionally like \code{@}\meta{dual}.
+If the fields provided by the \isty{glossaries-prefix} are defined,
+there will be additional mappings for the special internal fields
+\field{dualprefix}, \field{dualprefixfirst},
+\field{dualprefixplural}, and \field{dualprefixfirstplural}.
+
For example:
\begin{codeenv}
\atentry{dualabbreviationentry}\marg{svm,
@@ -5035,6 +5105,18 @@ The default mappings are:
\item \field{description} $\mapsto$ \field{name}
\item \field{descriptionplural} $\mapsto$ \field{plural}
\end{itemize}
+If the prefix fields are defined, then the default mappings
+additionally include:
+\begin{itemize}
+\item \field{prefix} $\mapsto$ \field{dualprefix}
+\item \field{prefixplural} $\mapsto$ \field{dualprefixplural}
+\item \field{prefixfirst} $\mapsto$ \field{dualprefixfirst}
+\item \field{prefixfirstplural} $\mapsto$ \field{dualprefixfirstplural}
+\item \field{dualprefix} $\mapsto$ \field{prefix}
+\item \field{dualprefixplural} $\mapsto$ \field{prefixplural}
+\item \field{dualprefixfirst} $\mapsto$ \field{prefixfirst}
+\item \field{dualprefixfirstplural} $\mapsto$ \field{prefixfirstplural}
+\end{itemize}
The required fields are as for \atentry{entry}.
For example:
@@ -5092,6 +5174,18 @@ like \atentry{entry}. The default field mapping is:
\begin{itemize}
\item \field{name} $\mapsto$ \field{name}
\end{itemize}
+If the prefix fields are defined, then the default mappings
+additionally include:
+\begin{itemize}
+\item \field{prefix} $\mapsto$ \field{dualprefix}
+\item \field{prefixplural} $\mapsto$ \field{dualprefixplural}
+\item \field{prefixfirst} $\mapsto$ \field{dualprefixfirst}
+\item \field{prefixfirstplural} $\mapsto$ \field{dualprefixfirstplural}
+\item \field{dualprefix} $\mapsto$ \field{prefix}
+\item \field{dualprefixplural} $\mapsto$ \field{prefixplural}
+\item \field{dualprefixfirst} $\mapsto$ \field{prefixfirst}
+\item \field{dualprefixfirstplural} $\mapsto$ \field{prefixfirstplural}
+\end{itemize}
This doesn't actually perform any swapping of fields, but it
provides the field used for backlinks (if
\csopt{dual-indexentry-backlink} is set). The reason that the primary
@@ -5197,6 +5291,18 @@ field mapping is:
\begin{itemize}
\item \field{name} $\mapsto$ \field{name}
\end{itemize}
+If the prefix fields are defined, then the default mappings
+additionally include:
+\begin{itemize}
+\item \field{prefix} $\mapsto$ \field{dualprefix}
+\item \field{prefixplural} $\mapsto$ \field{dualprefixplural}
+\item \field{prefixfirst} $\mapsto$ \field{dualprefixfirst}
+\item \field{prefixfirstplural} $\mapsto$ \field{dualprefixfirstplural}
+\item \field{dualprefix} $\mapsto$ \field{prefix}
+\item \field{dualprefixplural} $\mapsto$ \field{prefixplural}
+\item \field{dualprefixfirst} $\mapsto$ \field{prefixfirst}
+\item \field{dualprefixfirstplural} $\mapsto$ \field{prefixfirstplural}
+\end{itemize}
However in this case the required fields are \field{short} and
\field{long}. The \field{name} for the primary entry defaults to
\field{short} if omitted. (This may be changed with the
@@ -5245,6 +5351,18 @@ field mappings are:
\item \field{symbolplural} $\mapsto$ \field{plural}
\item \field{plural} $\mapsto$ \field{symbolplural}
\end{itemize}
+If the prefix fields are defined, then the default mappings
+additionally include:
+\begin{itemize}
+\item \field{prefix} $\mapsto$ \field{dualprefix}
+\item \field{prefixplural} $\mapsto$ \field{dualprefixplural}
+\item \field{prefixfirst} $\mapsto$ \field{dualprefixfirst}
+\item \field{prefixfirstplural} $\mapsto$ \field{dualprefixfirstplural}
+\item \field{dualprefix} $\mapsto$ \field{prefix}
+\item \field{dualprefixplural} $\mapsto$ \field{prefixplural}
+\item \field{dualprefixfirst} $\mapsto$ \field{prefixfirst}
+\item \field{dualprefixfirstplural} $\mapsto$ \field{prefixfirstplural}
+\end{itemize}
The required field is: \field{symbol}.
If the \field{name} field is omitted, the dual entry is assigned a
symbol from the original (unprefixed) label.
@@ -5412,6 +5530,18 @@ field mappings are:
\item \field{longplural} $\mapsto$ \field{plural}
\item \field{short} $\mapsto$ \field{text}
\end{itemize}
+If the prefix fields are defined, then the default mappings
+additionally include:
+\begin{itemize}
+\item \field{prefix} $\mapsto$ \field{dualprefix}
+\item \field{prefixplural} $\mapsto$ \field{dualprefixplural}
+\item \field{prefixfirst} $\mapsto$ \field{dualprefixfirst}
+\item \field{prefixfirstplural} $\mapsto$ \field{dualprefixfirstplural}
+\item \field{dualprefix} $\mapsto$ \field{prefix}
+\item \field{dualprefixplural} $\mapsto$ \field{prefixplural}
+\item \field{dualprefixfirst} $\mapsto$ \field{prefixfirst}
+\item \field{dualprefixfirstplural} $\mapsto$ \field{prefixfirstplural}
+\end{itemize}
You may need to add a mapping from \field{shortplural} to
\field{plural} if the default is inappropriate.
(In \bibgls\ version 1.0 this entry type was originally called
@@ -5493,6 +5623,18 @@ This is like \atentry{dualentry} but the default mappings are:
\item \field{symbol} $\mapsto$ \field{name}
\item \field{symbolplural} $\mapsto$ \field{plural}
\end{itemize}
+If the prefix fields are defined, then the default mappings
+additionally include:
+\begin{itemize}
+\item \field{prefix} $\mapsto$ \field{dualprefix}
+\item \field{prefixplural} $\mapsto$ \field{dualprefixplural}
+\item \field{prefixfirst} $\mapsto$ \field{dualprefixfirst}
+\item \field{prefixfirstplural} $\mapsto$ \field{dualprefixfirstplural}
+\item \field{dualprefix} $\mapsto$ \field{prefix}
+\item \field{dualprefixplural} $\mapsto$ \field{prefixplural}
+\item \field{dualprefixfirst} $\mapsto$ \field{prefixfirst}
+\item \field{dualprefixfirstplural} $\mapsto$ \field{prefixfirstplural}
+\end{itemize}
The \field{name} and \field{symbol} fields are required.
For example:
\begin{codeenv}
@@ -5563,6 +5705,18 @@ field mappings are:
\item \field{duallong} $\mapsto$ \field{long}
\item \field{duallongplural} $\mapsto$ \field{longplural}
\end{itemize}
+If the prefix fields are defined, then the default mappings
+additionally include:
+\begin{itemize}
+\item \field{prefix} $\mapsto$ \field{dualprefix}
+\item \field{prefixplural} $\mapsto$ \field{dualprefixplural}
+\item \field{prefixfirst} $\mapsto$ \field{dualprefixfirst}
+\item \field{prefixfirstplural} $\mapsto$ \field{dualprefixfirstplural}
+\item \field{dualprefix} $\mapsto$ \field{prefix}
+\item \field{dualprefixplural} $\mapsto$ \field{prefixplural}
+\item \field{dualprefixfirst} $\mapsto$ \field{prefixfirst}
+\item \field{dualprefixfirstplural} $\mapsto$ \field{prefixfirstplural}
+\end{itemize}
The required fields are: \field{short}, \field{long},
\field{dualshort} and \field{duallong}.
This includes some new fields: \field{dualshort},
@@ -5982,7 +6136,7 @@ original entry type (before it was aliased to
For example \code{article} or \code{book}.
You can iterate over these internal list fields using
-\ics{glsxtrfielddolistloop} or \ics{glsxtrfieldforlistloop}.
+\glsadd{idx.loop}\ics{glsxtrfielddolistloop} or \ics{glsxtrfieldforlistloop}.
For example:
\begin{codeenv}
\cs{newcommand}\marg{\csfmt{contributorhandler}}[1]\marg{\csfmt{par}\cs{glsentryname}\marg{\#1}}
@@ -6662,9 +6816,9 @@ that don't get seen by \LaTeX.
The \glostyle{alttree} glossary style needs to know the widest
\field{name} (for each level, if hierarchical). This can be set
-using \ics{glssetwidest} provided by the \styfmt{glossary-tree}
+using \ics{glssetwidest} provided by the \isty{glossary-tree}
package (or similar commands like \ics{glsupdatewidest} provided by
-\styfmt{glossaries-extra-stylemods}), but this requires knowing
+\isty{glossaries-extra-stylemods}), but this requires knowing
which name is the widest. Alternatively, one of the iterative commands
such as \ics{glsFindWidestTopLevelName} can be used, which slows the
document build as it has to iterate over all defined entries.
@@ -7056,8 +7210,15 @@ following values are allowed:
\begin{itemize}
\item \optfmt{recorded and deps}: add all recorded entries and
their dependencies (default).
+
\item \optfmt{recorded and deps and see}: as above but will also
-add unrecorded entries whose \field{see} or \field{seealso} field refers to a recorded entry.
+add unrecorded entries whose \field{see}, \field{seealso} or
+\field{alias} field refers to a recorded entry.
+
+\item \optfmt{recorded and deps and see not also}: as above but will
+add unrecorded entries whose \field{see} or \field{alias} (but not
+\field{seealso}) field refers to a recorded entry.
+
\item \optfmt{recorded no deps}: add all recorded entries but not
their dependencies. The dependencies include those referenced in the
\field{see} or \field{seealso} field or fields identified by
@@ -7065,10 +7226,12 @@ their dependencies. The dependencies include those referenced in the
with commands like \ics{gls} in the field values that are parsed by
\bibgls. With this setting, parents will be omitted unless they've
been referenced in the document through commands like \ics{gls}.
+
\item \optfmt{recorded and ancestors}: this is like the previous
setting but parents are added even if they haven't been referenced
in the document. The other dependent entries are omitted if they
haven't been referenced in the document.
+
\item \optfmt{all}: add all entries found in the \ext{bib} files
supplied in the \csopt{src} option.
\end{itemize}
@@ -7308,7 +7471,7 @@ 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}.
+format and can be iterated over using \glsadd{idx.loop}\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
@@ -7390,6 +7553,19 @@ grouping. With \sty{glossaries-extra} v1.31+ you can perform a
numerical test with \ics{GlsXtrIfFieldNonZero} or
\ics{GlsXtrIfFieldEqNum}.
+\optsection{save-sibling-count}
+
+This is a boolean option. The default setting is
+\csopt[false]{save-sibling-count}. This is like
+\csopt{save-child-count} but saves the sibling count in
+\field{siblingcount} and the sibling list in \field{siblinglist}.
+As with the child list, the sibling list is in \sty{etoolbox}['s]
+internal list format. The sibling information is only saved for
+entries that have a parent.
+
+The advantage with \field{siblinglist} over accessing the parent's
+\field{childlist} is that the entry itself is excluded from the list.
+
\optsection{flatten}
This is a boolean option. The default value is \csopt[false]{flatten}.
@@ -7803,7 +7979,7 @@ the new parent entry can be assigned with
\csopt{missing-parent-category}.
\end{itemize}
-For example, consider the \exfile{books.bib} file which contains
+For example, consider the \exfile!{books.bib} file which contains
entries like:
\begin{codeenv}
\atentry{entry}\marg{ubik,
@@ -8173,7 +8349,7 @@ characters \code{.}~(full stop), \code{-}~(hyphen), \code{+}~(plus),
\code{'}~(apostrophe) or \code{@}~(at-sign) are stripped. If you want to
retain commas, use \csopt{labelify-list} instead. If you want to
strip any of the allowed punctuation, use \csopt{labelify-replace} to
-remove the unwanted characters. (Remember that \sty{babel} can make
+remove the unwanted characters. (Remember that \isty{babel} can make
some of these punctuation characters active, in which case they need
to be stripped.)
@@ -9320,7 +9496,7 @@ as:
Any character that isn't of type \idx{punctuationother} won't
match.
-For example, the sample \exfile{books.bib} file contains:
+For example, the sample \exfile!{books.bib} file contains:
\begin{codeenv}
\atentry{entry}\marg{whydidnttheyaskevans,
\field{name}=\marg{Why Didn't They Ask Evans?},
@@ -9950,6 +10126,21 @@ bookmarks by adjusting the definition of the custom command:
}
\end{codeenv}
+\optsection[\subsubsection]{interpret-fields-action}
+
+This option governs the behaviour of \csopt{interpret-fields}.
+Available values are:
+\begin{itemize}
+\item\code{replace}: replace the field content with its interpreted
+value (default);
+\item\code{replace non empty}: only replace the field content with
+its interpreted value if the interpreted value isn't an empty
+string.
+\end{itemize}
+If a field value consists solely of commands that are unknown to the
+interpreter, then the resulting value will end up empty. In this
+case, it may be more appropriate to leave the field unchanged.
+
\optsection[\subsubsection]{date-time-fields}
This option indicates that the listed fields all contain
@@ -10040,6 +10231,107 @@ The value is the locale used when parsing fields identified
by \csopt{time-fields}. The \meta{value} is as for
\csopt{date-sort-locale}.
+\subsection{Prefix Fields}
+\label{sec:prefixes}
+
+If you use the \isty{glossaries-prefix} package, the prefix
+set of fields become available (\field{prefix},
+\field{prefixplural}, \field{prefixfirst} and
+\field{prefixfirstplural}). The default behaviour of \ics{pgls} is for no
+separator between the prefix and the text produced with \cs{gls}.
+This is because there are situations where there shouldn't be a
+space, although a space is more commonly required.
+
+This means that a space needs to be appended to the required prefix
+fields, but an actual space character can't be used because
+\sty{xkeyval} trims leading and trailing spaces. The \ics{space}
+command needs to be used instead, but there are also situations
+where an non-breakable space should be used (for example, where the
+prefix is a single character). It's a bit tiresome having to
+remember to put \ics{space} or \idx{nbspchar} at the end of the
+field value.
+
+The \csopt{append-prefix-field} option allows the automatic insertion of a
+space, but it may be used without the \sty{glossaries-prefix}
+package. The fields that contain prefixes are identified by
+\csopt{prefix-fields}.
+
+If you have any dual entries, then \bibgls\ will also recognise the
+special internal fields \field{dualprefix},
+\field{dualprefixplural}, \field{dualprefixfirst} and
+\field{dualprefixfirstplural}.
+
+\optsection[\subsubsection]{prefix-fields}
+
+Identifies the fields that are used to store prefixes. The default
+set is: \field{prefix}, \field{prefixfirst}, \field{prefixplural},
+\field{prefixfirstplural}, and their dual counterparts
+\field{dualprefix}, \field{dualprefixfirst}, \field{dualprefixplural}
+and \field{dualprefixfirstplural}.
+
+\optsection[\subsubsection]{append-prefix-field}
+
+Allowed values are:
+\begin{itemize}
+\item \optfmt{none}: don't append a space to the prefix fields (default);
+
+\item \optfmt{space}: append the command identified by
+\csopt{append-prefix-field-cs} (\ics{space} by default) to the
+prefix field unless the field value ends with a character identified
+by \csopt{append-prefix-field-exceptions} or a command identified by
+\csopt{append-prefix-field-cs-exceptions}. Note that if the field
+value ends with anything else (such as an empty group) then these
+exceptions won't apply.
+
+\item \optfmt{space or nbsp}: as above but uses \idx{nbspchar}
+instead of \ics{space} if the field value matches the pattern given
+by \csopt{append-prefix-field-nbsp-match}.
+
+\end{itemize}
+
+\optsection[\subsubsection]{append-prefix-field-cs}
+
+Identifies the command \meta{cs} that should be used to append to
+the prefix fields. The default value is \ics{space}. Remember to use
+\cs{cs.string} or \cs{protect} to prevent the command from being
+expanded as it's written to the \ext{aux} file.
+
+\optsection[\subsubsection]{append-prefix-field-exceptions}
+
+This setting identifies the set of characters that, if found at the
+end of a prefix field, prevent \csopt{append-prefix-field} from
+appending a space (either \ics{space} or \idx{nbspchar}).
+
+The value should be a sequence of characters. You may use
+\stringu\meta{hex} to identify a character by its hexadecimal code.
+Spaces are ignored, so \csopt[ ' - ]{append-prefix-field-exceptions}
+is equivalent to \csopt['-]{append-prefix-field-exceptions}.
+
+The default set is the straight apostrophe character (\hex{0027}),
+the hyphen-minus character (\hex{002D}), the tilde character
+(\idx{nbspchar}), the hyphen character (\hex{2010}), the
+non-breaking hyphen (\hex{2011}), and the right single quotation
+mark (\hex{2019}).
+
+\optsection[\subsubsection]{append-prefix-field-cs-exceptions}
+
+This setting identifies the set of commands that, if found at the
+end of a prefix field, prevent \csopt{append-prefix-field} from
+appending a space (either \ics{space} or \idx{nbspchar}). Any spaces
+found in \meta{sequence} are ignored. The default setting is the
+set: \cs{space}, \ics{nobreakspace} and \cs{cs.space}.
+
+Remember that you will need to use \cs{cs.string} or \cs{protect} to
+prevent the command from being expanded while the resource options
+are written to the \ext{aux} file.
+
+\optsection[\subsubsection]{append-prefix-field-nbsp-match}
+
+The value is the \idx{regex} that identifies prefixes that should be
+followed by \idx{nbspchar} instead of \ics{space}. The default
+is \csopt[\idx{matchanydot}]{append-prefix-field-nbsp-match} which indicates a
+single character.
+
\subsection{Case-Changing}
\label{sec:fieldcase}
@@ -10534,9 +10826,9 @@ is omitted for the argument that follows any of those commands.
For example, this manual defines some semantic commands such as
\csfmt{fieldfmt} (to format field names), \csfmt{abbrstylefmt}
(to format abbreviation style names) and \csfmt{glostylefmt} (to format
-glossary style names). These occur in some of the section
-and subsection headings in the \hyperref[sec:topics]{topic summary}
-which are converted to \idx{titlecase} (see \csopt{field-case-change}).
+glossary style names). If any these occur in section
+and subsection headings (which are converted to \idx{titlecase})
+then the case-change would produce an inappropriate result.
These formatting commands shouldn't have their argument changed so they
are identified with:
\begin{codeenv}
@@ -10629,8 +10921,7 @@ field and convert \fieldfmt{nametitle} to \idx{titlecase}:
\csopt[\field{name}=\fieldfmt{nametitle}]{replicate-fields},
\csopt[\fieldfmt{nametitle}=title]{field-case-change},
\end{codeenv}
-This means that the \hyperref[sec:topics]{topic summary}
-(page~\pageref{sec:topics}) can fetch the value of
+This means that it's possible to fetch the value of
\fieldfmt{nametitle} instead of \field{name}, which provides an
expandable \idx{titlecase} form that's suitable for the PDF
bookmarks.
@@ -10815,7 +11106,7 @@ for more information about supplemental locations and
records.)
You can iterate through the \field{loclist} value
-using one of \sty{etoolbox}'s internal list loops (either
+using one of \sty{etoolbox}'s internal list \idxpl{loop} (either
by first fetching the list using \ics{glsfieldfetch}
or through \styfmt{glossaries-extra}'s \ics{glsxtrfielddolistloop}
or \ics{glsxtrfieldforlistloop} shortcuts).
@@ -11014,7 +11305,7 @@ For more information on adjusting the formatting see the
By default, the locations will be processed and stored in the
\field{location} and \field{loclist} fields. However, if you don't
want the location lists (for example, you are using the
-\styopt{nonumberlist} option or you are using \idx{xindy} with a
+\styopt{nonumberlist} option or you are using \idx!{xindy} with a
custom location rule), then there's no need for \bibgls\ to process
the locations. To switch this function off, just use
\csopt[false]{save-locations}. Note that with this setting, if
@@ -11022,6 +11313,23 @@ you're not additionally using \idx!{makeindex} or \idx!{xindy}, then
the locations won't be available even if you don't have the
\styopt{nonumberlist} option set.
+The boolean \field{nonumberlist} key that may be used in
+\gls{newglossaryentry} can also be used in a \ext{bib} file, but in
+this case it can't have an empty value. The value must be either
+\code{true} or \code{false}. If \code{true} then \bibgls\ won't
+save the \field{location} or \field{loclist} fields.
+
+The \field{nonumberlist} key provided by the base \sty{glossaries}
+package doesn't represent a real field. The value isn't saved but,
+if used, it will alter the indexing information that's written to
+the \idx!{makeindex} or \idx!{xindy} file. It's a little hack to
+ensure that the location is hidden for a specific entry when used
+with \idx!{makeindex} and \idx!{xindy}.
+
+\bibgls\ will look for this key to determine if the location should
+be omitted for the given entry, but it won't write the key to the
+\ext{glstex} file.
+
\optsection{save-loclist}
If you want the \field{location} field but don't need
@@ -11911,7 +12219,7 @@ loaded) so that if the counter is \counter{wrglossary} then
page number is displayed in the location list but it links back to
the place where the corresponding \cs{label} occurred.
-This method works partially with \appfmt{makeindex} and \appfmt{xindy}
+This method works partially with \idx!{makeindex} and \idx!{xindy}
but from their point of view the location is the value of the
\counter{wrglossary} counter, which interferes with their ability to
merge duplicate page numbers and form ranges. Since \bibgls\ is
@@ -13778,7 +14086,7 @@ The alphabet sort options (\tableref{tab:sortoptionsrule}) typically
list non-letter characters before alphabetical characters and spaces
are quite often in the ignored set. This means that the alphabet
sort options are naturally in a letter order, similar to
-\idx{xindy}['s] \code{ord/letorder} module. (This isn't the same as
+\idx!{xindy}['s] \code{ord/letorder} module. (This isn't the same as
\csopt[letter-nocase]{sort}, which just sorts according to the
Unicode value not according to a particular alphabet.)
@@ -13827,7 +14135,7 @@ 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, or combine
+emulate \idx!{makeindex} or \idx!{xindy}'s letter ordering, or combine
with \csopt{sort-replace} to insert custom break points.
\end{itemize}
@@ -13909,6 +14217,9 @@ equal. The \meta{value} may be one of:
\begin{itemize}
\item\optfmt{none}: don't take any further action if sort values are
identical;
+\item\optfmt{def} if sort values are identical, order them according to definition;
+\item\optfmt{use}: if sort values are identical, order them
+according to use in the document (order determine by a normal record);
\item\optfmt{id}: if sort values are identical, compare
the entry labels;
\item\optfmt{original id}: if sort values are identical, compare the
@@ -13916,9 +14227,8 @@ original unprefixed entry labels (as given in the \ext{bib} file);
\item\meta{field}: if sort values are identical, compare
the values from the given \meta{field}.
\end{itemize}
-In each case (other than \csopt[none]{identical-sort-action}) a
-simple case-sensitive string comparison is used. If \meta{value}
-isn't a recognised keyword or valid field an error will occur. The
+For the last three cases, a simple case-sensitive string comparison is used.
+If \meta{value} isn't a recognised keyword or valid field an error will occur. The
default setting is \csopt[id]{identical-sort-action}. If you're
using one of the sort rules listed in \tableref{tab:sortoptionsrule}
and you also want a locale-sensitive sort used on the fallback, then
@@ -17754,7 +18064,7 @@ Converts the first letter of \meta{text} to \idx{uppercase}. This just uses
\chapter{Converting Existing \iext{tex} to \iext{bib}}
\label{sec:gls2bib}
-\setsecdepth{0}
+\setsecdepth{1}
If you have already been using the \styfmt{glossaries} or
\styfmt{glossaries-extra} package with a large file containing all your
@@ -17769,20 +18079,29 @@ the \ext{bib} file. This application is less secure than \bibgls\ as
it doesn't use \idx{kpsewhich} to check \texmfcnf{openinany} and
\texmfcnf{openoutany}. Take care not to accidentally overwrite
existing \ext{bib} files as there's no check to determine if
-\meta{bib file} already exists.
+\meta{bib file} already exists with the default \convertglsbiblongarg{overwrite}.
-The \meta{options} are:
-\begin{description}
-\item[\longargfmt{texenc} \meta{encoding}] The character encoding of the
-\ext{tex} file. If omitted, the operating system's default encoding
-is assumed (or the \idx{JVM}['s]).
+If the \ext{bib} extension is missing from \meta{bib file}, it will
+be added. The extension is required for \meta{tex file}.
+
+\section{Command Line Arguments}
-\item[\longargfmt{bibenc} \meta{encoding}] The character encoding of the
-\ext{bib} file. If omitted, the same encoding as the
-\ext{tex} file is assumed.
+The \meta{options} recognised by \idx{convertgls2bib} are described below.
-\item[\longargfmt{space-sub} \meta{replacement}] The \ext{bib}
-format doesn't allow spaces in labels. If your original
+\convertglsbibarg{texenc}
+
+The character encoding of the \ext{tex} file. If omitted, the
+operating system's default encoding is assumed (or the
+\idx{JVM}['s]).
+
+\convertglsbibarg{bibenc}
+
+The character encoding of the \ext{bib} file. If omitted, the same
+encoding as the \ext{tex} file is assumed.
+
+\convertglsbibarg{space-sub}
+
+The \ext{bib} format doesn't allow spaces in labels. If your original
definitions in your \ext{tex} file have spaces, use this option to
replace spaces in labels. Each space will be substituted with
\meta{replacement}. The cross-referencing fields, \field{see},
@@ -17796,38 +18115,234 @@ operating system. For example:
convertgls2bib --space-sub '' entries.tex entries.bib
\end{verbatim}
-\item[\longargfmt{ignore-sort}] Ignore the \field{sort} field.
-This is the default since \bibgls\ can work out a more intuitive
-sort value than either \idx!{makeindex} or \idx!{xindy}.
+\convertglsbibarg{ignore-sort}
-\item[\longargfmt{no-ignore-sort}] Don't ignore the \field{sort} field.
+Omit the \field{sort} field. This is the default since \bibgls\ can
+work out a more intuitive sort value than either \idx!{makeindex} or
+\idx!{xindy}.
-\item[\longargfmt{locale} \meta{lang tag}] Identifies the \langxml\
-to use for \idx{convertgls2bib}['s] messages.
+\convertglsbibarg{no-ignore-sort}
-\item[\longargfmt{silent}] Suppress all messages except for errors.
+Don't ignore the \field{sort} field.
-\item[\longargfmt{verbose}] Display messages and warnings (default).
+\convertglsbibarg{ignore-type}
-\item[\longargfmt{debug}] Display debugging messages (stack
-traces and other information in addition to \longargfmt{verbose}).
+Omit the \field{type} field in the \ext{bib} file. You may find it
+more flexible not to be locked into a specific glossary type if you
+have a large database of entries.
-\item[\longargfmt{help} or \shortargfmt{h}] Display help message and
-quit.
-\item[\longargfmt{version} or \shortargfmt{v}] Display version
-information and quit.
-\end{description}
+\convertglsbibarg{no-ignore-type}
+
+ Don't omit the \field{type} field (default unless
+\convertglsbiblongarg{split-on-type}).
+
+\convertglsbibarg{split-on-type}
+
+Split the entries into separate files according to the \field{type}
+field. Any entries that have the \field{type} field set to \ics{glsdefaulttype}
+or that don't have the \field{type} field set and there's no default provided
+by the command used to define the entry (see below) then the
+\atentryfmt{\meta{entry}} data will be written to the main \meta{bib
+file}. Otherwise entries will be written to the split file
+(in the same directory as \meta{bib file}).
+
+The split file name depends on whether or not the
+\convertglsbiblongarg{split-on-category} switch has also been used. With both
+and if the category and field values are different then
+the file name is \metametafilefmt{}{type}{-}{category}{.bib} otherwise
+it's \metafilefmt{}{type}{.bib}.
+
+Commands that have a default type are as follows:
+\begin{itemize}
+\item \gls{newabbreviation}, \gls{newacronym}, \ics{oldacronym},
+\gls{newdualentry}:
+the default type is assumed to be \code{abbreviations} (regardless
+of the definition of \ics{acronymtype} or \ics{glsxtrabbrvtype});
+\item \gls{glsxtrnewsymbol}: the default type is assumed to be \code{symbols};
+\item \gls{glsxtrnewnumber}: the default type is assumed to be \code{numbers};
+\item \gls{newterm}: the default type is assumed to be \code{index}.
+\end{itemize}
+
+This option automatically implements \convertglsbiblongarg{ignore-type} and
+\convertglsbiblongarg{no-overwrite}.
+
+\convertglsbibarg{no-split-on-type}
+
+Don't split the entries into separate files according to their type
+(default).
+
+\convertglsbibarg{ignore-category}
+
+Omit the \field{category} field in the \ext{bib} file.
+
+\convertglsbibarg{no-ignore-category}
+
+Don't omit the \field{category} field (default unless
+\convertglsbiblongarg{split-on-category}).
+
+\convertglsbibarg{split-on-category}
+
+Split the entries into separate files according to the \field{category}.
+If the \field{category} field isn't present and there's no default provided
+by the command used to define the entry (see below) then the
+\atentryfmt{\meta{entry}} data will be written to the main \meta{bib
+file}. Otherwise entries will be written to the split file
+(in the same directory as \meta{bib file}).
+
+The split file name depends on whether or not the
+\convertglsbiblongarg{split-on-type} switch has also been used. With both and
+if the category and field values are different then
+the file name is \metametafilefmt{}{type}{}{category}{.bib} otherwise
+it's \metafilefmt{}{category}{.bib}.
+
+Commands that have a default category are as follows:
+\begin{itemize}
+\item \gls{newabbreviation}, \gls{newacronym}, \ics{oldacronym},
+\gls{newdualentry}:
+the default category is assumed to be \code{abbreviation};
+\item \gls{glsxtrnewsymbol}: the default category is assumed to be \code{symbol};
+\item \gls{glsxtrnewnumber}: the default category is assumed to be \code{number};
+\item \gls{newterm}: the default category is assumed to be \code{index}.
+\end{itemize}
+
+For example, if you have both \convertglsbiblongarg{split-on-type} and
+\convertglsbiblongarg{split-on-category}, then the default file name for
+\gls{newabbreviation} will be
+\filefmt{abbreviations-abbreviation.bib} but the default file name
+for \gls{newterm} will be \filefmt{index.bib}. Whereas if you only
+have \convertglsbiblongarg{split-on-category} and not
+\convertglsbiblongarg{split-on-type}, then then default file name for
+\gls{newabbreviation} will be \filefmt{abbreviation.bib}.
+
+This option automatically implements \convertglsbiblongarg{ignore-category} and
+\convertglsbiblongarg{no-overwrite}.
+
+\convertglsbibarg{no-split-on-category}
+
+Don't split the entries into separate files according to their
+category (default).
+
+\convertglsbibarg{ignore-fields}
+
+Omit all the fields listed in \meta{list} from the \ext{bib} file.
+If \field{sort}, \field{type} or \field{category} are included
+in the list, this will automatically implement the corresponding
+\convertglsbiblongarg{ignore-sort},
+\convertglsbiblongarg{ignore-type} or
+\convertglsbiblongarg{ignore-category} option.
+
+This option is not cumulative. If the list is empty it will unset
+any previous list but won't unset any
+\convertglsbiblongarg{ignore-sort},
+\convertglsbiblongarg{ignore-type} or
+\convertglsbiblongarg{ignore-category} option.
+
+For example:
+\begin{alltt}
+convertgls2bib \longargfmt{ignore-fields} 'user1,sort' entries.bib
+\end{alltt}
+is equivalent to:
+\begin{alltt}
+convertgls2bib \longargfmt{ignore-fields} user1 \longargfmt{ignore-sort entries.bib}
+\end{alltt}
+and
+\begin{alltt}
+convertgls2bib \longargfmt{ignore-fields} 'user1,sort' \longargfmt{ignore-fields} '' entries.bib
+\end{alltt}
+is equivalent to:
+\begin{alltt}
+convertgls2bib \longargfmt{ignore-sort} entries.bib
+\end{alltt}
+
+\convertglsbibarg{preamble-only}
+
+Stop parsing if the start of the \env{document} environment is found.
+
+\convertglsbibarg{no-preamble-only}
+
+Parse the entire file (default). Be prepared for a lot of
+unknown command warnings if you make \idx{convertgls2bib} parse an
+entire document.
+
+\convertglsbibarg{absorb-see}
+
+Absorb any cross-referencing information identified with
+\ics{glssee} or \ics{glsxtrindexseealso} commands into
+the corresponding entry (default).
+
+\convertglsbibarg{no-absorb-see}
+
+Don't absorb any cross-referencing information identified with \ics{glssee}
+or \ics{glsxtrindexseealso} commands.
+
+\convertglsbibarg{index-conversion}
+
+Use \atentry{index} instead of \atentry{entry} if the
+\field{description} is empty or simply \ics{nopostdesc} or
+\ics{glsxtrnopostpunc}. (Only applies to terms that would otherwise
+be converted to \atentry{entry}, such as those defined with
+\gls{newglossaryentry}.)
+
+\convertglsbibarg{no-index-conversion}
+
+Don't convert \atentry{entry} to \atentry{index} (default).
+
+\convertglsbibarg{locale}
-This application recognises the commands listed below. Avoid any overly
+Identifies the \langxml\ to use for \idx{convertgls2bib}['s]
+messages.
+
+\convertglsbibarg{overwrite}
+
+Allow existing \ext{bib} files to be overwritten. (Default unless
+\convertglsbiblongarg{split-on-type}.)
+
+\convertglsbibarg{no-overwrite}
+
+Don't allow existing \ext{bib} files to be overwritten. (Default if
+\convertglsbiblongarg{split-on-type}.)
+
+\convertglsbibarg{silent}
+
+Suppress all messages except for errors.
+
+\convertglsbibarg{verbose}
+
+Display messages and warnings (default).
+
+\convertglsbibarg{debug}
+
+Display debugging messages (stack traces and other information in
+addition to \convertglsbiblongarg{verbose}).
+
+\convertglsbibarg{help}
+
+Display help message and quit.
+
+\convertglsbibarg{version}
+
+Display version information and quit.
+
+\section{Recognised Commands}
+
+This application recognises the commands listed below as well as
+some standard commands such as \ics{newcommand}. Avoid any overly
complicated code within the \ext{tex} file. The
\hyperref[sec:texparserlib]{\TeX\ parser library} isn't a \TeX\ engine! The
\ext{tex} file doesn't need to be a complete document, but if you want certain
commands recognised from packages that the \TeX\ parser library supports,
-you'll need to include \ics{usepackage} in the \ext{tex} file.
+you'll need to include \ics{usepackage} in the \ext{tex} file. If
+you want to quit parsing the \ext{tex} file at the start of the
+document, use the \convertglsbiblongarg{preamble-only} switch.
+
In all cases below, if \meta{\keyvallist} contains:
\begin{codeenv*}
\field{see}=\marg{[\ics{seealsoname}]\meta{label(s)}}
\end{codeenv*}
+or
+\begin{codeenv*}
+\field{see}=\marg{[\ics{alsoname}]\meta{label(s)}}
+\end{codeenv*}
this will be substituted with:
\begin{codeenv*}
\field{seealso}=\margm{label(s)}
@@ -17842,6 +18357,10 @@ will be written as:
\field{seealso} = \marg{goose}
}
\end{codeenv}
+Note that it won't convert \code{\field{see}=\marg{[see also]\meta{labels}}}.
+If you have used explicit text instead of \ics{seealsoname} or
+\ics{alsoname} then consider performing a global search and replace
+on your file using your text editor.
Additionally, if \meta{\keyvallist} contains:
\begin{codeenv}
@@ -17853,7 +18372,7 @@ recommended in \meta{\keyvallist} when loading files with
argument to set the \field{type}. With \bibgls\ you can use the
\csopt{type} option instead.)
-\cssection[\section]{glsexpandfields}
+\cssection{glsexpandfields}
The base \styfmt{glossaries} package provides:
\formatdef{glsexpandfields}
If present, this instructs \idx{convertgls2bib} to expand all fields
@@ -17864,19 +18383,19 @@ field values. Conversely, there are some commands that will be
expanded by \idx{convertgls2bib} that aren't expandable in \TeX\
(such as \ics{MakeUppercase} and \ics{char}).
-\cssection[\section]{glsnoexpandfields}
+\cssection{glsnoexpandfields}
The base \styfmt{glossaries} package provides:
\formatdef{glsnoexpandfields}
If present, this instructs \idx{convertgls2bib} to not expand fields
unless explicitly identified by \gls{glssetexpandfield}.
-\cssection[\section]{glssetexpandfield}
+\cssection{glssetexpandfield}
The base \styfmt{glossaries} package provides:
\formatdef{glssetexpandfield}
If present, this instructs \idx{convertgls2bib} to expand the
given field, even if \gls{glsnoexpandfields} has been used.
-\cssection[\section]{glssetnoexpandfield}
+\cssection{glssetnoexpandfield}
The base \styfmt{glossaries} package provides:
\formatdef{glssetnoexpandfield}
If present, this instructs \idx{convertgls2bib} to not expand the
@@ -17885,7 +18404,7 @@ Unlike the default behaviour with the \sty{glossaries} package, there are no
fields switched explicitly switched off by default with
\idx{convertgls2bib}.
-\cssection[\section]{newglossaryentry}
+\cssection{newglossaryentry}
The base \styfmt{glossaries} package provides:
\formatdef{newglossaryentry}
This is converted to:
@@ -17896,7 +18415,7 @@ This is converted to:
\end{codeenv}
\ics{newentry} is recognised as a synonym of \gls{newglossaryentry}.
-\cssection[\section]{provideglossaryentry}
+\cssection{provideglossaryentry}
The base \styfmt{glossaries} package provides:
\formatdef{provideglossaryentry}
This is converted to:
@@ -17907,7 +18426,7 @@ This is converted to:
\end{codeenv}
but only if \meta{label} hasn't already been defined.
-\cssection[\section]{longnewglossaryentry}
+\cssection{longnewglossaryentry}
The base \styfmt{glossaries} package provides:
\formatdef{longnewglossaryentry}
This is converted to:
@@ -17922,13 +18441,13 @@ is also recognised. The unstarred version strips trailing spaces
from \meta{description}. (This doesn't add \ics{nopostdesc}, but
\styfmt{glossaries-extra} defaults to \styopt{nopostdot}.)
-\cssection[\section]{longprovideglossaryentry}
+\cssection{longprovideglossaryentry}
The base \styfmt{glossaries} package provides:
\formatdef{longprovideglossaryentry}
As above, but only if \meta{label} hasn't already been defined.
-\cssection[\section]{newterm}
+\cssection{newterm}
The base \styfmt{glossaries} package provides:
\formatdef{newterm}
@@ -17983,7 +18502,7 @@ which will cause a problem when the \ext{bib} file is parsed
by \bibgls\ (and will probably also cause a problem for
bibliographic management systems).
-\cssection[\section]{newabbreviation}
+\cssection{newabbreviation}
The \styfmt{glossaries-extra} package provides:
\formatdef{newabbreviation}
This is converted to:
@@ -18002,15 +18521,19 @@ if the optional argument is present, otherwise it's converted to:
}
\end{codeenv}
-\cssection[\section]{newacronym}
+\cssection{newacronym}
The base \styfmt{glossaries} package provides:
\formatdef{newacronym}
(which is redefined by \styfmt{glossaries-extra} to use
\gls{newabbreviation}).
-As above but uses \atentry{acronym} instead.
+As above but uses \atentry{acronym} instead. The base package also
+provides \ics{oldacronym}, which emulates the way abbreviations were
+defined with the precursor \styfmt{glossary} package. This has
+different syntax to \gls{newacronym} but is also recognised by \idx{convertgls2bib}
+and is converted to \atentry{acronym}.
-\cssection[\section]{glsxtrnewsymbol}
+\cssection{glsxtrnewsymbol}
The \styfmt{glossaries-extra} package provides:
\formatdef{glsxtrnewsymbol}
(when the \styopt{symbols} option is used).
@@ -18036,7 +18559,7 @@ in which case it's converted to:
\end{codeenv}
\ics{newsym} is recognised as a synonym for \gls{glsxtrnewsymbol}.
-\cssection[\section]{glsxtrnewnumber}
+\cssection{glsxtrnewnumber}
The \styfmt{glossaries-extra} package provides:
\formatdef{glsxtrnewnumber}
@@ -18063,7 +18586,7 @@ otherwise it's converted to:
\end{codeenv}
\ics{newnum} is recognised as a synonym for \gls{glsxtrnewnumber}.
-\cssection[\section]{newdualentry}
+\cssection{newdualentry}
\formatdef{newdualentry}
This command isn't provided by either \styfmt{glossaries} or
@@ -18640,7 +19163,7 @@ that only conditionally append text.
The best solution is with \styfmt{glossaries-extra} v1.23+ which
provides \ics{glsxtrrestorepostpunc} for use in the category
\idxpl{postdescriptionhook} that counteracts \cs{glsxtrnopostpunc}.
-This can be placed inside a conditional, as used in
+This can be placed inside a \idx{conditional}, as used in
\exfile{sample-media.tex}, and does nothing if \cs{glsxtrnopostpunc}
doesn't occur in the \field{description} field. (Note that
\cs{glsxtrrestorepostpunc} can't be used to counteract
@@ -19564,7 +20087,7 @@ and (if the \field{description} field is displayed in the glossary):
the initial backslash.)
I'd like to use the \glostyle{bookindex} style, which is
-provided by the \sty{glossary-bookindex}
+provided by the \isty{glossary-bookindex}
package.\footnote{\styfmt{glossary-bookindex}
is distributed with \styfmt{glossaries-extra} v1.21+.} This isn't loaded
automatically, but it can be loaded through the
@@ -19712,7 +20235,7 @@ files. There won't be any number lists since there are no records.
I need a glossary style that shows the \field{symbol} field so I've
used \glostyle{mcolindexgroup}. Again I've suppressed the automatic
loading of the default styles with \styopt{nostyles} and used
-\styopt[mcols]{stylemods} to load \sty{glossary-mcols} and patch the
+\styopt[mcols]{stylemods} to load \isty{glossary-mcols} and patch the
styles. Note that although I've used \styopt{nostyles}, the
\sty{glossary-tree} style is loaded as it's required by
\sty{glossary-mcols}.
@@ -19838,14 +20361,14 @@ letter-number methods listed in
I've decided to define a custom style for the first glossary. Since
it's based on the \glostyle{long3col-booktabs} style I need to
-load \sty{glossary-longbooktabs}, which can conveniently be done with
+load \isty{glossary-longbooktabs}, which can conveniently be done with
the \styopt{stylemods} option. This uses \env{longtable} (provided
-by \sty{longtable}, which is automatically loaded) which means
+by \isty{longtable}, which is automatically loaded) which means
an extra \LaTeX\ call is required in the build process to ensure the
column widths are correct. Again I'm using \styopt{nostyles} to
suppress the automatic loading of the default styles, however
\sty{glossary-tree} will be loaded as it's listed in the value of
-\styopt{stylemods} and \sty{glossary-long} will be loaded as it's
+\styopt{stylemods} and \isty{glossary-long} will be loaded as it's
required by \sty{glossary-longbooktabs}. I can't use my custom style
in the \styopt{style} package option as it hasn't been defined at
that point. The default \glostyle{list} style is now unavailable
@@ -20252,7 +20775,7 @@ option to automatically load that package. I'd like to use the
\begin{codeenv}
\styopt[list,bookindex]{stylemods}
\end{codeenv}
-This ensures that \sty{glossary-list} and \sty{glossary-bookindex}
+This ensures that \isty{glossary-list} and \sty{glossary-bookindex}
are loaded and patches the list styles.
The first two glossaries would look better with a terminating
@@ -21230,7 +21753,7 @@ If you don't have it installed, you'll need to change it.
\usepackage{fontspec}
\setmainfont{Linux Libertine O}
\end{verbatim}
-Since it's a multilingual document I also need \sty{polyglossia}
+Since it's a multilingual document I also need \isty{polyglossia}
with the main language set to \code{english}:
\begin{codeenv}
\cmd{usepackage}\marg{polyglossia}
@@ -21249,7 +21772,7 @@ iterate over all the defined entries and check if the \fieldfmt{translation}
field has been set. If it has, then the first language tag in the
\fieldfmt{language} field will supply the language, but this needs to be
converted from the \idx{IETF} language tag to a language name recognised by
-\sty{polyglossia}.
+\isty{polyglossia}.
Iterating over all entries can be done with \ics{forglsentries}
but remember that no entries will be defined before \bibgls\ has
@@ -21264,13 +21787,13 @@ been run, so this does nothing on the first \LaTeX\ run.
\marg{}\comment{}
}
\end{codeenv}
-Within the outer (\cs{forglsentries}) loop, there's a check
+Within the outer (\cs{forglsentries}) \idx{loop}, there's a check
for the \fieldfmt{translation} field using \ics{glsxtrifhasfield}.
If it's present, then the first element of the \fieldfmt{language}
field is required. The simplest way to get this is to use
\ics{glsxtrforcsvfield} which iterates over all elements of the
given field (\fieldfmt{language} in this case) and break out of the
-loop (with \ics{glsxtrendfor}) once the language has been found.
+\idx{loop} (with \ics{glsxtrendfor}) once the language has been found.
The \idx{handler} function (\csfmt{addfirstlang}) is defined so that it
adds the given language tag as a tracked language using
@@ -21279,7 +21802,7 @@ adds the given language tag as a tracked language using
(\sty{tracklang}) dialect label for convenience. This dialect label
can then be converted to the root language label using
\ics{TrackedLanguageFromDialect}. If this language is supported
-by \sty{polyglossia}, then there should be a file called
+by \isty{polyglossia}, then there should be a file called
\metafilefmt{gloss-}{language}{.ldf}.
Some of the entries use the same language, so it's necessary to
@@ -21303,7 +21826,7 @@ which is the name of the control sequence used with
\sty{polyglossia} to switch language for a short block of text. This means that
\gls{glsxtrentryfmt}\margm{text} can be used to format \meta{text}
in the relevant language. Finally, \ics{glsxtrendfor} is used to
-break out of the loop.
+break out of the \idx{loop}.
\begin{codeenv}
\cs{newcommand}*\marg{\cmd{addfirstlang}}[1]\marg{\comment{}
\cs{TrackLocale}\marg{\idx{param}1}\comment{}
@@ -21319,7 +21842,7 @@ break out of the loop.
\marg{}\comment{}
}
\end{codeenv}
-Once the \ics{forglsentries} loop has found the appropriate
+Once the \ics{forglsentries} \idx{loop} has found the appropriate
languages, it's now necessary to iterate over the internal list
\csfmt{langlist} and set the language:
\begin{codeenv}
@@ -21888,8 +22411,11 @@ Unfortunately \ics{glossentrysymbol} doesn't pick up the
\catattr{glossnamefont} attribute, so if the short form of the
abbreviations is saved in the \field{symbol} field, using one of the
methods discussed above, then the custom \csfmt{bacteriafont} won't
-be applied. A simple solution is to use \ics{glossentrynameother}
-instead:
+be applied. (As from \sty{glossaries-extra} version 1.42, there is
+now the \catattr{glosssymbolfont} attribute that's used by
+\ics{glossentrysymbol}.)
+
+A simple solution is to use \ics{glossentrynameother} instead:
\begin{codeenv}
\cs{renewcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\comment{}
\cs{glossentryname}\marg{\idx{param}1}\comment{}
@@ -22012,11 +22538,11 @@ additional write registers are required and the number of associated
\bibgls\ files is equal to the number of resource commands plus the
transcript file (in this example, $9+1=10$).
-Since this document requires \exfile{people.bib}, \exfile{books.bib}
-and \exfile{films.bib} it also requires the files that
+Since this document requires \exfile!{people.bib}, \exfile!{books.bib}
+and \exfile!{films.bib} it also requires the files that
supply the definitions of the custom commands
-(\exfile{no-interpret-preamble.bib} and either
-\exfile{interpret-preamble.bib} or \exfile{interpret-preamble2.bib})
+(\exfile!{no-interpret-preamble.bib} and either
+\exfile!{interpret-preamble.bib} or \exfile!{interpret-preamble2.bib})
to ensure the custom commands are provided both for the document and
for \bibgls's interpreter.
@@ -22520,6 +23046,7 @@ The resulting document is shown in \figureref{fig:sample-multi2.pdf},
{fig:sample-multi2.pdf3}
\end{figure}
+\setupglossaries{indexonlyfirst}
\printstyoptsummary
\printcommandsummary
%\printcommandtopic
@@ -22536,14 +23063,88 @@ The resulting document is shown in \figureref{fig:sample-multi2.pdf},
}%
{\glossentryname{#1}}%
}
+\newcommand{\locationfont}{\small}
+\newcommand{\widecrossreffont}{\footnotesize}
+\newcommand{\ifwidecrossref}[3]{%
+ \dimen0=0pt\relax
+ \glsxtrifhasfield*{see}{#1}%
+ {\settowidth{\dimen0}{\locationfont\glsxtrusesee{#1}}}%
+ {%
+ \glsxtrifhasfield*{seealso}{#1}%
+ {\settowidth{\dimen0}{\locationfont\glsxtruseseealso{#1}}}%
+ {%
+ \glsxtrifhasfield*{alias}{#1}%
+ {\settowidth{\dimen0}{\locationfont\glsxtrusealias{#1}}}%
+ {}%
+ }%
+ }%
+ \ifdim\dimen0>0.4\linewidth #2\else#3\fi
+}
+\newcommand{\precrossref}{}
+\newcommand{\indexdotfill}{\,\cleaders\hbox to .44em{\hss\textcolor{lightgray}{.}\hss}\hfill\,}
\renewcommand*{\glsxtrbookindexprelocation}[1]{%
- \glsxtrifhasfield{location}{#1}%
- {\nobreak\cleaders\hbox to .44em{\hss\textcolor{lightgray}{.}\hss}\hfill}%
- {\glsxtrprelocation}%
+ \glsxtrifhasfield*{location}{#1}%
+ {\nobreak\indexdotfill
+ \ifwidecrossref{#1}%
+ {\def\precrossref{\widecrossreffont\glstreesubitem}}%
+ {\def\precrossref{, }}%
+ }%
+ {%
+ \ifwidecrossref{#1}{\nobreak\def\precrossref{\widecrossreffont\glstreesubitem}}%
+ {\def\precrossref{\nobreak\indexdotfill}}%
+ \glsxtrprelocation
+ }%
+}
+\renewcommand{\glsxtrbookindexlocation}[2]{%
+ \begingroup
+ \locationfont
+ #2%
+ \glsxtrifhasfield{see}{#1}{\precrossref\glsxtrusesee{#1}}%
+ {%
+ \glsxtrifhasfield{seealso}{#1}%
+ {\precrossref\glsxtruseseealso{#1}}%
+ {%
+ \glsxtrifhasfield{alias}{#1}{\precrossref\glsxtrusealias{#1}}{}%
+ }%
+ }%
+ \endgroup
+ \let\precrossref\empty
}
+% With \printcommandtopic missing a lot of spawned entries will
+% appear in the index without a record. Without the topic list they
+% need to be skipped
\renewcommand{\printunsrtglossaryentryprocesshook}[1]{%
- \glsxtrifhasfield*{progenitor}{#1}{\printunsrtglossaryskipentry}{}%
+ \glsxtrifhasfield*{progenitor}{#1}%
+ {%\typeout{SKIPPING [has progenitor] #1}
+ \printunsrtglossaryskipentry
+ }%
+ {%
+ \GlsXtrIfFieldEqStr*{originalentrytype}{#1}{topic}%
+ {%
+ \glsxtrifhasfield*{location}{#1}%
+ {}%
+ {%
+ \ifglshasdesc{#1}{}%
+ {%
+ %\typeout{SKIPPING [no location] #1}
+ \printunsrtglossaryskipentry
+ }%
+ }%
+ }%
+ {%
+ \GlsXtrIfFieldValueInCsvList*{#1}{category}%
+ {abbreviationstyle,packageoption,glossarystyle,package}%
+ {%
+ \glsxtrifhasfield*{location}{#1}{}%
+ {%\typeout{SKIPPING [topic \glscategory{#1} no location] #1}%
+ \printunsrtglossaryskipentry
+ }%
+ }%
+ {}%
+ }%
+ }%
}
\renewcommand*{\unicodecategoryfmt}[1]{\textsf{#1}}
+\renewcommand*{\bibglspassim}{}
\printunsrtglossary[type=index]
\end{document}