diff options
author | Karl Berry <karl@freefriends.org> | 2018-04-09 21:18:22 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2018-04-09 21:18:22 +0000 |
commit | 11bd7c1043384daa09ab391cfbbc6c9b47514c9f (patch) | |
tree | e9c91f9d74c0f9fd7b8e9518b327a04ad83a3737 /Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex | |
parent | a20371822a110924cb6a42227a0611df4004eb05 (diff) |
glossaries-extra (9apr18)
git-svn-id: svn://tug.org/texlive/trunk@47410 c570f23f-e606-0410-a88d-b1316a301751
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.tex | 120 |
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 |