summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2016-08-15 20:33:22 +0000
committerKarl Berry <karl@freefriends.org>2016-08-15 20:33:22 +0000
commit9f03d540e781cc9b40ca96a442b49c91d98d841e (patch)
tree8a9a1054005606820175b4275c8e939ecb431cf2 /Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex
parent1850016c7aa713d8e5b7e6ac583199a938407287 (diff)
glossaries-extra (16aug16)
git-svn-id: svn://tug.org/texlive/trunk@41856 c570f23f-e606-0410-a88d-b1316a301751
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.tex396
1 files changed, 365 insertions, 31 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 cf93ca072a9..291cd280f70 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
@@ -140,16 +140,16 @@ styles (glossaries):>#1={\protect\ttfamily#1}|main}}
\setlength\marginparwidth{70pt}
\begin{document}
-\MakeShortVerb{"}
\DeleteShortVerb{\|}
+\MakeShortVerb{"}
- \title{glossaries-extra.sty v1.06:
+ \title{glossaries-extra.sty v1.07:
an extension to the glossaries package}
\author{Nicola L.C. Talbot\\[10pt]
Dickimaw Books\\
\url{http://www.dickimaw-books.com/}}
- \date{2016-06-18}
+ \date{2016-08-15}
\maketitle
\begin{abstract}
@@ -178,6 +178,18 @@ or
\TeX\ on Linux}.)
\end{important}
+Additional resources:
+\begin{itemize}
+\item The \styfmt{glossaries-extra} documented code
+\href{http://mirrors.ctan.org/macros/latex/contrib/glossaries-extra/glossaries-extra-code.pdf}{glossaries-extra-code.pdf}.
+
+\item The
+\href{http://www.dickimaw-books.com/gallery/#glossaries-extra}{\styfmt{glossaries-extra} gallery}.
+
+\item
+\href{http://www.latex-community.org/know-how/latex/55-latex-general/263-glossaries-nomenclature-lists-of-symbols-and-acronyms}{Glossaries,
+Nomenclature, Lists of Symbols and Acronyms}.
+\end{itemize}
\tableofcontents
@@ -242,7 +254,12 @@ default if \sty{babel} hasn't been loaded.
\end{itemize}
-Examples:
+The examples below illustrate the difference in explicit
+package options between \styfmt{glossaries} and
+\styfmt{glossaries-extra}. There may be other differences
+resulting from modifications to commands provided by
+\styfmt{glossaries} (see \sectionref{sec:modifications}).
+
\begin{enumerate}
\item
\begin{verbatim}
@@ -863,6 +880,13 @@ if a full stop hasn't be discarded and
\end{definition}
if a full stop has been discarded.
+\begin{important}
+Avoid the use of \cs{gls}-like and \cs{glstext}-like commands
+within the post-link hook as they will cause interference.
+Consider using commands like \cs{glsentrytext}, \cs{glsaccesstext}
+or \cs{glsxtrp} (\sectionref{sec:nested}) instead.
+\end{important}
+
By default \cs{glsxtrpostlink} just does \postlinkcat\ if it exists, where
\meta{category} is the category label for the current entry.
(For example, for the \category{general} category,
@@ -1250,6 +1274,96 @@ The abbreviation style that governs \ics{glsabbrvfont} will be
set for \ics{glsxtrshort}. Note that \cs{acrshort} doesn't
set the abbreviation style.
+Alternatively you can use:
+\begin{definition}[\DescribeMacro\glsxtrp]
+\cs{glsxtrp}\marg{field}\marg{label}
+\end{definition}
+where \meta{field} is the field label and corresponds to a
+command in the form \cs{gls}\meta{field} (e.g.\ \cs{glstext}) or
+in the form \cs{glsxtr}\meta{field} (e.g.\ \cs{glsxtrshort}).
+
+There's a shortcut command for the most common fields:
+\begin{definition}[\DescribeMacro\glsps]
+\cs{glsps}\marg{label}
+\end{definition}
+which is equivalent to \verb|\glsxtrp{short}|\marg{label}, and
+\begin{definition}[\DescribeMacro\glspt]
+\cs{glspt}\marg{label}
+\end{definition}
+which is equivalent to \verb|\glsxtrp{text}|\marg{label}.
+
+The \cs{glsxtrp} command behaves much like the
+\cs{glsfmt}\meta{field} commands described in
+\sectionref{sec:headtitle} but the post-link hook is also
+suppressed and extra grouping is added. It automatically sets
+\gloskey[glslink]{hyper} to \texttt{false} and
+\gloskey[glslink]{noindex} to \texttt{true}. If you want to change
+this, you can use
+\begin{definition}[\DescribeMacro\glsxtrsetpopts]
+\cs{glsxtrsetpopts}\marg{options}
+\end{definition}
+For example:
+\begin{verbatim}
+\glsxtrsetpopts{hyper=false}
+\end{verbatim}
+will just switch off the hyperlinks but not the indexing.
+Be careful using this command or you can end up back to the
+original problem of nested links.
+
+The hyper link is re-enabled within glossaries. This is
+done through the command:
+\begin{definition}[\DescribeMacro\glossxtrsetpopts]
+\cs{glossxtrsetpopts}
+\end{definition}
+which by default just does
+\begin{verbatim}
+\glsxtrsetpopts{noindex}
+\end{verbatim}
+You can redefine this if you want to adjust the setting when
+\cs{glsxtrp} is used in the glossary. For example:
+\begin{verbatim}
+\renewcommand{\glossxtrsetpopts}{\glsxtrsetpopts{noindex=false}}
+\end{verbatim}
+
+For example,
+\begin{verbatim}
+\glsxtrp{short}{ssi}
+\end{verbatim}
+is equivalent to
+\begin{verbatim}
+{\let\glspostlinkhook\relax
+ \glsxtrshort[hyper=false,noindex]{ssi}[]%
+}
+\end{verbatim}
+in the main body of the document or
+\begin{verbatim}
+{\let\glspostlinkhook\relax
+ \glsxtrshort[noindex]{ssi}[]%
+}
+\end{verbatim}
+inside the glossary. (Note the post-link hook is locally disabled.)
+
+If \verb|\glsxtrp{short}{ssi}| occurs in a sectioning mark,
+it's equivalent to
+\begin{verbatim}
+{\glsxtrheadshort{ssi}}
+\end{verbatim}
+(which recognises the \catattr{headuc} attribute.)
+
+If \sty{hyperref} has been loaded, then the bookmark will
+use \cs{glsentry}\meta{field}
+(\verb|\glsentryshort{ssi}| in the above example).
+
+There are similar commands
+\begin{definition}[\DescribeMacro\Glsxtrp]
+\cs{Glsxtrp}\marg{field}\marg{label}
+\end{definition}
+for first letter upper case and
+\begin{definition}[\DescribeMacro\Glsxtrp]
+\cs{GLSxtrp}\marg{field}\marg{label}
+\end{definition}
+for all upper case.
+
\begin{important}
If you use any of the case-changing commands, such as \ics{Gls}
or \ics{Glstext}, (either all caps or first letter upper casing)
@@ -1264,20 +1378,163 @@ 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}.
+If you \emph{really need} nested commands, the safest method is
+\begin{verbatim}
+\newabbreviation{shtml}{shtml}{{}\glsxtrp{short}{ssi} enabled
+\glsxtrp{short}{html}}
+\end{verbatim}
+but be aware that it may have some unexpected results occasionally.
+
+Example document:
+\begin{verbatim}
+\documentclass{report}
+
+\usepackage[utf8]{inputenc}
+\usepackage[T1]{fontenc}
+\usepackage{slantsc}
+\usepackage[colorlinks]{hyperref}
+\usepackage[nopostdot=false]{glossaries-extra}
+
+\makeglossaries
+
+\setabbreviationstyle{long-short-sc}
+
+\newabbreviation{ssi}{ssi}{server-side includes}
+\newabbreviation{html}{html}{hypertext markup language}
+\newabbreviation{shtml}{shtml}{{}\glsps{ssi} enabled {}\glsps{html}}
+
+\pagestyle{headings}
+
+\glssetcategoryattribute{abbreviation}{headuc}{true}
+\glssetcategoryattribute{abbreviation}{glossdesc}{title}
+
+\begin{document}
+
+\tableofcontents
+
+\chapter{\glsfmtfull{shtml}}
+
+First use: \gls{shtml}, \gls{ssi} and \gls{html}.
+
+Next use: \gls{shtml}, \gls{ssi} and \gls{html}.
+
+\newpage
+Next page.
+
+\printglossaries
+\end{document}
+\end{verbatim}
+
\section{Acronym Style Modifications}
\label{sec:acronymmods}
The \styfmt{glossaries-extra} package provides a new way of dealing
with abbreviations and redefines \ics{newacronym} to
use \cs{newabbreviation} (see \sectionref{sec:abbreviations}).
-If you want to restore the generic acronym function provided
-by \styfmt{glossaries} you need to use
+The simplest way to update a document that uses
+\cs{newacronym} from \styfmt{glossaries} to
+\styfmt{glossaries-extra} is do just add
+\begin{verbatim}
+\setabbreviationstyle[acronym]{long-short}
+\end{verbatim}
+before you define any entries.
+For example, the following document using just \styfmt{glossaries}
+\begin{verbatim}
+\documentclass{article}
+\usepackage[acronym,nopostdot,toc]{glossaries}
+\makeglossaries
+\setacronymstyle{long-short}
+\newacronym{html}{HTML}{hypertext markup language}
+\begin{document}
+\gls{html}
+\printglossaries
+\end{document}
+\end{verbatim}
+can be easily adapted to use \styfmt{glossaries-extra}:
+\begin{verbatim}
+\documentclass{article}
+\usepackage[acronym]{glossaries-extra}
+\makeglossaries
+\setabbreviationstyle[acronym]{long-short}
+\newacronym{html}{HTML}{hypertext markup language}
+\begin{document}
+\gls{html}
+\printglossaries
+\end{document}
+\end{verbatim}
+Table~\ref{tab:acrabbrvstyles} lists the nearest equivalent
+\styfmt{glossaries-extra} abbreviation styles for
+the predefined acronym styles provided by \styfmt{glossaries}, but
+note that the new styles use different formatting commands. See
+\sectionref{sec:predefabbrvstyles} for further details.
+
+\begin{table}[htbp]
+\caption[Old Acronym Styles Verses New Abbreviation Styles]{Old Acronym Styles
+\cs{setacronymstyle}\marg{old-style-name} Verses New Abbreviation
+Styles \cs{setabbreviationstyle}\oarg{category}\marg{new-style-name}}
+\label{tab:acrabbrvstyles}
+\centering
+\begin{tabular}{@{}p{\dimexpr0.3\textwidth-2\tabcolsep}p{0.7\textwidth}@{}}
+\bfseries Old Style Name &
+\bfseries New Style Name\\
+\acrstyle{long-sc-short} & \abbrstyle{long-short-sc}\\
+\acrstyle{long-sm-short} & \abbrstyle{long-short-sm}\\
+\acrstyle{long-sp-short} & \abbrstyle{long-short} \newline with
+\ttfamily\cs{renewcommand}\{\cs{glsxtrfullsep}\}[1]\{\cs{glsacspace}\{\#1\}\}\\
+\acrstyle{short-long} & \abbrstyle{short-long}\\
+\acrstyle{sc-short-long} & \abbrstyle{short-sc-long}\\
+\acrstyle{sm-short-long} & \abbrstyle{short-sm-long}\\
+\acrstyle{long-short-desc} & \abbrstyle{long-short-desc}\\
+\acrstyle{long-sc-short-desc} & \abbrstyle{long-short-sc-desc}\\
+\acrstyle{long-sm-short-desc} & \abbrstyle{long-short-sm-desc}\\
+\acrstyle{long-sp-short-desc} & \abbrstyle{long-short-desc} \newline with
+\ttfamily\cs{renewcommand}\{\cs{glsxtrfullsep}\}[1]\{\cs{glsacspace}\{\#1\}\}\\
+\acrstyle{short-long-desc} & \abbrstyle{short-long-desc}\\
+\acrstyle{sc-short-long-desc} & \abbrstyle{short-sc-long-desc}\\
+\acrstyle{sm-short-long-desc} & \abbrstyle{short-sm-long-desc}\\
+\acrstyle{dua} & \abbrstyle{long-noshort}\\
+\acrstyle{dua-desc} & \abbrstyle{long-noshort-desc}\\
+\acrstyle{footnote} & \abbrstyle{short-footnote}\\
+\acrstyle{footnote-sc} & \abbrstyle{short-sc-footnote}\\
+\acrstyle{footnote-sm} & \abbrstyle{short-sm-footnote}\\
+\acrstyle{footnote-desc} & \abbrstyle{short-footnote-desc}\\
+\acrstyle{footnote-sc-desc} & \abbrstyle{short-sc-footnote-desc}\\
+\acrstyle{footnote-sm-desc} & \abbrstyle{short-sm-footnote-desc}
+\end{tabular}
+\end{table}
+
+The reason for introducing the new style of abbreviation commands
+provided by \styfmt{glossaries-extra} is because the original
+acronym commands provided by \styfmt{glossaries} are too restrictive
+to work with the internal modifications made by
+\styfmt{glossaries-extra}. However, if you really want to restore
+the generic acronym function provided
+by \styfmt{glossaries} you can use
\begin{definition}[\DescribeMacro\RestoreAcronyms]
\cs{RestoreAcronyms}
\end{definition}
-but be careful using this if you also want abbreviations as
-they will clash if you attempt to use them in the same glossary as
-generic acronyms from the \styfmt{glossaries} package.
+(before any use of \cs{newacronym}).
+
+\cs{RestoreAcronyms} should not be used in combination with the newer
+\styfmt{glossaries-extra} abbreviations. Don't combine old and
+new style entries with the same \gloskey{type}. The
+original \styfmt{glossaries} acronym mechanism doesn't work well
+with the newer \styfmt{glossaries-extra} commands.
+
+\begin{important}
+If you use \cs{RestoreAcronyms}, don't use any of the commands
+provided by \styfmt{glossaries-extra} intended for abbreviations
+(such as \ics{glsxtrshort} or \ics{glsfmtshort}) with entries
+defined via \ics{newacronym} as it will cause unexpected
+results.
+\end{important}
+
+In general, there's rarely any need for \cs{RestoreAcronyms}. If you
+have a document that uses \ics{newacronymstyle}, then it's best to
+either stick with just \styfmt{glossaries} for that document or
+define an equivalent abbreviation style with
+\ics{newabbreviationstyle}. (See \sectionref{sec:newabbrvstyle} for
+further details.)
\begin{definition}[\DescribeMacro\glsacspace]
\cs{glsacspace}\marg{label}
@@ -1291,6 +1548,13 @@ is modified so that it uses
instead of the hard-coded 3em. This is a command not a length
and so can be changed using \cs{renewcommand}.
+Any of the new abbreviation styles that use \ics{glsxtrfullsep}
+(such as \abbrstyle{long-short}) can easily be changed to use
+\cs{glsacspace} with
+\begin{verbatim}
+\renewcommand*{\glsxtrfullsep}[1]{\glsacspace{#1}}
+\end{verbatim}
+
The \gls{firstuse} acronym font command
\begin{definition}[\firstacronymfont]
\cs{firstacronymfont}\marg{text}
@@ -1683,16 +1947,14 @@ abbreviations or they may not be correctly applied.
The \ics{newacronym} command provided by the \styfmt{glossaries}
package is redefined by \styfmt{glossaries-extra} to use
\cs{newabbreviation} with the \gloskey{category} set to
-\texttt{acronym}. If you want to restore the original behaviour of
-acronyms (as implemented by the \styfmt{glossaries} package's
-\cs{newacronym}, \ics{setacronymstyle} and \ics{newacronymstyle})
-you need to use
-\begin{definition}[\DescribeMacro\RestoreAcronyms]
-\cs{RestoreAcronyms}
+\texttt{acronym} (see also \sectionref{sec:acronymmods}) so
+\begin{definition}[\DescribeMacro\newacronym]
+\cs{newacronym}\oarg{options}\marg{label}\marg{short}\marg{long}
\end{definition}
-However, if you do this take care not to mix acronyms with other
-types of entries within the same glossary. (You may also need to
-redefine \ics{acronymtype}.)
+is now equivalent to
+\begin{display}\raggedright\ttfamily
+\cs{newabbreviation}[type=\cs{acronymtype},category=acronym,\meta{options}]\marg{label}\marg{short}\marg{long}
+\end{display}
\begin{sloppypar}
The \cs{newabbreviation} command is superficially similar to the
@@ -1798,7 +2060,7 @@ This applies to all the predefined styles. For example:
\renewcommand*{\glsfirstlongdefaultfont}[1]{\emph{#1}}
\glsxtrinsertinsidetrue
\end{verbatim}
-This will make the long form and in the inserted text emphasized,
+This will make the long form and the inserted text emphasized,
whereas the default (without \cs{glsxtrinsertinsidetrue}) would
place the inserted text outside of the emphasized font.
@@ -1916,7 +2178,9 @@ Note that \ics{setacronymstyle} is disabled by
\cs{setabbreviationstyle}[acronym]\marg{style-name}
\end{alltt}
instead. The original acronym interface can be restored with
-\cs{RestoreAcronyms} (see \sectionref{sec:acronymmods}).
+\ics{RestoreAcronyms} (see \sectionref{sec:acronymmods}). However the
+original acronym interface is incompatible with all the commands
+described here.
Abbreviations can be used with the standard \styfmt{glossaries}
commands, such as \ics{gls}, but don't use the acronym commands
@@ -2664,6 +2928,39 @@ 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.
+As from version 1.05, all the footnote styles use:
+\begin{definition}[\DescribeMacro\glsfirstlongfootnotefont]
+\cs{glsfirstlongfootnotefont}\marg{text}
+\end{definition}
+to format the long form on \gls{firstuse} or for the full form and
+\begin{definition}[\DescribeMacro\glslongfootnotefont]
+\cs{glslongfootnotefont}\marg{text}
+\end{definition}
+to format the long form elsewhere (for example, when used with
+\cs{glsxtrlong}).
+
+As from version 1.07, all the footnote styles use:
+\begin{definition}[\DescribeMacro\glsxtrabbrvfootnote]
+\cs{glsxtrabbrvfootnote}\marg{label}\marg{long}
+\end{definition}
+By default, this just does \ics{footnote}\marg{long} (the first
+argument is ignored). For example, to make the footnote text
+link to the relevant place in the glossary:
+\begin{verbatim}
+\renewcommand{\glsxtrabbrvfootnote}[2]{%
+ \footnote{\glshyperlink[#2]{#1}}%
+}
+\end{verbatim}
+or to include the short form with a hyperlink:
+\begin{verbatim}
+\renewcommand{\glsxtrabbrvfootnote}[2]{%
+ \footnote{\glshyperlink[\glsfmtshort{#1}]{#1}: #2}%
+}
+\end{verbatim}
+Note that I haven't used commands like \cs{glsxtrshort} to
+avoid interference (see \sectionref{sec:entryfmtmods}
+and \sectionref{sec:nested}).
+
\item[\abbrstyle{footnote}] A synonym for
\abbrstyle{short-footnote}.
@@ -3265,7 +3562,9 @@ category label. (So take care if you have \sty{babel} shorthands on
that make some characters active.)
The use of categories can give you more control over the way entries
-are displayed in the text or glossary.
+are displayed in the text or glossary. Note that an entry's category
+is independent of the glossary type. Be careful not to confuse
+\gloskey{category} with \gloskey{type}.
The default category assumed by
\cs{newglossaryentry} is labelled \category{general}. Abbreviations
@@ -3320,7 +3619,18 @@ this will automatically suppress the hyperlink on \gls{firstuse} for entries wit
category that has this attribute set to \qt{true}.
(This settings can be overridden by explicitly setting
the \gloskey[glslink]{hyper} key on or off in the optional argument of
-commands like \cs{gls}.)
+commands like \cs{gls}.) As from version 1.07, \cs{glsfirst},
+\cs{Glsfirst}, \cs{GLSfirst} and their plural versions (which should ideally
+behave in a similar way to the \gls{firstuse} of \cs{gls} or
+\cs{glspl}) now honour
+this attribute (but not the package-wide \pkgopt[false]{hyperfirst}
+option, which matches the behaviour of \sty{glossaries}). If you
+want commands these \cs{glsfirst} etc commands to ignore the
+\catattr{nohyperfirst} attribute then just redefine
+\begin{definition}[\DescribeMacro\glsxtrchecknohyperfirst]
+\cs{glsxtrchecknohyperfirst}\marg{label}
+\end{definition}
+to do nothing.
\item[\catattr{nohyper}] When using commands like \ics{gls}
this will automatically suppress the hyperlink for entries with a
@@ -3428,12 +3738,32 @@ equal to the value of that attribute.
\item[\catattr{glossdesc}] The \ics{glossentrydesc} command
(used in the predefined glossary styles) is modified by
\styfmt{glossaries-extra} to check for this attribute.
-If the attribute is set to \qt{firstuc}, the first letter
-of the description will be converted to upper case (using
-\ics{Glsentrydesc}). If the attribute is set to \qt{title},
-the title casing command \ics{capitalisewords} (provided
-by \sty{mfirstuc}) is used on the name. Any other values of
-this attribute are ignored.
+The attribute may have one of the following values:
+\begin{itemize}
+\item \texttt{firstuc}: the first letter of the description will be
+converted to upper case (using \ics{Glsentrydesc}).
+
+\item \texttt{title}: the description will be used in the argument of the
+title casing command \ics{capitalisewords} (provided by
+\sty{mfirstuc}). If you want to use a different command
+you can redefine:
+\begin{definition}[\DescribeMacro\glsxtrfieldtitlecasecs]
+\cs{glsxtrfieldtitlecasecs}\marg{phrase cs}
+\end{definition}
+For example:
+\begin{verbatim}
+\newcommand*{\glsxtrfieldtitlecasecs}[1]{\xcapitalisefmtwords*{#1}}
+\end{verbatim}
+(Note that the argument to \cs{glsxtrfieldtitlecasecs}
+will be a control sequence whose replacement text is the
+entry's description, which is why \cs{xcapitalisefmtwords}
+is needed instead of \cs{capitalisefmtwords}.)
+
+\end{itemize}
+Any other values of this attribute are ignored. Remember
+that there are design limitations for both the first letter
+uppercasing and the title casing commands. See the \sty{mfirstuc}
+user manual for further details.
\item[\catattr{glossdescfont}] (New to version 1.04)
In addition to the above, the modified \ics{glossentrydesc}
@@ -3630,8 +3960,14 @@ for the \catattr{entrycount} attribute. This means that
you not only need to enable entry counting with
\ics{glsenableentrycount}, but you also need
to set the appropriate attribute (see \sectionref{sec:categories}).
+
+\begin{important}
Remember that entry counting only counts the number of times an
-entry is used by commands that change the \gls{firstuseflag}.
+entry is used by commands that change the \gls{firstuseflag}. (That
+is, all those commands that mark the entry as having been used.)
+There are many commands that don't modify this flag and they won't
+contribute to the entry use count.
+\end{important}
With \styfmt{glossaries-extra}, you may use \ics{cgls} instead of
\ics{gls} even if you haven't enabled entry counting. You will only
@@ -3664,8 +4000,6 @@ and
which convert the analogous \cs{cglsformat} and
\cs{cglsplformat} to upper case.
-%[TODO: work out what to do about \verb|\glsdisp|.]
-
Just using \styfmt{glossaries}:
\begin{verbatim}
\documentclass{article}