summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2017-08-09 22:15:23 +0000
committerKarl Berry <karl@freefriends.org>2017-08-09 22:15:23 +0000
commit88be00188d030954be624d333c41f0bf0a6c6488 (patch)
tree3e3b334e6c5d72e48de3d1ee9c73335008512589 /Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex
parent1aeae3e685706e19df5cf9084e71685db8e18d1a (diff)
glossaries-extra (9aug17)
git-svn-id: svn://tug.org/texlive/trunk@44998 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.tex1349
1 files changed, 933 insertions, 416 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 5178132f110..c80625f9bcb 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
@@ -148,32 +148,69 @@ governed by the \gloskey{first} and \gloskey{firstplural} keys of
\newcommand*{\acrstyle}[1]{\textsf{#1}\index{acronym
styles (glossaries):>#1={\protect\ttfamily#1}|main}}
-\newcommand*{\abbrstyle}[1]{\textsf{#1}\index{abbreviation styles:>#1={\protect\sffamily#1}|main}}
+\newcommand*{\abbrstylenolink}[1]{%
+ \textsf{#1}\index{abbreviation styles:>#1={\protect\sffamily#1}|main}}
+
+\newcommand*{\abbrstyle}[1]{%
+ \hyperlink{abbrstyle.#1}{\textsf{#1}}%
+ \index{abbreviation styles:>#1={\protect\sffamily#1}|main}%
+}
+
+\makeatletter
+\newcommand{\htarget}[2]{\Hy@raisedlink{\hypertarget{#1}{}}#2}
+\makeatother
+
+\newcommand*{\abbrstyledef}[1]{%
+ \htarget{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}}
+\newcommand*{\catattrnolink}[1]{%
+ \textsf{#1}\index{category attributes:>#1={\protect\sffamily#1}|main}}
+
+\newcommand*{\catattr}[1]{%
+ \hyperlink{catattr.#1}{\textsf{#1}}%
+ \index{category attributes:>#1={\protect\sffamily#1}|main}%
+}
+
+\newcommand*{\catattrdef}[1]{%
+ \htarget{catattr.#1}{\textsf{#1}}%
+ \index{category attributes:>#1={\protect\sffamily#1}|main}%
+}
\newcommand*{\postlinkcat}{%
\cs{glsxtrpostlink}\meta{category}%
\index{glsxtrpostlinkcategory=\cs{glsxtrpostlink}\meta{category}|hyperpage}%
}
+\newcommand*{\styopt}[2][]{%
+ \hyperlink{styopt.#2}{\pkgoptfmt{#2}}%
+ \ifstrempty{#1}{}{\pkgoptfmt{=#1}}%
+ \ipkgopt[#1]{#2}%
+}
+
+\newcommand*{\styoptdef}[1]{%
+ \htarget{styopt.#1}{\pkgoptfmt{#1}}%
+ \ipkgopt{#1}%
+}
+
\setlength\marginparwidth{70pt}
\begin{document}
\DeleteShortVerb{\|}
\MakeShortVerb{"}
- \title{glossaries-extra.sty v1.16:
+ \title{glossaries-extra.sty v1.17:
an extension to the glossaries package}
\author{Nicola L.C. Talbot\\[10pt]
Dickimaw Books\\
\url{http://www.dickimaw-books.com/}}
- \date{2017-06-15}
+ \date{2017-08-09}
\maketitle
\begin{abstract}
@@ -269,8 +306,8 @@ contents). Use \pkgopt[false]{toc} to switch this back off.
\item \pkgopt[true]{nopostdot} (suppress the terminating full stop
after the description in the glossary). Use
-\pkgopt[false]{nopostdot} to restore the terminating full stop
-(period).
+\pkgopt[false]{nopostdot} or just \styopt{postdot} to restore the
+terminating full stop (period).
\item \pkgopt[true]{noredefwarn} (suppress the warnings that occur when
the \env{theglossary} environment and \cs{printglossary} are redefined while
@@ -414,10 +451,12 @@ to add the \pkgopt{nomain} package option:
\begin{verbatim}
\documentclass{article}
-\usepackage[nomain,acronym]{glossaries-extra}
+\usepackage[nomain,acronym,postdot]{glossaries-extra}
\makeglossaries
+\setabbreviationstyle[acronym]{long-short}
+
\newacronym{laser}{laser}{light amplification by stimulated
emission of radiation}
@@ -429,7 +468,9 @@ emission of radiation}
\end{document}
\end{verbatim}
-
+(Note the need to set the acronym style using
+\cs{setabbreviationstyle} before \cs{newacronym}.
+See \sectionref{sec:abbreviations} for further details.)
\section{New or Modified Package Options}
\label{sec:pkgopts}
@@ -454,7 +495,10 @@ The new and modified options provided by \styfmt{glossaries-extra}
are described below:
\begin{description}
-\item[{\pkgopt{accsupp}}] Load the \sty{glossaries-accsupp}
+\item[{\styoptdef{postdot}}] (New to version 1.12.)
+This option is just a shortcut for \pkgopt[false]{nopostdot}.
+
+\item[{\styoptdef{accsupp}}] Load the \sty{glossaries-accsupp}
package (if not already loaded).
If you want to define styles that can interface with the
@@ -472,7 +516,7 @@ 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
+\item[{\styoptdef{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
@@ -480,7 +524,7 @@ 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}
+\item[{\styoptdef{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
glossary entry is referenced. The default behaviour is
@@ -495,7 +539,7 @@ over a glossary list. This includes \ics{forglsentries} and
\ics{glsaddall}.
\end{important}
-\item[{\pkgopt{indexcrossrefs}}] This is a boolean option.
+\item[{\styoptdef{indexcrossrefs}}] This is a boolean option.
If \pkgoptfmt{true}, this will automatically index any
cross-referenced entries that haven't been marked as used at
the end of the document. Note that this necessarily adds to
@@ -503,7 +547,7 @@ the overall document build time, especially if you have defined
a large number of entries, so this defaults to \pkgoptfmt{false},
but it will be automatically switched on if you use the \gloskey{see}
or \gloskey{seealso} keys in any entries (unless
-\pkgopt[false]{autoseeindex}). To force it off, even if you use the
+\styopt[false]{autoseeindex}). To force it off, even if you use the
\gloskey{see} or \gloskey{seealso} key, you
need to explicitly set \pkgopt{indexcrossrefs} to \pkgoptfmt{false}.
@@ -512,7 +556,7 @@ entries when it parses the \texttt{.bib} source file.
The \pkgopt{record} option automatically implements
\pkgopt[false]{indexcrossrefs}.
-\item[{\pkgopt{autoseeindex}}]\label{opt:autoseeindex} (New to
+\item[{\styoptdef{autoseeindex}}]\label{opt:autoseeindex} (New to
v1.16.) This is a boolean option. If true (default), this makes
the \gloskey{see} and \gloskey{seealso} keys automatically index the
cross-reference when an entry is defined. If false, the value
@@ -521,7 +565,7 @@ of those keys will still be stored in their corresponding fields
\cs{glsxtruseseealso}) but cross-reference won't be automatically
indexed.
-Note that the \pkgopt[only]{record} option automatically implements
+Note that the \styopt[only]{record} option automatically implements
\pkgopt[false]{autoseeindex}.
For example, if an entry is defined as
@@ -540,7 +584,7 @@ but with \texttt{autoseeindex=false}, this is equivalent to
\newglossaryentry{foo}{name={foo},description={}}
\GlsXtrSetField{foo}{see}{bar,baz}
\end{verbatim}
-Note that \pkgopt{indexcrossrefs} isn't automatically implemented
+Note that \styopt{indexcrossrefs} isn't automatically implemented
by the presence of the \gloskey{see} key when \pkgopt{autoseeindex}
is false.
@@ -554,7 +598,7 @@ open, the information can't be written to it. This will need
the package option \pkgoptfmt{seenoindex=ignore} (provided by
\styfmt{glossaries}) to prevent an error occurring.
-\item[{\pkgopt{record}}]\label{opt:record}(New to v1.08.) This is a \meta{key}=\meta{value}
+\item[{\styoptdef{record}}]\label{opt:record}(New to v1.08.) This is a \meta{key}=\meta{value}
option, which has three allowed values: \pkgoptfmt{off} (default),
\pkgoptfmt{only} and \pkgoptfmt{alsoindex}. If the value is omitted
\pkgoptfmt{only} is assumed. The option is provided for the benefit
@@ -563,10 +607,10 @@ of \gls{bib2gls} (see \sectionref{sec:bib2gls}).
The option may only be set in the preamble.
The \pkgopt[off]{record} option switches off the recording, as per
-the default behaviour. It implements \pkgopt[error]{undefaction}.
+the default behaviour. It implements \styopt[error]{undefaction}.
The other values switch on the recording and also
-\pkgopt[warn]{undefaction}, but \pkgopt[only]{record}
+\styopt[warn]{undefaction}, but \pkgopt[only]{record}
will also switch off the indexing mechanism (even if \cs{makeglossaries}
or \cs{makenoidxglossaries} has been used) whereas
\pkgopt[alsoindex]{record} will both record and index.
@@ -590,7 +634,7 @@ out which entries have been used. (Remember that commands like
add a corresponding \cs{glsxtr@record} entry to the \texttt{.aux}
file.) See \sectionref{sec:bib2gls} for further details.
-\item[{\pkgopt{docdef}}] This option governs the use of
+\item[{\styoptdef{docdef}}] This option governs the use of
\cs{newglossaryentry}. It was originally a boolean option,
but as from version 1.06, it can now take one of three values (if
the value is omitted, \pkgoptfmt{true} is assumed):
@@ -627,7 +671,7 @@ remains a preamble-only command.
With this option, if an entry appears in the glossary before
it has been defined, an error will occur (or a warning if
-the \pkgopt[warn]{undefaction} option is used.) If you edit your
+the \styopt[warn]{undefaction} option is used.) If you edit your
document and either remove an entry or change its label, you may
need to delete the document's temporary files (such as the
\texttt{.aux} and \texttt{.gls} files).
@@ -656,14 +700,14 @@ This option affects commands that internally use
the \qt{on-the-fly} commands described in \sectionref{sec:onthefly}.
\end{sloppypar}
-\item[{\pkgopt{nomissingglstext}}] This is a boolean option.
+\item[{\styoptdef{nomissingglstext}}] This is a boolean option.
If true, this will suppress the warning text that will appear in the
document if the external glossary files haven't been generated due
to an incomplete document build. However, it's probably simpler
just to fix whatever has caused the failure to build the external
file or files.
-\item[{\pkgopt{abbreviations}}] This option has no value and can't
+\item[{\styoptdef{abbreviations}}] This option has no value and can't
be cancelled. If used,
it will automatically create a new glossary with the label
\texttt{abbreviations} and redefines \cs{glsxtrabbrvtype} to this
@@ -708,7 +752,7 @@ package's \pkgopt{acronymlists} option (or associated commands)
as the abbreviation mechanism is handled differently with
\styfmt{glossaries-extra}.
-\item[{\pkgopt{symbols}}] This is passed to \styfmt{glossaries} but
+\item[{\styoptdef{symbols}}] This is passed to \styfmt{glossaries} but
will additionally define
\begin{definition}[\DescribeMacro\glsxtrnewsymbol]
\cs{glsxtrnewsymbol}\oarg{options}\marg{label}\marg{symbol}
@@ -721,7 +765,7 @@ which is equivalent to
Note that the \gloskey{sort} key is set to the \meta{label}
not the \meta{symbol} as the symbol will likely contain commands.
-\item[{\pkgopt{numbers}}] This is passed to \styfmt{glossaries} but
+\item[{\styoptdef{numbers}}] This is passed to \styfmt{glossaries} but
will additionally define
\begin{definition}[\DescribeMacro\glsxtrnewnumber]
\cs{glsxtrnewnumber}\oarg{options}\marg{number}
@@ -732,13 +776,20 @@ which is equivalent to
sort=\marg{label},type=numbers,category=number,\meta{options}\}
\end{alltt}
-\item[{\pkgopt{shortcuts}}] Unlike the \styfmt{glossaries} package
+\item[{\styoptdef{shortcuts}}] Unlike the \styfmt{glossaries} package
option of the same name, this option isn't boolean but has multiple
values:
\begin{itemize}
\item \pkgopt[acronyms]{shortcuts} (or \pkgopt[acro]{shortcuts}):
set the shortcuts provided by the \styfmt{glossaries} package for acronyms (such as \cs{ac}).
+\item \pkgopt[ac]{shortcuts}:
+set the shortcuts provided by the \styfmt{glossaries} package for
+acronyms (such as \cs{ac}) but uses the \styfmt{glossaries-extra}
+interface (such as \cs{glsxtrshort} rather than \cs{acrshort}).
+In this case \cs{ac} is defined as \cs{cgls} rather than
+\cs{gls}.
+
\item \pkgopt[abbreviations]{shortcuts} (or
\pkgopt[abbr]{shortcuts}):
set the abbreviation shortcuts provided by \styfmt{glossaries-extra}. (See
@@ -773,8 +824,8 @@ set available options using
\begin{definition}[\DescribeMacro\glossariesextrasetup]
\cs{glossariesextrasetup}\marg{options}
\end{definition}
-The \pkgopt{abbreviations} and \pkgopt{docdef} options may only be
-used in the preamble. Additionally, \pkgopt{docdef} can't be used
+The \styopt{abbreviations} and \styopt{docdef} options may only be
+used in the preamble. Additionally, \styopt{docdef} can't be used
after \ics{makenoidxglossaries}.
\chapter{Modifications to Existing Commands and Styles}
@@ -782,7 +833,7 @@ after \ics{makenoidxglossaries}.
The commands used by \styfmt{glossaries} to automatically produce an
error if an entry is undefined (such as \ics{glsdoifexists}) are
-changed to take the \pkgopt{undefaction} option into account.
+changed to take the \styopt{undefaction} option into account.
The \ics{newignoredglossary}\marg{type} command now (as from v1.11) has a starred
version that doesn't automatically switch off the hyperlinks.
@@ -893,7 +944,7 @@ for the other glossaries. (See the accompanying file
\begin{important}
If you use the optional argument \meta{list}, you can't define
-entries in the document (even with the \pkgopt{docdef} option).
+entries in the document (even with the \styopt{docdef} option).
\end{important}
You will need at least version 2.20 of \gls{makeglossaries} or at
@@ -1080,7 +1131,7 @@ This modification allows \styfmt{glossaries-extra} to provide
\end{definition}
which is used at the end of the document to automatically add
any unused cross-references unless the package option
-\pkgopt{indexcrossrefs} was set to false.
+\styopt{indexcrossrefs} was set to false.
As a by-product of this enhancement, the \gloskey{see} key will now
work for entries defined in the \env{document} environment, but it's still
@@ -1596,11 +1647,8 @@ use
\end{definition}
which defaults to just \cs{glspluralsuffix}. Some of the
abbreviation styles have their own command for the plural suffix,
-such as \cs{glsxtrscsuffix} which is defined as:
-\begin{verbatim}
-\newcommand*{\glsxtrscsuffix}{\glstextup{\glsxtrabbrvpluralsuffix}}
-\end{verbatim}
-So if you want to completely strip all the plural suffixes used for
+such as \cs{glsxtrscsuffix},
+so if you want to completely strip all the plural suffixes used for
abbreviations then you need to redefine \cs{glsxtrabbrvpluralsuffix}
\emph{not} \cs{abbrvpluralsuffix}, which changes with the style. Redefining
\cs{acrpluralsuffix} will have no affect, since it's not used by the
@@ -2327,14 +2375,14 @@ passing \meta{name} as a package option to
\usepackage{glossaries-extra}
\usepackage[longragged]{glossaries-extra-stylemods}
\end{verbatim}
-Another option is to use the \pkgopt{stylemods} key when you
+Another option is to use the \styopt{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
+Or the value of \styopt{stylemods} may be a comma-separated list
of the style package identifiers. For example:
\begin{verbatim}
\usepackage[style=mcoltree,stylemods=mcols]{glossaries-extra}
@@ -2567,106 +2615,11 @@ the \styfmt{glossaries} package, although they may produce similar
results.)
\end{sloppypar}
-The short form is displayed within commands like \cs{gls} using
-\begin{definition}[\DescribeMacro\glsfirstabbrvfont]
-\cs{glsfirstabbrvfont}\marg{short-form}
-\end{definition}
-on \gls{firstuse} and
-\begin{definition}[\DescribeMacro\glsabbrvfont]
-\cs{glsabbrvfont}\marg{short-form}
-\end{definition}
-for subsequent use.
-
-\begin{important}
-These commands (\cs{glsfirstabbrvfont} and \cs{glsabbrvfont}) are
-reset by the abbreviation styles and whenever an abbreviation is
-used by commands like \cs{gls} (but not by commands like
-\ics{glsentryshort}) so don't try redefining them outside of an
-abbreviation style.
-\end{important}
-
-If you use the \abbrstyle{long-short} style,
-\cs{glsabbrvfont} is redefine to use
-\begin{definition}[\DescribeMacro\glsabbrvdefaultfont]
-\cs{glsabbrvdefaultfont}\marg{text}
-\end{definition}
-whereas the \abbrstyle{long-short-sc} style redefines
-\cs{glsabbrvfont} to use \cs{glsxtrscfont}. If you want to use a different
-font-changing command you can either redefine \cs{glsabbrvdefaultfont} and
-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.
-
-Similarly the basic styles redefine \cs{glsfirstabbrvfont}
-to use
-\begin{definition}[\DescribeMacro\glsfirstabbrvdefaultfont]
-\cs{glsfirstabbrvdefaultfont}\marg{short-form}
-\end{definition}
-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 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, 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}
-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:
-\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 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).
+The way the abbreviations are displayed by commands like \cs{gls}
+varies according to the abbreviation style. The styles are set
+according to the entry's category so, unlike the base
+\styfmt{glossaries} package, you can have different abbreviation
+styles within the same glossary.
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
@@ -2803,6 +2756,13 @@ The \emph{inline} full form can be produced with
\end{definition}
(This this instead of \ics{acrfull}.)
+\begin{important}
+In general, it's best not to use commands like \ics{glsfirst}
+for abbreviations, especially if you use the \meta{insert}
+optional argument. Use either \cs{gls} (possibly with a reset)
+or \cs{glsxtrfull}.
+\end{important}
+
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-nolong} style
@@ -2897,37 +2857,47 @@ entry was defined. If you have mixed styles, you'll need to use
\label{sec:abbrshortcuts}
The abbreviation shortcut commands can be enabled using
-the package option \pkgopt[abbreviation]{shortcuts}
-(or \pkgopt[abbr]{shortcuts}). This defines the commands listed in
+the package option \styopt[abbreviation]{shortcuts}
+(or \styopt[abbr]{shortcuts}) or \styopt[ac]{shortcuts}.
+(You can use both settings at the same time.)
+The provided shortcut commands listed in
\tableref{tab:abbrshortcuts}.
\begin{table}[htbp]
\caption{Abbreviation Shortcut Commands}
\label{tab:abbrshortcuts}
\centering
-\begin{tabular}{ll}
-\bfseries Shortcut & \bfseries Equivalent Command\\
-\ics{ab} & \ics{cgls}\\
-\ics{abp} & \ics{cglspl}\\
-\ics{as} & \ics{glsxtrshort}\\
-\ics{asp} & \ics{glsxtrshortpl}\\
-\ics{al} & \ics{glsxtrlong}\\
-\ics{alp} & \ics{glsxtrlongpl}\\
-\ics{af} & \ics{glsxtrfull}\\
-\ics{afp} & \ics{glsxtrfullpl}\\
-\ics{As} & \ics{Glsxtrshort}\\
-\ics{Asp} & \ics{Glsxtrshortpl}\\
-\ics{Al} & \ics{Glsxtrlong}\\
-\ics{Alp} & \ics{Glsxtrlongpl}\\
-\ics{Af} & \ics{Glsxtrfull}\\
-\ics{Afp} & \ics{Glsxtrfullpl}\\
-\ics{AS} & \ics{GLSxtrshort}\\
-\ics{ASP} & \ics{GLSxtrshortpl}\\
-\ics{AL} & \ics{GLSxtrlong}\\
-\ics{ALP} & \ics{GLSxtrlongpl}\\
-\ics{AF} & \ics{GLSxtrfull}\\
-\ics{AFP} & \ics{GLSxtrfullpl}\\
-\ics{newabbr} & \ics{newabbreviation}
+\begin{tabular}{lll}
+\bfseries Shortcut &
+\bfseries Shortcut &
+\bfseries Equivalent Command\\
+\bfseries (\pkgopt[abbreviation]{shortcuts}) &
+\bfseries (\pkgopt[ac]{shortcuts})\\
+\ics{ab} & \ics{ac} & \ics{cgls}\\
+\ics{abp} & \ics{acp} & \ics{cglspl}\\
+\ics{as} & \ics{acs} & \ics{glsxtrshort}\\
+\ics{asp} & \ics{acsp} & \ics{glsxtrshortpl}\\
+\ics{al} & \ics{acl} & \ics{glsxtrlong}\\
+\ics{alp} & \ics{aclp} & \ics{glsxtrlongpl}\\
+\ics{af} & \ics{acf} & \ics{glsxtrfull}\\
+\ics{afp} & \ics{acfp} & \ics{glsxtrfullpl}\\
+\ics{Ab} & \ics{Ac} & \ics{cgls}\\
+\ics{Abp} & \ics{Acp} & \ics{cglspl}\\
+\ics{As} & \ics{Acs} & \ics{Glsxtrshort}\\
+\ics{Asp} & \ics{Acsp} & \ics{Glsxtrshortpl}\\
+\ics{Al} & \ics{Acl} & \ics{Glsxtrlong}\\
+\ics{Alp} & \ics{Aclp} & \ics{Glsxtrlongpl}\\
+\ics{Af} & \ics{Acf} & \ics{Glsxtrfull}\\
+\ics{Afp} & \ics{Acfp} & \ics{Glsxtrfullpl}\\
+\ics{AB} & \ics{AC} & \ics{cGLS}\\
+\ics{ABP} & \ics{ACP} & \ics{cGLSpl}\\
+\ics{AS} & \ics{ACS} & \ics{GLSxtrshort}\\
+\ics{ASP} & \ics{ACSP} & \ics{GLSxtrshortpl}\\
+\ics{AL} & \ics{ACL} & \ics{GLSxtrlong}\\
+\ics{ALP} & \ics{ACLP} & \ics{GLSxtrlongpl}\\
+\ics{AF} & \ics{ACF} & \ics{GLSxtrfull}\\
+\ics{AFP} & \ics{ACFP} & \ics{GLSxtrfullpl}\\
+\ics{newabbr} & \ics{newabbr} & \ics{newabbreviation}
\end{tabular}
\end{table}
@@ -2960,6 +2930,9 @@ In both cases, the \gls{firstuse} of \ics{gls} may not match the
text produced by \ics{glsfirst} (and likewise for the plural
and case-changing versions).
+The sample file \texttt{sample-abbr-styles.tex} demonstrates all
+predefined styles described here.
+
\begin{important}
For the \qt{sc} styles that use \ics{textsc}, be careful about your choice
of fonts as some only have limited support. For
@@ -2968,29 +2941,66 @@ recommend that you at least use the \sty{fontenc} package with the
\pkgoptfmt{T1} option or something similar.
\end{important}
-The \qt{sc} styles all use
-\begin{definition}[\DescribeMacro\glsxtrscfont]
-\cs{glsxtrscfont}\marg{text}
+The parenthetical styles, such as \abbrstyle{long-short},
+use
+\begin{definition}[\DescribeMacro\glsxtrparen]
+\cs{glsxtrparen}\marg{text}
+\end{definition}
+to set the parenthetical material. This just puts parentheses around
+the text: (\meta{text}).
+
+The basic abbreviation styles, such as \abbrstyle{long-short}
+and \abbrstyle{short-long} use
+\begin{definition}[\DescribeMacro\glsabbrvdefaultfont]
+\cs{glsabbrvdefaultfont}\marg{text}
\end{definition}
-which is defined as
-\begin{verbatim}
-\newcommand*{\glsxtrscfont}[1]{\textsc{#1}}
-\end{verbatim}
-and
-\begin{definition}[\DescribeMacro\glsxtrfirstscfont]
-\cs{glsxtrfirstscfont}\marg{text}
+for the short form. This just does \meta{text} by default.
+(That is, no font change is applied.) On first use,
+\begin{definition}[\DescribeMacro\glsfirstabbrvdefaultfont]
+\cs{glsfirstabbrvdefaultfont}\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
+is used instead. By default, this just does
+\cs{glsabbrvdefaultfont}. The long form is formatted according to
+\begin{definition}[\DescribeMacro\glslongdefaultfont]
+\cs{glslongdefaultfont}\marg{text}
+\end{definition}
+which again just does \meta{text} (no font change). On first use,
+\begin{definition}[\DescribeMacro\glsfirstlongdefaultfont]
+\cs{glsfirstlongdefaultfont}\marg{text}
+\end{definition}
+is used instead. This just does \cs{glslongdefaultfont}.
+The plural suffix used for the short form is given by
+\begin{definition}[\DescribeMacro\glsxtrabbrvpluralsuffix]
+\cs{glsxtrabbrvpluralsuffix}
+\end{definition}
+which defaults to \ics{glspluralsuffix}.
+
+The small-cap styles, such as \abbrstyle{long-short-sc}
+and \abbrstyle{short-sc-long}, use
+\begin{definition}[\DescribeMacro\glsabbrvscfont]
+\cs{glsabbrvscfont}\marg{text}
+\end{definition}
+which uses \cs{textsc}.\footnote{For compatibility with earlier
+versions, \cs{glsabbrvscfont} is defined to \cs{glsxtrscfont},
+which is defined to use \cs{textsc}. Direct use of
+\cs{glsxtrscfont} is now deprecated. Likewise for similar commands.}
+On first use
+\begin{definition}[\DescribeMacro\glsabbrvdefaultfont]
+\cs{glsfirstabbrvscfont}\marg{text}
+\end{definition}
+is used instead. This uses \cs{glsabbrvscfont} by default.
+So redefine, \cs{glsabbrvscfont} to change first and subsequent uses or
+\cs{glsfirstabbrvscfont} to change just the first use.
+
+The long form for the small-cap styles uses \cs{glslongdefaultfont}
+or \cs{glsfirstlongdefaultfont}, as with the basic style.
+The suffix is given by
\begin{definition}[\DescribeMacro\glsxtrscsuffix]
\cs{glsxtrscsuffix}
\end{definition}
-This just defined as
+This is defined as
\begin{verbatim}
-\newcommand*{\glsxtrscsuffix}{\glstextup{\glspluralsuffix}}
+\newcommand*{\glsxtrscsuffix}{\glstextup{\glsxtrabbrvpluralsuffix}}
\end{verbatim}
The \ics{glstextup} command is provided by \styfmt{glossaries}
and is used to switch off the small caps font for the suffix.
@@ -3002,59 +3012,160 @@ 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}
+The small styles, such as \abbrstyle{long-short-sm}
+and \abbrstyle{short-sm-long}, use
+\begin{definition}[\DescribeMacro\glsabbrvsmfont]
+\cs{glsabbrvsmfont}\marg{text}
\end{definition}
-This is defined as:
-\begin{verbatim}
-\newcommand*{\glsxtrsmfont}[1]{\textsmaller{#1}}
-\end{verbatim}
-and
-\begin{definition}[\DescribeMacro\glsxtrfirstsmfont]
-\cs{glsxtrfirstsmfont}\marg{text}
+which uses \cs{textsmaller}. (This requires the \sty{relsizes}
+package, which isn't loaded by \styfmt{glossaries-extra}, so must be
+loaded explicitly.)
+On first use
+\begin{definition}[\DescribeMacro\glsfirstabbrvsmfont]
+\cs{glsfirstabbrvsmfont}\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:
-\begin{verbatim}
-\renewcommand*{\glsxtrsmfont}[1]{\textsmaller{\MakeTextUppercase{#1}}}
-\end{verbatim}
-The default plural suffix for the short form is set to
+is used instead. This uses \cs{glsabbrvsmfont} by default.
+
+The long form for the smaller styles uses \cs{glslongdefaultfont}
+or \cs{glsfirstlongdefaultfont}, as with the basic style.
+The suffix is given by
\begin{definition}[\DescribeMacro\glsxtrsmsuffix]
\cs{glsxtrsmsuffix}
\end{definition}
-This just does \ics{glspluralsuffix}.
+which defaults to just \cs{glsxtrabbrvpluralsuffix}.
-The \qt{em} styles all use
+The \qt{short-em} (emphasize short) styles, such as
+\abbrstyle{long-short-em} or \abbrstyle{short-em-long}, 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
+On first use
\begin{definition}[\DescribeMacro\glsfirstabbrvemfont]
\cs{glsfirstabbrvemfont}\marg{text}
\end{definition}
-which is defined as:
+is used instead. This uses \cs{glsabbrvemfont} by default.
+The suffix is given by
+\begin{definition}[\DescribeMacro\glsxtremsuffix]
+\cs{glsxtremsuffix}
+\end{definition}
+which defaults to just \cs{glsxtrabbrvpluralsuffix}.
+The long form is as for the basic style unless the style
+is a \qt{long-em} style.
+
+The \qt{long-em} (emphasize long) styles, such as
+\abbrstyle{long-em-short-em} or \abbrstyle{short-em-long-em}, 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}.
+
+The user styles have similar commands:
+\begin{definition}[\DescribeMacro\glsabbrvuserfont]
+\cs{glsabbrvuserfont}\marg{text}
+\end{definition}
+for the short form,
+\begin{definition}[\DescribeMacro\glsfirstabbrvuserfont]
+\cs{glsfirstabbrvuserfont}\marg{text}
+\end{definition}
+for the first use short form,
+\begin{definition}[\DescribeMacro\glslonguserfont]
+\cs{glslonguserfont}\marg{text}
+\end{definition}
+for the long form,
+\begin{definition}[\DescribeMacro\glsfirstlonguserfont]
+\cs{glsfirstlonguserfont}\marg{text}
+\end{definition}
+for the first use long form, and
+\begin{definition}[\DescribeMacro\glsxtrusersuffix]
+\cs{glsxtrusersuffix}
+\end{definition}
+for the short plural suffix.
+
+Similarly for the hyphen styles:
+\begin{definition}[\DescribeMacro\glsabbrvhyphenfont]
+\cs{glsabbrvhyphenfont}\marg{text}
+\end{definition}
+for the short form,
+\begin{definition}[\DescribeMacro\glsfirstabbrvhyphenfont]
+\cs{glsfirstabbrvhyphenfont}\marg{text}
+\end{definition}
+for the first use short form,
+\begin{definition}[\DescribeMacro\glslonghyphenfont]
+\cs{glslonghyphenfont}\marg{text}
+\end{definition}
+for the long form,
+\begin{definition}[\DescribeMacro\glsfirstlonghyphenfont]
+\cs{glsfirstlonghyphenfont}\marg{text}
+\end{definition}
+for the first use long form, and
+\begin{definition}[\DescribeMacro\glsxtrhyphensuffix]
+\cs{glsxtrhyphensuffix}
+\end{definition}
+for the short plural suffix.
+
+Similarly for the \qt{only} styles, such as
+\abbrstyle{long-only-short-only}:
+\begin{definition}[\DescribeMacro\glsabbrvonlyfont]
+\cs{glsabbrvonlyfont}\marg{text}
+\end{definition}
+for the short form,
+\begin{definition}[\DescribeMacro\glsfirstabbrvonlyfont]
+\cs{glsfirstabbrvonlyfont}\marg{text}
+\end{definition}
+for the first use short form,
+\begin{definition}[\DescribeMacro\glslongonlyfont]
+\cs{glslongonlyfont}\marg{text}
+\end{definition}
+for the long form,
+\begin{definition}[\DescribeMacro\glsfirstlongonlyfont]
+\cs{glsfirstlongonlyfont}\marg{text}
+\end{definition}
+for the first use long form, and
+\begin{definition}[\DescribeMacro\glsxtronlysuffix]
+\cs{glsxtronlysuffix}
+\end{definition}
+for the short plural suffix.
+
+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 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).
+
+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{glsabbrvscfont} to
+convert its argument to lowercase. For example:
+\begin{verbatim}
+\renewcommand*{\glsabbrvscfont}[1]{\textsc{\MakeLowercase{#1}}}
+\end{verbatim}
+
+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 case:
\begin{verbatim}
-\newcommand*{\glsfirstabbrvemfont}[1]{\glsabbrvemfont{#1}}
+\renewcommand*{\glsabbrvscfont}[1]{\textsc{\MakeTextLowercase{#1}}}
+\renewcommand*{\glsabbrvsmfont}[1]{\textsmaller{\MakeTextUppercase{#1}}}
\end{verbatim}
Some of the styles use
@@ -3074,7 +3185,7 @@ or
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}]
+\meta{field1}[\texttt{-}\meta{modifier1}]\texttt{-}[post]\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
@@ -3085,6 +3196,9 @@ 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 \texttt{post} is present then \meta{field2} is
+placed after the \gls{linktext} using the post-link hook.
+
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.)
@@ -3101,8 +3215,32 @@ 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}).
+
+ \item\abbrstyle{long-hyphen-postshort-hyphen}: the short
+form and the inserted material (provided by the final optional
+argument of commands like \cs{gls}) is moved to the post-link hook.
+The long form is formatted according to \cs{glslonghyphenfont}
+(or \cs{glsfirstlonghyphenfont} on first use).
+The short form is formatted according to \cs{glsabbrvhyphenfont}
+(or \cs{glsfirstabbrvhyphenfont} on first use).
\end{itemize}
+\item \meta{style}\texttt{-noreg}
+
+Some styles set the \catattr{regular} attribute. In some cases,
+there's a version of the style that doesn't set this attribute.
+For example, \abbrstyle{long-em-noshort-em} sets the
+\catattr{regular} attribute. The
+\abbrstyle{long-em-noshort-em-noreg} style is a minor variation
+that style that doesn't set the attribute.
+
+There are a few \qt{noshort} styles, such as
+\abbrstyle{long-hyphen-noshort-noreg}, that have
+\qt{-noreg} version without a regular version. This is because the
+style won't work properly with the \catattr{regular} set, but the
+naming scheme is maintained for consistency with the other
+\qt{noshort} styles.
+
\item
\meta{field1}[\texttt{-}\meta{modifier1}]\texttt{-}[\texttt{post}]\texttt{footnote}
@@ -3165,34 +3303,34 @@ attribute to \qt{true} for all categories that have abbreviations
defined with any of these styles.
\begin{description}
-\item[\abbrstyle{short-nolong}]
+\item[\abbrstyledef{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}] A synonym for \abbrstyle{short-nolong}.
+\item[\abbrstyledef{short}] A synonym for \abbrstyle{short-nolong}.
-\item[\abbrstyle{short-sc-nolong}]
+\item[\abbrstyledef{short-sc-nolong}]
Like \abbrstyle{short-nolong} but redefines \cs{glsabbrvfont} to
-use \ics{glsxtrscfont}.
+use \ics{glsabbrvscfont} (which defaults to \cs{textsc}).
-\item[\abbrstyle{short-sc}] A synonym for \abbrstyle{short-sc-nolong}
+\item[\abbrstyledef{short-sc}] A synonym for \abbrstyle{short-sc-nolong}
-\item[\abbrstyle{short-sm-nolong}]
+\item[\abbrstyledef{short-sm-nolong}]
Like \abbrstyle{short-nolong} but redefines \cs{glsabbrvfont} to
-use \ics{glsxtrsmfont}.
+use \ics{glsabbrvsmfont} (which defaults to \cs{textsmaller}).
-\item[\abbrstyle{short-sm}] A synonym for \abbrstyle{short-sm-nolong}.
+\item[\abbrstyledef{short-sm}] A synonym for \abbrstyle{short-sm-nolong}.
-\item[\abbrstyle{short-em-nolong}]
+\item[\abbrstyledef{short-em-nolong}]
Like \abbrstyle{short-nolong} but redefines \cs{glsabbrvfont} to
-use \ics{glsxtremfont}.
+use \ics{glsabbrvemfont}.
-\item[\abbrstyle{short-em}] A synonym for \abbrstyle{short-em-nolong}
+\item[\abbrstyledef{short-em}] A synonym for \abbrstyle{short-em-nolong}
-\item[\abbrstyle{short-nolong-desc}]
+\item[\abbrstyledef{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-nolong} style with the
@@ -3200,31 +3338,31 @@ 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-desc}] A synonym for
+\item[\abbrstyledef{short-desc}] A synonym for
\abbrstyle{short-nolong-desc}.
-\item[\abbrstyle{short-sc-nolong-desc}]
+\item[\abbrstyledef{short-sc-nolong-desc}]
Like \abbrstyle{short-nolong} but redefines \cs{glsabbrvfont} to
-use \ics{glsxtrscfont}.
+use \ics{glsabbrvscfont} (which defaults to \cs{textsc}).
-\item[\abbrstyle{short-sc-desc}] A synonym for
+\item[\abbrstyledef{short-sc-desc}] A synonym for
\abbrstyle{short-sc-nolong-desc}.
-\item[\abbrstyle{short-sm-nolong-desc}]
+\item[\abbrstyledef{short-sm-nolong-desc}]
Like \abbrstyle{short-nolong-desc} but redefines \cs{glsabbrvfont} to
-use \ics{glsxtrsmfont}.
+use \ics{glsabbrvsmfont} (which defaults to \cs{textsmaller}).
-\item[\abbrstyle{short-sm-desc}] A synonym for
+\item[\abbrstyledef{short-sm-desc}] A synonym for
\abbrstyle{short-sm-nolong-desc}.
-\item[\abbrstyle{short-em-nolong-desc}]
+\item[\abbrstyledef{short-em-nolong-desc}]
Like \abbrstyle{short-nolong-desc} but redefines \cs{glsabbrvfont} to
-use \ics{glsxtremfont}.
+use \ics{glsabbrvemfont}.
-\item[\abbrstyle{short-em-desc}] A synonym for
+\item[\abbrstyledef{short-em-desc}] A synonym for
\abbrstyle{short-em-nolong-desc}.
-\item[\abbrstyle{long-noshort-desc}]
+\item[\abbrstyledef{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
@@ -3237,36 +3375,36 @@ 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}] A synonym for
+\item[\abbrstyledef{long-desc}] A synonym for
\abbrstyle{long-noshort-desc}.
-\item[\abbrstyle{long-noshort-sc-desc}]
+\item[\abbrstyledef{long-noshort-sc-desc}]
Like the \abbrstyle{long-noshort-desc} style but the short form (accessed
-through commands like \ics{glsxtrshort}) use \ics{glsxtrscfont}.
+through commands like \ics{glsxtrshort}) use \ics{glsabbrvscfont}.
(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-noshort-sm-desc}]
+\item[\abbrstyledef{long-noshort-sm-desc}]
Like \abbrstyle{long-noshort-desc} but redefines \cs{glsabbrvfont} to
-use \ics{glsxtrsmfont}.
+use \ics{glsabbrvsmfont}.
(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}]
+\item[\abbrstyledef{long-noshort-em-desc}]
Like \abbrstyle{long-noshort-desc} but redefines \cs{glsabbrvfont} to
-use \ics{glsxtremfont}. The long form isn't emphasized.
+use \ics{glsabbrvemfont}. 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}]
+\item[\abbrstyledef{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
+\cs{glsabbrvfont} to use \ics{glsabbrvemfont}. The long form uses
\ics{glsfirstlongemfont} and \ics{glslongemfont}.
-\item[\abbrstyle{long-noshort}]
+\item[\abbrstyledef{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-noshort-desc} style, but the \gloskey{name}
@@ -3274,35 +3412,37 @@ and \gloskey{sort} keys are
set to the short form and the \gloskey{description} is set to the
long form.
-\item[\abbrstyle{long}] A synonym for \abbrstyle{long-noshort}
+\item[\abbrstyledef{long}] A synonym for \abbrstyle{long-noshort}
-\item[\abbrstyle{long-noshort-sc}]
+\item[\abbrstyledef{long-noshort-sc}]
Like the \abbrstyle{long-noshort} style but the short form (accessed
-through commands like \ics{glsxtrshort}) use \ics{glsxtrscfont}.
+through commands like \ics{glsxtrshort}) use \ics{glsabbrvscfont}.
(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-noshort-sm}]
+\item[\abbrstyledef{long-noshort-sm}]
Like \abbrstyle{long-noshort} but redefines \cs{glsabbrvfont} to
-use \ics{glsxtrsmfont}.
+use \ics{glsabbrvsmfont}.
(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}]
+\item[\abbrstyledef{long-noshort-em}]
This style is like \abbrstyle{long-noshort} but redefines \cs{glsabbrvfont} to
-use \ics{glsxtremfont}. The long form isn't emphasized.
+use \ics{glsabbrvemfont}. 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}]
+\item[\abbrstyledef{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
+use \ics{glsabbrvemfont}, \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}.
+The related style \abbrstyledef{long-em-noshort-em-noreg}
+doesn't set the \catattr{regular} attribute.
\end{description}
@@ -3316,7 +3456,7 @@ been set. If it hasn't already been set, it's left unset.
Other attributes may also be set, depending on the style.
\begin{description}
-\item[\abbrstyle{long-short}]
+\item[\abbrstyledef{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}
and \gloskey{sort} keys are set to the short form. (The
@@ -3327,23 +3467,39 @@ 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}]
+\item[\abbrstyledef{long-short-sc}]
Like \abbrstyle{long-short} but redefines \cs{glsabbrvfont} to
-use \ics{glsxtrscfont}.
+use \ics{glsabbrvscfont}.
-\item[\abbrstyle{long-short-sm}]
+\item[\abbrstyledef{long-short-sm}]
Like \abbrstyle{long-short} but redefines \cs{glsabbrvfont} to
-use \ics{glsxtrsmfont}.
+use \ics{glsabbrvsmfont}.
-\item[\abbrstyle{long-short-em}]
+\item[\abbrstyledef{long-short-em}]
Like \abbrstyle{long-short} but redefines \cs{glsabbrvfont} to
-use \ics{glsxtremfont}.
+use \ics{glsabbrvemfont}.
-\item[\abbrstyle{long-em-short-em}]
+\item[\abbrstyledef{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}]
+\item[\abbrstyledef{long-only-short-only}]
+New to version 1.17, this style only shows the long form
+on first use and only shows the short form on subsequent use.
+The inline full form \cs{glsxtrfull} shows the long form
+followed by the short form in parentheses.
+
+\item[\abbrstyledef{long-only-short-only-desc}]
+New to version 1.17, this style is like
+\abbrstyle{long-only-short-only} but the user must supply the
+description.
+
+\item[\abbrstyledef{long-em-noshort-em-noreg}]
+New to version 1.17, this style is like
+\abbrstyle{long-em-noshort-em} but
+doesn't set the \catattr{regular} attribute.
+
+\item[\abbrstyledef{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
@@ -3364,7 +3520,9 @@ The format is governed by
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.
+a space using \cs{glsxtrfullsep} and then the parenthetical content
+(using \ics{glsxtrparen}).
+
The \meta{text} argument includes the font formatting command,
\cs{glsfirstabbrvfont}\marg{short} in the case of the
\abbrstyle{long-short-user} style and
@@ -3404,11 +3562,19 @@ 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{\glsabbruserfont}[1]{\glsabbrvscfont{#1}}
\renewcommand{\glsxtrusersuffix}{\glsxtrscsuffix}
\end{verbatim}
-\item[\abbrstyle{long-short-desc}]
+\item[\abbrstyledef{long-noshort-noreg}]
+This style is like \abbrstyle{long-noshort} but it doesn't
+set the \catattr{regular} attribute.
+
+\item[\abbrstyledef{long-noshort-desc-noreg}]
+This style is like \abbrstyle{long-noshort-desc} but it doesn't
+set the \catattr{regular} attribute.
+
+\item[\abbrstyledef{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{sort} key is set to
@@ -3425,24 +3591,29 @@ For example:
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}]
+\item[\abbrstyledef{long-short-sc-desc}]
Like \abbrstyle{long-short-desc} but redefines \cs{glsabbrvfont} to
-use \ics{glsxtrscfont}.
+use \ics{glsabbrvscfont}.
-\item[\abbrstyle{long-short-sm-desc}]
+\item[\abbrstyledef{long-short-sm-desc}]
Like \abbrstyle{long-short-desc} but redefines \cs{glsabbrvfont} to
-use \ics{glsxtrsmfont}.
+use \ics{glsabbrvsmfont}.
-\item[\abbrstyle{long-short-em-desc}]
+\item[\abbrstyledef{long-short-em-desc}]
Like \abbrstyle{long-short-desc} but redefines \cs{glsabbrvfont} to
-use \ics{glsxtremfont}.
+use \ics{glsabbrvemfont}.
-\item[\abbrstyle{long-em-short-em-desc}]
+\item[\abbrstyledef{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[\abbrstyledef{long-em-noshort-em-desc-noreg}]
+New to version 1.17, this style is like
+\abbrstyle{long-em-noshort-em-desc} but
+doesn't set the \catattr{regular} attribute.
-\item[\abbrstyle{long-short-user-desc}]
+
+\item[\abbrstyledef{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
@@ -3452,7 +3623,11 @@ 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}]
+\item[\abbrstyledef{short-nolong-noreg}]
+This is like \abbrstyle{short-nolong} but doesn't set the
+\catattr{regular} attribute.
+
+\item[\abbrstyledef{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}
and \gloskey{sort} keys are set to the short form. The
@@ -3462,53 +3637,57 @@ 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}]
+\item[\abbrstyledef{short-sc-long}]
Like \abbrstyle{short-long} but redefines \cs{glsabbrvfont} to
-use \ics{glsxtrscfont}.
+use \ics{glsabbrvscfont}.
-\item[\abbrstyle{short-sm-long}]
+\item[\abbrstyledef{short-sm-long}]
Like \abbrstyle{short-long} but redefines \cs{glsabbrvfont} to
-use \ics{glsxtrsmfont}.
+use \ics{glsabbrvsmfont}.
-\item[\abbrstyle{short-em-long}]
+\item[\abbrstyledef{short-em-long}]
Like \abbrstyle{short-long} but redefines \cs{glsabbrvfont} to
-use \ics{glsxtremfont}.
+use \ics{glsabbrvemfont}.
-\item[\abbrstyle{short-em-long-em}]
+\item[\abbrstyledef{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}]
+\item[\abbrstyledef{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}]
+\item[\abbrstyledef{short-nolong-desc-noreg}]
+This style is like \abbrstyle{short-nolong-desc} but it doesn't
+set the \catattr{regular} attribute.
+
+\item[\abbrstyledef{short-long-desc}]
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 full form. The
\gloskey{description} must be supplied by the user.
The short and long forms are separated by \cs{glsxtrfullsep}.
-\item[\abbrstyle{short-sc-long-desc}]
+\item[\abbrstyledef{short-sc-long-desc}]
Like \abbrstyle{short-long-desc} but redefines \cs{glsabbrvfont} to
-use \ics{glsxtrscfont}.
+use \ics{glsabbrvscfont}.
-\item[\abbrstyle{short-sm-long-desc}]
+\item[\abbrstyledef{short-sm-long-desc}]
Like \abbrstyle{short-long-desc} but redefines \cs{glsabbrvfont} to
-use \ics{glsxtrsmfont}.
+use \ics{glsabbrvsmfont}.
-\item[\abbrstyle{short-em-long-desc}]
+\item[\abbrstyledef{short-em-long-desc}]
Like \abbrstyle{short-long-desc} but redefines \cs{glsabbrvfont} to
-use \ics{glsxtremfont}.
+use \ics{glsabbrvemfont}.
-\item[\abbrstyle{short-em-long-em-desc}]
+\item[\abbrstyledef{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}]
+\item[\abbrstyledef{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
@@ -3517,7 +3696,7 @@ as for \abbrstyle{short-long-user} and the \gloskey{name} key is as
supplied in the optional argument of \cs{newabbreviation}
(or \cs{newacronym}).
-\item[\abbrstyle{short-footnote}]
+\item[\abbrstyledef{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
@@ -3561,31 +3740,31 @@ 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
+\item[\abbrstyledef{footnote}] A synonym for
\abbrstyle{short-footnote}.
-\item[\abbrstyle{short-sc-footnote}]
+\item[\abbrstyledef{short-sc-footnote}]
Like \abbrstyle{short-footnote} but redefines \cs{glsabbrvfont} to
-use \ics{glsxtrscfont}.
+use \ics{glsabbrvscfont}.
(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{short-sc-footnote}]
+\item[\abbrstyledef{short-sc-footnote}]
Like \abbrstyle{short-footnote} but redefines \cs{glsabbrvfont} to
-use \ics{glsxtrsmfont}.
+use \ics{glsabbrvsmfont}.
(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}]
+\item[\abbrstyledef{short-em-footnote}]
Like \abbrstyle{short-footnote} but redefines \cs{glsabbrvfont} to
-use \ics{glsxtremfont}.
+use \ics{glsabbrvemfont}.
(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}]
+\item[\abbrstyledef{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
@@ -3600,31 +3779,31 @@ 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}] A synonym for
+\item[\abbrstyledef{postfootnote}] A synonym for
\abbrstyle{short-postfootnote}.
-\item[\abbrstyle{short-sc-postfootnote}]
+\item[\abbrstyledef{short-sc-postfootnote}]
Like \abbrstyle{short-postfootnote} but redefines \cs{glsabbrvfont} to
-use \ics{glsxtrscfont}.
+use \ics{glsabbrvscfont}.
(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{short-sm-postfootnote}]
+\item[\abbrstyledef{short-sm-postfootnote}]
Like \abbrstyle{short-postfootnote} but redefines \cs{glsabbrvfont} to
-use \ics{glsxtrsmfont}.
+use \ics{glsabbrvsmfont}.
(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{short-em-postfootnote}]
+\item[\abbrstyledef{short-em-postfootnote}]
Like \abbrstyle{short-postfootnote} but redefines \cs{glsabbrvfont} to
-use \ics{glsxtremfont}.
+use \ics{glsabbrvemfont}.
(This style was originally called \depabbrstyle{postfootnote-em}. Renamed in version
1.04, but original name retained as a deprecated synonym for
backward-compatibility.)
-\item[\abbrstyle{short-postlong-user}]
+\item[\abbrstyledef{short-postlong-user}]
This style was introduced in version 1.12. It's like the
\abbrstyle{short-long-user} style but defers the parenthetical
material to after the link-text. This means that you don't have such
@@ -3632,22 +3811,231 @@ a long hyperlink (which can cause problems for the DVI \LaTeX\ format)
and it also means that the user supplied material can include a
hyperlink to another location.
-\item[\abbrstyle{short-postlong-user-desc}]
+\item[\abbrstyledef{short-postlong-user-desc}]
This style was introduced in version 1.12. It's like the above
\abbrstyle{short-postlong-user} style but the \gloskey{description}
must be specified.
-\item[\abbrstyle{long-postshort-user}]
+\item[\abbrstyledef{long-postshort-user}]
This style was introduced in version 1.12. It's like the above
\abbrstyle{short-postlong-user} style but the long form is shown
first and the short form is in the parenthetical material (as for
\abbrstyle{long-short-user}) style.
-\item[\abbrstyle{long-postshort-user-desc}]
+\item[\abbrstyledef{long-postshort-user-desc}]
This style was introduced in version 1.12. It's like the above
\abbrstyle{long-postshort-user} style but the \gloskey{description}
must be specified.
+\item[\abbrstyledef{long-hyphen-short-hyphen}]
+This style (new to v1.17) is designed to work with the \catattr{markwords}
+category attribute. The full form is formatted using
+\begin{definition}[\DescribeMacro\glsxtrlonghyphenshort]
+\cs{glsxtrlonghyphenshort}\marg{label}\marg{long}\marg{short}\marg{insert}
+\end{definition}
+where \meta{insert} is the inserted material
+provided in the final optional argument of commands like
+\cs{insert}. If \meta{insert} start with a hyphen, then this
+locally redefines \ics{glsxtrwordsep} to a hyphen, which means that
+if the \catattr{markwords} attribute is set then the long form
+will become hyphenated. (If this attribute isn't set, there's
+no alteration to the way the long form is displayed.)
+
+Unlike the other \meta{long} (\meta{short}) type of styles,
+such as \abbrstyle{long-short}, this style
+also repeats the insertion in the parenthetical part, so that the
+first use form is:
+\begin{quote}
+\cs{glsfirstlonghyphenfont}\marg{long}\meta{insert}
+(\cs{glsfirstabbrvhyphenfont}\marg{short}\meta{insert})
+\end{quote}
+The space before the parenthetical material is actually given by
+\cs{glsxtrfullsep}\marg{label} which defaults to a space.
+The \meta{insert} may be moved into the formatting commands
+according to the conditional \cs{ifglsxtrinsertinside}.
+
+For example, if \texttt{ip} is defined using:
+\begin{verbatim}
+\glssetcategoryattribute{english}{markwords}{true}
+\setabbreviationstyle[english]{long-hyphen-short-hyphen}
+\newabbreviation[category=english]{ip}{IP}{Internet Protocol}
+\end{verbatim}
+then
+\begin{verbatim}
+\gls{ip}[-Adressen]
+\end{verbatim}
+will do
+\begin{quote}
+Internet-Protocol-Adressen (IP-Adressen)
+\end{quote}
+on first use, whereas
+\begin{verbatim}
+\gls{ip}[ Address]
+\end{verbatim}
+will do
+\begin{quote}
+Internet Protocol Address (IP Address)
+\end{quote}
+on first use.
+
+\begin{important}
+Note that the hyphenation isn't applied when using commands like
+\cs{glsxtrlong}. This means that
+\begin{verbatim}
+\glsxtrlong{ip}[-Adressen]
+\end{verbatim}
+will do
+\begin{quote}
+Internet Protocol-Adressen
+\end{quote}
+\end{important}
+
+If the \catattr{markwords} attribute hadn't been set, then the
+first use of
+\begin{verbatim}
+\gls{ip}[-Adressen]
+\end{verbatim}
+would do
+\begin{quote}
+Internet Protocol-Adressen (IP-Adressen)
+\end{quote}
+instead.
+
+\begin{important}
+If the inserted material \meta{insert} is likely to contain commands like
+\cs{gls}, then use \abbrstyle{long-hyphen-postshort-hyphen}
+instead to avoid nested links.
+\end{important}
+
+If you want the short version in small-caps, you can
+just redefine \cs{glsabbrvhyphenfont} and \cs{glsxtrhyphensuffix}
+to use the small-caps versions. For example:
+\begin{verbatim}
+\renewcommand{\glsabbrvhyphenfont}{\glsabbrvscfont}
+\renewcommand{\glsxtrhyphensuffix}{\glsxtrscsuffix}
+\end{verbatim}
+Similarly for other font-changing variations.
+
+\item[\abbrstyledef{long-hyphen-noshort-desc-noreg}]
+New to version 1.17, this style is like
+\abbrstyle{long-hyphen-short-hyphen-desc} except that the
+parenthetical part is omitted and the long form is displayed
+on subsequent use. The short form can be accessed
+with \cs{glsxtrshort} but just uses the default abbreviation font.
+There's no regular version of this style as the regular form
+doesn't have the flexibility to deal with the hyphen switch.
+
+\item[\abbrstyledef{long-hyphen-noshort-noreg}]
+New to version 1.17, this style is like
+\abbrstyle{long-hyphen-noshort-desc-noreg} but the
+name is set to the short form and the description is set to the long
+form.
+
+\item[\abbrstyledef{long-hyphen-short-hyphen-desc}]
+
+New to version 1.17.
+This is similar to \abbrstyle{long-hyphen-short-hyphen} but the user
+supplies the description.
+
+\item[\abbrstyledef{long-hyphen-postshort-hyphen}]
+
+New to version 1.17.
+This is similar to \abbrstyle{long-hyphen-short-hyphen} but the
+inserted and parenthetical material are moved to the post-link hook.
+On first use, \cs{gls}\marg{label}\oarg{insert} will do
+\begin{display}
+\cs{glsxtrlonghyphen}\marg{long}\marg{label}\marg{insert}\cs{glsxtrposthyphenshort}\marg{label}\meta{insert}
+\end{display}
+where
+\begin{definition}[\DescribeMacro\glsxtrposthyphenshort]
+\cs{glsxtrposthyphenshort}\marg{label}\meta{insert}
+\end{definition}
+is in the post-link hook. This uses the format:
+\begin{display}
+\meta{insert} (\cs{glsfirstabbrvhyphenfont}\marg{short}\meta{isnert})
+\end{display}
+
+\begin{important}
+The singular short form is always used here, even with \cs{glspl}.
+(Unlike \abbrstyle{long-hyphen-long-hyphen}.)
+\end{important}
+
+The part in the link-text on first use:
+\begin{definition}[\DescribeMacro\glsxtrlonghyphen]
+\cs{glsxtrlonghyphen}\marg{long}\marg{label}\marg{insert}
+\end{definition}
+checks if \meta{insert} starts with a hyphen. If it does, then
+\cs{glsxtrwordsep} is locally redefined to a hyphen. This command
+only uses \meta{insert} to test if it starts with a hyphen.
+The actual insertion code isn't typeset until the post-link
+hook and it's also localised, which means that you can use
+commands like \cs{gls} in \meta{insert} for this style without
+causing nested hyperlinks, but only for commands like \cs{gls}.
+
+\begin{important}
+Don't use \cs{gls} in the \meta{insert} part for commands
+like \cs{glsxtrfull}, \cs{glsxtrshort} or \cs{glsxtrlong}.
+\end{important}
+
+The inline full display format used by commands like \cs{glsxtrfull}
+behaves differently to the first use of \cs{gls} with this style.
+It's better to use \cs{glsreset}\marg{label}\cs{gls}\marg{label}
+if you want to ensure the full format.
+
+\item[\abbrstyledef{long-hyphen-postshort-hyphen-desc}]
+
+New to version 1.17.
+This is similar to \abbrstyle{long-hyphen-postshort-hyphen} but the
+user supplies the description.
+
+
+\item[\abbrstyledef{short-hyphen-long-hyphen}]
+This style (new to v1.17) is like
+\abbrstyle{long-hyphen-short-hyphen}, except that the short form
+is displayed first followed by the long form in parentheses. The full form is formatted using
+\begin{definition}[\DescribeMacro\glsxtrshorthyphenlong]
+\cs{glsxtrshorthyphenlong}\marg{label}\marg{short}\marg{long}\marg{insert}
+\end{definition}
+which behaves in an analogous way to \cs{glsxtrlonghyphenshort}.
+
+\item[\abbrstyledef{short-hyphen-long-hyphen-desc}]
+
+New to version 1.17.
+This is similar to \abbrstyle{short-hyphen-long-hyphen} but the
+user supplies the description.
+
+\item[\abbrstyledef{short-hyphen-postlong-hyphen}]
+This style (new to v1.17) is like
+\abbrstyle{long-hyphen-postshort-hyphen}, but the
+short form is displayed first followed by the long form in
+parentheses.
+On first use, \cs{gls}\marg{label}\oarg{insert} will do
+\begin{display}
+\cs{glsxtrshorthyphen}\marg{short}\marg{label}\marg{insert}\cs{glsxtrposthyphenlong}\marg{label}\meta{insert}
+\end{display}
+where
+\begin{definition}[\DescribeMacro\glsxtrposthyphenlong]
+\cs{glsxtrposthyphenlong}\marg{label}\meta{insert}
+\end{definition}
+is in the post-link hook. These commands behave in an analogous
+manner to those used with \abbrstyle{long-hyphen-postshort-hyphen}.
+
+\begin{important}
+Don't use \cs{gls} in the \meta{insert} part for commands
+like \cs{glsxtrfull}, \cs{glsxtrshort} or \cs{glsxtrlong}.
+\end{important}
+
+The inline full display format used by commands like \cs{glsxtrfull}
+behaves differently to the first use of \cs{gls} with this style.
+It's better to use \cs{glsreset}\marg{label}\cs{gls}\marg{label}
+if you want to ensure the full format.
+
+\item[\abbrstyledef{short-hyphen-postlong-hyphen-desc}]
+
+New to version 1.17.
+This is similar to \abbrstyle{short-hyphen-postlong-hyphen} but the
+user supplies the description.
+
\end{description}
\section{Defining New Abbreviation Styles}
@@ -3698,15 +4086,24 @@ For example, the \abbrstyle{long-short} style has the following in
sort={\the\glsshorttok},
first={\protect\glsfirstlongfont{\the\glslongtok}%
\protect\glsxtrfullsep{\the\glslabeltok}%
- (\protect\glsfirstabbrvfont{\the\glsshorttok})},%
+ \glsxtrparen{\protect\glsfirstabbrvfont{\the\glsshorttok}}},%
firstplural={\protect\glsfirstlongfont{\the\glslongpltok}%
\protect\glsxtrfullsep{\the\glslabeltok}%
- (\protect\glsfirstabbrvfont{\the\glsshortpltok})},%
- plural={\protect\glsabbvfont{\the\glsshortpltok}},%
+ \glsxtrparen{\protect\glsfirstabbrvfont{\the\glsshortpltok}}},%
+ plural={\protect\glsabbrvfont{\the\glsshortpltok}},%
description={\the\glslongtok}}%
\end{verbatim}
Note that the \gloskey{first} and \gloskey{firstplural} are
-set even though they're not used by \cs{gls}.
+set even though they're not used by \cs{gls}.
+
+The basic styles, such as \abbrstyle{long-short}, use commands like
+\cs{glsabbrvfont} (which are redefined whenever the style formatting
+is set) within \cs{CustomAbbreviationFields}. Other styles, such as
+\abbrstyle{long-em-short-em} directly use their own custom commands,
+such as \cs{glsabbrvemfont}. With these styles, commands like
+\cs{glsabbrvfont} still need to be defined as appropriate in the
+\meta{fmts} argument even if they're not used within
+\cs{CustomAbbreviationFields}.
The \meta{setup} argument may also redefine
\begin{definition}[\DescribeMacro\GlsXtrPostNewAbbreviation]
@@ -3762,6 +4159,21 @@ Long plural value (defined by \styfmt{glossaries-extra}):
through the \gloskey{longplural} key in the optional argument
of \ics{newabbreviation}.)
+The short or long values may be modified by attributes (such as
+\catattr{markwords}). The above registers reflect the modification.
+If you want to access the original (unmodified) short or long form
+(as provided in the final two arguments of \cs{newabbreviation}),
+then use the commands:
+\begin{definition}[\DescribeMacro\glsxtrorgshort]
+\cs{glsxtrorgshort}
+\end{definition}
+for the short form and
+\begin{definition}[\DescribeMacro\glsxtrorglong]
+\cs{glsxtrorglong}
+\end{definition}
+for the long form. (These may be useful for the \gloskey{sort} key
+to avoid any formatting that may be added by the attribute setting.)
+
There are two other registers available that are defined by
\styfmt{glossaries}:
@@ -3789,16 +4201,15 @@ 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{short-sc-footnote} and \abbrstyle{short-sm-footnote}
-styles both simply use
+For example, the \abbrstyle{long-noshort-sc-desc} style simply does
\begin{verbatim}
-\GlsXtrUseAbbrStyleSetup{short-footnote}
+\GlsXtrUseAbbrStyleSetup{long-noshort-desc}
\end{verbatim}
within \meta{setup}.
The \meta{fmts} argument deals with the way the entry is displayed
in the document. This argument should redefine the following
-commands:
+commands.
The default suffix for the plural short form (if not overridden by
the \gloskey{shortplural} key):
@@ -3886,6 +4297,32 @@ Inline plural first letter converted to upper case (used by
\cs{Glsxtrinlinefullplformat}\marg{label}\marg{insert}
\end{definition}
+(New to version 1.17.)
+You can also modify the way the subsequent use is formatted by
+redefining the following four commands, but these won't be used for
+abbreviations with the \catattr{regular} attribute set. If the style
+doesn't redefine these commands, the default values are used.
+
+Singular with no case-change:
+\begin{definition}[\DescribeMacro\glsxtrsubsequentfmt]
+\cs{glsxtrsubsequentfmt}\marg{label}\marg{insert}
+\end{definition}
+
+Singular with first letter upper case:
+\begin{definition}[\DescribeMacro\Glsxtrsubsequentfmt]
+\cs{Glsxtrsubsequentfmt}\marg{label}\marg{insert}
+\end{definition}
+
+Plural with no case-change:
+\begin{definition}[\DescribeMacro\glsxtrsubsequentplfmt]
+\cs{glsxtrsubsequentplfmt}\marg{label}\marg{insert}
+\end{definition}
+
+Plural with first letter upper case:
+\begin{definition}[\DescribeMacro\Glsxtrsubsequentplfmt]
+\cs{Glsxtrsubsequentplfmt}\marg{label}\marg{insert}
+\end{definition}
+
If you want to provide support for \sty{glossaries-accsupp}
use the following \cs{glsaccess\meta{xxx}} commands
(\sectionref{sec:accsupp}) within the definitions of
@@ -3897,26 +4334,32 @@ use the following \cs{glsaccess\meta{xxx}} commands
For example, the \abbrstyle{short-long} style has the following in
\meta{fmts}:
\begin{verbatim}
- \renewcommand*{\abbrvpluralsuffix}{\glspluralsuffix}%
+ \renewcommand*{\abbrvpluralsuffix}{\glsxtrabbrvpluralsuffix}%
\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}})%
+ \glsfirstabbrvfont{\glsaccessshort{##1}\ifglsxtrinsertinside##2\fi}%
+ \ifglsxtrinsertinside\else##2\fi
+ \glsxtrfullsep{##1}%
+ \glsxtrparen{\glsfirstlongfont{\glsaccesslong{##1}}}%
}%
\renewcommand*{\glsxtrfullplformat}[2]{%
- \glsfirstabbrvfont{\glsaccessshortpl{##1}}##2\glsxtrfullsep{##1}%
- (\glsfirstlongfont{\glsaccesslongpl{##1}})%
+ \glsfirstabbrvfont{\glsaccessshortpl{##1}\ifglsxtrinsertinside##2\fi}%
+ \ifglsxtrinsertinside\else##2\fi
+ \glsxtrfullsep{##1}%
+ \glsxtrparen{\glsfirstlongfont{\glsaccesslongpl{##1}}}%
}%
\renewcommand*{\Glsxtrfullformat}[2]{%
- \glsfirstabbrvfont{\Glsaccessshort{##1}}##2\glsxtrfullsep{##1}%
- (\glsfirstlongfont{\glsaccesslong{##1}})%
+ \glsfirstabbrvfont{\Glsaccessshort{##1}\ifglsxtrinsertinside##2\fi}%
+ \ifglsxtrinsertinside\else##2\fi\glsxtrfullsep{##1}%
+ \glsxtrparen{\glsfirstlongfont{\glsaccesslong{##1}}}%
}%
\renewcommand*{\Glsxtrfullplformat}[2]{%
- \glsfirstabbrvfont{\Glsaccessshortpl{##1}}##2\glsxtrfullsep{##1}%
- (\glsfirstlongfont{\glsaccesslongpl{##1}})%
+ \glsfirstabbrvfont{\Glsaccessshortpl{##1}\ifglsxtrinsertinside##2\fi}%
+ \ifglsxtrinsertinside\else##2\fi\glsxtrfullsep{##1}%
+ \glsxtrparen{\glsfirstlongfont{\glsaccesslongpl{##1}}}%
}%
\end{verbatim}
Since the inline full commands aren't redefined, they default
@@ -3927,34 +4370,35 @@ If you want to base a style on an existing style, you can use
\cs{GlsXtrUseAbbrStyleFmts}\marg{name}
\end{definition}
within \meta{fmts}, where \meta{name} is the name of the existing
-style. For example, the \abbrstyle{short-sc-long} style has the
+style. For example, the \abbrstyle{long-short-desc} style has the
following in \meta{fmts}:
\begin{verbatim}
- \GlsXtrUseAbbrStyleFmts{short-long}%
- \renewcommand*{\abbrvpluralsuffix}{\protect\glsxtrscsuffix}%
- \renewcommand*{\glsabbrvfont}[1]{\glsxtrscfont{##1}}%
-\end{verbatim}
-and the \abbrstyle{short-sm-long} style has:
-\begin{verbatim}
- \GlsXtrUseAbbrStyleFmts{short-long-desc}%
- \renewcommand*{\glsabbrvfont}[1]{\glsxtrsmfont{##1}}%
- \renewcommand*{\abbrvpluralsuffix}{\protect\glsxtrsmsuffix}%
+ \GlsXtrUseAbbrStyleFmts{long-short}%
\end{verbatim}
-The simplest examples of creating a new style based on an
-existing style are the \qt{em} styles, such as the
-\abbrstyle{short-em-long} style, which is defined as:
+Here's an example of an abbreviation style that's based on
+\abbrstyle{long-short} that displays the short form within
+\cs{textsf}:
\begin{verbatim}
\newabbreviationstyle
-{short-em-long}% label
+{custom-sf}% label
{% setup
\GlsXtrUseAbbrStyleSetup{short-long}%
}%
{% fmts
\GlsXtrUseAbbrStyleFmts{short-long}%
- \renewcommand*{\glsabbrvfont}[1]{\glsxtremfont{##1}}%
+ \renewcommand*{\glsabbrvfont}[1]{\textsf{##1}}%
}
\end{verbatim}
+Note that this wouldn't work if it was instead based on one of the
+modified versions such as \abbrstyle{short-sc-long} as they
+explicitly use their own formatting commands, such as
+\cs{glsabbrvemfont}. The base styles, such as \abbrstyle{short-long},
+use the more generic \cs{glsabbrvfont} etc which makes them easier
+to adapt than the modified styles.
+
+For further details, see the \qt{Abbreviations} section in the documented code
+(\texttt{glossaries-extra-code.pdf}).
\chapter{Entries in Sectioning Titles, Headers, Captions and Contents}
\label{sec:headtitle}
@@ -4200,9 +4644,9 @@ default.
Additionally, if you have enabled \ics{newterm} with the
\pkgopt{index} package option that command
will set the category to \category{index} by default. If you have
-enabled \ics{glsxtrnewsymbol} with the \pkgopt{symbols} package
+enabled \ics{glsxtrnewsymbol} with the \styopt{symbols} package
option, that command will set the category to \category{symbol}. If you have
-enabled \ics{glsxtrnewnumber} with the \pkgopt{numbers} package
+enabled \ics{glsxtrnewnumber} with the \styopt{numbers} package
option, that command will set the category to \category{number}.
You can obtain the category label for a given entry using
@@ -4238,7 +4682,7 @@ Other attributes recognised by \styfmt{glossaries-extra} are:
\begin{description}
-\item[\catattr{nohyperfirst}] When using commands like \ics{gls}
+\item[\catattrdef{nohyperfirst}] When using commands like \ics{gls}
this will automatically suppress the hyperlink on \gls{firstuse} for entries with a
category that has this attribute set to \qt{true}.
(This settings can be overridden by explicitly setting
@@ -4256,22 +4700,22 @@ want commands these \cs{glsfirst} etc commands to ignore the
\end{definition}
to do nothing.
-\item[\catattr{nohyper}] When using commands like \ics{gls}
+\item[\catattrdef{nohyper}] When using commands like \ics{gls}
this will automatically suppress the hyperlink for entries with a
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}.)
-\item[\catattr{indexonlyfirst}] This is similar to the
+\item[\catattrdef{indexonlyfirst}] This is similar to the
\pkgopt{indexonlyfirst} package option but only for entries
that have a category with this attribute set to \qt{true}.
-\item[\catattr{wrgloss}] When using commands like \ics{gls},
+\item[\catattrdef{wrgloss}] When using commands like \ics{gls},
if this attribute is set to \qt{after}, it will automatically
implement \gloskey[glslink]{wrgloss}\optfmt{=after}. (New to v1.14.)
-\item[\catattr{discardperiod}] If set to \qt{true}, the
+\item[\catattrdef{discardperiod}] If set to \qt{true}, the
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.)
@@ -4294,26 +4738,82 @@ argument. For example:
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
+\item[\catattrdef{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
\cs{glspl} or \cs{glsplural}.
-\item[\catattr{retainfirstuseperiod}] If this attribute is set
+\item[\catattrdef{retainfirstuseperiod}] If this attribute is set
to \qt{true} then the full stop won't be discarded for
\gls{firstuse} instances, even if \catattr{discardperiod} or
\catattr{pluraldiscardperiod} are set. This is useful for
\meta{short} (\meta{long}) abbreviation styles where only the short
-form has a trailing full stop..
+form has a trailing full stop.
-\item[\catattr{insertdots}] If this attribute is set to \qt{true}
+\item[\catattrdef{markwords}] If this attribute is set to \qt{true}
+any entry defined using \ics{newabbreviation} will automatically
+have spaces in the long form replaced with
+\begin{definition}[\DescribeMacro\glsxtrwordsep]
+\cs{glsxtrwordsep}
+\end{definition}
+and each word is encapsulated with
+\begin{definition}[\DescribeMacro\glsxtrword]
+\cs{glsxtrword}\marg{word}
+\end{definition}
+For example:
+\begin{verbatim}
+\glssetcategoryattribute{abbreviation}{markwords}{true}
+\newabbreviation{ip}{IP}{Internet Protocol}
+\end{verbatim}
+is essentially the same as
+\begin{verbatim}
+\newabbreviation{ip}{IP}
+{\glsxtrword{Internet}\glsxtrwordsep\glsxtrword{Protocol}}
+\end{verbatim}
+The \qt{hyphen} styles, such as
+\abbrstyle{long-hyphen-short-hyphen}, take advantage of this
+markup. If the inserted material (provided in the final argument
+of commands like \ics{gls}) starts with a hyphen then
+\cs{glsxtrwordsep} is locally redefined to a hyphen. (The default
+value is a space). Note that this only applies to commands
+like \cs{gls} and not like \cs{glsxtrlong}. You can provide your own
+localised switch, if required. For example:
+\begin{verbatim}
+\newcommand{\hyplong}[2][]{%
+ {\def\glsxtrwordsep{-}\glsxtrlong[#1]{#2}}}
+\end{verbatim}
+
+This setting will also adjust the long plural.
+
+\begin{important}
+This setting may result in the
+\cs{glsxtrword} and \cs{glsxtrwordsep} markup ending up in the
+\gloskey{sort} field, depending on the style in use.
+\end{important}
+
+\item[\catattrdef{markshortwords}] This is similar to
+\catattr{markwords} but applies to the short form. (Only useful for
+abbreviations that contain spaces.)
+
+This setting will only adjust the short plural if the
+\gloskey{shortplural} key isn't used. This setting will
+take precedence over \catattr{insertdots}.
+
+\begin{important}
+This setting may result in the
+\cs{glsxtrword} and \cs{glsxtrwordsep} markup ending up in the
+\gloskey{sort} field, depending on the style in use.
+\end{important}
+
+\item[\catattrdef{insertdots}] If this attribute is set to \qt{true}
any entry defined using \ics{newabbreviation} will automatically
have full stops (periods) inserted after each letter. The entry will
be defined with those dots present as though they had been present
in the \meta{short} argument of \cs{newabbreviation} (rather than
inserting them every time the entry is used). The short plural
form defaults to the new dotted version of the original \meta{short}
-form with the plural suffix appended.
+form with the plural suffix appended. \emph{This setting is incompatible
+with \catattr{markshortwords}.}
\begin{important}
If you explicitly override
@@ -4326,29 +4826,29 @@ followed by a dot).
This attribute is best used with the \catattr{discardperiod}
attribute set to \qt{true}.
-\item[\catattr{aposplural}] If this attribute is set to \qt{true},
+\item[\catattrdef{aposplural}] If this attribute is set to \qt{true},
\ics{newabbreviation} will insert an apostrophe (') before
the plural suffix for the \emph{short} plural form (unless explicitly
overridden with the \gloskey{shortplural} key). The long plural form
-is unaffected by this setting.
+is unaffected by this setting. This setting overrides
+\catattr{noshortplural}.
-\item[\catattr{noshortplural}] If this attribute is set to
+\item[\catattrdef{noshortplural}] If this attribute is set to
\qt{true}, \ics{newabbreviation} won't append the plural suffix for
the short plural form. This means the \gloskey{short} and
\gloskey{shortplural} values will be the same unless explicitly
-overridden. \emph{The \catattr{aposplural} attribute trumps
-the \catattr{noshortplural} attribute.}
+overridden. \emph{This setting is incompatible with \catattr{aposplural}.}
-\item[\catattr{headuc}] If this attribute is set to \qt{true},
+\item[\catattrdef{headuc}] If this attribute is set to \qt{true},
commands like \ics{glsfmtshort} will use the upper case version
in the page headers.
-\item[\catattr{tagging}] If this attribute is set to \qt{true},
+\item[\catattrdef{tagging}] If this attribute is set to \qt{true},
the tagging command defined by \ics{GlsXtrEnableInitialTagging}
will be activated to use \ics{glsxtrtagfont} in the glossary
(see \sectionref{sec:tagging}).
-\item[\catattr{entrycount}] Unlike the above attributes,
+\item[\catattrdef{entrycount}] Unlike the above attributes,
this attribute isn't boolean but instead must be an integer
value and is used in combination with \ics{glsenableentrycount}
(see \sectionref{sec:entrycountmods}). Leave blank or undefined
@@ -4363,7 +4863,7 @@ have the \catattr{entrycount} attribute set and
where the previous usage count for that entry is less than or
equal to the value of that attribute.
-\item[\catattr{glossdesc}] The \ics{glossentrydesc} command
+\item[\catattrdef{glossdesc}] The \ics{glossentrydesc} command
(used in the predefined glossary styles) is modified by
\styfmt{glossaries-extra} to check for this attribute.
The attribute may have one of the following values:
@@ -4393,7 +4893,7 @@ 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)
+\item[\catattrdef{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
@@ -4404,16 +4904,16 @@ text. For example:
\end{verbatim}
-\item[\catattr{glossname}] As \catattr{glossdesc} but applies
+\item[\catattrdef{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.
-\item[\catattr{indexname}] If set, the \cs{glsxtrpostnamehook} hook
+\item[\catattrdef{indexname}] If set, the \cs{glsxtrpostnamehook} hook
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)
+\item[\catattrdef{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
@@ -4429,13 +4929,13 @@ 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
+\item[\catattrdef{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
line will be written to the indexing file using \ics{index}. See
\sectionref{sec:autoindex} for further details.
-\item[\catattr{targeturl}] If set, the hyperlink generated by
+\item[\catattrdef{targeturl}] If set, the hyperlink generated by
commands like \cs{gls} will be set to the URL provided by this
attributes value. For example:
\begin{verbatim}
@@ -4667,7 +5167,8 @@ commands like \ics{cgls} will generate a warning if
\cs{glsenableentrycount} hasn't been used.) The abbreviation
shortcut \ics{ab} uses \cs{cgls} (see
\sectionref{sec:abbrshortcuts}) unlike the acronym shortcut \ics{ac}
-which uses \cs{gls}.
+which uses \cs{gls} (except when it's defined through
+\styopt[ac]{shortcuts}).
All upper case versions (not provided by \styfmt{glossaries}) are
also available:
@@ -5168,12 +5669,12 @@ The \styfmt{glossaries} package advises against defining entries
in the \env{document} environment. As mentioned in
\sectionref{sec:pkgopts} above, this ability is disabled by
default with \styfmt{glossaries-extra} but can be enabled using
-the \pkgopt{docdefs} package options.
+the \styopt{docdefs} package options.
Although this can be problematic, the \styfmt{glossaries-extra}
package provides a way of defining and using entries within
the \env{document} environment without the tricks used with the
-\pkgopt{docdefs} option. \emph{There are limitations with this
+\styopt{docdefs} option. \emph{There are limitations with this
approach, so take care with it.} This function is disabled by
default, but can be enabled using the preamble-only command:
\begin{definition}[\DescribeMacro\GlsXtrEnableOnTheFly]
@@ -5272,7 +5773,8 @@ to just text.
\label{sec:bib2gls}
There is a new command line application under development called
-\gls{bib2gls}, which works in much the same way as \appfmt{bibtex}.
+\gls{bib2gls}, which works in much the same way as
+a combination of \appfmt{bibtex} and \appfmt{makeindex}.
Instead of storing all your entry definitions in a \texttt{.tex} and
loading them using \cs{input} or \cs{loadglsentries}, the entries
can instead be stored in a \texttt{.bib} file and \gls{bib2gls} can
@@ -5288,10 +5790,10 @@ hundreds of definitions, but you only use a dozen or so in your
document, then the build time is needlessly slowed by the unrequired
definitions that occur when the file is input.
-Although \gls{bib2gls} isn't ready yet, there have been some new
-commands and options added to \styfmt{glossaries-extra} to help
-assist the integration of \gls{bib2gls} into the document build
-process.
+Although \gls{bib2gls} isn't ready yet (at the time of writing
+this), there have been some new commands and options added to
+\styfmt{glossaries-extra} to help assist the integration of
+\gls{bib2gls} into the document build process.
An example of the contents of \texttt{.bib} file that stores
glossary entries that can be extracted with \gls{bib2gls}:
@@ -5362,7 +5864,7 @@ preamble{"\providecommand{\mtx}[1]{\boldsymbol{#1}}"}
\end{verbatim}
To ensure that \gls{bib2gls} can find out which entries have been
-used in the document, you need the \pkgopt{record} package. Option:
+used in the document, you need the \styopt{record} package option:
\begin{verbatim}
\usepackage[record]{glossaries-extra}
\end{verbatim}
@@ -5372,9 +5874,9 @@ collate the locations.
If you still want to use an indexing application (for example, you
need a custom \gls{xindy} rule), then just use
-\pkgopt[alsoindex]{record} and continue to use \cs{makeglossaries}
-and \cs{printglossary} (or \cs{printglossaries}), but instruct
-\gls{bib2gls} to omit sorting to save time.
+\styopt[alsoindex]{record} and continue to use \cs{makeglossaries}
+and \cs{printglossary} (or \cs{printglossaries}), but it's a good
+idea to also instruct \gls{bib2gls} to omit sorting to save time.
The \texttt{.glstex} file created by \cs{bib2gls} is loaded using:
\begin{definition}[\DescribeMacro\glsxtrresourcefile]
@@ -5418,12 +5920,28 @@ as the name of the \texttt{.bib} files and any changes to the
default behaviour.
Since the \texttt{.glstex} won't exist on the first \LaTeX\ run, the
-\pkgopt{record} package option additionally switches on
-\pkgopt[warn]{undefaction}. Any use of commands like \cs{gls} or
+\styopt{record} package option additionally switches on
+\styopt[warn]{undefaction}. Any use of commands like \cs{gls} or
\cs{glstext} will produce ?? in the document, since they are
undefined at this point. Once \gls{bib2gls} has created the
\texttt{.glstex} file the references should be resolved.
+\begin{important}
+Note that \cs{glsaddall} doesn't work with \gls{bib2gls} as the command
+has to iterate over the glossary lists, which will be empty on the first
+run and on subsequent runs will only contain those entries that have
+been selected by \gls{bib2gls}.
+\end{important}
+
+If you want to add all
+entries to the glossary, you need to tell \gls{bib2gls} this in the
+options list. For example:
+\begin{verbatim}
+\GlsXtrLoadResources[src={terms},selection={all}]
+\end{verbatim}
+See the \gls{bib2gls} user manual for more details of this and other
+available options.
+
Note that as from v1.12, \cs{glsxtrresourcefile} temporarily
switches the category code of \texttt{@} to 11 (letter) while it
reads the file to allow for any internal commands stored in the
@@ -5515,17 +6033,6 @@ locale. If this doesn't match the document language, you need to
set this in the option list, for example \verb|sort=de-CH-1996|
for Swiss German using the new orthography.)
-Note that \cs{glsaddall} doesn't work in this case as it has to
-iterate over the glossary lists, which will be empty on the first
-run and on subsequent runs will only contain those entries that have
-been selected by \gls{bib2gls}. Instead, if you want to add all
-entries to the glossary, you need to tell \gls{bib2gls} this in the
-options list:
-\begin{verbatim}
-\GlsXtrLoadResources[src={terms},selection={all}]
-\end{verbatim}
-
-The \gls{bib2gls} user manual will contain more detail.
\chapter{Miscellaneous New Commands}
\label{sec:miscnew}
@@ -5712,7 +6219,7 @@ assignment code.
This command just uses \ics{glsdoifexists}\marg{label}\marg{code}
(ignoring the \meta{field} argument), so by default it causes an
error if the entry doesn't exist. This can be changed to a warning
-with \pkgopt[warn]{undefaction}. You can redefine
+with \styopt[warn]{undefaction}. You can redefine
\cs{glsxtrsetfieldifexists} to simply do \meta{code} if you want to
skip the existence check. Alternatively you can instead use
\begin{definition}[\DescribeMacro\glsxtrdeffield]
@@ -5826,7 +6333,7 @@ See the \sty{etoolbox}'s user manual for further
details of these commands, in particular the limitations
of \cs{ifinlist}.
-When using the \pkgopt{record} option, in addition to recording the
+When using the \styopt{record} option, in addition to recording the
usual location, you can also record the current value
of another counter at the same time using the preamble-only command:
\begin{definition}[\DescribeMacro\GlsXtrRecordCounter]
@@ -5870,7 +6377,7 @@ entries and always lists all the defined entries for the given
glossary (and doesn't require \cs{makenoidxglossaries}).
There's also a starred form
-\begin{definition}[\DescribeMacro\printunsrtglossary*]
+\begin{definition}[\DescribeMacro{\printunsrtglossary*}]
\cs{printunsrtglossary}*\oarg{options}\marg{code}
\end{definition}
which is equivalent to
@@ -5888,11 +6395,18 @@ there will be no \gls{numberlist} in this case, as that has to be
set by a post-processor such as \gls{bib2gls} (see
\sectionref{sec:bib2gls}).
+\begin{important}
+No attempt is made to gather hierarchical elements.
+If child entries aren't defined immediately after their parent
+entry, they won't be together in the glossary when using
+\cs{printunsrtglossary}.
+\end{important}
+
If you have any entries with the \gloskey{see} key set, you will
need the \sty{glossaries} package option \pkgopt[ignore]{seenoindex}
or \pkgopt[warn]{seenoindex} to prevent an error occurring from the
automated \cs{glssee} normally triggered by this key. The
-\pkgopt[only]{record} package option will automatically deal with
+\styopt[only]{record} package option will automatically deal with
this.
For example:
@@ -5913,7 +6427,7 @@ For example:
In the above, zebra will be listed before ant as it was defined
first.
-If you allow document definitions with the \pkgopt{docdefs} option,
+If you allow document definitions with the \styopt{docdefs} option,
the document will require a second \LaTeX\ run if the entries are
defined after \cs{printunsrtglossary}.
@@ -6047,7 +6561,7 @@ which will start the list with a subsection header with the
title \qt{Summary} (overriding the glossary's title).
Note that this shortcut command is only available with the
-\pkgopt{record} (or \pkgopt[alsoindex]{record}) package option.
+\styopt{record} (or \styopt[alsoindex]{record}) package option.
This temporary change in the hypertarget prefix means you
need to explicitly use \cs{hyperlink} to create a link to it
@@ -6080,7 +6594,7 @@ was defined, the \gloskey{alias} key will automatically trigger
\cs{gls}\marg{entry-1} will link to \meta{entry-2}'s target. (Unless
the \catattr{targeturl} attribute has been set for \meta{entry-1}'s
category.)
-\item With \pkgopt[off]{record} or \pkgopt[alsoindex]{record}, the \gloskey[glslink]{noindex} setting will automatically be triggered
+\item With \styopt[off]{record} or \styopt[alsoindex]{record}, the \gloskey[glslink]{noindex} setting will automatically be triggered
when referencing \meta{entry-1} with commands like \cs{gls} or
\cs{glstext}. This prevents \meta{entry-1} from have a
\gls{locationlist} (aside from the cross-reference added with
@@ -6088,7 +6602,7 @@ when referencing \meta{entry-1} with commands like \cs{gls} or
if the indexing has been explicitly set using
\texttt{noindex=false}.
-Note that with \pkgopt[only]{record}, the \gls{locationlist}
+Note that with \styopt[only]{record}, the \gls{locationlist}
for aliased entries is controlled with \gls{bib2gls}['s] settings.
\end{itemize}
@@ -6098,7 +6612,7 @@ The index suppression trigger is performed by
\end{definition}
This is performed after the default options provided by
\ics{GlsXtrSetDefaultGlsOpts} have been set.
-With \pkgopt[only]{record}, \cs{glsxtrsetaliasnoindex} will
+With \styopt[only]{record}, \cs{glsxtrsetaliasnoindex} will
default to do nothing.
Within the definition of \cs{glsxtrsetaliasnoindex} you can use
@@ -6161,7 +6675,7 @@ Next use: \pgls{svm}.
\label{sec:accsupp}
The \sty{glossaries-accsupp} needs to be loaded before
-\styfmt{glossaries-extra} or through the \pkgopt{accsupp} package
+\styfmt{glossaries-extra} or through the \styopt{accsupp} package
option:
\begin{verbatim}
\usepackage[accsupp]{glossaries-extra}
@@ -6361,6 +6875,9 @@ The following sample files are provided with this package:
\item[sample.tex] Simple sample file that uses one of the dummy
files provided by the \styfmt{glossaries} package for testing.
+\item[sample-abbr-styles.tex] Demonstrates all predefined
+abbreviation styles.
+
\item[sample-mixture.tex] General entries, acronyms and initialisms
all treated differently.
@@ -6485,7 +7002,7 @@ in the supplementary file \texttt{sample-suppl-hyp.tex}.
There's only one command provided by \styfmt{glossaries-extra}
that you're likely to want to change in your document and that's
\ics{abbreviationsname} (\sectionref{sec:pkgopts}) if you use
-the \pkgopt{abbreviations} package option to automatically
+the \styopt{abbreviations} package option to automatically
create the glossary labelled \texttt{abbreviations}. If this
command doesn't already exist, it will be defined to
\qt{Abbreviations} if \sty{babel} hasn't been loaded, otherwise