catoptions 0.2 (1mar11)

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

3 files changed, 141 insertions, 37 deletions

diff --git a/Master/texmf-dist/doc/latex/catoptions/README b/Master/texmf-dist/doc/latex/catoptions/README
index e75d6b7a377..209718e379d 100644
--- a/Master/texmf-dist/doc/latex/catoptions/README
+++ b/Master/texmf-dist/doc/latex/catoptions/README
@@ -1,15 +1,21 @@
 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. It also provides robust options parsing mechanisms, in addition to many TeX programming tools.
+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. 
+It also provides robust options parsing mechanisms, in addition
+to many TeX programming tools.
 
 AUTHOR
 Ahmed Musa
 
-EARLIER WORKS
-The 'catoptions' package is based on the 'pcatcode' package by Michael J. Downes and David M. Jones.
+RELATED PACKAGES
+The 'catoptions' package is based on the 'pcatcode' package
+by Michael J. Downes and David M. Jones.
 
 VERSION
-Version 0.1, February 2011
+Version 0.2, February 2011
 
 
diff --git a/Master/texmf-dist/doc/latex/catoptions/catoptions-guide.pdf b/Master/texmf-dist/doc/latex/catoptions/catoptions-guide.pdf
index 9018dc051d0..9aeba1d85e3 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 7a7538d17b2..d6d4a9acee6 100644
--- a/Master/texmf-dist/doc/latex/catoptions/catoptions-guide.tex
+++ b/Master/texmf-dist/doc/latex/catoptions/catoptions-guide.tex
@@ -11,7 +11,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.1}
+\version{0.2}
 \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 +19,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 programming macros 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 \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.
 \end{abstract}
 
 \let\licensename\relax
@@ -46,13 +46,33 @@ My motivation for turning to the \pkgnoidx'{pcatcode} was to save myself the tro
 
 \docsection(sec:pkg-options)<Package options>{Package options}
 
-The \pkg'{catoptions} has only two options, namely, \ffx'{verbose, usepox}. The option \fxim{verbose} instructs the package to put information onto the log file when existing commands are being redefined by means of 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.
+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.
+
+
+\extrarowheight=2pt
+\arrayrulecolor{yellow}
+\begin{tabularx}{\linewidth}{|m{3cm}|m{2.5cm}|X|}
+\caption{Package options\xwmlabel{tab:pkgoptions}}\\\hline
+\rowcolor{pink}
+\bfseries Option&\bfseries Default&\bfseries Meaning\\\hline
+\endfirsthead
+\hline
+\multicolumn{3}{|l|}{\emph{Continued from last page}}\\\hline
+\bfseries Option&\bfseries Default&\bfseries Meaning\\\hline
+\endhead
+\multicolumn{3}{|r|}{\emph{Continued on next page}}\\\hline
+\endfoot
+\hline
+\endlastfoot
+\fx{verbose} & \hx{false} & The global boolean switch that determines if information should be logged for some tasks in the package.\\\hline
+\fx{usepox} & \hx{true} & The boolean switch that determines if the options parser of \pkgnoidx{catoptions} should be used for all options processing of packages loaded after \hx{\documentclass} even if those packages are based on \cptuse{latex2e}'s native options processing scheme.\\\hline
+\end{tabularx}
 
 If the \pkg'{catoptions} is loaded before \hx{documentclass}, it will invariably use the options processing mechanism of the package (namely, the more robust commands \ffx'{\XDeclareOption, \XExecuteOptions, \XProcessOptions} in place of \latex's native commands \hhx'{\DeclareOption, \ExecuteOptions, \ProcessOptions})\footnote{The user interfaces of \ffx'{\XDeclareOption, \XExecuteOptions, \XProcessOptions} are similar to those of \hhx'{\DeclareOption, \ExecuteOptions, \ProcessOptions} but they aren't the same. See \cref{sec:options-parse}.}. 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 semantics. This allows expandable options and option values 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 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}.
+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 \qoutedtt{textstyle} and \qoutedtt{name} belong to an existing package (say, \qoutedtt{mypackage}) to be loaded later, then the following example demonstrates one feature of the \pkg'{catoptions}:
+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}:
 
 \start{example}[]
 \RequirePackage[verbose, usepox]{catoptions}
@@ -67,7 +87,7 @@ Assuming that the options \qoutedtt{textstyle} and \qoutedtt{name} belong to an
 
 There are the following user commands for saving and returning category codes of \quoted{other} characters to their previous states:
 
-\start{newmacro}[]
+\start+{newmacro}[]
 \cptnormalcatcodes
 \cptpushcatcodes
 \cptpopcatcodes
@@ -77,7 +97,6 @@ There are the following user commands for saving and returning category codes of
 \finish{newmacro}
 \fxim*{\UseNormalCatcodes,\cptpushcatcodes,\cptpopcatcodes,
 \cptnormalcatcodes,\cptfutureletsetup,\GetCurrentCatcodeSubset}
-\fxim*{\cptfutureletsetup}
 
 The command \fx{\cptnormalcatcodes} simply resets the category codes of all \otherchars together with those of the space character and \fx{\^^I} and \fx{\^^J} to their standard values. The command \fx{\cptpushcatcodes} pushes the current category codes for restitution later with \fx{\cptpopcatcodes}. The command \fx{\UseNormalCatcodes} works only in packages and does more than one thing: it calls \ffx'{\cptpushcatcodes, \cptnormalcatcodes,\cptfutureletsetup} in that order. At the end of the package, it automatically issues \fx{\cptpopcatcodes} to recover all the category codes earlier pushed. The command \fx{\UseNormalCatcodes} can conveniently be issued at the start of the package and the developer can be assured of access to the standard category codes of all \otherchars together with those of the space character and \fx{\^^I} and \fx{\^^J}. It should be called only once in a package: subsequent calls will have no effect.
 
@@ -101,7 +120,7 @@ to see the current catcode setup. The command \fx{\cptfutureletsetup} is describ
 
 \docsection(sec:future-letting){Future-letting of \headq{other} characters}
 
-The command \fx{\cptfutureletsetup} defines canonical control sequences to represent all the visible ASCII characters (ranging from space to \fx{~} and 32--126 characters):
+The command \fx{\cptfutureletsetup} defines canonical control sequences to represent the  following characters:
 
 \start'{example}[Futurelet characters]
 space|R(|textvisiblespace) exclam|R(!) dblquote|R(") hash|R(#) dollar|R($) ampersand|R(|ampersand)
@@ -112,23 +131,49 @@ bslash|R(\)
 \finish{example}
 %\fxim*{\cptfutureletsetup}
 
-The defined commands have the syntaxes
+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
+
+\start{newmacro}[\declarefutureletset]
+\declarefutureletset[|nang(stub)]{|nang(set)}
+\finish{newmacro}
+
+Here, \ang{set} is a comma-separated list of names from the \quoted{other} characters listed above. The defined commands are prefixed with an optional \ang{stub}, whose default value is \fx{fl@}. The defined commands have the syntaxes
 
 \start'{newmacro}[Futurelet characters]
 \|nang(stub)|nang(char)
 \if|nang(stub)|nang(char)
 \finish{newmacro}
 
-They are prefixed with \ang{stub} which can be set with the command
+For efficiency gains, a call to \fx{\cptfutureletsetup} automatically undefines all the canonical control sequences previously defined with a call to \fx{\cptfutureletsetup}---before the new canonical control sequences are defined.
 
-\start{newmacro}[\declarefutureletprefix]
-\declarefutureletprefix{|nang(stub)}
-\finish{newmacro}
-\fxim*{\declarefutureletprefix}
+For instance, with the choices
 
-For instance, with the choice \fx{\declarefutureletprefix{fl@}}, we have the following commands on hand for testing after \fx{\futurelet}. If any of the commands emanating from \ang{stub}, concatenated with the name of the character, is already defined, an error message is flagged. It should be noted that these commands are available only after issuing the command \fx{\cptfutureletsetup}, which is called automatically at \hx{\AtBeginDocument}. At \hx{\AtBeginDocument} the \pkg'{catoptions} calls \fx{\cptrestorecatcodes}, followed by \fx{\cptfutureletsetup}.
+\start{example}[\declarefutureletset]
+\declarefutureletset[fl@]{space, star, lbracket}
+\cptfutureletsetup
+\finish{example}
+
+we have the following commands on hand for testing after \fx{\futurelet}:
 
 \start+{newmacro}[Futurelet commands]
+\fl@space       \fl@star       \fl@lbracket
+\iffl@space     \iffl@star     \iffl@lbracket
+\finish{newmacro}
+\fxim*{Futurelet commands}
+
+If any of the commands emanating from concatenating \ang{stub} with the name of the character is already defined, an error message is flagged. It should be noted that these commands are available only after issuing the command \fx{\cptfutureletsetup}, which isn't called automatically anywhere by the \pkg'{catoptions}. Normally, at \hx{\AtBeginDocument} the \pkg'{catoptions} calls the command \fx{\cptrestorecatcodes}, without calling \fx{\cptfutureletsetup}. Calling \ffx'{\declarefutureletset, \cptfutureletsetup} is the user's duty.
+
+The commands \ffx'{\declarefutureletset, \cptfutureletsetup} are decoupled to allow the user to call \fx{\declarefutureletset} only once, and perhaps much earlier, before calling the command \fx{\cptfutureletsetup} as often as desired.
+
+An inefficient call of the form
+
+\start{example}[\declarefutureletset]
+\declarefutureletset[fl@]{|R(all)}
+\finish{example}
+
+where \quotedtt{all} means that control sequences should be defined for all the available \quoted{other} characters, will define all the following control sequences whenever \fx{\cptfutureletsetup} is called:
+
+\start+{example}[Futurelet commands]
 \fl@space         \fl@exclam        \fl@dblquote      \fl@hash
 \fl@dollar        \fl@ampersand     \fl@lrquote       \fl@lparen
 \fl@rparen        \fl@star          \fl@plus          \fl@comma
@@ -137,11 +182,7 @@ For instance, with the choice \fx{\declarefutureletprefix{fl@}}, we have the fol
 \fl@question      \fl@lbracket      \fl@rbracket      \fl@hat
 \fl@underscore    \fl@lquote        \fl@lbrace        \fl@vert
 \fl@rbrace        \fl@tilde         \fl@bslash
-\finish{newmacro}
-
-The \pkg'{catoptions} has already defined these test macros. To further aid testing, the following commands are defined by the \pkg'{catoptions}:
 
-\start+{newmacro}[Futurelet commands]
 \iffl@space       \iffl@exclam      \iffl@dblquote    \iffl@hash
 \iffl@dollar      \iffl@ampersand   \iffl@lrquote     \iffl@lparen
 \iffl@rparen      \iffl@star        \iffl@plus        \iffl@comma
@@ -150,10 +191,12 @@ The \pkg'{catoptions} has already defined these test macros. To further aid test
 \iffl@question    \iffl@lbracket    \iffl@rbracket    \iffl@hat
 \iffl@underscore  \iffl@lquote      \iffl@lbrace      \iffl@vert
 \iffl@rbrace      \iffl@tilde       \iffl@bslash
-\finish{newmacro}
+\finish{example}
 \fxim*{Futurelet commands}
 
-The use syntaxes for these commands are as follows:
+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:
 
 \start{example}[Futurelet characters]
 \futurelet\next\cmd |textbf(|R(*))
@@ -251,6 +294,14 @@ The following example produces a warning when the user supplies an option that w
   `\CurrentOption' ignored}}
 \finish{example}
 
+\start{newmacro}[\XDeclareOptions]
+\XDeclareOptions<|nang(fam)>{|nang(options)}[|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.
+
+
 \start{newmacro}[\XDeclareCommandOption]
 \XDeclareCommandOption<|nang(fam)>{|nang(option)}[|nang(default)]|(pref|){|nang(fn)}
 \finish{newmacro}
@@ -258,6 +309,13 @@ The following example produces a warning when the user supplies an option that w
 
 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}.
 
+\start{newmacro}[\XDeclareCommandOptions]
+\XDeclareCommandOptions<|nang(fam)>{|nang(options)}[|nang(default)]|(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}.
+
 
 \start{newmacro}[\XDeclareBooleanOption]
 \XDeclareBooleanOption<|nang(fam)>{|nang(option)}[|nang(default)]|(pref|){|nang(fn)}
@@ -266,6 +324,21 @@ The command \fx{\XDeclareCommandOption} will, apart from declaring the option \a
 
 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.
 
+\start{newmacro}[\XDeclareBooleanOptions]
+\XDeclareBooleanOptions<|nang(fam)>{|nang(options)}[|nang(default)]|(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}.
+
+
+\start{newmacro}[\XDeclareBiBooleanOptions]
+\XDeclareBiBooleanOptions<|nang(fam)>{|nang(opt1),|nang(opt2)}[|nang(default)]|(pref|){|nang(fn1)}{|nang(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)}
@@ -287,7 +360,7 @@ This initializes \hx{\leftmargin} to 0pt.
 \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. 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{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 \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.
 
@@ -302,13 +375,18 @@ The implementation here differs significantly from the \latex kernel's scheme of
 |com(to avoid option clash with another loading of the package in the document.)
 |makepurple(% \RequirePackage{catoptions})
 \UseNormalCatcodes
-\newvariables{if}{bool}{a,b}
-\XDeclareOption<testclass>{boola}[true]{\cptuse{boola#1}}
+\newif\ifboola
+\XDeclareOption<testclass>{boola}[true]{%
+  \@nameuse{boola#1}%
+  \ifboola\let\eat\@gobble\fi
+}
+|com(No need for \newif when declaring boolean options:)
 \XDeclareBooleanOption<testclass>{boolb}[true]|(test@|){%
   \iftest@boolb
     \AtEndOfPackage{\gdef\tex{\TeX\xspace}}%
   \fi
 }
+\XDeclareBiBooleanOptions{draft,final}[true](test@){}{}
 \XDeclareCommandOption<testclass>{color}[blue]|(test@|){%
   \def\text{\textcolor{\test@color}{Result of test}}%
 }
@@ -337,11 +415,19 @@ The implementation here differs significantly from the \latex kernel's scheme of
 \endinput
 
 |com(This is a sample document:)
-\RequirePackage[usepox,align=right,boola=false,boolb]{catoptions}
-\documentclass[name={Mr J\"avier Claudioos},a4paper,draft,10pt]{testclass}
-|com(You can use \usepackage{catoptions} as below, but then the)
-|com(\documentclass option `name={Mr J\"avier Claudioos}' can't be processed:)
-|makepurple(% \usepackage[usepox,align=right,boola=false,boolb]{catoptions})
+\RequirePackage[usepox]{catoptions}
+\documentclass[
+  align     = right,
+  boola     = false,
+  boolb     = true,
+  name      = {Mr J\"avier Claudioos},
+  a4paper,
+  draft,
+  10pt
+]{testclass}
+|com(You can call \usepackage{catoptions}, instead of)
+|com(\RequirePackage{catoptions}, after \documentclass, but then the)
+|com(\documentclass option `name={Mr J\"avier Claudioos}' can't be processed.)
 \usepackage{cleveref}
 
 \begin{document}
@@ -349,9 +435,10 @@ The implementation here differs significantly from the \latex kernel's scheme of
 \end{document}
 \finish{example}
 
+
 \docsection(sec:normalize)<Normalizing lists>{Normalizing csv and kv lists}
 
-Any arbitrary comma-separated-values (csv) list can be normalized by using \fx{\csv@@normalize} before processing the list.
+Any arbitrary parser-separated-values list can be normalized by means of package the command \fx{\csv@@normalize} before processing the list.
 
 \start{newmacro}[\csv@@normalize]
 \csv@@normalize[|nang(parser)]{|nang(list)}
@@ -377,7 +464,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-values, returning the result in the macro \fx{\normalized@kvlist} (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@kvlist} (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}.
 
 \start{example}[\csv@@normalize]
 \begingroup
@@ -444,8 +531,8 @@ The following is a pseudocode that depicts the use of \fx{\kv@@parse}:
 \def\kv@do#1{%
   \def\CurrentOption{#1}%
   if \CurrentOption is not empty then
-    split \CurrentOption into option and value
-    search if option exists in \@declaredoptions
+    split \CurrentOption into option and value;
+    search if option exists in \@declaredoptions;
     if option is found then
       Execute the option's function
     else
@@ -462,7 +549,18 @@ fi
 
 \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.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
+    \finish{veritem}
+
+  \end{version}
   \begin{version}{0.1}{2011/01/25}
   \item First public release.
   \end{version}