summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex
diff options
context:
space:
mode:
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.tex257
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}