From 9427dfbe861b203ec9fe309a1d590644668f2630 Mon Sep 17 00:00:00 2001
From: Karl Berry <karl@freefriends.org>
Date: Sun, 5 May 2019 18:06:25 +0000
Subject: bib2gls (10apr19)

git-svn-id: svn://tug.org/texlive/trunk@51008 c570f23f-e606-0410-a88d-b1316a301751
---
 .../source/support/bib2gls/src/bib2gls-begin.tex   | 136 ++++++++++++---------
 1 file changed, 81 insertions(+), 55 deletions(-)

(limited to 'Master/texmf-dist/source/support/bib2gls/src/bib2gls-begin.tex')

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 df2ef53ae03..f30604e4bad 100644
--- a/Master/texmf-dist/source/support/bib2gls/src/bib2gls-begin.tex
+++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls-begin.tex
@@ -18,6 +18,7 @@
 \usepackage{hologo}
 \usepackage{pifont}
 \usepackage{graphicx}
+\usepackage{tcolorbox}
 \usepackage{datetime2}
 \usepackage{siunitx}
 \usepackage[version=4]{mhchem}
@@ -78,10 +79,17 @@
 
 \newcommand*{\csref}{\gls}
 
+\newcommand{\texparserdefnote}{}
+
 \GlsXtrLoadResources[
  src={bib2gls},
  max-loc-diff=3,
- entry-type-aliases={dualindexentry=index},
+ entry-type-aliases={
+  exampleentry=entry,
+  examplesymbol=symbol,
+  exampleabbreviation=abbreviation
+ },
+ unknown-entry-alias={index},
  field-aliases={note=user2},
  symbol-sort-fallback={name},
  break-at={none},
@@ -208,21 +216,33 @@
 
 \makeatletter
 \newcommand{\code}[1]{\texorpdfstring{{\ttfamily\obeyspaces #1}}{#1}}
-\newenvironment{codeenv}
- {%
-   \renewcommand{\glslinkpresetkeys}{\setkeys{glslink}{noindex}}%
+\newcommand{\setupcodeenvfmts}{%
    \def\cmd{\char`\\}%
-   \def\comment##1{\textcolor{comment}{\%\ ##1}}%
+   \def\comment##1{\mbox{\textcolor{comment}{\idx{commentchar}\ ##1}}}%
    \renewcommand*{\styfmt}[1]{##1}%
    \renewcommand*{\counterfmt}[1]{##1}%
    \renewcommand*{\catattrfmt}[1]{\textcolor{attribute}{##1}}%
    \renewcommand*{\abbrstylefmt}[1]{\textcolor{style}{##1}}%
    \renewcommand*{\csfmtfont}[1]{\textcolor{cs}{##1}}%
+}
+\newenvironment{codeenv}
+ {%
+   \renewcommand{\glslinkpresetkeys}{\setkeys{glslink}{noindex}}%
+   \setupcodeenvfmts
     \begin{flushleft}\textcolor{lightgray}{\hrulefill}\par\nopagebreak
      \medskip\nopagebreak
      \ttfamily\obeylines\frenchspacing\@vobeyspaces}
  {\nopagebreak\textcolor{lightgray}{\hrulefill}%
   \end{flushleft}\ignorespacesafterend}
+
+\newenvironment{codeenv*}
+ {%
+   \setupcodeenvfmts
+   \begin{flushleft}\ttfamily\obeylines\frenchspacing\@vobeyspaces
+   \parindent\z@\parfillskip\@flushglue\parskip\z@skip
+ }
+ {\end{flushleft}\ignorespacesafterend}
+
 \makeatother
 
 \newcommand{\primary}{\emph}
@@ -255,7 +275,7 @@
 }
 
 \newcommand*{\abbrstyle}[2][]{%
-  \texorpdfstring{\idx[#1]{#2}}{#2}%
+  \texorpdfstring{\idx[#1]{abbrstyle.#2}}{#2}%
 }
 
 \newcommand*{\glostyle}[1]{%
@@ -263,7 +283,7 @@
 }
 
 \newcommand*{\catattr}[1]{%
-  \texorpdfstring{\idx{#1}}{#1}%
+  \texorpdfstring{\idx{catattr.#1}}{#1}%
 }
 
 \newcommand*{\counter}[1]{%
@@ -373,24 +393,7 @@
   \ignorespacesafterend
 }
 
-\newenvironment{important}{%
-  \setlength{\fboxrule}{4pt}%
-  \setlength\borderedboxwidth{\linewidth}%
-  \addtolength\borderedboxwidth{-2\fboxsep}%
-  \addtolength\borderedboxwidth{-2\fboxrule}%
-  \begin{lrbox}{\borderedboxcontents}%
-    \begin{minipage}{\borderedboxwidth}%
-    \raggedright
-    \setlength\parindent{1em}%
-    \noindent\ignorespaces
-}%
-{%
-    \end{minipage}%
-  \end{lrbox}%
-  \par\vskip10pt\noindent
-  \fcolorbox{red}{white}{\usebox{\borderedboxcontents}}\par\vskip10pt
-  \noindent\ignorespacesafterend
-}
+\newtcolorbox{important}{colback=red!5!white,colframe=red}
 
 \newcommand*{\sectionref}[1]{section~\ref{#1}}
 \newcommand*{\Sectionref}[1]{Section~\ref{#1}}
@@ -457,6 +460,7 @@ the \isty{glossaries-extra} user manual,
 package~\cite{glossaries-extra})
 and the \isty{glossaries} user manual
 (distributed with the \sty{glossaries} package~\cite{glossaries}).
+See also the gallery~\cite{gallery} for examples.
 
 The \sty{glossaries} package is the \emph{base} package. The 
 \sty{glossaries-extra} package internally loads the \sty{glossaries} package 
@@ -535,9 +539,20 @@ can be found in the \isty{glossaries} user manual.  The
 are described in the \sty{glossaries-extra} manual. The \bibgls\
 user manual summarises all keys (fields) in \sectionref{sec:fields}.
 
+The term \qt{field} not only includes the keys that may be used with
+\gls{newglossaryentry} but also internal labels (which may or may
+not have a corresponding key) that are used to store information.
+Note that there are some fields that may be used in the document
+that are considered internal fields by \bibgls\ because the field
+value is typically set as a by-product of the way that \bibgls\
+works. If these fields are set manually then you may get unexpected
+results as this can break \bibgls's normal operation.
+
 \begin{important}
 If the field value contains commas or equal signs the value must be grouped
 to hide those characters from the \meta{key}\dequals\meta{value} parser.
+When using \bibgls, the field value must be delimited according to
+the \ext{bib} file format.
 \end{important}
 
 The two main keys are \field{name} and \field{description}. The
@@ -850,8 +865,8 @@ value of the \field{category} field using:
 \nosecformatdef{glsifcategory}
 This checks if the \field{category} field for the entry given by
 \meta{label} is set to \meta{category}, but doesn't perform any
-expansion. It generates an error if the entry doesn't exist (or
-warning with \styopt[warn]{undefaction}).
+expansion of \meta{category}. It generates an error if the entry
+doesn't exist (or warning with \styopt[warn]{undefaction}).
 
 The category allows you to apply certain types of formatting, such
 as the \idx{postlinkhook} (\sectionref{sec:postlinkhooks}).
@@ -921,7 +936,7 @@ associated image or citation, then you can supply this with the six
 user keys:
 \field{user1}\glsaddeach{field.user2,field.user3,field.user4,field.user5}, 
 \ldots, \field{user6}. The value of the
-first field can be obtained with:
+first field (\field{user1}) can be obtained with:
 \nosecformatdef{glsuseri}
 (which behaves like \gls{glssymbol}) or with:
 \nosecformatdef{glsentryuseri}
@@ -929,7 +944,7 @@ first field can be obtained with:
 \glsaddeach{glsuserii,glsuseriii,glsuseriv,glsuserv,%
 glsentryuserii,glsentryuseriii,glsentryuseriv,glsentryuserv}%
 The other fields are similarly obtained using \idx{lowercase} Roman
-numerals, so the sixth field can be obtained with:
+numerals, so value of the sixth field (\field{user6}) can be obtained with:
 \nosecformatdef{glsuservi}
 (which behaves like \gls{glssymbol}) or with:
 \nosecformatdef{glsentryuservi}
@@ -1443,7 +1458,7 @@ definition. For example, consider the following document:
 \end{codeenv}
 In this case, \csfmt{test} is expandable. Its definition doesn't
 contain anything complicated. The \ext{toc} file (which is input by
-\csfmt{tableofcontents}) contains the line:
+\csfmt{tableofcontents}\glsadd{toc}) contains the line:
 \begin{codeenv}
 \cmd{contentsline} \marg{section}\marg{\cmd{numberline} \marg{1}some sample text}\marg{1}
 \end{codeenv}
@@ -1519,7 +1534,7 @@ expansion, which makes the command behave as though it was robust:
 \gls{section}\marg{\gls{Gls}\marg{duck}\gls{protect}\gls{footnote}\marg{\gls{glsentrydesc}\marg{duck}}}
 \end{codeenv}
 In this case, it's unlikely that you'd want the footnote to appear
-in the table of contents, so it would be better to use the optional
+in the \gls{toc}, so it would be better to use the optional
 argument:
 \begin{codeenv}
 \gls{section}\oarg{Duck}\marg{\gls{Gls}\marg{duck}\gls{footnote}\marg{\gls{glsentrydesc}\marg{duck}}}\correct
@@ -1580,9 +1595,9 @@ with webbed feet}\marg{1}
 
 \begin{important}
 The examples in this section are used to illustrate the differences
-between \idx{robust}, \idx{fragile} and \idx{expandable} commands.
+between \idx{fragile}, \idx{robust} and \idx{expandable} commands.
 In general, it's better not to use commands like \gls{gls} in
-headings or captions (see \sectionref{sec:headings}) and using
+headings or captions (see \sectionref{sec:headings}). Using
 commands like \gls{gls} in field values can be problematic (see
 \sectionref{sec:nested}).
 \end{important}
@@ -1635,7 +1650,7 @@ or the expansion must first be switched off:
 Since it's not possible to programmatically define entries with
 \bibgls, the expansion is automatically switched off as \bibgls\
 writes \gls{glsnoexpandfields} to the \ext{glstex} file (although
-you can switch this feature off with \longarg{expand-fields}).
+you can disable this feature with \longarg{expand-fields}).
 
 The reason why \gls{footnote} didn't cause a problem in the
 \field{description} field \emph{when the entry was defined} is that, by
@@ -1687,10 +1702,10 @@ where \meta{category} is the category label and \meta{style-name} is
 the name of the style. If the optional argument is omitted,
 \code{abbreviation} is assumed. The \sty{glossaries-extra} package
 automatically sets the default styles:
-\begin{codeenv}
+\begin{codeenv*}
 \gls{setabbreviationstyle}\marg{\abbrstyle{long-short}}
 \gls{setabbreviationstyle}\oarg{acronym}\marg{\abbrstyle{short-nolong}}
-\end{codeenv}
+\end{codeenv*}
 This means that if you don't explicitly set the style then any
 abbreviation defined with \gls{newacronym} will use the
 \abbrstyle{short-nolong} style (unless you change the category in
@@ -1893,7 +1908,8 @@ This is essentially the same as
 \gls{newabbreviation}\marg{ssl}\marg{SSL}\marg{\gls{glsxtrword}\marg{Secure}\gls{glsxtrwordsep}
 \gls{glsxtrword}\marg{Sockets}\gls{glsxtrwordsep}\gls{glsxtrword}\marg{Layer}}
 \end{codeenv}
-This is typically used with the \code{-hyphen} abbreviation styles.
+This is typically used with the \code{-hyphen} abbreviation styles,
+such as \abbrstyle{long-hyphen-short-hyphen}.
 If the final optional \meta{insert} argument of commands like
 \gls{gls} starts with a hyphen, \gls{glsxtrwordsep} is locally
 changed to a hyphen.
@@ -1904,7 +1920,7 @@ For example:
 \strut
 \cmd{usepackage}\marg{glossaries-extra}
 \strut
-\gls{setabbreviationstyle}\marg{\gls[noindex=false]{long-hyphen-short-hyphen}}
+\gls{setabbreviationstyle}\marg{\abbrstyle[noindex=false]{long-hyphen-short-hyphen}}
 \strut
 \gls{glssetcategoryattribute}\marg{abbreviation}\marg{\catattr{markwords}}\marg{true}
 \strut
@@ -2126,7 +2142,7 @@ For example:
 \gls{glssetcategoryattribute}\marg{initialism}\marg{\catattr{discardperiod}}\marg{true}
 \gls{glssetcategoryattribute}\marg{initialism}\marg{\catattr{retainfirstuseperiod}}\marg{true}
 \strut
-\gls{setabbreviationstyle}\oarg{initialism}\marg{\gls[noindex=false]{short-long}}
+\gls{setabbreviationstyle}\oarg{initialism}\marg{\abbrstyle[noindex=false]{short-long}}
 \strut
 \gls{newabbreviation}\oarg{\field{category}=initialism}
  \marg{gp}\marg{GP}\marg{General Practitioner}
@@ -2784,7 +2800,7 @@ example:
 \begin{codeenv}
 \gls{printunsrtglossary}\oarg{\printglossopt[Nomenclature]{title}}
 \end{codeenv}
-The title used in the table of contents is assumed to be the same,
+The title used in the \gls{toc} is assumed to be the same,
 but you can change it with \printglossopt{toctitle}. For example:
 \begin{codeenv}
 \gls{printunsrtglossary}\oarg{
@@ -2934,6 +2950,16 @@ order of definition.
 \subsection{Groups and Locations}
 \label{sec:group}
 
+\begin{important}
+The \field{group} and \field{location} fields are considered
+internal fields by \bibgls. They may be referenced within the
+document, but they should not be assigned in the \ext{bib} file.
+\bibgls\ assigns these fields according to the resource options and
+command line switches. Explicitly assigning them can cause
+unexpected results. See also \sectionref{sec:logicaldivisions} of
+the \bibgls\ manual.
+\end{important}
+
 The \field{group} key isn't defined by default, but if it is defined
 then \gls{printunsrtglossary} will use the \field{group} field
 instead of trying to determine the group from the first character of
@@ -3931,7 +3957,7 @@ gallery}~\cite{gallery} for further ideas.)
 
 The above example uses the \catattr{glossname} attribute to convert the first
 letter of the \field{name} to \idx{uppercase}. Unfortunately this can't be
-applied to the PDF bookmark or table of contents. A solution to this
+applied to the PDF bookmark or \gls{toc}. A solution to this
 would be to explicitly set the \field{name} with the first letter as
 an \idx{uppercase} character and the \field{text} field in
 \idx{lowercase}. For example:
@@ -4646,7 +4672,7 @@ The arguments of sectioning commands (such as \gls{chapter} or
 \gls{section}) and of captions (\gls{caption}) are
 \pidxpl{moving-argument}. The text is not only displayed at the
 point in the document where the command occurs, but may also be
-copied to the table of contents or list of figures etc.
+copied to the \gls{toc} or list of figures etc.
 Additionally, depending on the page style, the section argument may
 also be reproduced in the page header. This repeated use of the same
 material can cause complications, in particular it can prematurely
@@ -4698,7 +4724,7 @@ enough text to trigger a page break) but does cause unexpected output:
 Reference \gls{gls}\marg{html}.
 \cmd{end}\marg{document}
 \end{codeenv}
-On the first \LaTeX\ run, the table of contents is empty as the
+On the first \LaTeX\ run, the \gls{toc} is empty as the
 associated \ext{toc} file didn't exist at the start. The chapter title
 appears as \qt{A chapter about hypertext markup language
 (\textsc{html})}, which shows the \idx{firstuse} of
@@ -4707,10 +4733,10 @@ but not read by \gls{tableofcontents}) now contains:
 \begin{codeenv}
 \cmd{contentsline} \marg{chapter}\marg{\cmd{numberline} \marg{1}A chapter about \gls{gls} \marg{html}}\marg{3}
 \end{codeenv}
-This means that on the next \LaTeX\ run, the table of contents now
-includes \code{\gls{gls}\marg{html}}. Since the table of contents
+This means that on the next \LaTeX\ run, the \gls{toc} now
+includes \code{\gls{gls}\marg{html}}. Since the \gls{toc}
 occurs at the start of the document, this is now the \idx{firstuse}
-of \code{html}, so the full form is shown in the table of contents,
+of \code{html}, so the full form is shown in the \gls{toc},
 but the chapter title is now \qt{A chapter about \textsc{html}}, which shows
 the subsequent use.
 
@@ -4746,7 +4772,7 @@ Reference \gls{gls}\marg{html}.
 \cmd{lipsum} \comment{dummy text}
 \cmd{end}\marg{document}
 \end{codeenv}
-This now shows the long form in the table of contents and the
+This now shows the long form in the \gls{toc} and the
 chapter title. Since \gls{glsfmtlong} doesn't affect the
 \idx{firstuseflag}, the reference after the chapter title now shows
 the \idx{firstuse} full form. There's no longer an error with the
@@ -4762,7 +4788,7 @@ This can be corrected by setting the \catattr{headuc} attribute to
 \end{codeenv}
 This now makes the page header too long, but remember that you can
 use the optional argument of sectioning commands to provide a
-shorter form for both the page heading and table of contents:
+shorter form for both the page heading and \gls{toc}:
 \begin{codeenv}
 \gls{chapter}\oarg{A chapter about \gls{glsfmtshort}\marg{html}}\marg{A chapter about 
 \gls{glsfmtlong}\marg{html}}
@@ -4772,7 +4798,7 @@ One final problem remains and it's due to the
 to display the short form in small capitals. The combination of
 italic and small capitals isn't supported with the default fonts and
 results in a font substitution. There's a similar problem in the 
-table of contents which displays the chapter title in bold. There's 
+\gls{toc} which displays the chapter title in bold. There's 
 a warning at the end of the transcript:
 \begin{verbatim}
 Some font shapes were not available, defaults substituted.
@@ -4793,17 +4819,17 @@ which is used by the \qt{sc} abbreviation styles:
 \end{codeenv}
 This uses:
 \nosecformatdef{glsxtrifinmark}
-which expands to \meta{true} in headings and the table of contents,
+which expands to \meta{true} in headings and the \gls{toc},
 otherwise it expands to \meta{false}. This use of
 \gls{MakeTextUppercase} replaces the need for the \catattr{headuc}
 attribute. Both \catattr{headuc} and the above redefinition of
 \gls{glsabbrvscfont} will cause the abbreviation to appear in
-\idx{uppercase} in the table of contents. If you don't want this,
-you can defer making these modifications until after the table of
-contents. Alternatively, use:
+\idx{uppercase} in the \gls{toc}. If you don't want this,
+you can defer making these modifications until after the 
+\gls{toc}. Alternatively, use:
 \nosecformatdef{glsxtrRevertTocMarks}
-which makes \gls{glsxtrifinmark} expand to \meta{false} in the table
-of contents.  For example:
+which makes \gls{glsxtrifinmark} expand to \meta{false} in the 
+\gls{toc}.  For example:
 \begin{codeenv}
 \cmd{documentclass}\marg{book}
 \strut
-- 
cgit v1.2.3

