From e1d4c31009f278d585fef0c245e25433947518ee Mon Sep 17 00:00:00 2001
From: Karl Berry <karl@freefriends.org>
Date: Mon, 5 Mar 2018 22:13:17 +0000
Subject: bib2gls (5mar18)

git-svn-id: svn://tug.org/texlive/trunk@46850 c570f23f-e606-0410-a88d-b1316a301751
---
 .../source/support/bib2gls/src/bib2gls.tex         | 274 ++++++++++++++++++---
 1 file changed, 243 insertions(+), 31 deletions(-)

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

diff --git a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex
index 8c6e3fedabb..a66a4125ae1 100644
--- a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex
+++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex
@@ -1155,6 +1155,71 @@ 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.
 
+\section{Indexing}
+
+The dual index entries such as \atentry{dualindexentry} (described in
+\sectionref{sec:dualentry}) are designed to provide a way of
+including an entry in both a glossary (with a description) and also
+include the term (without the description) in an index.  Additional
+terms that should only appear in the index can be defined with
+\atentry{index}.  (See, for example, the \exfile{sample-multi1.tex}
+and \exfile{sample-multi2.tex} sample files.)
+
+Although \bibgls\ is designed to create indexes as well as glossary
+lists using the same interface (\cs{gls} etc), it is
+possible to have a mixture of \bibgls\ and \ics{index}. For example:
+\begin{verbatim}
+\documentclass{report}
+
+\usepackage{makeidx}
+\usepackage[record]{glossaries-extra}
+
+\makeindex
+\GlsXtrLoadResources[src={entries}]
+
+\glssetcategoryattribute{general}{dualindex}{true}
+\glssetcategoryattribute{symbol}{dualindex}{true}
+\glssetcategoryattribute{abbreviation}{dualindex}{true}
+
+\glssetcategoryattribute{general}{indexname}{hyperbf}
+\glssetcategoryattribute{symbol}{indexname}{hyperbf}
+\glssetcategoryattribute{abbreviation}{indexname}{hyperbf}
+
+\begin{document}
+\chapter{Example}
+\gls{bird}, \gls{html}, $\gls{v}$ and \glspl{goose}.
+
+\printunsrtglossaries
+\printindex
+\end{document}
+\end{verbatim}
+If the document is called \filefmt{myDoc.tex} then the document
+build is:
+\begin{verbatim}
+pdflatex myDoc
+bib2gls myDoc
+pdflatex myDoc
+makeindex myDoc.idx
+pdflatex myDoc
+\end{verbatim}
+This requires an additional \LaTeX\ call between \bibgls\ and
+\idx{makeindex} since the entries must be defined before they can be
+indexed (and they can't be defined until \bibgls\ creates the
+associated \ext{glstex} files).
+
+Note that this method will use the \field{sort} value obtained by \bibgls\
+as the \meta{sort} part within
+\code{\cs{index}\marg{\meta{sort}@\meta{actual}}}.
+Be careful if you use \idx{makeindex} as this can result in Unicode
+characters appearing in the sort value, which \idx{makeindex}
+doesn't support.
+The \meta{actual} part is given by
+\code{\ics{glsentryname}\margm{label}}.
+(You can change the \meta{sort} and \meta{actual} parts by
+redefining \ics{glsxtrautoindexassignsort} and
+\ics{glsxtrautoindexentry}. See the \sty{glossaries-extra} manual
+for further details.)
+
 \section{Security}
 
 \TeX\ Live come with security settings
@@ -1208,6 +1273,59 @@ the correct translation (in English, this would be
 \csopt[Page\dcomma Pages]{loc-prefix}). The default definition of
 \csref{bibglspassim} is also obtained from the resource file.
 
+\section{Conditional Document Build}
+
+If you are using a document build method that tries to determine
+whether or not \bibgls\ should be run, you can find the information
+by searching the \iext{aux} file for instances of
+\nosecdef{glsxtr@resource}
+Each instance corresponds to an instance of \gls{glsxtrresourcefile}
+where \meta{filename} is the base name of the \iext{glstex} file
+that \bibgls\ needs to create for this resource set. If the
+\meta{options} part is missing the \csopt{src} option, this also indicates 
+the base name for the \iext{bib} file.
+
+So the simplest check to determine if \bibgls\ needs to be run is to test
+if the \iext{aux} file contains \gls{glsxtr@resource}. For
+example, with \idx{arara} version 4.0:
+\begin{codeenv}
+\% arara: bib2gls if found("aux", "glsxtr@resource")
+\end{codeenv}
+A sophisticated method could check if
+\meta{filename}\ext{glstex} is missing or is older than the document
+\ext{tex} file for each instance of \gls{glsxtr@resource} found in
+the \ext{aux} file.
+
+It might also be possible, although far more complex, to
+parse the \meta{options} part in each instance of \gls{glsxtr@resource}
+for \csopt{src} and determine if the corresponding \ext{bib} file or
+files are newer than the \ext{tex} file.
+
+It's not possible to determine if the location lists require
+updating, just as it's not possible to do this for the table of
+contents, list of figures, list of tables etc. (Or, if it could be
+implemented, the required code would make the document build far more
+complicated.)
+
+In general, the basic algorithm is:
+\begin{enumerate}
+\item If \gls{glsxtr@resource} is found in the \ext{aux} file then:
+
+   \begin{enumerate}
+   \item run \bibgls;
+   \item run \LaTeX\ (or PDF\LaTeX\ etc).
+   \end{enumerate}
+
+\item If \idx{@istfilename} is found in the \ext{aux} file then:
+
+   \begin{enumerate}
+   \item run \idx{makeglossaries} (or \idx{makeglossaries-lite});
+   \item run \LaTeX\ (or PDF\LaTeX\ etc).
+   \end{enumerate}
+
+\end{enumerate}
+This allows for the \styopt[alsoindex]{record} package option.
+
 \section{Manual Installation}
 
 If you are unable to install \bibgls\ through your \TeX\ package
@@ -1349,7 +1467,8 @@ following packages:
 \isty{wasysym}, \isty{lipsum}, \isty{natbib}, \isty{mhchem}, 
 \isty{bpchem}, \isty{stix}, \isty{textcomp}, \isty{MnSymbol}, 
 \isty{fourier}, \isty{upgreek}, \isty{xspace}, \isty{siunitx}, 
-\isty{fontenc} and \isty{tipa}. If you're wondering about the
+\isty{fontenc} and \isty{tipa}. (You can omit checking for specific
+packages with \longarg{ignore-packages}.) If you're wondering about the
 selection, the \file{texparserlib.jar} library was originally written for
 another application that required support for some of them. There
 are a few other packages that the library supports (see
@@ -1832,7 +1951,8 @@ if available (default). For example,
 \begin{verbatim}
 \textsuperscript{(2)}
 \end{verbatim}
-will be converted to \hex{207D} (superscript left parenthesis)
+will be converted to \code{\textsuperscript{(2)}}, which consists
+of: \hex{207D} (superscript left parenthesis)
 \hex{00B2} (superscript two) \hex{207E} (superscript right
 parenthesis). If the entire contents of the argument can't be
 represented by Unicode characters, the interpreter uses \verb|<sup>|
@@ -1882,6 +2002,17 @@ using a command from a package that the interpreter doesn't support
 but it happens to have the same name and meaning as a command from
 a package that the interpreter does support.
 
+\argsection{ignore-packages}
+
+This option is cumulative. When the document \iext{log} file is
+parsed for known packages, \bibgls\ will skip the check for any
+listed in \meta{list}. Note that this option simply instructs
+\bibgls\ to ignore the package information in the log file. Any packages
+that are identified with \longarg{packages} will be passed to the
+interpreter if support is available, even if the package is also
+listed in \longargfmt{ignore-packages}.  Note that
+\sty{glossaries-extra} can't be included in the ignored \meta{list}.
+
 \argsection{mfirstuc-protection}
 
 Commands like \ics{Gls} use \ics{makefirstuc} provided by the
@@ -2263,7 +2394,7 @@ The glossary won't have groups even if a group style, such as
 \bibgls\ tries to determine the character encoding to use for the
 output files. If the document has loaded the \isty{inputenc} package then
 \bibgls\ can obtain the value of the encoding from the
-\iext{aux} file. This then needs to be converted to a name
+\iext{aux} file. This is then converted to a name
 recognised by Java. For example, \code{utf8} will be mapped to
 \code{UTF-8}. If the \isty{fontspec} package has been loaded,
 \styfmt{glossaries-extra} will assume the encoding is \code{utf8} and
@@ -2273,7 +2404,27 @@ If neither package has been loaded, \bibgls\ will assume the
 operating system's default encoding. If this is incorrect or if
 \bibgls\ can't work out the appropriate mapping then you can specify
 the correct encoding using \longargfmt{tex-encoding} \meta{name}
-where \meta{name} is the encoding name.
+where \meta{name} is the encoding name (such as \code{UTF-8}).
+
+If you have a problem with non-ASCII characters not displaying
+correctly in your document:
+\begin{itemize}
+\item Check that the file encoding of your document \ext{tex} file (or files)
+has been correctly set by your text editor.
+\item Check that your document supports that encoding (for example,
+through the \isty{inputenc} package).
+\item Check \bibgls's transcript file (\ext{glg}) for the line that
+starts
+\begin{verbatim}
+TeX character encoding:
+\end{verbatim}
+This should be followed by the encoding used by \bibgls\ when
+creating the \ext{glstex} files. If this is incorrect use
+\longargfmt{tex-encoding}.
+\item Check that the encoding of the \ext{bib} files (set by your
+text editor or bibliographic management system) matches the encoding
+line in the \ext{bib} file or the \csopt{charset} resource option.
+\end{itemize}
 
 \argsection{no-expand-fields}
 
@@ -2284,7 +2435,7 @@ This is useful if constructing field values programmatically
 commands are included in the field. 
 
 The switch \longarg{no-expand-fields} makes \bibgls\ write
-\ics{glsnoexpandfields} to the \iext{glstex} file, which
+\gls{glsnoexpandfields} to the \iext{glstex} file, which
 switches off the expansion.  Since \bibgls\ is simply
 fetching the data from \iext{bib} files, it's unlikely 
 that this automatic expansion is required and since it can
@@ -2293,12 +2444,11 @@ switch it off with \longarg{expand-fields}.
 
 \argsection{expand-fields}
 
-Don't write \ics{glsnoexpandfields} to the \iext{glstex} file,
+Don't write \gls{glsnoexpandfields} to the \iext{glstex} file,
 allowing fields to expand when the entries are defined.
 Remember that this doesn't include the \field{name}, \field{symbol}
 or \field{description} fields, which need to have their
-expansion switched on with
-\nosecdef{glssetexpandfield}
+expansion switched on with \gls{glssetexpandfield}
 before the entries are defined (that is, before using
 \gls!{GlsXtrLoadResources}).
 
@@ -10394,6 +10544,10 @@ This is a boolean setting that determines whether or not primary and
 dual entries should be considered mutual dependencies. The default value is
 \csopt[true]{primary-dual-dependency}, which means that if a primary
 has records then the dual is added as a dependency and vice versa.
+The setting \csopt[false]{primary-dual-dependency} can't be used
+with \csopt[none]{dual-sort} or \csopt[use]{dual-sort} (but may be
+used with \csopt[combine]{dual-sort} and \csopt[none]{sort} or
+\csopt[use]{sort}).
 
 \optsection[\subsubsection]{combine-dual-locations}
 
@@ -12682,6 +12836,13 @@ sort value than either \idx!{makeindex} or \idx!{xindy}.
 
 \item[\longargfmt{no-ignore-sort}] Don't ignore the \field{sort} field.
 
+\item[\longargfmt{silent}] Suppress all messages except for errors.
+
+\item[\longargfmt{verbose}] Display messages and warnings (default).
+
+\item[\longargfmt{debug}] Display debugging messages (stack
+traces and other information in addition to \longargfmt{verbose}).
+
 \item[\longargfmt{help} or \shortargfmt{h}] Display help message and
 quit.
 \item[\longargfmt{version} or \shortargfmt{v}] Display version
@@ -12690,7 +12851,10 @@ information and quit.
 
 This application recognises the commands listed below. Avoid any
 overly complicated code within the \ext{tex} file. The \TeX\ parser
-library isn't a \TeX\ engine!
+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.
 In all cases below, if \meta{\keyvallist} contains
 \begin{alltt}
 see=[\ics{seealsoname}]\margm{label(s)}
@@ -12722,6 +12886,38 @@ 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}
+The base \styfmt{glossaries} package provides:
+\formatdef{glsexpandfields}
+If present, this instructs \idx{convertgls2bib} to expand all fields
+except for those explicitly identified by \gls{glssetnoexpandfield}.
+Remember that there are many commands that aren't recognised by
+\idx{convertgls2bib} so it may not be possible to correctly expand
+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}
+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}
+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}
+The base \styfmt{glossaries} package provides:
+\formatdef{glssetnoexpandfield}
+If present, this instructs \idx{convertgls2bib} to not expand the
+given field, even if \gls{glsexpandfields} has been used.
+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}
 The base \styfmt{glossaries} package provides:
 \formatdef{newglossaryentry}
@@ -15537,7 +15733,7 @@ round so that the short form is shown first, which conveniently
 matches the default \csopt{abbreviation-sort-fallback}.
 \begin{verbatim}
 \renewcommand*{\glsxtrlongshortdescname}{%
-  \protect\protect\glsabbrvfont{\the\glsshorttok}\space
+  \protect\glsabbrvfont{\the\glsshorttok}\space
   \glsxtrparen{\glslongfont{\the\glslongtok}}%
 }
 \end{verbatim}
@@ -16410,12 +16606,28 @@ The dual entry's label is easily obtained because \csopt{dual-field}
 has provided the \fieldfmt{dual} internal field and set it to the
 corresponding label.
 
-The complete document code is listed below. The document build is:
+It's sometimes useful for the index to include a reference to the
+term's definition. This can be done by making use of 
+\idx{glsextrapostnamehook}, which can be redefined before the
+glossaries to automatically record each entry:
+\begin{verbatim}
+\renewcommand{\glsextrapostnamehook}[1]{\glsadd[format=hyperbf]{#1}}
+\end{verbatim}
+This needs to be redefined to ignore its argument before the index,
+to avoid the redundant index record:
 \begin{verbatim}
+\renewcommand{\glsextrapostnamehook}[1]{}
+\end{verbatim}
+Remember that if any records are added within a glossary, an extra
+\LaTeX\ and \bibgls\ call are required, so the document build is:
+\begin{verbatim}
+pdflatex sample-multi1
+bib2gls --group sample-multi1
 pdflatex sample-multi1
 bib2gls --group sample-multi1
 pdflatex sample-multi1
 \end{verbatim}
+The complete document code is listed below. 
 The resulting document is shown in \figureref{fig:sample-multi1.pdf}
 and \figureref{fig:sample-multi1.pdf2}.
 
@@ -16464,12 +16676,12 @@ example, so it has extra glossaries, which all need to be defined:
 \newglossary*{information}{Information Symbols}
 \newglossary*{weather}{Weather Symbols}
 \end{verbatim}
-Note that this is a total of 15 (including the \code{index})
-glossaries. With the \ics{makeglossaries} method, this would require
-16 write registers (including the write register used to create the
-indexing style file), and a total of $15\times3 + 1 = 46$ associated
-files. (This doesn't include the standard \ext{aux} file and the
-\ext{out} file created by \sty{hyperref}.) With \bibgls, no
+Note that this is a total of 15~glossaries (including the
+\code{index}). With the basic \ics{makeglossaries} method, this would
+require 16 write registers (including the write register used to
+create the indexing style file), and a total of $15\times3 + 1 = 46$
+associated files. (This doesn't include the standard \ext{aux} file
+and the \ext{out} file created by \sty{hyperref}.) With \bibgls, no
 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$).
@@ -16623,7 +16835,7 @@ Next come the chemical formulae:
  \csopt[
    identifier=category,
    formula=name,
-   chemicalname=description,
+   chemicalname=description
  ]{field-aliases},
  \csopt[chemical]{type},
  \csopt{set-widest},
@@ -16636,18 +16848,18 @@ and the \idxpl{SIunit}, which are now combined into a single
 glossary:
 \begin{codeenv}
 \gls{GlsXtrLoadResources}\oarg{
- src={baseunits,derivedunits},
+ \csopt[baseunits,derivedunits]{src},
  \csopt[measurement=symbol,unit=symbol]{entry-type-aliases},
- field-aliases={
+ \csopt[
    unitname=description,
    unitsymbol=symbol,
    measurement=name
- },
- category={measurement},
- type={measurement},
- set-widest,
- symbol-sort-fallback={name},
- save-locations=false
+ ]{field-aliases},
+ \csopt[measurement]{category},
+ \csopt[measurement]{type},
+ \csopt{set-widest},
+ \csopt[name]{symbol-sort-fallback},
+ \csopt[false]{save-locations}
 }
 \end{codeenv}
 Here the \field{name} field is obtained from the custom
@@ -16764,7 +16976,7 @@ style (that is, the abbreviations with the \field{category} set to
 \meta{long} (\meta{short}):
 \begin{verbatim}
 \renewcommand*{\glsxtrlongshortdescname}{%
-  \protect\protect\glslongfont{\the\glslongtok}\space
+  \protect\glslongfont{\the\glslongtok}\space
   \glsxtrparen{\glsabbrvfont{\the\glsshorttok}}%
 }
 \end{verbatim}
@@ -16934,10 +17146,10 @@ entries without worrying about the prefixes:
 \cs{glsxtrnewgls}\marg{film.}\marg{\csfmt{film}}
 \end{codeenv}
 
-It would be useful to include the page where the entries are defined
-in their corresponding lists. This can be done by redefining the
-general purpose non-category post-name hook
-\ics{glsextrapostnamehook}:
+As with \exfile{sample-multi1.tex}, it would be useful to include
+the page where the entries are defined in their corresponding lists.
+Again this can be done by redefining the general purpose
+non-category post-name hook \ics{glsextrapostnamehook}:
 \begin{verbatim}
 \newcommand*{\glsextrapostnamehook}[1]{%
   \glsadd[format=hyperbf]{#1}%
-- 
cgit v1.2.3

