keyreader 0.2 (14jan10)

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

4 files changed, 65 insertions, 24 deletions

diff --git a/Master/texmf-dist/doc/latex/keyreader/README b/Master/texmf-dist/doc/latex/keyreader/README
index b5fdc5d981b..f8b3c25df38 100644
--- a/Master/texmf-dist/doc/latex/keyreader/README
+++ b/Master/texmf-dist/doc/latex/keyreader/README
@@ -18,7 +18,7 @@
 %                                                                                    %
 %+++++++++++++++++++++++++++++++++++++ LICENSE ++++++++++++++++++++++++++++++++++++++%
 %                                                                                    %
-% This is file 'keyreader.sty', version 0.1.                                         %
+% This is file 'keyreader.sty', version 0.2.                                         %
 %                                                                                    %
 % This package reads multiple keys to be defined by xkeyval.sty.                     %
 %                                                                                    %
diff --git a/Master/texmf-dist/doc/latex/keyreader/keyreader-guide-0dot2.pdf b/Master/texmf-dist/doc/latex/keyreader/keyreader-guide-0dot2.pdf
new file mode 100644
index 00000000000..d85c1c17a05
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/keyreader/keyreader-guide-0dot2.pdf
diff --git a/Master/texmf-dist/doc/latex/keyreader/keyreader-guide.tex b/Master/texmf-dist/doc/latex/keyreader/keyreader-guide-0dot2.tex
index a11013decd3..2ac2ad0cc4f 100644
--- a/Master/texmf-dist/doc/latex/keyreader/keyreader-guide.tex
+++ b/Master/texmf-dist/doc/latex/keyreader/keyreader-guide-0dot2.tex
@@ -18,7 +18,6 @@
 \date{\textcolor{purple}{\today}\vadjust{\kern0ex}}
 \newcommand*\krsty[1]{\textcolor{xgreen1}{\texttt{#1}}\xspace}
 \newcommand*\krcmd[1]{\textcolor{xteal1}{\texttt{\@backslashchar#1}}\xspace}
-\newcommand*\krcs[1]{\textcolor{xteal1}{\texttt{\string#1}}\xspace}
 \hypersetup{colorlinks=true,linkcolor=red,pdfpagemode=UseThumbs,
   implicit=true,breaklinks=true,pagebackref=true,backref=true,
   bookmarks=true,bookmarksnumbered=true,hyperfootnotes=true,debug=true,
@@ -31,7 +30,7 @@
 
 \begin{document}
 \DefineShortVerb{\+}
-\title{The \texttt{\color{blue}keyreader} Package\footnote{Version 0.1.}}
+\title{The \texttt{\color{blue}keyreader} Package\footnote{Version 0.2.}}
 \author{Ahmed Musa\\\email{a.musa@rocketmail.com}}
 \maketitle
 \thispagestyle{empty}
@@ -46,9 +45,8 @@
 
 \section{Motivation}
 
-The elaborate and powerful \krsty{xkeyval} package introduced \krcmd{define@cmdkeys} and
-\krcmd{define@boolkeys}, which permit the setting of multiple command keys and
-boolean keys, but in each category those keys must have the same default value
+The elaborate and powerful \krsty{xkeyval} package provides
+\krcmd{define@cmdkeys} and \krcmd{define@boolkeys} for defining and setting multiple command keys and boolean keys, but in each category those keys must have the same default value
 and no key macro/function. This package seeks to remove these restrictions,
 so that multiple keys of all categories (ordinary keys, command keys, boolean
 keys, and choice keys) can be set at one go and those keys can have different
@@ -62,7 +60,7 @@ key macros to the complementary keys.
 
 \section{Usage}
 
-The package can be loaded in style files by
+The package can be loaded in style and class files by
 \begin{krverbatim}
 \RequirePackage[options]{keyreader}
 \end{krverbatim}
@@ -72,12 +70,13 @@ and in document files via
 \end{krverbatim}
 where the options and their default values are
 \begin{krverbatim}
-parser=;, macroprefix=mp@, keyprefix=KV, keyfamily=myfamily.
+parser=;, macroprefix=mp@, keyprefix=KV, keyfamily=myfamily, 
+xchoicelist=false.
 \end{krverbatim}
 The \krsty{parser} is the separator between the keys in the key list to be defined in one go (see examples in section~\ref{sec:examples}). All these options can be set dynamically by using the \krcmd{krsetup} macro:
 \begin{krverbatim}
-\krsetup{parser=;,macroprefix=mp@,keyprefix=KV,
-  keyfamily=myfamily}.
+\krsetup{parser=;, macroprefix=mp@, keyprefix=KV,
+  keyfamily=myfamily, xchoicelist=false}.
 \end{krverbatim}
 
 The main user interface is the \krcmd{define@keylist} macro, whose syntax is
@@ -94,34 +93,54 @@ If the key list is available in a macro, say,
 \def\keylist{<key type/id>, <key>, <key value>,
   <key macro/function>; <another set of key specifiers>; etc},
 \end{krverbatim}
-then the keys can be defined by
+then the keys can be defined by the starred form of \krcmd{define@keylist}:
 \begin{krverbatim}
-\cmddefine@keylist\keylist.
+\define@keylist*\keylist.
 \end{krverbatim}
-\krcmd{cmddefine@keylist} takes a macro as argument, while \krcmd{define@keylist} accepts a key list.
+\krcmd{define@keylist*} takes a macro as argument, while \krcmd{define@keylist} accepts a key list.
 
-The \krcmd{kr@altlist} macro is needed for choice keys; it lists the alternate
+The \krcmd{ChoiceKeyValues} macro is needed for choice keys; it lists the alternate
 admissible values for a choice key and thus can't be empty when a choice key
-is being defined or set. It has to be defined or redefined each time a choice
-key is being defined, if its contents (ie, those of \krcmd{kr@altlist}) change from
-one choice key to the next one being defined. This, unfortunately, implies the restriction that no two choice keys can appear in one \krcmd{define@keylist} statement. This restriction can be easily lifted but at the cost of some complication and extra requirement for the package user. So far this hasn't been a severe limitation (to me, anyway).
+is being defined. Its syntax is
+\begin{krverbatim}
+\ChoiceKeyValues{<key>}{<admissible key values>}.
+\end{krverbatim}
+To save tokens, the abbreviation \krcmd{CKVS} is provided for \krcmd{ChoiceKeyValues} and may be used in place of \krcmd{ChoiceKeyValues}.
+
+It has to be defined each time a choice key is being defined. For example, if we want to define two choice keys \krsty{align} and \krsty{election}, then before the call to \krcmd{define@keylist}, we have to set
+\begin{krverbatim}
+\CKVS{align}{center,right,left,justified}
+\CKVS{election}{state,federal,congress,senate}.
+\end{krverbatim}
+It doesn't matter which choice key first gets a \krcmd{CKVS}. The prevailing key family, obtainable from  \krcmd{kr@keyfamily}, is used internally by \krcmd{ChoiceKeyValues} to build distinct alternate values lists for choice keys. Unless the key family changes, you can't set two \krcmd{ChoiceKeyValues} for the same choice key. This will be possible only if the package option \krsty{xchoicelist} (meaning ``allow overwriting of choice list'') has been set \krsty{true}, either through \krcmd{documentclass}, \krcmd{usepackage}, or \krcmd{krsetup}.
+
+As mentioned earlier, the key family (and other package options) can be changed via
+\begin{krverbatim}
+\krsetup{parser=;,macroprefix=mp@,keyprefix=KV,
+  keyfamily=myfamily,xchoicelist=false}.
+\end{krverbatim}
+
+Thus any number of choice keys can appear in one \krcmd{define@keylist} statement if their lists of alternate/admissible values have been set by \krcmd{CKVS}.
+
+In line with the philosophy of the \krsty{xkeyval} package, all the choice keys to be defined using this package require \krcmd{ChoiceKeyValues}: choice keys by definition have pre-ordained or acceptable values.
 
 \section{Examples}
 \label{sec:examples}
 
 Suppose we wish to define a set of keys \krsty{\{color,angle,scale,align\}}. The keys \krsty{color}, \krsty{angle} and \krsty{scale} will de defined using command keys, while the key \krsty{align} will be defined by choice keys. Assume that the \krsty{align} key can only assume the values \krsty{\{center,right,left,justified\}}, where the first three values would further imply \krcmd{centering}, \krcmd{flushright}, and \krcmd{flushleft}, respectively. Moreover, we assume that the key \krsty{scale} will be associated with a macro called \krcmd{mydo}, where \krcmd{do} is assumed defined elsewhere. The keys \krsty{color} and \krsty{angle} aren't associated with macros. Then we can go:
 \begin{krverbatim}
-\def\kr@altlist{center,right,left,justified}
+\CKVS{align}{center,right,left,justified}
 
 \def\f@align{%
-  \ifcase\kr@nr\relax
+  \ifcase\nr\relax
     \def\kr@align{\centering}%
   \or
     \def\kr@align{\flushright}%
   \or
     \def\kr@align{\flushleft}%
   \or
-    \let\kr@align\relax\fi
+    \let\kr@align\relax
+  \fi
 }
 
 \define@keylist{2,color,gray!25,;2,angle,45,;
@@ -138,7 +157,9 @@ Hundreds of keys can be defined efficiently in this way, using very few tokens.
 
 As another example, we consider the following page setup keys:
 \begin{krverbatim}
-\def\kr@altlist{center,right,left,justified} % reused
+\CKVS{align}{center,right,left,justified}
+\CKVS{election}{state,federal,congress,senate}
+% |color(gray)need to be defined only once|normalcolor
 
 \define@keylist{%
   3,boolvar,true,;1,paperheight,\paperheight,;
@@ -147,6 +168,7 @@ As another example, we consider the following page setup keys:
   2,textwidth,\textwidth,\f@textwidth;
   1,evensidemargin,\evensidemargin,;
   4,align,center,\f@align;
+  4,election,congress,;
   2,testdim,2cm,\long\def\f@testdim##1{A test dimension ##1
     \par\bigskip}%
 }
@@ -167,7 +189,7 @@ which have the following trivial key macros:
 \def\f@paperwidth{\wlog{`paperwidth' was defined as %
   ordinary key.}}
 \newcommand\f@align{%
-  \ifcase\kr@nr\relax
+  \ifcase\nr\relax
     \def\mp@align{\centering}%
   \or
     \def\mp@align{\flushright}%
@@ -180,6 +202,23 @@ which have the following trivial key macros:
 \end{krverbatim}
 Again, once the keys have been defined, these macros can be reused.
 
+The same set of keys can be defined via the starred form of \krcmd{define@keylist}:
+\begin{krverbatim}
+\def\keylist{%
+  3,boolvar,true,;1,paperheight,\paperheight,;
+  1,paperwidth,\paperwidth,\f@paperwidth;
+  2,textheight,\textheight,\f@textheight;
+  2,textwidth,\textwidth,\f@textwidth;
+  1,evensidemargin,\evensidemargin,;
+  4,align,center,\f@align;
+  4,election,congress,;
+  2,testdim,2cm,\long\def\f@testdim####1%
+    {Do something with ####1}%
+    % |color(gray) Note the number of parameter characters here.
+}
+\define@keylist*\keylist.
+\end{krverbatim}
+
 Since the keys have been defined, they can now be set. In the following, we set only two of the keys:
 \begin{krverbatim}
 \setkeys[KV]{myfamily}{align=right,testdim=3cm}
@@ -211,7 +250,9 @@ After defining and setting the keys above, the following tokens can be used in a
 \begin{krverbatim}
 \begin{center}
   \begin{minipage}{\mp@textwidth}
-    \lipsum[1] % from the lipsum package
+    \lipsum[1]
+      % |color(gray)From the |emph(lipsum) package.
+      % |color(gray)The |emph(blindtext) package can also be used.
   \end{minipage}
 \end{center}
 
@@ -300,7 +341,7 @@ and then do
 \begin{krverbatim}
 \define@keylist{3,boolone,true,\f@boolone},
 \end{krverbatim}
-which will execute \krcmd{f@boolone} when the key \krsty{boolone} is set. Once the key \krsty{boolone} has been defined by the above statement, the function \krcmd{f@boolone} may be  redefined and reused many times, any time, even before the setting of the key \krsty{boolone}. It isn't the function \krcmd{f@boolone} that is used in defining the key \krsty{boolone}, but the meaning of \krcmd{f@boolone}.
+which will execute \krcmd{f@boolone} when the key \krsty{boolone} is set. Once the key \krsty{boolone} has been defined by the above statement, the function \krcmd{f@boolone} may be  redefined and reused many times, any time, even before the setting of the key \krsty{boolone}. It isn't the function \krcmd{f@boolone} that is used in defining the key \krsty{boolone}, but the ``meaning'' of \krcmd{f@boolone}.
 
 As another example, we may do
 \begin{krverbatim}
diff --git a/Master/texmf-dist/doc/latex/keyreader/keyreader-guide.pdf b/Master/texmf-dist/doc/latex/keyreader/keyreader-guide.pdf
deleted file mode 100644
index 1056b606804..00000000000
--- a/Master/texmf-dist/doc/latex/keyreader/keyreader-guide.pdf
+++ /dev/null