summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/support
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2018-08-19 21:26:23 +0000
committerKarl Berry <karl@freefriends.org>2018-08-19 21:26:23 +0000
commite85f1f012e561b7b120927f0dff99816283dbbc2 (patch)
tree13a0b8429517f41f206a94f620ef40211186790d /Master/texmf-dist/source/support
parentde86d821d8b3efbc590d469c92db5012b4c84283 (diff)
bib2gls (19aug18)
git-svn-id: svn://tug.org/texlive/trunk@48439 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/support')
-rw-r--r--Master/texmf-dist/source/support/bib2gls/src/bib2gls-begin.tex28
-rw-r--r--Master/texmf-dist/source/support/bib2gls/src/bib2gls-src.zipbin148607 -> 150976 bytes
-rw-r--r--Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib57
-rw-r--r--Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex175
-rw-r--r--Master/texmf-dist/source/support/bib2gls/src/gls2bib-src.zipbin31437 -> 22054 bytes
-rw-r--r--Master/texmf-dist/source/support/bib2gls/src/texparser-src.zipbin795743 -> 795743 bytes
6 files changed, 234 insertions, 26 deletions
diff --git a/Master/texmf-dist/source/support/bib2gls/src/bib2gls-begin.tex b/Master/texmf-dist/source/support/bib2gls/src/bib2gls-begin.tex
index 6094b036745..1c82b8a2319 100644
--- a/Master/texmf-dist/source/support/bib2gls/src/bib2gls-begin.tex
+++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls-begin.tex
@@ -798,6 +798,25 @@ automated methods provided, such as the abbreviation mechanism
(\sectionref{sec:abbreviations}) or changing the formatting
(\sectionref{sec:glsformats}).
+You can test if an entry has been used with:
+\nosecformatdef{ifglsused}
+This requires that the entry (identified by \meta{label}) is
+defined. If it isn't then neither \meta{true} nor \meta{false} is
+done and an error or warning occurs. Otherwise, the command will do
+\meta{true} if the entry has been used or \meta{false} if the entry
+hasn't been used.
+
+When using \bibgls, entries are never defined on the first \LaTeX\
+run, so you may instead prefer:
+\nosecformatdef{GlsXtrIfUnusedOrUndefined}
+which does \meta{true} if either the entry hasn't been defined or
+hasn't been marked as used, otherwise it does \meta{false}.
+
+Neither \gls{ifglsused} nor \gls{GlsXtrIfUnusedOrUndefined} should
+occur in the \idx{postlinkhook} as the entry will have already
+been used by that point. Instead, you need \gls{glsxtrifwasfirstuse}
+(see \sectionref{sec:postlinkhooks}).
+
\section{Categories}
\label{sec:categories}
@@ -2260,7 +2279,7 @@ Consider the following document:
\cmd{usepackage}\marg{tracklang}
\strut
\cmd{begin}\marg{document}
-\gls{GetTrackedDialectFromLanguageTag}\marg{en-GB}\marg{\cmd{trackeddialect}}%
+\gls{GetTrackedDialectFromLanguageTag}\marg{en-GB}\marg{\cmd{trackeddialect}}\comment{}
Tracked dialect label: \cmd{trackeddialect}.
\gls{IfTrackedDialectHasMapping}\marg{\cmd{trackeddialect}}\comment{}
\marg{Has mapping: \gls{GetTrackedDialectToMapping}\marg{\cmd{trackeddialect}}}\comment{}
@@ -2307,6 +2326,7 @@ captions hook provided by \sty{babel}.
The above document produces:
\begin{result}
en-GB: Tracked dialect label: . No mapping. Root language: .
+
en-MT: Tracked dialect label: maltaenglish. Has mapping: british.
Root language: english.
\end{result}
@@ -2323,7 +2343,7 @@ label doesn't.
\cmd{usepackage}\marg{tracklang}
\strut
\cmd{begin}\marg{document}
-\gls{GetTrackedDialectFromLanguageTag}\marg{de-DE-1996}\marg{\cmd{trackeddialect}}%
+\gls{GetTrackedDialectFromLanguageTag}\marg{de-DE-1996}\marg{\cmd{trackeddialect}}\comment{}
Tracked dialect label: \cmd{trackeddialect}.
\gls{IfTrackedDialectHasMapping}\marg{\cmd{trackeddialect}}\comment{}
\marg{Has mapping: \gls{GetTrackedDialectToMapping}\marg{\cmd{trackeddialect}}}\comment{}
@@ -2396,7 +2416,7 @@ For example:
\end{codeenv}
This essentially uses the earlier \sty{tracklang} code where an
extra \gls{ifdefempty} is inserted, which sets the equivalent of
-\csfmt{trackeddialect} to \gls{TrackedDialectClosestSubMatch}. If
+\csfmt{trackeddialect} in the above to \gls{TrackedDialectClosestSubMatch}. If
the test for the captions hook is false, then \gls{foreignlanguage}
isn't used.
@@ -5233,7 +5253,7 @@ should be defined (unless you want the laborious task of filtering
them out, as in \sectionref{sec:printglossagain}). The \field{group}
field needs setting for every entry, and if the \field{location}
field also needs setting then the \filefmt{entries.tex} file will
-need to be modified every time the document changes cause a shift in
+need to be modified every time new document edits cause a shift in
the page numbers.
With \bibgls, you write all the entry definitions (without the
diff --git a/Master/texmf-dist/source/support/bib2gls/src/bib2gls-src.zip b/Master/texmf-dist/source/support/bib2gls/src/bib2gls-src.zip
index 165db216f11..6302e2da730 100644
--- a/Master/texmf-dist/source/support/bib2gls/src/bib2gls-src.zip
+++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls-src.zip
Binary files differ
diff --git a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib
index 5167ad5fabe..0696be2b875 100644
--- a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib
+++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib
@@ -446,6 +446,20 @@
category={command}
}
+@dualindexentry{bibglssupplementalsublist,
+ name={\csfmt{bib\-gls\-supple\-mental\-sub\-list}},
+ user1={\margm{n}\margm{external document}\margm{list}},
+ description={supplemental sub-list encapsulator},
+ category={command}
+}
+
+@dualindexentry{bibglssupplementalsubsep,
+ name={\csfmt{bib\-gls\-supple\-mental\-sub\-sep}},
+ user1={},
+ description={separator between supplementary sub-lists},
+ category={command}
+}
+
@dualindexentry{glsgroupheading,
name={\csfmt{gls\-group\-heading}},
user1={\margm{label}},
@@ -2382,6 +2396,24 @@ cs}\margm{Glspl-like cs}},
category={command}
}
+@dualindexentry{glsxtrdisplaysupploc,
+ name={\csfmt{gls\-xtr\-display\-supp\-loc}},
+ user1={\margm{prefix}\margm{counter}\margm{format}\margm{src}\margm{location}},
+ description={used to display an external location in the
+ supplementary list},
+ note={provided by \styfmt{glossaries-extra-bib2gls} v1.36+},
+ category={command}
+}
+
+@dualindexentry{glsxtrmultisupplocation,
+ name={\csfmt{gls\-xtr\-multi\-supp\-location}},
+ user1={\margm{location}\margm{src}\margm{format}},
+ description={used by \gls{glsxtrdisplaysupploc} to format the
+ external location},
+ note={provided by \styfmt{glossaries-extra-bib2gls} v1.36+},
+ category={command}
+}
+
@dualindexentry{glsxtr@record,
name={\csfmt{glsxtr@record}},
user1={\margm{label}\margm{prefix}\margm{counter}\margm{format}\margm{location}},
@@ -6481,6 +6513,31 @@ category},
category={command}
}
+@index{ifglsused,
+ name={\csfmt{if\-gls\-used}},
+ user1={\margm{label}\margm{true}\margm{false}},
+ description={does \meta{true} if the entry given by \meta{label} has been
+ used, \meta{false} if the entry hasn't been used and neither
+ if the entry doesn't exist (an error or warning message will
+ occur and ?? will appear in the document).
+ This command is not for use in the post-link hooks},
+ note={provided by \styfmt{glossaries}},
+ seealso={GlsXtrIfUnusedOrUndefined,glsxtrifwasfirstuse},
+ category={command}
+}
+
+@index{GlsXtrIfUnusedOrUndefined,
+ name={\csfmt{Gls\-Xtr\-If\-Un\-used\-Or\-Un\-defined}},
+ user1={\margm{label}\margm{true}\margm{false}},
+ description={does \meta{true} if the entry given by \meta{label}
+hasn't been
+ used or is undefined, otherwise it does \meta{false}.
+ This command is not for use in the post-link hooks},
+ note={provided by \styfmt{glossaries-extra} v1.34+},
+ seealso={ifglsused,glsxtrifwasfirstuse},
+ category={command}
+}
+
@index{glslabel,
name={\csfmt{glslabel}},
user1={},
diff --git a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex
index 39cd070365a..39be41ea2ff 100644
--- a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex
+++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex
@@ -2780,10 +2780,26 @@ you may end up with a mismatched encoding.
\section{Comments}
\label{sec:bibcomments}
-You may have comments within the \ext{bib} file provided they are
-outside of entry definitions. The most common type of comment is the
-encoding comment, described above.
-Avoid using comments within field values.
+The original \ext{bib} file format as defined by \BibTeX\ doesn't
+have a designated comment character, but instead treats anything
+outside of \code{@\meta{entry}\margm{data}} as unwanted material
+that's ignored. This can catch out users who try to do something
+like:
+\begin{verbatim}
+%@misc{sample, title={Sample} }
+\end{verbatim}
+In this case, the percent character is simply discarded and the
+line is treated as:
+\begin{verbatim}
+@misc{sample, title={Sample} }
+\end{verbatim}
+Some applications that parse \ext{bib} files are less tolerant of
+unwanted material. In the case of \bibgls, the percent character is
+treated as a comment character and other unwanted material
+should be omitted. Avoid using comments within field values.
+Comments are best placed outside of entry definitions.
+
+The most common type of comment is the encoding comment, described above.
\section{Fields}
\label{sec:fields}
@@ -8964,9 +8980,12 @@ identified by the \csopt[primary]{save-index-counter} setting.
\section{Supplemental Locations}
\label{sec:supplementalopts}
-\emph{These options require at least version 1.14 of \isty{glossaries-extra}.}
-
-\optsection{supplemental-locations}
+\emph{These options require at least version 1.14 of
+\isty{glossaries-extra}.} If you require locations from multiple
+external sources, then you need at least version 1.36 of
+\isty{glossaries-extra} (or, more specifically,
+\isty{glossaries-extra-bib2gls}, which is automatically loaded
+by the \styopt[only]{record} package option).
The \sty{glossaries-extra} package (from v1.14) provides a way of
manually adding locations in supplemental documents through the use
@@ -9035,9 +9054,35 @@ setting the \catattr{externallocation} attribute and using
and \glsaddopt[glsxtrsupphypernumber]{format}.
This can be simplified with \bibgls\ by using the
-\optfmt{supplemental-locations} option. The value should be the base
-name (without the extension) of the supplementary document
-(\optfmt{suppl} in the above example). For example:
+\optfmt{supplemental-locations} option, described below.
+
+Version 1.36 of \isty{glossaries-extra-bib2gls} introduces some
+special location formatting commands that don't use the
+\catattr{externallocation} attribute, but instead have an extra
+argument that indicates the external reference. The additional
+argument means that it can't be used by the \glsaddopt{format}
+key, but with \bibgls\ you don't use \cs{glsadd} to record
+the external locations. Instead it obtains the records from
+the corresponding supplementary \ext{aux} file, and adjusts the
+location encapsulator as appropriate.
+
+If \bibgls\ detects an older version of \sty{glossaries-extra},
+it will only allow one external supplemental source, and
+will set the \catattr{externallocation} attribute and use
+the \optfmt{glsxtrsupphypernumber} format. Otherwise \bibgls\
+will allow multiple sources and use the newer method.
+
+\optsection{supplemental-locations}
+
+The value should be the base name (without the extension) of the
+supplementary document (\optfmt{suppl} in the above example).
+If you have at least version 1.36 of \sty{glossaries-extra},
+the value may be a comma-separated list of base names (without the
+extensions) of the supplementary documents. If an older version is
+detected, \bibgls\ will issue a warning and only accept the first
+element of the list.
+
+For example:
\begin{verbatim}
\documentclass{article}
@@ -9056,16 +9101,84 @@ name (without the extension) of the supplementary document
\end{document}
\end{verbatim}
The location list for \code{sample} will now be \qt{1, S1} (page~1
-from the main document and S1 from the supplementary document). Note
-that the original location format from the supplementary document
-will be replaced by \optfmt{glsxtrsupphypernumber}, which will
-produce an external hyperlink if the main document loads the
-\isty{hyperref} package. (Note that not all PDF viewers can handle
-external hyperlinks, and some that can open the external PDF file may not
-recognise the destination within that file.)
+from the main document and S1 from the supplementary document).
+
+With \sty{glossaries-extra} v1.36+, the location from the
+supplementary document will be encapsulated with:
+\nosecdef{glsxtrdisplaysupploc}
+By default, this simply creates an external hyperlink to the
+supplementary document with the location as the hyperlink text.
+The hyperlink is created using \meta{src} as the target path
+with the fragment part (anchor) formed from the prefix and
+location. The \catattr{externallocation} attribute is not set in
+this case. The actual formatting is done via
+\nosecdef{glsxtrmultisupplocation}
+which ignores the \meta{format} argument by default. Its
+definition is simply:
+\begin{verbatim}
+\newcommand*{\glsxtrmultisupplocation}[3]{%
+ {% scope required to localise changes
+ \def\glsxtrsupplocationurl{#2}%
+ \glshypernumber{#1}%
+ }%
+}
+\end{verbatim}
+which locally sets the command checked by \ics{glshypernumber}
+to establish an external rather than internal link. You can
+redefine this command to retain the original formatting
+command used in the target document:
+\begin{verbatim}
+\renewcommand*{\glsxtrmultisupplocation}[3]{%
+ {% scope required to localise changes
+ \def\glsxtrsupplocationurl{#2}%
+ \csuse{#3}{#1}%
+ }%
+}
+\end{verbatim}
+but remember that if a hyperlink is required, the identified
+control sequence name must correspond to a command that
+uses \cs{glshyperlink} (such as \cs{hyperbf}), otherwise you
+will lose the hyperlink.
+
+With older versions of \sty{glossaries-extra},
+the original location format from the supplementary document
+will be replaced by \optfmt{glsxtrsupphypernumber}, which
+again produces an external hyperlink. The \catattr{externallocation}
+attribute also needs to be set (this can be done automatically with
+\csopt{supplemental-category}) to identify the external document.
+The original format can't be accessed.
+
+In both cases, if the document hasn't loaded the \isty{hyperref}
+package, the location will simply be displayed without a hyperlink.
+(Note that not all PDF viewers can handle external hyperlinks, and
+some that can open the external PDF file may not recognise the
+destination within that file.)
The supplementary locations lists are encapsulated within
-\gls{bibglssupplemental}.
+\gls{bibglssupplemental}. With \sty{glossaries-extra} v1.36+,
+this command will encapsulate the sub-lists with
+\gls{bibglssupplementalsublist}.
+
+So the above example with an old version of \sty{glossaries-extra}
+(pre 1.36) will set the supplemental location list (which only consists
+of one location) to
+\begin{verbatim}
+\bibglssupplemental{1}{\setentrycounter[I]{section}\glsxtrsupphypernumber{S1}}
+\end{verbatim}
+and the external target must be supplied through the
+\catattr{externallocation} attribute, which can be set
+with the \csopt{supplemental-category} option.
+
+Whereas with at least version 1.36, the list will be
+\begin{verbatim}
+\bibglssupplemental{1}{\bibglssupplementalsublist{1}{suppl.pdf}
+{\glsxtrdisplaysupploc{I}{section}{glsnumberformat}{suppl.pdf}{S1}}}
+\end{verbatim}
+
+If an entry has both a main location list and a supplementary
+location list (such as the \code{sample} entry above), the lists
+will be separated by \csref{bibglssupplementalsep}. The sub-lists
+(when supported) are separated by \csref{bibglssupplementalsubsep}.
\optsection{supplemental-selection}
@@ -9120,10 +9233,6 @@ even though they haven't been used in this document. The
\code{goose} entry used in the supplementary document won't be
included.
-If an entry has both a main location list and a supplementary
-location list (such as the \code{sample} entry above), the lists
-will be separated by \csref{bibglssupplementalsep}.
-
\optsection{supplemental-category}
The \field{category} field for entries containing supplemental location
@@ -12946,6 +13055,22 @@ from a supplementary document are encapsulated within the \meta{list}
part of \gls{bibglssupplemental}. The first argument \meta{n}
(ignored by default) is the number of supplementary locations.
+If multiple supplemental sources are permitted (that is,
+\bibgls\ has detected that the document is using at least
+version 1.36 of \sty{glossaries-extra}), then the \meta{list}
+part will consist of sub-lists for each external source. In this
+case, \meta{n} will be the total number of elements across
+all the sub-lists.
+
+\cssection{bibglssupplementalsublist}
+
+\formatdef{bibglssupplementalsublist}
+If multiple supplemental sources are permitted, this will be used
+to format each sub-list, where \meta{n} (ignored by default)
+is the number of elements in the sub-list, \meta{external document}
+(ignored by default) is the external source and \meta{list}
+is the list of supplementary locations in \meta{external document}.
+
\cssection{bibglssupplementalsep}
\formatdef{bibglssupplementalsep}
@@ -12968,6 +13093,12 @@ or redefined after the resources are loaded:
\renewcommand{\bibglssupplementalsep}{; }
\end{verbatim}
+\cssection{bibglssupplementalsubsep}
+
+\formatdef{bibglssupplementalsubsep}
+The separator between the supplementary
+location sub-lists. By default this is just \csref{bibglsdelimN}.
+
\section{Letter Groups}
\label{sec:lettergroupdefs}
diff --git a/Master/texmf-dist/source/support/bib2gls/src/gls2bib-src.zip b/Master/texmf-dist/source/support/bib2gls/src/gls2bib-src.zip
index 524f52d02c2..65d30f1005c 100644
--- a/Master/texmf-dist/source/support/bib2gls/src/gls2bib-src.zip
+++ b/Master/texmf-dist/source/support/bib2gls/src/gls2bib-src.zip
Binary files differ
diff --git a/Master/texmf-dist/source/support/bib2gls/src/texparser-src.zip b/Master/texmf-dist/source/support/bib2gls/src/texparser-src.zip
index 85ff7c54295..cdeb582956d 100644
--- a/Master/texmf-dist/source/support/bib2gls/src/texparser-src.zip
+++ b/Master/texmf-dist/source/support/bib2gls/src/texparser-src.zip
Binary files differ