From 9e987d284eb0915a995e129c61df7c94146b5007 Mon Sep 17 00:00:00 2001
From: Karl Berry
glossaries-extra.sty v1.15: an extension to the
+class="cmr-17">glossaries-extra.sty v1.16: an extension to the
glossaries package
2017-05-10
The file example-glossaries-xr.tex contains dummy entries with cross-references +that may be used for creating minimal working examples for testing the +glossaries-extra package. (The base glossaries package provides additional files, but this +one needs glossaries-extra.)
-
Additional resources:
++
Additional resources:
The The glossaries package is a flexible package, but it’s also a heavy-weight package
that uses a lot of resources. As package developer, I’m caught between those users
who complain about the drawbacks of a heavy-weight package with a large user
manual and those users who want more features (which necessarily adds to the
package weight and manual size).
- The The glossaries-extra package is an attempt to provide a compromise for this
conflict. Version 4.22 of the glossaries package is the last version to incorporate new
@@ -433,10 +443,10 @@ of package loading time and allocation of resources, but those users who do want
extra features available will have more of a chance of getting their feature requests
accepted.
I’m not happy with some of the default settings assumed by the I’m not happy with some of the default settings assumed by the glossaries package,
and, judging from code I’ve seen, other users also seem unhappy with them, as
certain package options are often used in questions posted on various sites. I can’t
@@ -446,7 +456,7 @@ but since glossaries-extra is a separate package, I have decided to implement some of
these commonly-used options by default. You can switch them back if they’re not
appropriate.
- The new defaults are: The new defaults are: The examples below illustrate the difference in explicit package options between
+ The examples below illustrate the difference in explicit package options between
glossaries and glossaries-extra. There may be other differences resulting from
@@ -507,7 +517,7 @@ href="#sec:modifications">§2
+
1.1 Package Defaults
-
\usepackage{glossaries-extra}
This is like: +
This is like: @@ -528,7 +538,7 @@ Commands and Styles
).+
This is like: +
This is like:
@@ -551,7 +561,7 @@ Commands and Styles).
\usepackage[toc,nopostdot,translate=babel]{glossaries}
\usepackage{glossaries-extra}
-
+
This is like: +
This is like:
@@ -572,7 +582,7 @@ Commands and Styles).
\usepackage[toc,nopostdot,noredefwarn]{glossaries}
\usepackage{glossaries-extra}
-
However
@@ -583,7 +593,7 @@ class="cmti-10">However
\usepackage{glossaries}
\usepackage{glossaries-extra}
-
This is like: +
This is like:
@@ -593,19 +603,19 @@ class="cmti-10">However
\usepackage[toc,nopostdot]{glossaries}
\usepackage{glossaries-extra}
-
Since by the time Since by the time glossaries-extra has been loaded, glossaries has already
redefined memoir’s glossary-related commands.
Another noticeable change is that by default Another noticeable change is that by default \printglossary will now display
information text in the document if the external glossary file doesn’t exist. This is
explanatory text to help new users who can’t work out what to do next to complete
the document build. Once the document is set up correctly and the external files have
been generated, this text will disappear.
- This change is mostly likely to be noticed by users with one or more
+ This change is mostly likely to be noticed by users with one or more
redundant empty glossaries who ignore transcript messages, explicitly use
\printglossaries
The above document will only display the list of acronyms at the place where
+ The above document will only display the list of acronyms at the place where
\printglossaries occurs. However it will also attempt to input the .gls file
associated with the main glossary.
- If you use If you use makeglossaries, you’ll get the warning message:
@@ -656,7 +666,7 @@ Warning: File 'test.glo' is empty.
(where the original file is called (where the original file is called test.tex) but if you simply call
No file test.gls.
- This doesn’t occur with This doesn’t occur with makeglossaries as it will create the .gls file containing
the single command \null.
- If you simply change from If you simply change from glossaries to glossaries-extra in this document, you’ll
find a change in the resulting PDF if you don’t use .acr The transcript file will still contain the message about the missing The transcript file will still contain the message about the missing .gls, but now
you’ll also see information in the actual PDF document. The simplest remedy is to
follow the advice inserted into the document at that point, which is to add the
@@ -712,13 +722,13 @@ class="cmss-10">nomain
-
+
+
If you haven’t already loaded If you haven’t already loaded glossaries, you can use any of the package options
provided by glossaries when you load \setupglossariesglossaries
- The new and modified options provided by
+ The new and modified options provided by glossaries-extra are described
below:
If you want to define styles that can interface with the accessibility support
+ If you want to define styles that can interface with the accessibility support
provided by glossaries-accsupp use the §11.2 Note that the Note that the accsupp option can only be used as a package option (not
through glossaries-extra-stylemodsvalue
+
Note that bib2gls can automatically find dependent entries when it
+ parses the .bib source file. The record option automatically implements
+ indexcrossrefs=false.
+ Note that the record=only option automatically implements autoseeindex=false.
+ For example, if an entry is defined as
+
+
+
+ then with autoseeindex=true, this is equivalent to
+
+
+
+ but with autoseeindex=false, this is equivalent to
+
+
+
+ Note that indexcrossrefs isn’t automatically implemented by the presence of the
+ see key when autoseeindex is false.
+ It’s therefore possible to remove the cross-references from the location lists and
+ set their position within the glossary style.
+ Another method of preventing the automatic indexing is to define the entries
+ before the external indexing files have been opened with \makeglossaries.
+ Since the appropriate file isn’t open, the information can’t be written to it.
+ This will need the package option seenoindex=ignore (provided by glossaries) to
+ prevent an error occurring.
+ The option may only be set in the preamble.
- The The option may only be set in the preamble.
+ The record=off option switches off the recording, as per the default behaviour.
+ id="dx1-4040"> option switches off the recording, as per the default behaviour.
It implements undefaction=error.
- The other values switch on the recording and also .
+ The other values switch on the recording and also undefaction=warn,
+ id="dx1-4042">,
but record=only will also switch off the indexing mechanism (even if
+ id="dx1-4043"> will also switch off the indexing mechanism (even if
\makeglossaries or \makenoidxglossaries has been used) whereas
record=alsoindex will both record and index. Note that will both record and index. Note that record=only will prevent
+ id="dx1-4045"> will prevent
the see from automatically implementing from automatically implementing \glssee. (bib2gls deals with the deals with the see
+ id="dx1-4049">
field.) You may explicitly use \glssee in the document, but bib2gls
-
-
-
+ id="dx1-4051">
will ignore the cross-reference if the see field was already set for that
+ id="dx1-4052"> field was already set for that
entry.
- With the recording on, any of the commands that would typically index the
+ The record=only option will automatically set the glossaries package’s sort=none
+ option if available. (That option value was only introduced to glossaries
+ v4.30.)
+ With the recording on, any of the commands that would typically index the
entry (such as \gls, \glstext or \glsadd) will add a \glsxtr@record entry
to the .aux file. bib2gls can then read these lines to find out which entries
+ id="dx1-4056"> can then read these lines to find out which entries
have been used. (Remember that commands like \glsentryname don’t index,
so any use of these commands won’t add a corresponding §9 bib2gls: Managing Reference Databases for
further details.
+
+
+
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-4074">
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-4075">
environment (when used with makeindex or xindy) but the user manual warns
+ id="dx1-4077">makeindex or xindy) but the user manual warns
against this usage. By default the glossaries-extra package prohibits
this, only allowing definitions within the preamble. If you are really
determined to define entries in the document environment, despite all the
+ id="dx1-4079"> environment, despite all the
associated drawbacks, you can restore this with docdef=true. Note that this
+ id="dx1-4081">. 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 further details. A better option if document definitions are
required is docdef=restricted. Only use . Only use docdef=true if document definitions
+ id="dx1-4083"> 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 Note that bib2gls
+
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-4090"> 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-4093"> option provided by the
glossaries package hasn’t been used, then \acronymtype will be set to
+ id="dx1-4094"> will be set to
\glsxtrabbrvtype so that acronyms defined with so that acronyms defined with \newacronym can be added
+ id="dx1-4096"> can be added
to the list of abbreviations. If you want acronyms in the main glossary and
other abbreviations in the main:
- Note that there are no analogous options to the
+ Note that there are no analogous options to the glossaries package’s acronymlists
+ id="dx1-4097">
option (or associated commands) as the abbreviation mechanism is handled
differently with glossaries-extra.
+
which is equivalent to
+
which is equivalent to Note that multiple invocations of the Note that multiple invocations of the shortcuts option option within the same option
list will override each other. After the After the glossaries-extra package has been loaded, you can set available options
using
- The commands used by The commands used by glossaries to automatically produce an error if an entry is
undefined (such as \glsdoifexists\glsdoifexists 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,
\glsdisablehyper this doesn’t switch off hyperlinks
any cross-references within the glossary won’t be affected. This is a way of
avoiding duplicate target warnings if a glossary needs to be displayed multiple
times.
- The \newglossaryentry command has two new keys: The \newglossaryentry command has three new keys: The for further details.
+
+ The test file example-glossaries-xr.tex contains dummy entries with a mixture of
+see, alias and seealso keys for use with minimal working examples.
+ The \longnewglossaryentry command now has a starred version (as from v1.12)
that doesn’t automatically insert
at the end of the description field.
- at the end of the description field.
+
+
The descriptionplural key is left unset unless explicitly set in ⟨ key is left unset unless explicitly set in ⟨options⟩.
- The unstarred version no longer hard-codes the above code (which removes
+ The unstarred version no longer hard-codes the above code (which removes
trailing space and suppresses the post-description hook) but instead uses:
-
+
This can be redefined to allow the post-description hook to work but retain the
\unskip part if required. For example:
@@ -1486,59 +1601,59 @@ class="cmtt-10">\unskip This will discarded unwanted trailing space at the end of the description but won’t
+ This will discarded unwanted trailing space at the end of the description but won’t
suppress the post-description hook.
- The unstarred version also alters the base The unstarred version also alters the base glossaries package’s treatment of the
+ id="dx1-5019"> package’s treatment of the
descriptionplural key. Since a plural description doesn’t make much sense for
+ id="dx1-5020"> key. Since a plural description doesn’t make much sense for
multi-paragraph descriptions, the default behaviour with glossaries-extra’s
+ id="dx1-5021">’s
\longnewglossaryentry is to simply leave the plural description unset
unless explicitly set using the descriptionplural key. The key. The glossaries.sty version
of this command sets the description’s plural form to the same as the
singular.2.1
- Note that this modified unstarred version doesn’t append
+ Note that this modified unstarred version doesn’t append \glsxtrpostlongdescription
to the description’s plural form.
- The The \newterm command (defined through the command (defined through the index package option) is modified
+ id="dx1-5030"> package option) is modified
so that the category defaults to index. The . The \newacronym command is modified
+ id="dx1-5032"> command is modified
to use the new abbreviation interface provided by glossaries-extra. (See §3
Abbreviations.)
- The The \makeglossaries command now has an optional argument.
-
+
If ⟨list⟩ is empty, \makeglossaries behaves as per its original definition in the
@@ -1546,28 +1661,28 @@ class="cmtt-10">\makeglossaries It should then be possible to use It should then be possible to use \printglossary for those glossaries listed in ⟨list⟩
and \printnoidxglossary for the other glossaries. (See the accompanying file
sample-mixedsort.tex for an example.)
-
+ You will need at least version 2.20 of makeglossaries or at least version 1.3 of
the Lua alternative makeglossaries-lite.lua (both distributed with (both distributed with glossaries
v4.27) to allow for this use of \makeglossaries[⟨list⟩]. Alternatively, use the
automake option.
+ id="dx1-5038"> option.
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:
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 after to automatically use this
@@ -1685,22 +1800,22 @@ class="cmtt-10">\GlsXtrSetDefaultGlsOpts 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.)
- 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
@@ -1726,13 +1841,13 @@ class="cmtt-10">\gls For example, suppose the file For example, suppose the file suppl.tex contains:
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
- (By placing (By placing \glsadd at the end of the document, it adds the supplementary location
to the end of the location list, although the ordering may be changed by the indexing
application depending on its location collation settings.)
- If you want hyperlinks, things are more complicated. First you need to set the
+ If you want hyperlinks, things are more complicated. First you need to set the
externallocation to the location of the PDF file. For example:
@@ -1776,21 +1891,21 @@ class="cmss-10">externallocation Next you need to add Next you need to add glsxtrsupphypernumber as the format:
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.
-
- The value of the
+
+ The value of the see key is now saved as a field. This isn’t the case with key is now saved as a field. This isn’t the case with glossaries,
where the see attribute is simply used to directly write a line to the corresponding
+ id="dx1-7002"> value is simply used to directly write a line to the corresponding
glossary file and is then discarded. This is why the see key can’t be used
+ id="dx1-7003"> key can’t be used
before \makeglossaries (since the file hasn’t been opened yet). It’s also the
+ id="dx1-7004"> (since the file hasn’t been opened yet). It’s also the
reason why the see key doesn’t have any effect when used in entries that
+ id="dx1-7005"> key doesn’t have any effect when used in entries that
are defined in the document environment. Since the value isn’t saved, it’s
+ id="dx1-7006"> environment. Since the value isn’t saved, it’s
not available when the .glsdefs file is created at the end of the document
and so isn’t available at the start of the document environment on the next
+ id="dx1-7008"> environment on the next
run.
- 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 was set to false.
+ As a by-product of this enhancement, the see key will now work for entries
+ id="dx1-7012"> key will now work for entries
defined in the document environment, but it’s still best to define entries in the
+ id="dx1-7013"> environment, but it’s still best to define entries in the
preamble, and the see key still can’t perform any indexing before the file has been
+ id="dx1-7015"> key still can’t perform any indexing before the file has been
opened by \makeglossaries. Note that glossaries v4.24 introduced the seenoindex
+ id="dx1-7016">
package option, which can be used to suppress the error when the see key
+ id="dx1-7017"> key
is used before \makeglossaries, so seenoindex=ignore will allow the will allow the see
+ id="dx1-7019">
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 (if
+ id="dx1-7022"> field (if
non-empty). By default, this just does \glsseeformat[⟨tag⟩xr list⟩}{},
which is how the cross-reference is displayed in the number list. Note that
\glsxtrusesee does nothing if the see field hasn’t been set for the entry given by
+ id="dx1-7024"> field hasn’t been set for the entry given by
⟨label⟩.
- Suppose you want to suppress the number list using Suppose you want to suppress the number list using nonumberlist. This
+ id="dx1-7026">. This
will automatically prevent the cross-references from being displayed. The
seeautonumberlist package option will automatically enable the number list for entries
+ id="dx1-7027"> package option will automatically enable the number list for entries
that have the see key set, but this will also show the rest of the number
+ id="dx1-7029"> key set, but this will also show the rest of the number
list.
- 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:
@@ -1947,51 +2067,193 @@ 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 seealso key. Unlike see, this doesn’t have an
+optional part for the textual tag. The syntax seealso={⟨xr-labels⟩} works in
+much the same way as using see=[\seealsoname]{⟨xr-labels⟩} but the
+information is stored in a separate field. If you need a different tag, use the see key
+instead (or redefine \seealsoname or \glsxtruseseealsoformat, described
+below).
+ 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:
+
+
+
+ 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 key. There’s
+no corresponding command to access the see field. If you really need to access it, you
+can use commands like \glsxtrfielduse, but remember that it may start with
+[⟨tag⟩], so it can’t be automatically treated as a simple comma-separated
+list.
+ The base glossaries package provides \glsseelist, which requires a
+comma-separated list of labels as the argument. The argument isn’t fully expanded,
+so it’s not suitable to use, for example, \glsxtrseealsolabels{⟨label⟩} as the
+argument. For convenience, glossaries-extra provides
+
+which fully expands its argument and passes it to \glsseelist.
+ 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
line in the glossary). This text is referred to as the “link-text” regardless of
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 link-text by commands like
+ id="dx1-8002">) used in the link-text by commands like
\gls, , \glsxtrfull, , \glsxtrshort and and \glsxtrlong (but not commands like
+ id="dx1-8007"> (but not commands like
\glslink, , \glsfirst and and \glstext) is changed by glossaries-extra to test for regular
entries, which are determined as follows:
@@ -1999,56 +2261,53 @@ entries, which are determined as follows:
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 now puts \glsgenentry in the argument of
+ id="dx1-8025"> 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
@@ -2079,42 +2338,42 @@ you can redefine \glsxtrregularfont. This is more precise than changing
\glstextformat which will be applied to all linking commands for all entries.
- For example:
+ id="dx1-8027"> which will be applied to all linking commands for all entries.
+ For example:
You can access the label through You can access the label through \glslabel. For example, you can query the
category:
or query the category attribute:
+ or query the category attribute:
or use the attribute to store the control sequence name:
+ or use the attribute to store the control sequence name:
(Remember the category and attribute settings will only queried here for (Remember the category and attribute settings will only queried here for regular
+ id="dx1-8028">
entries, so if the abbreviation style for the acronym category in the above example
+ id="dx1-8029"> category in the above example
changes the regular attribute to “false”, \glsxtrregularfont will no longer
apply.)
- 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
+ id="dx1-8032"> 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.
-
- By default
+ By default \glsxtrpostlink just does \glsxtrpostlink⟨category⟩ if
+ id="dx1-8035"> if
it exists, where ⟨category⟩ is the category label for the current entry. (For
example, for the general category, category, \glsxtrpostlinkgeneral if it has been
defined.)
- The sentence-ending hook is slightly more complicated. If the command
+ The sentence-ending hook is slightly more complicated. If the command
\glsxtrpostlink⟨category⟩ is defined the hook will do that and then insert a
+ id="dx1-8037"> is defined the hook will do that and then insert a
full stop with the space factor adjusted to match the end of sentence. If
\glsxtrpostlink⟨category⟩ hasn’t been defined, the space factor is adjusted to match
+ id="dx1-8038"> hasn’t been defined, the space factor is adjusted to match
the end of sentence. This means that if you have, for example, an entry that ends
with a full stop, a redundant following full stop will be discarded and the space factor
@@ -2208,163 +2467,163 @@ with a full stop, a redundant following full stop will be discarded and the spac
adjusted (in case the entry is in uppercase) unless the entry is followed by additional
material, in which case the following full stop is no longer redundant and needs to be
reinserted.
- There are some convenient commands you might want to use when customizing
+ There are some convenient commands you might want to use when customizing
the post-link-text category hooks:
-
+
This will add the description in parentheses on first use.
- For example, suppose you want to append the description in parentheses on first
+ For example, suppose you want to append the description in parentheses on first
use for entries in the symbol category:
+ id="dx1-8043"> category:
-
+
+
This will append the symbol (if defined) in parentheses on first use.
- If you want to provide your own custom format be aware that you can’t use
+ If you want to provide your own custom format be aware that you can’t use
\ifglsused within the post- within the post-link-text hook as by this point the first use flag will have
been unset. Instead you can use
-
+
This will do ⟨true⟩ if the last used entry was the first use for that entry, otherwise it
+ id="dx1-8050">first use for that entry, otherwise it
will do ⟨false⟩. (Requires at least glossaries v4.19 to work properly.) This command is
locally set by commands like \gls, so don’t rely on it outside of the post-link-text
+ id="dx1-8051">link-text
hook.
-
- For example, if you want to place the description in a footnote after the link-text
+
+ For example, if you want to place the description in a footnote after the link-text
on first use for the first use for the general category:
+ id="dx1-8062"> category:
- The
+ The short-postfootnote abbreviation style uses the post- abbreviation style uses the post-link-text hook to place the
footnote after trailing punctuation characters.
- You can set the default options used by 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:
and then use, for example, and then use, for example, \gls[noindex=false]{sample} when you actually want
the location added to the number list. These defaults may be overridden by other
settings (such as category attributes) in addition to any settings passed in the option
argument of commands like \glslink and \gls.
- Note that if you don’t want Note that if you don’t want any indexing, just omit \makeglossaries and
\printglossaries (or analogous commands). If you want to adjust the
default for wrgloss, it’s better to do this by redefining , it’s better to do this by redefining \glsxtrinitwrgloss
+ id="dx1-8070">
instead.
- Commands like Commands like \gls have star ( have star (*) and plus (+) modifiers as a short cut for
hyper=false and hyper=true. The glossaries-extra package provides a way to add a
third modifier, if required, using
-
+
where ⟨char⟩ is the character used as the modifier and ⟨options⟩ is the default set of
options (which may be overridden). Note that ⟨char⟩ must be a single character (not a
UTF-8 character, unless you are using XƎLATEX or LuaLATEX).
-
- Example:
+
+ Example:
This means that This means that \gls!{sample} will be equivalent to \gls[noindex]{sample}. It’s
not possible to mix modifiers. For example, if you want to do
@@ -2409,23 +2668,23 @@ not possible to mix modifiers. For example, if you want to do
you can use you can use \gls*[noindex]{sample} or \gls![hyper=false]{sample} but you
can’t combine the * and ! modifiers.
- Location lists displayed with \printnoidxglossary internally use
-
+
This command is provided by glossaries, but is modified by glossaries-extra to check
@@ -2446,53 +2705,53 @@ class="cmtt-10">( If the range identifiers aren’t present, this just uses
- If the range identifiers aren’t present, this just uses
+
+
otherwise it uses
-
+
for the start of a range (where the identifier has been stripped from ⟨format⟩)
or
-
+
for the end of a range (where the identifier has been stripped from ⟨format⟩).
- By default the start range command saves the format in
- By default the start range command saves the format in
+
+
and does The end command checks that the format matches the start of the range,
+ The end command checks that the format matches the start of the range,
does
-
+
(which does nothing by default), followed by This means that the list
+ This means that the list
doesn’t display any differently from
+ doesn’t display any differently from
but it does make it easier to define your own custom list handler that can
+ but it does make it easier to define your own custom list handler that can
accommodate the ranges.
-
+
The The \glsenableentrycount command is modified to allow for the For example, instead of just doing:
+ For example, instead of just doing:
you now need to do:
+ you now need to do:
This will enable the entry counting for entries in the This will enable the entry counting for entries in the abbreviation category, but any
+ id="dx1-9003"> 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 Entry Counting.
-
+
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 glossaries package allows 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 sets lets the package sets lets the plural
+ id="dx1-10004">
field default to the value of the text field with field with \glspluralsuffix appended. This
+ id="dx1-10006"> appended. This
command is defined to be just the letter “s”. This means that the majority of terms
don’t need to have the plural supplied as well, and you only need to use it for the
+ id="dx1-10007"> 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
+ id="dx1-10008"> field will always need to
be supplied, where needed.
- There are other plural fields, such as There are other plural fields, such as firstplural, , longplural and and shortplural. Again, if
+ id="dx1-10011">. Again, if
you are using a language that doesn’t have a simple suffix rule, you’ll have to
supply the plural forms if you need them (and if a plural makes sense in the
context).
- 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
shortplural field defaults to the field defaults to the short field with field with \abbrvpluralsuffix appended
+ id="dx1-10034"> appended
unless overridden by category attributes. This suffix command is set by the
abbreviation styles. This means that every time an abbreviation style is
implemented, \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
- So if you want to completely strip all the plural suffixes used for abbreviations then
+ So if you want to completely strip all the plural suffixes used for abbreviations then
you need to redefine \glsxtrabbrvpluralsuffix not \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 which
+ id="dx1-10036"> which
uses the suffix
That is, an apostrophe followed by That is, an apostrophe followed by \abbrvpluralsuffix is appended. The second
attribute is noshortplural which suppresses the suffix and simply sets which suppresses the suffix and simply sets shortplural to the
+ id="dx1-10038"> to the
same as short.
-
+ id="dx1-10039">.
+
Complications arise when you use Things can go wrong if we try the following with the Things can go wrong if we try the following with the glossaries package:
- The main problems are:
+
+ The main problems are:
which just doesn’t work. Grouping the which just doesn’t work. Grouping the \gls{ssi} doesn’t work either as this
will effectively try to do
This will upper case the label This will upper case the label ssi so the entry won’t be recognised.
This problem will also occur if you use the all capitals version, such as
\GLS.
+ id="dx1-11009">.
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
@@ -2885,41 +3144,41 @@ class="cmtt-10">shtml This produces:
+ This produces:
The sample files are either hypertext markup language (HTML)
+ The sample files are either hypertext markup language (HTML)
or server side includes (SSI) enabled HTML (SHTML), but let’s
first discuss SSI. So the So the 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:
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:
@@ -2927,22 +3186,22 @@ 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
instead of displaying “(SHTML)” at the end of the first use, it now
displays “(HTML)”, since \glslabel has been changed to html by
\gls{html}.
- Another oddity occurs if you reset the Another oddity occurs if you reset the html entry between uses of the shtml
entry. For example:
@@ -2950,27 +3209,27 @@ 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 \textsmaller),
+ id="dx1-11023">),
this will produce an odd result.
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 or \glsentryshort in the definition of other entries
+ id="dx1-11032"> in the definition of other entries
(although that doesn’t fix the first problem). Alternatively use something
like:
with with glossaries or:
with with glossaries-extra. This fixes all the above listed problems (as long as you don’t
use \glsdesc). Note that replacing ). Note that replacing \gls with \acrshort in the original example
may fix the first 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:
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
\end{document}
-
Remember to use package option 'nomain' if you
don't want to use the main glossary.
-
\end{document}
-1.2 New or Modified Package Options
-
\glssee{foo}{bar,baz}
+
\glossariesextrasetup{indexcrossrefs=true}
+
\GlsXtrSetField{foo}{see}{bar,baz}
+
\GlsXtrSetField{foo}{see}{bar,baz}
+
-
-
-
-
-
-
-
-
-
-2. Modifications to Existing Commands and Styles
-
-
§10.3 Entry
- Aliases for further details.
-
-
-
-2.1 Entry Indexing
-
-
\glsifattribute{\glslabel}{wrgloss}{after}%
{%
@@ -1663,15 +1778,15 @@ class="cmtt-10">\glsxtrinitwrgloss
}%
}
-
-
\usepackage{glossaries-extra}
\newglossaryentry{sample}{name={sample},description={an example}}
@@ -1743,7 +1858,7 @@ class="cmtt-10">suppl.tex contains:
\gls{sample}.
\end{document}
\usepackage{glossaries-extra}
\makeglossaries
@@ -1764,11 +1879,11 @@ example:
\glsadd[thevalue={S.2}]{sample}
\end{document}
\newglossaryentry{sample}{category=supplemental,
name={sample},description={an example}}
2.2 Cross-References (“see” and “see also”)
+
-
-
-
-
-
-
\ifglshasfield{see}{\glscurrententrylabel}
{, \glsxtrusesee{\glscurrententrylabel}}%
{}%
}
+
+2.2
+\renewcommand*{\glsxtrpostdescgeneral}{%
+
\ifglshasfield{see}{\glscurrententrylabel}
+
{, \glsxtrusesee{\glscurrententrylabel}}%
+
{}%
+
\ifglshasfield{seealso}{\glscurrententrylabel}
+
{ (\glsxtruseseealso{\glscurrententrylabel})}%
+
{}%
+
}
+
+
+
+2.3 Entry Display Style Modifications
-
-
-
\glsifcategory{\glslabel}{general}{\textsf{#1}}{#1}}
\renewcommand*{\glsxtrregularfont}[1]{%
\glsifattribute{\glslabel}{font}{sf}{\textsf{#1}}{#1}}
\glssetcategoryattribute{acronym}{font}{emph}
\renewcommand*{\glsxtrregularfont}[1]{%
@@ -2123,49 +2382,49 @@ category:
{#1}%
}
-
-
-
-
\glsxtrpostlinkAddDescOnFirstUse
}
-
-
\glsxtrifwasfirstuse{\footnote{\glsentrydesc{\glslabel}}}{}%
}
-
-
-
-
-
-
-
\glsxtrdisplaysingleloc{⟨}
-
\glsxtrdisplaysingleloc{⟨\glsxtrlocrangefmt to empty.
-
\glsnoidxdisplayloc{}{page}{textbf}{1},
\glsnoidxdisplayloc{}{page}{)textbf}{1}.
\glsnoidxdisplayloc{}{page}{textbf}{1},
\glsnoidxdisplayloc{}{page}{textbf}{1}.
2.3
2.4 Entry Counting Modifications
-
\glssetcategoryattribute{abbreviation}{entrycount}{1}
2.4
2.5 Plurals
-
-
-2.5
2.6 Nested Links
-
\newacronym{html}{HTML}{Hypertext Markup Language}
\newacronym{shtml}{S\gls{html}}{\gls{ssi} enabled \gls{html}}
first discuss \gls{ssi}.
[description={\acrshort{ssi} enabled \acrshort{html}}]
{shtml}{SHTML}{SSI enabled HTML}
[description={\glsxtrshort{ssi} enabled \glsxtrshort{html}}]
{shtml}{SHTML}{SSI enabled HTML}
\newabbreviation{ssi}{ssi}{server-side includes}
\newabbreviation{html}{html}{hypertext markup language}
\newabbreviation{shtml}{shtml}{\glsabbrvfont{ssi} enabled
\glsabbrvfont{html}}