summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2017-06-15 21:47:33 +0000
committerKarl Berry <karl@freefriends.org>2017-06-15 21:47:33 +0000
commit9e987d284eb0915a995e129c61df7c94146b5007 (patch)
tree5f10da256063d1d0d96d5124264cd7c38d4a5c79 /Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex
parent0f37ab813b7b69885fa8c19dde8c51fdb629eff5 (diff)
glossaries-extra (15jun17)
git-svn-id: svn://tug.org/texlive/trunk@44608 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.tex234
1 files changed, 213 insertions, 21 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 02ebd06489b..5178132f110 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
@@ -167,13 +167,13 @@ styles (glossaries):>#1={\protect\ttfamily#1}|main}}
\DeleteShortVerb{\|}
\MakeShortVerb{"}
- \title{glossaries-extra.sty v1.15:
+ \title{glossaries-extra.sty v1.16:
an extension to the glossaries package}
\author{Nicola L.C. Talbot\\[10pt]
Dickimaw Books\\
\url{http://www.dickimaw-books.com/}}
- \date{2017-05-10}
+ \date{2017-06-15}
\maketitle
\begin{abstract}
@@ -183,6 +183,12 @@ Some of the features provided by this package are only available
with \styfmt{glossaries} version 4.19 (or above).
This document assumes familiarity with the \styfmt{glossaries} package.
+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}.)
+
\end{abstract}
\begin{important}
@@ -489,6 +495,65 @@ over a glossary list. This includes \ics{forglsentries} and
\ics{glsaddall}.
\end{important}
+\item[{\pkgopt{indexcrossrefs}}] This is a boolean option.
+If \pkgoptfmt{true}, this will automatically index any
+cross-referenced entries that haven't been marked as used at
+the end of the document. Note that this necessarily adds to
+the overall document build time, especially if you have defined
+a large number of entries, so this defaults to \pkgoptfmt{false},
+but it will be automatically switched on if you use the \gloskey{see}
+or \gloskey{seealso} keys in any entries (unless
+\pkgopt[false]{autoseeindex}). To force it off, even if you use the
+\gloskey{see} or \gloskey{seealso} key, you
+need to explicitly set \pkgopt{indexcrossrefs} to \pkgoptfmt{false}.
+
+Note that \gls{bib2gls} can automatically find dependent
+entries when it parses the \texttt{.bib} source file.
+The \pkgopt{record} option automatically implements
+\pkgopt[false]{indexcrossrefs}.
+
+\item[{\pkgopt{autoseeindex}}]\label{opt:autoseeindex} (New to
+v1.16.) This is a boolean option. If true (default), this makes
+the \gloskey{see} and \gloskey{seealso} keys automatically index the
+cross-reference when an entry is defined. If false, the value
+of those keys will still be stored in their corresponding fields
+(and can be accessed using commands like \cs{glsxtrusesee} and
+\cs{glsxtruseseealso}) but cross-reference won't be automatically
+indexed.
+
+Note that the \pkgopt[only]{record} option automatically implements
+\pkgopt[false]{autoseeindex}.
+
+For example, if an entry is defined as
+\begin{verbatim}
+\newglossaryentry{foo}{name={foo},description={},see={bar,baz}}
+\end{verbatim}
+then with \texttt{autoseeindex=true}, this is equivalent to
+\begin{verbatim}
+\newglossaryentry{foo}{name={foo},description={}}
+\glssee{foo}{bar,baz}
+\glossariesextrasetup{indexcrossrefs=true}
+\GlsXtrSetField{foo}{see}{bar,baz}
+\end{verbatim}
+but with \texttt{autoseeindex=false}, this is equivalent to
+\begin{verbatim}
+\newglossaryentry{foo}{name={foo},description={}}
+\GlsXtrSetField{foo}{see}{bar,baz}
+\end{verbatim}
+Note that \pkgopt{indexcrossrefs} isn't automatically implemented
+by the presence of the \gloskey{see} key when \pkgopt{autoseeindex}
+is false.
+
+It's therefore possible to remove the cross-references from the
+location lists and set their position within the glossary style.
+
+Another method of preventing the automatic indexing is to
+define the entries before the external indexing files have been
+opened with \cs{makeglossaries}. Since the appropriate file isn't
+open, the information can't be written to it. This will need
+the package option \pkgoptfmt{seenoindex=ignore} (provided by
+\styfmt{glossaries}) to prevent an error occurring.
+
\item[{\pkgopt{record}}]\label{opt:record}(New to v1.08.) This is a \meta{key}=\meta{value}
option, which has three allowed values: \pkgoptfmt{off} (default),
\pkgoptfmt{only} and \pkgoptfmt{alsoindex}. If the value is omitted
@@ -511,6 +576,11 @@ automatically implementing \cs{glssee}. (\gls{bib2gls} deals with the
document, but \gls{bib2gls} will ignore the cross-reference if the
\gloskey{see} field was already set for that entry.
+The \pkgopt[only]{record} option will automatically set
+the \styfmt{glossaries} package's \pkgopt[none]{sort} option
+if available. (That option value was only introduced to
+\styfmt{glossaries} v4.30.)
+
With the recording on, any of the commands that would typically
index the entry (such as \cs{gls}, \cs{glstext} or \cs{glsadd})
will add a \cs{glsxtr@record} entry to the \texttt{.aux} file.
@@ -593,21 +663,6 @@ to an incomplete document build. However, it's probably simpler
just to fix whatever has caused the failure to build the external
file or files.
-\item[{\pkgopt{indexcrossrefs}}] This is a boolean option.
-If \pkgoptfmt{true}, this will automatically index any
-cross-referenced entries that haven't been marked as used at
-the end of the document. Note that this necessarily adds to
-the overall document build time, especially if you have defined
-a large number of entries, so this defaults to \pkgoptfmt{false},
-but it will be automatically switched on if you use the \gloskey{see} key in any
-entries. To force it off, even if you use the \gloskey{see} key, you
-need to explicitly set \pkgopt{indexcrossrefs} to \pkgoptfmt{false}.
-
-Note that \gls{bib2gls} can automatically find dependent
-entries when it parses the \texttt{.bib} source file.
-The \pkgopt{record} option automatically implements
-\pkgopt[false]{indexcrossrefs}.
-
\item[{\pkgopt{abbreviations}}] This option has no value and can't
be cancelled. If used,
it will automatically create a new glossary with the label
@@ -755,7 +810,7 @@ any cross-references within the glossary won't be affected. This is
a way of avoiding duplicate target warnings if a glossary needs to
be displayed multiple times.
-The \cs{newglossaryentry} command has two new keys:
+The \cs{newglossaryentry} command has three new keys:
\begin{itemize}
\item \gloskey{category}, which sets the category label for the given
entry. By default this is \texttt{general}. See
@@ -763,7 +818,13 @@ entry. By default this is \texttt{general}. See
categories.
\item \gloskey{alias}, which allows an entry to be alias to another
entry. See \sectionref{sec:alias} for further details.
+\item \gloskey{seealso}, which performs much like \gloskey{see}, but
+allows for separate \qt{see} and \qt{see also} treatment.
+See \sectionref{sec:see} for further details.
\end{itemize}
+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.
The \cs{longnewglossaryentry} command now has a starred version
(as from v1.12) that doesn't automatically insert
@@ -997,9 +1058,12 @@ 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}
+\section{Cross-References (\qt{see} and \qt{see also})}
+\label{sec:see}
+
The value of the \gloskey{see} key is now saved
as a field. This isn't the case with \styfmt{glossaries}, where
-the \gloskey{see} attribute is simply used to directly
+the \gloskey{see} value is simply used to directly
write a line to the corresponding glossary file and is then
discarded. This is why the \gloskey{see} key can't be
used before \ics{makeglossaries} (since the file hasn't been opened
@@ -1066,6 +1130,70 @@ the description. For example:
Now the cross-references can appear even though the \gls{numberlist}
has been suppressed.
+As from v1.16, there's a separate \gloskey{seealso} key. Unlike
+\gloskey{see}, this doesn't have an optional part for the textual
+tag. The syntax \texttt{seealso=\marg{xr-labels}} works in much the same way as using
+\texttt{see=[\cs{seealsoname}]\marg{xr-labels}} but the information
+is stored in a separate field. If you need a different tag, use the
+\gloskey{see} key instead (or redefine \cs{seealsoname} or
+\cs{glsxtruseseealsoformat}, described below).
+
+You can display the formatted list of
+cross-references stored in the \gloskey{seealso} key using:
+\begin{definition}[\DescribeMacro\glsxtruseseealso]
+\cs{glsxtruseseealso}\marg{label}
+\end{definition}
+This works in much the same way as \cs{glsxtrusesee}
+but it internally uses
+\begin{definition}[\DescribeMacro\glsxtruseseeformat]
+\cs{glsxtruseseealsoformat}\marg{xr list}
+\end{definition}
+For example:
+\begin{verbatim}
+\renewcommand*{\glsxtrpostdescgeneral}{%
+ \ifglshasfield{see}{\glscurrententrylabel}
+ {, \glsxtrusesee{\glscurrententrylabel}}%
+ {}%
+ \ifglshasfield{seealso}{\glscurrententrylabel}
+ { (\glsxtruseseealso{\glscurrententrylabel})}%
+ {}%
+}
+\end{verbatim}
+
+The actual unformatted comma-separated list \meta{xr-list}
+stored in the \gloskey{seealso} field can be accessed with:
+\begin{definition}[\DescribeMacro\glsxtrseealsolabels]
+\cs{glsxtrseealsolabels}\marg{label}
+\end{definition}
+This will just expand to the \meta{xr-labels} provided in the value
+of the \gloskey{seealso} key. There's no corresponding command to
+access the \gloskey{see} field. If you really need to access it, you
+can use commands like \cs{glsxtrfielduse}, but remember that it
+may start with \oarg{tag}, so it can't be automatically treated
+as a simple comma-separated list.
+
+The base \styfmt{glossaries} package provides \ics{glsseelist},
+which requires a comma-separated list of labels as the argument.
+The argument isn't fully expanded, so it's not suitable to use, for
+example, \cs{glsxtrseealsolabels}\marg{label} as the argument.
+For convenience, \styfmt{glossaries-extra} provides
+\begin{definition}[\DescribeMacro\glsxtrseelist]
+\cs{glsxtrseelist}\marg{xr list}
+\end{definition}
+which fully expands its argument and passes it to \cs{glsseelist}.
+
+The \gloskey{seealso} key implements the automatic indexing using
+\begin{definition}[\DescribeMacro\glsxtrindexseealso]
+\cs{glsxtrindexseealso}\marg{label}\marg{xr list}
+\end{definition}
+which just does
+\begin{alltt}
+\cs{glssee}\oarg{\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
+class is used instead.
+
\section{Entry Display Style Modifications}
\label{sec:entryfmtmods}
@@ -4895,8 +5023,65 @@ In both cases, the indexing is done through
\end{definition}
This uses the standard \ics{index} command with the sort value
taken from the entry's \gloskey{sort} key and the actual value
-set to \cs{glsentryname}\marg{label}. If the value of the
-attribute given by \meta{attribute-label} is \qt{true}, no encap
+set to \cs{glsentryname}\marg{label}. As from v1.16, there are
+user-level commands available to change the sort and actual
+value used by the automated index.
+
+The actual value is given by
+\begin{definition}[\DescribeMacro\glsxtrautoindexentry]
+\cs{glsxtrautoindexentry}\marg{label}
+\end{definition}
+where \meta{label} is the entry's label. The default definition
+is:
+\begin{verbatim}
+\newcommand*{\glsxtrautoindexentry}[1]{\string\glsentryname{#1}}
+\end{verbatim}
+Note the use of \cs{string} to prevent \cs{glsentryname} from
+being expanded as it's written to the index file.
+
+The sort value is assigned using:
+\begin{definition}[\DescribeMacro\glsxtrautoindexassignsort]
+\cs{glsxtrautoindexassignsort}\marg{cs}\marg{label}
+\end{definition}
+where \meta{label} is the entry label and \meta{cs} is the command
+which needs to be set to the sort value. The default definition is:
+\begin{verbatim}
+\newcommand*{\glsxtrautoindexassignsort}[2]{%
+ \glsletentryfield{#1}{#2}{sort}%
+}
+\end{verbatim}
+After this macro is called, \meta{cs} is then processed to escape
+any of \app{makeindex}'s special characters. Note that this
+escaping is only performed on the sort not on the actual value.
+
+The command used to perform the actual indexing is:
+\begin{definition}[\DescribeMacro\glsxtrautoindex]
+\cs{glsxtrautoindex}\marg{text}
+\end{definition}
+This just does \cs{index}\marg{text} by default.
+
+\begin{important}
+The entry's \gloskey{parent} field isn't referenced in this
+automated indexing.
+\end{important}
+
+For example, to index the value of the \gloskey{first} key,
+instead of the \gloskey{name} key:
+\begin{verbatim}
+\renewcommand*{\glsxtrautoindexentry}[1]{\string\glsentryfirst{#1}}
+\end{verbatim}
+and if the sort value also needs to be set to the \gloskey{long}
+field, if present, otherwise the \gloskey{sort} field:
+\begin{verbatim}
+\renewcommand*{\glsxtrautoindexassignsort}[2]{%
+ \ifglshaslong{#2}%
+ {\glsletentryfield{#1}{#2}{long}}%
+ {\glsletentryfield{#1}{#2}{sort}}%
+}
+\end{verbatim}
+
+If the value of the attribute given by \meta{attribute-label}
+is \qt{true}, no encap
will be added, otherwise the encap will be the
attribute value. For example:
\begin{verbatim}
@@ -5703,6 +5888,13 @@ there will be no \gls{numberlist} in this case, as that has to be
set by a post-processor such as \gls{bib2gls} (see
\sectionref{sec:bib2gls}).
+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
+automated \cs{glssee} normally triggered by this key. The
+\pkgopt[only]{record} package option will automatically deal with
+this.
+
For example:
\begin{verbatim}
\documentclass{article}