diff options
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 | 257 |
1 files changed, 255 insertions, 2 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 bb87202eee7..bb471d80816 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 @@ -225,13 +225,13 @@ styles (glossaries):>#1={\protect\ttfamily#1}|main}} \DeleteShortVerb{\|} \MakeShortVerb{"} - \title{glossaries-extra.sty v1.39: + \title{glossaries-extra.sty v1.40: an extension to the glossaries package} \author{Nicola L.C. Talbot\\[10pt] Dickimaw Books\\ \url{http://www.dickimaw-books.com/}} - \date{2019-03-22} + \date{2019-03-31} \maketitle \begin{abstract} @@ -1017,6 +1017,13 @@ which is equivalent to \begin{alltt} \cs{printglossary}[type=\cs{glsxtrabbrvtype},\meta{options}] \end{alltt} +If \sty{glossaries-extra-bib2gls} is also loaded then this option +will additionally provide: +\begin{definition}[\DescribeMacro\printunsrtabbreviations] +\cs{printunsrtabbreviations}\oarg{options} +\end{definition} +which uses \ics{printunsrtglossary}. + The title of the new glossary is given by \begin{definition}[\DescribeMacro\abbreviationsname] \cs{abbreviationsname} @@ -1063,6 +1070,13 @@ which is equivalent to Note that the \gloskey{sort} key is set to the \meta{label} not the \meta{symbol} as the symbol will likely contain commands. +If \sty{glossaries-extra-bib2gls} is also loaded then this option +will additionally provide: +\begin{definition}[\DescribeMacro\printunsrtsymbols] +\cs{printunsrtsymbols}\oarg{options} +\end{definition} +which uses \ics{printunsrtglossary}. + \item[{\pkgoptdef{numbers}}] This is passed to \styfmt{glossaries} but will additionally define \begin{definition}[\DescribeMacro\glsxtrnewnumber] @@ -1074,6 +1088,37 @@ which is equivalent to sort=\marg{label},type=numbers,category=number,\meta{options}\} \end{alltt} +If \sty{glossaries-extra-bib2gls} is also loaded then this option +will additionally provide: +\begin{definition}[\DescribeMacro\printunsrtnumbers] +\cs{printunsrtnumbers}\oarg{options} +\end{definition} +which uses \ics{printunsrtglossary}. + +\item[{\pkgoptdef{acronyms} (or \pkgoptdef{acronym})}] This is +passed to \styfmt{glossaries} but if +\sty{glossaries-extra-bib2gls} is also loaded then this option +will additionally provide: +\begin{definition}[\DescribeMacro\printunsrtacronyms] +\cs{printunsrtacronyms}\oarg{options} +\end{definition} +which uses \ics{printunsrtglossary}. + +\begin{important} +This option defines a new glossary with the label \texttt{acronym} +not \texttt{acronyms}. You may find it easier to reference it +with the command \ics{acronymtype}. +\end{important} + +\item[{\pkgoptdef{index}}] This is +passed to \styfmt{glossaries} but if +\sty{glossaries-extra-bib2gls} is also loaded then this option +will additionally provide: +\begin{definition}[\DescribeMacro\printunsrtindex] +\cs{printunsrtindex}\oarg{options} +\end{definition} +which uses \ics{printunsrtglossary}. + \item[{\pkgoptdef{shortcuts}}] Unlike the \styfmt{glossaries} package option of the same name, this option isn't boolean but has multiple values: @@ -3870,6 +3915,178 @@ and \end{description} +\section{\styfmt{glossary-topic} package} +\label{sec:topic} + +As from version 1.40, the \styfmt{glossaries-extra} package comes +with the supplementary package \sty{glossary-topic} that +provides glossary styles designed for hierarchical glossaries +where the top-level entries are topic titles. This package +automatically loads the \sty{multicols} package. If the +\sty{glossary-tree} package is also loaded then commands like +\cs{glssetwidest} can be used on these styles in much the same way +as for the \glostyle{alttree} style. If a widest value isn't set +then these styles behave more like the \glostyle{tree} style. +\begin{description} +\item[\glostyle{topic}] This style is similar to the \glostyle{tree} +style but the indentation doesn't start until the second +sub-item level. The top-level entries have the name displayed +in a larger font with the description following in a new paragraph. +This style doesn't support the \pkgopt{nogroupskip} setting. + +\item[\glostyle{topicmcols}] This style is like the \glostyle{topic} +style but the sub-entries are placed inside a \env{multicols} +environment. The environment name is supplied in the value of +the command: +\begin{definition}[\DescribeMacro\glstopicColsEnv] +\cs{glstopicColsEnv} +\end{definition} +You can change this to the starred form. For example: +\begin{verbatim} +\renewcommand{\glstopicColsEnv}{multicols*} +\end{verbatim} +The number of columns is given by the command: +\begin{definition}[\DescribeMacro\glstopicCols] +\cs{glstopicCols} +\end{definition} +The default value is 2. +\end{description} +Both styles use the following commands. +\begin{definition}[\DescribeMacro\glstopicParIndent] +\cs{glstopicParIndent} +\end{definition} +This command is a length that's used for the paragraph indentation +in any multi-paragraph description for top-level entries, but not +for the first paragraph (at the start of the description) which +isn't indented. + +\begin{definition}[\DescribeMacro\glstopicSubIndent] +\cs{glstopicSubIndent} +\end{definition} +This command is a length that's used to calculate the hanging +indentation for sub-entries. The level~1 sub-entries don't indent +the name. Level~$n$ sub-entries have the name indented by +$(n-1)\times$\cs{glstopicSubIndent}. The hanging indent depends +on whether or not a widest name has been set for the level. + +\begin{definition}[\DescribeMacro\glstopicInit] +\cs{glstopicInit} +\end{definition} +Hook used at the start of the glossary. Does nothing by default. + +Although the styles don't support letter groups by default, if you +have many topics (top-level entries) and you feel that it would help +the reader to divide them up into headed letter groups, you can +redefine: +\begin{definition}[\DescribeMacro\glstopicGroupHeading] +\cs{glstopicGroupHeading}\marg{group label} +\end{definition} +This does nothing by default. If you want to redefine it, you can +fetch the title corresponding to the group label with +\cs{glsxtrgetgrouptitle}. For example: +\begin{verbatim} +\renewcommand*{\glstopicGroupHeading}[1]{% + \glsxtrgetgrouptitle{#1}{\thisgrptitle}% + \section*{\thisgrptitle}% +} +\end{verbatim} +Remember that if you use \gls{bib2gls}, you will need the +\verb|--group| (or \verb|-g|) switch to support this. + +\begin{definition}[\DescribeMacro\glstopicItem] +\cs{glstopicItem}\marg{label}\marg{location list} +\end{definition} +Used to format the name, symbol, description and location list +for the top-level entries. This starts with a paragraph break +followed by: +\begin{definition}[\DescribeMacro\glstopicPreSkip] +\cs{glstopicPreSkip} +\end{definition} +which defaults to \cs{medskip}. There is then a hook: +\begin{definition}[\DescribeMacro\glstopicMarker] +\cs{glstopicMarker}\marg{label} +\end{definition} +which does nothing by default, but may be redefined. For example, +to add a line to the table of contents. +The name and symbol are set in the +form of a title using: +\begin{definition}[\DescribeMacro\glstopicTitle] +\cs{glstopicTitle}\marg{label} +\end{definition} +This uses \cs{Glossentryname} which converts the first letter to +upper case. If there's a symbol, this is added in parentheses. +Both name and symbol (if present) are encapsulated by +\begin{definition}[\DescribeMacro\glstopicTitleFont] +\cs{glstopicTitleFont}\marg{text} +\end{definition} +This uses a bold, large font by default. + +If the entry has the description key set (tested with +\cs{ifglshasdesc}) then a paragraph break is inserted followed by: +\begin{definition}[\DescribeMacro\glstopicMidSkip] +\cs{glstopicMidSkip} +\end{definition} +which defaults to \cs{smallskip}. This is followed by the +description which is formatted according to: +\begin{definition}[\DescribeMacro\glstopicDesc] +\cs{glstopicDesc}\marg{label} +\end{definition} +This just does \cs{Glossentrydesc}\marg{label} followed +by the post-description hook. + +A paragraph break followed by: +\begin{definition}[\DescribeMacro\glstopicPostSkip] +\cs{glstopicPostSkip} +\end{definition} +comes next regardless of whether or not the description was +displayed. This defaults to \cs{smallskip}. This is then followed +by: +\begin{definition}[\DescribeMacro\glstopicLoc] +\cs{glstopicLoc}\marg{label}\marg{location list} +\end{definition} +which may be used to display the location list, but does nothing by +default. + +The sub-entries first set up the paragraph and hanging indentations +using: +\begin{definition}[\DescribeMacro\glstopicAssignSubIndent] +\cs{glstopicAssignSubIndent}\marg{level} +\end{definition} +This uses: +\begin{definition}[\DescribeMacro\glstopicAssignWidest] +\cs{glstopicAssignWidest}\marg{level} +\end{definition} +to determine if a widest name has been set for the given level. + +The sub-entry has its information displayed using: +\begin{definition}[\DescribeMacro\glstopicSubItem] +\cs{glstopicSubItem}\marg{level}\marg{label}\marg{location} +\end{definition} +This encapsulates the name with: +\begin{definition}[\DescribeMacro\glstopicSubNameFont] +\cs{glstopicSubNameFont}\marg{text} +\end{definition} +By default this just uses \cs{textbf}. This is followed by: +\begin{definition}[\DescribeMacro\glstopicSubItemSep] +\cs{glstopicSubItemSep} +\end{definition} +which defaults to \cs{quad}. The name and separator are +passed in the \meta{text} argument of: +\begin{definition}[\DescribeMacro\glstopicSubItemBox] +\cs{glstopicSubItemBox}\marg{level}\marg{text} +\end{definition} +If a widest name was set for the given level, this will +put \meta{text} inside a box of that width otherwise it just does +\meta{text}. + +This is followed by the symbol in parentheses if set, then +the description and post-description hook, and finally the location +list is displayed using: +\begin{definition}[\DescribeMacro\glstopicSubLoc] +\cs{glstopicSubLoc}\marg{label}\marg{location} +\end{definition} +which just does a space followed by \meta{location} by default. + \section{Glossary Style Modifications} \label{sec:glosstylemods} @@ -4439,6 +4656,25 @@ the accompanying sample files \texttt{sample-alttree.tex}, \chapter{Abbreviations} \label{sec:abbreviations} +The new abbreviation system provided by \styfmt{glossaries-extra} +is more flexible than the acronym handling provided by the +base \styfmt{glossaries} package. The \styfmt{glossaries-extra} +package modifies the underlying formatting used by +\cs{gls} (and its variants) so that terms that are recognised as +abbreviations can have their formatting dealt with by the style. You +therefore need to select an abbreviation style that ensures that +\cs{gls} (and its variants) displays the desired output. + +\begin{important} +Don't use commands like \cs{glstext} or \cs{glsfirst} with +abbreviations as they aren't flexible enough to handle some +abbreviation styles and unexpected results may occur. Use commands +like \cs{glsfmtshort} or \cs{glsfmtlong} in section headings or +captions instead of \cs{gls}. If you don't want the full form to +show on first use of \cs{gls} use one of the \qt{nolong} or +\qt{noshort} styles. +\end{important} + Abbreviations include acronyms (words formed from initial letters, such as \qt{laser}), initialisms (initial letters of a phrase, such as \qt{html}, that @@ -8622,6 +8858,12 @@ search for the existence of document dialect (where \meta{script} is the four letter script identifier, such as \texttt{Latn}). +This package provides some shortcut commands that use +\ics{printunsrtglossary} if the relevant package option has defined +the associated glossary: \ics{printunsrtabbreviations}, +\ics{printunsrtacronyms}, \ics{printunsrtsymbols}, +\ics{printunsrtnumbers} and \ics{printunsrtindex}. + \begin{definition}[\DescribeMacro\glsxtrprovidecommand] \cs{glsxtrprovidecommand}\marg{cs}\oarg{n}\oarg{default}\marg{definition} \end{definition} @@ -9600,6 +9842,17 @@ you can just use, for example, \verb|\u E6| instead of \verb|\string\uE6| in the custom rule. This redefinition of \cs{u} is scoped so its original definition is restored after the write operation. +If you have multiple resource commands and you want a default set of +options you can supply them in the definition of: +\begin{definition}[\DescribeMacro\GlsXtrDefaultResourceOptions] +\cs{GlsXtrDefaultResourceOptions} +\end{definition} +For example: +\begin{verbatim} +\renewcommand{\GlsXtrDefaultResourceOptions}{selection=all} +\end{verbatim} +This should be done before the resource commands. + It's possible to specify label prefixes. For example, modifying the earlier example: \begin{verbatim} |