From 11bd7c1043384daa09ab391cfbbc6c9b47514c9f Mon Sep 17 00:00:00 2001
From: Karl Berry
glossaries-extra.sty v1.28: an extension to the
+class="cmr-17">glossaries-extra.sty v1.29: an extension to the
glossaries package
2018-03-06
By default (with hyperref), the page numbers in number lists link back to the + top of the relevant page (provided the format uses \glshypernumber). The + indexcounter option is designed to link back to the place within the page where + the indexing occurred. It does this by creating a new counter (called wrglossary) + that’s incremented with \refstepcounter every time an entry is indexed (but + not via cross-referencing commands, such as \glssee). A \label is placed + immediately after the increment command allowing the back-referenced to be + obtained with \pageref. The location, as seen by the indexing application, is + the value of the wrglossary counter but this value is substituted with the page + reference when number list is typeset. Since the counter is used by all + entries and is incremented every time any indexing occurs, neither + makeindex nor xindy can correctly collate the lists. For example, if the first + term to be referenced is indexed three times on page 5 without any + intervening terms then the actual locations obtained from wrglossary + will be 1, 2 and 3, which xindy and makeindex will try to form into + the range 1–3, but they should actually all simply appear as page 5, + whereas it can actually end up with 5–5. Conversely, a range may not be + + + + formed where it would naturally occur if just the page counter was + used. +
Since bib2gls is designed specifically to work with glossaries-extra, + bib2gls (v1.4+) will check for wrglossary locations. If the default + --merge-wrglossary-records is on, then any records for the same page + for a given entry will be merged. In the above example with three + references on page 5, only a single record for page 5 for that entry will be + added to the number list and it will link back to the first instance on + that page. Whereas if you use the --no-merge-wrglossary-records + switch, the number list will contain three instance of page 5, with + 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 bib2gls documentation for the save-index-counter resource option + for more details. +
Remember that if Remember that if \newglossaryentry wouldn’t be allowed in the
document environment with the base environment with the base glossaries package, then it still
won’t be allowed with docdefs=true. If your glossaries occur at the
+ id="dx1-4150">. If your glossaries occur at the
end of the document, consider using docdef=restricted instead.
+ id="dx1-4151"> instead.
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=warn + id="dx1-4159"> 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 .aux and .gls files).
The The glossaries package allows \newglossaryentry within the document
+ id="dx1-4160">
environment (when used with makeindex or xindy) but the user manual warns
against this usage. By default the prohibits this, only
allowing definitions within the preamble. If you are really determined to define
entries in the document environment, despite all the associated drawbacks, you
+ id="dx1-4164"> environment, despite all the associated drawbacks, you
can restore this with docdef=true. Note that this doesn’t change the
+ id="dx1-4166">. Note that this doesn’t change the
prohibitions that the glossaries package has in certain circumstances (for
example, when using “option 1”). See the glossaries user manual for
href="#styopt.docdef">docdef=restricted. Only use . Only use docdef=true if document definitions
+ id="dx1-4168"> if document definitions
are necessary and one or more of the glossaries occurs in the front
matter.
- 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 On-the-Fly Document Definitions
+
which is equivalent to
+
If this command is already defined, it’s left unchanged. Otherwise it’s defined
to “Abbreviations” if babel hasn’t been loaded or hasn’t been loaded or \acronymname if
babel has been loaded. However, if you’re using has been loaded. However, if you’re using babel it’s likely you
+ id="dx1-4175"> it’s likely you
will need to change this. (See §13 Multi-Lingual Support for further
details.)
-
- If the
+ If the abbreviations option is used and the option is used and the acronym option provided by the
+ id="dx1-4178">
- Note that there are no analogous options to the
+ Note that there are no analogous options to the glossaries package’s acronymlists
+ id="dx1-4182">
option (or associated commands) as the abbreviation mechanism is handled
differently with glossaries-extra.
@@ -1742,13 +1853,13 @@ class="cmss-10">glossaries-extra
+
which is equivalent to
+
which is equivalent to Note that multiple invocations of the Note that multiple invocations of the shortcuts option After the After the glossaries-extra package has been loaded, you can set available options
using
-
+
The abbreviations and and docdef options may only be used in the preamble. Additionally,
+ id="dx1-4214"> options may only be used in the preamble. Additionally,
docdef can’t be used after can’t be used after \makenoidxglossaries.
+ id="dx1-4216">.
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
@@ -2022,12 +2133,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:
@@ -2093,8 +2204,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 The \newglossaryentry command has three new keys: The test file The test file example-glossaries-xr.tex contains dummy entries with a mixture of
seebib2gls.
- The The \longnewglossaryentry command now has a starred version (as from v1.12)
that doesn’t automatically insert
@@ -2220,8 +2331,8 @@ 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 ⟨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:
@@ -2257,9 +2368,9 @@ 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
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 §3
Abbreviations.)
- The The \makeglossaries command now has an optional argument.
-
+
If ⟨list⟩ is empty, \makeglossaries behaves as per its original definition in the
@@ -2315,7 +2426,7 @@ class="cmtt-10">\makeglossaries This command is not permitted with the This command is not permitted with the record=onlyrecord=off.
- 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
+ You will need at least version 2.20 of makeglossaries or at least version 1.3 of
@@ -2363,10 +2474,10 @@ class="cmss-10">automake The The glossaries-extra package provides extra keys for commands like \gls and
wrgloss=after for specific instances. Note that this opti
settings (such as noindex).
- The default value is set up using
- The default value is set up using
+
+
which is defined as:
@@ -2452,15 +2563,15 @@ 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 \hyperlink. For
will set will set hyperoutside=false for all entries that are assigned to the category
mathrelation and
@@ -2542,7 +2653,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
options are set.)
- 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 thevalue 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 theHvalueprefix
+
- For example, For example, makeindex will only accept locations in the form [⟨num⟩⟨
\glsadd[thevalue={Supplementary Material}]{sample}
For example, suppose the file For example, suppose the file suppl.tex contains:
@@ -2683,7 +2794,7 @@ 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 \glsadd[thevalue={S.2}]{sample}
This location value will be accepted by This location value will be accepted by makeindex 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
externallocationexternallocation Next you need to add Next you need to add glsxtrsupphypernumber as the format:
@@ -2733,7 +2844,7 @@ class="cmtt-10">glsxtrsupphypernumber Both documents will need to use the Both documents will need to use the hyperref package. Remember that the counter
used for the location also needs to match. If 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,
@@ -2796,20 +2907,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:
@@ -2914,11 +3025,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:
@@ -2975,20 +3086,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
@@ -3014,20 +3125,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
@@ -3074,7 +3185,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
@@ -3185,7 +3296,7 @@ overridden by the textformat attribute.
- For example:
+ For example:
@@ -3193,7 +3304,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:
@@ -3204,7 +3315,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:
@@ -3216,7 +3327,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:
@@ -3224,9 +3335,9 @@ class="cmtt-10">font without redefining without redefining \glsxtrregularfont.
- 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
@@ -3288,9 +3399,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
+ The sentence-ending hook is slightly more complicated. If the command
\glsxtrpostlink⟨category⟩ 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 For example, suppose you want to append the description in parentheses on first
use for entries in the symbolsymbol
-
+
+
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
+ If you want to provide your own custom format be aware that you can’t use
\ifglsused 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
@@ -3398,7 +3509,7 @@ locally set by commands like \gls, so don’t rely on it outside of the post-link-text
hook.
-
- For example, if you want to place the description in a footnote after the
+ For example, if you want to place the description in a footnote after the link-text
on first use for the general \glsxtrifwasfirstuse{\footnote{\glsentrydesc{\glslabel}}}{}%
- The
+ The short-postfootnote abbreviation style uses the post-link-text hook to place the
footnote after trailing punctuation characters.
- You can set the default options used by You can set the default options used by \glslink, \gls etc with:
-
+
For example, if you mostly don’t want to index entries then you can do:
@@ -3466,7 +3577,7 @@ 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 \glslink Note that if you don’t want Note that if you don’t want any indexing, just omit \makeglossaries and
wrgloss\glsxtrinitwrgloss
- 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
@@ -3510,8 +3621,8 @@ overridden):
\backmatter
- Commands like
+ Commands like \gls have star (*) and plus (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:
@@ -3550,7 +3661,7 @@ class="cmti-10">char 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
@@ -3561,17 +3672,17 @@ 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
@@ -3595,8 +3706,8 @@ 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
@@ -3688,7 +3799,7 @@ class="cmtt-10">\glsxtrlocrangefmt doesn’t display any differently from
+ doesn’t display any differently from
@@ -3698,14 +3809,14 @@ class="cmtt-10">\glsxtrlocrangefmt 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:
@@ -3736,7 +3847,7 @@ href="#sec:categories">Categories you now need to do:
+ you now need to do:
@@ -3745,21 +3856,21 @@ href="#sec:categories">Categories).
\glsenableentrycount
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).
-
+
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 plural 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 \abbrvpluralsuffix, which changes with
the style. Redefining \acrpluralsuffix will have no affect, since it’s not used by the
new abbreviation mechanism.
- 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
'\abbrvpluralsuffix
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:
@@ -3950,8 +4061,8 @@ class="cmss-10">glossaries
- 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
@@ -3980,7 +4091,7 @@ class="cmtt-10">\gls{ssi} 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
@@ -4043,17 +4154,17 @@ 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 first use of the shtml entry now produces “server side includes (SSI)
enabled HTML (SHTML)”, which looks a bit strange.
- Now let’s suppose the Now let’s suppose the shtml entry is used before (or without) the other two
entries:
@@ -4063,17 +4174,17 @@ class="cmtt-10">shtml This produces:
+ This produces:
This article is an introduction to server side includes (SSI)
+ This article is an introduction to server side includes (SSI)
enabled hypertext markup language (HTML) (SHTML). So the So the first use of the shtml entry now produces “server side includes (SSI)
enabled hypertext markup language (HTML) (SHTML)”, which is even more
strange.
- This is all aggravated by setting the style using the This is all aggravated by setting the style using the glossaries package’s
\setacronymstyle. For example:
@@ -4084,7 +4195,7 @@ class="cmtt-10">\setacronymstyle as this references the label through the use of as this references the label through the use of \glslabel when displaying the
long and short forms, but this value changes with each use of \gls, so
@@ -4096,7 +4207,7 @@ class="cmtt-10">\glslabel Another oddity occurs if you reset the Another oddity occurs if you reset the html entry between uses of the shtml
entry. For example:
@@ -4107,10 +4218,10 @@ class="cmtt-10">shtml The next use of The next use of shtml produces “Shypertext markup language (HTML)”,
which is downright weird.
- Even without this, the short form has nested formatting commands, which
+ Even without this, the short form has nested formatting commands, which
amount to \acronymfont{S\acronymfont{HTML}}. This may not be a problem
for some styles, but if you use one of the “sm” styles (that use hyperref
- For these reasons it’s better to use the simple expandable commands
+ For these reasons it’s better to use the simple expandable commands
like \glsentrytext or [description={\acrshort{ssi} enabled \acrshort{html}}]
with with glossaries or:
@@ -4171,7 +4282,7 @@ class="cmss-10">glossaries with with glossaries-extra. This fixes all the above listed problems (as long as you don’t
use \glsdescfirst use issue, but it doesn’t fix any of the other problems listed
above.
- If it’s simply that you want to use the abbreviation font, you can use
+ If it’s simply that you want to use the abbreviation font, you can use
\glsabbrvfont:
@@ -4196,10 +4307,10 @@ class="cmtt-10">\glsabbrvfont This will pick up the font style setting of the outer entry (shtml, in the above case).
+ This will pick up the font style setting of the outer entry (shtml, in the above case).
This isn’t a problem in the above example as all the abbreviations use the same
style.
- However if you’re really determined to use However if you’re really determined to use \gls in a field that may be included
within some
\gls{ssi} enabled \gls{html}
is treated as
+ is treated as
@@ -4232,7 +4343,7 @@ form
{\glstext[hyper=false,noindex]{ssi}} enabled
This overcomes problems This overcomes problems 4, 5 and 6 listed above, but still doesn’t fix problems long-noshort-desc).
- Additionally, any instance of the long form commands, such as Additionally, any instance of the long form commands, such as \glsxtrlong or
shtml entry had instead been defined as:
then (using the then (using the long-short style) the first use will be like
{\acronymfont{\glsentryshort{ssi}}} enabled
whereas if the entry is defined as:
+ whereas if the entry is defined as:
@@ -4309,7 +4420,7 @@ href="#glo:firstuse">first use will be like
\newabbreviation{shtml}{SHTML}{\glsxtrshort{ssi} enabled
then the then the first use will be like:
@@ -4320,7 +4431,7 @@ href="#glo:firstuse">first use Note that the first optional argument of Note that the first optional argument of \acrshort or \glsxtrshort is ignored in
this context. (The final optional argument will be inserted, if present.) The
@@ -4331,8 +4442,8 @@ class="cmtt-10">\glsxtrshort Alternatively you can use:
- Alternatively you can use:
+
+
where ⟨field⟩ is the field label and corresponds to a command in the form \gls⟨\glstext) or in the form \glsxtr⟨field⟩ (e.g. \glsxtrshort).
- There’s a shortcut command for the most common fields:
- There’s a shortcut command for the most common fields:
+
+
which is equivalent to \glsxtrp{short}{⟨label⟩}, and
-
+
which is equivalent to \glsxtrp{text}{⟨label⟩}.
- The The \glsxtrp command behaves much like the \glsfmt⟨field⟩ commands described
@@ -4395,14 +4506,14 @@ class="cmss-10">noindex
+
For example:
@@ -4411,17 +4522,17 @@ For example:
will just switch off the hyperlinks but not the indexing. Be careful using
+ will just switch off the hyperlinks but not the indexing. Be careful using
this command or you can end up back to the original problem of nested
links.
- The hyper link is re-enabled within glossaries. This is done through the
+ The hyper link is re-enabled within glossaries. This is done through the
command:
-
+
which by default just does
@@ -4430,7 +4541,7 @@ which by default just does
You can redefine this if you want to adjust the setting when You can redefine this if you want to adjust the setting when \glsxtrp is used in the
glossary. For example:
@@ -4440,8 +4551,8 @@ glossary. For example:
- For example,
+
+ For example,
@@ -4449,7 +4560,7 @@ glossary. For example:
is equivalent to
+ is equivalent to
@@ -4459,7 +4570,7 @@ glossary. For example:
in the main body of the document or
+ in the main body of the document or
@@ -4469,8 +4580,8 @@ glossary. For example:
inside the glossary. (Note the post-link hook is locally disabled.)
- If inside the glossary. (Note the post-link hook is locally disabled.)
+ If \glsxtrp{short}{ssi} occurs in a sectioning mark, it’s equivalent
to
@@ -4480,19 +4591,19 @@ to
(which recognises the (which recognises the headuc attribute.)
- If If hyperref has been loaded, then the bookmark will use \glsentry⟨field⟩
(\glsentryshort{ssi} in the above example).
- There are similar commands
- There are similar commands
+
+
for first letter upper case and
-
+
for all upper case.
-
- You can, with care, protect against issue
+ You can, with care, protect against issue 1 by inserting an empty group at the
start if the long form starts with a command that breaks the first letter uppercasing
commands like \Gls, but you still won’t be able to use the all caps commands, such
as \GLS.
- If you If you really need nested commands, the safest method is
@@ -4544,8 +4655,8 @@ class="cmti-10">really need but be aware that it may have some unexpected results occasionally.
- Example document:
+ but be aware that it may have some unexpected results occasionally.
+ Example document:
@@ -4575,16 +4686,16 @@ class="cmti-10">really need
-
+
+
The The glossaries-extra package provides a new way of dealing with abbreviations and
redefines \newacronymglossaries-extra before you define any entries. For example, the following document using just
+ before you define any entries. For example, the following document using just
glossaries
@@ -4623,7 +4734,7 @@ class="cmss-10">glossaries can be easily adapted to use can be easily adapted to use glossaries-extra:
@@ -4640,7 +4751,7 @@ class="cmss-10">glossaries-extra Table Table 2.1 lists the nearest equivalent glossaries-extra abbreviation styles for the
predefined acronym styles provided by The reason for introducing the new style of abbreviation commands provided by
+ The reason for introducing the new style of abbreviation commands provided by
glossaries-extra is because the original acronym commands provided by glossaries are
@@ -4908,15 +5019,15 @@ class="cmss-10">glossaries-extra
+
(before any use of \newacronym).
- \RestoreAcronyms should not be used in combination with the newer
glossaries-extra abbreviations. Don’t combine old and new style entries with the same
@@ -4926,7 +5037,7 @@ class="cmss-10">type
- In general, there’s rarely any need for
+ In general, there’s rarely any need for \RestoreAcronyms. If you have a
document that uses \newacronymstyle§3.5 Defining New Abbreviation Styles for further
details.)
-
+
The space command \glsacspace used by the long-sp-short acronym style provided
by glossaries is modified so that it uses
-
+
instead of the hard-coded 3em. This is a command not a length and so can be
changed using \renewcommand.
- Any of the new abbreviation styles that use Any of the new abbreviation styles that use \glsxtrfullsep (such as \glsacspace with
- The
+ The first use acronym font command
-
+
is redefined to use the first use abbreviation font command \glsfirstabbrvfont.
This will be reset if you use \RestoreAcronyms.
- The subsequent use acronym font command
- The subsequent use acronym font command
+
+
is redefined to use the subsequent use abbreviation font command \glsabbrvfont.
This will be reset if you use \RestoreAcronyms.
As from v1.21, As from v1.21, glossaries-extra has a new supplementary package glossary-bookindex
@@ -5043,7 +5154,7 @@ style:
or use both the or use both the stylemods and style
\usepackage[stylemods=bookindex,style=bookindex]{glossaries-extra}
The The bookindex style only supports a maximum hierarchical level of 2 (top-level,
level 1 and level 2).
- The number of columns is given by
- The number of columns is given by
+
+
which defaults to 2.
- This style uses the This style uses the multicols environment. If the command
-
+
isn’t empty then it’s supplied as the optional argument following \begin{multicols}
multicolsmulticols*
+
For example
@@ -5104,16 +5215,16 @@ For example
- Each top-level entry is displayed using
-
+ Each top-level entry is displayed using
+
+
where the entry is identified by ⟨label⟩. This just does \glossentryname{⟨ \ifglshassymbol{#1}{\space (\glossentrysymbol{#1})}{}%
Alternatively you can use the Alternatively you can use the \glsxtrpostname⟨category⟩ hook.
- Sub-entries are displayed using
- Sub-entries are displayed using
+
+
which just defaults to \glsxtrbookindexname{⟨label⟩}.
- The separator used before the location list for top-level entries is given
+ The separator used before the location list for top-level entries is given
by
-
+
where ⟨label⟩ is the entry’s label. This checks if the location field has been set. If it
@@ -5168,7 +5279,7 @@ has, it does
otherwise it just does otherwise it just does \glsxtrprelocation (which defaults to \space). If you’re not
using bib2gls The separator used before the location list for sub-entries is given by
- The separator used before the location list for sub-entries is given by
+
+
which defaults to \glsxtrbookindexprelocation{⟨label⟩}.
- The separator used between a top-level parent and child entry is given
+ The separator used between a top-level parent and child entry is given
by
-
+
This defaults to \nopagebreak.
- The separator used between a sub-level parent and child entry is given
+ The separator used between a sub-level parent and child entry is given
by
-
+
This defaults to \glsxtrbookindexparentchildsep.
- The separator between top-level entries is given by
- The separator between top-level entries is given by
+
+
This comes after the entry given by ⟨label1⟩, if the entry has no children, or after the
last descendent otherwise, so it always comes immediately before the entry given by
⟨label2⟩ unless the entry occurs at the start of a group. This does nothing by
default.
- The separator between two level 1 entries is given by
- The separator between two level 1 entries is given by
+
- The separator between two level 2 entries is given by
-
+ The separator between two level 2 entries is given by
+
+
At the end of each letter group, the following hooks are done in order:
-
-
+
-
+
+
where ⟨sub-sub-label⟩ is the label of the last level 2 entry, ⟨sub-label⟩ is the label of the
last level 1 entry and ⟨label⟩ is the label of the last level 0 entry.
- For example, the resource option For example, the resource option seealso=omit instructs \glsxtrbookindexsubsubatendgroup{#1}%
This uses This uses \glstreesubitem and \glstreesubsubitem to indent the cross-reference
according to the next level down, so the cross-reference for a top-level entry is aligned
@@ -5342,7 +5453,7 @@ indented a bit further (but it won’t be aligned with any deeper level as t
class="cmss-10">bookindex The The bookindex style uses group headings. (If you use bib2gls
+
If \pdfbookmark has been defined, this will use that command to bookmark the
group title. If \pdfbookmark The group heading is formatted according to
- The group heading is formatted according to
+
+
which is defined as
@@ -5397,14 +5508,14 @@ which is defined as
where where \glstreegroupheaderfmt is provided by the glossary-tree package, which is
automatically loaded. Note that the entry names aren’t encapsulated with
\glstreenamefmt.
- The The glossary-bookindex package provides some supplementary commands that
aren’t used by default, but may be used when adjusting the style. These commands
@@ -5412,35 +5523,35 @@ should only be used within one of the \print…glossary commands. (That is, they
should only be used in glossary styles.)
-
+
This writes information to the .aux file that can be read on the next run to obtain
the first and last entry on each page of the glossary.
- You can display the first entry associated with the current page using:
- You can display the first entry associated with the current page using:
+
+
and the last entry associated with the current page using:
-
+
These do nothing if there are no entries marked on the current page (or if the
document build isn’t up to date).
- The entry is formatted using:
- The entry is formatted using:
+
+
for the first instance and
-
+
for the last.
- These commands are designed for use in page headers or footers where the page
+ These commands are designed for use in page headers or footers where the page
number is stable. For example, \glsxtrbookindexname can be redefined to mark the
current entry:
@@ -5474,7 +5585,7 @@ current entry:
If you only want to mark the top-level entries, remember to redefine
+ If you only want to mark the top-level entries, remember to redefine
\glsxtrbookindexsubname as it defaults to \glsxtrbookindexname:
@@ -5487,8 +5598,8 @@ class="cmtt-10">\glsxtrbookindexname
- Then if you’re using
+ Then if you’re using fancyhdr you can set the page style to show the first and last
entry for the current page with:
@@ -5503,13 +5614,13 @@ entry for the current page with:
-
+
+
The The glossaries-extra-stylemods package (more conveniently loaded through the
§2.9.3 The glossaries-extra-stylemods Package.
- The The glossaries package tries to determine the group title from its label by first
checking if \glsxtr@grouptitle@⟨label⟩
which shouldn’t clash with another package. You can set the group title
using
-
+
For example:
@@ -5563,9 +5674,9 @@ For example:
This uses a global assignment. If you need to scope the change you can
+ This uses a global assignment. If you need to scope the change you can
use
-
-
+
+
The commands The commands \glossentryname and \glossentrydesc§ If you want to adapt a style to use another field instead of If you want to adapt a style to use another field instead of name, you can
use
-
+
This behaves just like \glossentryname (that is, it obeys description). See the key to field mappings table in the glossaries user
manual.
- There is a hook after There is a hook after \glossentryname and \Glossentryname:
-
+
By default this checks the indexname attribute. If the attribute exists for the
category to which the label belongs, then the name is automatically indexed
using
-
+
See §7 Auto-Indexing for further details.
- As from version 1.04, the post-name hook As from version 1.04, the post-name hook \glsxtrpostnamehook will also use
\glsxtrpostname⟨ (\glsentrysymbol{\glscurrententrylabel})}
As from version 1.25, the post-name hook also does
- As from version 1.25, the post-name hook also does
+
+
(before \glsxtrpostname⟨category⟩) to allow for additional non-category related code.
This does nothing by default.
- The post-description code used within the glossary is modified so that it also
+ The post-description code used within the glossary is modified so that it also
does
-
+
This occurs before the original \glspostdescription, so if the nopostdot=false
option is used, it will be inserted before the terminating full stop.
- This new command will do This new command will do \glsxtrpostdesc⟨category⟩ if it exists, where
⟨general\glsxtrpostdescacronym Since both Since both \glossentry and \subglossentry set
-
+
to the label for the current entry, you can use this within the definition of these
post-description hooks if you need to reference the label.
- For example, suppose you want to insert the plural form in brackets after the
+ For example, suppose you want to insert the plural form in brackets after the
description in the glossary, but only for entries in the general category, then you could
@@ -5752,10 +5863,10 @@ do:
\renewcommand{\glsxtrpostdescgeneral}{\space
This means you don’t have to define a custom glossary style, which you may find
+ This means you don’t have to define a custom glossary style, which you may find
more complicated. (It also allows more flexibility if you decide to change the
underlying glossary style.)
-
-
+
+
The The number list is now placed inside the argument of
-
+
This is internally used by \glossaryentrynumbers. The \glossaryentrynumbers so that it doesn’t display th
id="dx1-16004">number list, but it
still saves the number list in case it’s required.
-
- If you want to, for example, change the font for the entire
+ If you want to, for example, change the font for the entire number list
then redefine \GlsXtrFormatLocationList as appropriate. Don’t modify
\glossaryentrynumbers.
- Sometimes users like to insert “page” or “pages” in front of the Sometimes users like to insert “page” or “pages” in front of the number list. This
is quite fiddly to do with the base glossaries package, but glossaries-extra provides a
way of doing this. First you need to enable this option and specify the text to display
using:
-
+
where ⟨page⟩ is the text to display if the number list only contains a single location and
@@ -5846,28 +5957,28 @@ class="cmti-10">pages An extra run is required when using this command.
- An extra run is required when using this command.
+
- See the accompanying sample file
+ See the accompanying sample file sample-pages.tex.
- Note that Note that bib2gls
+
As from v1.02, As from v1.02, glossaries-extra now includes the package glossaries-extra-stylemods that
@@ -5884,7 +5995,7 @@ class="cmss-10">glossaries-extra Alternatively you can load Alternatively you can load glossary-⟨name⟩.sty at the same time by passing ⟨glossaries-extra-stylemods\usepackage[longragged]{glossaries-extra-stylemods}
Another option is to use the Another option is to use the stylemods key when you load long3col
\usepackage[style=long3col,stylemods]{glossaries-extra}
Or the value of Or the value of stylemods may be a comma-separated list of the style package
@@ -5929,7 +6040,7 @@ identifiers. For example:
Remember to group the value if it contains any commas:
+ Remember to group the value if it contains any commas:
@@ -5937,8 +6048,8 @@ identifiers. For example:
- Note that the
+ Note that the inline style is dealt with slightly differently. The original definition
provided by the nopostdot The The tabular-like styles, such as \printglossary, \printnoidxglossary or \printunsrtglossary, you must also
reset the glossary style.
- As from version 1.21, the hard-coded As from version 1.21, the hard-coded \space before the number list in many of
the predefined styles is replaced with
-
+
This just defaults to \space but may be redefined as required. For example:
@@ -6010,27 +6121,27 @@ class="cmtt-10">\space
-
-
-
-
-
-2. Modifications to Existing Commands and Styles
-
-
-
-
}
-
-
-
-
-2.1 Entry Indexing
-
-
}%
}
-
-
-
\gls{sample}.
\end{document}
\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}}
-
-
-
-
-
}
-
-
}
-
-
\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 Plurals
-
@@ -3864,7 +3975,7 @@ class="cmtt-10">\acrpluralsuffix
short
-2.6 Nested Links
-
\newacronym{html}{HTML}{Hypertext Markup Language}
\newacronym{shtml}{S\gls{html}}{\gls{ssi} enabled \gls{html}}
first discuss \gls{ssi}.
{shtml}{SHTML}{SSI enabled HTML}
[description={\glsxtrshort{ssi} enabled \glsxtrshort{html}}]
{shtml}{SHTML}{SSI enabled HTML}
\newabbreviation{shtml}{shtml}{\glsabbrvfont{ssi} enabled
\glsabbrvfont{html}}
{\glstext[hyper=false,noindex]{html}}
{\acronymfont{\glsentryshort{html}}} (SHTML)
\glsxtrshort{html}}
{\glsabbrvfont{\glsentryshort{html}}} (SHTML)
-
-
-
-
-
\glsxtrshort[hyper=false,noindex]{ssi}[]%
}
\glsxtrshort[noindex]{ssi}[]%
}
-
-
\glsxtrp{short}{html}}
\printglossaries
\end{document}
2.7 Acronym Style Modifications
-
\printglossaries
\end{document}
\printglossaries
\end{document}
-
-
-
-
-2.8 glossary-bookindex package
-
\usepackage{glossary-bookindex}
\setglossarystyle{bookindex}
-
-
-
-
}
-
-
-
-
-
-
-
-
-
-
-
}
-
\par{\centering\glstreegroupheaderfmt{#1}\par}%
}
-
-
-
-
-
\glossentryname{#1}%
}
\glossentryname{#1}%
}
\cfoot{}%
\rfoot{\glsxtrbookindexlastmark}%
2.9 Glossary Style Modifications
-
-
-2.9.1 Style Hooks
-
-
-
-
-
-
-
(plural: \glsentryplural{\glscurrententrylabel})}
2.9.2 Number List
-
-
-2.9.3 The glossaries-extra-stylemods Package
-
\usepackage{glossary-longragged}
\usepackage{glossaries-extra-stylemods}
-