From 0dd6631d97c3dfb673037310f137101006db1151 Mon Sep 17 00:00:00 2001
From: Karl Berry
glossaries-extra.sty v1.30: an extension to the
+class="cmr-17">glossaries-extra.sty v1.31: an extension to the
glossaries package
2018-04-25
The The glossaries package is a flexible package, but it’s also a heavy-weight package
that uses a lot of resources. As package developer, I’m caught between those users
who complain about the drawbacks of a heavy-weight package with a large user
manual and those users who want more features (which necessarily adds to the
package weight and manual size).
- The The glossaries-extra package is an attempt to provide a compromise for this
conflict. Version 4.22 of the glossaries package is the last version to incorporate new
@@ -476,10 +485,10 @@ of package loading time and allocation of resources, but those users who do want
extra features available will have more of a chance of getting their feature requests
accepted.
I’m not happy with some of the default settings assumed by the I’m not happy with some of the default settings assumed by the glossaries package,
and, judging from code I’ve seen, other users also seem unhappy with them, as
certain package options are often used in questions posted on various sites. I can’t
@@ -489,7 +498,7 @@ but since glossaries-extra is a separate package, I have decided to implement some of
these commonly-used options by default. You can switch them back if they’re not
appropriate.
- The new defaults are: The new defaults are: The examples below illustrate the difference in explicit package options between
+ The examples below illustrate the difference in explicit package options between
glossaries and glossaries-extra. There may be other differences resulting from
@@ -569,7 +578,7 @@ href="#sec:modifications">§2
+
1.1 Package Defaults
-
\usepackage{glossaries-extra}
This is like: +
This is like: @@ -590,7 +599,7 @@ Commands and Styles
).+
This is like: +
This is like:
@@ -613,7 +622,7 @@ Commands and Styles).
\usepackage[toc,nopostdot,translate=babel]{glossaries}
\usepackage{glossaries-extra}
-
+
This is like: +
This is like:
@@ -634,7 +643,7 @@ Commands and Styles).
\usepackage[toc,nopostdot,noredefwarn]{glossaries}
\usepackage{glossaries-extra}
-
However
@@ -645,7 +654,7 @@ class="cmti-10">However
\usepackage{glossaries}
\usepackage{glossaries-extra}
-
This is like: +
This is like:
@@ -655,19 +664,19 @@ class="cmti-10">However
\usepackage[toc,nopostdot]{glossaries}
\usepackage{glossaries-extra}
-
Since by the time Since by the time glossaries-extra has been loaded, glossaries has already
redefined memoir’s glossary-related commands.
Another noticeable change is that by default Another noticeable change is that by default \printglossary will now display
information text in the document if the external glossary file doesn’t exist. This is
explanatory text to help new users who can’t work out what to do next to complete
the document build. Once the document is set up correctly and the external files have
been generated, this text will disappear.
- This change is mostly likely to be noticed by users with one or more
+ This change is mostly likely to be noticed by users with one or more
redundant empty glossaries who ignore transcript messages, explicitly use
\printglossaries
The above document will only display the list of acronyms at the place where
+ The above document will only display the list of acronyms at the place where
\printglossaries occurs. However it will also attempt to input the .gls file
associated with the main glossary.
- If you use If you use makeglossaries, you’ll get the warning message:
@@ -718,7 +727,7 @@ Warning: File 'test.glo' is empty.
(where the original file is called (where the original file is called test.tex) but if you simply call
No file test.gls.
- This doesn’t occur with This doesn’t occur with makeglossaries as it will create the .gls file containing
the single command \null.
- If you simply change from If you simply change from glossaries to glossaries-extra in this document, you’ll
find a change in the resulting PDF if you don’t use .acr The transcript file will still contain the message about the missing The transcript file will still contain the message about the missing .gls, but now
you’ll also see information in the actual PDF document. The simplest remedy is to
follow the advice inserted into the document at that point, which is to add the
@@ -776,19 +785,19 @@ class="cmss-10">nomain (Note the need to set the acronym style using (Note the need to set the acronym style using \setabbreviationstyle before
\newacronym. See §3 Abbreviations for further details.)
-
+
If you haven’t already loaded If you haven’t already loaded glossaries, you can use any of the package options
provided by glossaries when you load \setupglossariesglossaries
- The new and modified options provided by
+ The new and modified options provided by glossaries-extra are described
below:
@@ -838,7 +847,7 @@ class="cmss-10">glossaries The The glossaries-extra package extends this option to provide the additional
values debug=all.
- The The debug=showwrglossdebug=true and uses
-
+
to show a mark ⋅ just before the write operation performed by the
indexing commands. If you use makeindex The value may also be one of the following keywords:
+ The value may also be one of the following keywords:
+
+
The default definition is
+ The default definition is
@@ -982,7 +991,7 @@ class="cmss-10">=none where the conditional is determined by the where the conditional is determined by the nopostdot package option.
@@ -1000,7 +1009,7 @@ class="cmss-10">postdot The The glossaries-extra-stylemods package adjusts the predefined styles
that had a hard-coded \hfil:
\usepackage[postpunc=comma,stylemods]{glossaries-extra}
Be careful with doing this as it will look odd if the Be careful with doing this as it will look odd if the number list is missing.
(With accsupp If you want to define styles that can interface with the accessibility support
+ If you want to define styles that can interface with the accessibility support
provided by glossaries-accsupp use the §11.2 Note that the Note that the accsupp option can only be used as a package option (not
@@ -1136,7 +1145,7 @@ href="#styopt.undefaction">undefaction
+
Note that Note that bib2gls\glsxtrusesee
and \glsxtruseseealso) but cross-reference won’t be automatically
indexed.
- Note that the Note that the record=onlyautoseeindex=false.
- For example, if an entry is defined as
+ For example, if an entry is defined as
@@ -1227,7 +1236,7 @@ class="cmss-10">=false
\newglossaryentry{foo}{name={foo},description={},see={bar,baz}}
then with then with autoseeindex=true, this is equivalent to
@@ -1239,7 +1248,7 @@ class="cmtt-10">autoseeindex=true but with but with autoseeindex=false, this is equivalent to
@@ -1249,7 +1258,7 @@ class="cmtt-10">autoseeindex=false Note that Note that indexcrossrefs isn’t automatically implemented by the presence of the
@@ -1259,9 +1268,9 @@ class="cmss-10">see
\end{document}
-
Remember to use package option 'nomain' if you
don't want to use the main glossary.
-
\end{document}
-1.2 New or Modified Package Options
-
-
}
-
\renewcommand{\glsxtrprelocation}{\hfil}
-
\glossariesextrasetup{indexcrossrefs=true}
\GlsXtrSetField{foo}{see}{bar,baz}
\GlsXtrSetField{foo}{see}{bar,baz}
-
It’s therefore possible to remove the cross-references from the location lists and +
It’s therefore possible to remove the cross-references from the location lists and set their position within the glossary style. -
Another method of preventing the automatic indexing is to define the entries +
Another method of preventing the automatic indexing is to define the entries before the external indexing files have been opened with \makeglossaries. Since the appropriate file isn’t open, the information can’t be written to it. @@ -1285,7 +1294,7 @@ class="cmtt-10">bib2gls§9 bib2gls: Managing Reference Databases). -
The option may only be set in the preamble and can’t be used after +
The option may only be set in the preamble and can’t be used after \GlsXtrLoadResources. If the value is missing glossaries-extra-bib2glsglossaries-extra-bib2gls.) -
The glossaries should be displayed using The glossaries should be displayed using \printunsrtglossary (or
\printunsrtglossaries).
- The document build process is (assuming the file is called The document build process is (assuming the file is called myDoc.tex):
@@ -1345,8 +1354,8 @@ class="cmtt-10">myDoc.tex
-
bib2gls myDoc
pdflatex myDoc
-
The The record=onlybib2gls--log-file or -t
option.)
- The glossaries should be displayed using The glossaries should be displayed using \printglossary (or
\printglossaries). This option is expected to be used with sort=none The document build process is (assuming the file is called The document build process is (assuming the file is called myDoc.tex):
@@ -1443,8 +1452,8 @@ class="cmtt-10">myDoc.tex With the recording on (
+ With the recording on (record=onlycounter=wrglossary.
-
- By default (with
+
+ By default (with hyperref), the page numbers in makeindex Since Since bib2gls--no-merge-wrglossary-records
each linking to the corresponding place on that page. In both cases,
consecutive pages can form ranges, but it may look strange in the second
case.
- See the See the bib2gls documentation for the \newglossaryentry. (For example, when the glossary is dis
class="E">EX run has drawbacks that are detailed in the glossaries user
manual.
- Remember that if Remember that if \newglossaryentry wouldn’t be allowed in the
document\newglossaryentry With this option, if an entry appears in the glossary before it has been
+ With this option, if an entry appears in the glossary before it has been
defined, an error will occur (or a warning if the undefaction.aux and .gls files).
The The glossaries package allows \newglossaryentry within the document=true This option affects commands that internally use This option affects commands that internally use \newglossaryentry, such as
\newabbreviation, but not the “on-the-fly” commands described in abbreviations
+
which is equivalent to
+
If this command is already defined, it’s left unchanged. Otherwise it’s defined
to “Abbreviations” if babelMulti-Lingual Support for furth
-
- If the
+ If the abbreviations option is used and the main:
- Note that there are no analogous options to the
+ Note that there are no analogous options to the glossaries package’s acronymlistssymbols
+
which is equivalent to
+
which is equivalent to Note that multiple invocations of the Note that multiple invocations of the shortcuts option within the same option
list will override each other. After the After the glossaries-extra package has been loaded, you can set available options
using
-
+ The The glossaries package provides \nopostdesc which may be used in the descriptionglossaries-extra
+
which has a similar function but only suppresses the post-description punctuation. It
doesn’t suppress the use of \glsxtrpostdescription which allows the use of
@@ -2167,12 +2176,12 @@ class="cmtt-10">\glsxtrpostdescription
+
These commands have no effect outside of the glossary (except with standalone
entries that use \glsxtractivatenopost and §10.3
Standalone Entry Items).
- The The glossaries package provides
-
+
to format items in a cross-reference list (identified with the see key or \ifglshasshort{\glslabel}{\glsaccesstext{#1}}{\glsaccessname{#1}}%
If you want to restore the If you want to restore the glossaries v3.0+ definition just do:
@@ -2238,8 +2247,8 @@ class="cmss-10">glossaries
- The commands used by
+ The commands used by glossaries to automatically produce an error if an entry is
undefined (such as \glsdoifexistsundefaction option into
account.
- The The \newignoredglossary{⟨Categories for furt
check that the glossary doesn’t already exist. (The glossaries package omits this
check.)
- You can now provide an ignored glossary with:
- You can now provide an ignored glossary with:
+
+
which will only define the glossary if it doesn’t already exist. This also has a starred
version that doesn’t automatically switch off hyperlinks.
- The individual glossary displaying commands The individual glossary displaying commands \printglossary, \printnoidxglossary} The \gls).
+
+ The \newglossaryentry command has three new keys: The test file The test file example-glossaries-xr.tex contains dummy entries with a mixture of
see, , alias and and seealso keys for use with minimal working examples. There are also
+ id="dx1-5029"> keys for use with minimal working examples. There are also
example-glossaries-*.bib files that correspond to each example-glossaries-*.tex
file for testing bib2gls.
- The .
+ The \longnewglossaryentry command now has a starred version (as from v1.12)
that doesn’t automatically insert
@@ -2365,11 +2389,11 @@ that doesn’t automatically insert
at the end of the description field.
- at the end of the description field.
+
+
The descriptionplural key is left unset unless explicitly set in ⟨ key is left unset unless explicitly set in ⟨options⟩.
- The unstarred version no longer hard-codes the above code (which removes
+ The unstarred version no longer hard-codes the above code (which removes
trailing space and suppresses the post-description hook) but instead uses:
-
+
This can be redefined to allow the post-description hook to work but retain the
\unskip part if required. For example:
@@ -2402,57 +2426,57 @@ class="cmtt-10">\unskip This will discarded unwanted trailing space at the end of the description but won’t
+ This will discarded unwanted trailing space at the end of the description but won’t
suppress the post-description hook.
- The unstarred version also alters the base The unstarred version also alters the base glossaries package’s treatment of the
+ id="dx1-5035"> package’s treatment of the
descriptionplural key. Since a plural description doesn’t make much sense for
+ id="dx1-5036"> key. Since a plural description doesn’t make much sense for
multi-paragraph descriptions, the default behaviour with glossaries-extra’s
+ id="dx1-5037">’s
\longnewglossaryentry is to simply leave the plural description unset
unless explicitly set using the descriptionplural key. The key. The glossaries.sty version
of this command sets the description’s plural form to the same as the
singular.2.1
- Note that this modified unstarred version doesn’t append
+ Note that this modified unstarred version doesn’t append \glsxtrpostlongdescription
to the description’s plural form.
- The The \newterm command (defined through the command (defined through the index package option) is modified
+ id="dx1-5046"> package option) is modified
so that the category defaults to index. The . The \newacronym command is modified
+ id="dx1-5048"> command is modified
to use the new abbreviation interface provided by glossaries-extra. (See §3
Abbreviations.)
- The The \makeglossaries command now has an optional argument.
-
+
If ⟨list⟩ is empty, \makeglossaries behaves as per its original definition in the
@@ -2460,44 +2484,44 @@ class="cmtt-10">\makeglossaries This command is not permitted with the This command is not permitted with the record=only package option. Without
+ id="dx1-5050"> It should then be possible to use .
+ It should then be possible to use \printglossary for those glossaries listed in ⟨list⟩
and \printnoidxglossary for the other glossaries. (See the accompanying file
sample-mixedsort.tex for an example.)
-
-
+ You will need at least version 2.20 of makeglossaries or at least version 1.3 of
the Lua alternative makeglossaries-lite (both distributed with (both distributed with glossaries v4.27) to
allow for this use of \makeglossaries[⟨list⟩]. Alternatively, use the automake
+ id="dx1-5057">
option.
The As from version 1.31, there is a new command like \glsadd where the mandatory
+argument is a comma-separated list of labels:
+
+
+
+
+This simply iterates over ⟨list⟩ and does \glsadd[⟨options⟩]{⟨label⟩} for each entry in the
+list.
+ The glossaries-extra package provides extra keys for commands like \gls and
\glstext:
-
-
-
The default value is set up using
- The default value is set up using
+
+
which is defined as:
@@ -2597,31 +2642,31 @@ class="cmtt-10">\glsxtrinitwrgloss This sets the conditional
- This sets the conditional
+
+
which is used to determine where to perform the indexing.
- This means you can set the This means you can set the wrgloss attribute to will set will set hyperoutside=false for all entries that are assigned to the category
mathrelation and
@@ -2687,7 +2732,7 @@ class="cmtt-10">mathrelation will use will use \mathrel instead of \glstextformat resulting in: There is a new hook that’s used each time indexing information is written to the
+ There is a new hook that’s used each time indexing information is written to the
external glossary files:
-
+
where ⟨label⟩ is the entry’s label. This does nothing by default but may be redefined.
(See, for example, the accompanying sample file sample-indexhook.tex, which uses
this hook to determine which entries haven’t been indexed.)
- There’s also a new hook (from v1.26) that’s used immediately before the options
+ There’s also a new hook (from v1.26) that’s used immediately before the options
are set by the \gls-like and \glstext-like commands:
-
+
(The base package provides \glslinkpostsetkeys that’s used immediately after the
+ id="dx1-6028"> that’s used immediately after the
options are set.)
- As from version 1.30 there are also similar hooks for As from version 1.30 there are also similar hooks for \glsadd:
-
+
and
-
+
For example, to default to using the equation counter in maths mode:
+ id="dx1-6031"> counter in maths mode:
@@ -2783,9 +2836,9 @@ class="cmss-10">equation (This can be overridden with an explicit use of (This can be overridden with an explicit use of counter in the optional argument
+ id="dx1-6032"> in the optional argument
of \gls or \glsadd.) Alternatively, to enforce this (overriding the option
@@ -2800,43 +2853,43 @@ argument):
- As from version 1.14, there are two new keys for
+ As from version 1.14, there are two new keys for \glsadd: thevalue and and theHvalue.
+ id="dx1-6034">.
These keys are designed for manually adding explicit locations rather than obtaining
the value from the associated counter. As from version 1.19, these two keys are also
available for commands like \gls and \glslink. The thevalue keys is intended
+ id="dx1-6035"> keys is intended
primarily for adding locations in supplementary material that can’t be obtained from
a counter.
- The principle key The principle key thevalue is for the location value. The other key is for the location value. The other key theHvalue can
+ id="dx1-6037"> can
be used to extract a prefix value for the first argument of commands like
\glsnoidxdisplayloc. It’s value must be in the format ⟨. It’s value must be in the format ⟨prefix⟩⟨location⟩. In general,
there’s little need for this key as the prefix is typically associated with a counter that
can be used to form hypertargets.
-
- For example,
+ For example, makeindex will only accept locations in the form [⟨ will only accept locations in the form [⟨num⟩⟨sep⟩]*⟨num⟩
@@ -2849,7 +2902,7 @@ instances of a number followed by the recognised separator character (set
with \glsSetCompositor). This means that makeindex won’t accept, for
+ id="dx1-6041"> won’t accept, for
example,
@@ -2858,23 +2911,23 @@ example,
This location value will be accepted by This location value will be accepted by bib2gls For example, suppose the file For example, suppose the file suppl.tex contains:
@@ -2891,10 +2944,10 @@ class="cmtt-10">suppl.tex This has an entry on page S.2. Suppose another document wants to include this
+ This has an entry on page S.2. Suppose another document wants to include this
location in the glossary. Then this can be done by setting thevalue to to S.2. For
example:
@@ -2912,17 +2965,17 @@ example:
This location value will be accepted by This location value will be accepted by makeindex as it’s in the form ⟨ as it’s in the form ⟨num⟩⟨sep⟩⟨num⟩.
- If you want hyperlinks, things are more complicated. First you need to set the
+ If you want hyperlinks, things are more complicated. First you need to set the
externallocation to the location of the PDF file. For example:
+ id="dx1-6049"> to the location of the PDF file. For example:
@@ -2932,7 +2985,7 @@ class="cmss-10">externallocation Next you need to add Next you need to add glsxtrsupphypernumber as the format:
@@ -2941,30 +2994,30 @@ class="cmtt-10">glsxtrsupphypernumber Both documents will need to use the Both documents will need to use the hyperref package. Remember that the counter
+ id="dx1-6050"> package. Remember that the counter
used for the location also needs to match. If \theH⟨counter⟩ is defined in the other
document and doesn’t match in the referencing document, then you need to use
theHvalue to set the appropriate value. See the accompanying sample files
+ id="dx1-6051"> to set the appropriate value. See the accompanying sample files
sample-suppl-hyp.tex and sample-suppl-main-hyp.tex for an example that uses
hyperref.
-
- For example, if both
+ For example, if both sample-suppl-hyp.pdf and sample-suppl-main-hyp.pdf
are in the same directory, then viewing sample-suppl-main-hyp.pdf in Evince will
take you to the correct location in the linked document (when you click on the S.2
external link), but Okular will take you to the top of the first page of the linked
document.
-
+
The value of the The value of the see key is now saved as a field. This isn’t the case with glossaries,
@@ -3004,20 +3057,20 @@ class="cmss-10">document This modification allows This modification allows glossaries-extra to provide
-
+
which is used at the end of the document to automatically add any unused
cross-references unless the package option indexcrossrefs was set to false.
- As a by-product of this enhancement, the As a by-product of this enhancement, the see key will now work for entries
defined in the see
value to be stored even though it may not be possible to index it at that
point.
- As from version 1.06, you can display the cross-referenced information for a given
+ As from version 1.06, you can display the cross-referenced information for a given
entry using
-
+
This internally uses
-
+
where ⟨tag⟩ and ⟨xr list⟩ are obtained from the value of the entry’s see field hasn’t been set for the entry given by
⟨label⟩.
- Suppose you want to suppress the Suppose you want to suppress the number list using nonumberlistsee Another approach in this situation is to use the post description hook
+ Another approach in this situation is to use the post description hook
with \glsxtrusesee to append the cross-reference after the description. For
example:
@@ -3122,11 +3175,11 @@ example:
Now the cross-references can appear even though the Now the cross-references can appear even though the number list has been
suppressed.
- As from v1.16, there’s a separate As from v1.16, there’s a separate seealso key. Unlike see\seealsoname You can display the formatted list of cross-references stored in the You can display the formatted list of cross-references stored in the seealso key
using:
-
+
This works in much the same way as \glsxtrusesee but it internally uses
-
+
For example:
@@ -3183,20 +3236,20 @@ For example:
- The actual unformatted comma-separated list ⟨
+ The actual unformatted comma-separated list ⟨xr-list⟩ stored in the seealso field
can be accessed with:
-
+
This will just expand to the ⟨xr-labels⟩ provided in the value of the seealso[ The base The base glossaries package provides \glsseelist, which requires a
@@ -3222,20 +3275,20 @@ class="cmti-10">label
+
which fully expands its argument and passes it to \glsseelist.
- The The seealso key implements the automatic indexing using
-
+
which just does
+
Recall from the Recall from the glossaries package that commands such as \gls display text at
that point in the document (optionally with a hyperlink to the relevant
@@ -3282,7 +3335,7 @@ whether or not it actually has a hyperlink. The actual text and the way
it’s displayed depends on the command used (such as \gls) and the entry
format.
- The default entry format ( The default entry format (\glsentryfmt) used in the § This means that entries with a short form can be treated as regular entries rather
+ This means that entries with a short form can be treated as regular entries rather
than abbreviations if it’s more appropriate for the desired style.
- As from version 1.04, As from version 1.04, \glsentryfmt now puts \glsgenentry in the argument of
the new command
-
+
This just does its argument ⟨text⟩ by default. This means that if you want regular
entries in a different font but don’t want that font to apply to abbreviations, then
@@ -3393,7 +3446,7 @@ overridden by the textformat attribute.
- For example:
+ For example:
@@ -3401,7 +3454,7 @@ class="cmss-10">textformat You can access the label through You can access the label through \glslabel. For example, you can query the
category:
@@ -3412,7 +3465,7 @@ category:
\renewcommand*{\glsxtrregularfont}[1]{%
or query the category attribute, for example, provide a custom attribute called
+ or query the category attribute, for example, provide a custom attribute called
font:
@@ -3424,7 +3477,7 @@ class="cmtt-10">font:
As from version 1.21, it’s simpler to just do, for example:
+ As from version 1.21, it’s simpler to just do, for example:
@@ -3432,23 +3485,23 @@ class="cmtt-10">font without redefining without redefining \glsxtrregularfont.
- As from version 1.30, there is also a command for abbreviations that encapsulates
+ As from version 1.30, there is also a command for abbreviations that encapsulates
\glsxtrgenabbrvfmt:
-
+
This also just does its argument by default. Font changes made by abbreviation styles
are within ⟨text⟩.
- The The \glspostlinkhook provided by the glossaries package to insert information
after the link-text produced by commands like \gls and \glstext is redefined
to
-
+
This command will discard a following full stop (period) if the discardperiod attribute
is set to “true” for the current entry’s category. It will also do
-
+
if a full stop hasn’t be discarded and
-
+
if a full stop has been discarded.
- It may be that you want to check some other setting (rather than a category
+ It may be that you want to check some other setting (rather than a category
attribute) to determine whether or not to discard a following full stop. In which case
you can redefine:
-
+
You can access the field’s label using \glslabel. This command should do ⟨true⟩ if the
@@ -3510,9 +3563,9 @@ definition is simply:
which means that no additional checks are performed. (Only the recognised category
+ which means that no additional checks are performed. (Only the recognised category
attributes will be checked.)
-
- By default
+ By default \glsxtrpostlink just does \glsxtrpostlink⟨category⟩general The sentence-ending hook is slightly more complicated. If the command
+ You can define the post-link hook command using \newcommand, for
+example:
+
+
+
+ or, as from v1.31, you can use
+
+This is simply a shortcut for: The sentence-ending hook is slightly more complicated. If the command
\glsxtrpostlink⟨category⟩ is defined the hook will do that and then insert a
+ id="dx1-8039"> is defined the hook will do that and then insert a
full stop with the space factor adjusted to match the end of sentence. If
\glsxtrpostlink⟨category⟩ hasn’t been defined, the space factor is adjusted to match
+ id="dx1-8040"> hasn’t been defined, the space factor is adjusted to match
the end of sentence. This means that if you have, for example, an entry that ends
with a full stop, a redundant following full stop will be discarded and the space factor
adjusted (in case the entry is in uppercase) unless the entry is followed by additional
material, in which case the following full stop is no longer redundant and needs to be
reinserted.
- There are some convenient commands you might want to use when customizing
+ There are some convenient commands you might want to use when customizing
the post-link-text category hooks:
-
+
This will add the description in parentheses on first use.
- For example, suppose you want to append the description in parentheses on first
+ For example, suppose you want to append the description in parentheses on first
use for entries in the symbol category:
+ id="dx1-8045"> category:
-
+
+
This will append the symbol (if defined) in parentheses on first use.
- If you want to provide your own custom format be aware that you can’t use
+ id="dx1-8047">first use. (Does nothing if
+the symbol hasn’t been set.)
+
+(New to v1.31.) On first use, this will append \space(⟨symbol⟩, ⟨description⟩) if the
+symbol is defined otherwise it just appends \space(⟨description⟩).
+ If you want to provide your own custom format be aware that you can’t use
\ifglsused within the post- within the post-link-text hook as by this point the first use flag will have
been unset. Instead you can use
-
+
This will do ⟨true⟩ if the last used entry was the first use for that entry, otherwise it
+ id="dx1-8054">first use for that entry, otherwise it
will do ⟨false⟩. (Requires at least glossaries v4.19 to work properly.) This command is
locally set by commands like \gls, so don’t rely on it outside of the post-link-text
+ id="dx1-8055">link-text
hook.
-
- For example, if you want to place the description in a footnote after the link-text
+
+ For example, if you want to place the description in a footnote after the link-text
on first use for the first use for the general category:
+ id="dx1-8066"> category:
- The
+ The short-postfootnote abbreviation style uses the post- abbreviation style uses the post-link-text hook to place the
footnote after trailing punctuation characters.
- You can set the default options used by
+
For example, if you mostly don’t want to index entries then you can do:
and then use, for example, and then use, for example, \gls[noindex=false]{sample} when you actually want
the location added to the number list. These defaults may be overridden by other
settings (such as category attributes) in addition to any settings passed in the option
argument of commands like \glslink and \gls.
- Note that if you don’t want Note that if you don’t want any indexing, just omit \makeglossaries and
\printglossaries (or analogous commands). If you want to adjust the
default for wrgloss, it’s better to do this by redefining , it’s better to do this by redefining \glsxtrinitwrgloss
+ id="dx1-8074">
instead.
-
- If you want to change the default value of
+ If you want to change the default value of format, you can instead use:
-
+
This has the advantage of also working for \glsadd. For example, if you
want all locations in the back matter to appear in italic (unless explicitly
@@ -3728,14 +3830,14 @@ overridden):
- Commands like
+ Commands like \gls have star ( have star (*) and plus (+) modifiers as a short cut for
hyper=false and hyper=true. The glossaries-extra package provides a way to add a
third modifier, if required, using
-
+
where ⟨char⟩ is the character used as the modifier and ⟨options⟩ is the default set of
options (which may be overridden). Note that ⟨char⟩ must be a single character (not a
UTF-8 character, unless you are using XƎLATEX or LuaLATEX).
-
- Example:
+
+ Example:
This means that This means that \gls!{sample} will be equivalent to \gls[noindex]{sample}. It’s
not possible to mix modifiers. For example, if you want to do
@@ -3780,23 +3882,23 @@ not possible to mix modifiers. For example, if you want to do
you can use you can use \gls*[noindex]{sample} or \gls![hyper=false]{sample} but you
can’t combine the * and ! modifiers.
- Location lists displayed with \printnoidxglossary internally use
-
+
This command is provided by glossaries, but is modified by glossaries-extra to check
@@ -3817,53 +3919,53 @@ class="cmtt-10">( If the range identifiers aren’t present, this just uses
- If the range identifiers aren’t present, this just uses
+
+
otherwise it uses
-
+
for the start of a range (where the identifier has been stripped from ⟨format⟩)
or
-
+
for the end of a range (where the identifier has been stripped from ⟨format⟩).
- By default the start range command saves the format in
- By default the start range command saves the format in
+
+
and does The end command checks that the format matches the start of the range,
+ The end command checks that the format matches the start of the range,
does
-
+
(which does nothing by default), followed by This means that the list
+ This means that the list
doesn’t display any differently from
+ doesn’t display any differently from
but it does make it easier to define your own custom list handler that can
+ but it does make it easier to define your own custom list handler that can
accommodate the ranges.
-
+
If you are using If you are using bib2gls§9 bib2gls: Managing Reference Databases
instead.
- The The \glsenableentrycount command is modified to allow for the §5
Categories).
- For example, instead of just doing:
+ For example, instead of just doing:
you now need to do:
+ you now need to do:
This will enable the entry counting for entries in the This will enable the entry counting for entries in the abbreviation category, but any
entries assigned to other categories will be unchanged.
- Further information about entry counting, including the new per-unit feature, is
+ Further information about entry counting, including the new per-unit feature, is
described in §6.1 Entry Counting (First Use Flag).
-
+
The internal command used by \glsunset is modified first to allow for the changing
-in entry counting, described above, but also to allow for buffering pending unsets
-when commands like \gls are used in a context where changing a boolean variable
-can cause things to go wrong. One example of this is using \gls in one of the
-commands provided with the package. For example:
+ There are two new commands provided with version 1.31+:
+
+and
+
+These behave like \glslocalreset and \glslocalunset but the argument is a
+comma-separated list of labels.
+ The internal command used by \glsunset is modified first to allow for the
+changing in entry counting, described above, but also to allow for buffering pending
+unsets when commands like \gls are used in a context where changing a boolean
+variable can cause things to go wrong. One example of this is using \gls in one of
+the commands provided with the package. For example:
This causes the confusing error:
+ This causes the confusing error:
The simplest workaround is to put The simplest workaround is to put \gls{html} inside the argument of \mbox. For
example:
@@ -4013,37 +4137,44 @@ example:
This can work provided it’s not the first use of this entry. It if is, then unsetting the
+ This can work provided it’s not the first use of this entry. It if is, then unsetting the
first use flag causes a problem and results in the error:
The The glossaries-extra package provides a way of temporarily switching off \glsunset
so that it just makes a note of the entry’s label but doesn’t actually perform the
change:
-
-Later you can restore
+The unstarred version doesn’t check for duplicates, so the internal list may
+end up with multiple occurrences of the same label. The starred version
+only adds a label to the internal list if it’s not already in it. Note that this
+buffering only applies to the global \glsunset and does not affect the local
+\glslocalunset.
+ Later you can restore \glsunset and unset all buffered labels using:
-
+
The starred form \GlsXtrStopUnsetBuffering* uses \glslocalunset instead. For
@@ -4052,7 +4183,7 @@ example:
- Before you stop the unset buffering, you can iterate over the current buffer
+using
+
+where ⟨cs⟩ is a control sequence that takes a single argument (which is the entry label).
+This is best used with the starred version \GlsXtrStartUnsetBuffering* to avoid
+duplicates.
+
- There can still be a problem here as content within
+ There can still be a problem here as content within \mbox can’t break across a
line so you may end up with an overfull line or excessive white space within the
paragraph.
- An alternative is to use An alternative is to use \protect:
but the formatting (underlining in this example) won’t be applied. Another
+ but the formatting (underlining in this example) won’t be applied. Another
possibility is:
This moves This moves \gls outside of \ul and uses textformat to locally change the formatting
+ id="dx1-10007"> to locally change the formatting
command used by \gls (which is normally given by \glstextformat or the
textformat attribute) to a custom command attribute) to a custom command \gul, which locally changes the regular
font and the default abbreviation font to use \ul. It then uses
-
+
which (protected) fully expands ⟨text⟩ before applying ⟨cs⟩, which must be a control
@@ -4146,12 +4292,12 @@ something that \ul can’t deal with. For example, if an abbreviation style is used
that contains complex formatting or if the field value contains problematic
content.
-
+
Some languages, such as English, have a general rule that plurals are formed from
+ Some languages, such as English, have a general rule that plurals are formed from
the singular with a suffix appended. This isn’t an absolute rule. There are
plenty of exceptions (for example, geese, children, churches, elves, fairies,
sheep). The To make life easier for languages where the majority of plurals can simply be
+ To make life easier for languages where the majority of plurals can simply be
formed by appending a suffix to the singular, the glossaries package lets the plural supplied as well, and you only need to use it for the
exceptions.
- For languages that don’t have this general rule, the For languages that don’t have this general rule, the plural field will always need to
be supplied, where needed.
- There are other plural fields, such as There are other plural fields, such as firstplural, longpluralshortplural If these fields are omitted, the If these fields are omitted, the glossaries package follows these rules: This This last case is changed with glossaries-extra. With this extension package, the
\abbrvpluralsuffix is redefined. In most cases its redefined to
use
-
+
which defaults to just \glspluralsuffix. Some of the abbreviation styles have their
own command for the plural suffix, such as If you require a mixture (for example, in a multilingual document), there are two
+ If you require a mixture (for example, in a multilingual document), there are two
attributes that affect the short plural suffix formation. The first is aposplural
- That is, an apostrophe followed by That is, an apostrophe followed by \abbrvpluralsuffix is appended. The second
attribute is shortpluralshort
+
Complications arise when you use Complications arise when you use \gls in the value of the name Things can go wrong if we try the following with the Things can go wrong if we try the following with the glossaries package:
- The main problems are:
+
+ The main problems are:
which just doesn’t work. Grouping the which just doesn’t work. Grouping the \gls{ssi} doesn’t work either as this
will effectively try to do
This will upper case the label This will upper case the label ssi so the entry won’t be recognised.
This problem will also occur if you use the all capitals version, such as
shtml. For example:
- This produces:
+ This produces:
This section discusses server side includes (SSI), hypertext
+ This section discusses server side includes (SSI), hypertext
markup language (HTML) and SSI enabled HTML (SHTML). So the So the first use of the shtml entry produces “SSI enabled HTML (SHTML)”.
- Now let’s suppose the Now let’s suppose the html entry is used before the shtml but the ssi entry is
@@ -4434,41 +4580,41 @@ class="cmtt-10">shtml This produces:
+ This produces:
The sample files are either hypertext markup language (HTML)
+ The sample files are either hypertext markup language (HTML)
or server side includes (SSI) enabled HTML (SHTML), but let’s
first discuss SSI. So the So the
makeglossaries myDoc
pdflatex myDoc
-
\ifmmode \setkeys{glossadd}{counter=equation}\fi}
-
-
-
-
-2. Modifications to Existing Commands and Styles
-
-
-
-
}
-
-
-
-
-2.1 Entry Indexing
-
+
-
}%
}
-
-
-
-
-
\ifmmode \setkeys{glossadd}{counter=equation}\fi}
\renewcommand{\glsaddpostsetkeys}{%
\ifmmode \setkeys{glossadd}{counter=equation}\fi}
\gls{sample}.
\end{document}
\glsadd[thevalue={S.2}]{sample}
\end{document}
name={sample},description={an example}}
2.2 Cross-References (“see” and “see also”)
-
-
-
-
{}%
}
-
-
{}%
}
-
-
-2.3 Entry Display Style Modifications
-
-
\glsifcategory{\glslabel}{general}{\textsf{#1}}{#1}}
\renewcommand*{\glsxtrregularfont}[1]{%
\glsifattribute{\glslabel}{font}{sf}{\textsf{#1}}{#1}}
-
-
-
-
-
\glsxtrpostlinkAddDescOnFirstUse
+
}
+
+
-
\glsxtrpostlinkAddDescOnFirstUse
}
-
+
-
\glsxtrifwasfirstuse{\footnote{\glsentrydesc{\glslabel}}}{}%
}
-
-
\GlsXtrSetDefaultNumberFormat{hyperit}
-
-
-
-
-
-
\glsxtrdisplaysingleloc{⟨}
-
\glsxtrdisplaysingleloc{⟨\glsxtrlocrangefmt to empty.
-
\glsnoidxdisplayloc{}{page}{textbf}{1},
\glsnoidxdisplayloc{}{page}{)textbf}{1}.
\glsnoidxdisplayloc{}{page}{textbf}{1},
\glsnoidxdisplayloc{}{page}{textbf}{1}.
2.4 Entry Counting Modifications
-
\glssetcategoryattribute{abbreviation}{entrycount}{1}
2.5 Unsetting the First Use Flag
-
+
+
-
-
\usepackage[T1]{fontenc}
\usepackage{soul}
@@ -4065,35 +4196,50 @@ example:
Next use: \gls{html}.
\end{document}
+
\ul{Some text about \protect\gls{html}.}
\GlsXtrStopUnsetBuffering
\usepackage{soul}
\usepackage{glossaries-extra}
@@ -4110,31 +4256,31 @@ possibility is:
Next use: \gls{html}.
\end{document}
-2.6 Plurals
-
@@ -4256,7 +4402,7 @@ class="cmtt-10">\acrpluralsuffix
short
-2.7 Nested Links
-
\newacronym{html}{HTML}{Hypertext Markup Language}
\newacronym{shtml}{S\gls{html}}{\gls{ssi} enabled \gls{html}}
first discuss \gls{ssi}.