From 9144cd7fe8a83679a67b2739e85be044b997c4a7 Mon Sep 17 00:00:00 2001
From: Karl Berry <karl@freefriends.org>
Date: Tue, 26 Jan 2016 22:53:06 +0000
Subject: glossaries (24jan15)

git-svn-id: svn://tug.org/texlive/trunk@39488 c570f23f-e606-0410-a88d-b1316a301751
---
 .../doc/latex/glossaries/glossaries-user.tex       | 666 ++++++++++++++++++---
 1 file changed, 574 insertions(+), 92 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 37419b2fae6..18d96dbad06 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,inlinetitle]{nlctdoc}
+\documentclass[report,inlinetitle,widecs]{nlctdoc}
 
 \usepackage[inner=0.5in,includemp]{geometry}
 
@@ -308,6 +308,16 @@ user2={sanitization\protect\iterm{sanitize}}%
   description={An alphabet consisting of \glspl{nonlatinchar}.}
 }
 
+\newglossaryentry{glossaries-extra}{%
+  name={\styfmt{glossaries-extra}},
+  sort={glossaries-extra},
+  description={A separate package that extends the
+  \styfmt{glossaries} package, providing new features or improving
+  existing features. If you want to use \styfmt{glossaries-extra}, 
+  you must have both the \styfmt{glossaries} package and the 
+  \styfmt{glossaries-extra} package installed.}
+}
+
 \ifpdf
 \externaldocument{glossaries-code}
 \fi
@@ -378,11 +388,11 @@ and~\hyperlink{option#2}{#2}}
 \MakeShortVerb{"}
 \DeleteShortVerb{\|}
 
- \title{User Manual for glossaries.sty v4.20}
+ \title{User Manual for glossaries.sty v4.21}
  \author{Nicola L.C. Talbot\\%
   \url{http://www.dickimaw-books.com/}}
 
- \date{2015-11-30}
+ \date{2016-01-24}
  \maketitle
 
 \begin{abstract}
@@ -390,6 +400,12 @@ The \styfmt{glossaries} package provides a means to define terms or
 abbreviations or symbols that can be referenced within your document.
 Sorted lists with collated \glslink{entrylocation}{locations} can be 
 generated either using \TeX\ or using a supplementary \gls{indexingapp}.
+
+Additional features not provided here may be available through
+the supplemental package \gls{glossaries-extra} which, if required,
+needs to be installed separately. New features will be added to
+\gls*{glossaries-extra}. Any new versions of the \styfmt{glossaries}
+package after v4.21 will be just bug fixes.
 \end{abstract}
 
 If you require multilingual support you must also separately install 
@@ -401,6 +417,21 @@ the \styfmt{glossaries} package will automatically try to load it and
 will give a warning if the module isn't found. See
 \sectionref{sec:languages} for further details.
 
+The \styfmt{glossaries} package requires a number of other packages
+including, but not limited to, \sty{tracklang}, \sty{mfirstuc},
+\sty{etoolbox},
+\sty{xkeyval} (at least version dated 2006/11/18), \sty{textcase},
+\sty{xfor}, \sty{datatool-base} (part of the \sty{datatool} bundle) and \sty{amsgen}. These
+packages are all available in the latest \TeX\ Live and Mik\TeX\
+distributions. If any of them are missing, please update your
+\TeX\ distribution using your update manager.
+(For help on this see, for example,
+\href{http://tex.stackexchange.com/questions/55437/how-do-i-update-my-tex-distribution}{How
+do I update my \TeX\ distribution?}
+or
+\href{http://tex.stackexchange.com/questions/14925/updating-tex-on-linux}{Updating
+\TeX\ on Linux}.)
+
 \begin{important}
 Documents have wide-ranging styles when it comes to presenting glossaries
 or lists of terms or notation. People have their own preferences and
@@ -444,7 +475,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.20}.
+\qt{Documented Code for glossaries v4.21}.
 This includes the documented code for the \sty{mfirstuc} package.
 
 \item[INSTALL] Installation instructions.
@@ -1830,7 +1861,9 @@ the appropriate UTF-8 characters.
 
 \begin{important}
 This section is only applicable if you have chosen \optsor23. You can
-ignore this section if you have chosen \opt1.
+ignore this section if you have chosen \opt1. If you want to
+alphabetically sort your entries always remember to use the
+\gloskey{sort} key if the \gloskey{name} contains any \LaTeX\ commands.
 \end{important}
 
 If this section seriously confuses you, and you can't work out how
@@ -1894,6 +1927,12 @@ can't diagnose the problem, you will have to read the relevant transcript
 file and see if you can work it out from the \gls*{makeindex} or
 \gls*{xindy} messages.
 
+\item If \gls{makeindex} warns about multiple encap values,
+\gls{makeglossaries} will detect this and attempt to correct the
+problem.\footnote{Added to version \gls{makeglossaries} 2.18.} Since 
+\gls{xindy} doesn't warn about this, this correction is only
+provided by \gls{makeglossaries} when \gls{makeindex} is used.
+
 \end{itemize}
 
 As from version 4.16, the \styfmt{glossaries} package also comes
@@ -1906,21 +1945,19 @@ a~Lua interpreter) you don't need to install anything else in order
 to use \gls{makeglossaries-lite.lua} so it's an alternative to
 \gls{makeglossaries} if you want to use \opt2 (\gls{makeindex}).
 
-There is also a Java GUI alternative called \gls{makeglossariesgui},
-distributed separately, that has diagnostic tools.
-
-Whilst it is strongly recommended that you use the
-\gls{makeglossaries} Perl script or the \gls{makeglossaries-lite.lua}
-script or the \gls{makeglossariesgui} Java application, it is
+Whilst I strongly recommended that you use the \gls{makeglossaries}
+Perl script or the \gls{makeglossaries-lite.lua} Lua script, it is
 possible to use the \styfmt{glossaries} package without using those
 applications. However, note that some commands and package options
-have no effect if you explicitly run \gls{makeindex}\slash\gls{xindy}. 
+have no effect if you explicitly run \gls{makeindex}\slash\gls{xindy}.  
 These are listed in \tableref{tab:makeglossariesCmds}.
 
 \begin{important}
 If you are choosing not to use \gls*{makeglossaries} because you
 don't want to install Perl, you will only be able to use
-\gls*{makeindex} as \gls*{xindy} also requires Perl.
+\gls*{makeindex} as \gls*{xindy} also requires Perl. (Other useful
+Perl scripts include \appfmt{epstopdf} and \appfmt{latexmk}, so it's
+well-worth the effort to install Perl.)
 \end{important}
 
 Note that if any of your entries use an entry
@@ -1951,6 +1988,10 @@ latex myDoc
 makeglossaries myDoc
 latex myDoc
 \end{prompt}
+(Note that if you use \gls{glossaries-extra}, this will be done
+automatically for you if the \pkgoptfmt{indexcrossrefs} feature is
+enabled. See the \gls*{glossaries-extra} user guide for further
+details.)
 
 Likewise, an additional \gls{makeglossaries} and \LaTeX\ run
 may be required if the document pages shift with re-runs. For
@@ -2074,6 +2115,31 @@ path. If this isn't the case, you can specify the full pathname
 using \texttt{-m} \meta{path/to/makeindex} for \gls*{makeindex}
 or \texttt{-x} \meta{path/to/xindy} for \gls*{xindy}.
 
+As from \gls{makeglossaries} v2.18, if you are using
+\gls{makeindex}, there's a check for \gls*{makeindex}['s] multiple
+encap warning. This is where different encap values (location formats) are 
+used on the same location for the same entry. For example:
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage{glossaries}
+\makeglossaries
+
+\newglossaryentry{sample}{name={sample},description={an example}}
+
+\begin{document}
+\gls{sample}, \gls[format=textbf]{sample}.
+\printglossaries
+\end{document}
+\end{verbatim}
+If you explicitly use \gls{makeindex}, this will cause a warning and
+the location list will be \qt{1, \textbf{1}}. That is, the page
+number will be repeated with each format. As from v2.18,
+\gls{makeglossaries} will check for this warning and, if found, will
+attempt to correct the problem by removing duplicate locations and
+retrying. There's no similar check for \gls{xindy} as \gls*{xindy}
+won't produce any warning and will simply discard duplicates.
+
 The \gls{makeglossaries} script contains POD (Plain Old
 Documentation). If you want, you can create a man page for
 \gls*{makeglossaries} using \app{pod2man} and move the 
@@ -2084,7 +2150,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.18.
 \end{important}
 
 \subsection{Using the makeglossaries-lite.lua Lua Script}
@@ -2658,7 +2724,7 @@ If you want \cs{glsglossarymark} to use \cs{MakeUppercase} in the header, use th
 \pkgopt{ucmark} option described below.
 
 Occasionally you may find that another package defines 
-\linebreak\cs{cleardoublepage} when it is not required. This may cause an 
+\cs{cleardoublepage} when it is not required. This may cause an 
 unwanted blank page to appear before each glossary. This can
 be fixed by redefining \DescribeMacro\glsclearpage\cs{glsclearpage}:
 \begin{verbatim}
@@ -3281,8 +3347,8 @@ of acronyms using:
 \item[\pkgopt{shortcuts}] This option provides shortcut commands
 for acronyms.  See \sectionref{sec:acronyms} for further details.
 Alternatively you can use:
-\begin{definition}[\DescribeMacro\DefineAcronymShortcuts]
-\cs{DefineAcronymShortcuts}
+\begin{definition}[\DescribeMacro\DefineAcronymSynonyms]
+\cs{DefineAcronymSynonyms}
 \end{definition}
 \end{description}
 
@@ -3716,13 +3782,21 @@ information about this entry. There are two required fields:
 The description is set in the third argument of
 \cs{longnewglossaryentry} and \cs{longprovideglossaryentry}. With
 the other commands it's set via the \gloskey{description} key.
-Available fields are listed below:
+As is typical with \meta{key}=\meta{value} lists, values that contain 
+a comma or equal sign must be enclosed in
+braces. Available fields are listed below:
 
 \begin{description}
 \item[{\gloskey{name}}] The name of the entry (as it will appear in 
 the glossary). If this key is omitted and the \gloskey{parent}
 key is supplied, this value will be the same as the parent's name.
 
+\begin{important}
+If the \gloskey{name} key contains any commands, you must also
+use the \gloskey{sort} key (described below) if you intend sorting the entries
+alphabetically, otherwise the entries can't be sorted correctly.
+\end{important}
+
 \item[{\gloskey{description}}] A brief description of this term (to
 appear in the glossary). Within this value, you can use 
 \begin{definition}[\DescribeMacro{\nopostdesc}]
@@ -3865,7 +3939,10 @@ will set it to the expansion of the \gloskey{name} key (if
 \begin{important}
 Take care with \gls{xindy} (\opt3): if you have entries with the same
 \gloskey{sort} value they will be treated as the
-same entry.
+same entry. If you use \gls{xindy} and aren't using the \texttt{def}
+or \texttt{use} sort methods, \textbf{always} use the \gloskey{sort}
+key for entries where the name just consists of a control sequence
+(for example \texttt{name=\{\cs{alpha}\}}).
 
 Take care if you use \opt1 and the \gloskey{name} contains fragile
 commands. You will either need to explicitly set the \gloskey{sort}
@@ -3909,11 +3986,21 @@ glossary entries using \gloskey{nonumberlist=false} (see above).
 Alternatively, you can use the \pkgopt{seeautonumberlist} package
 option.  For further details, see \sectionref{sec:crossref}.
 
+This key essentially provides a convenient shortcut that performs
+\begin{alltt}
+\cs{glssee}\oarg{tag}\marg{label}\marg{xr-label list}
+\end{alltt}
+after the entry has been defined.
+
 \begin{important}
 For \optsand23, \ics{makeglossaries} must be used before any occurrence of
-\ics{newglossaryentry} that contains the \gloskey{see} key.
+\ics{newglossaryentry} that contains the \gloskey{see} key. This key
+has no effect for entries defined in the \env{document} environment.
 \end{important}
 
+If you use the \gloskey{see} key, you may want to consider using the
+supplementary \gls{glossaries-extra} package.
+
 \end{description}
 
 The following keys are reserved for \ics{newacronym} (see
@@ -3924,6 +4011,21 @@ and the \sty{glossaries-accsupp} (\sectionref{sec:accsupp}) packages.
 You can also define your own custom keys (see
 \sectionref{sec:addkey}).
 
+\begin{important}
+Avoid using any of the \glslike\ or \glstextlike\ commands within
+the \gloskey{text}, \gloskey{first}, \gloskey{short} or
+\gloskey{long} keys (or their plural equivalent) or any
+other key that you plan to access through those commands.
+(For example, the \gloskey{symbol} key if you intend to use
+\cs{glssymbol}.) Otherwise you end up with nested links, which
+can cause complications and they won't work with the case-changing
+commands. You can use them within the value of keys 
+that won't be accessed through those commands. For example,
+the \gloskey{description} key if you don't use \cs{glsdesc}.
+Additionally, they'll confuse the entry formatting commands, such as
+\cs{glslabel}.
+\end{important}
+
 Note that if the name starts with 
 \gls{nonlatinchar}, you must group the character, otherwise it will 
 cause a problem for commands like \ics{Gls} and \ics{Glspl}. 
@@ -4180,7 +4282,8 @@ Suppose I want to define acronyms and other forms of abbreviations,
 such as initialisms, but I want them all in the same glossary and I
 want the acronyms on first use to be displayed with the short form followed by
 the long form in parentheses, but the opposite way round for other
-forms of abbreviations.
+forms of abbreviations.\footnote{The \gls{glossaries-extra} package
+provides a simpler way of achieving this.}
 
 Here I can define a new key that determines whether the term is
 actually an acronym rather than some other form of abbreviation. I'm
@@ -4769,7 +4872,10 @@ used in the preamble. I reluctantly removed this restriction in version 1.13,
 but there are issues with defining commands in the \env{document}
 environment instead of the preamble, which is why the restriction is
 maintained for newer commands. This restriction is also reimposed
-for \cs{newglossaryentry} by the new \opt1.
+for \cs{newglossaryentry} by the new \opt1. (The
+\gls{glossaries-extra} automatically reimposes this restriction for
+\optsand23 but provides a package option to allow document
+definitions.)
 
 \subsection{Technical Issues}
 \label{sec:techissues}
@@ -4814,13 +4920,9 @@ There are drawbacks to this mechanism: if you modify an entry
 definition, you need a second run to see the effect of your
 modification; this method requires an extra \cs{newwrite}, which may
 exceed \TeX's maximum allocation; unexpected expansion issues could
-occur; if you have very long entries, you could find unexpected line
-breaks have been written to the temporary file causing spurious
-spaces (or, even worse, a~command name could get split across a line
-causing an error message).
-
-The last reason is why \ics{longnewglossaryentry} has the
-preamble-only restriction, which I don't intend to lift.
+occur; the \gloskey{see} key isn't stored, which means it can't be
+added to the \filetype{.glsdefs} file when it's created at the end of the 
+document (and therefore won't be present on subsequent runs).
 
 \subsection{Good Practice Issues}
 \label{sec:goodpractice}
@@ -4859,6 +4961,35 @@ option, or an alternative counter can be set as the default using
 the \pkgopt{counter} package option. The number list is also
 referred to as the location list\index{location list|see{number list}}.
 
+Each location in the \gls{numberlist} is encapsulated with a
+command. (The \termdef{encap} value.) By default this is the 
+\ics{glsnumberformat} command, but may be overridden using the
+\gloskey[glslink]{format} key in the optional argument to commands
+like \cs{gls}. (See \sectionref{sec:glslink}.) For example, you may
+want the location to appear in bold to indicate the principle use of
+a term or symbol. Complications can arise if you use different encap
+values for the same location. For example, suppose on page~10 you
+have both the default \cs{glsnumberformat} and \cs{textbf} encaps.
+While it may seem apparent that \cs{textbf} should override
+\cs{glsnumberformat} in this situation, neither \gls{makeindex} nor
+\gls{xindy} know this. In the case of \gls{xindy}, it only accepts
+one encap and discards the other for identical locations. The encap
+it chooses to keep may not necessarily be the one you want. In the
+case of \gls{makeindex}, it accepts different encaps for the same
+location, but warns about it. This leads to a \gls{numberlist} with
+the same location repeated in different fonts.
+
+This is something you need to be careful about, but if you use the
+\gls{makeglossaries} Perl script it will detect \gls{makeindex}'s
+warning and attempt to fix the problem.\footnote{This feature was
+introduced in \gls{makeglossaries} version 2.18.} Since \gls{xindy}
+doesn't generate a warning, \gls{makeglossaries} won't do anything
+about it if you are using \gls{xindy}. With \gls{makeindex},
+\gls{makeglossaries} will let the encaps override each other,
+similar to \gls{xindy}, except that the \cs{glsnumberformat} encap
+will always have the least precedence. Other conflicting encaps will
+have the last one override earlier ones for the same location.
+
 Due to the asynchronous nature of \TeX's output routine (see,
 for example,
 \href{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=oddpage}{Finding
@@ -4959,7 +5090,6 @@ command.)
 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.
@@ -5081,6 +5211,14 @@ 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.
 
+Note that repeated use of these commands for the same entry can
+cause the \gls{numberlist} to become quite long, which may not be
+particular helpful to the reader. In this case, you can use the
+non-indexing commands described in \sectionref{sec:glsnolink} or
+you can use the supplemental \gls{glossaries-extra} package, which
+provides a means to suppress the automated indexing of the commands listed
+in this chapter.
+
 \begin{important}
 I strongly recommend that you don't use the commands
 defined in this chapter in the arguments of sectioning or caption
@@ -5106,6 +5244,11 @@ command or use \sty{hyperref}'s \ics{texorpdfstring}. Examples:
 \chapter[An overview of Perl]{An overview of \gls{perl}}
 \chapter{An overview of \texorpdfstring{\gls{perl}}{Perl}}
 \end{verbatim}
+If you want to retain the formatting that's available through
+commands like \cs{acrshort} (for example, if you are using one of
+the small caps styles), then you might want to consider the
+\gls{glossaries-extra} package which provides commands
+for this purpose.
 
 If you want the \gls{linktext} to produce a hyperlink to the
 corresponding entry details in the glossary, you should load the
@@ -5160,29 +5303,43 @@ 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
+commands that unset (mark the entry as having been used) or reset
+(mark the entry as not used) 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.
+\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 \gls{glossaries-extra} package
+provides the option to add a third custom variant.
+
+\begin{important}
+Avoid nesting these commands. For example don't do
+\cs{glslink}\marg{label}\texttt{\{\cs{gls}\marg{label2}\}}
+as this is likely to cause problems. By implication, these
+means that you should avoid using any of these commands within
+the \gloskey{text}, \gloskey{first}, \gloskey{short} or
+\gloskey{long} keys (or their plural equivalent) or any
+other key that you plan to access through these commands.
+(For example, the \gloskey{symbol} key if you intend to use
+\cs{glssymbol}.)
+\end{important}
 
 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
+be used to enable\slash 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,
@@ -5227,13 +5384,6 @@ with the \gloskey[glslink]{format} key using
 See \sectionref{sec:xindy} for further details.
 \end{important}
 
-Note that unlike \ics{index}, you can't have anything following the
-command name, such as an asterisk or arguments. If you want to
-cross-reference another entry, either use the \gloskey{see} key when
-you define the entry or use \ics{glssee} (described in
-\sectionref{sec:crossref}).
-
-
 If you are using hyperlinks and you want to change the font of the
 hyperlinked location, don't use \ics{hyperpage} (provided by the
 \sty{hyperref} package) as the locations may not refer to a page
@@ -5291,11 +5441,19 @@ the \gls*{firstuseflag} will be localised to the current scope. The
 default is \texttt{local=false}.
 
 \end{description}
+The \gls{glossaries-extra} package provides an additional key.
+Please see the \gls{glossaries-extra} user manual for further
+details.
+
+\begin{important}
+The \gls{linktext} isn't scoped by default. Any unscoped
+declarations in the \gls{linktext} may affect subsequent text.
+\end{important}
 
 \section{The \cs{gls}-Like Commands (First Use Flag Queried)}
 \label{sec:gls-like}
 
-This section describes the commands that unset the \firstuseflag\ on
+This section describes the commands that unset (mark as used) 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 
@@ -5345,10 +5503,169 @@ and
 \end{definition}
 which make the first letter of the link text or all the link text
 upper case, respectively. For the former, the uppercasing of the
-first letter is performed by \ics{makefirstuc}. For further
-details, including its limitations, see the \sty{mfirstuc} user manual.
+first letter is performed by \ics{makefirstuc}.
+
+\begin{important}
+The first letter uppercasing command \cs{makefirstuc} has
+limitations which must be taken into account if you use \cs{Gls} or
+any of the other commands that convert the first letter to
+uppercase. 
+\end{important}
+The upper casing is performed as follows:
+\begin{itemize}
+\item If the first thing in the \gls{linktext} is a command follow
+by a group, the upper casing is performed on the first object of the
+group. For example, if an entry has been defined as
+\begin{verbatim}
+\newglossaryentry{sample}{
+ name={\emph{sample} phrase},
+ sort={sample phrase},
+ description={an example}}
+\end{verbatim}
+Then \cs{Gls}\verb|{sample}| will set the \gls{linktext}
+to\footnote{I've used \cs{MakeUppercase} in all the examples for clarity, but it
+will actually use \cs{mfirstucMakeUppercase}.}
+\begin{verbatim}
+\emph{\MakeUppercase sample} phrase
+\end{verbatim}
+which will appear as \emph{\MakeUppercase sample} phrase.
+
+\item If the first thing in the \gls{linktext} isn't a command or is
+a command but isn't followed by a group, then the upper casing will
+be performed on that first thing. For example, if an entry has been
+defined as:
+\begin{verbatim}
+\newglossaryentry{sample}{
+  name={\oe-ligature},
+  sort={oe-ligature},
+  description={an example}
+}
+\end{verbatim}
+Then \cs{Gls}\verb|{sample}| will set the \gls{linktext} to
+\begin{verbatim}
+\MakeUppercase \oe-ligature
+\end{verbatim}
+which will appear as \MakeUppercase \oe-ligature.
+
+\item If you have \sty{mfirstuc} v2.01 or above, an extra case is
+added. If the first thing is \cs{protect} it will be discarded and
+the above rules will then be tried.
 
-There are also analogous plural forms:
+\end{itemize}
+(Note the use of the \gloskey{sort} key in the above examples.)
+
+There are hundreds of \LaTeX\ packages that altogether define
+thousands of commands with various syntax and it's impossible for
+\sty{mfirstuc} to take them all into account. The above rules are quite
+simplistic and are designed for \gls{linktext} that starts with
+a~text-block command (such as \cs{emph}) or a command that produces 
+a character (such as \cs{oe}). This means that if your \gls{linktext}
+starts with something that doesn't adhere to \sty{mfirstuc}'s assumptions
+then things are likely to go wrong.
+
+For example, starting with a math-shift symbol:
+\begin{verbatim}
+\newglossaryentry{sample}{
+  name={$a$},
+  sort={a},
+  description={an example}
+}
+\end{verbatim}
+This falls into case~2 above, so the \gls{linktext} will be set to
+\begin{verbatim}
+\MakeUppercase $a$
+\end{verbatim}
+This attempts to uppercase the math-shift \verb|$|, which will go
+wrong. In this case it's not appropriate to perform any
+case-changing, but it may be that you want to use \cs{Gls}
+programmatically without checking if the text contains any maths.
+In this case, the simplest solution is to insert an empty brace at
+the start:
+\begin{verbatim}
+\newglossaryentry{sample}{
+  name={{}$a$},
+  sort={a},
+  description={an example}
+}
+\end{verbatim}
+Now the \gls{linktext} will be set to
+\begin{verbatim}
+\MakeUppercase{}$a$
+\end{verbatim}
+and the \cs{uppercase} becomes harmless.
+
+Another issue occurs when the \gls{linktext} starts with a command
+followed by an argument (case~1) but the argument is a label,
+identifier or something else that shouldn't have a case-change.
+A common example is when the \gls{linktext} starts with one of the
+commands described in this chapter. (But you haven't done that, have
+you? What with the warning not to do it at the beginning of the chapter.)
+Or when the \gls{linktext} starts with one of the non-linking
+commands described in \sectionref{sec:glsnolink}. For example:
+\begin{verbatim}
+\newglossaryentry{sample}{name={sample},description={an example}}
+\newglossaryentry{sample2}{
+   name={\glsentrytext{sample} two},
+   sort={sample two},
+   description={another example}
+ }
+\end{verbatim}
+Now the \gls{linktext} will be set to:
+\begin{verbatim}
+\glsentrytext{\MakeUppercase sample} two
+\end{verbatim}
+This will generate an error because there's no entry with the label
+given by \verb|\MakeUppercase sample|. The best solution here is to 
+write the term out in the \gloskey{text} field and use the command
+in the \gloskey{name} field. If you don't use \cs{glsname} anywhere
+in your document, you can use \cs{gls} in the \gloskey{name} field:
+\begin{verbatim}
+\newglossaryentry{sample}{name={sample},description={an example}}
+\newglossaryentry{sample2}{
+   name={\gls{sample} two},
+   sort={sample two},
+   text={sample two},
+   description={another example}
+ }
+\end{verbatim}
+
+If the \gls{linktext} starts with a command that has an optional
+argument or with multiple arguments where the actual text isn't in
+the first argument, then \cs{makefirstuc} will also fail. For
+example:
+\begin{verbatim}
+\newglossaryentry{sample}{
+ name={\textcolor{blue}{sample} phrase},
+ sort={sample phrase},
+ description={an example}}
+\end{verbatim}
+Now the \gls{linktext} will be set to:
+\begin{verbatim}
+\textcolor{\MakeUppercase blue}{sample} phrase
+\end{verbatim}
+This won't work because \verb|\MakeUppercase blue| isn't a recognised
+colour name. In this case you will have to define a helper command where
+the first argument is the text. For example:
+\begin{verbatim}
+\newglossaryentry{sample}{
+\newcommand*{\blue}[1]{\textcolor{blue}{#1}}
+ name={\blue{sample} phrase},
+ sort={sample phrase},
+ description={an example}}
+\end{verbatim}
+In fact, since the whole design ethos of \LaTeX\ is the separation
+of content and style, it's better to use a semantic command. For
+example:
+\begin{verbatim}
+\newglossaryentry{sample}{
+\newcommand*{\keyword}[1]{\textcolor{blue}{#1}}
+ name={\keyword{sample} phrase},
+ sort={sample phrase},
+ description={an example}}
+\end{verbatim}
+For further details see the \sty{mfirstuc} user manual.
+
+There are plural forms that are analogous to \cs{gls}:
 \begin{definition}[\DescribeMacro{\glspl}]
 \cs{glspl}\oarg{options}\marg{label}\oarg{insert}
 \end{definition}
@@ -5360,8 +5677,8 @@ There are also analogous plural forms:
 \end{definition}
 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
+defined using \ics{newglossaryentry} or, if the entry is an
+abbreviation and \cs{setacronymstyle} was used, from the \gloskey{longplural} or
 \gloskey{shortplural} keys.
 
 \begin{important}
@@ -5422,7 +5739,9 @@ final argument.
 
 \begin{important}
 Don't use any of the \glslike\ or \glstextlike\ commands in the 
-argument of \cs{glslink}.
+argument of \cs{glslink}. By extension, this means that you can't
+use them in the value of fields that are used to form
+\gls{linktext}.
 \end{important}
 
 \begin{definition}[\DescribeMacro{\glstext}]
@@ -5439,7 +5758,8 @@ There are also analogous commands:
 \cs{GLStext}\oarg{options}\marg{text}\oarg{insert}
 \end{definition}
 These convert the first character or all the characters to
-uppercase, respectively.
+uppercase, respectively. See the note on \cs{Gls} above for details
+on the limitations of converting the first letter to upper case.
 
 \begin{definition}[\DescribeMacro{\glsfirst}]
 \cs{glsfirst}\oarg{options}\marg{label}\oarg{insert}
@@ -5455,6 +5775,16 @@ There are also analogous uppercasing commands:
 \cs{GLSfirst}\oarg{options}\marg{text}\oarg{insert}
 \end{definition}
 
+\begin{important}
+The value of the \gloskey{first} key (and \gloskey{firstplural} key)
+doesn't necessarily match the text produced by \ics{gls} (or \ics{glspl}) on
+\firstuse\ as the \gls{linktext} used by \ics{gls} may be modified
+through commands like \ics{defglsentry}. (Similarly, the value of the
+\gloskey{text} and \gloskey{plural} keys don't necessarily match
+the \gls*{linktext} used by \cs{gls} or \cs{glspl} on subsequent
+use.)
+\end{important}
+
 \begin{definition}[\DescribeMacro{\glsplural}]
 \cs{glsplural}\oarg{options}\marg{label}\oarg{insert}
 \end{definition}
@@ -5721,11 +6051,23 @@ Note that you can also use commands such as \ics{ifglsused} within
 the definition of \cs{glsentryfmt} (see \sectionref{sec:glsunset}).
 
 The commands \ics{glslabel}, \ics{glstype}, \ics{glsifplural},
-\ics{glscapscase}, \ics{glscustomtex} and \ics{glsinsert} are
+\ics{glscapscase}, \ics{glscustomtext} and \ics{glsinsert} are
 typically updated at the start of the \glslike\ and \glstextlike\
 commands so they can usually be accessed in the hook user commands,
 such as \ics{glspostlinkhook} and \ics{glslinkpostsetkeys}.
 
+\begin{important}
+This means that using commands like \ics{gls} within the fields
+that are accessed using the \glslike\ or \glstextlike\ commands
+(such as the \gloskey{first}, \gloskey{text}, \gloskey{long}
+or \gloskey{short} keys) will cause a problem. The entry formatting
+performed by \cs{glsentryfmt} and related commands isn't scoped
+(otherwise if would cause problems for \cs{glspostlinkhook} which
+may need to look ahead as well as look behind).
+This means that any nested commands will, at the very least, change 
+the label stored in \cs{glslabel}.
+\end{important}
+
 If you only want to make minor modifications to \cs{glsentryfmt},
 you can use
 \begin{definition}[\DescribeMacro{\glsgenentryfmt}]
@@ -5735,7 +6077,7 @@ This uses the above commands to display just the \gloskey{first},
 \gloskey{text}, \gloskey{plural} or \gloskey{firstplural} keys 
 (or the custom text) with the insert text appended.
 
-Alternatively, if want to change the entry format for acronyms
+Alternatively, if want to change the entry format for abbreviations
 (defined via \ics{newacronym}) you can use:
 \begin{definition}[\DescribeMacro{\glsgenacfmt}]
 \cs{glsgenacfmt}
@@ -5779,7 +6121,8 @@ only need to redefine \ics{genacrfullformat} and
 on changing the style of acronyms.
 
 \begin{important}
-Note that \cs{glsentryfmt} is not used by the \glstextlike\ commands.
+Note that \cs{glsentryfmt} (or the formatting given by \cs{defglsentryfmt}) 
+is not used by the \glstextlike\ commands.
 \end{important}
 
 As from version 4.16, both the \glslike\ and \glstextlike\ commands
@@ -6319,7 +6662,10 @@ package, but make sure you use one of the expandable commands within
 \begin{verbatim}
 \ecaptialisewords{\glsentrytext{somelabel}}
 \end{verbatim}
-Note that \cs{ecapitalisewords} is not expandable.
+Note that \cs{ecapitalisewords} is not expandable. Note that
+this command has the same limitations as \cs{makefirstuc} which is
+used by commands like \cs{Gls} and \cs{Glsentryname} to upper-case
+the first letter (see the notes about \cs{Gls} in \sectionref{sec:gls-like}).
 
 \begin{definition}[\DescribeMacro{\glsentryname}]
 \cs{glsentryname}\marg{label}
@@ -6585,7 +6931,7 @@ followed by one or two runs of \LaTeX\ is required.
 
 The first command, \cs{glsentrynumberlist}, simply displays
 the number list as is. The second command,
-\linebreak\cs{glsdisplaynumberlist}, formats the list using:
+\cs{glsdisplaynumberlist}, formats the list using:
 \begin{definition}[\DescribeMacro{\glsnumlistsep}]
 \cs{glsnumlistsep}
 \end{definition}
@@ -6627,15 +6973,21 @@ glossary} in the documented code (\texttt{glossaries-code.pdf}).
 (Must be used with \ics{makeglossaries} in the preamble.)
 \end{description}
 
-These commands will display all the glossaries in the order in which they were
-defined. Note that, in the case of \optsand23, no glossaries will appear until you have either
-used the Perl script \gls{makeglossaries} or have directly used
-\gls{makeindex} or \gls{xindy} (as described in
-\sectionref{sec:makeglossaries}). If the glossary 
-still does not appear after you re-\LaTeX\ your document, check the
-\gls*{makeindex}\slash\gls*{xindy} log files to see if there is a problem.
-With \opt1, you just need two \LaTeX\ runs to make the glossaries appear, 
-but you may need further runs to make the \glspl{numberlist} up-to-date.
+These commands will display all the glossaries in the order in which
+they were defined. Note that, in the case of \optsand23, no
+glossaries will appear until you have either used the Perl script
+\gls{makeglossaries} or Lua script \gls{makeglossaries-lite.lua} or
+have directly used \gls{makeindex} or \gls{xindy} (as described in
+\sectionref{sec:makeglossaries}). (While the external files are
+missing, these commands will just do \cs{null} for each missing
+glossary to assist dictionary style documents that just use
+\cs{glsaddall} without inserting any text.)
+
+If the glossary still does not appear after you re-\LaTeX\ your
+document, check the \gls*{makeindex}\slash\gls*{xindy} log files to
+see if there is a problem.  With \opt1, you just need two \LaTeX\
+runs to make the glossaries appear, but you may need further runs to
+make the \glspl{numberlist} up-to-date.
 
 An individual glossary can be displayed using:
 \begin{description}
@@ -6652,6 +7004,9 @@ An individual glossary can be displayed using:
 (Must be used with \ics{makeglossaries} in the preamble.)
 \end{description}
 where \meta{options} is a \meta{key}=\meta{value} list of options. 
+(Again, when the associated external file is missing, \cs{null} is
+inserted into the document.)
+
 The following keys are available:
 \begin{description}
 \item[{\gloskey[printglossary]{type}}] The value of this key
@@ -6687,7 +7042,7 @@ 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
+for this glossary. If false (\verb|nonumberlist=false|) the
 numberlist is displayed for this glossary.
 
 \item[{\gloskey[printglossary]{nogroupskip}}] This is a boolean
@@ -6737,7 +7092,7 @@ entries have fragile commands in their \gloskey{sort} field.
 By default, the glossary is started either by \ics{chapter*} or by
 \ics{section*}, depending on whether or not \ics{chapter} is defined.
 This can be overridden by the \pkgopt{section} package option or the
-\linebreak\ics{setglossarysection} command. Numbered sectional units can be
+\ics{setglossarysection} command. Numbered sectional units can be
 obtained using the \pkgopt{numberedsection} package option. Each
 glossary sets the page header via the command
 \begin{definition}[\DescribeMacro\glsglossarymark]
@@ -7007,7 +7362,7 @@ you need to add a location style in the appropriate format using
 \end{definition}
 where \meta{name} is the name of the format and \meta{definition} is
 the \gls{xindy} definition. The optional argument \meta{prefix-location}
-is needed if \linebreak\cs{theH}\meta{counter} either isn't defined or is
+is needed if \cs{theH}\meta{counter} either isn't defined or is
 different from \cs{the}\meta{counter}.
 (See also \ics{glsaddprotectedpagefmt} described in
 \sectionref{sec:numberlists}.)
@@ -7214,7 +7569,7 @@ Note that \cs{GlsSetXdyFirstLetterAfterDigits} has no effect if
 
 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}
+\cs{newglossary}\oarg{log-ext}\marg{name}\marg{in-ext}\marg{out-ext}\linebreak\marg{title}\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
@@ -7253,7 +7608,7 @@ which is equivalent to
 \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
+It may be that you have some terms 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
@@ -7329,20 +7684,23 @@ change LaTeX’s \qt{fixed names}}.
 
 \begin{important}
 Note that although this chapter uses the term \qt{acronym}, you can also
-use the commands described here for abbreviations or contractions
+use the commands described here for initialisms or contractions
 (as in the case of some of the examples given below).
 If the glossary title is no longer applicable (for example, it
 should be \qt{Abbreviations} rather than \qt{Acronyms}) then
 you can change the title either by redefining \ics{acronymname} (see
 \sectionref{sec:languages}) or by using the \gloskey[printglossary]{title}
 in the optional argument of \ics{printglossary} (or
-\ics{printacronym}).
+\ics{printacronym}). You may prefer to use the
+\gls{glossaries-extra} package which defines \cs{newabbreviation}
+and treats acronyms (e.g.\ \qt{laser}) differently from other forms
+of abbreviations (e.g.\ \qt{html}).
 \end{important}
 
 You may have noticed in \sectionref{sec:newglosentry} that when you
 specify a new entry, you can specify alternate text to use when the
 term is \glsd{firstuse} in the document. This provides a
-useful means to define acronyms. For convenience, the
+useful means to define abbreviations. For convenience, the
 \styfmt{glossaries} package defines the command:
 \begin{definition}[\DescribeMacro{\newacronym}]
 \cs{newacronym}\oarg{key-val list}\marg{label}\marg{abbrv}\marg{long}
@@ -7417,12 +7775,50 @@ Now \verb|\gls{idn}| will produce \qt{identification number
 uses.
 \end{example}
 
+Recall from the warning in 
+\sectionref{sec:newglosentry} that you should avoid using
+the \glslike\ and \glstextlike\ commands within the value of
+keys like \gloskey{text} and \gloskey{first} due to complications
+arising from nested links. The same applies to abbreviations
+defined using \cs{newacronym}.
+
+For example, suppose you have defined:
+\begin{verbatim}
+\newacronym{ssi}{SSI}{server side includes}
+\newacronym{html}{HTML}{hypertext markup language}
+\end{verbatim}
+you may be tempted to do:
+\begin{verbatim}
+\newacronym{shtml}{S\gls{html}}{\gls{ssi} enabled \gls{html}}
+\end{verbatim}
+\textbf{Don't!} This will break the case-changing commands, such
+as \ics{Gls}, it will cause inconsistencies on \firstuse, and,
+if hyperlinks are enabled, will cause nested hyperlinks. It will
+also confuse the commands used by the entry formatting (such as
+\ics{glslabel}).
+
+Instead, consider doing:
+\begin{verbatim}
+\newacronym
+ [description={\gls{ssi} enabled \gls{html}}]
+ {shtml}{SHTML}{SSI enabled HTML}
+\end{verbatim}
+or
+\begin{verbatim}
+\newacronym
+ [description={\gls{ssi} enabled \gls{html}}]
+ {shtml}{SHTML}
+ {server side includes enabled hypertext markup language}
+\end{verbatim}
+Similarly for the \glstextlike\ commands.
+
 \begin{important}
 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.
+(Including the warning immediately above this box.)
 \end{important}
 
 The optional arguments are the same as those for the \glstextlike\
@@ -7622,7 +8018,7 @@ And the full form can be obtained using:
 These again use \ics{acrfullformat} by default, but
 the format may be redefined by the acronym style.
 
-\section{Changing the Acronym Style}
+\section{Changing the Abbreviation Style}
 \label{sec:setacronymstyle}
 
 It may be that the default style doesn't suit your requirements in
@@ -7639,6 +8035,12 @@ representing lists of acronyms, you must use \cs{setacronymstyle}
 \emph{after} using \cs{DeclareAcronymList}.
 \end{important}
 
+The \styfmt{glossaries} package has the restriction that only one
+style may be in use that applies to all entries defined with
+\cs{newacronym}. If you need multiple abbreviation styles, then try
+using the \gls{glossaries-extra} package, which has better
+abbreviation management.
+
 Note that unlike the default behaviour of \cs{newacronym}, the
 styles used via \cs{setacronymstyle} don't use the \gloskey{first}
 or \gloskey{text} keys, but instead they use \ics{defglsentryfmt} to
@@ -8412,6 +8814,8 @@ adjust the space factor, which is usually done by inserting \cs{@}
 before the full stop.
 
 The next example shows one way of achieving this.
+(Note that the supplemental \gls{glossaries-extra} package provides a much
+simpler way of doing this, which you may prefer to use.)
 
 \begin{example}{Abbreviations with Full Stops (Periods)}{ex:dotabbr}
 As from version 4.16, there's now a hook (\ics{glspostlinkhook})
@@ -8768,7 +9172,9 @@ Flag Unset)}
 
 As from version 4.14, it's now possible to keep track of how many
 times an entry is used. That is, how many times the \firstuseflag\
-is unset.
+is unset. Note that the supplemental \gls{glossaries-extra} package improves
+this function and also provides per-unit counting, which isn't
+available with the \styfmt{glossaries} package.
 
 \begin{important}
 This function is disabled by default as it adds extra
@@ -9218,7 +9624,8 @@ unless you use the \pkgopt{nolong} or \pkgopt{nostyles} package
 options.  These styles fully justify the description and page list
 columns.  If you want ragged right formatting instead, use the
 analogous styles described in \sectionref{sec:longraggedstyles}.
-
+If you want to incorporate rules from the \sty{booktabs} package,
+try the styles described in \sectionref{sec:longbooktabsstyles}.
 
 \begin{description}
 \item[long] The \glostyle{long} style uses the \env{longtable}
@@ -9285,7 +9692,7 @@ around it.
 \glostyle{long4col} but allows multi-line descriptions and page
 lists.  The width of the description column is governed by the
 length \ics{glsdescwidth} and the width of the page list column is
-governed by the length \linebreak\ics{glspagelistwidth}. The widths of the
+governed by the length \ics{glspagelistwidth}. The widths of the
 name and symbol columns are governed by the widest entry in the
 given column.
 
@@ -9298,7 +9705,7 @@ page lists.
 page lists.
 
 \item[altlong4colheaderborder] The \glostyle{altlong4colheaderborder} 
-style is like \linebreak\glostyle{long4colheaderborder} but allows multi-line
+style is like \glostyle{long4colheaderborder} but allows multi-line
 descriptions and page lists.
 \end{description}
 
@@ -9322,6 +9729,8 @@ these styles will only be available if you explicitly load
 Note that you can't set these styles using the \pkgopt{style}
 package option since the styles aren't defined until after
 the \styfmt{glossaries} package has been loaded.
+If you want to incorporate rules from the \sty{booktabs} package,
+try the styles described in \sectionref{sec:longbooktabsstyles}.
 
 \begin{description}
 \item[longragged] The \glostyle{longragged} style has two
@@ -9389,6 +9798,75 @@ lines around it.
 
 \end{description}
 
+\subsection{Longtable Styles (\styfmt{booktabs})}
+\label{sec:longbooktabsstyles}
+
+The styles described in this section are all defined in the package
+\sty{glossary-longbooktabs}.
+
+Since these styles all use the
+\env{longtable} environment, they are governed by the same
+parameters as that environment. The \sty{glossary-longbooktabs}
+package automatically loads the \sty{glossary-long}
+(\sectionref{sec:longstyles})
+and \sty{glossary-longragged} (\sectionref{sec:longraggedstyles}) packages.  Note that
+these styles will only be available if you explicitly load
+\sty{glossary-longbooktabs}:
+\begin{verbatim}
+\usepackage{glossaries}
+\usepackage{glossary-longbooktabs}
+\end{verbatim}
+Note that you can't set these styles using the \pkgopt{style}
+package option since the styles aren't defined until after
+the \styfmt{glossaries} package has been loaded.
+
+These styles are similar to the
+\qt{header} styles in the \sty{glossary-long} and
+\sty{glossary-ragged} packages, but they add the rules
+provided by the \sty{booktabs} package, \ics{toprule}, \ics{midrule} and
+\ics{bottomrule}. Additionally these styles patch the
+\env{longtable} environment to check for instances of the group
+skip occurring at a page break. If you don't want this patch to
+affect any other use of \env{longtable} in your document, you can
+scope the effect by only setting the style through the
+\gloskey[printglossary]{style} key in the optional argument of
+\cs{printglossary}. (The \pkgopt{nogroupskip} package option 
+is checked by these styles.)
+
+Alternatively, you can restore the original \env{longtable}
+behaviour with:
+\begin{definition}[\DescribeMacro\glsrestoreLToutput]
+\cs{glsrestoreLToutput}
+\end{definition}
+For more information about the patch, see the documented code
+(\texttt{glossaries-code.pdf}).
+
+\begin{description}
+\item[\glostyle{long-booktabs}] This style is similar to
+the \glostyle{longheader} style but adds rules above and below the
+header (\cs{toprule} and \cs{midrule}) and inserts a rule at the
+bottom of the table (\cs{bottomrule}).
+
+\item[\glostyle{long3col-booktabs}] This style is similar to
+the \glostyle{long3colheader} style but adds rules as per
+\glostyle{long-booktabs}.
+
+\item[\glostyle{long4col-booktabs}] This style is similar to
+the \glostyle{long4colheader} style but adds rules as above.
+
+\item[\glostyle{altlong4col-booktabs}] This style is similar to
+the \glostyle{altlong4colheader} style but adds rules as above.
+
+\item[\glostyle{longragged-booktabs}] This style is similar to
+the \glostyle{longraggedheader} style but adds rules as above.
+
+\item[\glostyle{longragged3col-booktabs}] This style is similar to
+the \glostyle{longragged3colheader} style but adds rules as above.
+
+\item[\glostyle{altlongragged4col-booktabs}] This style is similar to
+the \glostyle{altlongragged4colheader} style but adds rules as above.
+
+\end{description}
 
 \subsection{Supertabular Styles}
 \label{sec:superstyles}
@@ -9445,7 +9923,7 @@ lines around it.
 \glostyle{super3col} but has a header row.
 
 \item[super3colheaderborder] The \glostyle{super3colheaderborder} style
-is like the \linebreak\glostyle{super3colheader} style but has horizontal and vertical
+is like the \glostyle{super3colheader} style but has horizontal and vertical
 lines around it.
 
 \item[super4col] The \glostyle{super4col} style is like 
@@ -9463,7 +9941,7 @@ lines around it.
 \glostyle{super4col} but has a header row.
 
 \item[super4colheaderborder] The \glostyle{super4colheaderborder} style
-is like the \linebreak\glostyle{super4colheader} style but has horizontal and vertical
+is like the \glostyle{super4colheader} style but has horizontal and vertical
 lines around it.
 
 \item[altsuper4col] The \glostyle{altsuper4col} style is like 
@@ -9930,7 +10408,7 @@ may contain \ics{delimN} (to delimit individual numbers) and/or
 multiple occurrences of 
 \ics{setentrycounter}\oarg{Hprefix}\marg{counter name}\meta{format cmd}\marg{number(s)}, but note
 that the entire number list is enclosed within the argument
-of \linebreak\ics{glossaryentrynumbers}. The user can redefine this to change
+of \ics{glossaryentrynumbers}. The user can redefine this to change
 the way the entire number list is formatted, regardless of 
 the glossary style. However the most common use of
 \ics{glossaryentrynumbers} is to provide a means of suppressing the
@@ -10128,6 +10606,9 @@ can be found in the documented code (glossaries-code.pdf).
 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 any unwanted spaces in it as they don't get stripped.
+(Discussed in more detail in
+\href{http://www.dickimaw-books.com/latex/admin/html/docsvlist.shtml#spacesinlists}{\S2.7.2 of \qt{\LaTeX\ for Administrative
+Work}}.)
 \end{important}
 
 \begin{definition}[\DescribeMacro{\forallglossaries}]
@@ -10499,7 +10980,8 @@ commands contained in the \meta{definition} must be protected.
 
 \chapter{Prefixes or Determiners}\label{sec:prefix}
 
-The \sty{glossaries-prefix} package provides 
+The \sty{glossaries-prefix} package that comes with the
+\styfmt{glossaries} package provides 
 additional keys that can be used as prefixes. For example, if you
 want to specify determiners (such
 as \qt{a}, \qt{an} or \qt{the}). The \styfmt{glossaries-prefix}
@@ -10795,7 +11277,7 @@ The sample file \samplefile{accsupp} illustrates the
 \sty{glossaries-accsupp} package.
 
 See \ifpdf section~\ref*{sec:code:accsupp} in \fi the documented code
-(\texttt{glossaries-code.pdf}) for further details. It is recommended
+(\texttt{glossaries-code.pdf}) for further details. I~recommend
 that you also read the \sty{accsupp} documentation. 
 
 \chapter{Troubleshooting}
-- 
cgit v1.2.3

