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 | 1271 |
1 files changed, 679 insertions, 592 deletions
diff --git a/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex b/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex index 41b240eeb8f..2ce60f21764 100644 --- a/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex +++ b/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex @@ -49,9 +49,6 @@ style=altlist,\\ nogroupskip]\{glossaries\} \end{tabbing} -\cs{glsnoexpandfields}\newline -\cs{renewcommand*}\{\ics{glsseeformat}\}[3][\ics{seename}]\{\% \newline -(\ics{xmakefirstuc}\{\#1\} \ics{glsseelist}\{\#2\}.)\} \end{ttfamily} } @@ -70,6 +67,11 @@ \newcommand*{\htextbf}[1]{\textbf{\hyperpage{#1}}} \newcommand*{\itermdef}[1]{\index{#1|htextbf}} +\newcommand{\itempar}[1]{\item[{#1}]\mbox{}\par} + +\newcommand{\glslike}{\hyperref[sec:gls-like]{\cs{gls}-like}} +\newcommand{\glstextlike}{\hyperref[sec:glstext-like]{\cs{glstext}-like}} + \IndexPrologue{\chapter*{\indexname} \markboth{\indexname}{\indexname}} @@ -207,7 +209,7 @@ text={first use text},% description={The text that is displayed on \gls{firstuse}, which is governed by the \gloskey{first} and \gloskey{firstplural} keys of \ics{newglossaryentry}. (May be overridden by -\ics{glsdisp}.)}% +\ics{glsdisp} or by \ics{defglsentry}.)}% } \longnewglossaryentry{sanitize}{% @@ -235,7 +237,7 @@ user2={sanitization\protect\iterm{sanitize}}% text={Latin character\iterm{Latin character}}, sort={Latin character}, description={One of the letters \texttt{a}, \ldots, \texttt{z}, - \texttt{A}, \ldots, \texttt{Z}. + \texttt{A}, \ldots, \texttt{Z}\@. See also \gls{exlatinchar}.} } @@ -265,8 +267,8 @@ user2={sanitization\protect\iterm{sanitize}}% name={Non-Latin Character\itermdef{non-Latin character}}, text={non-Latin character\iterm{non-Latin character}}, sort={non-Latin character}, - description={An \gls{exlatinchar} or a~character from - a~non-\gls{latinalph}.} + description={An \gls{exlatinchar} or a~character that isn't + a~\gls{latinchar}.} } \newglossaryentry{latinalph}{% @@ -362,18 +364,18 @@ and~\hyperlink{option#2}{#2}} \MakeShortVerb{"} \DeleteShortVerb{\|} - \title{User Manual for glossaries.sty v4.07} + \title{User Manual for glossaries.sty v4.08} \author{Nicola L.C. Talbot\\% \url{http://www.dickimaw-books.com/}} - \date{2014-04-04} + \date{2014-07-30} \maketitle \begin{abstract} The \styfmt{glossaries} package provides a means to define terms or acronyms or symbols that can be referenced within your document. Sorted lists with collated \glslink{entrylocation}{locations} can be -generated using a supplementary \gls{indexingapp}. +generated either using \TeX\ or using a supplementary \gls{indexingapp}. \end{abstract} \begin{important} @@ -419,7 +421,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.07}. +\qt{Documented Code for glossaries v4.08}. This includes the documented code for the \sty{mfirstuc} package. \item[INSTALL] Installation instructions. @@ -506,7 +508,7 @@ first define your entries (terms, symbols or abbreviations). Then you can reference these within your document (like \cs{cite} or \cs{ref}). You can also, optionally, display a~list of the entries you have referenced in your document (the glossary). This last part, -displaying the glossary is the part that most new users find +displaying the glossary, is the part that most new users find difficult. There are three options: \begin{description} @@ -703,7 +705,7 @@ An overview of these three options is given in \label{tab:options} {% \centering - \begin{tabular}{>{\raggedright}p{0.3\textwidth}ccc} + \begin{tabular}{>{\raggedright}p{0.35\textwidth}ccc} & \bfseries \opt1 & \bfseries \opt2 & \bfseries \opt3\\ Requires an external application? & \no & \yes & \yes\\ @@ -714,7 +716,7 @@ An overview of these three options is given in \no\textsuperscript{\textdagger} & \no & \yes\\ Efficient sort algorithm? & \no & \yes & \yes\\ - Can use a different sort algorithm for each glossary? & + Can use a different sort method for each glossary? & \yes & \no & \no\\ Can form ranges in the location lists? & \no & \yes & \yes\\ @@ -1170,7 +1172,7 @@ latex sampleutf8 makeglossaries sampleutf8 latex sampleutf8 \end{prompt} -you will see that the entries that start with a \gls{nonlatinchar} +you will see that the entries that start with an \gls{exlatinchar} now appear in the symbols group, and the word \qt{man\oe uvre} is now after \qt{manor} instead of before it. If you are unable to use \gls{makeglossaries}, the call to \gls{makeindex} is as @@ -1224,7 +1226,7 @@ latex sampleSort latex sampleSort \end{prompt} -\exitem{-nomathhyper} This document illustrates how to selective +\exitem{-nomathhyper} This document illustrates how to selectively enable and disable entry hyperlinks in \ics{glsentryfmt}. \exitem{-entryfmt} This document illustrates how to change the @@ -1247,8 +1249,63 @@ viewers don't use the accessibility support. Information about the \styfmt{glossaries-accsupp} package can be found in \sectionref{sec:accsupp}. +\exitem{-ignored} This document defines an ignored glossary for +common terms that don't need a definition. + \end{samplelist} +\section{Dummy Entries for Testing} +\label{sec:lipsum} + +In addition to the sample files described above, \sty{glossaries} also provides +some files containing lorum ipsum dummy entries. These are provided +for testing purposes and are on \TeX's path (in +\texttt{tex\slash latex\slash glossaries\slash test-entries}) so they can be included +via \ics{input} or \ics{loadglsentries}. The files are as follows: +\begin{description} +\item[example-glossaries-brief.tex] These entries all have brief +descriptions. + +\item[example-glossaries-long.tex] These entries all have long +descriptions. + +\item[example-glossaries-multipar.tex] These entries all have +multi-paragraph descriptions. + +\item[example-glossaries-symbols.tex] These entries all use the +\gloskey{symbol} key. + +\item[example-glossaries-images.tex] These entries use the +\gloskey{user1} key to store the name of an image file. (The images +are provided by the \sty{mwe} package and should be on \TeX's path.) +One entry doesn't have an associated image to help test for a~missing key. + +\item[example-glossaries-acronym.tex] These entries are all acronyms. + +\item[example-glossaries-acronym-desc.tex] These entries are all +acronyms that use the \gloskey{description} key. + +\item[example-glossaries-acronyms-lang.tex] These entries are all +acronyms, where some of them have a~translation supplied in the +\gloskey{user1} key. + +\item[example-glossaries-parent.tex] These are hierarchical entries +where the child entries use the \gloskey{name} key. + +\item[example-glossaries-childnoname.tex] These are hierarchical entries +where the child entries don't use the \gloskey{name} key. + +\item[example-glossaries-cite.tex] These entries use the +\gloskey{user1} key to store a citation key (or comma-separated list +of citation keys). The citations are defined in \texttt{xampl.bib}, +which should be available on all modern \TeX\ distributions. +One entry doesn't have an associated citation to help test for a~missing +key. +\end{description} + +The sample file \texttt{glossary-lipsum-examples.tex} in the +\texttt{doc\slash latex\slash glossaries\slash samples} directory +uses all these files. \section{Multi-Lingual Support} \label{sec:languages} @@ -1474,6 +1531,11 @@ This section is only applicable if you have chosen \optsor23. You can ignore this section if you have chosen \opt1. \end{important} +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}. + 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 @@ -1709,7 +1771,7 @@ 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.14. +2.15. \end{important} \subsection[Using xindy explicitly (Option~3)]{Using @@ -2059,11 +2121,44 @@ See \sectionref{sec:fixednames} for further details. \pkgopt[false]{translate} and may be passed via the document class options. +\item[\pkgopt{nohypertypes}] Use this option if you have multiple +glossaries and you want to suppress the entry hyperlinks for a +particular glossary or glossaries. The value of this option should +be a comma-separated list of glossary types where \ics{gls} etc +shouldn't have hyperlinks by default. Make sure you enclose the +value in braces if it contains any commas. Example: +\begin{verbatim} +\usepackage[acronym,nohypertypes={acronym,notation}] + {glossaries} +\newglossary[nlg]{notation}{not}{ntn}{Notation} +\end{verbatim} +The values must be fully expanded, so \textbf{don't} try +\texttt{nohypertypes\discretionary{}{}{}=\ics{acronymtype}}. You may also use +\begin{definition} +\ics{GlsDeclareNoHyperList}\marg{list} +\end{definition} +instead or additionally. +See \sectionref{sec:glslink} for further details. + \item[\pkgopt{hyperfirst}] This is a boolean option that specifies whether each term has a hyperlink on \firstuse. The default is \pkgopt[true]{hyperfirst} (terms on \gls{firstuse} have a hyperlink, unless explicitly suppressed using starred versions of commands -such as \ics{gls*}). Note that this applies to all glossary types. +such as \ics{gls*} or by identifying the glossary with +\pkgopt{nohypertypes}, described above). Note that +\pkgopt{nohypertypes} overrides \pkgopt[true]{hyperfirst}. +This option only affects commands that check the \firstuseflag, such +as the \glslike\ commands (for example, \ics{gls} or +\ics{glsdisp}), but not the \glstextlike\ commands +(for example, \ics{glslink} or \ics{glstext}). + +The \pkgopt{hyperfirst} setting applies to +all glossary types (unless identified by \pkgopt{nohypertypes} or +defined with \ics{newignoredglossary}). It can be overridden on an +individual basis by explicitly setting the \gloskey[glslink]{hyper} key +when referencing an entry (or by using the plus or starred +version of the referencing command). + It may be that you only want to apply this to just the acronyms (where the first use explains the meaning of the acronym) but not for ordinary glossary entries (where the first use is identical to @@ -2078,24 +2173,29 @@ For example: \glsunsetall[main] \end{verbatim} -\item[\pkgopt{nohypertypes}] Use this option if you have multiple -glossaries and you want to suppress the entry hyperlinks for a -particular glossary or glossaries. The value of this option should -be a comma-separated list of glossary types where \ics{gls} etc -shouldn't have hyperlinks by default. Make sure you enclose the -value in braces if it contains any commas. Example: +Alternatively you can redefine the hook +\begin{definition}[\DescribeMacro\glslinkcheckfirsthyperhook] +\cs{glslinkcheckfirsthyperhook} +\end{definition} +which is used by the commands that check the \firstuseflag, such +as \ics{gls}. Within the definition of this command, you can use +\ics{glslabel} to reference the entry label and \ics{glstype} to +reference the glossary type. You can also use \ics{ifglsused} +to determine if the entry has been used. You can test if an entry is +an acronym by checking if it has the \gloskey{long} key set using +\ics{ifglshaslong}. For example, to switch off the hyperlink on +first use just for acronyms: \begin{verbatim} -\usepackage[acronym,nohypertypes={acronym,notation}] - {glossaries} -\newglossary[nlg]{notation}{not}{ntn}{Notation} +\renewcommand*{\glslinkcheckfirsthyperhook}{% + \ifglsused{\glslabel}{}% + {% + \ifglshaslong{\glslabel}{\setkeys{glslink}{hyper=false}}{}% + }% +} \end{verbatim} -The values must be fully expanded, so \textbf{don't} try -\texttt{nohypertypes\discretionary{}{}{}=\ics{acronymtype}}. You may also use -\begin{definition} -\ics{GlsDeclareNoHyperList}\marg{list} -\end{definition} -instead or additionally. -See \sectionref{sec:glslink} for further details. + +Note that this hook isn't used by the commands that don't check the +\firstuseflag, such as \ics{glstext}. \item[\pkgopt{savenumberlist}] This is a boolean option that specifies whether or not to gather and store the \gls{numberlist} @@ -2451,6 +2551,7 @@ allows you to specify sort methods for individual glossaries via the \gloskey[printnoidxglossary]{sort} key in the optional argument of \ics{printnoidxglossary}. If you have multiple glossaries in your document and you are using \opt1, only use +the package options \pkgopt[def]{sort} or \pkgopt[use]{sort} if you want to set this sort method for \emph{all} your glossaries. @@ -2676,6 +2777,34 @@ and code page can be set via \ics{GlsSetXdyLanguage} and \verb|xindy={glsnumbers=false}| and may be used as a document class option. +\item[\pkgopt{automake}] This is a boolean option (new to version +4.08) that will attempt to run \gls{makeindex} or \gls{xindy} using +\TeX's \ics{write18} mechanism at the end of the document. Since +this mechanism can be a security risk, some \TeX\ distributions +disable it completely, in which case this option won't have an +effect. (If this option doesn't appear to work, search the log file +for \qt{runsystem} and see if it is followed by +\qt{enabled} or \qt{disabled}.) + +Some distributions allow \cs{write18} in a restricted mode. +This mode has a~limited number of trusted applications, which +usually includes \gls{makeindex} but may not include \gls{xindy}. So +if you have the restricted mode on, \pkgopt{automake} should work +with \gls*{makeindex} but may not work with \gls{xindy}. + +However even in unrestricted mode this option may not work with +\gls*{xindy} as \gls*{xindy} uses language names that don't always +correspond with \ics{babel}'s language names. (The +\gls{makeglossaries} script applies mappings to assist you.) +Note that you still need at least two \LaTeX\ runs to ensure the document +is up-to-date with this setting. + +Since this package option attempts to run the \gls{indexingapp} on +every \LaTeX\ run, its use should be considered a last resort for +those who can't work out how to incorporate the \gls*{indexingapp} +into their document build. The default value for this option is +\pkgopt[false]{automake}. + \end{description} \section{Acronym Options} @@ -3807,6 +3936,17 @@ type has been specified by \ics{glsdefaulttype}, which is what This is a~preamble-only command. You may also use \ics{input} to load the file but don't use \ics{include}. +\begin{important} +If you want to use \ics{AtBeginDocument} to \cs{input} all your entries +automatically at the start of the document, add the +\cs{AtBeginDocument} command \emph{before} you load the +\sty{glossaries} package (and \sty{babel}, if you are also loading +that) to avoid the creation of the +\texttt{.glsdefs} file and any associated problems that are caused +by defining commands in the \env{document} environment. +(See \sectionref{sec:docdefs}.) +\end{important} + \begin{example}{Loading Entries from Another File}{ex:loadgls} Suppose I have a file called \texttt{myentries.tex} which contains: \begin{verbatim} @@ -3919,20 +4059,14 @@ entry and \meta{target glossary label} is the unique label identifying the glossary in which to put the entry. Note that no check is performed to determine the existence of -the target glossary. This means that you can, for example, move an -entry to an undefined glossary so you can use the entry in the -document text but not have it listed in any of the glossaries. -(Maybe you have an acronym that is so common it doesn't need listing.) +the target glossary. If you want to move an entry to a glossary +that's skipped by \ics{printglossaries}, then define an ignored +glossary with \ics{newignoredglossary}. (See +\sectionref{sec:newglossary}.) \begin{important} -If you move an entry to an undefined glossary and you have -hyperlinked entries, the link will point to an undefined target. -(Unless you identify that glossary using \pkgopt{nohypertypes} or -\ics{GlsDeclareNoHyperList}, as described in \sectionref{sec:glslink}.) -Also, you will get warnings about no file defined for that glossary -(unless you use the \pkgopt{nowarn} package option). Unpredictable -results may occur if you move an entry to a different glossary from -its parent or children. +Unpredictable results may occur if you move an entry to a different +glossary from its parent or children. \end{important} \section{Drawbacks With Defining Entries in the Document Environment} @@ -3954,11 +4088,27 @@ subsequently shuffle sections around, you could end up using an entry before it has been defined. \item Entry information is required when displaying the glossary. -If this occur at the start of the document, the entry details are +If this occurs at the start of the document, but the entries aren't +defined until later, then the entry details are being looked up before the entry has been defined. + + \item If you use a package, such as \sty{babel}, that makes +certain characters active at the start of the \env{document} +environment, there will be a~problem if those characters have +a~special significance when defining glossary entries. +These characters include the double-quote \verb|"| character, the +exclamation mark \texttt{!} character, the question mark \verb|?| +character, and the pipe \verb"|" character. They +must not be active when defining a~glossary entry where they occur +in the \gloskey{sort} key (and they should be avoided in the label +if they may be active at any point in the document). Additionally, +the comma \texttt{,} character and the equals \texttt{=} character +should not be active when using commands that have +\meta{key}=\meta{value} arguments. + \end{enumerate} -To overcome these problems, as from version 4.0 the +To overcome the first two problems, as from version 4.0 the \styfmt{glossaries} package modifies the definition of \cs{newglossaryentry} at the beginning of the \env{document} environment so that the definitions are written to an external file @@ -4020,6 +4170,7 @@ referred to as the location list\index{location list|see{number list}}. Both \gls{makeindex} and \gls{xindy} (\optsand23) concatenate a sequence of~3 or more consecutive pages into~a range. With \gls*{xindy} (\opt3) you can vary the minimum sequence length using +\linebreak \ics{GlsSetXdyMinRangeLength}\marg{n} where \meta{n} is either an integer or the keyword \texttt{none} which indicates that there should be no range formation. @@ -4124,21 +4275,26 @@ which is described in \sectionref{sec:customxr}. \chapter{Links to Glossary Entries} \label{sec:glslink} -Once you have defined a glossary entry using \ics{newglossaryentry}, +Once you have defined a glossary entry using \ics{newglossaryentry} +or \ics{newacronym} (see \sectionref{sec:acronyms}), you can refer to that entry in the document using one of the -commands listed in this section. The text which appears at that +commands listed in \sectionref{sec:gls-like} or +\sectionref{sec:glstext-like}. The text which appears at that point in the document when using one of these commands is referred -to as the \gls{linktext} (even if there are no hyperlinks). The -commands in this section also add a line to an external file that is +to as the \gls{linktext} (even if there are no hyperlinks). These +commands also add a line to an external file that is used to generate the relevant entry in the glossary. This information includes an associated location that is added to the \gls{numberlist} for that entry. By default, the location refers to the page number. For further information on number lists, see -\sectionref{sec:numberlists}. +\sectionref{sec:numberlists}. These external files need to be +post-processed by \gls{makeindex} or \gls{xindy} unless you have +chosen \opt1. If you don't use \ics{makeglossaries} these external +files won't be created. \begin{important} -It is strongly recommended that you don't use the commands -defined in this section in the arguments of sectioning or caption +I strongly recommend that you don't use the commands +defined in this chapter in the arguments of sectioning or caption commands or any other command that has a moving argument. \end{important} @@ -4147,12 +4303,13 @@ The above warning is particularly important if you are using the package. Instead, use one of the \emph{expandable} commands listed in \sectionref{sec:glsnolink} (such as \ics{glsentrytext} \emph{but not} the non-expandable -case changing versions like \ics{Glsentrytext}) or provide an +case changing versions like \ics{Glsentrytext}). Alternatively, provide an alternative via the optional argument to the sectioning\slash caption -command. Examples: +command or use \sty{hyperref}'s \ics{texorpdfstring}. Examples: \begin{verbatim} \chapter{An overview of \glsentrytext{perl}} \chapter[An overview of Perl]{An overview of \gls{perl}} +\chapter{An overview of \texorpdfstring{\gls{perl}}{Perl}} \end{verbatim} If you want the \gls{linktext} to produce a hyperlink to the @@ -4176,56 +4333,16 @@ format doesn't correctly size hyperlinks in subscripts or superscripts. This means that if you define a term that may be used as a subscript or superscript, if you use the DVI format, it won't come out the correct size. + +These are limitations of the DVI format not of the \sty{glossaries} +package. \end{important} It may be that you only want terms in certain glossaries to have -links, but not for other glossaries. In this case, you can use the +hyperlinks, but not for other glossaries. In this case, you can use the package option \pkgopt{nohypertypes} to identify the glossary lists -that shouldn't have hyperlinked \gls{linktext}. For example, suppose -your document contains lots of technical acronyms that the reader -might not know, but it also contains some very common acronyms that -most readers will recognise. So you might want two acronym lists, -but only the technical list will get displayed in your document. The -technical acronyms can be hyperlinked to that list, but common -acronyms shouldn't have hyperlinks as there's no target for them. In -this case, identify the common acronym list as having -non-hyperlinked entries using \pkgopt{nohypertypes}. Example: -\begin{verbatim} -\usepackage[acronym,nohypertypes={common}]{glossaries} -\newglossary{common}{cacr}{cacn}{Common Acronyms} -\end{verbatim} -Alternatively, you can use -\begin{definition}[\DescribeMacro{\GlsDeclareNoHyperList}] -\cs{GlsDeclareNoHyperList}\marg{type} -\end{definition} -For example: -\begin{verbatim} -\usepackage[acronym]{glossaries} -\newglossary{common}{cacr}{cacn}{Common Acronyms} -\GlsDeclareNoHyperList{common} -\end{verbatim} -Note that no check is performed to see if the glossary types listed -in \pkgopt{nohypertypes} or \cs{GlsDeclareNoHyperList} have been -defined. - -\begin{important} -The values must be fully expanded, so \textbf{don't} try -\verb|nohypertypes=\acronymtype| or -\verb|\GlsDeclareNoHyperList{\acronymtype}|. -Also, avoid unnecessary braces. For example, -\verb|\GlsDeclareNoHyperList{{acronym},{common}}| won't work. You do -however need an enclosing brace for the whole list when using the -package option. So -\begin{verbatim} -\usepackage[nohypertypes={acronym,common}]{glossaries} -\end{verbatim} -is correct, but \verb|nohypertypes={{acronym},{common}}| won't work. -\end{important} - -You can override the effect of \pkgopt{nohypertypes} or -\cs{GlsDeclareNoHyperList} by explicitly setting the -\gloskey[glslink]{hyper} option in commands such as \cs{glslink} or -\cs{gls}. +that shouldn't have hyperlinked \gls{linktext}. See +\sectionref{sec:pkgopts-general} for further details. The way the \gls{linktext} is displayed depends on \begin{definition}[\DescribeMacro{\glstextformat}] @@ -4241,29 +4358,45 @@ redefining \ics{glsentryfmt}. See \sectionref{sec:glsdisplay} for further details. Each entry has an associated conditional referred to as the -\firstuseflag. This determines whether \ics{gls} or -\ics{glspl} (or their upper case variants) should use the -value of the \gloskey{first}\slash\gloskey{firstplural} or -\gloskey{text}\slash\gloskey{plural} keys. Note that an -entry can be used without affecting the \firstuseflag\ (for example, -when used with \cs{glslink}). See \sectionref{sec:glsunset} for -commands that unset or reset this conditional. - - -The command: -\begin{definition}[\DescribeMacro{\glslink}] -\cs{glslink}\oarg{options}\marg{label}\marg{text} -\end{definition} -will place \cs{glstextformat}\marg{text} in the document at that -point and add a line into the associated glossary file for the -glossary entry given by \meta{label}. If hyperlinks are supported, -\meta{text} will be a hyperlink to the relevant line in the -glossary. (Note that this command doesn't affect the \firstuseflag: -use \ics{glsdisp} instead.) The optional argument \meta{options} -must be a \meta{key}=\meta{value} list which can take any of the -following keys: - +\firstuseflag. Some of the commands described in this chapter +automatically unset this flag and can also use it +to determine what text should be displayed. These types of commands +are the \glslike\ commands and are described in +\sectionref{sec:gls-like}. The commands that don't reference or change +the \firstuseflag\ are \glstextlike\ commands and are described +in \sectionref{sec:glstext-like}. See \sectionref{sec:glsunset} for +commands that unset or reset the \firstuseflag\ without referencing +the entries. + +The \glslike\ and \glstextlike\ commands all take a first +optional argument that is a comma-separated list of +\meta{key}=\meta{value} +options, described below. They also have a star-variant, which +inserts \texttt{hyper=false} at the start of the list of options +and a plus-variant, which inserts \texttt{hyper=true} at the start +of the list of options. For example \verb|\gls*{sample}| is the same +as \verb|\gls[hyper=false]{sample}| and \verb|\gls+{sample}| is the +same as \verb|\gls[hyper=true]{sample}|, whereas just +\verb|\gls{sample}| will use the default hyperlink setting which +depends on a number of factors (such as whether the entry is in a +glossary that has been identified in the \pkgopt{nohypertypes} list). +You can override the \gloskey[glslink]{hyper} key in the variant's +optional argument, for example, \verb|\gls*[hyper=true]{sample}| but +this creates redundancy and is best avoided. + +The following keys are available for the optional argument: \begin{description} +\item[{\gloskey[glslink]{hyper}}] This is a boolean key which can +be used to enable/disable the hyperlink to the relevant entry +in the glossary. If this key is omitted, the value is determined by current +settings, as indicated above. For example, when used with a \glslike\ command, if this is the first +use and the \pkgopt[false]{hyperfirst} package option has been used, +then the default value is \texttt{hyper=false}. The hyperlink can be +forced on using \texttt{hyper=true} unless the hyperlinks have been +suppressed using \ics{glsdisablehyper}. You must load the +\sty{hyperref} package before the \sty{glossaries} package to +ensure the hyperlinks work. + \item[{\gloskey[glslink]{format}}] This specifies how to format the associated location number for this entry in the glossary. This value is equivalent to the \gls{makeindex} encap value, and (as @@ -4356,49 +4489,56 @@ will need to add this to the list of location attributes: to use for this location. This overrides the default counter used by this entry. (See also \sectionref{sec:numberlists}.) -\item[{\gloskey[glslink]{hyper}}] This is a boolean key which can -be used to enable/disable the hyperlink to the relevant entry -in the glossary. (Note that setting \texttt{hyper=true} will have no -effect if \ics{hyperlink} has not been defined.) The default -value is \texttt{hyper=true}, unless the entry belongs to a glossary -that either has been listed in the package option -\pkgopt{nohypertypes} or has been identified using -\ics{GlsDeclareNoHyperList} in which case the default is -\texttt{hyper=false}. - \item[{\gloskey[glslink]{local}}] This is a boolean key that only -makes a different when used with commands that change the -entry's \gls{firstuseflag} (such as \ics{gls}). If -\texttt{local=true}, the change to the \gls*{firstuseflag} will be -localised to the current scope. The default is \texttt{local=false}. +makes a difference when used with \glslike\ commands that change the +entry's \gls{firstuseflag}. If \texttt{local=true}, the change to +the \gls*{firstuseflag} will be localised to the current scope. The +default is \texttt{local=false}. \end{description} -There is also a starred version: -\begin{definition}[\DescribeMacro{\glslink*}] -\cs{glslink*}\oarg{options}\marg{label}\marg{text} -\end{definition} -which is equivalent to \cs{glslink}, except it sets -\texttt{hyper=false}. Similarly, all the following commands -described in this section also have a starred version that disables -the hyperlink. + +\section{The \cs{gls}-Like Commands (First Use Flag Queried)} +\label{sec:gls-like} + +This section describes the commands that unset the \firstuseflag\ on +completion, and in most cases they use the current state of the flag +to determine the text to be displayed. As described above, these +commands all have a star-variant (\texttt{hyper=false}) and +a plus-variant (\texttt{hyper=true}) and have an +optional first argument that is a \meta{key}=\meta{value} list. + +These commands use \ics{glsentryfmt} or the equivalent definition provided by +\ics{defglsentryfmt} to determine the automatically generated text +and its format (see \sectionref{sec:glsdisplay}). + +Apart from \ics{glsdisp}, the commands described in this section +also have a \emph{final} optional argument \meta{insert} which may +be used to insert material into the automatically generated text. \begin{important} -Don't use commands like \cs{glslink} or \cs{gls} in the \meta{text} -argument of \cs{glslink}. +Since the commands have a final optional argument, take care if +you actually want to display an open square bracket after the command +when the final optional argument is absent. Insert an empty set of +braces \verb|{}| immediately before the opening square bracket to +prevent it from being interpreted as the final argument. For +example: +\begin{verbatim} +\gls{sample} {}[Editor's comment] +\end{verbatim} + +Don't use any of the \glslike\ or \glstextlike\ commands in the +\meta{insert} argument. \end{important} -The command: \begin{definition}[\DescribeMacro{\gls}] \cs{gls}\oarg{options}\marg{label}\oarg{insert} \end{definition} -is the same as \cs{glslink}, except that the \gls{linktext} -is determined from the values of the \gloskey{text} and -\gloskey{first} keys supplied when the entry was defined using -\ics{newglossaryentry}. If the entry has been marked as having -been used\ifirstuseflag, the value of the \gloskey{text} key will be used, otherwise -the value of the \gloskey{first} key will be used. -On completion, \cs{gls} will mark the entry's \gls{firstuseflag} as -used. +This command typically determines the \gls{linktext} from the values +of the \gloskey{text} or \gloskey{first} keys supplied when the +entry was defined using \ics{newglossaryentry}. However, if the +entry was defined using \ics{newacronym} and \ics{setacronymstyle} was +used, then the \gls*{linktext} will usually be determined from the \gloskey{long} or +\gloskey{short} keys. There are two upper case variants: \begin{definition}[\DescribeMacro{\Gls}] @@ -4411,20 +4551,6 @@ and which make the first letter of the link text or all the link text upper case, respectively. -The final optional argument \meta{insert}, allows you to insert -some additional text into the link text. By default, this will -append \meta{insert} at the end of the link text, but this -can be changed (see \sectionref{sec:glsdisplay}). - -The first optional argument \meta{options} is the same as the optional -argument to \ics{glslink}. As with \ics{glslink}, these commands also -have a starred version that disable the hyperlink. - -\begin{important} -Don't use commands like \cs{glslink} or \cs{gls} in the \meta{insert} -argument of \cs{gls} and its variants. -\end{important} - There are also analogous plural forms: \begin{definition}[\DescribeMacro{\glspl}] \cs{glspl}\oarg{options}\marg{label}\oarg{insert} @@ -4435,10 +4561,11 @@ There are also analogous plural forms: \begin{definition}[\DescribeMacro{\GLSpl}] \cs{GLSpl}\oarg{options}\marg{label}\oarg{insert} \end{definition} -These determine the link text from the \gloskey{plural} and -\gloskey{firstplural} keys supplied when the entry was first -defined. As before, these commands also have -a starred version that disable the hyperlink. +These typically determine the link text from the \gloskey{plural} or +\gloskey{firstplural} keys supplied when the entry was +defined using \ics{newglossaryentry} or, if the entry is an acronym +and \cs{setacronymstyle} was used, from the \gloskey{longplural} or +\gloskey{shortplural} keys. \begin{important} Be careful when you use glossary entries in math mode especially if you @@ -4461,31 +4588,51 @@ $\gls{Falpha}[^2]$ \end{verbatim} \end{important} -Note that \ics{glslink} doesn't use or affect the \firstuseflag, nor -does it use \ics{glsentryfmt} or the equivalent definition provided -by \ics{defglsentryfmt} (see \sectionref{sec:glsdisplay}). Instead, -you can use: \begin{definition}[\DescribeMacro{\glsdisp}] \cs{glsdisp}\oarg{options}\marg{label}\marg{link text} \end{definition} -This behaves in the same way as \ics{gls}, except -that it uses \meta{link text} instead of the value of the -\gloskey{first} or \gloskey{text} key. (Note that this command -always sets \meta{insert} to nothing.) This command affects the -\firstuseflag, and uses \ics{glsentryfmt} or the equivalent -definition provided by \ics{defglsentryfmt}. +This behaves in the same way as the above commands, except +that the \meta{link text} is explicitly set. There's no final +optional argument as any inserted material can be added to the +\meta{link text} argument. + +\begin{important} +Don't use any of the \glslike\ or \glstextlike\ commands in the +\meta{link text} argument of \cs{glsdisp}. +\end{important} + +\section{The \cs{glstext}-Like Commands (First Use Flag Not Queried)} +\label{sec:glstext-like} + +This section describes the commands that don't change or reference +the \firstuseflag. As described above, these commands all have a +star-variant (\texttt{hyper=false}) and a plus-variant +(\texttt{hyper=true}) and have an optional first argument +that is a \meta{key}=\meta{value} list. These commands also don't +use \ics{glsentryfmt} or the equivalent definition provided by +\ics{defglsentryfmt} (see \sectionref{sec:glsdisplay}). + +Apart from \ics{glslink}, the commands described in this section +also have a \emph{final} optional argument \meta{insert} which may +be used to insert material into the automatically generated text. +See the caveat above in \sectionref{sec:gls-like}. + +\begin{definition}[\DescribeMacro{\glslink}] +\cs{glslink}\oarg{options}\marg{label}\marg{link text} +\end{definition} +This command explicitly sets the \gls{linktext} as given in the +final argument. + +\begin{important} +Don't use any of the \glslike\ or \glstextlike\ commands in the +argument of \cs{glslink}. +\end{important} -The command: \begin{definition}[\DescribeMacro{\glstext}] \cs{glstext}\oarg{options}\marg{label}\oarg{insert} \end{definition} -is similar to \ics{gls} except that it always uses the value -of the \gloskey{text} key and does not affect the \firstuseflag. -Unlike \cs{gls}, the inserted text \meta{insert} is always appended -to the link text since \cs{glstext} doesn't use \ics{glsentryfmt} or -the equivalent definition provided by \ics{defglsentryfmt}. (The -same is true for all the following commands described in the rest of this -section.) +This command always uses the value of the \gloskey{text} key as the +\gls{linktext}. There are also analogous commands: \begin{definition}[\DescribeMacro{\Glstext}] @@ -4494,180 +4641,170 @@ There are also analogous commands: \begin{definition}[\DescribeMacro{\GLStext}] \cs{GLStext}\oarg{options}\marg{text}\oarg{insert} \end{definition} -As before, these commands also have a starred version that disable -the hyperlink. +These convert the first character or all the characters to +uppercase, respectively. -The command: \begin{definition}[\DescribeMacro{\glsfirst}] \cs{glsfirst}\oarg{options}\marg{label}\oarg{insert} \end{definition} -is similar to \cs{glstext} except that it always uses the value -of the \gloskey{first} key. Again, \meta{insert} is always appended -to the end of the link text and does not affect the -\firstuseflag. +This command always uses the value of the \gloskey{first} key as the +\gls{linktext}. -There are also analogous commands: +There are also analogous uppercasing commands: \begin{definition}[\DescribeMacro{\Glsfirst}] \cs{Glsfirst}\oarg{options}\marg{text}\oarg{insert} \end{definition} \begin{definition}[\DescribeMacro{\GLSfirst}] \cs{GLSfirst}\oarg{options}\marg{text}\oarg{insert} \end{definition} -As before, these commands also have a starred version that disable -the hyperlink. -The command: \begin{definition}[\DescribeMacro{\glsplural}] \cs{glsplural}\oarg{options}\marg{label}\oarg{insert} \end{definition} -is similar to \ics{glstext} except that it always uses the value -of the \gloskey{plural} key. Again, \meta{insert} is always appended -to the end of the link text and does not mark the entry as having -been used. +This command always uses the value of the \gloskey{plural} key as the +\gls{linktext}. -There are also analogous commands: +There are also analogous uppercasing commands: \begin{definition}[\DescribeMacro{\Glsplural}] \cs{Glsplural}\oarg{options}\marg{text}\oarg{insert} \end{definition} \begin{definition}[\DescribeMacro{\GLSplural}] \cs{GLSplural}\oarg{options}\marg{text}\oarg{insert} \end{definition} -As before, these commands also have a starred version that disable -the hyperlink. -The command: \begin{definition}[\DescribeMacro{\glsfirstplural}] \cs{glsfirstplural}\oarg{options}\marg{label}\oarg{insert} \end{definition} -is similar to \ics{glstext} except that it always uses the value -of the \gloskey{firstplural} key. Again, \meta{insert} is always -appended to the end of the link text and does not mark the entry as -having been used. +This command always uses the value of the \gloskey{firstplural} key as the +\gls{linktext}. -There are also analogous commands: +There are also analogous uppercasing commands: \begin{definition}[\DescribeMacro{\Glsfirstplural}] \cs{Glsfirstplural}\oarg{options}\marg{text}\oarg{insert} \end{definition} \begin{definition}[\DescribeMacro{\GLSfirstplural}] \cs{GLSfirstplural}\oarg{options}\marg{text}\oarg{insert} \end{definition} -As before, these commands also have a starred version that disable -the hyperlink. -The command: \begin{definition}[\DescribeMacro{\glsname}] \cs{glsname}\oarg{options}\marg{label}\oarg{insert} \end{definition} -is similar to \ics{glstext} except that it always uses the value of -the \gloskey{name} key. Again, \meta{insert} is always appended to -the end of the link text and does not mark the entry as having been -used. +This command always uses the value of the \gloskey{name} key as the +\gls{linktext}. -There are also analogous commands: +There are also analogous uppercasing commands: \begin{definition}[\DescribeMacro{\Glsname}] \cs{Glsname}\oarg{options}\marg{text}\oarg{insert} \end{definition} \begin{definition}[\DescribeMacro{\GLSname}] \cs{GLSname}\oarg{options}\marg{text}\oarg{insert} \end{definition} -As before, these commands also have a starred version that disable -the hyperlink. -The command: \begin{definition}[\DescribeMacro{\glssymbol}] \cs{glssymbol}\oarg{options}\marg{label}\oarg{insert} \end{definition} -is similar to \ics{glstext} except that it always uses the value of -the \gloskey{symbol} key. Again, \meta{insert} is always appended to -the end of the link text and does not mark the entry as having been -used. +This command always uses the value of the \gloskey{symbol} key as the +\gls{linktext}. -There are also analogous commands: +There are also analogous uppercasing commands: \begin{definition}[\DescribeMacro{\Glssymbol}] \cs{Glssymbol}\oarg{options}\marg{text}\oarg{insert} \end{definition} \begin{definition}[\DescribeMacro{\GLSsymbol}] \cs{GLSsymbol}\oarg{options}\marg{text}\oarg{insert} \end{definition} -As before, these commands also have a starred version that disable -the hyperlink. -The command: \begin{definition}[\DescribeMacro{\glsdesc}] \cs{glsdesc}\oarg{options}\marg{label}\oarg{insert} \end{definition} -is similar to \ics{glstext} except that it always uses the value of -the \gloskey{description} key. Again, \meta{insert} is always -appended to the end of the link text and does not mark the entry as -having been used. +This command always uses the value of the \gloskey{description} key as the +\gls{linktext}. -There are also analogous commands: +There are also analogous uppercasing commands: \begin{definition}[\DescribeMacro{\Glsdesc}] \cs{Glsdesc}\oarg{options}\marg{text}\oarg{insert} \end{definition} \begin{definition}[\DescribeMacro{\GLSdesc}] \cs{GLSdesc}\oarg{options}\marg{text}\oarg{insert} \end{definition} -As before, these commands also have a starred version that disable -the hyperlink. -The command: \begin{definition}[\DescribeMacro{\glsuseri}] \cs{glsuseri}\oarg{options}\marg{label}\oarg{insert} \end{definition} -is similar to \ics{glstext} except that it always uses the value -of the \gloskey{user1} key. Again, \meta{insert} is always -appended to the end of the link text and does not mark the entry as -having been used. +This command always uses the value of the +\gloskey{user1} key as the \gls{linktext}. -There are also analogous commands: +There are also analogous uppercasing commands: \begin{definition}[\DescribeMacro{\Glsuseri}] \cs{Glsuseri}\oarg{options}\marg{text}\oarg{insert} \end{definition} \begin{definition}[\DescribeMacro{\GLSuseri}] \cs{GLSuseri}\oarg{options}\marg{text}\oarg{insert} \end{definition} -As before, these commands also have a starred version that disable -the hyperlink. Similarly for the other user keys: + \begin{definition}[\DescribeMacro{\glsuserii}] \cs{glsuserii}\oarg{options}\marg{text}\oarg{insert} \end{definition} +This command always uses the value of the +\gloskey{user2} key as the \gls{linktext}. + +There are also analogous uppercasing commands: \begin{definition}[\DescribeMacro{\Glsuserii}] \cs{Glsuserii}\oarg{options}\marg{text}\oarg{insert} \end{definition} \begin{definition}[\DescribeMacro{\GLSuserii}] \cs{GLSuserii}\oarg{options}\marg{text}\oarg{insert} \end{definition} + \begin{definition}[\DescribeMacro{\glsuseriii}] \cs{glsuseriii}\oarg{options}\marg{text}\oarg{insert} \end{definition} +This command always uses the value of the +\gloskey{user3} key as the \gls{linktext}. + +There are also analogous uppercasing commands: \begin{definition}[\DescribeMacro{\Glsuseriii}] \cs{Glsuseriii}\oarg{options}\marg{text}\oarg{insert} \end{definition} \begin{definition}[\DescribeMacro{\GLSuseriii}] \cs{GLSuseriii}\oarg{options}\marg{text}\oarg{insert} \end{definition} + \begin{definition}[\DescribeMacro{\glsuseriv}] \cs{glsuseriv}\oarg{options}\marg{text}\oarg{insert} \end{definition} +This command always uses the value of the +\gloskey{user4} key as the \gls{linktext}. + +There are also analogous uppercasing commands: \begin{definition}[\DescribeMacro{\Glsuseriv}] \cs{Glsuseriv}\oarg{options}\marg{text}\oarg{insert} \end{definition} \begin{definition}[\DescribeMacro{\GLSuseriv}] \cs{GLSuseriv}\oarg{options}\marg{text}\oarg{insert} \end{definition} + \begin{definition}[\DescribeMacro{\glsuserv}] \cs{glsuserv}\oarg{options}\marg{text}\oarg{insert} \end{definition} +This command always uses the value of the +\gloskey{user5} key as the \gls{linktext}. + +There are also analogous uppercasing commands: \begin{definition}[\DescribeMacro{\Glsuserv}] \cs{Glsuserv}\oarg{options}\marg{text}\oarg{insert} \end{definition} \begin{definition}[\DescribeMacro{\GLSuserv}] \cs{GLSuserv}\oarg{options}\marg{text}\oarg{insert} \end{definition} + \begin{definition}[\DescribeMacro{\glsuservi}] \cs{glsuservi}\oarg{options}\marg{text}\oarg{insert} \end{definition} +This command always uses the value of the +\gloskey{user6} key as the \gls{linktext}. + +There are also analogous uppercasing commands: \begin{definition}[\DescribeMacro{\Glsuservi}] \cs{Glsuservi}\oarg{options}\marg{text}\oarg{insert} \end{definition} @@ -4678,9 +4815,8 @@ the hyperlink. Similarly for the other user keys: \section{Changing the format of the link text} \label{sec:glsdisplay} -The default format of the \gls{linktext} for \ics{gls}, \ics{glspl} -and their upper case variants and also for \ics{glsdisp} is governed -by\footnote{\ics{glsdisplayfirst} and \ics{glsdisplay} are now +The default format of the \gls{linktext} for the \glslike\ commands +is governed by\footnote{\ics{glsdisplayfirst} and \ics{glsdisplay} are now deprecated. Backwards compatibility should be preserved but you may need to use the \pkgopt{compatible-3.07} option}: \begin{definition}[\DescribeMacro{\glsentryfmt}] @@ -4700,7 +4836,7 @@ entry format definition. Note that \cs{glsentryfmt} is the default display format for entries. Once the display format has been changed for an individual glossary using \ics{defglsentryfmt}, redefining \cs{glsentryfmt} -won't have an effect on that glossary, you must instead us +won't have an effect on that glossary, you must instead use \cs{defglsentryfmt} again. Note that glossaries that have been identified as lists of acronyms (via the package option \pkgopt{acronymlists} or the command \ics{DeclareAcronymList}, @@ -4715,7 +4851,13 @@ commands: \begin{definition}[\DescribeMacro{\glslabel}] \cs{glslabel} \end{definition} -This is the label of the entry being referenced. +This is the label of the entry being referenced. As from version +4.08, you can also access the glossary entry type using: +\begin{definition}[\DescribeMacro{\glstype}] +\cs{glstype} +\end{definition} +This is defined using \ics{edef} so the replacement text is the +actual glossary type rather than \verb|\glsentrytype{\glslabel}|. \begin{definition}[\DescribeMacro{\glscustomtext}] \cs{glscustomtext} @@ -4744,17 +4886,32 @@ If \cs{gls}, \cs{glspl} or \cs{glsdisp} were used, this does \meta{no case}. If \cs{Gls} or \cs{Glspl} were used, this does \meta{first uc}. If \cs{GLS} or \cs{GLSpl} were used, this does \meta{all caps}. -\begin{definition}[\DescribeMacro\glsifhyper] -\cs{glsifhyper}\marg{hyper true}\marg{hyper false} -\end{definition} -This will do \meta{hyper true} if the unstarred version -(\texttt{hyper=true}) was used and will be -\meta{hyper false} if the starred version -(\texttt{hyper=false}) was used. Note that this -isn't the same as testing the internal conditional that the -\gloskey[glslink]{hyper} key sets, as this can subsequently change -depending on package options such as \pkgopt{hyperfirst} and -\pkgopt{nohypertypes}. +\begin{definition}[\DescribeMacro\glsifhyperon] +\cs{glsifhyperon}\marg{hyper true}\marg{hyper false} +\end{definition} +This will do \meta{hyper true} if the hyperlinks are on for the +current reference, otherwise it will do \meta{hyper false}. The +hyperlink may be off even if it wasn't explicitly switched off with +the \gloskey[glslink]{hyper} key or the use of a starred command. +It may be off because the \sty{hyperref} package hasn't been loaded +or because \ics{glsdisablehyper} has been used or because the entry +is in a glossary type that's had the hyperlinks switched off (using +\pkgopt{nohypertypes}) or because it's the \firstuse\ and the +hyperlinks have been suppressed on first use. + +Note that \ics{glsifhyper} is now deprecated. +If you want to know if the command used to reference +this entry was used with the star or plus variant, you can use: +\begin{definition}[\DescribeMacro\glslinkvar] +\cs{glslinkvar}\marg{unmodified}\marg{star}\marg{plus} +\end{definition} +This will do \meta{unmodified} if the unmodified version was used, +or will do \meta{star} if the starred version was used, or +will do \meta{plus} if the plus version was used. +Note that this doesn't take into account if the +\gloskey[glslink]{hyper} key was used to override the default +setting, so this command shouldn't be used to guess whether or not +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}). @@ -4812,8 +4969,7 @@ only need to redefine \ics{genacrfullformat} and on changing the style of acronyms. \begin{important} -Note that \cs{glsentryfmt} is not used by \ics{glslink} or any of -the other commands, such as \ics{glstext}. +Note that \cs{glsentryfmt} is not used by the \glstextlike\ commands. \end{important} \begin{example}{Custom Entry Display in Text}{ex:customfmt} @@ -4896,10 +5052,13 @@ ignore it. \label{sec:disablehyperlinks} If you load the \sty{hyperref} or \sty{html} packages prior to -loading the \styfmt{glossaries} package, commands such as \ics{glslink} -and \ics{gls}, described above, will automatically have hyperlinks +loading the \styfmt{glossaries} package, the \glslike\ and +\glstextlike\ commands will automatically have hyperlinks to the relevant glossary entry, unless the \gloskey[glslink]{hyper} -option has been set to \texttt{false}. You can disable or enable links using: +option has been switched off (either explicitly or through +implicit means, such as via the \pkgopt{nohypertypes} package option). + +You can disable or enable links using: \begin{definition}[\DescribeMacro{\glsdisablehyper}] \cs{glsdisablehyper} \end{definition} @@ -4914,8 +5073,7 @@ defined (for example, by the \sty{hyperref} package). You can disable just the \gls{firstuse} links using the package option \pkgopt[false]{hyperfirst}. Note that this option only -affects commands that recognise the \firstuseflag, for example -\ics{gls}, \ics{glspl} and \ics{glsdisp} but not \ics{glslink}. +affects the \glslike\ commands that recognise the \firstuseflag. \begin{example}{First Use With Hyperlinked Footnote Description}{ex:hyperdesc} Suppose I want the \gls*{firstuse} to have a hyperlink to the @@ -4972,32 +5130,27 @@ off all hyperlinks via \ics{glsdisablehyper} and put the hyperlinks \begin{example}{Only Hyperlink in Text Mode Not Math Mode}{ex:nomathhyper} This is a bit of a contrived example, but suppose, for some reason, -I only want commands like \ics{gls} and \ics{glsdisp} to have +I only want the \glslike\ commands to have hyperlinks when used in text mode, but not in math mode. I~can do -this by disabling all hyperlinks and redefining \ics{glsentryfmt}: +this by adding the glossary to the list of nohypertypes and redefining +\ics{glsentryfmt}: \begin{verbatim} -\glsdisablehyper +\GlsDeclareNoHyperList{main} + \renewcommand*{\glsentryfmt}{% \ifmmode \glsgenentryfmt \else - % Temporarily enable hyperlinks: - \glsenablehyper - \glshyperlink[\glsgenentryfmt]{\glslabel}% - % Disable hyperlinks again - \glsdisablehyper + \glsifhyperon + {\glsgenentryfmt}% hyperlink already on + {\glshyperlink[\glsgenentryfmt]{\glslabel}}% \fi } \end{verbatim} -To ensure the target exists, the hyperlinks must be enabled again -when the glossary is displayed: -\begin{verbatim} -\renewcommand{\glossarypreamble}{\glsenablehyper} -\renewcommand{\glossarypostamble}{\glsdisablehyper} -\end{verbatim} -(The redefinition of \ics{glossarypostamble} is only necessary if -the glossary is displayed at the start of the document instead of at -the end.) +Note that this doesn't affect the \glstextlike\ commands, which will +have the hyperlinks off unless they're forced on using the plus +variant. + See the sample file \samplefile{-nomathhyper} for a complete document. \end{example} @@ -5005,15 +5158,15 @@ document. \chapter{Adding an Entry to the Glossary Without Generating Text} \label{sec:glsadd} -It is possible to add a line in the glossary file without +It is possible to add a line to the glossary file without generating any text at that point in the document using: \begin{definition}[\DescribeMacro{\glsadd}] \cs{glsadd}\oarg{options}\marg{label} \end{definition} -This is similar to \ics{glslink}, only it doesn't produce +This is similar to the \glstextlike\ commands, only it doesn't produce any text (so therefore, there is no \gloskey[glslink]{hyper} key available in \meta{options} but all the other options that can -be used with \ics{glslink} can be passed to \cs{glsadd}). +be used with \glstextlike\ commands can be passed to \cs{glsadd}). For example, to add a page range to the glossary number list for the entry whose label is given by \texttt{set}: \begin{verbatim} @@ -5057,6 +5210,11 @@ ignore this location in the number list. The optional argument \meta{list} is a comma-separated list of glossary types. If omitted, it defaults to the list of all defined glossaries. +If you want to use \cs{glsaddallunused}, it's best to place the +command at the end of the document to ensure that all the commands +you intend to use have already been used. Otherwise you could end up +with a spurious comma or dash in the location list. + \begin{example}{Dual Entries}{ex:dual} The example file \samplefile{-dual} makes use of \cs{glsadd} to allow for an entry that should appear both in the main glossary and @@ -5427,8 +5585,8 @@ existence of \meta{label}. \begin{definition}[\DescribeMacro\glsletentryfield] \cs{glsletentryfield}\marg{cs}\marg{label}\marg{field} \end{definition} -This command doesn't display anything it merely fetches the -value associated with field (where the available field names +This command doesn't display anything. It merely fetches the +value associated with the given field (where the available field names are listed in \tableref{tab:fieldmap}) and stores the result in the control sequence \meta{cs}. For example, to store the description for the entry whose label is \qt{apple} in the @@ -5442,7 +5600,7 @@ control sequence \verb|\tmp|: \end{definition} This is like \cs{glsentrysymbol}\marg{label} but also checks for the existence of \meta{label}. This command is -not expandable. It's used in the predefined glossary styles to +not expandable. It's used in some of the predefined glossary styles to display the symbol. \begin{definition}[\DescribeMacro{\Glossentrysymbol}] \cs{Glossentrysymbol}\marg{label} @@ -5516,7 +5674,10 @@ glossary file}. The link text is given by \ics{glsentrytext}\marg{label} by default\footnote{versions before 3.0 used \ics{glsentryname} as the default, but this could cause problems when \gloskey{name} had been \glsd{sanitize}.}, but can be -overridden using the optional argument. +overridden using the optional argument. Note that the hyperlink will +be suppressed if you have used \ics{glsdisablehyper} or if you +haven't loaded the \sty{hyperref} package. + \begin{important} If you use \cs{glshyperlink}, you need to ensure that the relevant entry has been added to the glossary using any of the commands @@ -5569,13 +5730,13 @@ glossary} in the documented code (\texttt{glossaries-code.pdf}). \label{sec:printglossary} \begin{description} -\item[\opt1:]\null +\itempar{\opt1:} \begin{definition}[\DescribeMacro{\printnoidxglossaries}] \cs{printnoidxglossaries} \end{definition} (Must be used with \ics{makenoidxglossaries} in the preamble.) -\item[\optsand23:]\null +\itempar{\optsand23:} \begin{definition}[\DescribeMacro{\printglossaries}] \cs{printglossaries} \end{definition} @@ -5594,13 +5755,13 @@ but you may need further runs to make the \glspl{numberlist} up-to-date. An individual glossary can be displayed using: \begin{description} -\item[\opt1:]\null +\itempar{\opt1:} \begin{definition}[\DescribeMacro{\printnoidxglossary}] \cs{printnoidxglossary}\oarg{options} \end{definition} (Must be used with \ics{makenoidxglossaries} in the preamble.) -\item[\optsand23:]\null +\itempar{\optsand23:} \begin{definition}[\DescribeMacro{\printglossary}] \cs{printglossary}\oarg{options} \end{definition} @@ -5615,6 +5776,10 @@ glossary is assumed. For example, to print the list of acronyms: \begin{verbatim} \printglossary[type=\acronymtype] \end{verbatim} +Note that you can't display an ignored glossary, so don't try +setting \gloskey[printglossary]{type} to the name of a glossary that +was defined using \ics{newignoredglossary}. (See +\sectionref{sec:newglossary}.) \item[{\gloskey[printglossary]{title}}] This is the glossary's title (overriding the title specified when the glossary was @@ -5639,22 +5804,44 @@ option, described in \sectionref{sec:pkgopts-sec}. \item[{\gloskey[printglossary]{nonumberlist}}] This is a boolean key. If true (\verb|nonumberlist=true|) the numberlist is suppressed for this glossary. If false \linebreak(\verb|nonumberlist=false|) the -numberlist is displayed for this glossary. If no value is supplied, -true is assumed. +numberlist is displayed for this glossary. + +\item[{\gloskey[printglossary]{nogroupskip}}] This is a boolean +key. If true the vertical gap between groups +is suppressed for this glossary. + +\item[{\gloskey[printglossary]{nopostdot}}] This is a boolean +key. If true the full stop after the description +is suppressed for this glossary. + +\item[{\gloskey[printglossary]{entrycounter}}] This is a boolean +key. Behaves similar to the package option of the same name. +The corresponding package option must be used to make \ics{glsrefentry} +work correctly. -\item[{\gloskey{printnoidxglossary}{sort}}] This key is only +\item[{\gloskey[printglossary]{subentrycounter}}] This is a boolean +key. Behaves similar to the package option of the same name. If you +want to set both \gloskey{entrycounter} and +\gloskey{subentrycounter}, make sure you specify +\gloskey{entrycounter} first. The corresponding package option must +be used to make \ics{glsrefentry} work correctly. + +\item[{\gloskey[printnoidxglossary]{sort}}] This key is only available for \opt1. Possible values are: \texttt{word} (word order), \texttt{letter} (letter order), \texttt{standard} (word or letter ordering taken from the \pkgopt{order} package option), \texttt{use} (order of use), \texttt{def} (order of definition) \texttt{nocase} (case-insensitive) or \texttt{case} (case-sensitive). -The word and letter order sort methods use \sty{datatool}'s +{\raggedright +The word and letter order sort methods use +\sty{datatool}'s \ics{dtlwordindexcompare} and \ics{dtlletterindexcompare} handlers. The case-insensitive sort method uses \sty{datatool}'s \ics{dtlicompare} handler. The case-sensitive sort method uses \sty{datatool}'s \ics{dtlcompare} handler. See the \sty{datatool} documentation for further details. +\par} If you don't get an error with \texttt{sort=use} and \texttt{sort=def} but you do get an error with one of the other sort @@ -6129,8 +6316,8 @@ A new glossary can be defined using: \begin{definition}[\DescribeMacro{\newglossary}] \cs{newglossary}\oarg{log-ext}\marg{name}\marg{in-ext}\marg{out-ext}\marg{title}\linebreak\oarg{counter} \end{definition} -where \meta{name} is the label to assign to this glossary. The -arguments \meta{in-ext} and \meta{out-ext} specify the extensions to +where \meta{name} is the label to assign to this glossary. +The arguments \meta{in-ext} and \meta{out-ext} specify the extensions to give to the input and output files for that glossary, \meta{title} is the default title for this new glossary and the final optional argument \meta{counter} specifies which counter to use for the @@ -6148,15 +6335,45 @@ characters. It's generally best to stick with just characters that have category code~11 (typically the non-extended \glspl{latinchar}). \end{important} -You can also use: +There is also a starred version (new to v4.08): +\begin{definition}[\DescribeMacro{\newglossary*}] +\cs{newglossary*}\marg{name}\marg{title}\oarg{counter} +\end{definition} +which is equivalent to +\begin{alltt} +\cs{newglossary}[\meta{name}-glg]\marg{name}\{\meta{name}-gls\}\{\meta{name}-glo\}\ifpdf\linebreak\fi\marg{title}\oarg{counter} +\end{alltt} +or you can also use: \begin{definition}[\DescribeMacro{\altnewglossary}] \cs{altnewglossary}\marg{name}\marg{tag}\marg{title}\oarg{counter} \end{definition} -This is equivalent to +which is equivalent to \begin{alltt} \cs{newglossary}[\meta{tag}-glg]\marg{name}\{\meta{tag}-gls\}\{\meta{tag}-glo\}\marg{title}\oarg{counter} \end{alltt} +It may be that you have some terms or acronyms that are so common +that they don't need to be listed. In this case, you can define +a~special type of glossary that doesn't create any associated files. +This is referred to as an \qt{ignored glossary} and it's ignored by +commands that iterate over all the glossaries, such as +\ics{printglossaries}. To define an ignored glossary, use +\begin{definition}[\DescribeMacro\newignoredglossary] +\cs{newignoredglossary}\marg{name} +\end{definition} +where \meta{name} is the name of the glossary (as above). This +glossary type will automatically be added to the +\pkgopt{nohypertypes} list, since there are no hypertargets for +the entries in an ignored glossary. +(The sample file \samplefile{-entryfmt} defines an ignored glossary.) + +You can test if a glossary is an ignored one using: +\begin{definition}[\DescribeMacro\ifignoredglossary] +\cs{ifignoredglossary}\marg{name}\marg{true}\marg{false} +\end{definition} +This does \meta{true} if \meta{name} was defined as an ignored +glossary, otherwise it does \meta{false}. + Note that the main (default) glossary is automatically created as: \begin{verbatim} \newglossary{main}{gls}{glo}{\glossaryname} @@ -6287,27 +6504,28 @@ Now \verb|\gls{idn}| will produce \qt{identification number uses. \end{example} -There are commands similar to \ics{glstext} (described in -\sectionref{sec:glslink}) that allow you to access just the short -form, just the long form or the full form, without affecting the -\gls{firstuseflag}. (Note that the full form isn't necessarily the same -as the text produced on \firstuse.) - \begin{important} -Although these commands are -similar to commands such as \ics{glstext}, they behave more like -\ics{glsdisp} (except for the \gls*{firstuse} behaviour) in that -the display is governed by \ics{defentryfmt} with -\ics{glscustomtext} set as appropriate. +The commands described below are similar to the \glstextlike\ +commands in that they don't modify the \firstuseflag. +However, their display is governed by \ics{defentryfmt} with +\ics{glscustomtext} set as appropriate. All caveats that apply to +the \glstextlike\ commands also apply to the following commands. \end{important} +The optional arguments are the same as those for the \glstextlike\ +commands, and there are similar star and plus variants that switch +off or on the hyperlinks. As with the \glstextlike\ commands, the +\gls{linktext} is placed in the argument of \ics{glstextformat}. + \begin{definition}[\DescribeMacro{\acrshort}] \cs{acrshort}\oarg{options}\marg{label}\oarg{insert} \end{definition} -This displays the short form (within the argument of \ics{acronymfont}) for the entry given by \meta{label}. -The optional arguments are the same as those for \ics{glstext}. -There is also a starred version to suppress the hyperlink. There are -also analogous upper case variants: +This sets the \gls{linktext} to the short form (within the argument +of \ics{acronymfont}) for the entry given by \meta{label}. The short +form is as supplied by the \gloskey{short} key, which +\ics{newacronym} implicitly sets. + +There are also analogous upper case variants: \begin{definition}[\DescribeMacro{\Acrshort}] \cs{Acrshort}\oarg{options}\marg{label}\oarg{insert} \end{definition} @@ -6324,15 +6542,17 @@ There are also plural versions: \begin{definition}[\DescribeMacro\ACRshortpl] \cs{ACRshortpl}\oarg{options}\marg{label}\oarg{insert} \end{definition} +The short plural form is as supplied +by the \gloskey{shortplural} key, which \ics{newacronym} implicitly sets. -Similarly for the long form: \begin{definition}[\DescribeMacro{\acrlong}] \cs{acrlong}\oarg{options}\marg{label}\oarg{insert} \end{definition} -This displays the long form for the entry given by \meta{label}. -The optional arguments are the same as before. There is also a starred -version to suppress the hyperlink. There are also analogous upper case -variants: +This sets the \gls{linktext} to the long form for the entry given by +\meta{label}. The long form is as supplied +by the \gloskey{long} key, which \ics{newacronym} implicitly sets. + +There are also analogous upper case variants: \begin{definition}[\DescribeMacro{\Acrlong}] \cs{Acrlong}\oarg{options}\marg{label}\oarg{insert} \end{definition} @@ -6349,16 +6569,37 @@ Again there are also plural versions: \begin{definition}[\DescribeMacro{\ACRlongpl}] \cs{ACRlongpl}\oarg{options}\marg{label}\oarg{insert} \end{definition} +The long plural form is as supplied by the \gloskey{longplural} key, +which \ics{newacronym} implicitly sets. + +The commands below display the full form of the acronym, but note +that this isn't necessarily the same as the form used on \firstuse. +These full-form commands are shortcuts that use the above commands, +rather than creating the \gls{linktext} from the complete full form. +These full-form commands have star and plus variants and optional +arguments that are passed to the above commands. -And for the full form: \begin{definition}[\DescribeMacro{\acrfull}] \cs{acrfull}\oarg{options}\marg{label}\oarg{insert} \end{definition} -This defaults to \meta{long} (\ics{acronymfont}\marg{short}). -The format (including hyperlinks) can be modified by redefining: +This is a shortcut for \begin{definition}[\DescribeMacro{\acrfullfmt}] \cs{acrfullfmt}\marg{options}\marg{label}\marg{insert} \end{definition} +which by default does +\begin{alltt} +\cs{acrfullformat} + \{\cs{acrlong}\oarg{options}\marg{label}\marg{insert}\} + \{\cs{acrshort}\oarg{options}\marg{label}\} +\end{alltt} +where +\begin{definition}[\DescribeMacro\acrfullformat] +\cs{acrfullformat}\marg{long}\marg{short} +\end{definition} +by default does \meta{long} (\meta{short}). +(For further details of these format commands see +\ifpdf section~\ref*{sec:code:acronym} in \fi the documented code, +\texttt{glossaries-code.pdf}.) There are also analogous upper case variants: \begin{definition}[\DescribeMacro{\Acrfull}] @@ -6367,15 +6608,7 @@ There are also analogous upper case variants: \begin{definition}[\DescribeMacro{\ACRfull}] \cs{ACRfull}\oarg{options}\marg{label}\oarg{insert} \end{definition} -The formats (including hyperlinks) can be modified by redefining: -\begin{definition}[\DescribeMacro{\Acrfullfmt}] -\cs{Acrfullfmt}\marg{options}\marg{label}\marg{insert} -\end{definition} -\begin{definition}[\DescribeMacro{\ACRfullfmt}] -\cs{ACRfullfmt}\marg{options}\marg{label}\marg{insert} -\end{definition} - -As before there are also plural versions: +and plural versions: \begin{definition}[\DescribeMacro\acrfullpl] \cs{acrfullpl}\oarg{options}\marg{label}\oarg{insert} \end{definition} @@ -6385,16 +6618,6 @@ As before there are also plural versions: \begin{definition}[\DescribeMacro\ACRfullpl] \cs{ACRfullpl}\oarg{options}\marg{label}\oarg{insert} \end{definition} -The formats (including hyperlinks) can be modified by redefining: -\begin{definition}[\DescribeMacro{\acrfullplfmt}] -\cs{acrfullplfmt}\marg{options}\marg{label}\marg{insert} -\end{definition} -\begin{definition}[\DescribeMacro{\Acrfullplfmt}] -\cs{Acrfullplfmt}\marg{options}\marg{label}\marg{insert} -\end{definition} -\begin{definition}[\DescribeMacro{\ACRfullplfmt}] -\cs{ACRfullplfmt}\marg{options}\marg{label}\marg{insert} -\end{definition} If you find the above commands too cumbersome to write, you can use the \pkgopt{shortcuts} package option to activate the shorter @@ -6470,8 +6693,7 @@ Plural forms: \cs{Glsentryshortpl}\marg{label} \end{definition} -And the full form, \meta{long} (\meta{short}), can be obtained -using: +And the full form can be obtained using: \begin{definition}[\DescribeMacro{\glsentryfull}] \cs{glsentryfull}\marg{label} \end{definition} @@ -6484,13 +6706,14 @@ using: \begin{definition}[\DescribeMacro{\Glsentryfullpl}] \cs{Glsentryfullpl}\marg{label} \end{definition} -(These may be redefined by the acronym style.) +These again use \ics{acrfullformat} by default, but +the format may be redefined by the acronym style. \section{Changing the Acronym Style} \label{sec:setacronymstyle} It may be that the default style doesn't suit your requirements in -which case you can switch to another styles via +which case you can switch to another styles using \begin{definition}[\DescribeMacro{\setacronymstyle}] \cs{setacronymstyle}\marg{style name} \end{definition} @@ -6548,10 +6771,11 @@ If you want the short form displayed differently on first use, you can redefine \ics{firstacronymfont} independently of the acronym style. -The predefined styles that contain \texttt{sc} in their name -(for example \acrstyle{long-sc-short}) redefine \cs{acronymfont} to -use \ics{textsc} (so the short form needs to be specified in lower -case). +The predefined styles that contain \texttt{sc} in their name (for +example \acrstyle{long-sc-short}) redefine \cs{acronymfont} to use +\ics{textsc}, which means that the short form needs to be specified +in lower case. \ifpdf Remember that \verb|\textsc{abc}| produces +\textsc{abc} but \verb|\textsc{ABC}| produces \textsc{ABC}.\fi \hypertarget{boldsc}{}% \begin{important}% @@ -6648,8 +6872,8 @@ same as those for \acrstyle{long-short-desc} etc. \item \acrstyle{dua}, \acrstyle{dua-desc}: -These styles always display (via \ics{gls}) the long form regardless -of whether the entry has been used or not. However, \ics{acrfull} +With these styles, the \glslike\ commands always display the long form +regardless of whether the entry has been used or not. However, \ics{acrfull} and \ics{glsentryfull} will display \meta{long} (\cs{acronymfont}\marg{short}). In the case of \acrstyle{dua}, the \gloskey{name} and \gloskey{sort} keys are set to the short form and the description is set to the long form. In the @@ -6660,13 +6884,12 @@ optional argument of \ics{newacronym}. \item \acrstyle{footnote}, \acrstyle{footnote-sc}, \acrstyle{footnote-sm}: -These three styles set the first use display to: +With these three styles, on first use the \glslike\ commands display: \begin{definition} \cs{firstacronymfont}\marg{short}\ics{footnote}\marg{long} \end{definition} -However, \ics{acrfull} and \ics{glsentryfull} are set to \cs{acronymfont}\marg{short} -(\meta{long}). (And similarly for plural and upper case forms.) -On subsequent use the display is: +However, \ics{acrfull} and \ics{glsentryfull} are set to +\cs{acronymfont}\marg{short} (\meta{long}). On subsequent use the display is: \begin{definition} \cs{acronymfont}\marg{short} \end{definition} @@ -6676,7 +6899,8 @@ form. \begin{important} In order to avoid nested hyperlinks on \firstuse\ the footnote -styles automatically implement \pkgopt[false]{hyperfirst}. +styles automatically implement \pkgopt[false]{hyperfirst} for the +acronym lists. \end{important} \item \acrstyle{footnote-desc}, \acrstyle{footnote-sc-desc}, @@ -7139,12 +7363,12 @@ example. The list of acronyms is just like any other type of glossary and can be displayed on its own using: \begin{description} -\item[\opt1:]\null +\itempar{\opt1:} \begin{alltt} \ics{printnoidxglossary}[type=\ics{acronymtype}] \end{alltt} -\item[\optsand23:]\null +\itempar{\optsand23:} \begin{alltt} \ics{printglossary}[type=\ics{acronymtype}] \end{alltt} @@ -7259,7 +7483,7 @@ optional argument from being recognised. \chapter{Unsetting and Resetting Entry Flags} \label{sec:glsunset} -When using \ics{gls}, \ics{glspl} and their upper case variants it is +When using the \glslike\ commands it is possible that you may want to use the value given by the \gloskey{first} key, even though you have already \glslink{firstuse}{used} the glossary entry. Conversely, you may want to use the value given by the @@ -7293,7 +7517,8 @@ glossaries using: \cs{glslocalunsetall}\oarg{glossary list} \end{definition} where \meta{glossary list} is a comma-separated list of -glossary labels. If omitted, all defined glossaries are assumed. +glossary labels. If omitted, all defined glossaries are assumed +(except for the ignored ones). For example, to reset all entries in the main glossary and the list of acronyms: \begin{verbatim} @@ -7309,7 +7534,7 @@ entry has been used, \meta{true part} will be done, otherwise \meta{false part} will be done. \begin{important} -Be careful when using commands such as \ics{gls} within an +Be careful when using \glslike\ commands within an environment or command argument that gets processed multiple times as it can cause unwanted side-effects when the first use displayed text is different from subsequent use. @@ -7346,8 +7571,33 @@ On the first overlay, \verb|\gls{svm}| produces \qt{support vector machine (SVM)} and then unsets the \firstuseflag. When the second overlay is processed, \verb|\gls{svm}| now produces \qt{SVM}, which is unlikely to be the desired effect. I~don't know anyway around -this and the only suggestion I~can give is to explicitly reset each -acronym on first use: +this and I can only offer two suggestions. + +Firstly, unset all acronyms at the start of the document and +explicitly use \ics{acrfull} when you want the full version to be +displayed: +\begin{verbatim} +\documentclass{beamer} + +\usepackage{glossaries} + +\newacronym{svm}{SVM}{support vector machine} + +\glsunsetall + +\begin{document} +\begin{frame} + \frametitle{Frame 1} + + \begin{itemize} + \item<+-> \acrfull{svm} + \item<+-> Stuff. + \end{itemize} +\end{frame} +\end{document} +\end{verbatim} + +Secondly, explicitly reset each acronym on first use: \begin{verbatim} \begin{frame} \frametitle{Frame 1} @@ -7358,8 +7608,12 @@ acronym on first use: \end{itemize} \end{frame} \end{verbatim} -This is non-optimal, but the \cls{beamer} class is too complex for -me to suggest an alternative solution. +These are non-optimal, but the \cls{beamer} class is too complex for +me to provide a programmatic solution. Other potentially problematic +environments are some \env{tabular}-like environments (but not +\env{tabular} itself) that process the contents in order to work out +the column widths and then reprocess the contents to do the actual +typesetting. The \sty{amsmath} environments, such as \env{align}, also process their contents multiple times, but the \styfmt{glossaries} package now @@ -7391,6 +7645,10 @@ Some of the predefined glossary styles may also be set using the \pkgopt{style} package option, it depends if the package in which they are defined is automatically loaded by the \styfmt{glossaries} package. +You can use the lorum ipsum dummy entries provided in the +\texttt{example-glossaries-*.tex} files (described in +\sectionref{sec:lipsum}) to test the different styles. + \section{Predefined Styles} \label{sec:predefinedstyles} @@ -7957,7 +8215,15 @@ glossaries but can also be used with glossaries that don't have sub-entries. These styles will display the entry's symbol if it exists. Note that these styles will automatically be available unless you use the \pkgopt{notree} or \pkgopt{nostyles} package -options. +options. These styles all format the entry name using: +\begin{definition}[\DescribeMacro\glstreenamefmt] +\cs{glstreenamefmt}\marg{name} +\end{definition} +This defaults to \cs{textbf}\marg{name}, but note that \meta{name} +includes \ics{glsnamefont} so the bold setting in \cs{glstreenamefont} +may be counteracted by another font change in \cs{glsnamefont} (or +in \cs{acronymfont}). The tree-like styles that also display the +header use \cs{glstreenamefmt} to format the heading. \begin{description} \item[index] The \glostyle{index} style is similar to the way @@ -8487,7 +8753,7 @@ can be found in the documented code (glossaries-code.pdf). \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 -doesn't have an unwanted spaces in it as they don't get stripped. +doesn't have any unwanted spaces in it as they don't get stripped. \end{important} \begin{definition}[\DescribeMacro{\forallglossaries}] @@ -8498,7 +8764,17 @@ of glossary labels (as supplied when the glossary was defined). At each iteration \meta{cs} (which must be a control sequence) is set to the glossary label for the current iteration and \meta{body} is performed. If \meta{glossary list} is omitted, the default is to -iterate over all glossaries. +iterate over all glossaries (except the ignored ones). + +\begin{definition}[\DescribeMacro{\forallacronyms}] +\cs{forallacronyms}\marg{cs}\marg{body} +\end{definition} +This is like \cs{forallglossaries} but only iterates over the +lists of acronyms (that have previously been declared using +\ics{DeclareAcronymList} or the \pkgopt{acronymlists} package +option). This command doesn't have an optional argument. If you want +to explicitly say which lists to iterate over, just use the optional +argument of \cs{forallglossaries}. \begin{definition}[\DescribeMacro{\forglsentries}] \cs{forglsentries}\oarg{glossary label}\marg{cs}\marg{body} @@ -8515,9 +8791,10 @@ omitted, \ics{glsdefaulttype} (usually the main glossary) is used. This is like \cs{forglsentries} but for each glossary in \meta{glossary list} (a comma-separated list of glossary labels). If \meta{glossary list} is omitted, the default is the list of all -defined glossaries. At each iteration \meta{cs} is set to the entry -label and \meta{body} is performed. (The current glossary label can -be obtained using \cs{glsentrytype}\marg{cs} within \meta{body}.) +defined glossaries (except the ignored ones). At each iteration +\meta{cs} is set to the entry label and \meta{body} is performed. +(The current glossary label can be obtained using +\cs{glsentrytype}\marg{cs} within \meta{body}.) \begin{definition}[\DescribeMacro{\ifglossaryexists}] \cs{ifglossaryexists}{\meta{label}}{\meta{true part}}{\meta{false @@ -8553,7 +8830,7 @@ Does the reverse of \cs{glsdoifexists}. (This command uses \cs{ifglsentryexists}.) \begin{definition}[\DescribeMacro{\glsdoifexistsorwarn}] -\cs{glsdoifexistsorwanr}\marg{label}\marg{code} +\cs{glsdoifexistsorwarn}\marg{label}\marg{code} \end{definition} As \cs{glsdoifexists} but issues a warning rather than an error if the entry doesn't exist. @@ -8594,7 +8871,7 @@ This checks if the glossary entry given by \meta{label} has had the \gloskey{long} field set. If it has, \meta{true part} is performed, otherwise \meta{false part}. This should be true for any entry that has been defined via \ics{newacronym}. -There is no check for the existance of \meta{label}. +There is no check for the existence of \meta{label}. \begin{definition}[\DescribeMacro{\ifglshasshort}] \cs{ifglshasshort}\marg{label}\marg{true part}\marg{false part} @@ -8603,7 +8880,7 @@ This checks if the glossary entry given by \meta{label} has had the \gloskey{short} field set. If it has, \meta{true part} is performed, otherwise \meta{false part}. This should be true for any entry that has been defined via \ics{newacronym}. -There is no check for the existance of \meta{label}. +There is no check for the existence of \meta{label}. \begin{definition}[\DescribeMacro{\ifglshasdesc}] \cs{ifglshasdesc}\marg{label}\marg{true part}\marg{false part} @@ -8617,7 +8894,7 @@ performed, otherwise \meta{false part}. Compare with: This checks if the \gloskey{description} field has been set to just \ics{nopostdesc} for the entry given by \meta{label}. If it has, \meta{true part} is performed, otherwise \meta{false part}. -There is no check for the existance of \meta{label}. +There is no check for the existence of \meta{label}. For all other fields you can use: \begin{definition} @@ -8626,12 +8903,12 @@ part} \end{definition} This checks if the field given by \meta{field} for the entry identified by \meta{label} is empty. If it is, \meta{true part} is -performed, otherwise \meta{false part}. If the field supplied is unrecognised \meta{false part} +performed, otherwise \meta{false part}. If the field supplied is +unrecognised \meta{false part} is performed and a warning is issued. Unlike the above commands, such as \cs{ifglshasshort}, an error occurs if the entry is undefined. - \chapter{Prefixes or Determiners}\label{sec:prefix} The \sty{glossaries-prefix} package provides @@ -8705,11 +8982,14 @@ The prefixes can also be used with acronyms. For example: The \sty{glossaries-prefix} package provides convenient commands to use these prefixes with commands such as \ics{gls}. Note that the prefix is not considered part of the \gls{linktext}, so it's not -included in the hyperlink (where hyperlinks are enabled). +included in the hyperlink (where hyperlinks are enabled). The +options and any star or plus modifier are passed on to the \glslike\ +command. (See \sectionref{sec:glslink} for further details.) + \begin{definition}[\DescribeMacro\pgls] \cs{pgls}\oarg{options}\marg{label}\oarg{insert} \end{definition} -This is prepends the value of the \gloskey{prefix} key (or +This is inserts the value of the \gloskey{prefix} key (or \gloskey{prefixfirst} key, on \gls{firstuse}) in front of \cs{gls}\oarg{options}\marg{label}\oarg{insert}. @@ -8732,7 +9012,7 @@ As \cs{pgls} but converts the prefix to upper case and uses \begin{definition}[\DescribeMacro\pglspl] \cs{pglspl}\oarg{options}\marg{label}\oarg{insert} \end{definition} -This is prepends the value of the \gloskey{prefixplural} key (or +This is inserts the value of the \gloskey{prefixplural} key (or \gloskey{prefixfirstplural} key, on \gls{firstuse}) in front of \cs{glspl}\oarg{options}\marg{label}\oarg{insert}. @@ -8769,7 +9049,9 @@ Singular: a~sample, l'oeil. Plural: the samples, les yeux. For a complete document, see \samplefile{-prefix}. \end{example} -This package also provides the following commands: +This package also provides the commands described below, none of +which perform any check to determine the entry's existence. + \begin{definition}[\DescribeMacro\ifglshasprefix] \cs{ifglshasprefix}\marg{label}\marg{true part}\marg{false part} \end{definition} @@ -8800,15 +9082,13 @@ non-empty value for the \gloskey{prefixfirstplural} key. \cs{glsentryprefix}\marg{label} \end{definition} Displays the value of the \gloskey{prefix} key for the entry given -by \meta{label}. (No check is performed to determine if the entry -exists.) +by \meta{label}. \begin{definition}[\DescribeMacro\glsentryprefixfirst] \cs{glsentryprefixfirst}\marg{label} \end{definition} Displays the value of the \gloskey{prefixfirst} key for the entry given -by \meta{label}. (No check is performed to determine if the entry -exists.) +by \meta{label}. \begin{definition}[\DescribeMacro\glsentryprefixplural] \cs{glsentryprefixplural}\marg{label} @@ -8844,7 +9124,7 @@ apply.}: \end{definition} \begin{important} -As with analoguous commands such as \ics{Glsentrytext}, these +As with analogous commands such as \ics{Glsentrytext}, these commands aren't expandable so can't be used in PDF bookmarks. \end{important} @@ -8944,9 +9224,7 @@ 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/}. -Below is a list of some frequently asked questions about the -\styfmt{glossaries} package. For a complete -list, consult the +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 @@ -8955,197 +9233,6 @@ comp.text.tex newsgroup, the Bug reports can be submitted via \urlfootref{http://www.dickimaw-books.com/bug-report.html}{my package bug report form}. -\begin{enumerate} -\item \textbf{Q.} I get the error message: -\begin{verbatim} -! Undefined control sequence. -\in@ #1#2->\begingroup \def \in@@ -\end{verbatim} - -\textbf{A.} This error can occur if you have a fragile command in -one of your entry definitions. -In most cases using \cs{glsnoexpandfields} before defining your -entry should fix this, but there are still a few fragile commands -that will still cause this error even with \cs{glsnoexpandfields}. -If this is the case put \cs{protect} in front of the fragile -command. - -\item \textbf{Q.} I get the error message: -\begin{verbatim} -Missing \begin{document} -\end{verbatim} - -\textbf{A.} Check you are using an up to date version of the \sty{xkeyval} -package. - -\item \textbf{Q.} When I use \gls{xindy}, I get the following error -message: -\begin{verbatim} -ERROR: CHAR: index 0 should be less than the length of -the string -\end{verbatim} - -\textbf{A.} \gls{xindy} discards all commands and braces from the -sort string. If your sort string (either specified by the \gloskey{sort} -key or the \gloskey{name} key) only consists of commands, this will -be treated by \gls*{xindy} as an empty sort string, which produces an -error message in newer versions of \gls*{xindy}. For example, the -following will cause a problem: -\begin{verbatim} -\newglossaryentry{alpha}{name={\ensuremath{\alpha}}, - description=alpha} -\end{verbatim} -Either use a different sort key for the entry, for example: -\begin{verbatim} -\newglossaryentry{alpha}{sort=alpha, - name={\ensuremath{\alpha}}, - description=alpha} -\end{verbatim} -or, if all entries are like this, you may prefer to use the -\pkgopt[use]{sort} or \pkgopt[def]{sort} package options. See -\sectionref{sec:pkgopts-sort} for further details of the \pkgopt{sort} -option. - -\item \textbf{Q.} I've used the \pkgopt{smallcaps} option, but the acronyms -are displayed in normal sized upper case letters. - -\textbf{A.} The \pkgopt{smallcaps} package option uses \ics{textsc} to typeset -the acronyms. This command converts lower case letters to small -capitals, while upper case letters remain their usual size. Therefore -you need to specify the acronym in lower case letters. - -\item \textbf{Q.} My acronyms won't break across a line when they're -expanded. - -\textbf{A.} PDF\LaTeX\ can break hyperlinks across a line, but -\LaTeX\ can't. If you can't use PDF\LaTeX\ then disable the \gls{firstuse} -links using the package option \pkgopt[false]{hyperfirst}. - -\item \textbf{Q.} How do I change the font that the acronyms are displayed in? - -\textbf{A.} The easiest way to do this is to specify the \pkgopt{smaller} package -option and redefine \ics{acronymfont} to use the required typesetting -command. For example, suppose you would like the acronyms displayed in -a sans-serif font, then you can do: -\begin{verbatim} -\usepackage[smaller]{glossaries} -\renewcommand*{\acronymfont}[1]{\textsf{#1}} -\end{verbatim} - -\item \textbf{Q.} How do I change the font that the acronyms are displayed in -on \firstuse? - -\textbf{A.} The easiest way to do this is to specify the \pkgopt{smaller} package -option and redefine \ics{firstacronymfont} to use the required -command. Note that if you don't want the acronym on subsequent use -to use \ics{textsmaller}, you will also need to redefine \ics{acronymfont}, -as above. For example to make the acronym emphasized on -\firstuse, but use the surrounding font for subsequent use, you can do: -\begin{verbatim} -\usepackage[smaller]{glossaries} -\renewcommand*{\firstacronymfont}[1]{\emph{#1}} -\renewcommand*{\acronymfont}[1]{#1} -\end{verbatim} - -\item \textbf{Q.} I don't have Perl installed, do I have to use -\gls{makeglossaries}? - -\textbf{A.} No. Although it is strongly recommended, you don't have to -use \gls{makeglossaries}. If you prefer a GUI application and have -Java installed, you can use \gls{makeglossariesgui} instead. -Otherwise you can just call \gls{makeindex} explicitly (see -\sectionref{sec:makeindexapp}). Note that you can't use \gls{xindy} -if you don't have Perl installed. - -\item \textbf{Q.} I'm used to using the \styfmt{glossary} package: are there any -instructions on migrating from the \sty{glossary} package to the -\styfmt{glossaries} package? - -\textbf{A.} Read \qtdocref{Upgrading from the glossary package to -the glossaries package}{glossary2glossaries} which should be -available from the same location as this document. - -\item \textbf{Q.} I'm using \sty{babel} but the fixed names haven't -been translated. - -\textbf{A.} The \styfmt{glossaries} package currently only supports -the following languages: Brazilian Portuguese, Danish, Dutch, -English, French, German, Irish, Italian, Hungarian, Polish, Serbian and -Spanish. If you want to add another language, send me the -translations, and I'll add them to the next version. - -If you are using one of the above languages, but the text hasn't -been translated, try using the \styfmt{glossaries} package option -\pkgopt[babel]{translate}. Also, try adding the language as a -global option to the class file. - -\item \textbf{Q.} My glossaries haven't appeared. - -\textbf{A.} Remember to do the following: -\begin{itemize} -\item Add \ics{makeglossaries} to the document preamble. - -\item Use either \ics{printglossary} for each glossary that has -been defined or \ics{printglossaries}. - -\item Use the commands listed in \sectionref{sec:glslink}, -\sectionref{sec:glsadd} or \sectionref{sec:crossref} for each entry -that you want to appear in the glossary. - -\item Run \LaTeX\ on your document, then run \gls{makeglossaries}, -then run \LaTeX\ on your document again. If you want the glossaries -to appear in the table of contents, you will need an extra \LaTeX\ -run. If any of your entries cross-reference an entry that's not -referenced in the main body of the document, you will need to run -\gls*{makeglossaries} (see \sectionref{sec:makeglossaries}) after the -second \LaTeX\ run, followed by another \LaTeX\ run. -\end{itemize} - -Check the log files (\filetype{.log}, \filetype{.glg} etc) for any -warnings. - -\item \textbf{Q.} Why is glossaries creating an empty \filetype{.glo} file? - -\textbf{A.} Because you haven't used any entries in the -\texttt{main} glossary via commands such as \ics{gls}. -If you don't want to use this glossary, you can suppress its -creation via the package option \pkgopt{nomain}. - -\item \textbf{Q.} It is possible to change the rules used to sort -the glossary entries? - -\textbf{A.} If it's for an individual entry, then you can use the -entry's \gloskey{sort} key to sort it according to a different term. -If it's for the entire alphabet, then you will need to use -\gls{xindy} (instead of \gls{makeindex}) and use an appropriate -\gls*{xindy} language module. Writing \gls*{xindy} modules or styles -is beyond the scope of this manual. Further information about -\gls*{xindy} can be found at the -\urlfootref{http://xindy.sourceforge.net/}{Xindy Web Site}. There is -also a link to the \gls*{xindy} mailing list from that site. - -If you want to sort according to order of definition or order of -use, use the \pkgopt{sort} package option described in -\sectionref{sec:pkgopts-sort}. - -\item \textbf{Q.} I get an error when using TeX4HT\index{TeX4HT|hyperpage} with -\styfmt{glossaries}. - -\textbf{A.} TeX4HT seems to have a problem with the glossary styles -that use \ics{indexspace}. I don't know enough about TeX4HT to find -out why. Either use a different glossary style or redefine the -style command that uses \cs{indexspace}. For example, if you are -using the \glostyle{list} style, try: -\begin{verbatim} -\renewcommand*{\glsgroupskip}{} -\end{verbatim} -or -\begin{verbatim} -\renewcommand*{\glsgroupskip}{\item[]} -\end{verbatim} - -\end{enumerate} - \PrintIndex \end{document} |