diff options
author | Karl Berry <karl@freefriends.org> | 2015-07-08 22:32:47 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2015-07-08 22:32:47 +0000 |
commit | e1218e4d5ddcb68ac921c718bbe7a537af862583 (patch) | |
tree | b77730b9572c833245ca5b3a0f4389e16dd72fa3 /Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex | |
parent | 4cc63125c198c95120c614619f6adca51ed8b7e3 (diff) |
glossaries (8jul15)
git-svn-id: svn://tug.org/texlive/trunk@37808 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex | 1055 |
1 files changed, 999 insertions, 56 deletions
diff --git a/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex b/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex index bf307e4c510..878b1bff733 100644 --- a/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex +++ b/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex @@ -133,6 +133,17 @@ to \gls{xindy} and \gls{makeindex} provided with the \styfmt{glossaries} package.} } +\newglossaryentry{makeglossaries-lite.lua}{% +name={\appfmt{makeglossaries-lite.lua}\index{makeglossaries-lite.lua=\appfmt{makeglossaries-lite.lua}|htextbf}},% +sort={makeglossaries-lite.lua},% +text={\appfmt{makeglossaries-lite.lua}\iapp{makeglossaries-lite.lua}},% +description={A custom designed Lua script interface +to \gls{xindy} and \gls{makeindex} provided with the \styfmt{glossaries} +package. This is a cut-down alternative to the Perl +\appfmt{makeglossaries} script. If you have Perl installed, use the +Perl script instead.} +} + \longnewglossaryentry{makeglossariesgui}{% name={\appfmt{makeglossariesgui}\index{makeglossariesgui=\appfmt{makeglossariesgui}|htextbf}},% sort={makeglossariesgui},% @@ -367,11 +378,11 @@ and~\hyperlink{option#2}{#2}} \MakeShortVerb{"} \DeleteShortVerb{\|} - \title{User Manual for glossaries.sty v4.15} + \title{User Manual for glossaries.sty v4.16} \author{Nicola L.C. Talbot\\% \url{http://www.dickimaw-books.com/}} - \date{2015-03-16} + \date{2015-07-08} \maketitle \begin{abstract} @@ -381,7 +392,7 @@ Sorted lists with collated \glslink{entrylocation}{locations} can be generated either using \TeX\ or using a supplementary \gls{indexingapp}. \end{abstract} -If you require multilingual support you must also install +If you require multilingual support you must also separately install the relevant language module. Each language module is called \texttt{glossaries-}\meta{language}, where \meta{language} is the root language name. For example, \texttt{glossaries-french} @@ -391,7 +402,7 @@ will give a warning if the module isn't found. See \sectionref{sec:languages} for further details. \begin{important} -Documents have various styles when it comes to presenting glossaries +Documents have wide-ranging styles when it comes to presenting glossaries or lists of terms or notation. People have their own preferences and to a large extent this is determined by the kind of information that needs to go in the glossary. They may just have symbols with @@ -433,7 +444,7 @@ letter}{mfirstuc-manual}. \item[\url{glossaries-code.pdf}] 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.15}. +\qt{Documented Code for glossaries v4.16}. This includes the documented code for the \sty{mfirstuc} package. \item[INSTALL] Installation instructions. @@ -504,7 +515,7 @@ assistance in upgrading. One of the strengths of this package is its flexibility, however the drawback of this is the necessity of having a large manual -that can cover all the various settings. If you are daunted by the +that covers all the various settings. If you are daunted by the size of the manual, try starting off with the much shorter \docref{guide for beginners}{glossariesbegin}. @@ -537,6 +548,10 @@ difficult. There are three options: and will default to \verb|\'elite| if \pkgopt[true]{sanitizesort} is used. + This option works best with the \pkgopt[def]{sort} setting. For any + other setting, be prepared for a long document build time, + especially if you have a lot of entries defined. + \begin{enumerate} \item Add \cs{makenoidxglossaries} to your preamble (before you start defining your entries, as described in @@ -565,6 +580,9 @@ difficult. There are three options: Then \gls{makeindex} writes a~new file containing the code to typeset the glossary. \LaTeX\ then reads this file in on the next run. + This option works best if you want to sort entries according to the + English alphabet and you don't want to install Perl. + \begin{enumerate} \item Add \cs{makeglossaries} to your preamble (before you start defining your entries, as described in @@ -631,6 +649,10 @@ makeindex -l -s myDoc.ist -o myDoc.gls myDoc.glo writes a~new file containing the code to typeset the glossary. \LaTeX\ then reads this file in on the next run. + This is the best option if you want to sort according to a + language other than English or if you want non-standard location + lists. + \begin{enumerate} \item Add the \pkgopt{xindy} option to the \styfmt{glossaries} package option list: @@ -657,13 +679,14 @@ package option list: Unix-like users) then you need to run the command (all on one line): \begin{verbatim} -xindy -L english -C utf8 -I xindy -M myDoc +xindy -L english -C utf8 -I xindy -M myDoc -t myDoc.glg -o myDoc.gls myDoc.glo \end{verbatim} (Replace \texttt{myDoc} with the base name of your \LaTeX\ document file. Avoid spaces in the file name. If necessary, also replace \texttt{english} with the name of your language and \texttt{utf8} - with your input encoding.) If you don't know + with your input encoding, for example, \texttt{-L german -C + din5007-utf8}.) If you don't know how to use the command prompt, then you can probably access \gls{xindy} via your text editor, but each editor has a different method of doing this, so I~can't give a~general @@ -676,8 +699,9 @@ xindy -L english -C utf8 -I xindy -M myDoc \begin{verbatim} \usepackage[xindy,order=letter]{glossaries} \end{verbatim} - (See \sectionref{sec:xindyapp} for further details on using - \gls*{xindy} explicitly.) + (and return to the previous step.) + See \sectionref{sec:xindyapp} for further details on using + \gls*{xindy} explicitly. \item Once you have successfully completed the previous step, you can now run \LaTeX\ on your document again. @@ -688,7 +712,7 @@ xindy -L english -C utf8 -I xindy -M myDoc For \optsand23, it can be difficult to remember all the parameters required for \gls{makeindex} or \gls{xindy}, so the -\styfmt{glossaries} package provides a~script called +\styfmt{glossaries} package provides a~Perl script called \gls{makeglossaries} that reads the \texttt{.aux} file to determine what settings you have used and will then run \gls{makeindex} or \gls{xindy}. Again, this is a~command line @@ -702,6 +726,17 @@ makeglossaries myDoc file. Avoid spaces in the file name.) This is described in more detail in \sectionref{sec:makeglossaries}. +If you don't have Perl installed you can use the Lua script instead: +\begin{verbatim} +makeglossaries-lite.lua myDoc +\end{verbatim} +This script doesn't have the full functionality of the Perl script, +but since modern \TeX\ distributions come with Lua, you shouldn't +need to install anything extra to make it run. Remember that since +\gls{xindy} is also a~Perl script, if you want to use \gls{xindy} +you'll need Perl installed anyway, so there's no point using this +Lua script if you're using \gls{xindy}. + \begin{important} The \texttt{.gls} and \texttt{.glo} are temporary files created to help build your document. You should not edit or explicitly input @@ -854,6 +889,11 @@ You should now have a complete document. The number following each entry in the glossary is the location number. By default, this is the page number where the entry was referenced. +There are three other files that can be used as a +\href{http://www.dickimaw-books.com/latex/minexample/}{minimal working +example}: \texttt{mwe-gls.tex}, \texttt{mwe-acr.tex} and +\texttt{mwe-acr-desc.tex}. + \exitem{-noidx} This document illustrates how to use the \styfmt{glossaries} package without an external \gls{indexingapp} (\opt1). To create the complete document, you need to do: @@ -1205,7 +1245,22 @@ makeglossaries sample-index latex sample-index \end{prompt} -\exitem{-newkeys} This document illustrates how add custom keys. +\exitem{-newkeys} This document illustrates how add custom keys +(using \cs{glsaddkey}). + +\exitem{-storage-abbr} This document illustrates how add custom +storage keys (using \cs{glsaddstoragekey}). + +\exitem{-storage-abbr-desc} An extension of the previous example +where the user needs to provide a~description. + +\exitem{-chap-hyperfirst} This document illustrates how to add +a~custom key using \cs{glsaddstoragekey} and hook into the \glslike\ +and \glstextlike\ mechanism used to determine whether or not to +hyperlink an entry. + +\exitem{-font-abbr} This document illustrates how to different fonts +for abbreviations within the style. \exitem{-numberlist} This document illustrates how to reference the \gls{numberlist} in the document text. This requires an additional @@ -1781,21 +1836,22 @@ ignore this section if you have chosen \opt1. If this section seriously confuses you, and you can't work out how to run \gls{makeglossaries} or \gls{makeindex}, you can try using the \pkgopt{automake} package option, described in -\sectionref{sec:pkgopts-sort}. +\sectionref{sec:pkgopts-sort}, but you will need \TeX's shell escape +enabled. In order to generate a sorted glossary with compact \glspl{numberlist}, it is necessary to use an external \gls{indexingapp} as an intermediate step (unless you have chosen -\opt1). It is this application that creates the file containing the -code that typesets the glossary. If this step is omitted, the -glossaries will not appear in your document. The two -\glspl*{indexingapp} that are most commonly used with \LaTeX\ are -\gls{makeindex} and \gls{xindy}. As from version 1.17, the -\styfmt{glossaries} package can be used with either of these -applications. Previous versions were designed to be used with -\gls*{makeindex} only. Note that \gls*{xindy} has much better -multi-lingual support than \gls*{makeindex}, so \gls*{xindy} is -recommended if you're not writing in English. Commands that only +\opt1, which uses \TeX\ to do the sorting). It is this application +that creates the file containing the code that typesets the +glossary. \textbf{If this step is omitted, the glossaries will not +appear in your document.} The two \glspl*{indexingapp} that are most +commonly used with \LaTeX\ are \gls{makeindex} and \gls{xindy}. As +from version 1.17, the \styfmt{glossaries} package can be used with +either of these applications. Previous versions were designed to be +used with \gls*{makeindex} only. Note that \gls*{xindy} has much +better multi-lingual support than \gls*{makeindex}, so \gls*{xindy} +is recommended if you're not writing in English. Commands that only have an effect when \gls*{xindy} is used are described in \sectionref{sec:xindy}. @@ -1840,16 +1896,26 @@ file and see if you can work it out from the \gls*{makeindex} or \end{itemize} +As from version 4.16, the \styfmt{glossaries} package also comes +with a~Lua script called \gls{makeglossaries-lite.lua}. This is a +\emph{trimmed-down} alternative to the \gls{makeglossaries} Perl +script. It doesn't have some of the options that the Perl version +has and it doesn't attempt to diagnose any problems, but since +modern \TeX\ distributions come with Lua\TeX\ (and therefore have +a~Lua interpreter) you don't need to install anything else in order +to use \gls{makeglossaries-lite.lua} so it's an alternative to +\gls{makeglossaries} if you want to use \opt2 (\gls{makeindex}). + There is also a Java GUI alternative called \gls{makeglossariesgui}, distributed separately, that has diagnostic tools. Whilst it is strongly recommended that you use the -\gls{makeglossaries} script or \gls{makeglossariesgui}, it is -possible to use the \styfmt{glossaries} package without using either -application. However, note that some commands and package options -have no effect if you don't use \gls*{makeglossaries} or -\gls*{makeglossariesgui}. These are listed in -\tableref{tab:makeglossariesCmds}. +\gls{makeglossaries} Perl script or the \gls{makeglossaries-lite.lua} +script or the \gls{makeglossariesgui} Java application, it is +possible to use the \styfmt{glossaries} package without using those +applications. However, note that some commands and package options +have no effect if you explicitly run \gls{makeindex}\slash\gls{xindy}. +These are listed in \tableref{tab:makeglossariesCmds}. \begin{important} If you are choosing not to use \gls*{makeglossaries} because you @@ -2018,9 +2084,38 @@ resulting file onto the man path. Alternatively do \begin{important} When upgrading the \styfmt{glossaries} package, make sure you also upgrade your version of \gls{makeglossaries}. The current version is -2.15. +??. \end{important} +\subsection{Using the makeglossaries-lite.lua Lua Script} +\label{sec:makeglossarieslua} + +The Lua alternative to the \gls{makeglossaries} Perl script requires +a~Lua interpreter, which should already be available if you have +a~modern \TeX\ distribution that includes Lua\TeX. Lua is +a~light-weight, cross-platform scripting language, but because it's +light-weight it doesn't have the full-functionality of heavy-weight +scripting languages, such as Perl. The \gls{makeglossaries-lite.lua} +script is therefore limited by this and some of the options +available to the \gls{makeglossaries} Perl script aren't available +here. (In particular the \texttt{-d} option.) + +The \gls{makeglossaries-lite.lua} script can be invoked in the same way +as \gls{makeglossaries} but you need to remember the \texttt{.lua} +extension. For example, if your document is called +\texttt{myDoc.tex}, then do +\begin{prompt} +makeglossaries-lite.lua myDoc +\end{prompt} + +\emph{Some} of the options available with \gls{makeglossaries} are +also available with \gls{makeglossaries-lite.lua}. For a complete list of +available options, do +\begin{prompt} +makeglossaries-lite.lua -{}-help +\end{prompt} + + \subsection[Using xindy explicitly (Option~3)]{Using \gls{xindy} explicitly (\ifpdf \opt3\else Option 3\fi)} \label{sec:xindyapp} @@ -2442,7 +2537,52 @@ first use just for acronyms: \end{verbatim} Note that this hook isn't used by the commands that don't check the -\firstuseflag, such as \ics{glstext}. +\firstuseflag, such as \ics{glstext}. (You can, instead, redefine +\ics{glslinkpostsetkeys}, which is used by both the \glslike\ and +\glstextlike\ commands.) + +\item[\pkgopt{indexonlyfirst}] This is a boolean option that specifies +whether to only add information to the external glossary file on +\gls{firstuse}. The default is \pkgopt[false]{indexonlyfirst}, +which will add a line to the file every time one of the +\glslike\ or \glstextlike\ commands are used. Note that \ics{glsadd} +will always add information to the external glossary +file\footnote{bug fix in v4.16 has corrected the code to ensure +this.}\ (since that's the purpose of that command). + +You can customise this by redefining +\begin{definition}[\DescribeMacro\glswriteentry] +\cs{glswriteentry}\marg{label}\marg{wr-code} +\end{definition} +where \meta{label} is the entry's label and \meta{wr-code} is the +code that writes the entry's information to the external file. +The default definition of \cs{glswriteentry} is: +\begin{verbatim} +\newcommand*{\glswriteentry}[2]{% + \ifglsindexonlyfirst + \ifglsused{#1}{}{#2}% + \else + #2% + \fi +} +\end{verbatim} +This checks the \pkgopt{indexonlyfirst} package option (using +\cs{ifglsindexonlyfirst}) and does \meta{wr-code} if this is +\pkgoptfmt{false} otherwise it only does \meta{wr-code} of the entry +hasn't been used. + +For example, suppose you only want to index the first use for +entries in the \texttt{acronym} glossary and not in the +\texttt{main} (or any other) glossary: +\begin{verbatim} +\renewcommand*{\glswriteentry}[2]{% + \ifthenelse{\equal{\glsentrytype{#1}}{acronym}} + {\ifglsused{#1}{}{#2}}% + {#2}% +} +\end{verbatim} +Here I've used \cs{ifthenelse} to ensure the arguments of +\cs{equal} are fully expanded before the comparison is made. \item[\pkgopt{savenumberlist}] This is a boolean option that specifies whether or not to gather and store the \gls{numberlist} @@ -2828,6 +2968,9 @@ redefined, if required, before the entries are defined (in the case of \pkgopt[def]{sort}) or before the entries are used (in the case of \pkgopt[use]{sort}). \end{itemize} +Note that the group styles (such as \glostyle{listgroup}) are +incompatible with the \pkgopt[use]{sort} and \pkgopt[def]{sort} +options. The default is \pkgopt[standard]{sort}. When the standard sort option is in use, you can hook into the sort mechanism by @@ -3092,7 +3235,8 @@ another glossary is explicitly specified. \begin{important} Remember to use the \pkgopt{nomain} package option if you're only -interested in using this \texttt{acronym} glossary. +interested in using this \texttt{acronym} glossary. (That is, you +don't intend to use the \texttt{main} glossary.) \end{important} \item[\pkgopt{acronyms}] This is equivalent to @@ -3285,7 +3429,8 @@ to display the list of symbols. \begin{important} Remember to use the \pkgopt{nomain} package option if you're only -interested in using this \texttt{symbols} glossary. +interested in using this \texttt{symbols} glossary and don't intend +to use the \texttt{main} glossary. \end{important} \item[\pkgopt{numbers}] This option defines a new glossary type with @@ -3310,7 +3455,8 @@ to display the list of numbers. \begin{important} Remember to use the \pkgopt{nomain} package option if you're only -interested in using this \texttt{numbers} glossary. +interested in using this \texttt{numbers} glossary and don't intend +to use the \texttt{main} glossary. \end{important} \item[\pkgopt{index}] This option defines a new glossary type with @@ -3344,7 +3490,8 @@ to display this glossary. \begin{important} Remember to use the \pkgopt{nomain} package option if you're only -interested in using this \texttt{index} glossary. Note that you +interested in using this \texttt{index} glossary and don't intend to +use the \texttt{main} glossary. Note that you can't mix this option with \ics{index}. Either use \styfmt{glossaries} for the indexing or use a~custom indexing package, such as \sty{makeidx}, \sty{index} or \sty{imakeidx}. @@ -3736,7 +3883,7 @@ assumed unless \ics{newacronym} is used (see Six keys provided for any additional information the user may want to specify. (For example, an associated dimension or an alternative plural or some other grammatical construct.) Alternatively, you can -add new keys using \ics{glsaddkey} (see \sectionref{sec:addkey}). +add new keys using \ics{glsaddkey} or \ics{glsaddstoragekey} (see \sectionref{sec:addkey}). Other keys are also provided by the \sty{glossaries-prefix} (\sectionref{sec:prefix}) and \sty{glossaries-accsupp} (\sectionref{sec:accsupp}) packages. @@ -3899,7 +4046,30 @@ Alternatively, you can define your own keys using \section{Additional Keys} \label{sec:addkey} -You can now also define your own custom keys using: +You can now also define your own custom keys using the +commands described in this section. There are two types of keys: +those for use within the document and those to store information +used behind the scenes by other commands. + +For example, if you want to add a key that indicates the associated +unit for a~term, you might want to reference this unit in your +document. In this case use \cs{glsaddkey} described in +\sectionref{sec:glsaddkey}. If, on the other hand, you want to add a +key to indicate to a glossary style or acronym style that this entry +should be formatted differently to other entries, then you can use +\cs{glsaddstoragekey} described in \sectionref{sec:glsaddstoragekey}. + +In both cases, a new command \meta{no link cs} will be defined that +can be used to access the value of this key (analogous to commands +such as \cs{glsentrytext}). This can be used in an expandable +context (provided any fragile commands stored in the key have been +protected). The new keys must be added using \cs{glsaddkey} or +\cs{glsaddstoragekey} before glossary entries are defined. + +\section{Document Keys} +\label{sec:glsaddkey} + +A custom key that can be used in the document is defined using: \begin{definition}[\DescribeMacro\glsaddkey] \cs{glsaddkey}\marg{key}% \marg{default value}% @@ -3989,6 +4159,274 @@ The dog \glsed{run} away from the duck. For a complete document, see the sample file \samplefile{-newkeys}. \end{example} +\section{Storage Keys} +\label{sec:glsaddstoragekey} + +A custom key that can be used for simply storing information is +defined using: +\begin{definition}[\DescribeMacro\glsaddstoragekey] +\cs{glsaddstoragekey}\marg{key}\marg{default value}\marg{no link cs} +\end{definition} +where the arguments are as the first three arguments of +\cs{glsaddkey}, described above in \sectionref{sec:glsaddkey}. + +This is essentially the same as \cs{glsaddkey} except that it +doesn't define the additional commands. You can access or update +the value of your new field using the commands described in +\sectionref{sec:fetchset}. + +\begin{example}{Defining Custom Storage Key (Acronyms and Initialisms)}{ex:addstoragekey} +Suppose I want to define acronyms and other forms of abbreviations, +such as initialisms, but I want them all in the same glossary and I +want the acronyms on first use to be displayed with the short form followed by +the long form in parentheses, but the opposite way round for other +forms of abbreviations. + +Here I can define a new key that determines whether the term is +actually an acronym rather than some other form of abbreviation. I'm +going to call this key \texttt{abbrtype} (since \texttt{type} +already exists): +\begin{verbatim} +\glsaddstoragekey + {abbrtype}% key/field name + {word}% default value if not explicitly set + {\abbrtype}% custom command to access the value if required +\end{verbatim} + +Now I can define a style that looks up the value of this new key to +determine how to display the full form: +\begin{verbatim} +\newacronymstyle + {mystyle}% style name + {% Use the generic display + \ifglshaslong{\glslabel}{\glsgenacfmt}{\glsgenentryfmt}% + } + {% Put the long form in the description + \renewcommand*{\GenericAcronymFields}{description={\the\glslongtok}}% + % For the full format, test the value of the "abbrtype" key. + % If it's set to "word" put the short form first with + % the long form in brackets. + \renewcommand*{\genacrfullformat}[2]{% + \ifglsfieldeq{##1}{abbrtype}{word} + {% is a proper acronym + \protect\firstacronymfont{\glsentryshort{##1}}##2\space + (\glsentrylong{##1})% + } + {% is another form of abbreviation + \glsentrylong{##1}##2\space + (\protect\firstacronymfont{\glsentryshort{##1}})% + }% + }% + % first letter upper case version: + \renewcommand*{\Genacrfullformat}[2]{% + \ifglsfieldeq{##1}{abbrtype}{word} + {% is a proper acronym + \protect\firstacronymfont{\Glsentryshort{##1}}##2\space + (\glsentrylong{##1})% + } + {% is another form of abbreviation + \Glsentrylong{##1}##2\space + (\protect\firstacronymfont{\glsentryshort{##1}})% + }% + }% + % plural + \renewcommand*{\genplacrfullformat}[2]{% + \ifglsfieldeq{##1}{abbrtype}{word} + {% is a proper acronym + \protect\firstacronymfont{\glsentryshortpl{##1}}##2\space + (\glsentrylong{##1})% + } + {% is another form of abbreviation + \glsentrylongpl{##1}##2\space + (\protect\firstacronymfont{\glsentryshortpl{##1}})% + }% + }% + % plural and first letter upper case + \renewcommand*{\Genplacrfullformat}[2]{% + \ifglsfieldeq{##1}{abbrtype}{word} + {% is a proper acronym + \protect\firstacronymfont{\Glsentryshortpl{##1}}##2\space + (\glsentrylong{##1})% + } + {% is another form of abbreviation + \Glsentrylongpl{##1}##2\space + (\protect\firstacronymfont{\glsentryshortpl{##1}})% + }% + }% + % Just use the short form as the name part in the glossary: + \renewcommand*{\acronymentry}[1]{\acronymfont{\glsentryshort{##1}}}% + % Sort by the short form: + \renewcommand*{\acronymsort}[2]{##1}% + % Just use the surrounding font for the short form: + \renewcommand*{\acronymfont}[1]{##1}% + % Same for first use: + \renewcommand*{\firstacronymfont}[1]{\acronymfont{##1}}% + % Default plural suffix if the plural isn't explicitly set + \renewcommand*{\acrpluralsuffix}{\glspluralsuffix}% + } +\end{verbatim} +Remember that the new style needs to be set before defining any +terms: +\begin{verbatim} +\setacronymstyle{mystyle} +\end{verbatim} + +Since it's a bit confusing to use \ics{newacronym} for something +that's not technically an acronym, let's define a new command for +initialisms: +\begin{verbatim} +\newcommand*{\newinitialism}[4][]{% + \newacronym[abbrtype=initialism,#1]{#2}{#3}{#4}% +} +\end{verbatim} +Now the entries can all be defined: +\begin{verbatim} +\newacronym{radar}{radar}{radio detecting and ranging} +\newacronym{laser}{laser}{light amplification by stimulated +emission of radiation} +\newacronym{scuba}{scuba}{self-contained underwater breathing +apparatus} +\newinitialism{dsp}{DSP}{digital signal processing} +\newinitialism{atm}{ATM}{automated teller machine} +\end{verbatim} +On \gls{firstuse}, \verb|\gls{radar}| will produce \qt{radar (radio +detecting and ranging)} but \verb|\gls{dsp}| will produce \qt{DSP +(digital signal processing)}. + +For a complete document, see the sample file +\samplefile{-storage-abbr}. +\end{example} + +In the above example, if \cs{newglossaryentry} is explicitly used +(instead of through \cs{newacronym}) the \texttt{abbrtype} key will +be set to its default value of \qt{word} but the \cs{ifglshaslong} +test in the custom acronym style will be false (since the +\gloskey{long} key hasn't been set) so the display style will switch +to that given by \cs{glsgenentryfmt} and they'll be no test +performed on the \texttt{abbrtype} field. + +\begin{example}{Defining Custom Storage Key (Acronyms and +Non-Acronyms with Descriptions)}{ex:addstoragekey2} +The previous example can be modified if the \gloskey{description} +also needs to be provided. Here I've changed \qt{word} to +\qt{acronym}: +\begin{verbatim} +\glsaddstoragekey + {abbrtype}% key/field name + {acronym}% default value if not explicitly set + {\abbrtype}% custom command to access the value if required +\end{verbatim} +This may seem a little odd for non-abbreviated entries defined using +\cs{newglossaryentry} directly, but \ics{ifglshaslong} can be used +to determine whether or not to reference the value of this new +\texttt{abbrtype} field. + +The new acronym style has a~minor modification that forces the user +to specify a description. In the previous example, the line: +\begin{verbatim} + \renewcommand*{\GenericAcronymFields}{description={\the\glslongtok}}% +\end{verbatim} +needs to be changed to: +\begin{verbatim} + \renewcommand*{\GenericAcronymFields}{}% +\end{verbatim} +Additionally, to accommodate the change in the default value of the +\texttt{abbrtype} key, all instances of +\begin{verbatim} + \ifglsfieldeq{##1}{abbrtype}{word} +\end{verbatim} +need to be changed to: +\begin{verbatim} + \ifglsfieldeq{##1}{abbrtype}{acronym} +\end{verbatim} + +Once this new style has been set, the new acronyms can be defined +using the optional argument to set the description: +\begin{verbatim} +\newacronym[description={system for detecting the position and +speed of aircraft, ships, etc}]{radar}{radar}{radio detecting +and ranging} +\end{verbatim} + +No change is required for the definition of \cs{newinitialism} but +again the optional argument is required to set the description: +\begin{verbatim} +\newinitialism[description={mathematical manipulation of an +information signal}]{dsp}{DSP}{digital signal processing} +\end{verbatim} + +We can also accommodate contractions in a similar manner to the +initialisms: +\begin{verbatim} +\newcommand*{\newcontraction}[4][]{% + \newacronym[abbrtype=contraction,#1]{#2}{#3}{#4}% +} +\end{verbatim} +The contractions can similarly been defined using this new command: +\begin{verbatim} +\newcontraction[description={front part of a ship below the +deck}]{focsle}{fo'c's'le}{forecastle} +\end{verbatim} + +Since the custom acronym style just checks if \texttt{abbrtype} is +\texttt{acronym}, the contractions will be treated the same as the +initialisms, but the style could be modified by a further test of +the \texttt{abbrtype} value if required. + +To test regular non-abbreviated entries, I've also defined a simple +word: +\begin{verbatim} +\newglossaryentry{apple}{name={apple},description={a fruit}} +\end{verbatim} + +Now for a new glossary style that provides information about the +abbreviation (in addition to the description): +\begin{verbatim} +\newglossarystyle + {mystyle}% style name + {% base it on the "list" style + \setglossarystyle{list}% + \renewcommand*{\glossentry}[2]{% + \item[\glsentryitem{##1}% + \glstarget{##1}{\glossentryname{##1}}] + \ifglshaslong{##1}% + { (\abbrtype{##1}: \glsentrylong{##1})\space}{}% + \glossentrydesc{##1}\glspostdescription\space ##2}% + } +\end{verbatim} +This uses \ics{ifglshaslong} to determine whether or not the term is +an abbreviation. If it has an abbreviation, the full form is +supplied in parentheses and \cs{abbrtype} (defined by +\cs{glsaddstoragekey} earlier) is used to indicate the type of +abbreviation. + +With this style set, the \texttt{apple} entry is simply displayed in +the glossary as +\begin{description} +\item[apple] a fruit. +\end{description} +but the abbreviations are displayed in the form +\begin{description} +\item[laser] (acronym: light amplification by +stimulated emission of radiation) device that creates a narrow beam +of intense light. +\end{description} +(for acronyms) or +\begin{description} +\item[DSP] (initialism: digital signal processing) mathematical +manipulation of an information signal. +\end{description} +(for initalisms) or +\begin{description} +\item[fo'c's'le] (contraction: forecastle) front part of a ship +below the deck. +\end{description} +(for contractions). + +For a complete document, see the sample file +\samplefile{-storage-abbr-desc}. +\end{example} + \section{Expansion} \label{sec:expansion} @@ -5282,6 +5720,12 @@ the hyperlink is on for this reference. Note that you can also use commands such as \ics{ifglsused} within the definition of \cs{glsentryfmt} (see \sectionref{sec:glsunset}). +The commands \ics{glslabel}, \ics{glstype}, \ics{glsifplural}, +\ics{glscapscase}, \ics{glscustomtex} and \ics{glsinsert} are +typically updated at the start of the \glslike\ and \glstextlike\ +commands so they can usually be accessed in the hook user commands, +such as \ics{glspostlinkhook} and \ics{glslinkpostsetkeys}. + If you only want to make minor modifications to \cs{glsentryfmt}, you can use \begin{definition}[\DescribeMacro{\glsgenentryfmt}] @@ -5338,6 +5782,21 @@ on changing the style of acronyms. Note that \cs{glsentryfmt} is not used by the \glstextlike\ commands. \end{important} +As from version 4.16, both the \glslike\ and \glstextlike\ commands +use +\begin{definition}[\DescribeMacro\glslinkpostsetkeys] +\cs{glslinkpostsetkeys} +\end{definition} +after the \meta{options} are set. This macro does nothing by default +but can be redefined. (For example, to switch off the hyperlink +under certain conditions.) This version also introduces +\begin{definition}[\DescribeMacro\glspostlinkhook] +\cs{glspostlinkhook} +\end{definition} +which is done after the link text has been displayed and also +\emph{after} the \firstuseflag\ has been unset (see +example~\ref{ex:dotabbr}). + \begin{example}{Custom Entry Display in Text}{ex:customfmt} Suppose you want a glossary of measurements and units, you can use the \gloskey{symbol} key to store the unit: @@ -5521,6 +5980,48 @@ See the sample file \samplefile{-nomathhyper} for a complete document. \end{example} +\begin{example}{One Hyper Link Per Entry Per Chapter}{ex:chap-hyperfirst} +Here's a more complicated example that will only have the hyperlink +on the first time an entry is used per chapter. This doesn't involve +resetting the \firstuseflag. Instead it adds a~new key using +\ics{glsaddstoragekey} (see \sectionref{sec:glsaddstoragekey}) that +keeps track of the chapter number that the entry was last used in: +\begin{verbatim} +\glsaddstoragekey{chapter}{0}{\glschapnum} +\end{verbatim} +This creates a new user command called \cs{glschapnum} that's +analogous to \cs{glsentrytext}. The default value for this key is~0. +I~then define my glossary entries as usual. + +Next I redefine the hook \ics{glslinkpostsetkeys} +(see \sectionref{sec:glsdisplay}) so that it determines the current +chapter number (which is stored in \cs{currentchap} using +\cs{edef}). This value is then compared with the value of the +entry's \texttt{chapter} key that I defined earlier. If they're the +same, this entry has already been used in this chapter so the +hyperlink is switched off using \sty{xkeyval}'s \cs{setkeys} +command. If the chapter number isn't the same, then this entry +hasn't been used in the current chapter. The \texttt{chapter} field +is updated using \ics{glsfieldxdef} (\sectionref{sec:fetchset}) +provided the user hasn't switched off the hyperlink. +(This test is performed using \cs{glsifhyperon}. +\begin{verbatim} +\renewcommand*{\glslinkpostsetkeys}{% + \edef\currentchap{\arabic{chapter}}% + \ifnum\currentchap=\glschapnum{\glslabel}\relax + \setkeys{glslink}{hyper=false}% + \else + \glsifhyperon{\glsfieldxdef{\glslabel}{chapter}{\currentchap}}{}% + \fi +} +\end{verbatim} +Note that this will be confused if you use \cs{gls} etc when the +chapter counter is~0. (That is, before the first \cs{chapter}.) + +See the sample file \samplefile{-chap-hyperfirst} for a complete +document. +\end{example} + \chapter{Adding an Entry to the Glossary Without Generating Text} \label{sec:glsadd} @@ -6823,7 +7324,7 @@ just follow the advice in change LaTeX’s \qt{fixed names}}. \end{important} -\chapter{Acronyms} +\chapter{Acronyms and Other Abbreviations} \label{sec:acronyms} \begin{important} @@ -6898,8 +7399,8 @@ type as \verb|type=\glsdefaulttype| in the optional argument to \ics{newacronym}. See \sectionref{sec:loadglsentries}. \end{important} -\begin{example}{Defining an Acronym}{ex:newacronym} -The following defines the acronym IDN: +\begin{example}{Defining an Abbreviation}{ex:newacronym} +The following defines the abbreviation IDN: \begin{verbatim} \newacronym{idn}{IDN}{identification number} \end{verbatim} @@ -7225,7 +7726,7 @@ The following styles are supplied by the \styfmt{glossaries} package: \begin{itemize} \item \acrstyle{long-short}, \acrstyle{long-sc-short}, -\acrstyle{long-sm-short}: +\acrstyle{long-sm-short}, \acrstyle{long-sp-short}: With these three styles, acronyms are displayed in the form \begin{definition} @@ -7242,6 +7743,20 @@ their short form. In addition, \cs{acronymentry}\marg{label} is set to just the short form (enclosed in \cs{acronymfont}) and the \gloskey{description} key is set to the long form. +The \acrstyle{long-sp-short} style was introduced in version~4.16 +and uses +\begin{definition}[\DescribeMacro\glsacspace] +\cs{glsacspace}\marg{label} +\end{definition} +for the space between the long and short forms. This defaults to +a~non-breakable space (\verb|~|) if +(\cs{acronymfont}\marg{short}) is less than 3em, otherwise it uses +a~normal space. This may be redefined as required. For example, to +always use a~non-breakable space: +\begin{verbatim} +\renewcommand*{\glsacspace}[1]{~} +\end{verbatim} + \item \acrstyle{short-long}, \acrstyle{sc-short-long}, \acrstyle{sm-short-long}: @@ -7257,10 +7772,10 @@ same as for the \meta{long} (\meta{short}) styles above, so the acronyms are still sorted according to the short form. \item \acrstyle{long-short-desc}, \acrstyle{long-sc-short-desc}, -\acrstyle{long-sm-short-desc}: +\acrstyle{long-sm-short-desc}, \acrstyle{long-sp-short-desc}: -These are like the \acrstyle{long-short}, \acrstyle{long-sc-short} -and \acrstyle{long-sm-short} styles described above, except that the +These are like the \acrstyle{long-short}, \acrstyle{long-sc-short}, +\acrstyle{long-sm-short} and \acrstyle{long-sp-short} styles described above, except that the \gloskey{description} key must be supplied in the optional argument of \ics{newacronym}. They also redefine \ics{acronymentry} to \marg{long} (\cs{acronymfont}\marg{short}) and redefine @@ -7769,6 +8284,222 @@ The sample file \samplefile{-custom-acronym} illustrates this example. \end{example} +\begin{example}{Italic and Upright Abbreviations}{ex:font-abbr} +Suppose I~want to have some abbreviations in italic and some that +just use the surrounding font. Hard-coding this into the +\meta{short} argument of \cs{newacronym} can cause complications. + +This example uses \ics{glsaddstoragekey} to add an extra field that +can be used to store the formatting declaration (such as \cs{em}). +\begin{verbatim} +\glsaddstoragekey{font}{}{\entryfont} +\end{verbatim} +This defines a~new field/key called \texttt{font}, which defaults to +nothing if it's not explicitly set. This also defines a command +called \cs{entryfont} that's analogous to \cs{glsentrytext}. A~new +style is then created to format abbreviations that access this field. + +There are two ways to do this. The first is to create a style that +doesn't use \ics{glsgenacfmt} but instead provides a~modified +version that doesn't use \cs{acronymfont}\marg{short} +but instead uses +\verb|{|\cs{entryfont}\verb|{\glslabel}|\meta{short}\verb|}|. +The full format given by commands such as \cs{genacrfullformat} +need to be similarly adjusted. For example: +\begin{verbatim} + \renewcommand*{\genacrfullformat}[2]{% + \glsentrylong{##1}##2\space + ({\entryfont{##1}\glsentryshort{##1}})% + }% +\end{verbatim} +This will deal with commands like \ics{gls} but not commands like +\ics{acrshort} which still use \ics{acronymfont}. Another approach +is to redefine \cs{acronymfont} to look up the required font +declaration. Since \cs{acronymfont} doesn't take the entry label as +an argument, the following will only work if \cs{acronymfont} is +used in a~context where the label is provided by \ics{glslabel}. +This is true in \cs{gls}, \cs{acrshort} and \cs{acrfull}. The +redefinition is now: +\begin{verbatim} +\renewcommand*{\acronymfont}[1]{{\entryfont{\glslabel}#1}}% +\end{verbatim} +So the new style can be defined as: +\begin{verbatim} +\newacronymstyle{long-font-short} +{% + \GlsUseAcrEntryDispStyle{long-short}% +} +{% + \GlsUseAcrStyleDefs{long-short}% + \renewcommand*{\genacrfullformat}[2]{% + \glsentrylong{##1}##2\space + ({\entryfont{##1}\glsentryshort{##1}})% + }% + \renewcommand*{\Genacrfullformat}[2]{% + \Glsentrylong{##1}##2\space + ({\entryfont{##1}\glsentryshort{##1}})% + }% + \renewcommand*{\genplacrfullformat}[2]{% + \glsentrylongpl{##1}##2\space + ({\entryfont{##1}\glsentryshortpl{##1}})% + }% + \renewcommand*{\Genplacrfullformat}[2]{% + \Glsentrylongpl{##1}##2\space + ({\entryfont{##1}\glsentryshortpl{##1}})% + }% + \renewcommand*{\acronymfont}[1]{{\entryfont{\glslabel}##1}}% + \renewcommand*{\acronymentry}[1]{{\entryfont{##1}\glsentryshort{##1}}}% +} +\end{verbatim} +Remember the style needs to be set before defining the entries: +\begin{verbatim} +\setacronymstyle{long-font-short} +\end{verbatim} + +The complete document is contained in the sample file +\samplefile{-font-abbr}. +\end{example} + +Some writers and publishing houses have started to drop full stops +(periods) from upper case initials but may still retain them for +lower case abbreviations, while others may still use them for both +upper and lower case. This can cause complications. Chapter~12 of +\emph{The \TeX{}book} discusses the spacing between words but, +briefly, the default behaviour of \TeX\ is to assume that an upper +case character followed by a~full stop and space is an abbreviation, +so the space is the default inter-word space whereas a~lower case +character followed by a~full stop and space is a word occurring at +the end of a~sentence. In the event that this isn't true, you need +to make a~manual adjustment using \verb*| | (back slash space) in +place of just a~space character for an inter-word mid-sentence space +and use \verb|\@| before the full stop to indicate the end of the +sentence. + +For example: +\begin{verbatim} +I was awarded a B.Sc. and a Ph.D. (From the same place.) +\end{verbatim} +is typeset as +\begin{display} +I was awarded a B.Sc. and a Ph.D. (From the same place.) +\end{display} +The spacing is more noticeable with the typewriter font: +\begin{verbatim} +\ttfamily +I was awarded a B.Sc. and a Ph.D. (From the same place.) +\end{verbatim} +is typeset as +\begin{display}\ttfamily +I was awarded a B.Sc. and a Ph.D. (From the same place.) +\end{display} +The lower case letter at the end of ``B.Sc.''\ is confusing \TeX\ +into thinking that the full stop after it marks the end of the +sentence. Whereas the upper case letter at the end of ``Ph.D.'' has +confused \TeX\ into thinking that the following full stop is just +part of the abbreviation. These can be corrected: +\begin{verbatim} +I was awarded a B.Sc.\ and a Ph.D\@. (From the same place.) +\end{verbatim} + +This situation is a bit problematic for \styfmt{glossaries}. The +full stops can form part of the \meta{short} argument of +\cs{newacronym} and the \verb*|B.Sc.\ | part can be dealt with by +remembering to add \verb*|\ | (for example, \verb*|\gls{bsc}\ |) +but the end of sentence case is more troublesome as you need to omit +the sentence terminating full stop (to avoid two dots) which can +make the source code look a little strange but you also need to +adjust the space factor, which is usually done by inserting \cs{@} +before the full stop. + +The next example shows one way of achieving this. + +\begin{example}{Abbreviations with Full Stops (Periods)}{ex:dotabbr} +As from version 4.16, there's now a hook (\ics{glspostlinkhook}) +that's called at the very end of the \glslike\ and \glstextlike\ +commands. This can be redefined to check if the following character +is a full stop. The \sty{amsgen} package (which is automatically +loaded by \styfmt{glossaries}) provides an internal command +called \cs{new@ifnextchar} that can be used to determine if the +given character appears next. (For more information see the +\sty{amsgen} documentation.) + +It's possible that I~may also want acronyms or contractions in my +document, so I~need some way to differentiate between them. +Here I'm going to use the same method as in +example~\ref{ex:addstoragekey} where a~new field is defined +to indicate the type of abbreviation: +\begin{verbatim} +\glsaddstoragekey{abbrtype}{word}{\abbrtype} + +\newcommand*{\newabbr}[1][]{\newacronym[abbrtype=initials,#1]} +\end{verbatim} +Now I just use \ics{newacronym} for the acronyms, for example, +\begin{verbatim} +\newacronym{laser}{laser}{light amplification by stimulated +emission of radiation} +\end{verbatim} +and my new command \cs{newabbr} for initials, for example, +\begin{verbatim} +\newabbr{eg}{e.g.}{exempli gratia} +\newabbr{ie}{i.e.}{id est} +\newabbr{bsc}{B.Sc.}{Bachelor of Science} +\newabbr{ba}{B.A.}{Bachelor of Arts} +\newabbr{agm}{A.G.M.}{annual general meeting} +\end{verbatim} +Within \cs{glspostlinkhook} the entry's label can be accessed using +\ics{glslabel} and \ics{ifglsfieldeq} can be used to determine if +the current entry has the new \texttt{abbrtype} field set to +\qt{initials}. If it doesn't, then nothing needs to happen, but if +it does, a~check is performed to see if the next character is a~full +stop. If it is, this signals the end of a~sentence otherwise it's +mid-sentence. + +Remember that internal commands within the document file (rather +than in a~class or package) need to be placed between +\ics{makeatletter} and \ics{makeatother}: +\begin{verbatim} +\makeatletter +\renewcommand{\glspostlinkhook}{% + \ifglsfieldeq{\glslabel}{abbrtype}{initials}% + {\new@ifnextchar.\doendsentence\doendword} + {}% +} +\makeatother +\end{verbatim} +In the event that a full stop is found \cs{doendsentence} is +performed but it will be followed by the full stop, which needs to +be discarded. Otherwise \cs{doendword} will be done but it won't be +followed by a full stop so there's nothing to discard. The +definitions for these commands are: +\begin{verbatim} +\newcommand{\doendsentence}[1]{\spacefactor=10000{}} +\newcommand{\doendword}{\spacefactor=1000{}} +\end{verbatim} +Now, I can just do \verb|\gls{bsc}| mid-sentence and +\verb|\gls{phd}.| at the end of the sentence. The terminating full +stop will be discarded in the latter case, but it won't be discarded +in, say, \verb|\gls{laser}.| as that doesn't have the +\texttt{abbrtype} field set to \qt{initials}. + +This also works on first use when the style is set to one of the +\meta{long} (\meta{short}) styles but it will fail with the +\meta{short} (\meta{long}) styles as in this case the terminating +full stop shouldn't be discarded. Since \ics{glspostlinkhook} is +used after the \firstuseflag\ has been unset for the entry, this +can't be fixed by simply checking with \ics{ifglsused}. One possible +solution to this is to redefine \ics{glslinkpostsetkeys} to check +for the \firstuseflag\ and define a macro that can then be used in +\ics{glspostlinkhook}. + +The other thing to consider is what to do with plurals. One +possibility is to check for plural use within \cs{doendsentence} +(using \ics{glsifplural}) and put the full stop back if the plural +has been used. + +The complete document is contained in the sample file +\samplefile{-dot-abbr}. +\end{example} + \section{Displaying the List of Acronyms} \label{sec:disploa} @@ -8211,13 +8942,13 @@ document build order is now (at least): \texttt{(pdf)latex}, \texttt{(pdf)latex}, \texttt{makeglossaries}, \texttt{(pdf)latex}. \begin{example}{Don't index entries that are only used once}{sec:entrycount} -In this example, the acronyms that have only been used once (on the previous run) +In this example, the abbreviations that have only been used once (on the previous run) only have their long form shown with \cs{cgls}. \begin{verbatim} \documentclass{article} \usepackage[colorlinks]{hyperref} -\usepackage[nomain,acronym]{glossaries} +\usepackage[acronym]{glossaries} \makeglossaries \glsenableentrycount @@ -8241,7 +8972,7 @@ These entries are only used once: \cgls{sql}, \cgls{rdbms}, \end{document} \end{verbatim} After a complete document build (\texttt{latex}, \texttt{latex}, -\texttt{makeglossaries}, \texttt{latex}) the list of acronyms only +\texttt{makeglossaries}, \texttt{latex}) the list of abbrevaitions only includes the entries HTML, CSS and RDSMS. The entries SQL, RDBMS and XML only have their long forms displayed and don't have a~hyperlink. @@ -8293,6 +9024,12 @@ package options \pkgopt{entrycounter}, \pkgopt{counterwithin} and \sectionref{sec:pkgopts-printglos}. There is a summary of available styles in \tableref{tab:styles}. +\begin{important} +Note that the group styles (such as \glostyle{listgroup}) will +have unexpected results if used with the \pkgopt[def]{sort} +or \pkgopt[use]{sort} options. +\end{important} + \begin{table}[htbp] \caption[Glossary Styles]{Glossary Styles. An asterisk in the style name indicates anything that matches that doesn't match any @@ -9384,6 +10121,9 @@ that displays each entry in a \env{longtable} as follows: This section describes some utility commands. Additional commands can be found in the documented code (glossaries-code.pdf). +\section{Loops} +\label{sec:loops} + \begin{important} Some of the commands described here take a comma-separated list as an argument. As with \LaTeX's \cs{@for} command, make sure your list @@ -9430,6 +10170,9 @@ defined glossaries (except the ignored ones). At each iteration (The current glossary label can be obtained using \cs{glsentrytype}\marg{cs} within \meta{body}.) +\section{Conditionals} +\label{sec:conditionals} + \begin{definition}[\DescribeMacro{\ifglossaryexists}] \cs{ifglossaryexists}{\meta{label}}{\meta{true part}}{\meta{false part}} @@ -9543,6 +10286,205 @@ is performed and a warning is issued. Unlike the above commands, such as \cs{ifglshasshort}, an error occurs if the entry is undefined. +You can test if the value of the field is equal to a given string +using: +\begin{definition}[\DescribeMacro\ifglsfieldeq] +\cs{ifglsfieldeq}\marg{label}\marg{field}\marg{string}\marg{true}\marg{false} +\end{definition} +In this case the \meta{field} must be the field name not the key +(see \tableref{tab:fieldmap}). If the field isn't recognised, an +error will occur. This command internally uses +\sty{etoolbox}'s \cs{ifcsstring} to perform the comparison. \emph{The +string is not expanded during the test.} + +The result may vary depending on whether or not expansion is on for +the given field (when the entry was defined). For example: +\begin{verbatim} +\documentclass{article} + +\usepackage{glossaries} + +\newcommand*{\foo}{FOO} + +\newglossaryentry{sample1}{name={sample1},description={an example}, +user1={FOO}} +\newglossaryentry{sample2}{name={sample2},description={an example}, +user1={\foo}} + +\begin{document} +\ifglsfieldeq{sample1}{useri}{FOO}{TRUE}{FALSE}. + +\ifglsfieldeq{sample2}{useri}{FOO}{TRUE}{FALSE}. +\end{document} +\end{verbatim} +This will produce \qt{TRUE} in both cases since expansion is on, so +\cs{foo} was expanded to \qt{FOO} when \texttt{sample2} was defined. +If the tests are changed to: +\begin{verbatim} +\ifglsfieldeq{sample1}{useri}{\foo}{TRUE}{FALSE}. + +\ifglsfieldeq{sample2}{useri}{\foo}{TRUE}{FALSE}. +\end{verbatim} +then this will produce \qt{FALSE} in both cases. Now suppose +expansion is switched off for the \gloskey{user1} key: +\begin{verbatim} +\documentclass{article} + +\usepackage{glossaries} + +\newcommand*{\foo}{FOO} + +\glssetnoexpandfield{useri} + +\newglossaryentry{sample1}{name={sample1},description={an example}, +user1={FOO}} +\newglossaryentry{sample2}{name={sample2},description={an example}, +user1={\foo}} + +\begin{document} +\ifglsfieldeq{sample1}{useri}{FOO}{TRUE}{FALSE}. + +\ifglsfieldeq{sample2}{useri}{FOO}{TRUE}{FALSE}. +\end{document} +\end{verbatim} +This now produces \qt{TRUE} for the first case (comparing \qt{FOO} +with \qt{FOO}) and \qt{FALSE} for the second case (comparing +\qt{\cs{foo}} with \qt{FOO}). + +The reverse happens in the following: +\begin{verbatim} +\documentclass{article} + +\usepackage{glossaries} + +\newcommand*{\foo}{FOO} + +\glssetnoexpandfield{useri} + +\newglossaryentry{sample1}{name={sample1},description={an example}, +user1={FOO}} +\newglossaryentry{sample2}{name={sample2},description={an example}, +user1={\foo}} + +\begin{document} +\ifglsfieldeq{sample1}{useri}{\foo}{TRUE}{FALSE}. + +\ifglsfieldeq{sample2}{useri}{\foo}{TRUE}{FALSE}. +\end{document} +\end{verbatim} +This now produces \qt{FALSE} for the first case (comparing \qt{FOO} +with \qt{\cs{foo}}) and \qt{TRUE} for the second case (comparing +\qt{\cs{foo}} with \qt{\cs{foo}}). + +You can test if the value of a field is equal to the replacement +text of a command using: +\begin{definition}[\DescribeMacro\ifglsfielddefeq] +\cs{ifglsfielddefeq}\marg{label}\marg{field}\marg{command}\marg{true}\marg{false} +\end{definition} +This internally uses \sty{etoolbox}'s \cs{ifdefstrequal} command to +perform the comparison. The argument \meta{command} must be a macro. + +For example: +\begin{verbatim} +\documentclass{article} + +\usepackage{glossaries} + +\newcommand*{\foo}{FOO} + +\glssetnoexpandfield{useri} + +\newglossaryentry{sample1}{name={sample1},description={an example}, +user1={FOO}} +\newglossaryentry{sample2}{name={sample2},description={an example}, +user1={\foo}} + +\begin{document} +\ifglsfielddefeq{sample1}{useri}{\foo}{TRUE}{FALSE}. + +\ifglsfielddefeq{sample2}{useri}{\foo}{TRUE}{FALSE}. +\end{document} +\end{verbatim} +Here, the first case produces \qt{TRUE} since the value of the +\texttt{useri} field (\qt{FOO}) is the same as the replacement text +(definition) of \cs{foo} (\qt{FOO}). We have the result +\qt{\texttt{FOO}} is equal to \qt{\texttt{FOO}}. + +The second case produces \qt{FALSE} since the value of the +\texttt{useri} field (\qt{\cs{foo}}) is not the same as the replacement +text (definition) of \cs{foo} (\qt{FOO}). No expansion has been +performed on the value of the \texttt{useri} field. We have the +result \qt{\cs{foo}} is not equal to \qt{\texttt{FOO}}. + +If we add: +\begin{verbatim} +\newcommand{\FOO}{\foo} +\ifglsfielddefeq{sample2}{useri}{\FOO}{TRUE}{FALSE}. +\end{verbatim} +we now get \qt{TRUE} since the value of the +\texttt{useri} field (\qt{\cs{foo}}) is the same as the replacement +text (definition) of \cs{FOO} (\qt{\cs{foo}}). We have the result \qt{\cs{foo}} +is equal to \qt{\cs{foo}}. + +There is a similar command that requires the control sequence name +(without the leading backslash) instead of the actual control sequence: +\begin{definition}[\DescribeMacro\ifglsfieldcseq] +\cs{ifglsfieldcseq}\marg{label}\marg{field}\marg{csname}\marg{true}\marg{false} +\end{definition} +This internally uses \sty{etoolbox}'s \cs{ifcsstrequal} command +instead of \cs{ifdefstrequal}. + +\section{Fetching and Updating the Value of a Field} +\label{sec:fetchset} + +You can fetch the value of a given field and store it in a control +sequence using: +\begin{definition}[\DescribeMacro\glsfieldfetch] +\cs{glsfieldfetch}\marg{label}\marg{field}\marg{cs} +\end{definition} +where \meta{label} is the label identifying the glossary entry, +\meta{field} is the field label (see \tableref{tab:fieldmap}) +and \meta{cs} is the control sequence in which to store the value. +Remember that \meta{field} is the internal label and is not +necessarily the same as the key used to set that field in the +argument of \cs{newglossaryentry} (or the optional argument of +\cs{newacronym}). + +You can change the value of a given field using one of the following +commands. Note that these commands only change the value of the +given field. They have no affect on any related field. For example, +if you change the value of the \gloskey{text} field, it won't modify the +value given by the \gloskey{name}, \gloskey{plural}, \gloskey{first} or any other related key. + +In all the four related commands below, \meta{label} and +\meta{field} are as above and \meta{definition} is the new value +of the field. + +\begin{definition}[\DescribeMacro\glsfielddef] +\cs{glsfielddef}\marg{label}\marg{field}\marg{definition} +\end{definition} +This uses \cs{def} to change the value of the field (so it will be +localised by any grouping). + +\begin{definition}[\DescribeMacro\glsfieldedef] +\cs{glsfieldedef}\marg{label}\marg{field}\marg{definition} +\end{definition} +This uses \cs{edef} to change the value of the field (so it will be +localised by any grouping). Any fragile commands contained in the +\meta{definition} must be protected. + +\begin{definition}[\DescribeMacro\glsfieldgdef] +\cs{glsfieldgdef}\marg{label}\marg{field}\marg{definition} +\end{definition} +This uses \cs{gdef} to change the value of the field. + +\begin{definition}[\DescribeMacro\glsfieldxdef] +\cs{glsfieldxdef}\marg{label}\marg{field}\marg{definition} +\end{definition} +This uses \cs{xdef} to change the value of the field. Any fragile +commands contained in the \meta{definition} must be protected. + + \chapter{Prefixes or Determiners}\label{sec:prefix} The \sty{glossaries-prefix} package provides @@ -9847,21 +10789,22 @@ that you also read the \sty{accsupp} documentation. \chapter{Troubleshooting} \label{sec:trouble} -The \styfmt{glossaries} package comes with a minimal file called -\texttt{minimalgls.tex} which can be used for testing. This -should be located in the \texttt{samples} subdirectory (folder) -of the \styfmt{glossaries} documentation directory. The location -varies according to your operating system and \TeX\ installation. -For example, on my Linux partition it can be found in -\texttt{\slash usr\slash local\slash texlive\slash 2013\slash -texmf-dist\slash doc\slash latex\slash glossaries/}. +The \styfmt{glossaries} package comes with some minimal example +files, \texttt{minimalgls.tex}, \texttt{mwe-gls.tex}, +\texttt{mwe-acr.tex} and \texttt{mwe-acr-desc.tex}, which can be +used for testing. These should be located in the \texttt{samples} +subdirectory (folder) of the \styfmt{glossaries} documentation +directory. The location varies according to your operating system +and \TeX\ installation. For example, on my Linux partition it can +be found in \texttt{/usr\slash local\slash texlive\slash +2014\slash texmf-dist\slash doc\slash latex\slash glossaries/}. Further information on debugging \LaTeX\ code is available at \url{http://www.dickimaw-books.com/latex/minexample/}. If you have any problems, please first consult the \urlfootref{http://www.dickimaw-books.com/faqs/glossariesfaq.html}{\styfmt{glossaries} FAQ}. If that doesn't help, try posting your query to somewhere like the -comp.text.tex newsgroup, the +\texttt{comp.text.tex} newsgroup, the \urlfootref{http://www.latex-community.org/}{\LaTeX\ Community Forum} or \urlfootref{http://tex.stackexchange.com/}{\TeX\ on StackExchange}. Bug reports can be submitted via |