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 | 178 |
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] |