glossaries-extra (9sep17)

git-svn-id: svn://tug.org/texlive/trunk@45251 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 111 insertions, 31 deletions

diff --git a/Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex b/Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex
index ff6387e5686..e6f12508fea 100644
--- a/Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex
+++ b/Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex
@@ -77,8 +77,9 @@ sort={bib2gls},%
 text={\appfmt{bib2gls}\iapp{bib2gls}},%
 description={A command line Java application that selects
 entries from a .bib file and converts them to glossary
-definitions. At the time of writing, this application
-is still under development. Further details at:
+definitions (like \appfmt{bibtex} but also performs hierarchical
+sorting and collation, thus omitting the need for \gls{xindy} or
+\gls{makeindex}). Further details at:
 \url{http://www.dickimaw-books.com/software/bib2gls/}.}%
 }
 
@@ -204,13 +205,13 @@ styles (glossaries):>#1={\protect\ttfamily#1}|main}}
 \DeleteShortVerb{\|}
 \MakeShortVerb{"}
 
- \title{glossaries-extra.sty v1.18:
+ \title{glossaries-extra.sty v1.19:
  an extension to the glossaries package}
  \author{Nicola L.C. Talbot\\[10pt]
 Dickimaw Books\\
 \url{http://www.dickimaw-books.com/}}
 
- \date{2017-08-10}
+ \date{2017-09-08}
  \maketitle
 
 \begin{abstract}
@@ -224,7 +225,8 @@ The file \texttt{example-glossaries-xr.tex} contains dummy
 entries with cross-references that may be used for creating
 minimal working examples for testing the \styfmt{glossaries-extra}
 package. (The base \styfmt{glossaries} package provides additional files,
-but this one needs \styfmt{glossaries-extra}.)
+but this one needs \styfmt{glossaries-extra}.) There are equivalent
+\texttt{.bib} files for use with \gls{bib2gls}.
 
 \end{abstract}
 
@@ -257,7 +259,7 @@ Additional resources:
 \href{http://www.latex-community.org/know-how/latex/55-latex-general/263-glossaries-nomenclature-lists-of-symbols-and-acronyms}{Glossaries,
 Nomenclature, Lists of Symbols and Acronyms}.
 
-\item \href{https://github.com/nlct/bib2gls}{bib2gls}
+\item \href{http://www.dickimaw-books.com/software/bib2gls}{bib2gls}
 \end{itemize}
 
 \tableofcontents
@@ -876,6 +878,9 @@ See \sectionref{sec:see} for further details.
 The test file \texttt{example-glossaries-xr.tex} contains
 dummy entries with a mixture of \gloskey{see}, \gloskey{alias}
 and \gloskey{seealso} keys for use with minimal working examples.
+There are also \texttt{example-glossaries-*.bib} files that
+correspond to each \texttt{example-glossaries-*.tex} file
+for testing \gls{bib2gls}.
 
 The \cs{longnewglossaryentry} command now has a starred version
 (as from v1.12) that doesn't automatically insert
@@ -1031,14 +1036,43 @@ indexed.)
 As from version 1.14, there are two new keys for \cs{glsadd}: 
 \gloskey[glsadd]{thevalue} and \gloskey[glsadd]{theHvalue}. 
 These keys are designed for manually adding explicit locations
-rather than obtaining the value from the associated counter. (If 
-you want an automated method, you might want to investigate \gls{bib2gls}.) This is
+rather than obtaining the value from the associated counter.
+As from version 1.19, these two keys are also available for commands
+like \cs{gls} and \cs{glslink}. The \gloskey[glsadd]{thevalue} keys is
 intended primarily for adding locations in supplementary material
-that can't otherwise be picked up by \gls{makeindex} or \gls{xindy}.
-They therefore aren't available for commands like \cs{gls} or
-\cs{glslink}. Remember that the value will still need to 
-be a valid location according to the rules of whichever indexing
-application you use.
+that can't be obtained from a counter.
+
+The principle key \gloskey[glslink]{thevalue} is for the location value. The
+other key \gloskey[glslink]{theHvalue} can be used to
+extract a prefix value for the first argument of commands like
+\ics{glsnoidxdisplayloc}. It's value must be in the format
+\meta{prefix}\meta{location}. In general, there's little need for
+this key as the prefix is typically associated with a counter that can be
+used to form hypertargets.
+
+\begin{important}
+If you use \gloskey[glsadd]{thevalue}, you must make sure that you
+use an indexing application that will accept the given value.
+\end{important}
+
+For example, \app{makeindex} will only accept locations in the form
+[\meta{num}\meta{sep}]*\meta{num} where \meta{num} is an arabic
+number (0, 1, \ldots), roman numeral (i, ii, \ldots\ or I, II,
+\ldots) or a character from a, \ldots, z or A, \ldots, Z, and
+[\meta{num}\meta{sep}]* indicates zero or more instances of a number
+followed by the recognised separator character (set with
+\cs{glsSetCompositor}). This means that \app{makeindex} won't
+accept, for example,
+\begin{verbatim}
+\glsadd[thevalue={Supplementary Material}]{sample}
+\end{verbatim}
+This location value will be accepted by \gls{bib2gls}, since it will
+allow any location and will only try forming ranges if the location
+matches any of its numerical patterns.
+In the case of \app{xindy}, you'll need to add a rule that can match
+the value. If you're using \sty{hyperref}, you may need to use the
+\gloskey[glslink]{format} key to prevent a hyperlink if one can't
+naturally be formed from the prefix, counter and location value.
 
 For example, suppose the file \texttt{suppl.tex} contains:
 \begin{verbatim}
@@ -1075,10 +1109,8 @@ Some \gls{sample} text.
 \glsadd[thevalue={S.2}]{sample}
 \end{document}
 \end{verbatim}
-(By placing \cs{glsadd} at the end of the document, it adds the
-supplementary location to the end of the location list, although the
-ordering may be changed by the indexing application depending on its
-location collation settings.)
+This location value will be accepted by \app{makeindex} as it's in
+the form \meta{num}\meta{sep}\meta{num}.
 
 If you want hyperlinks, things are more complicated. First
 you need to set the \catattr{externallocation} to the location of
@@ -1096,7 +1128,7 @@ Next you need to add \texttt{glsxtrsupphypernumber} as the format:
 Both documents will need to use the \sty{hyperref} package.
 Remember that the counter used for the location also needs to match.
 If \cs{theH}\meta{counter} is defined in the other document
-and is not the same as \cs{the}\meta{counter}, then you need
+and doesn't match in the referencing document, then you need
 to use \gloskey[glsadd]{theHvalue} to set the appropriate value.
 See the accompanying sample files \texttt{sample-suppl-hyp.tex}
 and \texttt{sample-suppl-main-hyp.tex} for an example that uses
@@ -1109,6 +1141,13 @@ take you to the relevant place in the external PDF file
 links, and some may take you to the first page or last visited page.
 \end{important}
 
+For example, if both \texttt{sample-suppl-hyp.pdf}
+and \texttt{sample-suppl-main-hyp.pdf} are in the same directory,
+then viewing \texttt{sample-suppl-main-hyp.pdf} in Evince will
+take you to the correct location in the linked document (when you
+click on the S.2 external link), but Okular will take you to the top
+of the first page of the linked document.
+
 \section{Cross-References (\qt{see} and \qt{see also})}
 \label{sec:see}
 
@@ -1239,7 +1278,7 @@ The \gloskey{seealso} key implements the automatic indexing using
 \end{definition}
 which just does
 \begin{alltt}
-\cs{glssee}\oarg{\cs{seealsoname}}\marg{label}\marg{xr list}
+\cs{glssee}[\cs{seealsoname}]\marg{label}\marg{xr list}
 \end{alltt}
 unless the \pkgopt{xindy} option is used with \sty{glossaries}
 v4.30+, in which case a distinct \texttt{seealso} cross-reference
@@ -1460,6 +1499,23 @@ commands). If you want to adjust the default for
 \gloskey[glslink]{wrgloss}, it's better to do this by redefining
 \ics{glsxtrinitwrgloss} instead.
 
+\begin{important}
+\cs{GlsXtrSetDefaultGlsOpts} doesn't affect \cs{glsadd}.
+\end{important}
+
+If you want to change the default value of \gloskey[glsadd]{format}, 
+you can instead use:
+\begin{definition}[\GlsXtrSetDefaultNumberFormat]
+\cs{GlsXtrSetDefaultNumberFormat}\marg{format}
+\end{definition}
+This has the advantage of also working for \cs{glsadd}.
+For example, if you want all locations in the back matter to appear
+in italic (unless explicitly overridden):
+\begin{verbatim}
+\backmatter
+\GlsXtrSetDefaultNumberFormat{hyperit}
+\end{verbatim}
+
 Commands like \ics{gls} have star (\texttt{*}) and plus 
 (\texttt{+}) modifiers as a short cut for \texttt{hyper=false}
 and \texttt{hyper=true}. The \styfmt{glossaries-extra} package
@@ -5772,9 +5828,10 @@ to just text.
 \chapter{bib2gls: Managing Reference Databases}
 \label{sec:bib2gls}
 
-There is a new command line application under development called
+There is a new command line application called
 \gls{bib2gls}, which works in much the same way as 
-a combination of \appfmt{bibtex} and \appfmt{makeindex}.
+a combination of \appfmt{bibtex} and
+\appfmt{makeindex}\slash\appfmt{xindy}.
 Instead of storing all your entry definitions in a \texttt{.tex} and
 loading them using \cs{input} or \cs{loadglsentries}, the entries
 can instead be stored in a \texttt{.bib} file and \gls{bib2gls} can
@@ -5788,10 +5845,12 @@ by only defining the entries that are actually required in the
 document. If you currently have a \texttt{.tex} file that contains
 hundreds of definitions, but you only use a dozen or so in your
 document, then the build time is needlessly slowed by the unrequired
-definitions that occur when the file is input.
+definitions that occur when the file is input. (You can convert an
+existing \texttt{.tex} file containing glossary definitions to a
+\texttt{.bib} file using \app{convertgls2bib}, supplied with
+\gls{bib2gls}.)
 
-Although \gls{bib2gls} isn't ready yet (at the time of writing
-this), there have been some new commands and options added to
+There are some new commands and options added to
 \styfmt{glossaries-extra} to help assist the integration of
 \gls{bib2gls} into the document build process.
 
@@ -5883,7 +5942,7 @@ The \texttt{.glstex} file created by \cs{bib2gls} is loaded using:
 \cs{glsxtrresourcefile}\oarg{options}\marg{filename}
 \end{definition}
 (Don't include the file extension in \meta{filename}.)
-There's a shortcut version that sets \meta{filename} \cs{jobname}:
+There's a shortcut version (recommended over the above) that sets \meta{filename} to use \cs{jobname}:
 \begin{definition}[\DescribeMacro\GlsXtrLoadResources]
 \cs{GlsXtrLoadResources}\oarg{options}
 \end{definition}
@@ -5914,21 +5973,19 @@ to the \texttt{.aux} file and will input
 for example, \meta{filename} happens to be the same as \cs{jobname}.
 The \texttt{.glstex} extension was enforced by version 1.11.}
 
-The options are ignored by \styfmt{glossaries-extra} but are picked
-up by \gls{bib2gls} and are used to supply various information, such
-as the name of the \texttt{.bib} files and any changes to the
-default behaviour.
-
 Since the \texttt{.glstex} won't exist on the first \LaTeX\ run, the
 \styopt{record} package option additionally switches on
 \styopt[warn]{undefaction}. Any use of commands like \cs{gls} or
 \cs{glstext} will produce ?? in the document, since they are
 undefined at this point. Once \gls{bib2gls} has created the
 \texttt{.glstex} file the references should be resolved.
+This may cause a shift in the locations if the actual text produced
+once the entry is defined is larger than the placeholder ?? (as can
+occur with long citations).
 
 \begin{important}
 Note that \cs{glsaddall} doesn't work with \gls{bib2gls} as the command 
-has to iterate over the glossary lists, which will be empty on the first
+has to iterate over the internal lists of defined entry labels, which will be empty on the first
 run and on subsequent runs will only contain those entries that have
 been selected by \gls{bib2gls}.
 \end{important}
@@ -6269,6 +6326,29 @@ given by \meta{label-2}. There's no check for the existence of
 \cs{glsxtrsetfieldifexists}\marg{label-1}\marg{field-1}\marg{code}
 is still used, as for \cs{GlsXtrSetField}.
 
+The \styfmt{glossaries} package provides \ics{ifglshasfield}
+to determine if a field has been set. The \styfmt{glossaries-extra}
+package provides a simpler version:
+\begin{definition}[\DescribeMacro\glsxtrifhasfield]
+\cs{glsxtrifhasfield}\marg{label}\marg{field}\marg{true}\marg{false}
+\end{definition}
+(New to v1.19.)
+Unlike \cs{ifglshasfield}, this version doesn't complain if the
+entry (given by \meta{label}) or the field don't exist and
+will simply do \meta{false}. If the field does exist for the given
+entry and it's not empty, the \meta{true} part is done otherwise it
+does \meta{false}. Within \meta{true} you may use
+\begin{definition}[\DescribeMacro\glscurrentfieldvalue]
+\cs{glscurrentfieldvalue}
+\end{definition}
+to access the field value. This command includes grouping
+which scopes the \meta{true} and \meta{false} parts.
+The starred version
+\begin{definition}[\DescribeMacro{\glsxtrifhasfield*}]
+\cs{glsxtrifhasfield*}\marg{label}\marg{field}\marg{true}\marg{false}
+\end{definition}
+omits the implicit grouping.
+
 The \styfmt{glossaries} package provides \ics{glsfieldfetch} which
 can be used to fetch the value of the given field and store it in a
 control sequence. The \styfmt{glossaries-extra} package provides