new latex package catoptions (7feb11)

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

3 files changed, 493 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/latex/catoptions/README b/Master/texmf-dist/doc/latex/catoptions/README
new file mode 100644
index 00000000000..e75d6b7a377
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/catoptions/README
@@ -0,0 +1,15 @@
+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.
+
+AUTHOR
+Ahmed Musa
+
+EARLIER WORKS
+The 'catoptions' package is based on the 'pcatcode' package by Michael J. Downes and David M. Jones.
+
+VERSION
+Version 0.1, February 2011
+
+
diff --git a/Master/texmf-dist/doc/latex/catoptions/catoptions-guide.pdf b/Master/texmf-dist/doc/latex/catoptions/catoptions-guide.pdf
new file mode 100644
index 00000000000..9018dc051d0
--- /dev/null
+++ 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
new file mode 100644
index 00000000000..7a7538d17b2
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/catoptions/catoptions-guide.tex
@@ -0,0 +1,478 @@
+\documentclass[a4paper,10pt,final,language=UKenglish,fancysec,framesecno,
+  parabst,inputcfg]{amltxdoc}
+\makeatletter
+\WrapQuotes
+\NoPrintNotes
+\makeindex
+
+\begin{document}
+
+\begin{frontmatter}
+\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}
+\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}
+
+\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.
+\end{abstract}
+
+\let\licensename\relax
+\begin{license}
+\xwmcolorbox[textalign=justified,outerframecolor=blue,innerframecolor=orange,width=.985\hsize]{%
+  This work (\ie, all the files in the \pkg'{catoptions} bundle) may be distributed and/or modified under the conditions of the \lppl, either version~1.3 of this license or any later version.
+  \endgraff
+  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 implied warranties of merchantability and fitness for a particular purpose.
+  \endgraf
+  \centerline{\makered{\CopyrightYear}}\vspace{-.8\baselineskip}\relax
+}
+\end{license}
+\end{frontmatter}
+
+\begin{xwmshade}[fillcolor=white,framecolor=orange,framerule=1pt,framesep=2pt,
+  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.
+
+
+\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.
+
+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}.
+
+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}:
+
+\start{example}[]
+\RequirePackage[verbose, usepox]{catoptions}
+\documentclass[textstyle=\ttfamily,name={Mr X\"avier Sanchez},a4paper,
+  draft,10pt]{article}
+\usepackage{mypackage}
+\finish{example}
+\fxim*{\RequirePackage,\usepackage,\documentclass}
+
+
+\docsection(sec:saving-catcodes){Saving and restituting category codes}
+
+There are the following user commands for saving and returning category codes of \quoted{other} characters to their previous states:
+
+\start{newmacro}[]
+\cptnormalcatcodes
+\cptpushcatcodes
+\cptpopcatcodes
+\UseNormalCatcodes
+\GetCurrentCatcodeSubset
+\cptfutureletsetup
+\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.
+
+After issuing the command \fx{\GetCurrentCatcodeSubset}, you can do
+
+\start{example}[]
+\show\currentcatcodesubset
+\finish{example}
+\fxim*{\currentcatcodesubset}
+
+to see the current catcode setup. The command \fx{\cptfutureletsetup} is described in \cref{sec:future-letting}.
+
+\start{example}[\UseNormalCatcodes]
+\ProvidesPackage{mypackage}[2011/01/16 v0.01]
+\NeedsTeXFormat{LaTeX2e}[1995/12/01]
+\RequirePackage[verbose, usepox]{catoptions}
+\UseNormalCatcodes
+\finish{example}
+%\fxi*{\UseNormalCatcodes}
+
+
+\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):
+
+\start'{example}[Futurelet characters]
+space|R(|textvisiblespace) exclam|R(!) dblquote|R(") hash|R(#) dollar|R($) ampersand|R(|ampersand)
+lrquote|R(') lparen|R(|() rparen|R(|)) star|R(*) plus|R(+) comma|R(,) hyphen|R(-) period|R(.)
+slash|R(/) colon|R(:) semicolon|R(;) less|R(<) equal|R(=) greater|R(>) question|R(?) lbracket|R([)
+rbracket|R(]) hat|R(^) underscore|R(_) lquote|R(`) lbrace|R({) vert|R(|rv) rbrace|R(}) tilde|R(~)
+bslash|R(\)
+\finish{example}
+%\fxim*{\cptfutureletsetup}
+
+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
+
+\start{newmacro}[\declarefutureletprefix]
+\declarefutureletprefix{|nang(stub)}
+\finish{newmacro}
+\fxim*{\declarefutureletprefix}
+
+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+{newmacro}[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
+\fl@hyphen        \fl@period        \fl@slash         \fl@colon
+\fl@semicolon     \fl@less          \fl@equal         \fl@greater
+\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
+\iffl@hyphen      \iffl@period      \iffl@slash       \iffl@colon
+\iffl@semicolon   \iffl@less        \iffl@equal       \iffl@greater
+\iffl@question    \iffl@lbracket    \iffl@rbracket    \iffl@hat
+\iffl@underscore  \iffl@lquote      \iffl@lbrace      \iffl@vert
+\iffl@rbrace      \iffl@tilde       \iffl@bslash
+\finish{newmacro}
+\fxim*{Futurelet commands}
+
+The use syntaxes for these commands are as follows:
+
+\start{example}[Futurelet characters]
+\futurelet\next\cmd |textbf(|R(*))
+\def\cmd{\ifx\fl@star\next `I saw star'\else `I didn't see star'\fi}
+\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@}.
+
+After setting up \fx{\futurelet} characters with \fx{\cptfutureletsetup}, you can reset active characters to catcode~13 by \fx{\futureletresetactives}.
+
+
+\docsection(sec:package-prelim){Setting up package preliminaries}
+
+Every package normally requires some preliminary declarations, such as seen below. The commands \ffx'{\StyleFilePurpose, \StyleFileRCSInfo, \StyleFileInfo, \SetStyleFileMessages} are defined by the \pkg'{catoptions}. All of them have intuitive syntaxes, except the command \fx{\SetStyleFileMessages}, whose syntax is explained below.
+
+\start{example}[Package preliminaries]
+\StyleFilePurpose{A collection of useful commands}
+\StyleFileRCSInfo
+$Id: mypackage.sty,v 0.1 2011/01/01 09:00:00 My Name Exp $
+\ProvidesPackage{mypackage}[\StyleFileInfo]
+\NeedsTeXFormat{LaTeX2e}[1996/12/01]
+\SetStyleFileMessages[mypack@]{err}{warn}{info}
+\finish{example}
+
+\start{newmacro}[\SetStyleFileMessages]
+\SetStyleFileMessages[|nang(stub)]{|nang(err)}{|nang(warn)}{|nang(info)}
+\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.
+
+For instance, with the declaration
+
+\start{example}[\SetStyleFileMessages]
+\SetStyleFileMessages[mypack@]{error}{warning}{info}
+\finish{example}
+
+the following commands are automatically defined by the \pkg'{catoptions}:
+
+\start{example}[\SetStyleFileMessages]
+\mypack@error     |tto    Error message of two parameters
+\mypack@warning   |tto    Warning message of one parameter
+\mypack@info      |tto    Information message of one parameter
+\finish{example}
+
+The commands \ffx'{\mypack@error,\mypack@info} can be used as follows:
+
+\start{example}[\SetStyleFileMessages]
+\ifcptonetokenTF{#1}{%
+  \mypack@info{Correct single argument `\detokenize{#1}': accepted}%
+}{%
+  \mypack@error{Multiple arguments `\detokenize{#1}'}%
+    {Invalid multiple arguments `\detokenize{#1}' rejected}%
+}
+\finish{example}
+
+
+\docsection(sec:options-parse){Options parsing}
+
+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(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}.
+
+\start{example}[\XDeclareOption]
+\ProvidesPackage{mypackage}[\StyleFileInfo]
+\newif\ifmybool
+\XDeclareOption{mybool}[true]{\@nameuse{mybool#1}}
+\XDeclareOption{leftmargin}[.5\hsize]{\setlength\leftmargin{#1}}
+\finish{example}
+
+The options \ffx'{mybool,leftmargin} could then be called via any of the following statements:
+
+\start{example}[\XDeclareOption]
+|com(Inside class or package files:)
+\RequirePackage[mybool=true,leftmargin=20\p@]{mypackage}
+|com(Inside document file:)
+\usepackage[mybool=false,leftmargin=20\p@]{mypackage}
+|com(Via document class:)
+\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 following example produces a warning when the user supplies an option that was not previously declared.
+
+\start{example}[\XDeclareOption*]
+\XDeclareOption|*{\PackageWarningNoLine{mypackage}{Unknown option
+  `\CurrentOption' ignored}}
+\finish{example}
+
+\start{newmacro}[\XDeclareCommandOption]
+\XDeclareCommandOption<|nang(fam)>{|nang(option)}[|nang(default)]|(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}.
+
+
+\start{newmacro}[\XDeclareBooleanOption]
+\XDeclareBooleanOption<|nang(fam)>{|nang(option)}[|nang(default)]|(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.
+
+
+\start{newmacro}[\XExecuteOptions]
+\XExecuteOptions<|nang(fam)>{|nang(options)}
+\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}.
+
+\start{example}[\XExecuteOptions]
+\XExecuteOptions{leftmargin=0pt}
+\finish{example}
+%\fxi*{\XExecuteOptions}
+
+This initializes \hx{\leftmargin} to 0pt.
+
+\start{newmacro}[\XProcessOptions]
+\XProcessOptions<|nang(fam)>[|nang(na)]
+\XProcessOptions|*<|nang(fam)>[|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. 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 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,)
+|com(instead of using the default family |(testclass.sty|).)
+\ProvidesClass{testclass}[2011/01/15 v1.0 A test class]
+\NeedsTeXFormat{LaTeX2e}
+|com(The following loading of `catoptions' may need to be commented out)
+|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}}
+\XDeclareBooleanOption<testclass>{boolb}[true]|(test@|){%
+  \iftest@boolb
+    \AtEndOfPackage{\gdef\tex{\TeX\xspace}}%
+  \fi
+}
+\XDeclareCommandOption<testclass>{color}[blue]|(test@|){%
+  \def\text{\textcolor{\test@color}{Result of test}}%
+}
+\XDeclareOption<testclass>{align}[left]{%
+  \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'.
+        }%
+      }%
+    }%
+  }%
+}
+\XDeclareOption*<testclass>{\PassOptionsToClass{\CurrentOption}{article}}
+\XExecuteOptions<testclass>{boola,boolb}
+\XProcessOptions*<testclass>\relax
+\LoadClass{article}
+\RequirePackage{xcolor}
+\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})
+\usepackage{cleveref}
+
+\begin{document}
+ Blackberry bush ... blackberry-lily.
+\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.
+
+\start{newmacro}[\csv@@normalize]
+\csv@@normalize[|nang(parser)]{|nang(list)}
+\csv@@normalize|*[|nang(parser)]|nang(listcmd)
+\finish{newmacro}
+\fxim*{\csv@@normalize}
+
+Here, \ang{list}, which is populated by parser-separated elements, is not expanded before normalization; \ang{listcmd}, on the other hand, is expanded once before normalization. The default value of the optional \ang{parser} is~\qcomma (comma). \quoted{Normalization} implies changing the category codes of all the active parsers to their standard values, as well as trimming leading and trailing spaces around the elements of the list and removing consecutive multiple parsers. Thus empty entries that are not enforced by curly braces are removed. The result (\ie, normalized list) is available in the macro \fx{\normalized@csvlist} (in the \unstform case) or \ang{listcmd} (in the \stform case).
+
+\start{example}[\csv@@normalize]
+\begingroup
+\catcode`\;=\active
+\gdef\x{x ;  ;  {y}; ;  z}
+\endgroup
+
+\csv@@normalize*[;]\x
+|com(\show\x)
+\finish{example}
+
+\start{newmacro}[\kv@@normalize]
+\kv@@normalize[|nang(parser)]{|nang(list)}
+\kv@@normalize|*[|nang(parser)]|nang(listcmd)
+\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}.
+
+\start{example}[\csv@@normalize]
+\begingroup
+\catcode`\;\string=\active
+\catcode`\=\string=\active
+\gdef\x{x=A ; ;  y=={B} ; ;  z=C}
+\endgroup
+
+\kv@@normalize*[;]\x
+|com(\show\x)
+\finish{example}
+
+
+\docsection(csv-kv-parse)<Parsing lists>{Parsing csv and kv lists}
+
+\start{newmacro}[\csv@@parse,\kv@@parse]
+\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}
+
+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 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 starred variants of \ffx'{\csv@@parse,\kv@@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. Issuing any of these commands prior to the commencement of the loop is recommended, because a previous call to either \fx{\csv@@parse} or \fx{\kv@@parse} (perhaps by another package) could have set \fx{@useempty} to a state that is no longer valid or desired. Both \ffx'{\csv@@parse,\kv@@parse} will execute at least once for empty \ang{list} or \ang{listcmd}. Both commands \ffx'{\csv@@parse,\kv@@parse} can be nested to any level and can be mixed.
+
+\start{example}[\csv@@parse]
+\begingroup
+\catcode`\;=\active
+\gdef\x{a ;  ;  {b}; ;  c}
+\endgroup
+
+\@tempcnta\z@
+\def\csv@do#1{%
+  \advance\@tempcnta\@ne
+  \@namedef{x@\romannumeral\@tempcnta}{#1}%
+}
+\csv@@parse*[;]\x
+|com(\show\x@ii)
+
+\def\xa{a,b,c}
+\def\xb{x,y,z}
+\def\csv@do#1{%
+  \pushnumber\nra
+  \csn@edef{arg@\romannumeral\nra}{#1}%
+  \let\nrb\z@
+  \def\csv@do##1{%
+    \pushnumber\nrb
+    \csn@edef{arg@\romannumeral\nra @\romannumeral\nrb}{#1,##1}%
+  }%
+  \csv@@parse*\xb
+}
+\csv@@parse*\xa
+\finish{example}
+
+The following is a pseudocode that depicts the use of \fx{\kv@@parse}:
+
+\start{example}[\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
+    if option is found then
+      Execute the option's function
+    else
+      Report option as unknown
+    fi
+  fi
+}
+|com(\kv@@parse will normalize \@classoptions before parsing it:)
+if there are declared options then
+  \kv@@parse*\@classoptions
+fi
+\finish{example}
+
+
+\docsection(sec:version-hist){Version history}
+
+\begin{versionhist}
+  \begin{version}{0.1}{2011/01/25}
+  \item First public release.
+  \end{version}
+
+\end{versionhist}
+
+\newpage
+\indexpreamble{Index numbers refer to page numbers.}
+\indexpreambleformat{\centering}
+\indexcolumns\tw@
+\printindex
+
+\end{document} 
\ No newline at end of file