From b172732c296db880f27bfba6ea750c2f4bffb860 Mon Sep 17 00:00:00 2001
From: Karl Berry <karl@freefriends.org>
Date: Mon, 20 Jan 2014 23:17:11 +0000
Subject: glossaries (20jan14)

git-svn-id: svn://tug.org/texlive/trunk@32735 c570f23f-e606-0410-a88d-b1316a301751
---
 .../doc/latex/glossaries/glossaries-user.tex       | 309 +++++++++++++++------
 1 file changed, 222 insertions(+), 87 deletions(-)

(limited to 'Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex')

diff --git a/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex b/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex
index 3cb0f0ab9b9..dbc79467c05 100644
--- a/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex
+++ b/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex
@@ -1,4 +1,4 @@
-\documentclass[report]{nlctdoc}
+\documentclass[report,inlinetitle]{nlctdoc}
 
 \usepackage[inner=0.5in,includemp]{geometry}
 
@@ -90,15 +90,15 @@
 {%
   An application that doesn't have a graphical user
   interface. That is, an application that doesn't have any windows,
-  buttons or menus and can be run in a command
-  prompt or terminal (see
-  \url{http://www.dickimaw-books.com/latex/novices/html/terminal.html}).
+  buttons or menus and can be run in 
+  \href{http://www.dickimaw-books.com/latex/novices/html/terminal.html}{a command
+  prompt or terminal}.
 }
 
 \longnewglossaryentry{xindy}{%
-  name={\appfmt{xindy}\index{xindy|htextbf}},
+  name={\appfmt{xindy}\index{xindy=\appfmt{xindy}|htextbf}},
   sort={xindy},
-  text={\protect\app{xindy}}
+  text={\appfmt{xindy}\iapp{xindy}}
 }%
 {%
   A flexible \gls{indexingapp} with multilingual
@@ -106,37 +106,35 @@
 }
 
 \newglossaryentry{makeindex}{%
-name={\appfmt{makeindex}\index{makeindex|htextbf}},%
+name={\appfmt{makeindex}\index{makeindex=\appfmt{makeindex}|htextbf}},%
 sort={makeindex},%
-text={\protect\app{makeindex}},%
+text={\appfmt{makeindex}\iapp{makeindex}},%
 description={An \gls{indexingapp}},
 }
 
 \newglossaryentry{makeglossaries}{%
-name={\appfmt{makeglossaries}\index{makeglossaries|htextbf}},%
+name={\appfmt{makeglossaries}\index{makeglossaries=\appfmt{makeglossaries}|htextbf}},%
 sort={makeglossaries},%
-text={\protect\app{makeglossaries}},%
+text={\appfmt{makeglossaries}\iapp{makeglossaries}},%
 description={A custom designed Perl script interface 
 to \gls{xindy} and \gls{makeindex} provided with the \styfmt{glossaries}
 package}
 }
 
 \longnewglossaryentry{makeglossariesgui}{%
-name={\appfmt{makeglossariesgui}\index{makeglossariesgui|htextbf}},%
+name={\appfmt{makeglossariesgui}\index{makeglossariesgui=\appfmt{makeglossariesgui}|htextbf}},%
 sort={makeglossariesgui},%
-text={\protect\app{makeglossariesgui}}%
+text={\appfmt{makeglossariesgui}\iapp{makeglossariesgui}}%
 }%
 {%
   A Java GUI alternative to \gls{makeglossaries} that
-  also provides diagnostic tools. Home page:
-  \url{http://www.dickimaw-books.com/apps/makeglossariesgui/}. Also
-  available on CTAN.
+  also provides diagnostic tools. Available separately on CTAN.
 }
 
 \newglossaryentry{numberlist}{%
 name={Number list\itermdef{number list}},%
 sort={number list},%
-text={\protect\term{number list}},%
+text={number list\iterm{number list}},%
 description={A list of \glslink{entrylocation}{entry locations} (also 
 called a location list). The number list can be suppressed using the 
 \pkgopt{nonumberlist} package option}
@@ -145,7 +143,7 @@ called a location list). The number list can be suppressed using the
 \newglossaryentry{entrylocation}{%
 name={Entry location\itermdef{entry location}},%
 sort={entry location},%
-text={\protect\term{entry location}},%
+text={entry location\iterm{entry location}},%
 description={The location of the entry in the document. This
 defaults to the page number on which the entry appears. An entry may
 have multiple locations}
@@ -162,7 +160,7 @@ see={numberlist}
 \newglossaryentry{linktext}{%
 name={Link text\itermdef{link text}},
 sort={link text},%
-text={\protect\term{link text}},
+text={link text\iterm{link text}},
 description={The text produced by commands such as \ics{gls}. It may
 or may not be a hyperlink to the glossary}
 }
@@ -208,7 +206,7 @@ governed by the \gloskey{first} and \gloskey{firstplural} keys of
 \longnewglossaryentry{sanitize}{%
 name={Sanitize\itermdef{sanitize}},%
 sort={sanitize},
-text={\protect\term{sanitize}},%
+text={sanitize\iterm{sanitize}},%
 user1={sanitized\protect\iterm{sanitize}},%
 user2={sanitization\protect\iterm{sanitize}}%
 }%
@@ -280,13 +278,20 @@ user2={sanitization\protect\iterm{sanitize}}%
 \MakeShortVerb{"}
 \DeleteShortVerb{\|}
 
- \title{User Manual for glossaries.sty v4.02}
+ \title{User Manual for glossaries.sty v4.03}
  \author{Nicola L.C. Talbot\\%
   \url{http://www.dickimaw-books.com/}}
 
- \date{2013-12-05}
+ \date{2014-01-20}
  \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}.
+\end{abstract}
+
 \begin{important}
 Documents have various styles when it comes to presenting glossaries
 or lists of terms or notation. People have their own preferences and
@@ -297,7 +302,7 @@ complicated descriptions. The \styfmt{glossaries} package is
 flexible enough to accommodate such varied requirements, but this
 flexibility comes at a price: a~big manual.
 
-\grimace\ If you're freaking out at the size of this manual, start with
+\aargh\ If you're freaking out at the size of this manual, start with
 \texttt{glossariesbegin.pdf} (\qt{The glossaries package: a guide
 for beginnners}). You should find it in the same directory as this
 document or try \texttt{texdoc glossariesbegin.pdf}. Once you've got
@@ -330,7 +335,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.02}.
+\qt{Documented Code for glossaries v4.03}.
 This includes the documented code for the \sty{mfirstuc} package.
 
 \item[INSTALL] Installation instructions.
@@ -1319,7 +1324,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.10.
+2.12.
 \end{important}
 
 \subsection{Using xindy explicitly}
@@ -1517,7 +1522,9 @@ package. Options that aren't \meta{key}=\meta{value} (such as
 
 \begin{description}
 \item[\pkgopt{nowarn}] This suppresses all warnings generated by
-the \styfmt{glossaries} package.
+the \styfmt{glossaries} package. Don't use this option if you're new to using
+\styfmt{glossaries} as the warnings are designed to help detect
+common mistakes (such as forgetting to use \ics{makeglossaries}).
 
 \item[\pkgopt{nomain}] This suppresses the creation of the main
 glossary and associated \texttt{.glo} file, if unrequired. Note that
@@ -1741,7 +1748,8 @@ The start of each glossary adds information to the page header via
 \begin{definition}[\DescribeMacro{\glsglossarymark}]
 \cs{glsglossarymark}\marg{glossary title}
 \end{definition}
-This defaults to \cs{@mkboth}, but you may 
+By default this uses \cs{@mkboth}\footnote{unless \cls{memoir} is
+loaded, which case it uses \ics{markboth}} but you may 
 need to redefine it.
 For example, to only change the right header:
 \begin{verbatim}
@@ -3303,6 +3311,34 @@ in the text will appear in the relevant glossaries.
 Note also that \cs{loadglsentries} may only be used in the 
 preamble.
 
+Remember that you can use \ics{provideglossaryentry} rather than
+\ics{newglossaryentry}. Suppose you want to maintain a large database
+of acronyms or terms that you're likely to use in your documents,
+but you may want to use a modified version of some of those entries.
+(Suppose, for example, one document may require a more detailed
+description.) Then if you define the entries using
+\cs{provideglossaryentry} in your database file, you can override
+the definition by simply using \cs{newglossaryentry} before loading
+the file. For example, suppose your file (called, say,
+\texttt{terms.tex}) contains:
+\begin{verbatim}
+\provideglossaryentry{mallard}{name=mallard,
+ description={a type of duck}}
+\end{verbatim}
+but suppose your document requires a more detailed description, you
+can do:
+\begin{verbatim}
+\usepackage{glossaries}
+\makeglossaries
+
+\newglossaryentry{mallard}{name=mallard,
+ description={a dabbling duck where the male has a green head}}
+
+\loadglsentries{terms}
+\end{verbatim}
+Now the \texttt{mallard} definition in the \texttt{terms.tex} file
+will be ignored.
+
 \section{Moving Entries to Another Glossary}
 \label{sec:moveentry}
 
@@ -3478,8 +3514,10 @@ commands or any other command that has a moving argument.
 
 The above warning is particularly important if you are using the
 \styfmt{glossaries} package in conjunction with the \sty{hyperref}
-package. Instead, use one of the commands listed in
-\sectionref{sec:glsnolink} (such as \ics{glsentrytext}) or provide an
+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
 alternative via the optional argument to the sectioning\slash caption
 command. Examples:
 \begin{verbatim}
@@ -4008,7 +4046,7 @@ the hyperlink. Similarly for the other user keys:
 \section{Changing the format of the link text}
 \label{sec:glsdisplay}
 
-The format of the \gls{linktext} for \ics{gls}, \ics{glspl}
+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
 deprecated. Backwards compatibility should be preserved but
@@ -4016,8 +4054,31 @@ you may need to use the \pkgopt{compatible-3.07} option}:
 \begin{definition}[\DescribeMacro{\glsentryfmt}]
 \cs{glsentryfmt}
 \end{definition}
-If you want to redefine this command, you may use the following
-commands within its definition:
+This may be redefined but if you only want the change the display style 
+for a given glossary, then you need to use
+\begin{definition}[\DescribeMacro{\defglsentryfmt}]
+\cs{defglsentryfmt}\oarg{type}\marg{definition}
+\end{definition}
+instead of redefining \cs{glsentryfmt}. The optional first argument 
+\meta{type} is the glossary type. This defaults to
+\ics{glsdefaulttype} if omitted. The second argument is the
+entry format definition.
+
+\begin{important}
+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
+\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}, 
+see \sectionref{sec:pkgopts-acronym}) use 
+\cs{defglsentryfmt} to set their display style.
+\end{important}
+
+Within the \meta{definition} argument of \cs{defglsentryfmt}, or if you
+want to redefine \cs{glsentryfmt}, you may use the following
+commands:
 
 \begin{definition}[\DescribeMacro{\glslabel}]
 \cs{glslabel}
@@ -4146,20 +4207,6 @@ then \verb|\gls{distance}| will produce \qt{\textbf{distance (km)}}.
 For a complete document, see the sample file \samplefile{-entryfmt}.
 \end{example}
 
-If you have multiple glossaries, changing \cs{glsentryfmt} will change the 
-way entries for all of the glossaries appear when using the commands 
-\ics{gls}, \ics{glspl}, their upper case variants and \ics{glsdisp}.  
-If you only
-want the change to affect entries for a given glossary, then you need
-to use
-\begin{definition}[\DescribeMacro{\defglsentryfmt}]
-\cs{defglsentryfmt}\oarg{type}\marg{definition}
-\end{definition}
-instead of redefining \cs{glsentryfmt}. The optional first argument 
-\meta{type} is the glossary type. This defaults to
-\ics{glsdefaulttype} if omitted. The second argument is the
-entry format definition.
-
 \begin{example}{Custom Format for Particular Glossary}{ex:defglsentryfmt}
 Suppose you have created a new glossary called
 \texttt{notation} and you want to change the way the entry is
@@ -5372,6 +5419,22 @@ the extension for the \gls{makeindex} or \gls{xindy} transcript file
 (this information is only used by \gls{makeglossaries} which picks
 up the information from the auxiliary file).
 
+\begin{important}
+The glossary label \meta{name} must not contain any active
+characters. It's generally best to stick with just characters that
+have category code~11 (typically \texttt{a}, \ldots, \texttt{z}
+and \texttt{A}, \ldots, \texttt{Z}).
+\end{important}
+
+You can also use:
+\begin{definition}[\DescribeMacro{\altnewglossary}]
+\cs{altnewglossary}\marg{name}\marg{tag}\marg{title}\oarg{counter}
+\end{definition}
+This is equivalent to
+\begin{alltt}
+\cs{newglossary}[\meta{tag}-glg]\marg{name}\{\meta{tag}-gls\}\{\meta{tag}-glo\}\marg{title}\oarg{counter}
+\end{alltt}
+
 Note that the main (default) glossary is automatically created as:
 \begin{verbatim}
 \newglossary{main}{gls}{glo}{\glossaryname}
@@ -5426,10 +5489,25 @@ useful means to define acronyms. For convenience, the
 \end{definition}
 
 This uses \ics{newglossaryentry} to create an entry with the given
-label in the glossary given by \ics{acronymtype}. It also uses the
-\gloskey{long}, \gloskey{longplural}, \gloskey{short} and
-\gloskey{shortplural} keys to store the long and abbreviated forms
-and their plurals. 
+label in the glossary given by \ics{acronymtype}. You can specify a
+different glossary using the \gloskey{type} key within the optional
+argument. The \cs{newacronym} command also uses the \gloskey{long},
+\gloskey{longplural}, \gloskey{short} and \gloskey{shortplural} keys
+in \cs{newglossaryentry} to store the long and abbreviated forms and
+their plurals. 
+
+\begin{important}
+If you haven't identified the specified glossary type as a list of
+acronyms (via the package option
+\pkgopt{acronymlists} or the command \ics{DeclareAcronymList}, 
+see \sectionref{sec:pkgopts-acronym}) \cs{newacronym} will add it to
+the list and \emph{reset the display style} for that glossary via
+\ics{defglsentryfmt}. If you have a mixture of acronyms and regular
+entries within the same glossary, care is needed if you want to
+change the display style: you must first identify that glossary as a
+list of acronyms and then use \ics{defglsentryfmt} (not redefine
+\ics{glsentryfmt}) before defining your entries.
+\end{important}
 
 The optional argument \marg{key-val list} allows you to specify keys
 such as \gloskey{description} (when used with one of the styles that
@@ -5443,7 +5521,10 @@ For example:
   {dm}{DM}{diagonal matrix}
 \end{verbatim}
 If the \firstuse\ uses the plural form, \verb|\glspl{dm}| will
-display: diagonal matrices (DMs).
+display: diagonal matrices (DMs). If you want to use
+the \gloskey{longplural} or \gloskey{shortplural} keys, I recommend
+you use \ics{setacronymstyle} to set the display style rather than
+using one of the pre-version 4.02 acronym styles.
 
 Since \ics{newacronym} uses \ics{newglossaryentry}, you can use
 commands like \ics{gls} and \ics{glsreset} as with any other
@@ -5476,16 +5557,24 @@ Now \verb|\gls{idn}| will produce \qt{identification number
 uses.
 \end{example}
 
-There are commands analogous to \ics{glstext} (described in
+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.
+\end{important}
+
 \begin{definition}[\DescribeMacro{\acrshort}]
 \cs{acrshort}\oarg{options}\marg{label}\oarg{insert}
 \end{definition}
-This displays the short form for the entry given by \meta{label}.
+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:
@@ -5611,6 +5700,14 @@ It is also possible to access the long and short forms without
 adding information to the glossary using commands analogous to
 \ics{glsentrytext} (described in \sectionref{sec:glsnolink}).
 
+\begin{important}
+The commands that convert the first letter to upper case come with
+the same caveats as those for analogous commands like
+\ics{Glsentrytext} (non-expandable, can't be used in PDF bookmarks,
+care needs to be taken if the first letter is an accented character
+etc). See \sectionref{sec:glsnolink}.
+\end{important}
+
 The long form can be accessed using:
 \begin{definition}[\DescribeMacro{\glsentrylong}]
 \cs{glsentrylong}\marg{label}
@@ -6528,19 +6625,34 @@ checks for this.
 Glossaries vary from lists that simply contain a symbol with a terse
 description to lists of terms or phrases with lengthy descriptions.
 Some glossaries may have terms with associated symbols. Some may
-have hierarchical entries.  There is therefore no single style 
-that fits every type of glossary. The \styfmt{glossaries} package 
-comes with a number of pre-defined glossary styles, and you need to
-choose one that best suits your type of glossary. There is a summary
-of available styles in \tableref{tab:styles}. If none of them suit
-your document, you can defined your own style 
-(see \sectionref{sec:newglossarystyle}).
+have hierarchical entries.  There is therefore no single style that
+fits every type of glossary. The \styfmt{glossaries} package comes
+with a number of pre-defined glossary styles, described in
+\sectionref{sec:predefinedstyles}. You can choose one of these that
+best suits your type of glossary or, if none of them suit your
+document, you can defined your own style (see
+\sectionref{sec:newglossarystyle}).
+
+The glossary style can be set using the \gloskey[printglossary]{style} key in the optional
+argument to \ics{printglossary} or using the command:
+\begin{definition}[\DescribeMacro{\setglossarystyle}]
+\cs{setglossarystyle}\marg{style-name}
+\end{definition}
+(before the glossary is displayed).
+
+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.
+
+\section{Predefined Styles}
+\label{sec:predefinedstyles}
 
 The predefined styles can
 accommodate numbered level~0 (main) and level~1 entries. See the
 package options \pkgopt{entrycounter}, \pkgopt{counterwithin} and
 \pkgopt{subentrycounter} described in
-\sectionref{sec:pkgopts-printglos}.
+\sectionref{sec:pkgopts-printglos}. There is a summary
+of available styles in \tableref{tab:styles}. 
 
 \begin{table}[htbp]
 \caption[Glossary Styles]{Glossary Styles. An asterisk in the style 
@@ -6582,15 +6694,6 @@ be displayed.}
 \par
 \end{table}
 
-The glossary style can be set using the \gloskey[printglossary]{style} key in the optional
-argument to \ics{printglossary} or using the command:
-\begin{definition}[\DescribeMacro{\setglossarystyle}]
-\cs{setglossarystyle}\marg{style-name}
-\end{definition}
-Some of the 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.
-
 The tabular-like styles that allow multi-line descriptions and page
 lists use the length \DescribeMacro{\glsdescwidth}\cs{glsdescwidth}
 to set the width of the description column and the length
@@ -6652,7 +6755,7 @@ given entry by placing \ics{nopostdesc} in the entry's description.
 As from version 3.03 you can now use the package option
 \pkgopt{nopostdot} to suppress this full stop.
 
-\section{List Styles}
+\subsection{List Styles}
 \label{sec:liststyles}
 
 The styles described in this section are all defined in the package
@@ -6727,7 +6830,7 @@ the same manner as \glostyle{listdotted}.
 \end{description}
 
 
-\section{Longtable Styles}
+\subsection{Longtable Styles}
 \label{sec:longstyles}
 
 The styles described in this section are all defined in the package
@@ -6823,7 +6926,7 @@ descriptions and page lists.
 \end{description}
 
 
-\section{Longtable Styles (Ragged Right)}
+\subsection{Longtable Styles (Ragged Right)}
 \label{sec:longraggedstyles}
 
 The styles described in this section are all defined in the package
@@ -6910,7 +7013,7 @@ lines around it.
 \end{description}
 
 
-\section{Supertabular Styles}
+\subsection{Supertabular Styles}
 \label{sec:superstyles}
 
 The styles described in this section are all defined in the package
@@ -7009,7 +7112,7 @@ descriptions and page lists.
 \end{description}
 
 
-\section{Supertabular Styles (Ragged Right)}
+\subsection{Supertabular Styles (Ragged Right)}
 \label{sec:superraggedstyles}
 
 The styles described in this section are all defined in the package
@@ -7097,7 +7200,7 @@ lines around it.
 
 \end{description}
 
-\section{Tree-Like Styles}
+\subsection{Tree-Like Styles}
 \label{sec:treestyles}
 
 The styles described in this section are all defined in the package
@@ -7184,7 +7287,7 @@ groups. The navigation line is the same as that for
 
 \end{description}
 
-\section{Multicols Style}
+\subsection{Multicols Style}
 \label{sec:mcolstyles}
 
 The \sty{glossary-mcols} package provides tree-like styles that are
@@ -7237,7 +7340,7 @@ Analogous Tree Style\\
 \end{tabular}
 \end{table}
 
-\section{In-Line Style}
+\subsection{In-Line Style}
 \label{sec:inline}
 
 This section covers the \sty{glossary-inline} package that supplies
@@ -7289,7 +7392,7 @@ a parent main entry and its first sub-entry.
 This defaults to ``\texttt{\glsinlineseparator}'' and is used at the end
 of the glossary.
 
-\chapter{Defining your own glossary style}
+\section{Defining your own glossary style}
 \label{sec:newglossarystyle}
 
 If the predefined styles don't fit your requirements, you can
@@ -7632,6 +7735,12 @@ that displays each entry in a \env{longtable} as follows:
 This section describes some utility commands. Additional commands
 can be found in the documented code (glossaries-code.pdf).
 
+\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.
+\end{important}
+
 \begin{definition}[\DescribeMacro{\forallglossaries}]
 \cs{forallglossaries}\oarg{glossary list}\marg{cs}\marg{body}
 \end{definition}
@@ -7694,6 +7803,12 @@ doesn't exist, an error is generated. (This command uses
 Does the reverse of \cs{glsdoifexists}. (This command uses
 \cs{ifglsentryexists}.)
 
+\begin{definition}[\DescribeMacro{\glsdoifexistsorwarn}]
+\cs{glsdoifexistsorwanr}\marg{label}\marg{code}
+\end{definition}
+As \cs{glsdoifexists} but issues a warning rather than an error if
+the entry doesn't exist.
+
 \begin{definition}[\DescribeMacro{\ifglsused}]
 \cs{ifglsused}{\meta{label}}{\meta{true part}}{\meta{false
 part}}
@@ -7730,6 +7845,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}.
 
 \begin{definition}[\DescribeMacro{\ifglshasshort}]
 \cs{ifglshasshort}\marg{label}\marg{true part}\marg{false part}
@@ -7738,6 +7854,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}.
 
 \begin{definition}[\DescribeMacro{\ifglshasdesc}]
 \cs{ifglshasdesc}\marg{label}\marg{true part}\marg{false part}
@@ -7751,6 +7868,20 @@ 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}.
+
+For all other fields you can use:
+\begin{definition}
+\cs{ifglshasfield}\marg{field}\marg{label}\marg{true part}\marg{false
+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}
+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}
 
@@ -7958,12 +8089,16 @@ apply.}:
 \cs{Glsentryprefixplural}\marg{label}
 \end{definition}
 
-\pagebreak
 \DescribeMacro\Glsentryprefixfirstplural
 \begin{definition}
 \cs{Glsentryprefixfirstplural}\marg{label}
 \end{definition}
 
+\begin{important}
+As with analoguous commands such as \ics{Glsentrytext}, these
+commands aren't expandable so can't be used in PDF bookmarks.
+\end{important}
+
 \begin{example}{Adding Determiner to Glossary Style}{ex:plist}
 You can use the above commands to define a new glossary style that
 uses the determiner. For example, the following style is a slight
@@ -8058,17 +8193,17 @@ For example, on my Linux partition it can be found in
 \texttt{\slash usr\slash local\slash texlive\slash 2013\slash
 texmf-dist\slash doc\slash latex\slash glossaries/}. 
 Further information on debugging \LaTeX\ code is available at
-\url{http://theoval.cmp.uea.ac.uk/~nlct/latex/minexample/}.
+\url{http://www.dickimaw-books.com/latex/minexample/}.
 
 Below is a list of the most frequently asked questions. For other
-queries, consult the \styfmt{glossaries} FAQ at
-\url{http://www.dickimaw-books.com/faqs/glossariesfaq.html}. If that
+queries, 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 \LaTeX\ Community Forum
-(\url{http://www.latex-community.org/}) or \TeX\ on StackExchange
-(\url{http://tex.stackexchange.com/}). 
-Bug reports can be submitted at
-\url{http://www.dickimaw-books.com/bug-report.html}. 
+comp.text.tex newsgroup, the 
+\urlfootref{http://www.latex-community.org/}{\LaTeX\ Community Forum} or 
+\urlfootref{http://tex.stackexchange.com/}{\TeX\ on StackExchange}. 
+Bug reports can be submitted via 
+\urlfootref{http://www.dickimaw-books.com/bug-report.html}{my package bug report form}. 
 
 \begin{enumerate}
 \item \textbf{Q.} I get the error message:
-- 
cgit v1.2.3

