summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex')
-rw-r--r--Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex120
1 files changed, 117 insertions, 3 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 45bded9ecae..758d2a4c2f5 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
@@ -226,13 +226,13 @@ styles (glossaries):>#1={\protect\ttfamily#1}|main}}
\DeleteShortVerb{\|}
\MakeShortVerb{"}
- \title{glossaries-extra.sty v1.28:
+ \title{glossaries-extra.sty v1.29:
an extension to the glossaries package}
\author{Nicola L.C. Talbot\\[10pt]
Dickimaw Books\\
\url{http://www.dickimaw-books.com/}}
- \date{2018-03-06}
+ \date{2018-04-09}
\maketitle
\begin{abstract}
@@ -787,6 +787,55 @@ out which entries have been used. (Remember that commands like
add a corresponding \cs{glsxtr@record} entry to the \texttt{.aux}
file.) See \sectionref{sec:bib2gls} for further details.
+\item[{\pkgoptdef{indexcounter}}] (New to v1.29.) This option (which
+doesn't take a value) is primarily intended for use with
+\gls{bib2gls} (v1.4+) and \sty{hyperref}. It can be used with
+\gls{makeindex} or \gls{xindy} but it will interfere with the
+\gls{numberlist} collation, so you won't have ranges and you'll have
+duplicate page numbers present (but each page number will link to
+the relevant part of the page where the indexing occurred). This
+option automatically implements \pkgopt[wrglossary]{counter}.
+
+By default (with \sty{hyperref}), the page numbers in
+\glspl{numberlist} link back to the top of the relevant page
+(provided the format uses \cs{glshypernumber}). The
+\pkgopt{indexcounter} option is designed to link back to the place
+within the page where the indexing occurred. It does this by
+creating a new counter (called \ctr{wrglossary}) that's incremented
+with \cs{refstepcounter} every time an entry is indexed (but not via
+cross-referencing commands, such as \cs{glssee}). A \cs{label} is
+placed immediately after the increment command allowing the
+back-referenced to be obtained with \cs{pageref}. The location, as
+seen by the indexing application, is the value of the
+\ctr{wrglossary} counter but this value is substituted with the page
+reference when \gls{numberlist} is typeset. Since the counter is
+used by all entries and is incremented every time any indexing
+occurs, neither \gls{makeindex} nor \gls{xindy} can correctly
+collate the lists. For example, if the first term to be referenced
+is indexed three times on page~5 without any intervening terms then
+the actual locations obtained from \ctr{wrglossary} will be 1, 2 and
+3, which \gls{xindy} and \gls{makeindex} will try to form into the
+range 1--3, but they should actually all simply appear as page~5,
+whereas it can actually end up with 5--5. Conversely, a range may
+not be formed where it would naturally occur if just the \ctr{page}
+counter was used.
+
+Since \gls{bib2gls} is designed specifically to work with
+\styfmt{glossaries-extra}, \gls{bib2gls} (v1.4+) will check for
+\ctr{wrglossary} locations. If the default
+\texttt{--merge-wrglossary-records} is on, then any records for the
+same page for a given entry will be merged. In the above example
+with three references on page~5, only a single record for page~5 for
+that entry will be added to the \gls{numberlist} and it will link
+back to the first instance on that page. Whereas if you use the
+\texttt{--no-merge-wrglossary-records} switch, the \gls{numberlist}
+will contain three instance of page~5, with each linking to the
+corresponding place on that page. In both cases, consecutive pages
+can form ranges, but it may look strange in the second case.
+
+See the \gls{bib2gls} documentation for the
+\texttt{save-index-counter} resource option for more details.
+
\item[{\pkgoptdef{docdef}}] This option governs the use of
\cs{newglossaryentry}. It was originally a boolean option,
but as from version 1.06, it can now take one of three values (if
@@ -7335,7 +7384,7 @@ the above needs to be written as:
The package option \pkgopt[only]{record} (or simply \pkgopt{record})
automatically loads the supplementary package
\sty{glossaries-extra-bib2gls}, which provides some commands
-that are specific to sorting with \gls{bib2gls}. The package isn't
+that are specific to \gls{bib2gls}. The package isn't
loaded by \pkgopt[alsoindex]{record} as that option is intended
for sorting with \gls{makeindex} or \gls{xindy} and it is expected
that the sorting will be switched off (with the resource option
@@ -7377,6 +7426,44 @@ to the \texttt{.glstex} file (as it is by default) then it won't
override the current definition (provided by the kernel or redefined
by a package).
+\begin{definition}[\DescribeMacro\GlsXtrIndexCounterLink]
+\cs{GlsXtrIndexCounterLink}\marg{text}\marg{label}
+\end{definition}
+If the \ics{hyperref} command has been defined (that is,
+\sty{hyperref} has been loaded before \styfmt{glossaries-extra})
+then this command checks for the existence of the
+\texttt{indexcounter} field. If this field is set for the entry
+given by \meta{label}, this command does
+\cs{hyperref}\texttt{[wrglossary.\meta{value}]\marg{text}}, where
+\meta{value} is the value of the \texttt{indexcounter} field. If the
+field isn't set or if \cs{hyperref} hasn't been defined, this just
+does \meta{text}. This command is provided for use with the
+\pkgopt{indexcounter} package option combined with \gls{bib2gls}['s]
+\texttt{save-index-counter} resource option. See the \gls{bib2gls}
+manual for further details (at least version 1.4).
+
+\begin{definition}[\DescribeMacro\GlsXtrBibTeXEntryAliases]
+\cs{GlsXtrBibTeXEntryAliases}
+\end{definition}
+A convenient shortcut for use in the \texttt{entry-type-aliases}
+setting. This provides aliases for Bib\TeX's standard entry types to
+\gls{bib2gls}['s] \texttt{@bibtexentry} entry type (requires at
+least \gls{bib2gls} version 1.4).
+
+\begin{definition}[\DescribeMacro\GlsXtrProvideBibTeXFields]
+\cs{GlsXtrProvideBibTeXFields}
+\end{definition}
+Defines storage keys for Bib\TeX's standard fields. Note that
+Bib\TeX's \texttt{type} field clashes with the \sty{glossaries}
+package's \gloskey{type} key, so this command provides the key
+\texttt{bibtextype} instead. You can alias it with
+\texttt{field-aliases={type=bibtextype}} in the resource options.
+Each storage key is provided with a convenient command to access the
+value in the form \cs{glsxtrbib}\meta{field}. For example,
+\cs{glsxtrbibaddress}. The \texttt{bibtextype} field can be accessed
+with \cs{glsxtrbibtype}. Each of these commands takes the entry
+label as the sole argument.
+
The \sty{glossaries-extra-bib2gls} package also provides definitions
of the missing mathematical Greek commands: \ics{Alpha},
\ics{Beta}, \ics{Epsilon}, \ics{Zeta}, \ics{Eta}, \ics{Iota},
@@ -8864,6 +8951,33 @@ entry, they won't be together in the glossary when using
\cs{printunsrtglossary}.
\end{important}
+There's a difference in behaviour depending on whether or not the
+\gloskey{group} key is defined. If not defined (default), the
+group label will be formed from the first letter of the
+\gloskey{name} field. The corresponding group title will be obtained
+as discussed in \sectionref{sec:glosstylemods}. This can lead to an
+odd effect if you are using a style that separates letter groups
+when the ordering isn't alphabetical.
+
+If the \gloskey{group} key is defined (which it is with the
+\pkgopt{record} option) then the group label will be obtained from
+the value of that field. If the field is empty, \emph{no grouping is
+performed}, even if the style supports it. (That is, there won't be
+a header or a vertical separation.) If the \gloskey{group} field is
+non-empty, then the corresponding title is obtained as described
+earlier.
+
+If you want to use a different field, you can redefine
+\begin{definition}[\DescribeMacro\glsxtrgroupfield]
+\cs{glsxtrgroupfield}
+\end{definition}
+to the relevant internal field label, but the \gloskey{group}
+\emph{key} must still be defined (through the \pkgopt{record} option
+or with commands like \cs{glsaddstoragekey}) to ensure that
+\cs{printunsrtglossary} uses \cs{glsxtrgroupfield}. (This method is
+used by \gls{bib2gls} for secondary entries, which have the group
+label stored in the \texttt{secondarygroup} internal field.)
+
If you have any entries with the \gloskey{see} key set, you will
need the \sty{glossaries} package option \pkgopt[ignore]{seenoindex}
or \pkgopt[warn]{seenoindex} to prevent an error occurring from the