catoptions (19apr11)

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

3 files changed, 210 insertions, 63 deletions

diff --git a/Master/texmf-dist/doc/latex/catoptions/README b/Master/texmf-dist/doc/latex/catoptions/README
index 209718e379d..49831b28d7f 100644
--- a/Master/texmf-dist/doc/latex/catoptions/README
+++ b/Master/texmf-dist/doc/latex/catoptions/README
@@ -2,9 +2,9 @@ This is the README file for the 'catoptions' package.
 
 SUMMARY
 The 'catoptions' package changes package loading internals so
-that all subsequently loaded packages can rely on normal/standard 
-catcodes of all ASCII characters. The package defines canonical 
-control sequences to represent all the visible ASCII characters. 
+that all subsequently loaded packages can rely on normal/standard
+catcodes of all ASCII characters. The package defines canonical
+control sequences to represent all the visible ASCII characters.
 It also provides robust options parsing mechanisms, in addition
 to many TeX programming tools.
 
@@ -12,10 +12,10 @@ AUTHOR
 Ahmed Musa
 
 RELATED PACKAGES
-The 'catoptions' package is based on the 'pcatcode' package
-by Michael J. Downes and David M. Jones.
+The catcode section of the 'catoptions' package is based on
+the 'pcatcode' package by Michael J. Downes and David M. Jones.
 
 VERSION
-Version 0.2, February 2011
+Version 0.2b, April 2011
 
 
diff --git a/Master/texmf-dist/doc/latex/catoptions/catoptions-guide.pdf b/Master/texmf-dist/doc/latex/catoptions/catoptions-guide.pdf
index 9aeba1d85e3..2ef01da6887 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 d6d4a9acee6..4b9a1c0b4d6 100644
--- a/Master/texmf-dist/doc/latex/catoptions/catoptions-guide.tex
+++ b/Master/texmf-dist/doc/latex/catoptions/catoptions-guide.tex
@@ -3,6 +3,7 @@
 \makeatletter
 \WrapQuotes
 \NoPrintNotes
+\def\XDecS{\fx{\XDeclareOption}\RedStar\sspace}
 \makeindex
 
 \begin{document}
@@ -11,7 +12,7 @@
 \title{The \texttt{\color{blue}catoptions} Package\titleref{t1}}
 \titlenote[t1]{The package is available at
   \iftogTF{pdf}{\url{\@titleurl}}{\url{\@shorttitleurl}}.}
-\version{0.2}
+\version{0.2b}
 \titleurl{http://www.ctan.org/tex-archive/macros/latex/contrib/catoptions/}
 \shorttitleurl{http://www.ctan.org/}
 \author{Ahmed Musa \Email{a.musa@rocketmail.com}\\Preston, Lancashire, UK}
@@ -19,7 +20,7 @@
 \def\abstractname{\textsf{Summary}}
 \begin{abstract}
   \small
-  The \pkg'{catoptions} provides several extensions to the \pkgm'{pcatcode}. Apart from the tools related to setting up, preserving and restoring category codes, it includes many \texorlatex programming tools and even new list and options processing interfaces. It modifies the \latex kernel's options parsing mechanism to forestall premature expansion of options and values (in the manner of the \pkgs'{xkvltxp,kvoptions-patch}), so that the \pkg'{catoptions} may be loaded even before \hx{\documentclass}. In fact, the package is meant to be loaded on top of other packages, so as to exploit its catcode preserving scheme. Among other reasons, this necessitated the development of the options parsing scheme of this package. Only the catcode and options parsing facilities are treated in this manual; the macro programming interfaces will be covered in the documentation of the \pkg'{ltxtools}. The machinery of the \pkg'{catoptions} adds no cost to the simple syntax of \LaTeX's native options parser. Users who are already familiar with \LaTeX's legacy options processing don't necessarily have to invest the time that is essential in learning the extensive machinery of existing key-value and option parsers, although those other packages (\eg, \pkgs{xkeyval, kvsetkeys, kvoptions, skeyval, rkeyval, pgfkeys, pgfopts}) contain richer featuresets. Existing packages don't have to be modified to use the features of the \pkg'{catoptions}. The \pkg'{catoptions}, while maintaining simplicity, does not strip off even one level of outer braces in parsing package options and in list processing. It robustly normalizes key-values and options prior to parsing. The options parsing scheme of the \pkg'{catoptions} has been tried as a replacement parser on many packages, including \pkgs'{hyperref, cleveref, natbib} without difficulties.
+  The \pkg'{catoptions} provides several extensions to the \pkgm'{pcatcode}. Apart from the tools related to setting up, preserving and restoring category codes, it includes many \texorlatex programming tools and even new list and options processing interfaces. It modifies the \latex kernel's options parsing mechanism to forestall premature expansion of options and values (in the manner of the \pkgs'{xkvltxp,kvoptions-patch}), so that the \pkg'{catoptions} may be loaded even before \hx{\documentclass}. In fact, the package is meant to be loaded on top of other packages, so as to exploit its catcode preserving scheme. Among other reasons, this necessitated the development of the options parsing scheme of this package. Only the catcode and options parsing facilities are treated in this manual; the application programming interfaces will be covered in the documentation of the \pkg'{ltxtools}. The machinery of the \pkg'{catoptions} adds no cost to the simple syntax of \LaTeX's native options parser. Users who are already familiar with \LaTeX's legacy options processing don't necessarily have to invest the time that is essential in learning the extensive machinery of existing key-value and option parsers. Existing packages don't have to be modified to use the features of the \pkg'{catoptions}. The \pkg'{catoptions}, while maintaining simplicity, does not strip off even one level of outer braces in parsing package options and in list processing. It robustly normalizes key-values and options prior to parsing. The options parsing scheme of the \pkg'{catoptions} has been tried as a replacement parser on the \pkgnoidx{article} class and on many packages, including \pkgs'{hyperref, cleveref, natbib} without difficulties.
 \end{abstract}
 
 \let\licensename\relax
@@ -38,15 +39,14 @@
   width=1.0\hsize]\tableofcontents
 \end{xwmshade}
 
-
 \docsection(sec:motivation){Motivation}
 
-My motivation for turning to the \pkgnoidx'{pcatcode} was to save myself the trouble of declaring category codes at the beginning of my packages. After spending some time on the \pkgnoidx'{pcatcode}, I discovered I had learnt enough to make changes and additions to some of its macros and functionality. After completing the catcode stuff in the \pkg'{catoptions}, I wanted to pass options to the package. If the package is to be loaded on top of other packages, as intended, then its options parsing scheme should be independent of other packages. But realizing the trouble with passing expandable option values to packages and classes via the \latex kernel's scheme, I decided to implement modifications to the kernel's options parser. Apart from the problem of premature expansion of options and values by the \latex kernel, outer curly braces in option values are lost during parsing. Indeed, the kernel's option parsing scheme doesn't recognize option values indicated with the equality sign. And the syntaxes (if not also the semantics) of \cptuse{latex3}, whose options parser is presumably more robust than that of \cptuse{latex2e}, calls for additional investment in time that may not be readily affordable to some users.
+\lletter{M}{y motivation} for turning to the \pkgnoidx'{pcatcode} was to save myself the trouble of declaring category codes at the beginning of my packages. After spending some time on the \pkgnoidx'{pcatcode}, I discovered I had learnt enough to make changes and additions to some of its macros and functionality. After completing the catcode stuff in the \pkg'{catoptions}, I wanted to pass options to the package. If the package is to be loaded on top of other packages, as intended, then its options parsing scheme should be independent of other packages. But realizing the trouble with passing expandable option values to packages and classes via the \latex kernel's scheme, I decided to implement modifications to the kernel's options parser. Apart from the problem of premature expansion of options and values by the \latex kernel, outer curly braces in option values are lost during parsing. Indeed, the kernel's option parsing scheme doesn't recognize option values indicated with the equality sign.
 
 
 \docsection(sec:pkg-options)<Package options>{Package options}
 
-The \pkg'{catoptions} has the options shown in \cref{tab:pkgoptions}. The boolean option \fxim{verbose} instructs the package to put information onto the log file when existing commands are being redefined by means of, say, the command \fx{\robust@redef} (which has the same syntax with  \tex's legacy \hx{\def}). 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 \cref{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
@@ -115,7 +115,7 @@ to see the current catcode setup. The command \fx{\cptfutureletsetup} is describ
 \RequirePackage[verbose, usepox]{catoptions}
 \UseNormalCatcodes
 \finish{example}
-%\fxi*{\UseNormalCatcodes}
+\dummyfxi*{\UseNormalCatcodes}
 
 
 \docsection(sec:future-letting){Future-letting of \headq{other} characters}
@@ -129,7 +129,7 @@ slash|R(/) colon|R(:) semicolon|R(;) less|R(<) equal|R(=) greater|R(>) question|
 rbracket|R(]) hat|R(^) underscore|R(_) lquote|R(`) lbrace|R({) vert|R(|rv) rbrace|R(}) tilde|R(~)
 bslash|R(\)
 \finish{example}
-%\fxim*{\cptfutureletsetup}
+\dummyfxim*{\cptfutureletsetup}
 
 However, for efficiency reasons, the canonical control sequences will be defined for only the characters (or their names) appearing in the user-supplied list \fx{\declarefutureletset}, whose syntax is
 
@@ -196,7 +196,7 @@ where \quotedtt{all} means that control sequences should be defined for all the
 
 This will yield control sequences that may never be needed. While such a facility does exist, using it will be inefficient despite the large capacities of many modern text engines.
 
-The use syntaxes for the commands \xfnn\bs{{stub}{char}} and \xfnn\bs{{if}{stub}{char}} are as follows:
+The use syntaxes for the commands \fnl{{stub}{char}} and \fnl{{if}{stub}{char}} are as follows:
 
 \start{example}[Futurelet characters]
 \futurelet\next\cmd |textbf(|R(*))
@@ -204,7 +204,7 @@ The use syntaxes for the commands \xfnn\bs{{stub}{char}} and \xfnn\bs{{if}{stub}
 \def\cmd{\iffl@star\next{`I saw star'}{`I didn't see star'}}
 \finish{example}
 
-Notice that \fx{\ifx\fl@comma\next} is a conventional \tex test, while \fx{\iffl@...} expects two \latex branches (\ffx'{\@firstoftwo,\@secondoftwo}). It may be argued that these commands are needlessly too many and may be defined by means of only two macros. That would appear a valid point, but the commands are meant to be easy to recall and use. If, for example, you are testing for the presence of \fx{\tilde}, you simply do \fx{\iffl@tilde\next{...}{...}}, assuming a \ang{stub} of \fx{fl@}.
+Notice that \fx{\ifx\fl@comma\next} is a conventional \tex test, while \fx{\iffl@...} expects two \latex branches (\ffx'{\@firstoftwo,\@secondoftwo}). The commands are meant to be easy to recall and use. If, for example, you are testing for the presence of \fx{\tilde}, you simply do \fx{\iffl@tilde\next{...}{...}}, assuming a \ang{stub} of \fx{fl@}.
 
 After setting up \fx{\futurelet} characters with \fx{\cptfutureletsetup}, you can reset active characters to catcode~13 by \fx{\futureletresetactives}.
 
@@ -227,7 +227,7 @@ $Id: mypackage.sty,v 0.1 2011/01/01 09:00:00 My Name Exp $
 \finish{newmacro}
 \fxim*{\SetStyleFileMessages}
 
-Here, \ang{stub} is an optional prefix for the three package messages described below. The default value of \ang{stub} is the first three characters of the package or class name (\hx{\@currname}) concatenated with the \quoted{at} sign \quoted{\fx{@}}. The mandatory arguments \ang{err}, \ang{warn}, and \ang{info} are the suffices for the package error, warning and information messages, respectively.
+Here, \ang{stub} is an optional prefix for the three package messages described below. The default value of \ang{stub} is the first three characters of the package or class name (\hx{\@currname}) concatenated with the \quoted{at} sign \quotedfx{@}. The mandatory arguments \ang{err}, \ang{warn}, and \ang{info} are the suffices for the package error, warning and information messages, respectively.
 
 For instance, with the declaration
 
@@ -260,18 +260,18 @@ 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.
 
 \start{newmacro}[\XDeclareOption]
-\XDeclareOption<|nang(fam)>{|nang(option)}[|nang(default)]{|nang(fn)}
+\XDeclareOption<|nang(fam)>{|nang(opt)}[|nang(default)]{|nang(fn)}
 \XDeclareOption|*<|nang(fam)>{|nang(fn)}
 \finish{newmacro}
 \fxim*{\XDeclareOption}
 
-The \unstform of the macro \fx{\XDeclareOption} declares an option that can be used as a package or class option and executed by \fx{\XExecuteOptions} or \fx{\XProcessOptions}. This macro is similar to the standard \latex macro \hx{\DeclareOption}, but with this command the user can pass a value to the option as well. That value can be accessed by using \fx{#1} or \fx{\currval} in \ang{fn}. This will contain \ang{default} when no value has been specified for the option. The default value of the optional argument \ang{default} is empty. This implies that when the user does not assign a value to \ang{option} and when no default value has been defined, no error message will ensue. The optional argument \ang{fam} can be used to specify a unique family for the option. When the argument is not used, the macro will insert the default family name (namely, \fx{\@currname.\@currext}). The current option name is available in \fx{\curropt}.
+The \unstform of the macro \fx{\XDeclareOption} declares an option that can be used as a package or class option and executed by \fx{\XExecuteOptions} or \fx{\XProcessOptions}. This macro is similar to the standard \latex macro \hx{\DeclareOption}, but with this command the user can pass a value to the option as well. That value can be accessed by using \fx{#1} or \fx{\currval} in \ang{fn}. This will contain \ang{default} when no value has been specified for the option. The default value of the optional argument \ang{default} is empty. This implies that when the user does not assign a value to \ang{opt} and when no default value has been defined, no error message will ensue. The optional argument \ang{fam} can be used to specify a unique family for the option. When the argument is not used, the macro will insert the default family name (namely, \fx{\@currname.\@currext}). The current option name is available in \fx{\curropt}.
 
 \start{example}[\XDeclareOption]
 \ProvidesPackage{mypackage}[\StyleFileInfo]
 \newif\ifmybool
 \XDeclareOption{mybool}[true]{\@nameuse{mybool#1}}
-\XDeclareOption{leftmargin}[.5\hsize]{\setlength\leftmargin{#1}}
+\XDeclareOption{leftmargin}[.5\hsize]{\setlength\leftmargin{#1}}|xwmlabel(mac:leftmargin)
 \finish{example}
 
 The options \ffx'{mybool,leftmargin} could then be called via any of the following statements:
@@ -285,82 +285,162 @@ The options \ffx'{mybool,leftmargin} could then be called via any of the followi
 \documentclass[mybool,leftmargin=20\p@]{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. 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.
+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.
+
+
+\start{newmacro}[\XUnknownOptionHandler]
+\XUnknownOptionHandler<|nang(fams)>[|nang(na)]{|nang(handler)}
+\finish{newmacro}
+\fxim*{\XUnknownOptionHandler}
+
+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}. \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]
+define/.code=|nang(callback)
+\finish{example}
+\fxim*{define/.code}
+
+then the unknown option \fx{\cpt@curropt} 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}. You can use \fx{#1}, \fx{#2} and \fx{#3} in \ang{callback} to refer to the current option family, option name, and option value, respectively.
 
-The following example produces a warning when the user supplies an option that was not previously declared.
+If \fx{\cpt@currval} is \hx{true} or \hx{false}, the new (\ie, unknown) 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}.) Note that the token \quoted{define} in the above syntax is not escaped.
 
+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>{%
+  \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|*{\PackageWarningNoLine{mypackage}{Unknown option
-  `\CurrentOption' ignored}}
+\XDeclareOption|*{\PassOptionsToClass{#2=#3}{article}}
 \finish{example}
 
+The following example instructs \fx{\XProcessOptions} to define all unknown keys on the fly with the call-back shown.
+
+\start{example}[\XUnknownOptionHandler]
+\XUnknownOptionHandler<mypackage>{%
+  define/.code=\def\x##1{##1\relax `option #2 = value #3' in family `#1'}%
+  \PackageWarningNoLine{mypackage}{Unknown option `#2' of family `#1' defined}%
+}
+\finish{example}
+
+If no default family handler has been provided by the user (through the macro \XDecS or \fx{\XUnknownOptionHandler}) for an undeclared option, and the option doesn't appear in the list \fx{\ExternalOptions}, then that option will be logged (\ie, entered in the transcript file) as undefined at the end of the document. By default, \fx{\ExternalOptions} contains all \hhx'{article,report,memoir} class options. The user can update the \fx{\ExternalOptions} list by means of the following commands:
+
+\start+{newmacro}[\AddToExternalOptions,\RemoveFromExternalOptions]
+\AddToExternalOptions{|nang(opts)}
+\RemoveFromExternalOptions{|nang(opts)}
+\finish{newmacro}
+\fxim*{\ExternalOptions,\AddToExternalOptions,\RemoveFromExternalOptions}
+
+where \ang{opts} are the comma-separated option names to be added to, or removed from, the list.
+
 \start{newmacro}[\XDeclareOptions]
-\XDeclareOptions<|nang(fam)>{|nang(options)}[|nang(default)]{|nang(fn)}
+\XDeclareOptions<|nang(fam)>{|nang(opts)}[|nang(default)]{|nang(fn)}
 \finish{newmacro}
 \fxim*{\XDeclareOptions}
 
-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{options}. Each option in the list \ang{options} 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.
+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}
 
 
 \start{newmacro}[\XDeclareCommandOption]
-\XDeclareCommandOption<|nang(fam)>{|nang(option)}[|nang(default)]|(pref|){|nang(fn)}
+\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{option}, also create a macro \fnn{{pref}{option}} 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 \quoted{\fx{\@currname @}} prefixed with the letters \fx{cmd}.
+The command \fx{\XDeclareCommandOption} will, apart from declaring the option \ang{opt}, also create a macro \fnl{{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(options)}[|nang(default)]|(pref|){|nang(fn)}
+\XDeclareCommandOptions<|nang(fam)>{|nang(opts)}[|nang(default)]|(|nang(pref)|){|nang(fn)}
 \finish{newmacro}
 \fxim*{\XDeclareCommandOptions}
 
-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{options}. Each option in the list \ang{options} is defined with the same family \ang{fam}, default value \ang{default}, and function \ang{fn}.
-
+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}.
 
 \start{newmacro}[\XDeclareBooleanOption]
-\XDeclareBooleanOption<|nang(fam)>{|nang(option)}[|nang(default)]|(pref|){|nang(fn)}
+\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{option}, also create a boolean \fnn{{if}{pref}{option}}. 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 \quoted{\fx{\@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{{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(options)}[|nang(default)]|(pref|){|nang(fn)}
+\XDeclareBooleanOptions<|nang(fam)>{|nang(opts)}[|nang(default)]|(|nang(pref)|){|nang(fn)}
 \finish{newmacro}
 \fxim*{\XDeclareBooleanOptions}
 
-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{options}. Again, each option in the list \ang{options} is defined with the same family \ang{fam}, default value \ang{default}, and function \ang{fn}.
-
+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}.
 
 \start{newmacro}[\XDeclareBiBooleanOptions]
-\XDeclareBiBooleanOptions<|nang(fam)>{|nang(opt1),|nang(opt2)}[|nang(default)]|(pref|){|nang(fn1)}{|nang(fn2)}
+\XDeclareBiBooleanOptions<|A(fam)>{|A(opt1),|A(opt2)}[|A(default)]|(|A(pref)|){|A(fn1)}{|A(fn2)}
 \finish{newmacro}
 \fxim*{\XDeclareBiBooleanOptions}
 
 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.
 
-
 \start{newmacro}[\XExecuteOptions]
-\XExecuteOptions<|nang(fam)>{|nang(options)}
+\XExecuteOptions<|nang(fams)>{|nang(opts)}[|nang(na)]
 \finish{newmacro}
 \fxim*{\XExecuteOptions}
 
-The re-entrant \fx{\XExecuteOptions} macro sets options created by \fx{\XDeclareOption} and is basically a means of setting up the default values of the options. The optional argument \ang{fam} can be used to specify a list of families that define the options. When the argument is not used, the macro will insert the default family name (\fx{\@currname.\@currext}). This macro will not use the declaration done by \fx{\XDeclareOption}\RedStar when undeclared options appear in its argument. Instead, in this case the macro will issue a warning and ignore the option. This differs from the behavior of \latex's \hx{\ExecuteOptions}.
+The re-entrant \fx{\XExecuteOptions} macro sets options created by \fx{\XDeclareOption} and is basically a means of setting up the default values of the options. The optional argument \ang{fams} can be used to specify a list of \emph{families} that define the options. When the argument is not used, the macro will insert the default family name (\fx{\@currname.\@currext}). The set \ang{na} is the list of keys to be ignored (\ie, not executed if they appear in \ang{opts}).
+
+This macro will not use the declaration done by \XDecS when undeclared options appear in its argument. Instead, in this case the macro will issue a warning and ignore the option. This differs from the behavior of \latex's \hx{\ExecuteOptions}.
 
 \start{example}[\XExecuteOptions]
 \XExecuteOptions{leftmargin=0pt}
 \finish{example}
-%\fxi*{\XExecuteOptions}
+\dummyfxi*{\XExecuteOptions}
 
-This initializes \hx{\leftmargin} to 0pt.
+This initializes the option \hx{\leftmargin} of \macref{mac:leftmargin} to 0pt.
 
 \start{newmacro}[\XProcessOptions]
-\XProcessOptions<|nang(fam)>[|nang(na)]
-\XProcessOptions|*<|nang(fam)>[|nang(na)]
+\XProcessOptions<|nang(fams)>[|nang(na)]
+\XProcessOptions|*<|nang(fams)>[|nang(na)]
 \finish{newmacro}
 \fxim*{\XProcessOptions}
 
-The re-entrant \fx{\XProcessOptions} macro processes the options and values passed by the user to the class or package. The optional argument \ang{fam} can be used to specify the 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 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.
 
@@ -380,6 +460,9 @@ The implementation here differs significantly from the \latex kernel's scheme of
   \@nameuse{boola#1}%
   \ifboola\let\eat\@gobble\fi
 }
+\XDeclareOptions<testclass>{opta,optb}[true]{%
+  \def\alloptsfunc##1{\def\tempa{##1}}%
+}
 |com(No need for \newif when declaring boolean options:)
 \XDeclareBooleanOption<testclass>{boolb}[true]|(test@|){%
   \iftest@boolb
@@ -388,18 +471,14 @@ The implementation here differs significantly from the \latex kernel's scheme of
 }
 \XDeclareBiBooleanOptions{draft,final}[true](test@){}{}
 \XDeclareCommandOption<testclass>{color}[blue]|(test@|){%
-  \def\text{\textcolor{\test@color}{Result of test}}%
+  Load `color' package
 }
+|com(Disable option `color' at \AtBeginDocument:)
+\XDisableOption|*<testclass>{color}
 \XDeclareOption<testclass>{align}[left]{%
-  \ifstrcmpTF{#1}{left}{%
-    \let\align\raggedright
-  }{%
-    \ifstrcmpTF{#1}{right}{%
-      \let\align\raggedleft
-    }{%
-      \ifstrcmpTF{#1}{center}{%
-        \let\align\centering
-      }{%
+  \ifstrcmpTF{#1}{left}{\let\align\raggedright}{%
+    \ifstrcmpTF{#1}{right}{\let\align\raggedleft}{%
+      \ifstrcmpTF{#1}{center}{\let\align\centering}{%
         \@latex@error{Invalid value `#1' for align}{%
           You have issued an illegal value `#1' for the variable `align'.
         }%
@@ -407,11 +486,16 @@ The implementation here differs significantly from the \latex kernel's scheme of
     }%
   }%
 }
-\XDeclareOption*<testclass>{\PassOptionsToClass{\CurrentOption}{article}}
+\XDeclareInvalidOption<testclass>{deadoption}
+\XDeclareOption|*<testclass>{%
+  define/.code=\PassOptionsToClass\CurrentOption{article}%
+}
 \XExecuteOptions<testclass>{boola,boolb}
-\XProcessOptions*<testclass>\relax
+\XProcessOptions|*<testclass>\relax
 \LoadClass{article}
-\RequirePackage{xcolor}
+\cptloadpackages{%
+  |nang(pkg name)|rv|nang(pkg opts)|rv|nang(pkg date)|R(;)...|R(;)|nang(more packages)
+}
 \endinput
 
 |com(This is a sample document:)
@@ -435,6 +519,40 @@ The implementation here differs significantly from the \latex kernel's scheme of
 \end{document}
 \finish{example}
 
+\start{newmacro}[\ifoptdefTF]
+\ifoptdefTF<|nang(fams)>{|nang(opt)}{|nang(true)}{|nang(false)}
+\ifoptdefFT<|nang(fams)>{|nang(opt)}{|nang(false)}{|nang(true)}
+\finish{newmacro}
+\fxim*{\ifoptdefTF}
+
+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}.
+
+
+\start{newmacro}[\XDisableOptions]
+\XDisableOptions<|nang(fams)>{|nang(opts)}
+\XDisableOptions|*<|nang(fams)>{|nang(opts)}
+\finish{newmacro}
+\fxim*{\XDisableOptions}
+
+The command \fx{\XDisableOptions} disables all the options in the list \ang{opts} that can be found in the families \ang{fams}, \ie, it makes the options invalid thereafter. If any of the options in the list \ang{opts} can't be found in the families \ang{fams}, it is simply ignored without warning: since families can be mixed in \ang{fams}, it wouldn't be meaningful issuing several warnings in this case.
+
+The \stform of \fx{\XDisableOptions} delays the invalidation of the \ang{opts} until the invocation of \hx{\AtBeginDocument}. 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}.
+
+\start{newmacro}[\XLogDisabledOptions]
+\XLogDisabledOptions<|nang(fams)>
+\finish{newmacro}
+\fxim*{\XLogDisabledOptions}
+
+The command \fx{\XLogDisabledOptions}, which can be called before and after 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.
+
 
 \docsection(sec:normalize)<Normalizing lists>{Normalizing csv and kv lists}
 
@@ -480,17 +598,19 @@ The command \fx{\kv@@normalize} normalizes a list of key-value pairs, returning
 
 \docsection(csv-kv-parse)<Parsing lists>{Parsing csv and kv lists}
 
-\start{newmacro}[\csv@@parse,\kv@@parse]
+\start+{newmacro}[\csv@@loop,\csv@@parse,\kv@@parse]
+\csv@@loop[|nang(parser)][|nang(list)]
+\csv@@loop|*[|nang(parser)][|nang(listcmd)]
 \csv@@parse[|nang(parser)][|nang(list)]
 \csv@@parse|*[|nang(parser)][|nang(listcmd)]
 \kv@@parse[|nang(parser)][|nang(list)]
 \kv@@parse|*[|nang(parser)][|nang(listcmd)]
 \finish{newmacro}
-\fxim*{\csv@@parse,\kv@@parse}
+\fxim*{\csv@@parse,\kv@@parse,\csv@@loop}
 
-The macros \ffx'{\csv@@parse,\kv@@parse} call \ffx'{\csv@@normalize, \kv@@normalize}, respectively. The macro \fx{\csv@@parse} is meant for general csv-list processing with an arbitrary parser, while the command \fx{\kv@@parse} is designed for processing key-value lists. The macros \ffx'{\csv@@parse,\kv@@parse} loop over a given \ang{parser}-separated \ang{list} and execute the user-defined, parametered commands \ffx'{\csv@do,\kv@do}, respectively, for every item in the list, passing the item as an argument and preserving outer braces.
+The macros \ffx'{\csv@@parse,\kv@@parse} (and their \stform+) call \ffx'{\csv@@normalize, \kv@@normalize}, respectively. On the other hand, the macro \fx{\csv@@loop} and its \stform don't call \fx{\csv@@normalize} (since not every list will require normalization). This is the only difference between \fx{\csv@@loop} and \fx{\csv@@parse}. The macros \fx{\csv@@loop} and \fx{\csv@@parse} are meant for general csv-list processing with an arbitrary parser, while the command \fx{\kv@@parse} is designed for processing key-value lists. These macros loop over a given \ang{parser}-separated \ang{list} and execute the user-defined, one-parameter commands \ffx'{\csv@do,\kv@do}, respectively, for every item in the list, passing the item as an argument and preserving outer braces.
 
-The commands \ffx'{\csv@@parse,\kv@@parse} aren't expandable. White spaces before and after the list separator are always ignored. If an item contains \ang{parser} or starts with a space, it must be wrapped in curly braces. The braces will persist thereafter, but will of course be removed during printing (if the items are printed). The default value of \ang{parser} is comma (\qcomma).
+The commands \ffx'{\csv@@loop,\csv@@parse,\kv@@parse} aren't expandable. White spaces before and after the list separator are always ignored. If an item contains \ang{parser} or starts with a space, it must be wrapped in curly braces. The braces will persist thereafter, but will of course be removed during printing (if the items are printed). The default value of \ang{parser} is comma (\qcomma).
 
 The starred variants of \ffx'{\csv@@parse,\kv@@parse} expand \ang{listcmd} once before commencing the loop.
 
@@ -547,17 +667,44 @@ fi
 \finish{example}
 
 
+\docsection(tsv-parse)<Iterating tokenwise>{Parsing \headq{tsv} lists}
+
+\start+{newmacro}[\tsv@@parse,\tsv@@loop]
+\tsv@@loop[|nang(list)]
+\tsv@@loop|*[|nang(listcmd)]
+\tsv@@parse[|nang(list)]
+\tsv@@parse|*[|nang(listcmd)]
+\finish{newmacro}
+\fxim*{\tsv@@parse,\tsv@@loop}
+
+The macros \ffx'{\tsv@@loop,\tsv@@parse} loop over \quoted{non-separated} tokens (tsv-list), picking each token as an argument and applying the one-parameter, user-supplied, function \fx{\tsv@do} to it while preserving outer braces in the item. The macros \ffx'{\tsv@@loop, \tsv@@parse} are meant for general tsv-list processing.
+
+The macros \ffx'{\tsv@@loop,\tsv@@parse} (and their \stform+) of course don't call \fx{\csv@@normalize} or \fx{\kv@@normalize}, but instead they trim leading and trailing spaces of individual tokens/entries. The only difference between \fx{\tsv@@loop} and \fx{\tsv@@parse} is that the former calls \fx{\normal@despace}, while the latter calls \fx{\robust@despace}. The function \fx{\robust@despace} trims all leading and trailing spaces (including chains of implicit spaces) around its argument, while \fx{\normal@despace} trims only one leading and one trailing space around its argument. Both \ffx'{\normal@despace,\robust@despace} preserve outer braces around their arguments. The expandable form of \fx{\normal@despace} is \fx{\xp@despace}.
+
+The starred variants of \ffx'{\tsv@@loop,\tsv@@parse} expand \ang{listcmd} once before commencing the loop.
+
+Empty entries in \ang{list} or \ang{listcmd} will be processed if the boolean \fx{@useempty} is true. You may thus issue the command \fx{\UseEmptyEntry} or \fx{\DiscardEmptyEntry} before commencing the iteration. Both commands \ffx'{\tsv@@loop,\tsv@@parse} can be nested to any level and can be mixed.
+
+
 \docsection(sec:version-hist){Version history}
 
 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.2b}{2011/04/02}
+  \item The following commands have been introduced \secref{sec:options-parse}
+    \start{veritem}
+    \XDeclareInvalidOptions  \XUnknownOptionHandler   \XDisableOptions
+    \XLogDisabledOptions     \ifoptdisabledTF         \ifoptdefTF
+    \finish{veritem}
+
+  \end{version}
   \begin{version}{0.2}{2011/02/15}
   \item For efficiency reasons, canonical control sequences for futurelet characters are no longer defined automatically. The user is now responsible for specifying the canonical control sequences that should be defined.\secref{sec:future-letting}
   \item The following plural-form commands have been introduced \secref{sec:options-parse}
     \start{veritem}
-    \XDeclareOptions \XDeclareCommandOptions \XDeclareBooleanOptions
-    \XDeclareBiBooleanOptions
+    \XDeclareOptions          \XDeclareCommandOptions
+    \XDeclareBooleanOptions   \XDeclareBiBooleanOptions
     \finish{veritem}
 
   \end{version}