summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2017-01-19 22:07:21 +0000
committerKarl Berry <karl@freefriends.org>2017-01-19 22:07:21 +0000
commitb83fe0210c4b3eb248892e1c50424808d8880498 (patch)
tree0c1bd465b09edb8c4048b052d168b5c3baaf58e1 /Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex
parent460e2fdeae5c294d5575ad3ad7b3115ad6349c98 (diff)
glossaries-extra (19jan17)
git-svn-id: svn://tug.org/texlive/trunk@42994 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.tex210
1 files changed, 193 insertions, 17 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 5e9f2964f67..b531dedd609 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
@@ -155,13 +155,13 @@ styles (glossaries):>#1={\protect\ttfamily#1}|main}}
\DeleteShortVerb{\|}
\MakeShortVerb{"}
- \title{glossaries-extra.sty v1.10:
+ \title{glossaries-extra.sty v1.11:
an extension to the glossaries package}
\author{Nicola L.C. Talbot\\[10pt]
Dickimaw Books\\
\url{http://www.dickimaw-books.com/}}
- \date{2016-12-17}
+ \date{2017-01-19}
\maketitle
\begin{abstract}
@@ -201,6 +201,8 @@ Additional resources:
\item
\href{http://www.latex-community.org/know-how/latex/55-latex-general/263-glossaries-nomenclature-lists-of-symbols-and-acronyms}{Glossaries,
Nomenclature, Lists of Symbols and Acronyms}.
+
+\item \href{https://github.com/nlct/bib2gls}{bib2gls}
\end{itemize}
\tableofcontents
@@ -469,16 +471,24 @@ default for \styfmt{glossaries}). You can switch this to a warning
message (and ?? appearing in the text) with
\pkgopt[warn]{undefaction}.
+\begin{important}
+Undefined entries can't be picked up by any commands that iterate
+over a glossary list. This includes \ics{forglsentries} and
+\ics{glsaddall}.
+\end{important}
+
\item[{\pkgopt{record}}] (New to v1.08.) This is a \meta{key}=\meta{value}
option, which has three allowed values: \pkgoptfmt{off} (default),
\pkgoptfmt{only} and \pkgoptfmt{alsoindex}. If the value is omitted
\pkgoptfmt{only} is assumed. The option is provided for the benefit
of any post-processing applications that need to know information
-about the entries used in the document. The option may only be set
-in the preamble.
+about the entries used in the document, such as
+\href{https://github.com/nlct/bib2gls}{bib2gls}.\footnote{Still
+under development at the time of writing this.}
+The option may only be set in the preamble.
The \pkgopt[off]{record} option switches off the recording, as per
-the default behaviour. It implements \pkgopt[error]{undefaction}
+the default behaviour. It implements \pkgopt[error]{undefaction}.
The other values switch on the recording and also
\pkgopt[warn]{undefaction}, but \pkgopt[only]{record}
@@ -495,21 +505,43 @@ out which entries have been used. (Remember that commands like
add a corresponding \cs{glsxtr@record} entry to the \texttt{.aux}
file.)
-There are two new commands that are intended for use with the
+There are new commands that are intended for use with the
recording function:
\begin{definition}[\DescribeMacro\glsxtrresourcefile]
\cs{glsxtrresourcefile}\oarg{options}\marg{filename}
\end{definition}
+(Don't include the file extension in \meta{filename}.)
+There's a shortcut version that sets \meta{filename} \cs{jobname}:
+\begin{definition}[\DescribeMacro\GlsXtrLoadResources]
+\cs{GlsXtrLoadResources}\oarg{options}
+\end{definition}
+(Only one instance of \cs{GlsXtrLoadResources} is permitted
+per document. Use \cs{glsxtrresourcefile} for any additional
+resources.)
+
This writes the line
\begin{alltt}
\cs{glsxtr@resource}\marg{options}\marg{filename}
\end{alltt}
-to the \texttt{.aux} file and, if \meta{filename} exists, will then
-input \meta{filename}. The post-processor may use this information
-to create the required file. The options aren't processed by
+to the \texttt{.aux} file and will input
+\meta{filename}\texttt{.glstex} if it exists.\footnote{v1.08 assumed
+\meta{filename}\texttt{.tex} but that's potentially dangerous if,
+for example, \meta{filename} happens to be the same as \cs{jobname}.
+The \texttt{.glstex} extension was enforced by version 1.11.} The post-processor may use this information
+to create the required file. (This is why the \pkgopt{record}
+option automatically switches on \pkgopt[warn]{undefaction},
+to allow the document to compile before the post-processor
+has created the \texttt{.glstex} file.)
+
+The options aren't processed by
\styfmt{glossaries-extra} (other than simply writing \meta{options}
to the \texttt{.aux} file). The post-processor determines the
-allowed options.
+allowed options. As from v1.11, this command also writes other
+information to the \texttt{.aux} file for the benefit of the
+post-processor, including the list of valid keys allowed by
+\cs{newglossaryentry} so make sure you add any custom keys
+before using \cs{glsxtrresourcefile} or \cs{GlsXtrLoadResources}
+if the post-processor needs that information.
\begin{definition}[\DescribeMacro\printunsrtglossary]
\cs{printunsrtglossary}\oarg{options}
@@ -517,12 +549,32 @@ allowed options.
This behaves like \cs{printnoidxglossary} but never sorts the
entries and always lists all the defined entries for the given
glossary (and doesn't require \cs{makenoidxglossaries}).
-The optional argument is as for \cs{printnoidxglossary}.
+
+\begin{important}
+You may use this command without the \pkgopt{record} option
+or \cs{glsxtrresourcefile} if you're happy to have a complete
+unsorted list without \glspl{numberlist}. However this requires
+all entries to have been defined before use, so if you've used the
+\pkgopt{docdefs} package option with definitions after the glossary,
+you'll need a second \LaTeX\ run to pick up the definitions from the
+\texttt{.glsdefs} file.
+\end{important}
+
+The optional argument is as for \cs{printnoidxglossary} (except for
+the \gloskey[printnoidxglossary]{sort} key, which isn't available).
The \gls{numberlist} will need setting by the post-processor
-by adding the \gloskey{loclist} field to the entry definitions,
-otherwise the \gls*{numberlist} will be empty. The \gloskey{loclist}
-field should be a comma-separated list where each location in the
-list is in the format
+by adding the \gloskey{loclist} or \gloskey{location} field to the entry definitions,
+otherwise the \gls*{numberlist} will be empty. (If both the
+\gloskey{loclist} and \gloskey{location} fields are set, the
+\gloskey{location} field will be used in the glossary.)
+
+The \gloskey{location} field should contain the relevant commands to
+format the \gls{numberlist}. There's no specific syntax for this
+field, it just needs to contain valid \LaTeX\ commands.
+
+The \gloskey{loclist} field should be a list separated by
+\verb"|" (as per \sty{etoolbox}'s internal lists) where each
+location in the list is in the format
\begin{definition}
\cs{glsnoidxdisplayloc}\marg{prefix}\marg{counter}\marg{format}\marg{location}
\end{definition}
@@ -740,6 +792,12 @@ The commands used by \styfmt{glossaries} to automatically produce an
error if an entry is undefined (such as \ics{glsdoifexists}) are
changed to take the \pkgopt{undefaction} option into account.
+The \ics{newignoredglossary}\marg{type} command now (as from v1.11) has a starred
+version that doesn't automatically switch off the hyperlinks.
+This starred version may be used with the \catattr{targeturl}
+attribute to create a link to an external URL. (See
+\sectionref{sec:categories} for further details.)
+
The \cs{newglossaryentry} command has a new key called
\gloskey{category}, which sets the category label for the given
entry. By default this is \texttt{general}. See
@@ -763,7 +821,8 @@ that need processing with an external indexing application.
It should then be possible to use \cs{printglossary} for those
glossaries listed in \meta{list} and \cs{printnoidxglossary}
-for the other glossaries.
+for the other glossaries. (See the accompanying file
+\texttt{sample-mixedsort.tex} for an example.)
\begin{important}
If you use the optional argument \meta{list}, you can't define
@@ -771,7 +830,7 @@ entries in the document (even with the \pkgopt{docdef} option).
\end{important}
You will need at least version 2.20 of \gls{makeglossaries} or at
-least version 1.3 of \gls{makeglossaries-lite.lua} (both distributed
+least version 1.3 of the Lua alternative \gls{makeglossaries-lite.lua} (both distributed
with \styfmt{glossaries} v4.27) to allow for this use of
\cs{makeglossaries}\oarg{list}. Alternatively, use the
\pkgopt{automake} option.
@@ -3910,6 +3969,68 @@ through commands like \ics{gls} and \ics{glsadd}, a~corresponding
line will be written to the indexing file using \ics{index}. See
\sectionref{sec:autoindex} for further details.
+\item[\catattr{targeturl}] If set, the hyperlink generated by
+commands like \cs{gls} will be set to the URL provided by this
+attributes value. For example:
+\begin{verbatim}
+\glssetcategoryattribute{general}{targeturl}{master-doc.pdf}
+\end{verbatim}
+(See also the accompanying sample file
+\texttt{sample-external.tex}.) If the URL contains awkward
+characters (such as \verb|%| or \verb|~|) remember that the base
+\styfmt{glossaries} package provides commands like
+\ics{glspercentchar} and \cs{glstildechar} that expand to literal
+characters.
+
+If you want to a named anchor within the target URL (notionally
+adding \texttt{\#}\meta{name} to the URL), then you also
+need to set \catattr{targetname} to the anchor \meta{name}. You may
+use \cs{glslabel} within \meta{name} which is set by commands
+like \cs{gls} to the entry's label.
+
+All the predefined glossary styles start each entry
+listing with \cs{glstarget} which sets the anchor to
+\verb|\glolinkprefix\glslabel|, so if you want entries to link
+to glossaries in the URL given by \catattr{targeturl}, you
+can just do:
+\begin{verbatim}
+\glssetcategoryattribute{general}{targetname}{\glolinkprefix\glslabel}
+\end{verbatim}
+(If the target document changed \cs{glolinkprefix} then you will
+need to adjust the above as appropriate.)
+
+If the anchor is in the form \meta{name1}\texttt{.}\meta{name2}
+then use \catattr{targetname} for the \meta{name2} part and
+\catattr{targetcategory} for the \meta{name1} part.
+
+For example:
+\begin{verbatim}
+\glssetcategoryattribute{general}{targeturl}{master-doc.pdf}
+\glssetcategoryattribute{general}{targetcategory}{page}
+\glssetcategoryattribute{general}{targetname}{7}
+\end{verbatim}
+will cause all link text for \texttt{general} entries to
+link to \texttt{master-doc.pdf\#page.7} (page 7 of that PDF).
+
+If you want a mixture in your document of entries that link to
+an internal glossary and entries that link to an external URL
+then you can use the starred form of \ics{newignoredglossary}
+for the external list. For example:
+\begin{verbatim}
+\newignoredglossary*{external}
+
+\glssetcategoryattribute{external}{targeturl}{master-doc.pdf}
+\glssetcategoryattribute{general}{targetname}{\glolinkprefix\glslabel}
+
+\newglossaryentry{sample}{name={sample},description={local example}}
+
+\newglossaryentry{sample2}{name={sample2},
+ type=external,
+ category=external,
+ description={external example}}
+\end{verbatim}
+
+
\end{description}
An attribute can be set using:
@@ -4624,6 +4745,53 @@ don't use any commands in the \meta{label}, even if they expand
to just text.
\end{important}
+\chapter{Miscellaneous New Commands}
+\label{sec:miscnew}
+
+The \styfmt{glossaries} package provides \ics{glsrefentry} entry to
+cross-reference entries when used with the \pkgopt{entrycounter} or
+\pkgopt{subentrycounter} options. The \styfmt{glossaries-extra}
+package provides a supplementary command
+\begin{definition}[\DescribeMacro\glsxtrpageref]
+\cs{glsxtrpageref}\marg{label}
+\end{definition}
+that works in the same way except that it uses \ics{pageref}
+instead of \ics{ref}.
+
+As mentioned in the description for the \pkgopt{record} package
+option described in \sectionref{sec:pkgopts}, there's a new way of
+printing a glossary without sorting or indexing:
+\begin{definition}
+\ics{printunsrtglossary}\oarg{options}
+\end{definition}
+To iterate over all glossaries:
+\begin{definition}
+\ics{printunsrtglossaries}
+\end{definition}
+
+However, you can also uses these commands together with a
+post-processor that works with the \pkgopt{record} package option and
+\begin{definition}
+\ics{glsxtrresourcefile}\oarg{options}{filename}
+\end{definition}
+or
+\begin{definition}
+\ics{GlsXtrLoadResources}\oarg{options}
+\end{definition}
+At the time of writing this,
+there is a new post-processor under development called
+\href{https://github.com/nlct/bib2gls}{bib2gls} that can be used in
+this way to fetch glossary entries stored in a \texttt{.bib} file,
+selecting only those referenced in the document. It then creates a
+\texttt{.glstex} file with the relevant definitions defined in the
+order indicated in by \meta{options}. Since the order of definition
+is already in the appropriate order, there's no need for any
+additional sorting by \gls{makeindex} or \gls{xindy}. (It is however
+possible to use \gls{makeindex}\slash\gls{xindy} in combination
+with the post-processor by setting \pkgopt[alsoindex]{record} and using
+\cs{makeglossaries} and \cs{printglossaries} as usual. For example,
+if you require custom \gls{xindy} rules.)
+
\chapter{Supplemental Packages}
\label{sec:supplemental}
@@ -4929,6 +5097,14 @@ to only have one hyperlink per entry per page.
\item[sample-altmodifier.tex] Set the default options for
commands like \cs{gls} and add an alternative modifier.
+\item[sample-mixedsort.tex] Uses the optional argument
+of \cs{makeglossaries} to allow a mixture of \cs{printglossary}
+and \cs{printnoidxglossary}.
+
+\item[sample-external.tex] Uses the \catattr{targeturl} attribute
+to allow for entries that should link to an external URL
+rather than to an internal glossary.
+
\item[sample-alttree.tex] Uses the \sty{glossaries-extra-stylemods}
package with the \glostyle{alttree} style (see \sectionref{sec:stylemods}).