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.tex178
1 files changed, 171 insertions, 7 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 459aad1f0d1..39a9e6e1c4d 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
@@ -139,13 +139,13 @@ styles (glossaries):>#1={\protect\ttfamily#1}|main}}
\MakeShortVerb{"}
\DeleteShortVerb{\|}
- \title{glossaries-extra.sty v1.01:
+ \title{glossaries-extra.sty v1.02:
an extension to the glossaries package}
\author{Nicola L.C. Talbot\\[10pt]
Dickimaw Books\\
\url{http://www.dickimaw-books.com/}}
- \date{2016-02-02}
+ \date{2016-04-25}
\maketitle
\begin{abstract}
@@ -189,8 +189,11 @@ package weight and manual size).
The \styfmt{glossaries-extra} package is an attempt to provide
a~compromise for this
-conflict. Version 4.21 of the \styfmt{glossaries} package is
-the last version to incorporate new features. Future versions of
+conflict. Version 4.22 of the \styfmt{glossaries} package is
+the last version to incorporate new features.\footnote{4.21 was
+originally intended as the last release of \styfmt{glossaries} to
+incorporate new features, but a few new minor features slipped in with
+some bug fixes in v4.21.} Future versions of
\styfmt{glossaries} will just be bug fixes. New features will
instead be added to \styfmt{glossaries-extra}.
This means that the base \styfmt{glossaries} package won't increase
@@ -408,6 +411,14 @@ a~package option (not through \ics{glossariesextrasetup}) since the \sty{glossar
package must be loaded before \styfmt{glossaries-extra} if it's
required.
+\item[{\pkgopt{stylemods}}] This is a
+\meta{key}=\meta{value} option used to load the
+\sty{glossaries-extra-stylemods} package. The value may be a
+comma-separated list of options to pass to that package. (Remember
+to group \meta{value} if it contains any commas.) The value may be
+omitted if no options need to be passed. See \sectionref{sec:glosstylemods}
+for further details.
+
\item[{\pkgopt{undefaction}}] This is a \meta{key}=\meta{value}
option, which has two allowed values: \pkgoptfmt{warn} and
\pkgoptfmt{error}. This indicates what to do if an undefined
@@ -760,6 +771,9 @@ Note that commands like \ics{glsfirst} and \ics{glsxtrfull} fake
\cs{glsxtrifwasfirstuse} to \cs{@firstoftwo}.
(Although, depending on the styles in use, they may not exactly match
the text produced by \ics{gls}-like commands on \gls{firstuse}.)
+However, the \abbrstyle{postfootnote} style alters \cs{glsxtrfull}
+so that it fakes non-\gls{firstuse} otherwise the inline full format
+would include the footnote, which is inappropriate.
\end{important}
For example, if you want to place the description in a footnote
@@ -872,7 +886,7 @@ Things can go wrong if we try the following with the
The main problems are:
\begin{enumerate}
-\item The first letter upper casing commands, such as \ics{Gls},
+\item\label{itm:nestedfirstucprob} The first letter upper casing commands, such as \ics{Gls},
won't work for the \texttt{shtml} entry on \gls{firstuse} if the
long form is displayed before the short form (which is the
default abbreviation style). This will attempt to do
@@ -893,6 +907,9 @@ version, such as \ics{GLS}.
and so can't be used be used in contexts that require this,
such as PDF bookmarks.
+\item\label{itm:nestedsortprob} The nested commands may end up in the \gloskey{sort} key,
+which will confuse the indexing.
+
\item The \texttt{shtml} entry produces inconsistent results
depending on whether the \texttt{ssi} or \texttt{html} entries have
been used. Suppose both \texttt{ssi} and \texttt{html} are used
@@ -940,7 +957,8 @@ So the \gls{firstuse} of the \texttt{shtml} entry now produces
\qt{server side includes (SSI) enabled hypertext markup language (HTML)
(SHTML)}, which is even more strange.
-This is all aggravated by setting the style using
+This is all aggravated by setting the style using the
+\styfmt{glossaries} package's
\cs{setacronymstyle}. For example:
\begin{verbatim}
\setacronymstyle{long-short}
@@ -1002,6 +1020,20 @@ Note that replacing \cs{gls} with \cs{acrshort} in the original
example may fix the \gls{firstuse} issue, but it doesn't
fix any of the other problems listed above.
+If it's simply that you want to use the abbreviation font, you can
+use \cs{glsabbrvfont}:
+\begin{verbatim}
+\setabbreviationstyle{long-short-sc}
+
+\newabbreviation{ssi}{ssi}{server-side includes}
+\newabbreviation{html}{html}{hypertext markup language}
+\newabbreviation{shtml}{shtml}{\glsabbrvfont{ssi} enabled
+\glsabbrvfont{html}}
+\end{verbatim}
+This will pick up the font style setting of the outer entry (shtml,
+in the above case). This isn't a problem in the above example as all
+the abbreviations use the same style.
+
However if you're really determined to use
\ics{gls} in a field that may be included within
some \gls{linktext}, \styfmt{glossaries-extra} patches internals
@@ -1021,6 +1053,10 @@ is treated as
\end{verbatim}
This overcomes the last three problems listed
above, but still doesn't fix the first two.
+Problem~\ref{itm:nestedsortprob} usually won't be an issue as most abbreviation
+styles set the \gloskey{sort} key to the short form, so using these
+commands in the long form but not the short form will only affect
+entries with a style that sorts according to the long form.
Additionally, any instance of the long form commands, such
as \ics{glsxtrlong} or \ics{acrlong} will be temporarily
@@ -1067,6 +1103,12 @@ don't use any of the linking commands, such as \ics{gls} or
fields that may be used by those case-changing commands.
\end{important}
+You can, with care, protect against issue~\ref{itm:nestedfirstucprob} by
+inserting an empty group at the start if the long form starts with a
+command that breaks the first letter uppercasing commands like
+\cs{Gls}, but you still won't be able to use the all caps commands,
+such as \cs{GLS}.
+
\subsection{Acronym Style Modifications}
\label{sec:acronymmods}
@@ -1181,6 +1223,55 @@ nothing instead of using the \pkgopt{nopostdot} option to suppress
the terminating full stop.)
\end{important}
+As from v1.02, \styfmt{glossaries-extra} now includes the package
+\sty{glossaries-extra-stylemods} that will redefine the predefined
+styles to include the post-description hook (for those that are
+missing it). You will need to make sure the styles have already
+been defined before loading \sty{glossaries-extra}. For example:
+\begin{verbatim}
+\usepackage{glossaries-extra}
+\usepackage{glossary-longragged}
+\usepackage{glossaries-extra-stylemods}
+\end{verbatim}
+Alternatively you can load
+\texttt{glossary-}\meta{name}\texttt{.sty} at the same time by
+passing \meta{name} as a package option to
+\sty{glossaries-extra-stylemods}. For example:
+\begin{verbatim}
+\usepackage{glossaries-extra}
+\usepackage[longragged]{glossaries-extra-stylemods}
+\end{verbatim}
+Another option is to use the \pkgopt{stylemods} key when you
+load \styfmt{glossaries-extra}. You can omit a value if you only want to use
+the predefined styles that are automatically loaded by
+\styfmt{glossaries} (for example, the \glostyle{long3col} style):
+\begin{verbatim}
+\usepackage[style=long3col,stylemods]{glossaries-extra}
+\end{verbatim}
+Or the value of \pkgopt{stylemods} may be a comma-separated list
+of the style package identifiers. For example:
+\begin{verbatim}
+\usepackage[style=mcoltree,stylemods=mcols]{glossaries-extra}
+\end{verbatim}
+Remember to group the value if it contains any commas:
+\begin{verbatim}
+\usepackage[stylemods={mcols,longbooktabs}]{glossaries-extra}
+\end{verbatim}
+
+Note that the \glostyle{inline} style is dealt with slightly
+differently. The original definition provided by the
+\sty{glossary-inline} package uses \cs{glspostdescription} at the
+end of the glossary (not after each entry description) within the
+definition of \cs{glspostinline}. The style modification changes
+this so that \cs{glspostinline} just does a full stop followed by
+space factor adjustment, and the description
+\cs{glsinlinedescformat} and sub-entry description formats
+\cs{glsinlinesubdescformat} are redefined to include
+\cs{glsxtrpostdescription} (not \cs{glspostdescription}). This means
+that the modified \glostyle{inline} style isn't affected by the
+\pkgopt{nopostdot} option, but the post-description category hook
+can still be used.
+
\chapter{Abbreviations}
\label{sec:abbreviations}
@@ -1300,6 +1391,26 @@ the long form on \gls{firstuse} for all your abbreviations, or you can
define your own abbreviation style that provides a different format
for only those abbreviations defined with that style.
+Note that by default inserted material (provided in the final
+optional argument of commands like \cs{gls}), is placed outside the
+font command in the predefined styles. To move it inside, use:
+\begin{definition}[\DescribeMacro\glsxtrinsertinsidetrue]
+\cs{glsxtrinsertinsidetrue}
+\end{definition}
+This applies to all the predefined styles. For example:
+\begin{verbatim}
+\setabbreviationstyle{long-short}
+\renewcommand*{\glsfirstlongdefaultfont}[1]{\emph{#1}}
+\glsxtrinsertinsidetrue
+\end{verbatim}
+This will make the long form and in the inserted text emphasized,
+whereas the default (without \cs{glsxtrinsertinsidetrue}) would
+place the inserted text outside of the emphasized font.
+
+Note that for some styles, such as the \abbrstyle{short-long}, the
+inserted text would be placed inside the font command for the short
+form (rather than the long form in the above example).
+
There are two types of full forms. The display full form, which is
used on \gls{firstuse} by commands like \ics{gls} and the inline full
form, which is used by commands like \ics{glsxtrfull}.
@@ -1876,6 +1987,9 @@ following punctuation character that's recognised by
The inline full form uses the \meta{short}
(\meta{long}) style. The \gloskey{name} is set to the short form.
The \gloskey{description} is set to the long form.
+Note that this style will change \cs{glsxtrfull} (and it's variants)
+so that it fakes non-\gls{firstuse}. (Otherwise the footnote would
+appear after the inline form.)
\item[\abbrstyle{postfootnote-sc}]
Like \abbrstyle{postfootnote} but redefines \cs{glsabbrvfont} to
@@ -2188,7 +2302,7 @@ existing style are the \qt{em} styles, such as the
}
\end{verbatim}
-\chapter{Entries in Sectioning Titles, Headers and Contents}
+\chapter{Entries in Sectioning Titles, Headers, Captions and Contents}
\label{sec:headtitle}
The \sty{glossaries} user manual cautions against using commands
@@ -2212,6 +2326,8 @@ PDF bookmark (with a warning from \sty{hyperref});
\item if you use \sty{hyperref}, you will end up with nested hyperlinks
in the table of contents.
\end{itemize}
+Similar problems can also occur with captions (except for the page
+header and bookmark issues).
To get around all these problems, the \sty{glossaries} user manual
recommends using the expandable non-hyperlink commands, like
@@ -2314,6 +2430,54 @@ First letter upper case plural short form:
\end{definition}
(No case-change applied to PDF bookmarks.)
+Display the long form:
+\begin{definition}[\DescribeMacro\glsfmtlong]
+\cs{glsfmtlong}\marg{label}
+\end{definition}
+
+Display the plural long form:
+\begin{definition}[\DescribeMacro\glsfmtlongpl]
+\cs{glsfmtlongpl}\marg{label}
+\end{definition}
+
+First letter upper case singular long form:
+\begin{definition}[\DescribeMacro\Glsfmtlong]
+\cs{Glsfmtlong}\marg{label}
+\end{definition}
+(No case-change applied to PDF bookmarks.)
+
+First letter upper case plural long form:
+\begin{definition}[\DescribeMacro\Glsfmtlongpl]
+\cs{Glsfmtlongpl}\marg{label}
+\end{definition}
+(No case-change applied to PDF bookmarks.)
+
+There are similar commands for the full form, but note that these
+use the \emph{inline} full form, which may be different from the
+full form used by \cs{gls}.
+
+Display the full form:
+\begin{definition}[\DescribeMacro\glsfmtfull]
+\cs{glsfmtfull}\marg{label}
+\end{definition}
+
+Display the plural full form:
+\begin{definition}[\DescribeMacro\glsfmtfullpl]
+\cs{glsfmtfullpl}\marg{label}
+\end{definition}
+
+First letter upper case singular full form:
+\begin{definition}[\DescribeMacro\Glsfmtfull]
+\cs{Glsfmtfull}\marg{label}
+\end{definition}
+(No case-change applied to PDF bookmarks.)
+
+First letter upper case plural full form:
+\begin{definition}[\DescribeMacro\Glsfmtfullpl]
+\cs{Glsfmtfullpl}\marg{label}
+\end{definition}
+(No case-change applied to PDF bookmarks.)
+
There are also equivalent commands for the value of the
\gloskey{text} field:
\begin{definition}[\DescribeMacro\glsfmttext]