diff options
author | Karl Berry <karl@freefriends.org> | 2017-04-18 21:31:32 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2017-04-18 21:31:32 +0000 |
commit | 8e743c86b6872f30b7a35c72aa944455157d4b3f (patch) | |
tree | 1d712f3824ef514604b4f626c4a5f53f290b7aa3 /Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex | |
parent | 684bd5dd12c9a1f9dfdb2093e5250b7e5d8967c2 (diff) |
glossaries-extra (18apr17)
git-svn-id: svn://tug.org/texlive/trunk@43913 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.tex | 188 |
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} |