From d45285c28e456bfaf2a23c50159f572358770ffe Mon Sep 17 00:00:00 2001
From: Karl Berry
glossaries-extra.sty v1.39: an extension to the
+class="cmr-17">glossaries-extra.sty v1.40: an extension to the
glossaries package
2019-03-22
+ which uses \printunsrtglossary. +
The title of the new glossary is given by +
+
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-4196"> 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-4199">
-
Note that there are no analogous options to the
+ Note that there are no analogous options to the glossaries package’s acronymlists
+ id="dx1-4203">
option (or associated commands) as the abbreviation mechanism is handled
differently with glossaries-extra.
@@ -2058,13 +2077,13 @@ class="cmss-10">glossaries-extra
+
which is equivalent to
If glossaries-extra-bib2gls is also loaded then this option will additionally + provide: +
+ which uses \printunsrtglossary. +
+
which is equivalent to
If glossaries-extra-bib2gls is also loaded then this option will additionally + provide: +
+ which uses \printunsrtglossary. +
+ which uses \printunsrtglossary. +
+
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-4251"> options may only be used in the preamble. Additionally,
docdef can’t be used after can’t be used after \makenoidxglossaries.
+ id="dx1-4253">.
-
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 @@ -2338,12 +2445,12 @@ class="cmtt-10">\glsxtrpostdescription
not before.) The post-description hook can counter-act the effect of \glsxtrnopostpunc using -
+
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:
@@ -2409,7 +2516,7 @@ class="cmss-10">glossaries The The glossaries-extra package provides \glsxtrhiername§2.2 Cross-References (“see” and “see also”) for
further details.
- 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}
+
but take care of duplicate labels if it’s not scoped. 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
@@ -2585,8 +2692,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:
@@ -2622,9 +2729,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
@@ -2680,7 +2787,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
@@ -2728,16 +2835,16 @@ class="cmss-10">automake As from version 1.31, there is a new command like 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[⟨]{⟨label⟩} for each entry in the
list.
- As from version 1.37, you can make commands like As from version 1.37, you can make commands like \gls or \glslink
automatically use } in the optional argument of the corresponding
\gls, \glslink etc).
-
+
The optional argument ⟨label⟩ defaults to \glslabel and indicates the label to use in
@@ -2795,7 +2902,7 @@ class="cmtt-10">format={ For example, with:
+ For example, with:
@@ -2803,7 +2910,7 @@ list.
then then \gls[format=hyperbf]{sample} will be equivalent to
@@ -2812,11 +2919,11 @@ class="cmtt-10">\gls[format=hyperbf]{sample} Note that the explicit range markers will prevent a match unless you include
+ Note that the explicit range markers will prevent a match unless you include
them in ⟨format list⟩ (in which case, be sure to add both the start and end
formats).
- Here’s another example:
+ Here’s another example:
@@ -2824,7 +2931,7 @@ formats).
In this case In this case \gls[format=hyperbf]{sample} will now be equivalent to:
@@ -2833,12 +2940,12 @@ class="cmtt-10">\gls[format=hyperbf]{sample}
-
+
+
The glossaries-extra package provides extra keys for commands like \gls and
@@ -2899,13 +3006,13 @@ class="cmtt-10">wrgloss=after The default value is set up using
- The default value is set up using
+
+
which is defined as:
@@ -2922,15 +3029,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
@@ -3012,7 +3119,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
@@ -3101,21 +3208,21 @@ 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:
@@ -3129,7 +3236,7 @@ class="cmss-10">equation In this case, the counter can be overridden with an explicit use of In this case, the counter can be overridden with an explicit use of counter in the
optional argument of equations package option.)
- Alternatively, to enforce this (overriding the option argument):
+ Alternatively, to enforce this (overriding the option argument):
@@ -3150,8 +3257,8 @@ class="cmss-10">equations
- 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}
This location value will be accepted by This location value will be accepted by bib2gls, since it will allow any location and
@@ -3223,7 +3330,7 @@ class="cmss-10">format For example, suppose the file For example, suppose the file suppl.tex contains:
@@ -3240,7 +3347,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:
@@ -3290,7 +3397,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.
- This method can only be used where there is one external source for the
+ This method can only be used where there is one external source for the
designated category (identified by the externallocation.aux
+
The value of the The value of the see key is now saved as a field. This isn’t the case with glossaries,
@@ -3367,9 +3474,9 @@ 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⟩.
- As with the base As with the base glossaries package, \glsseeformat is defined to do }. The third argument is always ignored and is present fo
class="cmtt-10">makeindex
+
used to iterate over the list of cross-reference labels is also unchanged from
the base glossaries package, with each item in the list formatted according
to:
-
+
This is defined by the glossaries package to:
- The command:
-
+ The command:
+
+
performs a recursive action:
The first step above is skipped if the entry doesn’t have a parent. Each level is separated
+ The first step above is skipped if the entry doesn’t have a parent. Each level is separated
by:
-
+
which defaults to “ ⊳ ”. This can be redefined as appropriate.
- There are some case-changing variants:
- There are some case-changing variants:
+
+
The top-level has the first letter changed to upper case (either \Glsaccessshort or
\Glsaccessname). There’s no case-change for sub-entries.
-
+
All levels have the first letter changed to upper case (either \Glsaccessshort or
\Glsaccessname).
-
+
The top-level is converted to upper case (either \GLSaccessshort or \GLSaccessname).
There’s no case-change for sub-entries.
-
+
All levels are converted to upper case (either \GLSaccessshort or \GLSaccessname).
- Suppose you want to suppress the Suppose you want to suppress the number list using nonumberlist 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:
@@ -3653,11 +3760,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:
@@ -3714,20 +3821,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[ As mentioned above, the base As mentioned above, the base glossaries package provides \glsseelist, which
@@ -3753,20 +3860,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
@@ -3813,7 +3920,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
@@ -3924,7 +4031,7 @@ overridden by the textformat attribute.
- For example:
+ For example:
@@ -3932,7 +4039,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:
@@ -3943,7 +4050,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:
@@ -3955,7 +4062,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:
@@ -3963,23 +4070,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
@@ -4041,9 +4148,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 You can define the post-link hook command using You can define the post-link hook command using \newcommand, for
example:
@@ -4080,8 +4187,8 @@ example:
or, as from v1.31, you can use
- 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
+ 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. (Does nothing if
the symbol hasn’t been set.)
-
+
(New to v1.31.) On first use, this will append \space(⟨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
+ 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
@@ -4203,7 +4310,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:
@@ -4271,7 +4378,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
@@ -4315,8 +4422,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:
@@ -4355,7 +4462,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
@@ -4366,17 +4473,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
@@ -4400,8 +4507,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
@@ -4493,7 +4600,7 @@ class="cmtt-10">\glsxtrlocrangefmt doesn’t display any differently from
+ doesn’t display any differently from
@@ -4503,14 +4610,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 you may find it more convenient to use the record
@@ -4520,7 +4627,7 @@ class="cmsy-10">§ The The \glsenableentrycount command is modified to allow for the §5
Categories).
- For example, instead of just doing:
+ For example, instead of just doing:
@@ -4541,7 +4648,7 @@ href="#sec:categories">Categories).
you now need to do:
+ you now need to do:
@@ -4550,23 +4657,23 @@ 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).
-
+
The The glossaries package provides
-
+
to determine whether or not an entry has been used. This requires the entry to have
been defined. If the entry is undefined, then the underlying boolean variable doesn’t
exist and so is neither true nor false. This command will produce an error with the
@@ -4595,7 +4702,7 @@ class="cmti-10">true The The record option automatically implements bib2gls. In this case, you may prefer
to use:
-
+
(new to v1.34) which does ⟨true⟩ if the entry given by ⟨label⟩ is undefined or if
@@ -4639,24 +4746,24 @@ href="#sec:entryfmtmods">§2.3 Entry Display Style
Modifications.)
- There are two new commands provided with version 1.31+:
- There are two new commands provided with version 1.31+:
+
+
and
-
+
These behave like \glslocalreset and \glslocalunset but the argument is a
@@ -4664,7 +4771,7 @@ class="cmtt-10">\glslocalunset The internal command used by 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
\ul{Some text about \gls{html}.}
This causes the confusing error:
+ This causes the confusing error:
@@ -4688,7 +4795,7 @@ the commands provided with the
Glossary entry `{html}' has not been defined.
The simplest workaround is to put The simplest workaround is to put \gls{html} inside the argument of \mbox. For
example:
@@ -4699,7 +4806,7 @@ 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:
@@ -4708,17 +4815,17 @@ 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:
-
+
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
@@ -4726,14 +4833,14 @@ buffering only applies to the global \glsunset and does not affect the local
\glslocalunset.
- Later you can restore Later you can restore \glsunset and unset all buffered labels using:
-
+
The starred form \GlsXtrStopUnsetBuffering* uses \glslocalunset instead. For
@@ -4755,9 +4862,9 @@ example:
Before you stop the unset buffering, you can iterate over the current buffer
+ 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:
@@ -4792,7 +4899,7 @@ class="cmtt-10">\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:
@@ -4815,7 +4922,7 @@ possibility is:
This moves This moves \gls outside of \ul and uses textformattextformat
+
which (protected) fully expands ⟨text⟩ before applying ⟨cs⟩, which must be a control
@@ -4851,12 +4958,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
'\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:
@@ -5050,8 +5157,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
@@ -5080,7 +5187,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
@@ -5143,17 +5250,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:
@@ -5163,17 +5270,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:
@@ -5184,7 +5291,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
@@ -5196,7 +5303,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:
@@ -5207,10 +5314,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:
@@ -5271,7 +5378,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:
@@ -5296,10 +5403,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
@@ -5332,7 +5439,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:
@@ -5409,7 +5516,7 @@ href="#glo:firstuse">first use will be like
\newabbreviation{shtml}{SHTML}{\glsxtrshort{ssi} enabled
then the then the first use will be like:
@@ -5420,7 +5527,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
@@ -5431,8 +5538,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
@@ -5495,14 +5602,14 @@ class="cmss-10">noindex
+
For example:
@@ -5511,17 +5618,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
@@ -5530,7 +5637,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:
@@ -5540,8 +5647,8 @@ glossary. For example:
- For example,
+
+ For example,
@@ -5549,7 +5656,7 @@ glossary. For example:
is equivalent to
+ is equivalent to
@@ -5559,7 +5666,7 @@ glossary. For example:
in the main body of the document or
+ in the main body of the document or
@@ -5569,8 +5676,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
@@ -5580,19 +5687,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
@@ -5644,8 +5751,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:
@@ -5675,16 +5782,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
@@ -5723,7 +5830,7 @@ class="cmss-10">glossaries can be easily adapted to use can be easily adapted to use glossaries-extra:
@@ -5740,7 +5847,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
@@ -6008,15 +6115,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
@@ -6026,7 +6133,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
@@ -6143,7 +6250,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). It’s primarily designed for use with record package
option.)
- 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
@@ -6218,16 +6325,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})}{}%
or if you want the description (if set):
+ or if you want the description (if set):
@@ -6255,27 +6362,27 @@ default. For example, if you want the symbol to be included:
(which picks up the post-description hook).
- Alternatively you can use the (which picks up the post-description hook).
+ Alternatively you can use the \glsxtrpostname⟨category⟩ hook to append
information after the name according to the entry’s category.
- 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
@@ -6295,7 +6402,7 @@ has, it does
otherwise it just does otherwise it just does \glsxtrprelocation (which defaults to \space). If you’re not
using bib2gls, the location field won’t be set.
- 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 actual location list is encapsulated with:
- The actual location list is encapsulated with:
+
+
for top-level entries and
-
+
for sub-entries. These both just do ⟨location list⟩ by default.
- 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
@@ -6495,7 +6602,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
@@ -6549,14 +6656,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
@@ -6564,35 +6671,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:
+
-
}
-
-
-
-
-
-2.1 Entry Indexing
-
-
-
-
}%
}
-
-
-
-
-
\ifmmode \setkeys{glossadd}{counter=equation}\fi}
\ifmmode \setkeys{glossadd}{counter=equation}\fi}
\gls{sample}.
\end{document}
\end{document}
name={sample},description={an example}}
2.2 Cross-References (“see” and “see also”)
-
-
-
-
-
-
-
\glsaccessshort) otherwise
the name is displayed (using \glsaccessname).
-
-
-
-
-
-
{}%
}
-
-
{}%
}
-
-
-2.3 Entry Display Style Modifications
-
-
\glsifcategory{\glslabel}{general}{\textsf{#1}}{#1}}
\renewcommand*{\glsxtrregularfont}[1]{%
\glsifattribute{\glslabel}{font}{sf}{\textsf{#1}}{#1}}
-
-
-
-
-
\glsxtrpostlinkAddDescOnFirstUse
}
-
-
}
-
-
-
}
-
-
\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 First Use Flag
-
-
-
-
-
-
-
Next use: \gls{html}.
\end{document}
-
\ul{Some text about \protect\gls{html}.}
\GlsXtrStopUnsetBuffering
Next use: \gls{html}.
\end{document}
-2.6 Plurals
-
@@ -4961,7 +5068,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}.
{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.8 Acronym Style Modifications
-
\printglossaries
\end{document}
\printglossaries
\end{document}
-
-
-
-
-2.9 glossary-bookindex package
-
\usepackage{glossary-bookindex}
\setglossarystyle{bookindex}
-
-
-
-
}
\ifglshasdesc{#1}{\space \glossentrydesc{#1}\glspostdescription}{}%
}
-
-
-
-
-
-
-
-
-
-
-
-
}
-
\par{\centering\glstreegroupheaderfmt{#1}\par}%
}
-