summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex')
-rw-r--r--Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex165
1 files changed, 132 insertions, 33 deletions
diff --git a/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex b/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex
index 8b39cc03f24..b1cd27efc69 100644
--- a/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex
+++ b/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex
@@ -22,10 +22,9 @@
% files in the examples directory, then you need to run arara on
% each .tex file (which will call pdfcrop where applicable).
%
-% This document requires glossaries-extra v1.49, bib2gls v3.0
+% This document requires glossaries-extra v1.49+, bib2gls v3.0+
% and nlctuserguide.sty. Some of the example documents require
-% glossaries v4.50 and mfirstuc v2.08. If they haven't already
-% been uploaded to CTAN, they will be shortly.
+% glossaries v4.50+ and mfirstuc v2.08+.
\documentclass[titlepage=false,oneside,toc=listof,
fontsize=12pt,captions=tableheading]{scrbook}
@@ -36,6 +35,8 @@
deephierarchy,
numberedsection,
abbreviations,
+ tikzsymbols,
+ indexmarks,
%debug=showwrgloss,
%showtargets=annoteleft
]{nlctuserguide}
@@ -46,6 +47,8 @@
\GetTitleStringSetup{expand}
+\RedeclareSectionCommand[tocnumwidth=35pt]{section}
+
\renewcommand*{\thispackagename}{glossaries}
\renewcommand{\cmdnotefmt}[1]{}
@@ -75,11 +78,11 @@ build}}}
\MFUblocker{\csfmt}
-\newcommand{\combase}{\comment{\glslink{pkg.glossaries-extra}{glossaries.sty}}}
-\newcommand{\comxr}{\comment{\glslink{pkg.glossaries-extra}{glossaries-extra.sty}}}
-\newcommand{\comxronly}{\comment{\glslink{pkg.glossaries-extra}{glossaries-extra.sty} only}}
-\newcommand{\comxrkey}{\comment{\glslink{pkg.glossaries-extra}{glossaries-extra.sty} key}}
-\newcommand{\comxropt}[1]{\comment{requires \glslink{pkg.glossaries-extra}{glossaries-extra.sty} '\opt{#1}' option}}
+\newcommand{\combase}{\commentnl{\glslink{pkg.glossaries-extra}{glossaries.sty}}}
+\newcommand{\comxr}{\commentnl{\glslink{pkg.glossaries-extra}{glossaries-extra.sty}}}
+\newcommand{\comxronly}{\commentnl{\glslink{pkg.glossaries-extra}{glossaries-extra.sty} only}}
+\newcommand{\comxrkey}{\commentnl{\glslink{pkg.glossaries-extra}{glossaries-extra.sty} key}}
+\newcommand{\comxropt}[1]{\commentnl{requires \glslink{pkg.glossaries-extra}{glossaries-extra.sty} '\opt{#1}' option}}
\newcommand{\location}{\idxc{entrylocation}{location}}
\newcommand{\locations}{\idxc{entrylocation}{locations}}
@@ -136,11 +139,12 @@ build}}}
\newcommand{\glosfielddef}[1]{\inlineglsdef[optdef]{opt.glosfield.#1}}
\newcommand{\glostypedef}[1]{\inlineglsdef[optdef]{opt.glostype.#1}}
\newcommand{\glsoptdef}[1]{\inlineglsdef[optdef]{opt.glsopt.#1}}
-\newcommand{\printglossoptdef}[1]{\inlineglsdef[optdef]{opt.printgloss.#1}}
\newcommand{\inlineglostyledef}[1]{\inlineglsdef[optdef]{opt.glostyle.#1}}
\newcommand{\glostyledef}[1]{\optiondef{glostyle.#1}}
+\newcommand{\printglossoptdef}[1]{\optiondef{printgloss.#1}}
+
\defsemanticcmd[style2]{\glostypefmt}{\texttt}{}
\glsxtrnewgls{opt.glostype.}{\glostype}
@@ -5403,6 +5407,45 @@ cs}\margm{\gls{glspl}-like cs}\margm{\gls{Gls}-like cs}\margm{\gls{Glspl}-like c
information if \opteqvalref{debug}{showtargets}. This uses \gls{hypertarget}
but measures the height of \meta{text} so that the target can
be placed at the top of \meta{text} instead of along the baseline}
+ \field{seealso}{glsdohyperlink,glsdohypertargethook}
+ }
+ % \glsdohypertargethook
+ \gcmd{gls\-do\-hyper\-target\-hook}
+ {
+ \providedby{\sty{glossaries} v4.54+}
+ \syntax{\margm{target}\margm{text}}
+ \desc{hook used by \gls{glsdohypertarget}. Does nothing by default}
+ }
+ % \glslabelhypertarget
+ \gcmd{gls\-label\-hyper\-target}
+ {
+ \providedby{\sty{glossaries} v4.54+}
+ \syntax{\margm{target}\margm{text}}
+ \desc{may be used in the definition of \gls{glsdohypertargethook}
+ to simulate a label corresponding to the target where the label is
+ given by \code{\gls{glslabelhypertargetprefix}\meta{target}}}
+ }
+ % \glslabelhypertargetprefix
+ \gcmd{gls\-label\-hyper\-target\-prefix}
+ {
+ \initvalempty
+ \providedby{\sty{glossaries} v4.54+}
+ \desc{expands to the prefix used for the label created by
+ \gls{glslabelhypertarget}}
+ }
+ % \glslabelhypertargetdefs
+ \gcmd{gls\-label\-hyper\-target\-defs}
+ {
+ \providedby{\sty{glossaries} v4.54+}
+ \desc{hook used by \gls{glslabelhypertarget} to locally redefine
+ problematic commands}
+ }
+ % \glslabelhypertargetvalue
+ \gcmd{gls\-label\-hyper\-target\-value}
+ {
+ \providedby{\sty{glossaries} v4.54+}
+ \desc{expands to the value part of the label created by
+ \gls{glslabelhypertarget}}
}
% \glsdohyperlink
\gcmd{gls\-do\-hyper\-link}
@@ -5412,7 +5455,14 @@ cs}\margm{\gls{glspl}-like cs}\margm{\gls{Gls}-like cs}\margm{\gls{Glspl}-like c
\desc{creates a hyperlink to the given target using
\gls{hyperlink}, and includes the debugging
information if \opteqvalref{debug}{showtargets}}
- \field{seealso}{glsdohypertarget,glsdonohyperlink}
+ \field{seealso}{glsdohypertarget,glsdonohyperlink,glsdohyperlinkhook}
+ }
+ % \glsdohyperlinkhook
+ \gcmd{gls\-do\-hyper\-link\-hook}
+ {
+ \providedby{\sty{glossaries} v4.54+}
+ \syntax{\margm{target}\margm{text}}
+ \desc{hook used by \gls{glsdohyperlink}. Does nothing by default}
}
% \glsdonohyperlink
\gcmd{gls\-do\-no\-hyper\-link}
@@ -10804,6 +10854,7 @@ formats}
\gcmd{At\-Be\-gin\-Doc\-u\-ment}{}% \AtBeginDocument
\gcmd{cite}{}% \cite
\gcmd{ref}{}% \ref
+ \gcmd{page\-ref}{}% \pageref
\gcmd{label}{}% \label
\gcmd{caption}{}% \caption
\gcmd{section}{}% \section
@@ -11502,11 +11553,11 @@ formats}
{\begin{information}[title={\app{bib2gls}}]}
{\end{information}}
-\title{User Manual for glossaries.sty v4.53}
+\title{User Manual for glossaries.sty v4.54}
\author{Nicola L.C. Talbot\\%
\href{http://www.dickimaw-books.com/contact}{\nolinkurl{dickimaw-books.com/contact}}}
-\date{2023-09-29}
+\date{2024-04-03}
\begin{document}
\maketitle
@@ -11590,7 +11641,7 @@ package.
\begin{itemdesc}
Advanced users wishing to know more about the inner workings of all the
packages provided in the \styfmt{glossaries} bundle should read
-\qt{Documented Code for glossaries v4.53}.
+\qt{Documented Code for glossaries v4.54}.
\end{itemdesc}
\itemtitle{\url{CHANGES}}
@@ -11692,7 +11743,8 @@ format certain types of terms, such as \idxpl{acronym}, or you may
prefer to have descriptions scattered about the document and be able
to easily link to the relevant description (\option{standalone}).
-The simplest document is one without a glossary:
+\mExampleref{ex:simplenogloss} demonstrates a simple document
+without a glossary:
\begin{codebox}
\cmd{documentclass}\marg{article}
\cmd{usepackage}[
@@ -11793,7 +11845,7 @@ The \sty{glossaries-extra} package, which is distributed as a
separate bundle, extends the capabilities of the \sty{glossaries}
package. The simplest document with a \idx{glossary} can be created
with \sty{glossaries-extra} (which internally loads the
-\sty{glossaries} package):
+\sty{glossaries} package). \mExampleref{ex:simpleunsrt} demonstrates this:
\begin{codebox}
\cmd{documentclass}\marg{article}
\cmd{usepackage}[
@@ -12234,7 +12286,7 @@ completeness and for comparison with the actual \idx{indexing} options.
This option isn't generally recommended for reasons given below.
It's best used with \opteqvalref{sort}{use} (order of use) or
\opteqvalref{sort}{def} (order of definition).
-Example Document:
+\mExampleref{ex:noidx} demonstrates this method:
\begin{codebox}
\cmd{documentclass}\marg{article}
\cmd{usepackage}[\optval{style}{\glostyle{indexgroup}}]\marg{glossaries}
@@ -12383,7 +12435,8 @@ Summary:
\subsection{\idxoptiondef{mkidx}}\label{option2}
-\glsadd{app.makeindex}Example document:
+\glsadd{app.makeindex}\mExampleref{ex:mkidx} demonstrates a simple
+document that requires \app{makeindex}:
\begin{codebox}
\cmd{documentclass}\marg{article}
\cmd{usepackage}[\optval{style}{\glostyle{indexgroup}}]\marg{glossaries}
@@ -12611,7 +12664,8 @@ you have any cross-references which can't be \indexed\ until the
\subsection{\idxoptiondef{xdy}}\label{option3}
-\glsadd{app.xindy}Example document:
+\glsadd{app.xindy}\mExampleref{ex:xdy} demonstrates a simple document that
+requires \app{xindy}:
\begin{codebox}
\cmd{documentclass}\marg{article}
\cmd{usepackage}[\strong{\opt{xindy}},\optval{style}{\glostyle{indexgroup}}]\marg{glossaries}
@@ -12837,7 +12891,7 @@ build} for some examples.
\app{bib2gls} to both fetch \idx{entry} definitions from \ext+{bib} files
and to hierarchically sort and collate.
-Example document:
+\mExampleref{ex:b2g} demonstrates a simple document that requires \app{bib2gls}:
\begin{codebox*}
\cmd{documentclass}\marg{article}
\cmd{usepackage}[\strong{\opt{record}},\optval{style}{\glostyle{indexgroup}}]\marg{\strong{glossaries-extra}}
@@ -13073,7 +13127,7 @@ build}.
This option is only available with the extension package
\sty{glossaries-extra}. No \idx{indexingapp} is required.
-Example document:
+\mExampleref{ex:unsrt} demonstrates this method:
\begin{codebox}
\cmd{documentclass}\marg{article}
\cmd{usepackage}[\optval{style}{\glostyle{indexgroup}}]\marg{glossaries-extra}
@@ -13212,7 +13266,7 @@ document. The entry name may or may not be in a section heading.
You can either define entries in the \idx{documentpreamble} (or in an
external file loaded with \gls{loadglsentries}), as with
-\option{unsrt}, for example:
+\option{unsrt}. \mExampleref{ex:standalone} demonstrates standalone definitions:
\begin{codebox*}
\cmd{documentclass}\marg{article}
\codepar
@@ -17075,7 +17129,7 @@ This valueless option switches off \opt{index} if \opt{index} has
been passed implicitly (for example, through global document
options). This option can't be used in \gls{setupglossaries}.
-\section{\Glsfmttext{idx.acronym} and \Glsfmttext{idx.abbreviation} Options}
+\section{Acronym and Abbreviation Options}
\label{sec:pkgopts-acronym}
\glsaddeach{idx.acronym,idx.abbreviation}%
@@ -17603,7 +17657,7 @@ formats, then do:
See \sectionref{sec:numberlists} for further information about
\idxpl{numberlist}.
-\chapter{Defining \Glsfmtplural{idx.glossaryentry}}
+\chapter{Defining Glossary Entries}
\label{sec:newglosentry}
\begin{bib2gls}
@@ -17738,7 +17792,7 @@ to suppress the description terminator for this entry. For example, if this
entry is a parent entry that doesn't require a description, you
can do \gloskeyval{description}{\gls{nopostdesc}}. If you want a paragraph
break in the description use:
-\cmddef{glspar}
+\cmddef*{glspar}
or, better, use \gls{longnewglossaryentry}.
However, note that not all \idxpl{glossarystyle} support multi-line
descriptions. If you are using one of the tabular-like
@@ -18800,7 +18854,7 @@ after \qt{greekletter} and before \qt{romanletter}.
\end{xtr}
\end{example}
-\subsection{\Glsfmtplural{homograph}}
+\subsection{Homographs}
\label{sec:homographs}
\glsadd{homograph}%
@@ -20128,7 +20182,7 @@ manual for further details.
\end{xtr}
-\subsection{Enabling and Disabling \Glsfmtplural{idx.hyperlink} to Glossary Entries}
+\subsection{Enabling and Disabling Hyperlinks to Glossary Entries}
\label{sec:disablehyperlinks}
If you load \sty{hyperref} prior to loading the \sty{glossaries}
@@ -20557,7 +20611,8 @@ before the parentheses.
The way the \idx{acronym} is displayed on \idx{firstuse} is
governed by the \idx{acronymstyle} that's identified with
\gls{setacronymstyle}. This should be set before you define
-your \idxpl{acronym}. For example:
+your \idxpl{acronym}. \mExampleref{ex:simpleacronyms} demonstrates the
+use of \gls{newacronym}:
\begin{codebox}
\cmd{documentclass}\marg{article}
\cmd{usepackage}\marg{glossaries}
@@ -20669,7 +20724,7 @@ effect unless you explicitly set
\gls{newacronym}. See \sectionref{sec:loadglsentries}.
\end{important}
-The following defines the \idx{acronym} IDN and then uses it in the
+\mExampleref{ex:newacronym} defines the \idx{acronym} IDN and then uses it in the
document text. It then resets the \idx{firstuseflag} and uses it
again.
\begin{codebox}
@@ -21018,9 +21073,10 @@ first instance of \gls{newacronym} will automatically implement:
\begin{codebox}
\gls{setacronymstyle}\marg{\acrstyle{long-short}}
\end{codebox}
-which is the closest match to the old default. The earlier
-\exampleref{ex:newacronym} can be adjusted to use rollback to
-demonstrated the difference:
+which is the closest match to the old default.
+\mExampleref{ex:newacronymrollback} is a modification of the earlier
+\exampleref{ex:newacronym} so that it uses rollback in order to
+demonstrate the difference:
\begin{codebox}
\cmd{usepackage}\marg{glossaries}[=v4.46]\comment{rollback to v4.46}
\comment{no \gls{setacronymstyle} so old style used}
@@ -21114,6 +21170,7 @@ small capital glyphs for \idx{lowercase} letters but normal sized
capital glyphs for \idx{uppercase} letters, which means there's no
visual difference between a normal upright font and a
\idx{smallcaps} font if the text is in \idx{allcaps}.
+This is demonstrated in \mexampleref{ex:longscshort}:
\begin{coderesult}
\gls{setacronymstyle}\marg{\acrstyle{long-sc-short}}
\gls{newacronym}\marg{mathml}\marg{MathML}\marg{mathematical markup language}
@@ -22600,9 +22657,9 @@ makeglossaries myDoc
pdflatex myDoc
\end{terminal}
-In the following document, the \idxpl{acronym} that have only been used once
+In \mexampleref{sec:entrycount}, the \idxpl{acronym} that have only been used once
(on the previous run) only have their long form shown with
-\gls{cgls}.
+\gls{cgls}:
\begin{codebox}
\cmd{documentclass}\marg{article}
\codepar
@@ -27989,6 +28046,48 @@ The corresponding command that's used to link to this target is:
This includes the debugging information, if applicable, and creates
a link with \gls{hyperlink}.
+Both the above target and link commands have a corresponding hook that does
+nothing by default. These commands are not used if hyperlinks have been
+disabled (or if \sty{hyperref} has not been loaded).
+\cmddef{glsdohypertargethook}
+This hook occurs after the height of the \meta{text} has been measured and
+before the target is inserted.
+
+\cmddef{glsdohyperlinkhook}
+This hook occurs immediately before the link is created with \gls{hyperlink}.
+
+\cmddef{glslabelhypertarget}
+This command is provided for use in \gls{glsdohypertargethook} and will simulate
+a label corresponding to the target. It's primarily intended for use with
+\gls{pageref} rather than \gls{ref} as there is no corresponding counter
+to provide a numeric value. It is an alternative to using the \opt{entrycounter}
+option. The label is given by \code{\meta{prefix}\meta{target}}, where the
+\meta{prefix} is obtained by expanding:
+\cmddef{glslabelhypertargetprefix}
+The target \meta{text} will be the title corresponding to the label (which
+can be referenced with \gls{nameref}). Since there is no numeric value,
+the text obtained with \gls{ref} will either be empty or the name of the most recent
+entry in the glossary list where the hypertarget occurs.
+For example:
+\begin{codebox}
+\cmd{renewcommand}\marg{\gls{glsdohypertargethook}}[2]\marg{\gls{glslabelhypertarget}\marg{\#1}\marg{\#2}}
+\end{codebox}
+Certain commands that may occur in the \meta{text} argument, such as
+\gls{glossentryname}, are locally redefined during the protected write
+to the \ext{aux} file. These redefinitions are performed by:
+\cmddef{glslabelhypertargetdefs}
+You can append any additional redefinitions of problematic commands to this
+hook.
+
+The \qt{value} part of the label (that is, the text produced with \gls{ref}) is
+obtained by expanding:
+\cmddef{glslabelhypertargetvalue}
+The default definition expands
+\begin{compactcodebox}
+\gls{glsentryname}\gls{glscurrententrylabel}
+\end{compactcodebox}
+if \gls{glscurrententrylabel} is defined and not empty. Otherwise it expands to nothing.
+
\cmddef{glstexorpdfstring}
If you're not sure whether or not the \sty{hyperref} package will be
loaded, this command will use \gls{texorpdfstring} if