catoptions 0.2.7 (20nov11)

git-svn-id: svn://tug.org/texlive/trunk@24654 c570f23f-e606-0410-a88d-b1316a301751

3 files changed, 199 insertions, 134 deletions

diff --git a/Master/texmf-dist/doc/latex/catoptions/README b/Master/texmf-dist/doc/latex/catoptions/README
index 277392c5dce..9003c0f039d 100644
--- a/Master/texmf-dist/doc/latex/catoptions/README
+++ b/Master/texmf-dist/doc/latex/catoptions/README
@@ -11,17 +11,17 @@ to many TeX programming tools.
 
 LICENSE
 
-The 'catoptions' package may be distributed and/or modified under 
-the conditions of the LaTeX Project Public License, either 
-version 1.3 of this license or any later version. The latest 
-version of this license is in http://www.latex-project.org/lppl.txt 
-and version 1.3 or later is part of all distributions of LaTeX 
+The 'catoptions' package may be distributed and/or modified under
+the conditions of the LaTeX Project Public License, either
+version 1.3 of this license or any later version. The latest
+version of this license is in http://www.latex-project.org/lppl.txt
+and version 1.3 or later is part of all distributions of LaTeX
 version 2005/12/01 or later.
 
 The LPPL maintenance status of this software is 'author-maintained'.
 
 This software is provided 'as it is', without warranty of any kind,
-either expressed or implied, including, but not limited to, the 
+either expressed or implied, including, but not limited to, the
 implied warranties of merchantability and fitness for a particular
 purpose.
 
@@ -36,6 +36,6 @@ The catcode section of the 'catoptions' package is based on the
 
 VERSION
 
-Version 0.2.5, July 2011
+Version 0.2.7, November 2011
 
 
diff --git a/Master/texmf-dist/doc/latex/catoptions/catoptions-guide.pdf b/Master/texmf-dist/doc/latex/catoptions/catoptions-guide.pdf
index cb85c28fa4b..e3f6e07ba75 100644
--- a/Master/texmf-dist/doc/latex/catoptions/catoptions-guide.pdf
+++ b/Master/texmf-dist/doc/latex/catoptions/catoptions-guide.pdf
diff --git a/Master/texmf-dist/doc/latex/catoptions/catoptions-guide.tex b/Master/texmf-dist/doc/latex/catoptions/catoptions-guide.tex
index 5037a01e1bb..a2277633ab6 100644
--- a/Master/texmf-dist/doc/latex/catoptions/catoptions-guide.tex
+++ b/Master/texmf-dist/doc/latex/catoptions/catoptions-guide.tex
@@ -13,8 +13,10 @@
 \hfuzz1pt
 \makeatletter
 \WrapQuotes
-\def\xdecs{\fx{\XDeclareOption}\RedStar\sspace}
+\def\xdecs{\fx{\XDeclareOption}\Redstar\sspace}
 \makeindex
+\useshortdoccmds
+\let\footnote\ltsfootnote
 
 \begin{document}
 
@@ -23,10 +25,10 @@
 \titlenotes[t1,t2]{%
   The package is available at \url{\titleurltext}.\sep
   This manual doesn't, as yet, explain all the currently available features and commands of
-  the \pkg'{catoptions}. This manual continues to evolve, but many of the available functions will appear in the user guide of the forthcoming \pkg'{ltxtools}.
+  the \pkg'{catoptions}. This manual continues to evolve, but many of the available functions will appear in the forthcoming user guide of the \pkg'{ltxtools}.
 }
-\version{0.2.6}
-\titleurl{http://www.ctan.org/tex-archive/macros/latex/contrib/catoptions/}
+\version{0.2.7}
+\titleurl{http://mirror.ctan.org/macros/latex/contrib/catoptions/}
 \author{Ahmed Musa \Email{amusa22@gmail.com}\\Preston, Lancashire, UK}
 
 \def\abstractname{\textsf{Summary}}
@@ -60,17 +62,17 @@
 
 \docsection(sec:packageloading){Loading the package}
 
-\deffnote{1}{%
-  The user interfaces of \ffx'{\XDeclareOption, \XExecuteOptions, \XProcessOptions} are similar to those of \hhx'{\DeclareOption, \ExecuteOptions, \ProcessOptions} but they aren't the same. See \amref{sec:options-parse}.
+\deffootnote{1}{%
+  The user interfaces of \ffx'{\XDeclareOption, \XExecuteOptions, \XProcessOptions} are similar to those of \hhx'{\DeclareOption, \ExecuteOptions, \ProcessOptions} but they aren't the same. See \sref{sec:options-parse}.
 }
-The \pkg'{catoptions} can be loaded in class and style files and in documents (before or after \hx{\documentclass}) with the options described in \amref{sec:pkg-options}. If the package is loaded before \hx{\documentclass}, it will, by default, use the options parser of the package in place of \latex's options parsing scheme (namely, the more robust commands \ffx'{\XDeclareOption, \XExecuteOptions, \XProcessOptions} in place of \latex's native commands \hhx'{\DeclareOption, \ExecuteOptions, \ProcessOptions})\usefnote{1}. In that case, the legacy commands \hhx'{\DeclareOption, \ExecuteOptions, \ProcessOptions} are aliased to \ffx'{\XDeclareOption, \XExecuteOptions, \XProcessOptions}, respectively. The latter set of commands do immediately recognize that they have to deal with option functions that are based on the kernel's syntax and semantics. This allows expandable options and option values (together with options with spaces in their names) to be passed via \hx{\documentclass}---if \pkg{catoptions} is loaded before \hx{\documentclass}. This also implies that existing packages can use the options parsing scheme of \pkg'{catoptions} without modifying the packages.
+The \pkg'{catoptions} can be loaded in class and style files and in documents (before or after \hx{\documentclass}) with the options described in \sref{sec:pkg-options}. If the package is loaded before \hx{\documentclass}, it will, by default, use the options parser of the package in place of \latex's options parsing scheme (namely, the more robust commands \ffx'{\XDeclareOption, \XExecuteOptions, \XProcessOptions} in place of \latex's native commands \hhx'{\DeclareOption, \ExecuteOptions, \ProcessOptions})\usefootnote{1}. In that case, the legacy commands \hhx'{\DeclareOption, \ExecuteOptions, \ProcessOptions} are aliased to \ffx'{\XDeclareOption, \XExecuteOptions, \XProcessOptions}, respectively. The latter set of commands do immediately recognize that they have to deal with option functions that are based on the kernel's syntax and semantics. This allows expandable options and option values (together with options with spaces in their names) to be passed via \hx{\documentclass}---if \pkg{catoptions} is loaded before \hx{\documentclass}. This also implies that existing packages can use the options parsing scheme of \pkg'{catoptions} without modifying the packages.
 
-However, if after loading \pkg'{catoptions} before \hx{\documentclass} the user still wants to use the legacy commands \hhx'{\DeclareOption, \ExecuteOptions, \ProcessOptions}, the package option \fx{usepox} (see \amref{sec:pkg-options}) can be toggled to \texttt{false}. In this case, option values can't be passed via \hx{\documentclass}. More precisely, option values passed via \hx{\documentclass} are stripped off internally by \pkg{catoptions} so that they may be processed by \hx{\ProcessOptions}.
+However, if after loading \pkg'{catoptions} before \hx{\documentclass} the user still wants to use the legacy commands \hhx'{\DeclareOption, \ExecuteOptions, \ProcessOptions}, the package option \fx{usepox} (see \sref{sec:pkg-options}) can be toggled to \texttt{false}. In this case, option values can't be passed via \hx{\documentclass}. More precisely, option values passed via \hx{\documentclass} are stripped off internally by \pkg{catoptions} so that they may be processed by \hx{\ProcessOptions}.
 
 
 \docsection(sec:pkg-options)<Package options>{Package options}
 
-\lletter{T}{he} \pkg'{catoptions} has the options shown in \amref{tab:pkgoptions}. The boolean option \fxim{verbose} instructs the package to enter information onto the log file when some events happen  (\eg, when commands are redefined by means of, say, the command \fx{\robust@redef}, which has the same syntax with  \tex's legacy \hx{\def}; and when an option from the same family is multiply submitted to, say, \fx{\XExecuteOptions}). This option may be used in the future to provide debugging features for the package.
+\lletter{T}{he} \pkg'{catoptions} has the options shown in \sref{tab:pkgoptions}. The boolean option \fxim{verbose} instructs the package to enter information onto the log file when some events happen  (\eg, when commands are redefined by means of, say, the command \fx{\robust@redef}, which has the same syntax with  \tex's legacy \hx{\def}; and when an option from the same family is multiply submitted to, say, \fx{\XExecuteOptions}). This option may be used in the future to provide debugging features for the package.
 
 \extrarowheight=2pt
 \arrayrulecolor{yellow}
@@ -91,7 +93,7 @@ However, if after loading \pkg'{catoptions} before \hx{\documentclass} the user
 \fx{usepox} & \hx{true} & The boolean switch that determines if the options parser of \pkgg{catoptions} should be used for all options processing of packages loaded after \hx{\documentclass} even if those packages are based on \usecsn{latex2e}'s native options processing scheme.\\\hline
 \end{tabularx}
 
-As noted in \amref{sec:packageloading}, if the \pkg'{catoptions} is loaded before \hx{\documentclass} it will invariably use the options processing mechanism of the package. In that case (of the package being loaded before \hx{\documentclass}), the option \fxim{usepox} directs the package to use the \pkg{catoptions}'s options processing scheme for all the packages loaded after \hx{\documentclass}, instead of \latex's native options parsing procedures. This allows \pkg{catoptions}'s options parsing scheme to be used for existing packages loaded after \hx{\documentclass} without modifying the packages.
+As noted in \sref{sec:packageloading}, if the \pkg'{catoptions} is loaded before \hx{\documentclass} it will invariably use the options processing mechanism of the package. In that case (of the package being loaded before \hx{\documentclass}), the option \fxim{usepox} directs the package to use the \pkg{catoptions}'s options processing scheme for all the packages loaded after \hx{\documentclass}, instead of \latex's native options parsing procedures. This allows \pkg{catoptions}'s options parsing scheme to be used for existing packages loaded after \hx{\documentclass} without modifying the packages.
 
 Assuming that the options \quotedtt{textstyle} and \quotedtt{name} belong to an existing package (say, \quotedtt{mypackage}) to be loaded later, then the following example demonstrates one feature of the \pkg'{catoptions}, in the case in which the package is loaded before \hx{\documentclass}:
 
@@ -132,7 +134,7 @@ After issuing the command \fx{\GetCurrentCatcodeSubset}, you can do
 \finish{example}
 \fxim*{\currentcatcodesubset}
 
-to see the current catcode setup. The command \fx{\cptfutureletsetup} is described in \amref{sec:future-letting}.
+to see the current catcode setup. The command \fx{\cptfutureletsetup} is described in \sref{sec:future-letting}.
 
 \start{example}[\UseNormalCatcodes]
 \ProvidesPackage{mypackage}[2011/01/16 v0.01]
@@ -145,7 +147,7 @@ to see the current catcode setup. The command \fx{\cptfutureletsetup} is describ
 \dummyfxi*{\UseNormalCatcodes}
 
 
-\docsection(sec:future-letting){Future-letting of \headqtd{other} characters}
+\docsection(sec:future-letting){Future-letting of \headquoted{other} characters}
 
 The command \fx{\cptfutureletsetup} defines canonical control sequences to represent the  following characters:
 
@@ -299,6 +301,9 @@ The commands \ffx'{\mypack@error,\mypack@info} can be used as follows:
 
 The interfaces of the options processing commands are as follows, which, apart from the optional family \ang{fam} and default value \ang{default}, are syntactically similar to the corresponding native \latex commands. The optional family name is useful for defining unique options that stand only a remote chance of being mixed up with options of other families. And the optional default value is handy when the user doesn't supply a value for an option: no errors are produced in this case. Existing packages can be processed with these commands without any modifications to those packages. In fact, we have run many existing packages on the bases of these commands (by letting \latex's \hhx'{\DeclareOption,\ExecuteOptions,\ProcessOptions} to these commands), without encountering difficulties.
 
+
+\docsubsection(sec:ord-options){Ordinary options}
+
 \start{newmacro}[\XDeclareOption]
 \XDeclareOption<|nang(fam)>{|nang(opt)}[|nang(default)]{|nang(fn1)}|label(mac:xdec:a)
 \XDeclareOption|*<|nang(fam)>{|nang(fn2)}|label(mac:xdec:b)
@@ -314,11 +319,11 @@ The \unstform of the macro \fx{\XDeclareOption} declares an option that can be u
 \XDeclareOption{leftmargin}[.5\hsize]{\setlength\leftmargin{#1}}|xwmlabel(mac:leftmargin)
 \finish{example}
 
-\deffnote{2}{%
+\deffootnote{2}{%
   The commands \ffx'{\XDeclareBooleanOption, \XDeclareBooleanOptions, \XDeclareBiBooleanOptions} allow the user to define new boolean options without the need to first initialize the booleans with \hx{\newif} or \fx{\cptnewbool} as seen here.
 }
 
-The user would have noticed the use \fx{\cptnewbool} in the above example\usefnote{2}. The options \ffx'{mybool,leftmargin} could then be called via any of the following statements:
+The user would have noticed the use \fx{\cptnewbool} in the above example\usefootnote{2}. The options \ffx'{mybool,leftmargin} could then be called via any of the following statements:
 
 \start{example}[\XDeclareOption]
 |com(Inside class or package files:)
@@ -329,76 +334,12 @@ The user would have noticed the use \fx{\cptnewbool} in the above example\usefno
 \documentclass[mybool,leftmargin=20pt]{myclass}
 \finish{example}
 
-The \stform of the macro \fx{\XDeclareOption} can be used to process unknown options. It is similar to \latex's \hx{\DeclareOption}\RedStar, but it has additional features. You can deploy \hx{\CurrentOption} within the \ang{fn} of this macro to access the option name and value for which the option is unknown. These values (possibly including an option) could, for example, be passed on to another class or package or could be used as an extra class or package option that, for instance, specifies a style that should be loaded. Moreover, you can use \fx{#1}, \fx{#2} and \fx{#3} within \ang{fn} to refer to the current family, current option (without its value), and current value, respectively.
+The \stform of the macro \fx{\XDeclareOption} can be used to process unknown options. It is similar to \latex's \hx{\DeclareOption}\Redstar, but it has additional features. You can deploy \hx{\CurrentOption} within the \ang{fn} of this macro to access the option name and value for which the option is unknown. These values (possibly including an option) could, for example, be passed on to another class or package or could be used as an extra class or package option that, for instance, specifies a style that should be loaded. Moreover, you can use \fx{#1}, \fx{#2} and \fx{#3} within \ang{fn} to refer to the current family, current option (without its value), and current value, respectively.
 
-\Note This note refers to macro lines \ref{mac:xdec:a} and \ref{mac:xdec:b}. In \fx{\XDeclareOption}, the current option value can be accessed by using \fx{#1} in \ang{fn1}. However, in \xdecs the current family name is accessed as \fx{#1}, the option name is available in \fx{#2}, and the current option value can be accessed with \fx{#3} (all in \ang{fn2}). These differences are important.
-
-\start{newmacro}[\XUnknownOptionHandler]
-\XUnknownOptionHandler<|nang(fams)>[|nang(na)]{|nang(handler)}
-\finish{newmacro}
-\fxim*{\XUnknownOptionHandler}
+\ltsnote This note refers to macro lines \ref{mac:xdec:a} and \ref{mac:xdec:b}. In \fx{\XDeclareOption}, the current option value can be accessed by using \fx{#1} in \ang{fn1}. However, in \xdecs the current family name is accessed as \fx{#1}, the option name is available in \fx{#2}, and the current option value can be accessed with \fx{#3} (all in \ang{fn2}). These differences are important.
 
-\deffnote{3}{%
-  Declaring a default handler for each unknown option is, of course, inefficient.
-  We have, therefore, provided provisions for declaring such handers for only families of options.
-}
-The command \fx{\XUnknownOptionHandler} can be used in place of \xdecs to specify default action(s) for options undefined in any family in \ang{fams}\usefnote{3}. \ang{handler} refers to the default function that should be executed if undeclared options are called from families \ang{fams} by the user. \hx{\CurrentOption} can be deployed within \ang{handler} to access the option name (coupled with its current value) for which the option name is unknown. As mentioned above in the case of \xdecs, you can use \fx{#1}, \fx{#2} and \fx{#3} within \ang{handler} to access the current family, current option (uncoupled from its current value), and current value, respectively. \ang{na} is the list of options for which \ang{handler} shouldn't apply; for these options, the kernel's unknown option handler (\ie, \hx{\default@ds}) would apply.
 
-If the \ang{handler} contains the special literal form \fx{define/.code=} as in
-
-\start{example}[Unknown option handler]
-|A(fn1) |R(define/.code=)|nang(callback)|R(/.end) |A(fn2)|label(mac:handler)
-\finish{example}
-\fxim*{define/.code}
-
-then each unknown option in families \ang{fams} will be momentarily defined and executed with the option function \ang{callback}. The family of the new option will be \fx{\cpt@currfam} (the prevailing family name); its default value will be \fx{\cpt@currval} (the value specified by the user for the unknown option); and its macro function will be the above-indicated \ang{callback}. Again, you can use \fx{#1}, \fx{#2} and \fx{#3} in \ang{handler} to refer to the current option family, option name, and option value, respectively.
-
-\Note Functions \ang{fn1} and \ang{fn2} on \amref{mac:handler} will be executed for each unknown function in families \ang{fams}, but (unlike \ang{callback}) will not be used in defining unknown options of \ang{fams}.
-
-If the value given for the unknown option is \hx{true} or \hx{false}, the new (\ie, undeclared) option will be defined as a boolean option with macro prefix \quotedFx{\@currname @}; otherwise it will be defined as a command option with macro prefix \quotedfx{cmd\@currname @}. (See the descriptions of the commands \ffx'{\XDeclareCommandOption,\XDeclareBooleanOption} for the meaning of \quoted{macro prefix}.) It should be noted that the token \quoted{define} in the above syntax is not escaped, and that the token \fx{/.end} is mandatory. If \ang{callback} contains these literal forms, they have to be enclosed in curly braces.
-
-The following example, among other things, produces a warning when the user supplies an option that was not previously declared:
-
-\zapname
-\start{example}[\XDeclareOption*]
-\XDeclareOption|*<mypackage>{%
-  |com(Unknown options will not be defined automatically here:)
-  \PackageWarningNoLine{mypackage}{Unknown option `\CurrentOption' ignored}%
-  |com(Current option family:)
-  \def\currfamily{#1}%
-  |com(Current option without the given value:)
-  \def\curroption{#2}%
-  |com(User-supplied value of current option:)
-  \def\currvalue{#3}%
-  |com(User defined function:)
-  \def\mymacro##1{\do@a{#2=#3}\do@b{##1}%
-  |com(`\CurrentOption' isn't equivalent to `#2=#3' because non-active)
-  |com(spaces around `#3' would have been removed.)
-}
-\finish{example}
-
-And the following example passes undeclared options to \hx{article} class:
-
-\zapname
-\start{example}[\XDeclareOption*]
-\XDeclareOption|*{\PassOptionsToClass{#2=#3}{article}}
-\finish{example}
-
-The following example instructs \fx{\XProcessOptions} to define all unknown keys on the fly with the callback shown.
-
-\start{example}[\XUnknownOptionHandler]
-\XUnknownOptionHandler<mypackage>{%
-  |com(Unknown options will be defined automatically here with the)
-  |com(indicated code:)
-  |R(define/.code=)
-  \def\x##1{##1\relax `option #2 = value #3' in family `#1'}%
-  |R(/.end)
-  |com(The following will be executed for each unknown option of the)
-  |com(given family, but will not be a `callback' for unknown options:)
-  \PackageWarningNoLine{mypackage}{Unknown option `#2' of family
-    `#1' defined on the fly}%
-}
-\finish{example}
+\docsubsection(sec:external-options){External options}
 
 If no default family handler has been provided by the user (through the macro \xdecs or \fx{\XUnknownOptionHandler}) for the family of an undeclared option, and the option doesn't appear in the list \fx{\XExternalOptions}, then that option will be logged (\ie, entered in the transcript file) as undefined at the end of the document. By default, \fx{\XExternalOptions} contains all \hhx'{article,report,memoir} class options. The user can update the \fx{\XExternalOptions} list by means of the following commands:
 
@@ -410,7 +351,7 @@ If no default family handler has been provided by the user (through the macro \x
 
 where \ang{opts} are the comma-separated option names to be added to, or removed from, the list.
 
-\Note Unknown options that appear in \fx{\XExternalOptions} list will not have their \ang{fn1}, \ang{fn2} and \ang{callback} of the default family handler (see \amref{mac:handler}) executed unless they contain one of the commands \hhx'{\PassOptionsToClass, \PassOptionsToPackage}.
+\ltsnote Unknown options that appear in \fx{\XExternalOptions} list will not have their \ang{fn1}, \ang{fn2} and \ang{callback} of the default family handler (see \sref{mac:handler}) executed unless they contain one of the commands \hhx'{\PassOptionsToClass, \PassOptionsToPackage}.
 
 \start{newmacro}[\XDeclareOptions]
 \XDeclareOptions<|nang(fam)>{|nang(opts)}[|nang(default)]{|nang(fn)}
@@ -419,37 +360,15 @@ where \ang{opts} are the comma-separated option names to be added to, or removed
 
 The command \fx{\XDeclareOptions} is similar to \fx{\XDeclareOption} but, instead of declaring just one option, it declares all the options in the comma-separated list \ang{opts}. Each option in the list \ang{opts} is defined with the same family \ang{fam}, default value \ang{default}, and function \ang{fn}. The command \fx{\XDeclareOptions} can be used to save tokens when it is required to declare a set of options with identical attributes.
 
-\start+{newmacro}[\XDeclareInvalidOption,\XDeclareInvalidOptions]
-\XDeclareInvalidOption<|nang(fams)>{|nang(opt)}
-\XDeclareInvalidOptions<|nang(fams)>{|nang(opts)}
-\finish{newmacro}
-\fxim*{\XDeclareInvalidOption,\XDeclareInvalidOptions}
-
-The commands \ffx'{\XDeclareInvalidOption,\XDeclareInvalidOptions} declare the given list \ang{opts} as invalid or inadmissible within the specified families \ang{fams}. A user submitting the invalid option will receive the message the option author has specified for the given family via the command \fx{\XInvalidOptionHandler}. Package and class authors don't necessarily have to provide invalid-option handler for each or any family (of their options) via the macro \fx{\XInvalidOptionHandler}: the package provides a default error message for invoked invalid options when the author of the option hasn't defined an invalid-option handler.
-
-\start{newmacro}[\XInvalidOptionHandler]
-\XInvalidOptionHandler<|nang(fams)>{|nang(handler)}
-\finish{newmacro}
-\fxim*{\XInvalidOptionHandler}
-
-The command \fx{\XInvalidOptionHandler} defines, for each family \ang{fam} in \ang{fams}, a one-parameter function, which, when specified, is used to replace the macros of options in the family \ang{fam} when the options appear in \ang{opts} list of \fx{\XDeclareInvalidOptions}.
-
-\start{example}[\XInvalidOptionHandler]
-\XInvalidOptionHandler<fama,famb>{%
-  \@latex@error{Invalid or null option `\CurrentOption'}%
-    {I have encountered an invalid option `\CurrentOption':
-    Your package author has set this option as inadmissible.}%
-}
-\XDeclareInvalidOptions<fama,famb>{opta,optb}
-\finish{example}
 
+\docsubsection(sec:cmd-options){Command options}
 
 \start{newmacro}[\XDeclareCommandOption]
 \XDeclareCommandOption<|nang(fam)>{|nang(opt)}[|nang(default)]|(|nang(pref)|){|nang(fn)}
 \finish{newmacro}
 \fxim*{\XDeclareCommandOption}
 
-The command \fx{\XDeclareCommandOption} will, apart from declaring the option \ang{opt}, also create a macro \fnl*'\bs{pref,opt} to hold the user-supplied value of the option. The macro so created can be used in \ang{fn} or in any other place. The default value of the optional \ang{pref} is \quotedFx{\@currname @} prefixed with the letters \fx{cmd}.
+The command \fx{\XDeclareCommandOption} will, apart from declaring the option \ang{opt}, also create a macro \fnl*'\bs{pref,opt} to hold the user-supplied value of the option. The macro so created can be used in \ang{fn} or in any other place. The default value of the optional \ang{pref} is \quotedfx{\@currname @} prefixed with the letters \fx{cmd}.
 
 \start{newmacro}[\XDeclareCommandOptions]
 \XDeclareCommandOptions<|nang(fam)>{|nang(opts)}[|nang(default)]|(|nang(pref)|){|nang(fn)}
@@ -459,12 +378,14 @@ The command \fx{\XDeclareCommandOption} will, apart from declaring the option \a
 The command \fx{\XDeclareCommandOptions} is similar to \fx{\XDeclareCommandOption} but, instead of declaring just one option, it declares all the options in the comma-separated list \ang{opts}. Each option in the list \ang{opts} is defined with the same family \ang{fam}, default value \ang{default}, and function \ang{fn}.
 
 
+\docsubsection(sec:bool-options){Boolean options}
+
 \start{newmacro}[\XDeclareBooleanOption]
 \XDeclareBooleanOption<|nang(fam)>{|nang(opt)}[|nang(default)]|(|nang(pref)|){|nang(fn)}
 \finish{newmacro}
 \fxim*{\XDeclareBooleanOption}
 
-The command \fx{\XDeclareBooleanOption} will, apart from declaring the option \ang{opt}, also create a boolean \fnl*'{\bs if}{pref,opt}. It will automatically toggle this boolean (to \hx{true} or \hx{false}) when the option is set and the input is valid, depending on the user-supplied value of the option. The macros so created can be used in \ang{fn} or in any other place. The default value of the optional \ang{pref} is \quotedFx{\@currname @} with no additional prefix. Only \hx{true} or \hx{false} may be submitted as the value of a boolean option.
+The command \fx{\XDeclareBooleanOption} will, apart from declaring the option \ang{opt}, also create a boolean \fnl*'{\bs if}{pref,opt}. It will automatically toggle this boolean (to \hx{true} or \hx{false}) when the option is set and the input is valid, depending on the user-supplied value of the option. The macros so created can be used in \ang{fn} or in any other place. The default value of the optional \ang{pref} is \quotedfx{\@currname @} with no additional prefix. Only \hx{true} or \hx{false} may be submitted as the value of a boolean option.
 
 \start{newmacro}[\XDeclareBooleanOptions]
 \XDeclareBooleanOptions<|nang(fam)>{|nang(opts)}[|nang(default)]|(|nang(pref)|){|nang(fn)}
@@ -474,6 +395,8 @@ The command \fx{\XDeclareBooleanOption} will, apart from declaring the option \a
 The command \fx{\XDeclareBooleanOptions} is similar to \fx{\XDeclareBooleanOption} but, instead of declaring just one option, it declares all the options in the comma-separated list \ang{opts}. Again, each option in the list \ang{opts} is defined with the same family \ang{fam}, default value \ang{default}, and function \ang{fn}.
 
 
+\docsubsubsection(sec:bibool-options){Biboolean options}
+
 \start{newmacro}[\XDeclareBiBooleanOptions]
 \XDeclareBiBooleanOptions<|A(fam)>{|A(opt1),|A(opt2)}[|A(default)]|(|A(pref)|){|A(fn1)}{|A(fn2)}
 \finish{newmacro}
@@ -482,6 +405,8 @@ The command \fx{\XDeclareBooleanOptions} is similar to \fx{\XDeclareBooleanOptio
 The command \fx{\XDeclareBiBooleanOptions} declares the two options \ang{opt1} and \ang{opt2} in the comma-separated list of options. Again, each of the two declared options is defined with the same family \ang{fam} and default value \ang{default}, but separate functions \ang{fn1} and \ang{fn2}. A distinguishing characteristic of bi-boolean options is that when one option is \hx{true}, the partner option is automatically turned \hx{false}, and vice versa.
 
 
+\docsubsection(sec:switch-options){Switch options}
+
 \start{newmacro}[\XDeclareSwitchOption]
 \XDeclareSwitchOption<|nang(fam)>{|nang(opt)}[|nang(default)]|(|nang(pref)|){|nang(fn)}
 \finish{newmacro}
@@ -495,10 +420,10 @@ In the parlance of the \pkg'{catoptions,ltxtools}, a switch can assume only one
 \finish{newmacro}
 \fxim*{\ifswitchTF,\ifswitchFT}
 
-\deffnote{4}{%
+\deffootnote{4}{%
   Because of the need to do, \eg, \fx{\let\swa\cpttrue} and \hx{\if}\unskip\fx{\swa} for any given switch \fx{\swa}, switches, unlike toggles, don't have their own separate namespace and it is all too easy to redefine an existing switch.
 }
-Note that here \ang{switch} has no escape character, unless it evaluates to a switch name. So, after defining \fx{\def\swa{00}} we could then do \fx{\ifswitchTF{swa}{true}{false}}. It is somewhat risky to introduce new switches with \hx{\def} or \hx{\let}\usefnote{4}. It is advisable to always use \fx{\newswitch} instead. It has the syntax
+Note that here \ang{switch} has no escape character, unless it evaluates to a switch name. So, after defining \fx{\def\swa{00}} we could then do \fx{\ifswitchTF{swa}{true}{false}}. It is somewhat risky to introduce new switches with \hx{\def} or \hx{\let}\usefootnote{4}. It is advisable to always use \fx{\newswitch} instead. It has the syntax
 
 \start{newmacro}[\newswitch]
 \newswitch{|nang(switch)}[|nang(state)]
@@ -519,7 +444,7 @@ It is possible to toggle the state of a switch by simply using the commands:
 \finish{newmacro}
 \fxim*{\setswitchtrue,\setswitchfalse}
 
-The command \fx{\XDeclareSwitchOption} will, apart from declaring the option \ang{opt}, also create a switch \fnl*'\bs{pref,opt}. It will automatically toggle this switch to \hx{true} (equivalent to \fx{00}) or \hx{false} (equivalent to \fx{01}) when the option is set and the input is valid, depending on the user-supplied value of the option. The macros so created can be used in \ang{fn} or in any other place. The default value of the optional \ang{pref} is again \quotedFx{\@currname @} with no additional prefix. Only \hx{true} or \hx{false} may be submitted as the value of a switch option.
+The command \fx{\XDeclareSwitchOption} will, apart from declaring the option \ang{opt}, also create a switch \fnl*'\bs{pref,opt}. It will automatically toggle this switch to \hx{true} (equivalent to \fx{00}) or \hx{false} (equivalent to \fx{01}) when the option is set and the input is valid, depending on the user-supplied value of the option. The macros so created can be used in \ang{fn} or in any other place. The default value of the optional \ang{pref} is again \quotedfx{\@currname @} with no additional prefix. Only \hx{true} or \hx{false} may be submitted as the value of a switch option.
 
 \start{newmacro}[\XDeclareSwitchOptions]
 \XDeclareSwitchOptions<|nang(fam)>{|nang(opts)}[|nang(default)]|(|nang(pref)|){|nang(fn)}
@@ -529,6 +454,105 @@ The command \fx{\XDeclareSwitchOption} will, apart from declaring the option \an
 The command \fx{\XDeclareSwitchOptions} is similar to \fx{\XDeclareSwitchOption} but, instead of declaring just one option, it declares all the options in the comma-separated list \ang{opts}. Again, each option in the list \ang{opts} is defined with the same family \ang{fam}, default value \ang{default}, and function \ang{fn}.
 
 
+\docsubsection(sec:unknown-options){Unknown option handler}
+
+\start{newmacro}[\XUnknownOptionHandler]
+\XUnknownOptionHandler<|nang(fams)>[|nang(na)]{|nang(handler)}
+\finish{newmacro}
+\fxim*{\XUnknownOptionHandler}
+
+\deffootnote{3}{%
+  Declaring a default handler for each unknown option is, of course, inefficient.
+  We have, therefore, provided provisions for declaring such handers for only families of options.
+}
+The command \fx{\XUnknownOptionHandler} can be used in place of \xdecs to specify default action(s) for options undefined in any family in \ang{fams}\usefootnote{3}. \ang{handler} refers to the default function that should be executed if undeclared options are called from families \ang{fams} by the user. \hx{\CurrentOption} can be deployed within \ang{handler} to access the option name (coupled with its current value) for which the option name is unknown. As mentioned above in the case of \xdecs, you can use \fx{#1}, \fx{#2} and \fx{#3} within \ang{handler} to access the current family, current option (uncoupled from its current value), and current value, respectively. \ang{na} is the list of options for which \ang{handler} shouldn't apply; for these options, the kernel's unknown option handler (\ie, \hx{\default@ds}) would apply.
+
+If the \ang{handler} contains the special literal form \fx{define/.code=} as in
+
+\start{example}[Unknown option handler]
+|A(fn1) |R(define/.code=)|nang(callback)|R(/.end) |A(fn2)|label(mac:handler)
+\finish{example}
+\fxim*{define/.code}
+
+then each unknown option in families \ang{fams} will be momentarily defined and executed with the option function \ang{callback}. The family of the new option will be \fx{\cpt@currfam} (the prevailing family name); its default value will be \fx{\cpt@currval} (the value specified by the user for the unknown option); and its macro function will be the above-indicated \ang{callback}. Again, you can use \fx{#1}, \fx{#2} and \fx{#3} in \ang{handler} to refer to the current option family, option name, and option value, respectively.
+
+\ltsnote Functions \ang{fn1} and \ang{fn2} on \sref{mac:handler} will be executed for each unknown function in families \ang{fams}, but (unlike \ang{callback}) will not be used in defining unknown options of \ang{fams}.
+
+If the value given for the unknown option is \hx{true} or \hx{false}, the new (\ie, undeclared) option will be defined as a boolean option with macro prefix \quotedfx{\@currname @}; otherwise it will be defined as a command option with macro prefix \quotedfx{cmd\@currname @}. (See the descriptions of the commands \ffx'{\XDeclareCommandOption,\XDeclareBooleanOption} for the meaning of \quoted{macro prefix}.) It should be noted that the token \quoted{define} in the above syntax is not escaped, and that the token \fx{/.end} is mandatory. If \ang{callback} contains these literal forms, they have to be enclosed in curly braces.
+
+The following example, among other things, produces a warning when the user supplies an option that was not previously declared:
+
+\amvzapname
+\start{example}[\XDeclareOption*]
+\XDeclareOption|*<mypackage>{%
+  |com(Unknown options will not be defined automatically here:)
+  \PackageWarningNoLine{mypackage}{Unknown option `\CurrentOption' ignored}%
+  |com(Current option family:)
+  \def\currfamily{#1}%
+  |com(Current option without the given value:)
+  \def\curroption{#2}%
+  |com(User-supplied value of current option:)
+  \def\currvalue{#3}%
+  |com(User defined function:)
+  \def\mymacro##1{\do@a{#2=#3}\do@b{##1}%
+  |com(`\CurrentOption' isn't equivalent to `#2=#3' because non-active)
+  |com(spaces around `#3' would have been removed.)
+}
+\finish{example}
+
+And the following example passes undeclared options to \hx{article} class:
+
+\amvzapname
+\start{example}[\XDeclareOption*]
+\XDeclareOption|*{\PassOptionsToClass{#2=#3}{article}}
+\finish{example}
+
+The following example instructs \fx{\XProcessOptions} to define all unknown keys on the fly with the callback shown.
+
+\start{example}[\XUnknownOptionHandler]
+\XUnknownOptionHandler<mypackage>{%
+  |com(Unknown options will be defined automatically here with the)
+  |com(indicated code:)
+  |R(define/.code=)
+  \def\x##1{##1\relax `option #2 = value #3' in family `#1'}%
+  |R(/.end)
+  |com(The following will be executed for each unknown option of the)
+  |com(given family, but will not be a `callback' for unknown options:)
+  \PackageWarningNoLine{mypackage}{Unknown option `#2' of family
+    `#1' defined on the fly}%
+}
+\finish{example}
+
+
+\docsubsection(sec:invalid-options){Invalid options}
+
+\start+{newmacro}[\XDeclareInvalidOption,\XDeclareInvalidOptions]
+\XDeclareInvalidOption<|nang(fams)>{|nang(opt)}
+\XDeclareInvalidOptions<|nang(fams)>{|nang(opts)}
+\finish{newmacro}
+\fxim*{\XDeclareInvalidOption,\XDeclareInvalidOptions}
+
+The commands \ffx'{\XDeclareInvalidOption,\XDeclareInvalidOptions} declare the given list \ang{opts} as invalid or inadmissible within the specified families \ang{fams}. A user submitting the invalid option will receive the message the option author has specified for the given family via the command \fx{\XInvalidOptionHandler}. Package and class authors don't necessarily have to provide invalid-option handler for each or any family (of their options) via the macro \fx{\XInvalidOptionHandler}: the package provides a default error message for invoked invalid options when the author of the option hasn't defined an invalid-option handler.
+
+\start{newmacro}[\XInvalidOptionHandler]
+\XInvalidOptionHandler<|nang(fams)>{|nang(handler)}
+\finish{newmacro}
+\fxim*{\XInvalidOptionHandler}
+
+The command \fx{\XInvalidOptionHandler} defines, for each family \ang{fam} in \ang{fams}, a one-parameter function, which, when specified, is used to replace the macros of options in the family \ang{fam} when the options appear in \ang{opts} list of \fx{\XDeclareInvalidOptions}.
+
+\start{example}[\XInvalidOptionHandler]
+\XInvalidOptionHandler<fama,famb>{%
+  \@latex@error{Invalid or null option `\CurrentOption'}%
+    {I have encountered an invalid option `\CurrentOption':
+    Your package author has set this option as inadmissible.}%
+}
+\XDeclareInvalidOptions<fama,famb>{opta,optb}
+\finish{example}
+
+
+\docsubsection(sec:exec-options){Executing options}
+
 \start{newmacro}[\XExecuteOptions]
 \XExecuteOptions<|nang(fams)>{|nang(opts)}[|nang(na)]
 \finish{newmacro}
@@ -543,7 +567,10 @@ This macro will not use the declaration done by \xdecs when undeclared options a
 \finish{example}
 \dummyfxi*{\XExecuteOptions}
 
-This initializes the option \hx{\leftmargin} of \amref{mac:leftmargin} to 0pt.
+This initializes the option \hx{\leftmargin} of \sref{mac:leftmargin} to 0pt.
+
+
+\docsubsection(sec:process-options){Processing options}
 
 \start{newmacro}[\XProcessOptions]
 \XProcessOptions<|nang(fams)>[|nang(na)]
@@ -553,9 +580,9 @@ This initializes the option \hx{\leftmargin} of \amref{mac:leftmargin} to 0pt.
 
 The re-entrant \fx{\XProcessOptions} macro processes the options and values passed by the user to the class or package. The optional argument \ang{fams} can be used to specify the \emph{families} that have been used to define the options. The optional argument \ang{na} can be used to specify options that should be ignored, \ie, not processed. When used in a class file, this macro will ignore unknown options. This allows the user to use global options in the \hx{\documentclass} command which could be claimed by packages loaded later.
 
-The \stform of \fx{\XProcessOptions} works like the \unstform except that the former also copies user input from the \hx{\documentclass} command and processes the options in the order specified by the \hx{\documentclass}. When the user specifies an option in the \hx{\documentclass} which also exists in the local family (or families) of the package calling \fx{\XProcessOptions}\RedStar, the local option will be set as well. In this case, \fx{#1} in \fx{\XDeclareOption} macro will contain the user-value entered in the \hx{\documentclass} (or \fx{\usepackage} or \fx{\RequirePackage}) command for this option. First the global options from \hx{\documentclass} will set local options and afterwards the local options (specified via \hhx'{\usepackage, \RequirePackage, \LoadClass} or similar commands) will set local options, which could overwrite the global options set earlier, depending on how the options sections are organized. The macro \fx{\XProcessOptions}\RedStar reduces to \fx{\XProcessOptions} only when issued from the class which forms the document class for the file at hand (to avoid setting the same options twice), but not for classes loaded later using, for instance, \hx{\LoadClass}. Global options that do not exist in the local families of the package or class calling \fx{\XProcessOptions}\RedStar will be simply ignored or highlighted.
+The \stform of \fx{\XProcessOptions} works like the \unstform except that the former also copies user input from the \hx{\documentclass} command and processes the options in the order specified by the \hx{\documentclass}. When the user specifies an option in the \hx{\documentclass} which also exists in the local family (or families) of the package calling \fx{\XProcessOptions}\Redstar, the local option will be set as well. In this case, \fx{#1} in \fx{\XDeclareOption} macro will contain the user-value entered in the \hx{\documentclass} (or \fx{\usepackage} or \fx{\RequirePackage}) command for this option. First the global options from \hx{\documentclass} will set local options and afterwards the local options (specified via \hhx'{\usepackage, \RequirePackage, \LoadClass} or similar commands) will set local options, which could overwrite the global options set earlier, depending on how the options sections are organized. The macro \fx{\XProcessOptions}\Redstar reduces to \fx{\XProcessOptions} only when issued from the class which forms the document class for the file at hand (to avoid setting the same options twice), but not for classes loaded later using, for instance, \hx{\LoadClass}. Global options that do not exist in the local families of the package or class calling \fx{\XProcessOptions}\Redstar will be simply ignored or highlighted.
 
-The implementation here differs significantly from the \latex kernel's scheme of carrying out \hx{\ProcessOptions} and \hx{\ProcessOptions}\RedStar. It also deviates from the implementations by other options processing packages. The differences lie mainly in how the local and global options are distinguished and in the order of processing those options. Among other issues, the family structure introduced by the \pkg'{catoptions} (though lightweight) makes the independence between local and global options possible, even if the options from the two categories share the same namespace and are mixed in, say, \hx{\documentclass} command. Also, document classes loaded by \hx{\LoadClass} don't have the same primacy as the first document class. When using \latex kernel's \hx{\ProcessOptions} or \hx{\ProcessOptions}\RedStar, a class file can't copy document class options, even if the class file is loaded by \hx{\LoadClass}. This is not the case with the \pkg'{catoptions}.
+The implementation here differs significantly from the \latex kernel's scheme of carrying out \hx{\ProcessOptions} and \hx{\ProcessOptions}\Redstar. It also deviates from the implementations by other options processing packages. The differences lie mainly in how the local and global options are distinguished and in the order of processing those options. Among other issues, the family structure introduced by the \pkg'{catoptions} (though lightweight) makes the independence between local and global options possible, even if the options from the two categories share the same namespace and are mixed in, say, \hx{\documentclass} command. Also, document classes loaded by \hx{\LoadClass} don't have the same primacy as the first document class. When using \latex kernel's \hx{\ProcessOptions} or \hx{\ProcessOptions}\Redstar, a class file can't copy document class options, even if the class file is loaded by \hx{\LoadClass}. This is not the case with the \pkg'{catoptions}.
 
 \start+{example}[\XDeclareOption,\XExecuteOptions,\XProcessOptions]
 |com(This is a sample class file. We specify a family for the options,)
@@ -630,6 +657,35 @@ The implementation here differs significantly from the \latex kernel's scheme of
 \fxim*{\cptloadpackages}
 
 
+\docsubsection(sec:before-proc-options){Hook for before and after processing options}
+
+\start{newmacro}[\BeforeProcessOptions,\AfterProcessOptions]
+\BeforeProcessOptions{|nang(code)}
+\AfterProcessOptions{|nang(code)}
+\finish{newmacro}
+\fxim*{\BeforeProcessOptions,\AfterProcessOptions}
+
+The macros \ffx'{\BeforeProcessOptions,\AfterProcessOptions} can be used to process \ang{code} before and after \fx{\XProcessOptions} has run its course. The command \fx{\AfterProcessOptions} is particularly useful when it is required to optionally load a package, depending on the state of an option in the current package. For obvious reasons, \latex doesn't allow the loading of packages in the options section. The command \fx{\AfterProcessOptions} can be used to load packages after the current package's options have been processed. Here is an example for optionally loading sub-packages at the end of the options section:
+
+\start{example}[\AfterProcessOptions]
+\newif\ifloadsubpackages
+\robust@def*\inputpackage{\cpt@testopt\inp@tpackage{}}
+\robust@def*\inp@tpackage[#1]#2{%
+  \ifloadsubpackages
+    \AfterProcessOptions{\RequirePackage[#1]{#2}}%
+  \fi
+}
+\robust@def*\loadsub#1{%
+  \docommalist{#1}{%
+    \XDeclareOption{##1}{\inputpackage[####1]{##1}}%
+  }%
+}
+\loadsub{subpkg1,subpkg2,subpkg3}
+\finish{example}
+
+
+\docsubsection(sec:ifoptiondef){Testing if an option is defined}
+
 \start{newmacro}[\ifoptdefTF]
 \ifoptdefTF<|nang(fams)>{|nang(opt)}{|nang(true)}{|nang(false)}
 \ifoptdefFT<|nang(fams)>{|nang(opt)}{|nang(false)}{|nang(true)}
@@ -639,6 +695,8 @@ The implementation here differs significantly from the \latex kernel's scheme of
 The macro \fx{\ifoptdefTF} returns \ang{true} if option \ang{opt} is undefined in one or more members of \ang{fams}, and \ang{false} otherwise. The command \fx{\ifoptdefFT} reverses the logic of \fx{\ifoptdefTF}.
 
 
+\docsubsection(sec:disable-options){Disabling options}
+
 \start{newmacro}[\XDisableOptions]
 \XDisableOptions<|nang(fams)>{|nang(opts)}
 \XDisableOptions|*<|nang(fams)>{|nang(opts)}
@@ -649,14 +707,8 @@ The command \fx{\XDisableOptions} disables all the options in the list \ang{opts
 
 The \stform of \fx{\XDisableOptions} delays the invalidation of the \ang{opts} until the invocation of \hx{\begin{document}}. This may be used to bar users of the options from committing the options after the start of document, but not before.
 
-\start{newmacro}[\ifoptdisabled]
-\ifoptdisabledTF<|nang(fams)>{|nang(opt)}{|nang(true)}{|nang(false)}
-\ifoptdisabledFT<|nang(fams)>{|nang(opt)}{|nang(false)}{|nang(true)}
-\finish{newmacro}
-\fxim*{\ifoptdisabledTF}
-
-The macro \fx{\ifoptdisabledTF} returns \ang{true} if option \ang{opt} has been disabled from one or more members of \ang{fams}, and \ang{false} otherwise. The command \fx{\ifoptdisabledFT} reverses the logic of \fx{\ifoptdisabledTF}.
 
+\docsubsubsection{Logging disabled options}
 
 \start{newmacro}[\XLogDisabledOptions]
 \XLogDisabledOptions<|nang(fams)>
@@ -666,6 +718,17 @@ The macro \fx{\ifoptdisabledTF} returns \ang{true} if option \ang{opt} has been
 The command \fx{\XLogDisabledOptions}, which can be called before and after \hx{\begin{document}}, writes in the current transcript file the options of the families \ang{fams} that have been disabled so far. If no options have been disabled from any of the given families or if the given family does not exist, a message is logged to that effect.
 
 
+\docsubsubsection{Testing if an option is disabled}
+
+\start{newmacro}[\ifoptdisabled]
+\ifoptdisabledTF<|nang(fams)>{|nang(opt)}{|nang(true)}{|nang(false)}
+\ifoptdisabledFT<|nang(fams)>{|nang(opt)}{|nang(false)}{|nang(true)}
+\finish{newmacro}
+\fxim*{\ifoptdisabledTF}
+
+The macro \fx{\ifoptdisabledTF} returns \ang{true} if option \ang{opt} has been disabled from one or more members of \ang{fams}, and \ang{false} otherwise. The command \fx{\ifoptdisabledFT} reverses the logic of \fx{\ifoptdisabledTF}.
+
+
 \docsection(sec:normalize)<Normalizing lists>{Normalizing csv and kv lists}
 
 Any arbitrary parser-separated-values (csv) list can be normalized by means of the package command \fx{\csv@@normalize} before processing the list.
@@ -694,7 +757,7 @@ Here, \ang{list}, which is populated by parser-separated elements, is not expand
 \finish{newmacro}
 \fxim*{\kv@@normalize}
 
-The command \fx{\kv@@normalize} normalizes a list of key-value pairs, returning the result in the macro \fx{\normalized@list} (in the \unstform case) or \ang{listcmd} (in the \stform case). Besides dealing with multiple commas and the spaces between entries, in this case the spaces between keys and the equality sign are removed and multiple equality signs are made only one. Moreover, the category codes of the arbitrary parser and the equality sign is made normal/other throughout the list. The command \fx{\kv@@normalize} is meant for options or key-value parsing; it is used in the options processing scheme of \pkg'{catoptions}.
+The command \fx{\kv@@normalize} normalizes a list of key-value pairs, returning the result in the macro \fx{\normalized@list} (in the \unstform case) or \ang{listcmd} (in the \stform case). Besides dealing with multiple commas and the spaces between entries, in this case the spaces between keys and the equality sign are removed and multiple equality signs are made only one. Moreover, the category codes of the arbitrary parser and the equality sign are made normal/other throughout the list. The command \fx{\kv@@normalize} is meant for options or key-value parsing; it is used in the options processing scheme of \pkg'{catoptions}.
 
 \start{example}[\csv@@normalize]
 \begingroup
@@ -730,7 +793,6 @@ Here are some points to note about these list processors:
 \item If an item contains \ang{parser}, it must be wrapped in curly braces when using \ffx'{\csv@@loop,\csv@@parse,\kv@@loop,\kv@@parse}, otherwise the elements may be mixed up during parsing. The braces will persist thereafter, but will of course be removed during printing (if the items are printed).
 \item White spaces before and after the list separator are always ignored by the normalizer called by \ffx'{\csv@@parse,\kv@@parse}. If an item contains \ang{parser} or starts with a space, it must, therefore, be wrapped in curly braces before commencing these loops.
 \item Since \ffx'{\csv@@loop,\kv@@loop} don't call the normalizer, they preserve outer/surrounding spaces in the entries. Empty entries in \ang{list} or \ang{listcmd} will be processed by \ffx'{\csv@@loop,\kv@@loop} if the boolean \fx{cpt@useempty} is true. You may thus issue the command \fx{\UseEmptyEntry} or \fx{\DiscardEmptyEntry}, which are based on the boolean \fx{cpt@useempty}, before commencing the iteration. If empty entries are important to the task at hand, then issuing \fx{\UseEmptyEntry} or \fx{\DiscardEmptyEntry} prior to the commencement of the loop is recommended, because a previous call to either \fx{\csv@@loop} or \fx{\kv@@loop} (perhaps by another package) could have set \fx{cpt@useempty} to a state that is no longer valid or desired.
-\item The commands \ffx'{\csv@@loop,\csv@@parse,\kv@@loop,\kv@@parse} will execute at least once for empty \ang{list} or \ang{listcmd}.
 \item The commands \ffx'{\csv@@loop,\csv@@parse,\kv@@loop,\kv@@parse} can be nested to any level and can be mixed.
 \item In the commands \ffx'{\csv@@loop,\csv@@parse,\kv@@loop,\kv@@parse}, it is always possible to break out of the loop prematurely at any level of nesting, simply by issuing the command \fx{\loopbreak} (see the example below). Breaking an inner loop doesn't affect the continuation of the outer loop, and vice versa; that is, loop breaks are nest-level-dependent.
 \item The user can insert \fx{\csvbreak} as an element in \ang{list} for any of the commands \ffx'{\csv@@loop, \csv@@parse, \kv@@loop, \kv@@parse, \dofunclist} with the hope of automatically breaking out of the list processing prematurely (\ie, before the list is exhausted). The tokens \ffx'{\listbreak, \breaklist} are not defined or used by the \pkg'{catoptions}, to avoid name clashes with other packages. The \pkg'{catoptions} instead uses \fx{\csvbreak}, which is an unexpandable token; if it were to be expandable, then experience has shown that a chaotic infinite loop could arise in an expansion context. Breaking out of the loop prematurely on the current nest level doesn't affect the continuation of the loop on the other levels.
@@ -822,7 +884,7 @@ Empty entries in \ang{list} will be ignored by the normalizer called by \fx{\dof
 
 |com(Let us load many packages compactly here. This is just an example of)
 |com(|fx(\dofunclist); you can instead use the more appropriate command)
-|com(|fx(\cptloadpackages) to load packages (see |amref(mac:loadpkg)):)
+|com(|fx(\cptloadpackages) to load packages (see |sref(mac:loadpkg)):)
 \def\do#1.#2[#3]{%
   \@ifpackageloaded{#1}{%
     \@ifpackagelater{#1}{#2}{}{%
@@ -929,7 +991,7 @@ The following provides a simple application of \fx{\indrisloop}, which I posted
 \finish{example}
 
 %\bigskip
-\docsection(sec:tsvparse)<Iterating tokenwise>{Parsing \headqtd{tsv} lists}
+\docsection(sec:tsvparse)<Iterating tokenwise>{Parsing \headquoted{tsv} lists}
 
 \start+{newmacro}[\tsv@@parse,\tsv@@loop]
 \tsv@@loop{|nang(list)}
@@ -969,6 +1031,9 @@ In the commands \ffx'{\tsv@loop,\tsv@@parse}, it is always possible to break out
 The following change history highlights significant changes that affect user utilities and interfaces; mutations of technical nature are not documented in this section. The numbers on the right-hand side of the following lists are section numbers; the \stsign means the subject features in the package but is not reflected anywhere in this user guide.
 
 \begin{versionhist}
+  \begin{version}{0.2.7}{2011/10/10}
+  \item Introduced the commands \ffx'{\BeforeProcessOptions,\AfterProcessOptions} \vsecref{sec:before-proc-options}
+  \end{version}
   \begin{version}{0.2.6}{2011/09/10}
   \item Bug fix in the command \fx{\UseNormalCatcodes} \vsecref{sec:saving-catcodes}
   \end{version}
@@ -1006,9 +1071,9 @@ The following change history highlights significant changes that affect user uti
 \end{versionhist}
 
 \newpage
-\indexpreambleformat{\centering}
-\indexpreamble{Index numbers refer to page numbers.}
-\indexcolumns\tw@
+\ltsindexpreambleformat{\centering}
+\ltsindexpreamble{Index numbers refer to page numbers.}
+\ltsindexcolumns\tw@
 \printindex
 
 \end{document} 
\ No newline at end of file