summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex
diff options
context:
space:
mode:
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.tex188
1 files changed, 179 insertions, 9 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 edac846667d..014415d45a9 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
@@ -79,7 +79,7 @@ description={A command line Java application that selects
entries from a .bib file and converts them to glossary
definitions. At the time of writing, this application
is still under development. Further details at:
-\url{https://github.com/nlct/bib2gls}.}%
+\url{http://www.dickimaw-books.com/software/bib2gls/}.}%
}
\newglossaryentry{numberlist}{%
@@ -141,6 +141,7 @@ governed by the \gloskey{first} and \gloskey{firstplural} keys of
\newcommand*{\igloskey}[2][newglossaryentry]{\icsopt{#1}{#2}}
\newcommand*{\gloskey}[2][newglossaryentry]{\csopt{#1}{#2}}
+\newcommand*{\optfmt}[1]{\textsf{#1}}
\newcommand*{\glostyle}[1]{\textsf{#1}\index{glossary styles:>#1={\protect\sffamily#1}|main}}
@@ -166,13 +167,13 @@ styles (glossaries):>#1={\protect\ttfamily#1}|main}}
\DeleteShortVerb{\|}
\MakeShortVerb{"}
- \title{glossaries-extra.sty v1.13:
+ \title{glossaries-extra.sty v1.14:
an extension to the glossaries package}
\author{Nicola L.C. Talbot\\[10pt]
Dickimaw Books\\
\url{http://www.dickimaw-books.com/}}
- \date{2017-02-07}
+ \date{2017-04-18}
\maketitle
\begin{abstract}
@@ -504,6 +505,11 @@ The other values switch on the recording and also
will also switch off the indexing mechanism (even if \cs{makeglossaries}
or \cs{makenoidxglossaries} has been used) whereas
\pkgopt[alsoindex]{record} will both record and index.
+Note that \pkgopt[only]{record} will prevent the \gloskey{see} from
+automatically implementing \cs{glssee}. (\gls{bib2gls} deals with the
+\gloskey{see} field.) You may explicitly use \cs{glssee} in the
+document, but \gls{bib2gls} will ignore the cross-reference if the
+\gloskey{see} field was already set for that entry.
With the recording on, any of the commands that would typically
index the entry (such as \cs{gls}, \cs{glstext} or \cs{glsadd})
@@ -838,9 +844,10 @@ with \styfmt{glossaries} v4.27) to allow for this use of
\section{Entry Indexing}
\label{sec:wrglossary}
-The \styfmt{glossaries-extra} package provides an extra key for
-commands like \cs{gls} and \cs{glstext} called
-\gloskey[glslink]{noindex}. This is a boolean key. If true,
+The \styfmt{glossaries-extra} package provides extra keys for
+commands like \cs{gls} and \cs{glstext}:
+\begin{description}
+\item[{\gloskey[glslink]{noindex}}] This is a boolean key. If true,
this suppresses the indexing. (That is, it prevents \cs{gls} or
whatever from adding a line to the external glossary file.)
This is more useful than the \pkgopt{indexonlyfirst} package option
@@ -853,6 +860,51 @@ Note that the \gloskey[glslink]{noindex} key isn't available
for \ics{glsadd} (and \ics{glsaddall}) since the whole purpose
of that command is to index an entry.
+\item[{\gloskey[glslink]{wrgloss}}] (New to v1.14.)
+This is may only take the
+values \optfmt{before} or \optfmt{after}. By default, commands
+that both index and display link text (such as \cs{gls},
+\cs{glstext} and \cs{glslink}), perform the indexing before
+the link text as the indexing creates a whatsit that can cause
+problems if it occurs after the link text. However, it may
+be that in some cases (such as long phrases) you may actually
+want the indexing performed after the link text. In this
+case you can use \texttt{wrgloss=after} for specific
+instances. Note that this option doesn't
+have an effect if the indexing has been suppressed through
+other settings (such as \gloskey[glslink]{noindex}).
+
+The default value is set up using
+\begin{definition}[\DescribeMacro\glsxtrinitwrgloss]
+\cs{glsxtrinitwrgloss}
+\end{definition}
+which is defined as:
+\begin{verbatim}
+\newcommand*{\glsxtrinitwrgloss}{%
+ \glsifattribute{\glslabel}{wrgloss}{after}%
+ {%
+ \glsxtrinitwrglossbeforefalse
+ }%
+ {%
+ \glsxtrinitwrglossbeforetrue
+ }%
+}
+\end{verbatim}
+This sets the conditional
+\begin{definition}[\DescribeMacro\ifglsxtrinitwrglossbefore]
+\cs{ifglsxtrinitwrgloss}
+\end{definition}
+which is used to determine where to perform the indexing.
+
+This means you can set the \catattr{wrgloss}
+attribute to \optfmt{after} to automatically use this as
+the default for entries with that category attribute. (Note that
+adding \gloskey[glslink]{wrgloss} to the default options
+in \ics{GlsXtrSetDefaultGlsOpts} will override
+\cs{glsxtrinitwrgloss}.)
+
+\end{description}
+
There is a new hook that's used each time indexing information is
written to the external glossary files:
\begin{definition}[\DescribeMacro\glsxtrdowrglossaryhook]
@@ -864,6 +916,87 @@ accompanying sample file \texttt{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 \cs{glsadd}:
+\gloskey[glsadd]{thevalue} and \gloskey[glsadd]{theHvalue}.
+These keys are designed for manually adding explicit locations
+rather than obtaining the value from the associated counter. (If
+you want an automated method, you might want to investigate \gls{bib2gls}.) This is
+intended primarily for adding locations in supplementary material
+that can't otherwise be picked up by \gls{makeindex} or \gls{xindy}.
+They therefore aren't available for commands like \cs{gls} or
+\cs{glslink}. Remember that the value will still need to
+be a valid location according to the rules of whichever indexing
+application you use.
+
+For example, suppose the file \texttt{suppl.tex} contains:
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage{glossaries-extra}
+
+\newglossaryentry{sample}{name={sample},description={an example}}
+
+\renewcommand{\thepage}{S.\arabic{page}}
+
+\begin{document}
+First page.
+\newpage
+\gls{sample}.
+\end{document}
+\end{verbatim}
+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 \gloskey[glsadd]{thevalue} to \texttt{S.2}. For example:
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage{glossaries-extra}
+
+\makeglossaries
+
+\newglossaryentry{sample}{name={sample},description={an example}}
+
+\begin{document}
+Some \gls{sample} text.
+
+\printglossaries
+\glsadd[thevalue={S.2}]{sample}
+\end{document}
+\end{verbatim}
+(By placing \cs{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 \catattr{externallocation} to the location of
+the PDF file. For example:
+\begin{verbatim}
+\glssetcategoryattribute{supplemental}{externallocation}{suppl.pdf}
+
+\newglossaryentry{sample}{category=supplemental,
+ name={sample},description={an example}}
+\end{verbatim}
+Next you need to add \texttt{glsxtrsupphypernumber} as the format:
+\begin{verbatim}
+\glsadd[thevalue={S.2},format=glsxtrsupphypernumber]{sample}
+\end{verbatim}
+Both documents will need to use the \sty{hyperref} package.
+Remember that the counter used for the location also needs to match.
+If \cs{theH}\meta{counter} is defined in the other document
+and is not the same as \cs{the}\meta{counter}, then you need
+to use \gloskey[glsadd]{theHvalue} to set the appropriate value.
+See the accompanying sample files \texttt{sample-suppl-hyp.tex}
+and \texttt{sample-suppl-main-hyp.tex} for an example that uses
+\sty{hyperref}.
+
+\begin{important}
+The hyperlink for the supplementary location may or \emph{may not}
+take you to the relevant place in the external PDF file
+\emph{depending on your PDF viewer}. Some may not support external
+links, and some may take you to the first page or last visited page.
+\end{important}
+
The value of the \gloskey{see} key is now saved
as a field. This isn't the case with \styfmt{glossaries}, where
the \gloskey{see} attribute is simply used to directly
@@ -1144,7 +1277,9 @@ option argument of commands like \cs{glslink} and \cs{gls}.
Note that if you don't want \emph{any} indexing, just omit
\cs{makeglossaries} and \cs{printglossaries} (or analogous
-commands).
+commands). If you want to adjust the default for
+\gloskey[glslink]{wrgloss}, it's better to do this by redefining
+\ics{glsxtrinitwrgloss} instead.
Commands like \ics{gls} have star (\texttt{*}) and plus
(\texttt{+}) modifiers as a short cut for \texttt{hyper=false}
@@ -1892,6 +2027,26 @@ it's set at the start of the document (if it hasn't been changed in
the preamble). This should take into account situations where
\cs{hsize} isn't set until the start of the document.
+The \sty{glossaries} package tries to determine the group
+title from its label by first checking if
+\cs{}\meta{label}\texttt{groupname} exists. If it doesn't exist,
+then the title is assumed to be the same as the label.
+For example, when typesetting the \qt{A} letter group,
+\sty{glossaries} first checks if \cs{Agroupname} exists.
+This could potentially cause conflict with another package
+that may have some other meaning for \cs{Agroupname}, so
+\sty{glossaries-extra} first checks for the existence
+of the internal command \cs{glsxtr@grouptitle@}\meta{label}
+which shouldn't clash with another package. You can set the
+group title using
+\begin{definition}[\DescribeMacro\glsxtrsetgrouptitle]
+\cs{glsxtrsetgrouptitle}\marg{label}\marg{title}
+\end{definition}
+For example:
+\begin{verbatim}
+\glsxtrsetgrouptitle{A}{A (a)}
+\end{verbatim}
+
\subsection{Style Hooks}
\label{sec:stylehooks}
@@ -3984,6 +4139,10 @@ commands like \cs{gls}.)
\pkgopt{indexonlyfirst} package option but only for entries
that have a category with this attribute set to \qt{true}.
+\item[\catattr{wrgloss}] When using commands like \ics{gls},
+if this attribute is set to \qt{after}, it will automatically
+implement \gloskey[glslink]{wrgloss}\optfmt{=after}. (New to v1.14.)
+
\item[\catattr{discardperiod}] If set to \qt{true}, the
post-\gls{linktext} hook will
discard a~full stop (period) that follows \emph{non-plural} commands like \cs{gls} or
@@ -5339,9 +5498,12 @@ field may not have been set for any of the entries if no
default was provided.
There are now commands provided to set individual fields. Note that
-these only change the specified field, not any related fields. For
+these only change the specified field, not any related values. For
example, changing the value of the \gloskey{text} field won't update
-the \gloskey{plural} field.
+the \gloskey{plural} field. There are also some fields that
+should really only be set when entries are defined (such
+as the \gloskey{parent} field). Unexpected results may occur
+if they are subsequently changed.
\begin{definition}[\DescribeMacro\GlsXtrSetField]
\cs{GlsXtrSetField}\marg{label}\marg{field}\marg{value}
@@ -6115,6 +6277,14 @@ the label.
\item[sample-prefix.tex] Integrate \sty{glossaries-prefix}.
+\item[sample-suppl-main.tex] Uses \gloskey[glsadd]{thevalue} to
+reference a location in the supplementary file
+\texttt{sample-suppl.tex}.
+
+\item[sample-suppl-main-hyp.tex] A more complicated version to the
+above that uses the \sty{hyperref} package to reference a location
+in the supplementary file \texttt{sample-suppl-hyp.tex}.
+
\end{description}
\chapter{Multi-Lingual Support}