diff options
author | Karl Berry <karl@freefriends.org> | 2016-05-02 22:49:50 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2016-05-02 22:49:50 +0000 |
commit | c970e86904ff1076f46506d6df9fa4a06a30ceab (patch) | |
tree | defbd547d713da8ed65c879b7f4cdaa18b71df1e /Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex | |
parent | 9d63d20b395741946482b9029e072ae7ebff21f0 (diff) |
glossaries-extra (2may16)
git-svn-id: svn://tug.org/texlive/trunk@40839 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 | 728 |
1 files changed, 628 insertions, 100 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 bf74f0c66f8..e82cc157a45 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 @@ -124,6 +124,8 @@ styles (glossaries):>#1={\protect\ttfamily#1}|main}} \newcommand*{\abbrstyle}[1]{\textsf{#1}\index{abbreviation styles:>#1={\protect\sffamily#1}|main}} +\newcommand*{\depabbrstyle}[1]{\textsf{#1}\index{abbreviation styles (deprecated):>#1={\protect\sffamily#1}|main}} + \newcommand*{\category}[1]{\textsf{#1}\index{categories:>#1={\protect\sffamily#1}|main}} \newcommand*{\catattr}[1]{\textsf{#1}\index{category attributes:>#1={\protect\sffamily#1}|main}} @@ -139,13 +141,13 @@ styles (glossaries):>#1={\protect\ttfamily#1}|main}} \MakeShortVerb{"} \DeleteShortVerb{\|} - \title{glossaries-extra.sty v1.03: + \title{glossaries-extra.sty v1.04: an extension to the glossaries package} \author{Nicola L.C. Talbot\\[10pt] Dickimaw Books\\ \url{http://www.dickimaw-books.com/}} - \date{2016-04-27} + \date{2016-05-02} \maketitle \begin{abstract} @@ -662,8 +664,9 @@ actually has a hyperlink. The actual text and the way it's displayed depends on the command used (such as \cs{gls}) and the entry format. The default entry format (\ics{glsentryfmt}) used in the -\gls{linktext} by commands like \cs{gls} (but not commands like -\cs{glstext}) is changed by \styfmt{glossaries-extra} to test for +\gls{linktext} by commands like \ics{gls}, \ics{glsxtrfull}, +\ics{glsxtrshort} and \ics{glsxtrlong} (but not commands like +\ics{glslink}, \ics{glsfirst} and \cs{glstext}) is changed by \styfmt{glossaries-extra} to test for regular entries, which are determined as follows: \begin{itemize} @@ -695,6 +698,52 @@ This means that entries with a short form can be treated as regular entries rather than abbreviations if it's more appropriate for the desired style. +As from version 1.04, \ics{glsentryfmt} now puts \ics{glsgenentry} +in the argument of the new command +\begin{definition}[\DescribeMacro\glsxtrregularfont] +\cs{glsxtrregularfont}\marg{text} +\end{definition} +This just does its argument \meta{text} by default. This means that +if you want regular entries in a different font but don't want +that font to apply to abbreviations, then you can redefine +\cs{glsxtrregularfont}. This is more precise than changing +\ics{glstextformat} which will be applied to all linking commands +for all entries. + +For example: +\begin{verbatim} +\renewcommand*{\glsxtrregularfont}[1]{\textsf{#1}} +\end{verbatim} +You can access the label through \cs{glslabel}. For example, +you can query the category: +\begin{verbatim} +\renewcommand*{\glsxtrregularfont}[1]{% + \glsifcategory{\glslabel}{general}{\textsf{#1}}{#1}} +\end{verbatim} +or query the category attribute: +\begin{verbatim} +\glssetcategoryattribute{general}{font}{sf} + +\renewcommand*{\glsxtrregularfont}[1]{% + \glsifattribute{\glslabel}{font}{sf}{\textsf{#1}}{#1}} +\end{verbatim} +or use the attribute to store the control sequence name: +\begin{verbatim} +\glssetcategoryattribute{general}{font}{textsf} +\glssetcategoryattribute{acronym}{font}{emph} + +\renewcommand*{\glsxtrregularfont}[1]{% + \glshasattribute{\glslabel}{font}% + {\csuse{\glsgetattribute{\glslabel}{font}}{#1}}% + {#1}% +} +\end{verbatim} +(Remember the category and attribute settings will only queried +here for \catattr{regular} entries, so if the abbreviation style +for the \category{acronym} category in the above example changes +the regular attribute to \qt{false}, \cs{glsxtrregularfont} will +no longer apply.) + The \cs{glspostlinkhook} provided by the \sty{glossaries} package to insert information after the \gls{linktext} produced by commands like \cs{gls} and \cs{glstext} is redefined to @@ -771,7 +820,7 @@ 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} +However, the \abbrstyle{short-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} @@ -784,7 +833,7 @@ after the \gls{linktext} on \gls{firstuse} for the \category{general} category: } \end{verbatim} -The \abbrstyle{postfootnote} abbreviation style uses the +The \abbrstyle{short-postfootnote} abbreviation style uses the post-\gls{linktext} hook to place the footnote after trailing punctuation characters. @@ -1059,7 +1108,7 @@ 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 (such as -\abbrstyle{long-desc}). +\abbrstyle{long-noshort-desc}). Additionally, any instance of the long form commands, such as \ics{glsxtrlong} or \ics{acrlong} will be temporarily @@ -1164,8 +1213,8 @@ the preamble). This should take into account situations where \cs{hsize} isn't set until the start of the document. The commands \ics{glossentryname} and \ics{glossentrydesc} are -modified to take into account the \catattr{glossname} and -\catattr{glossdesc} attributes (see \sectionref{sec:categories}). +modified to take into account the \catattr{glossname}, +\catattr{glossdesc} and \catattr{glossdescfont} attributes (see \sectionref{sec:categories}). This means you can make simple case-changing modifications to the name and description without defining a new glossary style. @@ -1182,6 +1231,18 @@ then the name is automatically indexed using \end{definition} See \sectionref{sec:autoindex} for further details. +As from version 1.04, the post-name hook \cs{glsxtrpostnamehook} +will also do \cs{glsxtrpostname}\meta{category} if it exists. +You can use \ics{glscurrententrylabel} to obtain the entry label +with the definition of this command. For example, suppose you are +using a glossary style the doesn't display the symbol, you can +insert the symbol after the name for a particular category, say, +the \qt{symbol} category: +\begin{verbatim} +\newcommand*{\glsxtrpostnamesymbol}{\space + (\glsentrysymbol{\glscurrententrylabel})} +\end{verbatim} + The post-description code used within the glossary is modified so that it also does \begin{definition}[\DescribeMacro\glsxtrpostdescription] @@ -1275,6 +1336,48 @@ that the modified \glostyle{inline} style isn't affected by the \pkgopt{nopostdot} option, but the post-description category hook can still be used. +The \gls{numberlist} is now placed inside the argument of +\begin{definition}[\DescribeMacro\GlsXtrFormatLocationList] +\cs{GlsXtrFormatLocationList}\marg{number list} +\end{definition} +This is internally used by \cs{glossaryentrynumbers}. The +\pkgopt{nonumberlist} redefines \cs{glossaryentrynumbers} so that it +doesn't display the \gls{numberlist}, but it still saves the +\gls{numberlist} in case it's required. + +\begin{important} +If you want to suppress the \gls{numberlist} always use the +\pkgopt{nonumberlist} option instead of redefining +\cs{glossaryentrynumbers} to do nothing. +\end{important} + +If you want to, for example, change the font for the entire +\gls{numberlist} then redefine \cs{GlsXtrFormatLocationList} as +appropriate. Don't modify \cs{glossaryentrynumbers}. + +Sometimes users like to insert \qt{page} or \qt{pages} in front of +the \gls{numberlist}. This is quite fiddly to do with the base +\styfmt{glossaries} package, but \styfmt{glossaries-extra} +provides a way of doing this. First you need to enable this +option and specify the text to display using: +\begin{definition}[\DescribeMacro\GlsXtrEnablePreLocationTag] +\cs{GlsXtrEnablePreLocationTag}\marg{page}\marg{pages} +\end{definition} +where \meta{page} is the text to display if the \gls{numberlist} only +contains a single location and \meta{pages} is the text to display +otherwise. For example: +\begin{verbatim} +\GlsXtrEnablePreLocationTag{Page: }{Pages: } +\end{verbatim} +An extra run is required when using this command. + +\begin{important} +Use \texttt{glsignore} not \texttt{@gobble} as the format if you +want to suppress the page number (and only index the entry once). +\end{important} + +See the accompanying sample file \texttt{sample-pages.tex}. + \chapter{Abbreviations} \label{sec:abbreviations} @@ -1332,7 +1435,7 @@ redefine \ics{acronymtype}.) The \cs{newabbreviation} command is superficially similar to the \sty{glossaries} package's \cs{newacronym} but you can apply different styles to different categories. The default style is -\abbrstyle{short} for entries in the \category{acronym} category and +\abbrstyle{short-nolong} for entries in the \category{acronym} category and \abbrstyle{short-long} for entries in the \category{abbreviation} category. (These aren't the same as the acronym styles provided by the \sty{glossaries} package, although they may produce similar @@ -1368,32 +1471,57 @@ use one of the base styles, such as \abbrstyle{long-short}, or define a new style in a similar manner to the \qt{sc}, \qt{sm} or \qt{em} styles. -All predefined abbreviation styles redefine \cs{glsfirstabbrvfont} +Similarly the basic styles redefine \cs{glsfirstabbrvfont} to use \begin{definition}[\DescribeMacro\glsfirstabbrvdefaultfont] \cs{glsfirstabbrvdefaultfont}\marg{short-form} \end{definition} -By default, this just does \cs{glsabbrvfont}\marg{short-form} -so the \gls{firstuse} format matches the subsequence use format -for the short form. +whereas the font modifier styles, such as \abbrstyle{long-short=sc}, +use their own custom command, such as \cs{glsfirstscfont}. + The commands that display the full form for abbreviations use \cs{glsfirstabbrvfont} to display the short form and \begin{definition}[\DescribeMacro\glsfirstlongfont] \cs{glsfirstlongfont}\marg{long-form} \end{definition} -to display the long form. As with \ics{glsabbrvfont}, this command +to display the long form on \gls{firstuse} or for the inline full +format. Commands like \cs{glsxtrlong} use +\begin{definition}[\DescribeMacro\glslongfont] +\cs{glslongfont}\marg{long-form} +\end{definition} +instead. + +As with \ics{glsabbrvfont}, this command is changed by all styles. Currently all predefined abbreviation -styles provided by \styfmt{glossaries-extra} redefine +styles, except the \qt{long-em} (emphasize long form) versions, provided by +\styfmt{glossaries-extra} redefine \cs{glsfirstlongfont} to use \begin{definition}[\DescribeMacro\glsfirstlongdefaultfont] \cs{glsfirstlongdefaultfont}\marg{long-form} \end{definition} -You can redefine this command if you want to change the font used by -the long form on \gls{firstuse} for all your abbreviations, or you can +and \cs{glslongfont} to use +\begin{definition}[\DescribeMacro\glslongdefaultfont] +\cs{glslongdefaultfont}\marg{long-form} +\end{definition} + +You can redefine these command if you want to change the font used by +the long form for all your abbreviations (except for the +emphasize-long styles), or you can define your own abbreviation style that provides a different format for only those abbreviations defined with that style. +The \qt{long-em} (emphasize long) styles use +\begin{definition}[\DescribeMacro\glsfirstlongemfont] +\cs{glsfirstlongemfont}\marg{long-form} +\end{definition} +instead of \cs{glsfirstlongdefaultfont}\marg{long-form} and +\begin{definition}[\DescribeMacro\glslongemfont] +\cs{glslongemfont}\marg{long-form} +\end{definition} +instead of \cs{glslongdefaultfont}\marg{long-form}. The first form +\cs{glsfirstlongemfont} is initialised to use \cs{glslongemfont}. + 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: @@ -1418,8 +1546,8 @@ 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}. For some of the abbreviation styles, such as \abbrstyle{long-short}, the display and inline forms -are the same. In the case of styles such as \abbrstyle{short} or -\abbrstyle{footnote}, the display and inline full forms are different. +are the same. In the case of styles such as \abbrstyle{short-nolong} or +\abbrstyle{short-footnote}, the display and inline full forms are different. These formatting commands aren't stored in the \gloskey{short}, \gloskey{shortplural}, \gloskey{long} or \gloskey{longplural} @@ -1509,7 +1637,7 @@ given category. If there is no style set for the category, the fallback is the style for the \texttt{abbreviation} category. Some styles may automatically modify one or more of the attributes associated with the given category. For example, the -\abbrstyle{long} and \abbrstyle{short} styles set the +\abbrstyle{long-noshort} and \abbrstyle{short-nolong} styles set the \catattr{regular} attribute to \texttt{true}. \begin{important} @@ -1548,7 +1676,8 @@ The \emph{inline} full form can be produced with (This this instead of \ics{acrfull}.) As mentioned earlier, the inline full form may not necessarily match the format used on -\gls{firstuse} with \cs{gls}. For example, the \abbrstyle{short} style +\gls{firstuse} with \cs{gls}. For example, the +\abbrstyle{short-nolong} style only displays the short form on \gls{firstuse}, but the full form will display the long form followed by the short form in parentheses. @@ -1719,6 +1848,14 @@ which is defined as \begin{verbatim} \newcommand*{\glsxtrscfont}[1]{\textsc{#1}} \end{verbatim} +and +\begin{definition}[\DescribeMacro\glsxtrfirstscfont] +\cs{glsxtrfirstscfont}\marg{text} +\end{definition} +which is defined as +\begin{verbatim} +\newcommand*{\glsxtrfirstscfont}[1]{\glsxtrscfont{#1}} +\end{verbatim} The default plural suffix for the short form is set to \begin{definition}[\DescribeMacro\glsxtrscsuffix] \cs{glsxtrscsuffix} @@ -1737,6 +1874,15 @@ through the use of the \catattr{aposplural} and \catattr{noshortplural} attributes. See \sectionref{sec:categories} for further details.) +Remember that \cs{textsc} renders \emph{lowercase} letters as small +capitals. Uppercase letters are rendered as normal uppercase +letters, so if you specify the short form in uppercase, you won't +get small capitals unless you redefine \cs{glsxtrscfont} to +convert its argument to lowercase. For example: +\begin{verbatim} +\renewcommand*{\glsxtrscfont}[1]{\textsc{\MakeLowercase{#1}}} +\end{verbatim} + The \qt{sm} styles all use \begin{definition}[\DescribeMacro\glsxtrsmfont] \cs{glsxtrsmfont}\marg{text} @@ -1745,7 +1891,15 @@ This is defined as: \begin{verbatim} \newcommand*{\glsxtrsmfont}[1]{\textsmaller{#1}} \end{verbatim} -If you want to use this, you must explicitly load the \sty{relsize} +and +\begin{definition}[\DescribeMacro\glsxtrfirstsmfont] +\cs{glsxtrfirstsmfont}\marg{text} +\end{definition} +which is defined as +\begin{verbatim} +\newcommand*{\glsxtrfirstsmfont}[1]{\glsxtrsmfont{#1}} +\end{verbatim} +If you want to use this style, you must explicitly load the \sty{relsize} package which defines the \ics{textsmaller} command. If you want to easily switch between the \qt{sc} and \qt{sm} styles, you may find it easier to redefine this command to convert to upper case: @@ -1758,9 +1912,22 @@ The default plural suffix for the short form is set to \end{definition} This just does \ics{glspluralsuffix}. -The \qt{em} styles all redefine \ics{glsabbrvfont} to use -\ics{emph}. This is done explicitly and not through a helper -command such as \cs{glsxtrscfont}. +The \qt{em} styles all use +\begin{definition}[\DescribeMacro\glsabbrvemfont] +\cs{glsabbrvemfont}\marg{text} +\end{definition} +which is defined as: +\begin{verbatim} +\newcommand*{\glsabbrvemfont}[1]{\emph{#1}} +\end{verbatim} +and +\begin{definition}[\DescribeMacro\glsfirstabbrvemfont] +\cs{glsfirstabbrvemfont}\marg{text} +\end{definition} +which is defined as: +\begin{verbatim} +\newcommand*{\glsfirstabbrvemfont}[1]{\glsabbrvemfont{#1}} +\end{verbatim} Some of the styles use \begin{definition}[\DescribeMacro\glsxtrfullsep] @@ -1776,6 +1943,91 @@ or \renewcommand*{\glsxtrfullsep}[1]{\glsacspace{#1}} \end{verbatim} +The new naming scheme for abbreviation styles is as follows: +\begin{itemize} +\item +\meta{field1}[\texttt{-}\meta{modifier1}]\texttt{-}\meta{field2}[\texttt{-}\meta{modifier2}][\texttt{-user}] + +This is for the parenthetical styles. The \texttt{-}\meta{modifier} parts may +be omitted. These styles display \meta{field1} followed by +\meta{field2} in parentheses. If \meta{field2} starts with \qt{no} +then the parenthetical element is omitted from the display style but +is included in the inline style. + +If the \texttt{-}\meta{modifier} part is present, then the field has +a font changing command applied to it. + +If the \texttt{-user} part is present, then the \gloskey{user1} +value, if provided, is inserted into the parenthetical material . +(The field used for the inserted material may be changed.) + +Examples: + \begin{itemize} + \item\abbrstyle{long-noshort-sc}: \meta{field1} is the long +form, the short form is set in smallcaps but omitted in the display +style. + \item\abbrstyle{long-em-short-em}: both the long form and the +short form are emphasized. The short form is in parentheses. + \item\abbrstyle{long-short-em}: the +short form is emphasized but not the long form. The short form is in parentheses. + \item\abbrstyle{long-short-user}: if the \gloskey{user1} key has +been set, this produces the style \meta{long} (\meta{short}, +\meta{user1}) otherwise it just produces \meta{long} (\meta{short}). + \end{itemize} + +\item +\meta{field1}[\texttt{-}\meta{modifier1}]\texttt{-}[\texttt{post}]\texttt{footnote} + +The display style uses \meta{field1} followed by a footnote with the +other field in it. If \texttt{post} is present then the footnote is +placed after the \gls{linktext} using the post-link hook. +The inline style does \meta{field1} followed by the other field in +parentheses. + +If \texttt{-}\meta{modifier1} is present, \meta{field1} has a +font-changing command applied to it. + +Examples: +\begin{itemize} +\item \abbrstyle{short-footnote}: short form in the text with the +long form in the footnote. +\item \abbrstyle{short-sc-postfootnote}: short form in smallcaps +with the long form in the footnote outside of the \gls{linktext}. +\end{itemize} + +\begin{important} +Take care with the footnote styles. Remember that there are some +situations where \ics{footnote} doesn't work. +\end{important} + +\item \meta{style}\texttt{-desc} + +Like \meta{style} but the \gloskey{description} key must be provided +when defining abbreviations with this style. + +Examples: +\begin{itemize} + +\item \abbrstyle{short-long-desc}: like \abbrstyle{short-long} but +requires a description. +\item \abbrstyle{short-em-footnote-desc}: like +\abbrstyle{short-em-footnote} but requires a description. +\end{itemize} +\end{itemize} + +Not all combinations that fit the above syntax are provided. +Pre-version 1.04 styles that didn't fit this naming scheme are either +provided with a synonym (where the former name wasn't ambiguous) or +provided with a deprecated synonym (where the former name was +confusing). +The deprecated style names generate a warning using: +\begin{definition}[\DescribeMacro\GlsXtrWarnDeprecatedAbbrStyle] +\cs{GlsXtrWarnDeprecatedAbbrStyle}\marg{old-name}\marg{new-name} +\end{definition} +where \meta{old-name} is the deprecated name and \meta{new-name} is +the preferred name. You can suppress these warnings by redefining +this command to do nothing. + \subsection{Predefined Abbreviation Styles that Set the Regular Attribute} \label{sec:predefregabbrvstyles} @@ -1785,88 +2037,144 @@ attribute to \qt{true} for all categories that have abbreviations defined with any of these styles. \begin{description} -\item[\abbrstyle{short}] +\item[\abbrstyle{short-nolong}] This only displays the short form on \gls{firstuse}. The \gloskey{name} is set to the short form. The \gloskey{description} is set to the long form. The inline full form displays \meta{short} (\meta{long}). The long form on its own can be displayed through commands like \ics{glsxtrlong}. -\item[\abbrstyle{short-sc}] -Like \abbrstyle{short} but redefines \cs{glsabbrvfont} to +\item[\abbrstyle{short}] A synonym for \abbrstyle{short-nolong}. + +\item[\abbrstyle{short-sc-nolong}] +Like \abbrstyle{short-nolong} but redefines \cs{glsabbrvfont} to use \ics{glsxtrscfont}. -\item[\abbrstyle{short-sm}] -Like \abbrstyle{short} but redefines \cs{glsabbrvfont} to +\item[\abbrstyle{short-sc}] A synonym for \abbrstyle{short-sc-nolong} + +\item[\abbrstyle{short-sm-nolong}] +Like \abbrstyle{short-nolong} but redefines \cs{glsabbrvfont} to use \ics{glsxtrsmfont}. -\item[\abbrstyle{short-em}] -Like \abbrstyle{short} but redefines \cs{glsabbrvfont} to -use \ics{emph}. +\item[\abbrstyle{short-sm}] A synonym for \abbrstyle{short-sm-nolong}. + +\item[\abbrstyle{short-em-nolong}] +Like \abbrstyle{short-nolong} but redefines \cs{glsabbrvfont} to +use \ics{glsxtremfont}. -\item[\abbrstyle{short-desc}] -Like the \abbrstyle{short} style, but the \gloskey{name} is set to +\item[\abbrstyle{short-em}] A synonym for \abbrstyle{short-em-nolong} + +\item[\abbrstyle{short-nolong-desc}] +Like the \abbrstyle{short-nolong} style, but the \gloskey{name} is set to the full form and the \gloskey{description} must be supplied by the -user. You may prefer to use the \abbrstyle{short} style with the +user. You may prefer to use the \abbrstyle{short-nolong} style with the post-description hook set to display the long form and override the \gloskey{description} key. (See the sample file \texttt{sample-acronym-desc.tex}.) -\item[\abbrstyle{short-sc-desc}] -Like \abbrstyle{short} but redefines \cs{glsabbrvfont} to +\item[\abbrstyle{short-desc}] A synonym for +\abbrstyle{short-nolong-desc}. + +\item[\abbrstyle{short-sc-nolong-desc}] +Like \abbrstyle{short-nolong} but redefines \cs{glsabbrvfont} to use \ics{glsxtrscfont}. -\item[\abbrstyle{short-sm-desc}] -Like \abbrstyle{short-desc} but redefines \cs{glsabbrvfont} to +\item[\abbrstyle{short-sc-desc}] A synonym for +\abbrstyle{short-sc-nolong-desc}. + +\item[\abbrstyle{short-sm-nolong-desc}] +Like \abbrstyle{short-nolong-desc} but redefines \cs{glsabbrvfont} to use \ics{glsxtrsmfont}. -\item[\abbrstyle{short-em-desc}] -Like \abbrstyle{short-desc} but redefines \cs{glsabbrvfont} to -use \ics{emph}. +\item[\abbrstyle{short-sm-desc}] A synonym for +\abbrstyle{short-sm-nolong-desc}. + +\item[\abbrstyle{short-em-nolong-desc}] +Like \abbrstyle{short-nolong-desc} but redefines \cs{glsabbrvfont} to +use \ics{glsxtremfont}. + +\item[\abbrstyle{short-em-desc}] A synonym for +\abbrstyle{short-em-nolong-desc}. -\item[\abbrstyle{long-desc}] +\item[\abbrstyle{long-noshort-desc}] This style only displays the long form, regardless of first or subsequent use of commands \ics{gls}. The short form may be accessed through commands like \ics{glsxtrshort}. The inline full form displays \meta{long} (\meta{short}). -The \gloskey{name} is set to the long form and the +The \gloskey{name} and \gloskey{sort} keys are set to the long form and the \gloskey{description} must be provided by the user. The predefined glossary styles won't display the short form. You can use the post-description hook to automatically append the short form to the description. The inline full form will display \meta{long} (\meta{short}). -\item[\abbrstyle{long-desc-sc}] -Like the \abbrstyle{long-desc} style but the short form (accessed +\item[\abbrstyle{long-desc}] A synonym for +\abbrstyle{long-noshort-desc}. + +\item[\abbrstyle{long-noshort-sc-desc}] +Like the \abbrstyle{long-noshort-desc} style but the short form (accessed through commands like \ics{glsxtrshort}) use \ics{glsxtrscfont}. +(This style was originally called \depabbrstyle{long-desc-sc}. Renamed in version +1.04, but original name retained as a deprecated synonym for +backward-compatibility.) -\item[\abbrstyle{long-desc-sm}] -Like \abbrstyle{long-desc} but redefines \cs{glsabbrvfont} to +\item[\abbrstyle{long-noshort-sm-desc}] +Like \abbrstyle{long-noshort-desc} but redefines \cs{glsabbrvfont} to use \ics{glsxtrsmfont}. - -\item[\abbrstyle{long-desc-em}] -Like \abbrstyle{long-desc} but redefines \cs{glsabbrvfont} to -use \ics{emph}. - -\item[\abbrstyle{long}] +(This style was originally called \depabbrstyle{long-desc-sm}. Renamed in version +1.04, but original name retained as a deprecated synonym for +backward-compatibility.) + +\item[\abbrstyle{long-noshort-em-desc}] +Like \abbrstyle{long-noshort-desc} but redefines \cs{glsabbrvfont} to +use \ics{glsxtremfont}. The long form isn't emphasized. +(This style was originally called \depabbrstyle{long-desc-em}. Renamed in version +1.04, but original name retained as a deprecated synonym for +backward-compatibility.) + +\item[\abbrstyle{long-em-noshort-em-desc}] +New to version 1.04, like \abbrstyle{long-noshort-desc} but redefines +\cs{glsabbrvfont} to use \ics{glsxtremfont}. The long form uses +\ics{glsfirstlongemfont} and \ics{glslongemfont}. + +\item[\abbrstyle{long-noshort}] This style doesn't really make sense if you don't use the short form anywhere in the document, but is provided for completeness. -This is like the \abbrstyle{long-desc} style, but the \gloskey{name} -is set to the short form and the \gloskey{description} is set to the +This is like the \abbrstyle{long-noshort-desc} style, but the \gloskey{name} +and \gloskey{sort} keys are +set to the short form and the \gloskey{description} is set to the long form. -\item[\abbrstyle{long-sc}] -Like the \abbrstyle{long} style but the short form (accessed +\item[\abbrstyle{long}] A synonym for \abbrstyle{long-noshort} + +\item[\abbrstyle{long-noshort-sc}] +Like the \abbrstyle{long-noshort} style but the short form (accessed through commands like \ics{glsxtrshort}) use \ics{glsxtrscfont}. +(This style was originally called \depabbrstyle{long-sc}. Renamed in version +1.04, but original name retained as a deprecated synonym for +backward-compatibility.) -\item[\abbrstyle{long-sm}] -Like \abbrstyle{long} but redefines \cs{glsabbrvfont} to +\item[\abbrstyle{long-noshort-sm}] +Like \abbrstyle{long-noshort} but redefines \cs{glsabbrvfont} to use \ics{glsxtrsmfont}. - -\item[\abbrstyle{long-em}] -Like \abbrstyle{long} but redefines \cs{glsabbrvfont} to -use \ics{emph}. +(This style was originally called \depabbrstyle{long-sm}. Renamed in version +1.04, but original name retained as a deprecated synonym for +backward-compatibility.) + +\item[\abbrstyle{long-noshort-em}] +This style is like \abbrstyle{long-noshort} but redefines \cs{glsabbrvfont} to +use \ics{glsxtremfont}. The long form isn't emphasized. +(This style was originally called \depabbrstyle{long-em}. Renamed in version +1.04, but original name retained as a deprecated synonym for +backward-compatibility.) + +\item[\abbrstyle{long-em-noshort-em}] +New to version 1.04, this style is like \abbrstyle{long-noshort} but redefines \cs{glsabbrvfont} to +use \ics{glsxtremfont}, \cs{glsfirstlongfont} to use +\cs{glsfirstlongemfont} and \cs{glslongfont} to use +\cs{glslongemfont}. The short form isn't used by commands like +\ics{gls}, but can be obtained using \ics{glsxtrshort}. \end{description} @@ -1883,9 +2191,13 @@ Other attributes may also be set, depending on the style. \item[\abbrstyle{long-short}] On \gls{firstuse}, this style uses the format \meta{long} (\meta{short}). The inline and display full forms are the same. The \gloskey{name} -is set to the short form. The +and \gloskey{sort} keys are set to the short form. (The +\gloskey{name} key additionally includes the font command +\cs{glsabbrvfont}.) The \gloskey{description} is set to the long form. The long and short -forms are separated by \cs{glsxtrfullsep}. +forms are separated by \cs{glsxtrfullsep}. If you want to insert +material within the parentheses (such as a~translation), try the +\abbrstyle{long-short-user} style. \item[\abbrstyle{long-short-sc}] Like \abbrstyle{long-short} but redefines \cs{glsabbrvfont} to @@ -1897,13 +2209,92 @@ use \ics{glsxtrsmfont}. \item[\abbrstyle{long-short-em}] Like \abbrstyle{long-short} but redefines \cs{glsabbrvfont} to -use \ics{emph}. +use \ics{glsxtremfont}. + +\item[\abbrstyle{long-em-short-em}] +New to version 1.04, this style is like \abbrstyle{long-short-em} but redefines \cs{glsfirstlongfont} to +use \ics{glsfirstlongemfont}. + +\item[\abbrstyle{long-short-user}] +This style was introduced in version 1.04. It's like the +\abbrstyle{long-short} style but additional information can be +inserted into the parenthetical material. This checks the value +of the field given by +\begin{definition}[DescribeMacro\glsxtruserfield] +\cs{glsxtruserfield} +\end{definition} +(which defaults to \texttt{useri}) using \ics{ifglshasfield} +(provided by \sty{glossaries}). If the field hasn't been set, +the style behaves like the \abbrstyle{long-short} style and +produces \meta{long} (\meta{short}) but if the field has been set, +the contents of that field are inserted within the parentheses in +the form \meta{long} (\meta{short}, \meta{field-value}). +The format is governed by +\begin{definition}[\DescribeMacro\glsxtruserparen] +\cs{glsxtruserparen}\marg{text}\marg{label} +\end{definition} +where \meta{text} is the short form (for the +\abbrstyle{long-short-user} style) or the long form (for the +\abbrstyle{short-long-user} style). This command first inserts +a space using \cs{glsxtrfullsep} and then the parenthetical content. +The \meta{text} argument includes the font formatting command, +\cs{glsfirstabbrvfont}\marg{short} in the case of the +\abbrstyle{long-short-user} style and +\cs{glsfirstlongfont}\marg{long} in the +case of the \abbrstyle{short-long-user} style. + +For example: +\begin{verbatim} +\setabbreviationstyle[acronym]{long-short-user} + +\newacronym{tug}{TUG}{\TeX\ User Group} + +\newacronym + [user1={German Speaking \TeX\ User Group}] + {dante}{DANTE}{Deutschsprachige Anwendervereinigung \TeX\ e.V} + +\end{verbatim} +On first use, \verb|\gls{tug}| will appear as: +\begin{quote} +\TeX\ User Group (TUG) +\end{quote} +whereas \verb|\gls{dante}| will appear as: +\begin{quote} +Deutschsprachige Anwendervereinigung \TeX\ e.V (DANTE, German Speaking \TeX\ User Group) +\end{quote} + +The short form is formatted according to +\begin{definition}[\DescribeMacro\glsabbrvuserfont] +\cs{glsabbrvuserfont}\marg{text} +\end{definition} +and the plural suffix is given by +\begin{definition}[\DescribeMacro\glsxtrusersuffix] +\cs{glsxtrusersuffix} +\end{definition} + +These may be redefined as appropriate. For example, +if you want a~smallcaps style, you can just set these commands +to those used by the \abbrstyle{long-short-sc} style: +\begin{verbatim} +\renewcommand{\glsabbruserfont}[1]{\glsxtrscfont{#1}} +\renewcommand{\glsxtrusersuffix}{\glsxtrscsuffix} +\end{verbatim} \item[\abbrstyle{long-short-desc}] On \gls{firstuse}, this style uses the format \meta{long} (\meta{short}). The inline and display full forms are the same. The \gloskey{name} -is set to the full form. The -\gloskey{description} must be supplied by the user. +is set to the full form. The \gloskey{sort} key is set to +\meta{long} (\meta{short}). Before version 1.04, this was +incorrectly set to the short form. If you want to revert back to +this you can redefine +\begin{definition}[\DescribeMacro\glsxtrlongshortdescsort] +\cs{glsxtrlongshortdescsort} +\end{definition} +For example: +\begin{verbatim} +\renewcommand*{\glsxtrlongshortdescsort}{\the\glsshorttok} +\end{verbatim} +The \gloskey{description} must be supplied by the user. The long and short forms are separated by \cs{glsxtrfullsep}. \item[\abbrstyle{long-short-sc-desc}] @@ -1916,14 +2307,32 @@ use \ics{glsxtrsmfont}. \item[\abbrstyle{long-short-em-desc}] Like \abbrstyle{long-short-desc} but redefines \cs{glsabbrvfont} to -use \ics{emph}. +use \ics{glsxtremfont}. + +\item[\abbrstyle{long-em-short-em-desc}] +New to version 1.04, this style is like \abbrstyle{long-short-em-desc} but redefines \cs{glsfirstlongfont} to +use \ics{glsfirstlongemfont}. + + +\item[\abbrstyle{long-short-user-desc}] +New to version 1.04, this style is like a~cross between the +\abbrstyle{long-short-desc} style and the +\abbrstyle{long-short-user} style. The display and inline forms are +as for \abbrstyle{long-short-user} and the \gloskey{name} key is as +\abbrstyle{long-short-desc}. The \gloskey{description} key must be +supplied in the optional argument of \cs{newabbreviation} +(or \cs{newacronym}). The \gloskey{sort} key is set to \meta{long} +(\meta{short}) as per the \abbrstyle{long-short-desc} style. \item[\abbrstyle{short-long}] On \gls{firstuse}, this style uses the format \meta{short} (\meta{long}). The inline and display full forms are the same. The \gloskey{name} -is set to the short form. The +and \gloskey{sort} keys are set to the short form. The \gloskey{description} is set to the long form. The short and long forms are separated by \cs{glsxtrfullsep}. +If you want to insert +material within the parentheses (such as a~translation), try the +\abbrstyle{short-long-user} style. \item[\abbrstyle{short-sc-long}] Like \abbrstyle{short-long} but redefines \cs{glsabbrvfont} to @@ -1935,7 +2344,18 @@ use \ics{glsxtrsmfont}. \item[\abbrstyle{short-em-long}] Like \abbrstyle{short-long} but redefines \cs{glsabbrvfont} to -use \ics{emph}. +use \ics{glsxtremfont}. + +\item[\abbrstyle{short-em-long-em}] +New to version 1.04, this style is like \abbrstyle{short-em-long} but redefines \cs{glsfirstlongfont} to +use \ics{glsfirstlongemfont}. + +\item[\abbrstyle{short-long-user}] +New to version 1.04. This style is like the +\abbrstyle{long-short-user} style but with the long and short forms +switched. The parenthetical material is governed by the same command +\ics{glsxtruserparen}, but the first argument supplied to it is +the long form instead of the short form. \item[\abbrstyle{short-long-desc}] On \gls{firstuse}, this style uses the format \meta{short} (\meta{long}). @@ -1954,9 +2374,22 @@ use \ics{glsxtrsmfont}. \item[\abbrstyle{short-em-long-desc}] Like \abbrstyle{short-long-desc} but redefines \cs{glsabbrvfont} to -use \ics{emph}. - -\item[\abbrstyle{footnote}] +use \ics{glsxtremfont}. + +\item[\abbrstyle{short-em-long-em-desc}] +New to version 1.04, this style is like \abbrstyle{short-em-long-desc} but redefines \cs{glsfirstlongfont} to +use \ics{glsfirstlongemfont}. + +\item[\abbrstyle{short-long-user-desc}] +New to version 1.04, this style is like a~cross between the +\abbrstyle{short-long-desc} style and the +\abbrstyle{short-long-user} style. The display and inline forms are +as for \abbrstyle{short-long-user} and the \gloskey{name} key is as +\abbrstyle{short-long-desc}. The \gloskey{description} key must be +supplied in the optional argument of \cs{newabbreviation} +(or \cs{newacronym}). + +\item[\abbrstyle{short-footnote}] On \gls{firstuse}, this style displays the short form with the long form as a footnote. This style automatically sets the \catattr{nohyperfirst} attribute to \qt{true} for the supplied @@ -1967,20 +2400,32 @@ 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. -\item[\abbrstyle{footnote-sc}] -Like \abbrstyle{footnote} but redefines \cs{glsabbrvfont} to +\item[\abbrstyle{footnote}] A synonym for +\abbrstyle{short-footnote}. + +\item[\abbrstyle{short-sc-footnote}] +Like \abbrstyle{short-footnote} but redefines \cs{glsabbrvfont} to use \ics{glsxtrscfont}. +(This style was originally called \depabbrstyle{footnote-sc}. Renamed in version +1.04, but original name retained as a deprecated synonym for +backward-compatibility.) -\item[\abbrstyle{footnote-sm}] -Like \abbrstyle{footnote} but redefines \cs{glsabbrvfont} to +\item[\abbrstyle{short-sc-footnote}] +Like \abbrstyle{short-footnote} but redefines \cs{glsabbrvfont} to use \ics{glsxtrsmfont}. - -\item[\abbrstyle{footnote-em}] -Like \abbrstyle{footnote} but redefines \cs{glsabbrvfont} to -use \ics{emph}. - -\item[\abbrstyle{postfootnote}] -This is similar to the \abbrstyle{footnote} style but doesn't modify +(This style was originally called \depabbrstyle{footnote-sm}. Renamed in version +1.04, but original name retained as a deprecated synonym for +backward-compatibility.) + +\item[\abbrstyle{short-em-footnote}] +Like \abbrstyle{short-footnote} but redefines \cs{glsabbrvfont} to +use \ics{glsxtremfont}. +(This style was originally called \depabbrstyle{footnote-em}. Renamed in version +1.04, but original name retained as a deprecated synonym for +backward-compatibility.) + +\item[\abbrstyle{short-postfootnote}] +This is similar to the \abbrstyle{short-footnote} style but doesn't modify the category attribute. Instead it changes \postlinkcat\ to insert the footnote after the \gls{linktext} on \gls{firstuse}. This will also defer the footnote until after any @@ -1994,17 +2439,29 @@ 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 +\item[\abbrstyle{postfootnote}] A synonym for +\abbrstyle{short-postfootnote}. + +\item[\abbrstyle{short-sc-postfootnote}] +Like \abbrstyle{short-postfootnote} but redefines \cs{glsabbrvfont} to use \ics{glsxtrscfont}. +(This style was originally called \depabbrstyle{postfootnote-sc}. Renamed in version +1.04, but original name retained as a deprecated synonym for +backward-compatibility.) -\item[\abbrstyle{postfootnote-sm}] -Like \abbrstyle{postfootnote} but redefines \cs{glsabbrvfont} to +\item[\abbrstyle{short-sm-postfootnote}] +Like \abbrstyle{short-postfootnote} but redefines \cs{glsabbrvfont} to use \ics{glsxtrsmfont}. +(This style was originally called \depabbrstyle{postfootnote-sm}. Renamed in version +1.04, but original name retained as a deprecated synonym for +backward-compatibility.) -\item[\abbrstyle{postfootnote-em}] -Like \abbrstyle{postfootnote} but redefines \cs{glsabbrvfont} to -use \ics{emph}. +\item[\abbrstyle{short-em-postfootnote}] +Like \abbrstyle{short-postfootnote} but redefines \cs{glsabbrvfont} to +use \ics{glsxtremfont}. +(This style was originally called \depabbrstyle{postfootnote-em}. Renamed in version +1.04, but original name retained as a deprecated synonym for +backward-compatibility.) \end{description} @@ -2071,7 +2528,7 @@ The \meta{setup} argument may also redefine which can be used to assign attributes. (This will automatically be initialised to do nothing.) -For example, the \abbrstyle{footnote} includes the following in +For example, the \abbrstyle{short-footnote} includes the following in \meta{setup}: \begin{verbatim} \renewcommand*{\GlsXtrPostNewAbbreviation}{% @@ -2145,10 +2602,10 @@ If you want to base a style on an existing style, you can use \cs{GlsXtrUseAbbrStyleSetup}\marg{name} \end{definition} where \meta{name} is the name of the existing style. -For example, the \abbrstyle{footnote-sc} and \abbrstyle{footnote-sm} +For example, the \abbrstyle{short-sc-footnote} and \abbrstyle{short-sm-footnote} styles both simply use \begin{verbatim} -\GlsXtrUseAbbrStyleSetup{footnote} +\GlsXtrUseAbbrStyleSetup{short-footnote} \end{verbatim} within \meta{setup}. @@ -2180,6 +2637,12 @@ The font used for the long form on \gls{firstuse} or in the full forms: \cs{glsfirstlongfont}\marg{text} \end{definition} +The font used for the long form in commands like \cs{glsxtrlong} +use: +\begin{definition}[\DescribeMacro\glslongfont] +\cs{glslongfont}\marg{text} +\end{definition} + Display full form singular no case-change (used by \ics{gls} on \gls{firstuse} for abbreviations without the \catattr{regular} attribute set): @@ -2251,6 +2714,7 @@ For example, the \abbrstyle{short-long} style has the following in \renewcommand*{\glsabbrvfont}[1]{\glsabbrvdefaultfont{##1}}% \renewcommand*{\glsfirstabbrvfont}[1]{\glsfirstabbrvdefaultfont{##1}}% \renewcommand*{\glsfirstlongfont}[1]{\glsfirstlongdefaultfont{##1}}% + \renewcommand*{\glslongfont}[1]{\glslongdefaultfont{##1}}% \renewcommand*{\glsxtrfullformat}[2]{% \glsfirstabbrvfont{\glsaccessshort{##1}}##2\glsxtrfullsep{##1}% (\glsfirstlongfont{\glsaccesslong{##1}})% @@ -2301,7 +2765,7 @@ existing style are the \qt{em} styles, such as the }% {% fmts \GlsXtrUseAbbrStyleFmts{short-long}% - \renewcommand*{\glsabbrvfont}[1]{\emph{##1}}% + \renewcommand*{\glsabbrvfont}[1]{\glsxtremfont{##1}}% } \end{verbatim} @@ -2609,6 +3073,24 @@ post-\gls{linktext} hook will discard a~full stop (period) that follows \emph{non-plural} commands like \cs{gls} or \cs{glstext}. (Provided for entries such as abbreviations that end with a full stop.) +Note that this can cause a problem if you access a field that +doesn't end with a full stop. For example: +\begin{verbatim} +\newabbreviation + [user1={German Speaking \TeX\ User Group}] + {dante}{DANTE e.V.}{Deutschsprachige Anwendervereinigung \TeX\ +e.V.} +\end{verbatim} +Here the \gloskey{short} and \gloskey{long} fields end with a full stop, but the +\gloskey{user1} field doesn't. The simplest solution in this +situation is to put the sentence terminator in the final optional +argument. For example: +\begin{verbatim} +\glsuseri{dante}[.] +\end{verbatim} +This will bring the punctuation character inside the \gls{linktext} +and it won't be discarded. + \item[\catattr{pluraldiscardperiod}] If this attribute is set to \qt{true} \emph{and} the \catattr{discardperiod} attribute is set to \qt{true}, this will behave as above for the plural commands like @@ -2688,6 +3170,17 @@ the title casing command \ics{capitalisewords} (provided by \sty{mfirstuc}) is used on the name. Any other values of this attribute are ignored. +\item[\catattr{glossdescfont}] (New to version 1.04) +In addition to the above, the modified \ics{glossentrydesc} +command also checks this attribute. If set, it should be the name of +a control sequence (without the leading backslash) that takes one +argument. This control sequence will be applied to the description +text. For example: +\begin{verbatim} +\glssetcategoryattribute{general}{glossdescfont}{emph} +\end{verbatim} + + \item[\catattr{glossname}] As \catattr{glossdesc} but applies to \ics{glossentryname}. Additionally, if this attribute is set to \qt{uc} the name is converted to all capitals. @@ -2697,6 +3190,22 @@ used at the end of \ics{glossentyname} will index the entry using \ics{index}. See \sectionref{sec:autoindex} for further details. +\item[\catattr{glossnamefont}] (New to version 1.04) +In addition to the above, the modified \ics{glossentryname} +command also checks this attribute. If set, it should be the name of +a control sequence (without the leading backslash) that takes one +argument. This control sequence will be applied to the name +text. For example: +\begin{verbatim} +\glssetcategoryattribute{general}{glossnamefont}{emph} +\end{verbatim} +Note that this overrides \cs{glsnamefont} which will only +be used if this attribute hasn't been set. + +Remember that glossary styles may additionally apply a font change, +such as the list styles which put the name in the optional argument +of \cs{item}. + \item[\catattr{dualindex}] If set, whenever a glossary entry has information written to the external glossary file through commands like \ics{gls} and \ics{glsadd}, a~corresponding @@ -2783,7 +3292,7 @@ from a particular entry: \end{definition} There's also a shortcut to determine if a particular category has -the \catattr{regular} attribute set: +the \catattr{regular} attribute set to \qt{true}: \begin{definition}[\DescribeMacro\glsifregularcategory] \cs{glsifregularcategory}\marg{category-label}\marg{true-part}\marg{false-part} \end{definition} @@ -2792,6 +3301,19 @@ entry: \begin{definition}[\DescribeMacro\glsifregular] \cs{glsifregular}\marg{entry-label}\marg{true-part}\marg{false-part} \end{definition} +Note that if the \catattr{regular} attribute hasn't be set, the +above do \meta{false-part}. There are also reverse commands that +test if the \catattr{regular} attribute has been set to \qt{false}: +\begin{definition}[\DescribeMacro\glsifnotregularcategory] +\cs{glsifnotregularcategory}\marg{category-label}\marg{true-part}\marg{false-part} +\end{definition} +or for a particular entry: +\begin{definition}[\DescribeMacro\glsifnotregular] +\cs{glsifnotregular}\marg{entry-label}\marg{true-part}\marg{false-part} +\end{definition} +Again, if the \catattr{regular} attribute hasn't been set, the above +do \meta{false-part}, so these reverse commands aren't logically +opposite in the strict sense. You can iterate through all entries with a given category using: \begin{definition} @@ -3640,6 +4162,9 @@ files provided by the \sty{glossaries} package for testing. \item[sample-mixture.tex] General entries, acronyms and initialisms all treated differently. +\item[sample-name-font] Categories and attributes are used to +customize the way different entries appear. + \item[sample-abbrv.tex] General abbreviations. \item[sample-acronym.tex] Acronyms aren't initialisms and don't @@ -3690,6 +4215,9 @@ if used more than $n$ times). \item[sample-unitentrycount.tex] Enable use of per-unit entry-use counting. +\item[sample-pages.tex] Insert \qt{page} or \qt{pages} before the +location list. + \item[sample-onelink.tex] Using the per-unit entry counting to only have one hyperlink per entry per page. |