diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex | 165 |
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 |