summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2018-08-19 21:25:32 +0000
committerKarl Berry <karl@freefriends.org>2018-08-19 21:25:32 +0000
commite2d776e4380890862007f3a0b2b6982a081ce452 (patch)
tree2037eaf5f16b76501606244ea4751ae3d8566948 /Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex
parentf94067db8245d94307cfb15701d3e58fda409f3b (diff)
glossaries-extra (19aug18)
git-svn-id: svn://tug.org/texlive/trunk@48437 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex')
-rw-r--r--Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex101
1 files changed, 86 insertions, 15 deletions
diff --git a/Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex b/Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex
index f280413c474..954aa4584f3 100644
--- a/Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex
+++ b/Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex
@@ -226,13 +226,13 @@ styles (glossaries):>#1={\protect\ttfamily#1}|main}}
\DeleteShortVerb{\|}
\MakeShortVerb{"}
- \title{glossaries-extra.sty v1.35:
+ \title{glossaries-extra.sty v1.36:
an extension to the glossaries package}
\author{Nicola L.C. Talbot\\[10pt]
Dickimaw Books\\
\url{http://www.dickimaw-books.com/}}
- \date{2018-08-13}
+ \date{2018-08-18}
\maketitle
\begin{abstract}
@@ -1398,6 +1398,12 @@ See the \sty{soul} example in \sectionref{sec:glsunset}.
\ics{glolinkprefix} to the given value. It should match the prefix
for the desired glossary.
+\item[{\gloskey[glslink]{thevalue}}] Explicitly set the location to
+this value (see below).
+
+\item[{\gloskey[glslink]{theHvalue}}] Set the corresponding
+hyperlink location (see below).
+
\end{description}
There is a new hook that's used each time indexing information is
@@ -1459,7 +1465,7 @@ that can't be obtained from a counter.
The principle key \gloskey[glslink]{thevalue} is for the location value. The
other key \gloskey[glslink]{theHvalue} can be used to
extract a prefix value for the first argument of commands like
-\ics{glsnoidxdisplayloc}. It's value must be in the format
+\ics{glsnoidxdisplayloc}. Its value must be in the format
\meta{prefix}\meta{location}. In general, there's little need for
this key as the prefix is typically associated with a counter that can be
used to form hypertargets.
@@ -1527,7 +1533,7 @@ This location value will be accepted by \app{makeindex} as it's in
the form \meta{num}\meta{sep}\meta{num}.
If you want hyperlinks, things are more complicated. First
-you need to set the \catattr{externallocation} to the location of
+you need to set the \catattr{externallocation} attribute to the location of
the PDF file. For example:
\begin{verbatim}
\glssetcategoryattribute{supplemental}{externallocation}{suppl.pdf}
@@ -1562,6 +1568,14 @@ 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 designated category (identified by the
+\catattr{externallocation} attribute). For multiple sources, you need to use
+\gls{bib2gls} version 1.7+, which is the better method in general as it can
+automatically fetch the relevant locations from the \texttt{.aux}
+files of the designated external documents without the need to
+explicitly use \cs{glsadd}.
+
\section{Cross-References (\qt{see} and \qt{see also})}
\label{sec:see}
@@ -1731,8 +1745,7 @@ In this case \cs{glsentryfmt} uses \ics{glsgenentryfmt}.
\item If an entry does has a~value for the \gloskey{short} key
and hasn't been marked as a~regular entry through the
-\catattr{regular} attribute, it's not
-considered a regular entry.
+\catattr{regular} attribute, it's not considered a regular entry.
In this case \cs{glsentryfmt} uses \ics{glsxtrgenabbrvfmt}
(defined by \styfmt{glossaries-extra}) which is governed
by the abbreviation style (see \sectionref{sec:abbrstyle}).
@@ -2901,7 +2914,14 @@ or use both the \pkgopt{stylemods} and \sty{style} options:
\usepackage[stylemods=bookindex,style=bookindex]{glossaries-extra}
\end{verbatim}
The \glostyle{bookindex} style only supports a maximum
-hierarchical level of 2 (top-level, level~1 and level~2).
+hierarchical level of 2 (top-level, level~1 and level~2). It's
+primarily designed for use with \gls{bib2gls}. It may be used with
+other indexing options, but some features may not be present and
+UTF-8 characters may cause a problem with non-Unicode engines in
+letter group headings or PDF bookmarks. (\gls{bib2gls} uses numeric
+identifies by default to avoid these problems. If numbers show up in
+the group headings instead of the appropriate characters, check that
+you have used the \pkgopt{record} package option.)
The number of columns is given by
\begin{definition}[\DescribeMacro\glsxtrbookindexcols]
@@ -2938,8 +2958,18 @@ For example, if you want the symbol to be included:
\ifglshassymbol{#1}{\space (\glossentrysymbol{#1})}{}%
}
\end{verbatim}
+or if you want the description (if set):
+\begin{verbatim}
+\renewcommand*{\glsxtrbookindexname}[1]{%
+ \glossentryname{#1}%
+ \ifglshasdesc{#1}{\space \glossentrydesc{#1}\glspostdescription}{}%
+}
+\end{verbatim}
+(which picks up the post-description hook).
+
Alternatively you can use the \cs{glsxtrpostname\meta{category}}
-hook.
+hook to append information after the name according to the entry's
+category.
Sub-entries are displayed using
\begin{definition}[\DescribeMacro\glsxtrbookindexsubname]
@@ -5123,7 +5153,7 @@ following punctuation character that's recognised by
The inline full form uses the \meta{short}
(\meta{long}) style. The \gloskey{name} is set to the short form.
The \gloskey{description} is set to the long form.
-Note that this style will change \cs{glsxtrfull} (and it's variants)
+Note that this style will change \cs{glsxtrfull} (and its variants)
so that it fakes non-\gls{firstuse}. (Otherwise the footnote would
appear after the inline form.)
@@ -6476,6 +6506,11 @@ for the external list. For example:
description={external example}}
\end{verbatim}
+\item[\catattrdef{externallocation}] The value should be the
+file name of the target document when manually indexing an
+external location (see \sectionref{sec:wrglossary}). In general,
+it's better to use \gls{bib2gls} v1.7+ which can handle multiple
+external sources and doesn't require this attribute.
\end{description}
@@ -7182,6 +7217,17 @@ added to the index (as in this document).
There are two attributes that govern this: \catattr{indexname}
and \catattr{dualindex}.
+\begin{important}
+The auto-indexing is designed for \gls{makeindex} syntax. If you've
+used the \pkgopt{xindy} package option, the automatic escaping of
+\gls{xindy} special characters in the \gloskey{sort} field may
+result in an incorrect sort value for the \cs{index} command used by
+the auto-indexing. Note also that \app{texindy} has a fixed set of
+special characters (corresponding to \gls{makeindex}['s] defaults)
+that can't be customized. You may want to consider using \gls{bib2gls} and
+its dual entries as an alternative approach.
+\end{important}
+
\begin{sloppypar}
The \ics{glsxtrpostnamehook} macro, used
at the end of \ics{glossentryname} and \ics{Glossentryname},
@@ -7233,6 +7279,16 @@ which needs to be set to the sort value. The default definition is:
After this macro is called, \meta{cs} is then processed to escape
any of \app{makeindex}'s special characters. Note that this
escaping is only performed on the sort not on the actual value.
+The escaping of the sort value is performed by
+\begin{definition}[\DescribeMacro\glsxtrautoindexesc]
+\cs{glsxtrautoindexesc}
+\end{definition}
+You can redefine this to do nothing if you want to omit the
+escaping. You may want to consider providing another field to obtain
+the appropriate sort value if the one provided in the \gloskey{sort}
+field isn't suitable (because it may already have had special
+characters escaped or it may be a numeric value in the case of
+sort by use or definition).
The command used to perform the actual indexing is:
\begin{definition}[\DescribeMacro\glsxtrautoindex]
@@ -7964,6 +8020,21 @@ value in the form \cs{glsxtrbib}\meta{field}. For example,
with \cs{glsxtrbibtype}. Each of these commands takes the entry
label as the sole argument.
+\begin{definition}[\DescribeMacro\glsxtrdisplaysupploc]
+\cs{glsxtrdisplaysupploc}\marg{prefix}\marg{counter}\marg{format}\marg{src}\marg{location}
+\end{definition}
+This is used by \gls{bib2gls} version 1.7+ for supplemental
+locations, instead of using \cs{glsxtrsupphypernumber} with the
+\catattr{externallocation} attribute. This command sets up the
+location counter and prefix (used in the formation of hyperlinks)
+and then uses
+\begin{definition}[\DescribeMacro\glsxtrmultisupplocation]
+\cs{glsxtrmultisupplocation}\marg{location}\marg{src}\marg{format}
+\end{definition}
+to format the actual location (with an external hyperlink, if
+supported).
+
+
The \sty{glossaries-extra-bib2gls} package also provides definitions
of the missing mathematical Greek commands: \ics{Alpha},
\ics{Beta}, \ics{Epsilon}, \ics{Zeta}, \ics{Eta}, \ics{Iota},
@@ -9704,10 +9775,10 @@ avoid duplicate hypertarget names. For example:
}%
\ifcsundef{theHsection}%
{%
- \renewcommand*{\glolinkprefix}{record.#2.\csuse{thesection}.}%
+ \renewcommand*{\glolinkprefix}{record.\csuse{thesection}.}%
}%
{%
- \renewcommand*{\glolinkprefix}{record.#2.\csuse{theHsection}.}%
+ \renewcommand*{\glolinkprefix}{record.\csuse{theHsection}.}%
}%
}
\end{verbatim}
@@ -9724,10 +9795,10 @@ to use:
}%
\ifcsundef{theHsection}%
{%
- \setkeys{printgloss}{targetnameprefix={record.#2.\csuse{thesection}.}}%
+ \setkeys{printgloss}{targetnameprefix={record.\csuse{thesection}.}}%
}%
{%
- \setkeys{printgloss}{targetnameprefix={record.#2.\csuse{theHsection}.}}%
+ \setkeys{printgloss}{targetnameprefix={record.\csuse{theHsection}.}}%
}%
}
\end{verbatim}
@@ -9744,10 +9815,10 @@ space afterwards:
}%
\ifcsundef{theHsection}%
{%
- \renewcommand*{\glolinkprefix}{record.#2.\csuse{thesection}.}%
+ \renewcommand*{\glolinkprefix}{record.\csuse{thesection}.}%
}%
{%
- \renewcommand*{\glolinkprefix}{record.#2.\csuse{theHsection}.}%
+ \renewcommand*{\glolinkprefix}{record.\csuse{theHsection}.}%
}%
\renewcommand*{\glossarysection}[2][]{}%
\appto\glossarypostamble{\glspar\medskip\glspar}%