diff options
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.tex | 210 |
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}). |