diff options
author | Karl Berry <karl@freefriends.org> | 2016-08-15 20:33:22 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2016-08-15 20:33:22 +0000 |
commit | 9f03d540e781cc9b40ca96a442b49c91d98d841e (patch) | |
tree | 8a9a1054005606820175b4275c8e939ecb431cf2 /Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex | |
parent | 1850016c7aa713d8e5b7e6ac583199a938407287 (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.tex | 396 |
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} |