diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex | 157 |
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}, |