summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex')
-rw-r--r--Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex157
1 files changed, 138 insertions, 19 deletions
diff --git a/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex b/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex
index 8ef6883f0ad..3b416ba21d9 100644
--- a/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex
+++ b/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex
@@ -76,6 +76,7 @@
\newcommand{\glstextlike}{\hyperref[sec:glstext-like]{\cs{glstext}-like}}
\IndexPrologue{\chapter*{\indexname}
+ \addcontentsline{toc}{chapter}{\indexname}%
\markboth{\indexname}{\indexname}}
\longnewglossaryentry{indexingapp}%
@@ -395,11 +396,11 @@ and~\hyperlink{option#2}{#2}}
\MakeShortVerb{"}
\DeleteShortVerb{\|}
- \title{User Manual for glossaries.sty v4.25}
+ \title{User Manual for glossaries.sty v4.26}
\author{Nicola L.C. Talbot\\%
\url{http://www.dickimaw-books.com/}}
- \date{2016-06-09}
+ \date{2016-10-12}
\maketitle
\begin{abstract}
@@ -477,7 +478,7 @@ package.
\item[\url{glossaries-code.pdf}]
Advanced users wishing to know more about the inner workings of all the
packages provided in the \styfmt{glossaries} bundle should read
-\qt{Documented Code for glossaries v4.25}.
+\qt{Documented Code for glossaries v4.26}.
\item[INSTALL] Installation instructions.
@@ -3075,7 +3076,8 @@ reference the number within the document using
associated with the sub-entry.
\item[\pkgopt{style}] This is a \meta{key}=\meta{value} option.
-(Default is \pkgopt[list]{style}.) Its value should be the name of
+(Default is \pkgopt[list]{style}, unless \sty{classicthesis}
+has been loaded, in which case the default is \pkgopt[index]{style}.) Its value should be the name of
the glossary style to use. This key may only be used for styles
defined in \sty{glossary-list}, \sty{glossary-long},
\sty{glossary-super} or \sty{glossary-tree}. Alternatively, you can
@@ -3107,7 +3109,8 @@ overhead by not defining unwanted styles. Note that if
you use this option, you won't be able to use any of the
glossary styles defined in the \styfmt{glossary-list} package
(unless you explicitly load \sty{glossary-list}).
-Note that since the default style is \glostyle{list}, you will
+Note that since the default style is \glostyle{list} (unless
+\sty{classicthesis} has been loaded), you will
also need to use the \pkgopt{style} option to set the style to
something else.
@@ -3116,7 +3119,9 @@ from automatically loading \sty{glossary-tree}. This reduces
overhead by not defining unwanted styles. Note that if
you use this option, you won't be able to use any of the
glossary styles defined in the \styfmt{glossary-tree} package
-(unless you explicitly load \sty{glossary-tree}).
+(unless you explicitly load \sty{glossary-tree}). Note that if
+\sty{classicthesis} has been loaded, the default style is
+\glostyle{index}, which is provided by \sty{glossary-tree}.
\item[\pkgopt{nostyles}] This prevents all the predefined styles
from being loaded. If you use this option, you need to load a
@@ -5544,7 +5549,7 @@ provides the option to add a third custom variant.
\begin{important}
Avoid nesting these commands. For example don't do
\cs{glslink}\marg{label}\texttt{\{\cs{gls}\marg{label2}\}}
-as this is likely to cause problems. By implication, these
+as this is likely to cause problems. By implication, this
means that you should avoid using any of these commands within
the \gloskey{text}, \gloskey{first}, \gloskey{short} or
\gloskey{long} keys (or their plural equivalent) or any
@@ -5942,6 +5947,8 @@ star-variant (\texttt{hyper=false}) and a plus-variant
that is a \meta{key}=\meta{value} list. These commands also don't
use \ics{glsentryfmt} or the equivalent definition provided by
\ics{defglsentryfmt} (see \sectionref{sec:glsdisplay}).
+Additional commands for abbreviations are described in
+\sectionref{sec:acronyms}.
Apart from \ics{glslink}, the commands described in this section
also have a \emph{final} optional argument \meta{insert} which may
@@ -7946,6 +7953,10 @@ change LaTeX’s \qt{fixed names}}.
\chapter{Acronyms and Other Abbreviations}
\label{sec:acronyms}
+The \sty{glossaries-extra} package provides superior
+abbreviation handling. You may want to consider using that
+package instead of the commands described here.
+
\begin{important}
Note that although this chapter uses the term \qt{acronym}, you can also
use the commands described here for initialisms or contractions
@@ -7955,10 +7966,9 @@ should be \qt{Abbreviations} rather than \qt{Acronyms}) then
you can change the title either by redefining \ics{acronymname} (see
\sectionref{sec:languages}) or by using the \gloskey[printglossary]{title}
in the optional argument of \ics{printglossary} (or
-\ics{printacronym}). You may prefer to use the
-\gls{glossaries-extra} package which defines \cs{newabbreviation}
-and treats acronyms (e.g.\ \qt{laser}) differently from other forms
-of abbreviations (e.g.\ \qt{html}).
+\ics{printacronym}). Alternatively consider using the
+\sty{glossaries-extra} package's \pkgoptfmt{abbreviations}
+option instead.
\end{important}
You may have noticed in \sectionref{sec:newglosentry} that when you
@@ -7995,8 +8005,11 @@ list of acronyms and then use \ics{defglsentryfmt} (not redefine
\ics{glsentryfmt}) before defining your entries.
\end{important}
-The optional argument \marg{key-val list} allows you to specify keys
-such as \gloskey{description} (when used with one of the styles that
+The optional argument \marg{key-val list} allows you to specify
+additional information. Any key that can be used in the second
+argument of \ics{newglossaryentry} can also be used here in \meta{key-val
+list}.
+For example, \gloskey{description} (when used with one of the styles that
require a description, described in
\sectionref{sec:setacronymstyle}) or you can
override plural forms of \meta{abbrv} or \meta{long} using the
@@ -8043,6 +8056,10 @@ Now \verb|\gls{idn}| will produce \qt{identification number
uses.
\end{example}
+\begin{important}
+Avoid nested definitions.
+\end{important}
+
Recall from the warning in
\sectionref{sec:newglosentry} that you should avoid using
the \glslike\ and \glstextlike\ commands within the value of
@@ -8080,6 +8097,10 @@ or
\end{verbatim}
Similarly for the \glstextlike\ commands.
+Other approaches are available with \sty{glossaries-extra}.
+See the section \qt{Nested Links} in the \styfmt{glossaries-extra}
+user manual.
+
\begin{important}
The commands described below are similar to the \glstextlike\
commands in that they don't modify the \firstuseflag.
@@ -8173,9 +8194,12 @@ where
\begin{definition}[\DescribeMacro\acrfullformat]
\cs{acrfullformat}\marg{long}\marg{short}
\end{definition}
-by default does \meta{long} (\meta{short}).
-(For further details of these format commands see
-\ifpdf section~\ref*{sec:code:acronym} in \fi the documented code,
+by default does \meta{long} (\meta{short}). This command is now
+deprecated for new acronym styles but is used by the default for
+backward compatibility if \cs{setacronymstyle}
+(\sectionref{sec:setacronymstyle}) hasn't been used. (For further
+details of these format commands see \ifpdf
+section~\ref*{sec:code:acronym} in \fi the documented code,
\texttt{glossaries-code.pdf}.)
There are also analogous upper case variants:
@@ -8284,7 +8308,8 @@ And the full form can be obtained using:
\cs{Glsentryfullpl}\marg{label}
\end{definition}
These again use \ics{acrfullformat} by default, but
-the format may be redefined by the acronym style.
+the new styles described in the section below use different
+formatting commands.
\section{Changing the Abbreviation Style}
\label{sec:setacronymstyle}
@@ -9772,6 +9797,14 @@ explicitly create a line-break within a multi-line description in
a tabular-like style it's better to use \ics{newline} instead of
\verb|\\|.
+\begin{important}
+Remember that a cell within a tabular-like environment can't
+be broken across a page, so even if a tabular-like style, such as
+\glostyle{long}, allows multilined descriptions, you'll probably encounter
+page-breaking problems if you have entries with long descriptions.
+You may want to consider using the \glostyle{alttree} style instead.
+\end{important}
+
Note that if you use the \gloskey[printglossary]{style} key in the
optional argument to \ics{printnoidxglossary} (\opt1) or
\ics{printglossary} (\optsand23), it will override any
@@ -9827,6 +9860,11 @@ environment. These styles all ignore the entry's symbol. Note that
these styles will automatically be available unless you use the
\pkgopt{nolist} or \pkgopt{nostyles} package options.
+\begin{important}
+Note that, except for the \glostyle{listdotted} style, these
+list styles are incompatible with \sty{classicthesis}.
+\end{important}
+
\begin{description}
\item[list] The \glostyle{list} style uses the \env{description}
environment. The entry name is placed in the optional argument of
@@ -9836,6 +9874,8 @@ that entry. The symbol is ignored. If the entry has child entries,
the description and number list follows (but not the name) for each
child entry. Groups are separated using \ics{indexspace}.
+The closest matching non-list style is the \glostyle{index} style.
+
\item[listgroup] The \glostyle{listgroup} style is like
\glostyle{list} but the glossary groups have headings
obtained using \cs{glsgetgrouptitle}\marg{label},
@@ -9879,6 +9919,14 @@ with the \glostyle{list} style, the symbol is ignored.) Each child
entry starts a new line, but as with the \glostyle{list} style,
the name associated with each child entry is ignored.
+The closest matching non-list style is the \glostyle{index}
+style with the following adjustment:
+\begin{verbatim}
+\renewcommand{\glstreepredesc}{%
+ \glstreeitem\parindent\hangindent}
+\end{verbatim}
+
+
\item[altlistgroup] The \glostyle{altlistgroup} style is like
\glostyle{altlist} but the glossary groups have headings.
@@ -9898,10 +9946,24 @@ ignores both the \gls{numberlist} and the symbol. The length
governs where the description should start. This is a flat style, so
child entries are formatted in the same way as the parent entries.
+A non-list alternative is to use the \glostyle{index} style
+with
+\begin{verbatim}
+\renewcommand{\glstreepredesc}{\dotfill}
+\renewcommand{\glstreechildpredesc}{\dotfill}
+\end{verbatim}
+Note that this doesn't use \cs{glslistdottedwidth} and causes
+the description to be flush-right and will display the
+symbol, if provided. (It also doesn't suppress
+the \gls*{numberlist}, but that can be achieved with the
+\pkgopt{nonumberlist} option.)
+
\item[sublistdotted] This is a variation on the \glostyle{listdotted}
style designed for hierarchical glossaries. The main entries
have just the name displayed. The sub entries are displayed in
-the same manner as \glostyle{listdotted}.
+the same manner as \glostyle{listdotted}. Unlike the
+\glostyle{listdotted} style, this style is incompatible with
+\sty{classicthesis}.
\end{description}
@@ -10356,7 +10418,9 @@ glossaries but can also be used with glossaries that don't have
sub-entries. These styles will display the entry's symbol if it
exists. Note that these styles will automatically be available
unless you use the \pkgopt{notree} or \pkgopt{nostyles} package
-options. These styles all format the entry name using:
+options.
+
+These styles all format the entry name using:
\begin{definition}[\DescribeMacro\glstreenamefmt]
\cs{glstreenamefmt}\marg{name}
\end{definition}
@@ -10379,6 +10443,30 @@ which defaults to \cs{glstreenamefmt}\marg{text}. Note that this is
different from \cs{glslistnavigationitem}, provided with the styles
such as \glostyle{listhypergroup}, as that also includes \cs{item}.
+With the exception of the \glostyle{alttree} style (and those
+derived from it), the space before the description for top-level
+entries is produced with
+\begin{definition}[\DescribeMacro\glstreepredesc]
+\cs{glstreepredesc}
+\end{definition}
+This defaults to \cs{space}.
+
+With the exception of the \glostyle{treenoname} and
+\glostyle{alttree} styles (and those derived from them), the
+space before the description for child
+entries is produced with
+\begin{definition}[\DescribeMacro\glstreechildpredesc]
+\cs{glstreechildpredesc}
+\end{definition}
+This defaults to \cs{space}.
+
+\begin{important}
+Most of these styles are not designed for multi-paragraph
+descriptions. (The \glostyle{tree} style isn't too bad for
+multi-paragraph top-level entry descriptions, or you can use the
+\glostyle{index} style with the adjustment shown below.)
+\end{important}
+
\begin{description}
\item[index] The \glostyle{index} style is similar to the way
indices are usually formatted in that it has a hierarchical
@@ -10389,6 +10477,37 @@ Sub-entries are indented and also include the name, the symbol
in brackets (if present) and the description. Groups are separated
using \ics{indexspace}.
+Each main level item is started with
+\begin{definition}[\DescribeMacro\glstreeitem]
+\cs{glstreeitem}
+\end{definition}
+The level~1 entries are started with
+\begin{definition}[\DescribeMacro\glstreesubitem]
+\cs{glstreesubitem}
+\end{definition}
+
+The level~2 entries are started with
+\begin{definition}[\DescribeMacro\glstreesubsubitem]
+\cs{glstreesubsubitem}
+\end{definition}
+
+Note that the \glostyle{index} style automatically sets
+\begin{verbatim}
+\let\item\glstreeitem
+\let\subitem\glstreesubitem
+\let\subsubitem\glstreesubsubitem
+\end{verbatim}
+at the start of the glossary for backward compatibility.
+
+The \glostyle{index} style isn't suitable for multi-paragraph
+descriptions, but this limitation can be overcome by redefining
+the above commands. For example:
+\begin{verbatim}
+\renewcommand{\glstreeitem}{%
+ \parindent0pt\par\hangindent40pt
+ \everypar{\parindent50pt\hangindent40pt}}
+\end{verbatim}
+
\item[indexgroup] The \glostyle{indexgroup} style is similar to
the \glostyle{index} style except that each group has a heading
obtained using \cs{glsgetgrouptitle}\marg{label},