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.tex99
1 files changed, 90 insertions, 9 deletions
diff --git a/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex b/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex
index ca53bf11c96..79edf330817 100644
--- a/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex
+++ b/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex
@@ -447,11 +447,11 @@ and~\hyperlink{option#2}{#2}}
\MakeShortVerb{"}
\DeleteShortVerb{\|}
- \title{User Manual for glossaries.sty v4.35}
+ \title{User Manual for glossaries.sty v4.36}
\author{Nicola L.C. Talbot\\%
\url{http://www.dickimaw-books.com/}}
- \date{2017-11-14}
+ \date{2018-03-07}
\maketitle
\begin{abstract}
@@ -536,7 +536,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.35}.
+\qt{Documented Code for glossaries v4.36}.
\item[INSTALL] Installation instructions.
@@ -553,6 +553,11 @@ FAQ}
\item \href{http://www.dickimaw-books.com/gallery/glossaries-styles/}{\styfmt{glossaries}
gallery}
+\item
+\href{http://www.dickimaw-books.com/gallery/glossaries-performance.shtml}{\styfmt{glossaries}
+performance} (comparing document build times for the different
+options provided by \styfmt{glossaries} and \styfmt{glossaries-extra}).
+
\item \href{http://www.dickimaw-books.com/latex/thesis/}{Using LaTeX to Write a PhD Thesis}
(chapter 6).
@@ -616,6 +621,45 @@ referenced using any of the commands described in
\sectionref{sec:glslink} and \sectionref{sec:glsadd} or via
\ics{glssee} (or the \gloskey{see} key) or commands such as
\ics{acrshort}.}\ in the document will be added to the glossary.
+The \styfmt{glossaries-extra} package, which is distributed as a
+separated bundle, extends the capabilities of
+the \styfmt{glossaries} package. The simplest document can be
+created with \styfmt{glossaries-extra} (which internally loads the
+\styfmt{glossaries} package):
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage[
+ sort=none,% no sorting or indexing required
+ abbreviations,% create list of abbreviations
+ symbols,% create list of symbols
+ postdot % append a full stop after the descriptions
+]{glossaries-extra}
+
+\newglossaryentry % provided by glossaries.sty
+ {cafe}% label
+ {% definition:
+ name={caf\'e},
+ description={small restaurant selling refreshments}
+ }
+
+\newabbreviation % provided by glossaries-extra.sty
+ {html}% label
+ {HTML}% short form
+ {hypertext markup language}% long form
+
+\glsxtrnewsymbol % provided by glossaries-extra.sty 'symbols' option
+ [description={Archimedes' constant}]% options
+ {pi}% label
+ {\ensuremath{\pi}}% symbol
+
+\begin{document}
+First use: \gls{cafe}, \gls{html}, \gls{pi}.
+Next use: \gls{cafe}, \gls{html}, \gls{pi}.
+
+\printunsrtglossaries % list all defined entries
+\end{document}
+\end{verbatim}
\textbf{This package replaces the \sty{glossary} package which is
now obsolete.} Please see the document \qtdocref{Upgrading from the
@@ -691,6 +735,10 @@ commands that must come before \cs{makeglossaries} (such as
\cs{newglossary}) and they can't switch off the indexing whilst
working on a draft document.
+For a comparison of the various methods when used with large entry
+sets or when used with symbols such as \cs{alpha}, see the
+\href{http://www.dickimaw-books.com/gallery/glossaries-performance.shtml}{\styfmt{glossaries} performance page}.
+
\begin{table}[htbp]
\caption{Glossary Options: Pros and Cons}
\label{tab:options}
@@ -2353,16 +2401,27 @@ definition of \cs{glossariescaptions}\meta{lang}, replace the
English text (such as \qt{Glossaries}) with the appropriate
translation.
+\label{pluralsuffix}%
\textbf{Note:} the suffixes used to generate the plural forms when
the plural hasn't been specified are given by
\cs{glspluralsuffix} (for general entries) and
\cs{glsupacrpluralsuffix} for acronyms where the suffix needs to be
set using \cs{glstextup} to counteract the effects of \cs{textsc}
-and \cs{glsacrpluralsuffix} for other acronym styles. These commands
-need to be set before the entry is defined and so the definitions
-aren't included in the caption mechanism as that's not switched on
-until the start of the document. This means that the suffix in
-effect will be for the last loaded language.
+and \cs{glsacrpluralsuffix} for other acronym styles. There's no
+guarantee when these commands will be expanded. They may be expanded
+on definition or they may be expanded on use, depending on the
+\styfmt{glossaries} configuration.
+
+\begin{important}
+Therefore these plural suffix command definitions
+aren't included in the caption mechanism as that's typically not switched on
+until the start of the document. \textbf{This means that the suffix in
+effect will be for the last loaded language that redefined these
+commands.} It's best to initialise these commands to the most common
+suffix required in your document and use the \gloskey{plural},
+\gloskey{longplural}, \gloskey{shortplural} etc keys to override
+exceptions.
+\end{important}
If you want to add a regional variation, create a file called
\texttt{glossaries-}\meta{iso lang}\texttt{-}\meta{iso
@@ -2779,7 +2838,7 @@ resulting file onto the man path. Alternatively do
\begin{important}
When upgrading the \styfmt{glossaries} package, make sure you also
upgrade your version of \gls{makeglossaries}. The current version is
-4.35.
+4.36.
\end{important}
\subsection{Using the makeglossaries-lite Lua Script}
@@ -4280,6 +4339,11 @@ interested in using this \texttt{symbols} glossary and don't intend
to use the \texttt{main} glossary.
\end{important}
+The \styfmt{glossaries-extra} package has a slightly modified
+version of this option which additionally provides \ics{glsxtrnewsymbol}
+as a convenient shortcut method for defining symbols. See the
+\styfmt{glossaries-extra} manual for further details.
+
\item[\pkgopt{numbers}] This option defines a new glossary type with
the label \texttt{numbers} via
\begin{verbatim}
@@ -4306,6 +4370,11 @@ interested in using this \texttt{numbers} glossary and don't intend
to use the \texttt{main} glossary.
\end{important}
+The \styfmt{glossaries-extra} package has a slightly modified
+version of this option which additionally provides \ics{glsxtrnewnumber}
+as a convenient shortcut method for defining numbers. See the
+\styfmt{glossaries-extra} manual for further details.
+
\item[\pkgopt{index}] This option defines a new glossary type with
the label \texttt{index} via
\begin{verbatim}
@@ -8990,6 +9059,18 @@ the \gloskey{longplural} or \gloskey{shortplural} keys, I recommend
you use \ics{setacronymstyle} to set the display style rather than
using one of the pre-version 4.02 acronym styles.
+As with \gloskey{plural} and \gloskey{firstplural}, if
+\gloskey{longplural} is missing, it's obtained by appended
+\ics{glspluralsuffix} to the singular form. The short plural
+\gloskey{shortplural} is obtained (is not explicitly set) by appending
+\ics{glsacrpluralsuffix} to the short form. These commands may be
+changed by the associated language files, but they can't be added to
+the usual caption hooks as there's no guarantee when they'll be
+expanded (as \hyperref[pluralsuffix]{discussed earlier}).
+A different approach is used by \styfmt{glossaries-extra}, which has
+category attributes to determine whether or not to append a suffix
+when forming the default value of \gloskey{shortplural}.
+
Since \ics{newacronym} uses \ics{newglossaryentry}, you can use
commands like \ics{gls} and \ics{glsreset} as with any other
glossary entry.