keyreader (12oct12)

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

5 files changed, 203 insertions, 27 deletions

diff --git a/Master/texmf-dist/doc/latex/keyreader/README b/Master/texmf-dist/doc/latex/keyreader/README
index fa3a3b270fd..25603641d83 100644
--- a/Master/texmf-dist/doc/latex/keyreader/README
+++ b/Master/texmf-dist/doc/latex/keyreader/README
@@ -6,7 +6,7 @@ Ahmed Musa
 
 VERSION
 
-Version 0.4b, January 2012
+Version 0.5, October 2012
 
 SUMMARY
 
@@ -16,7 +16,7 @@ Keys are automatically set/initialized as soon as they are defined.
 It provides a compact and robust interface to the xkeyval package.
 The xkeyval package's commands for setting keys are made more robust,
 in the sense that outer braces in key values are preserved throughout
-parsing and unbalanced conditionals can be parsed as part of a key's 
+parsing and unbalanced conditionals can be parsed as part of a key's
 value. In the case of choice keys defined by the command
 \krddefinekeys, each admissible value of the key can be associated
 with a callback, unlike in the xkeyval package.
@@ -26,6 +26,10 @@ ltxkeys package because the xkeyval package, on which the keyreader
 package is based, has been quite stable for some years (its inherent
 shortcomings not withstanding).
 
+RELATED PACKAGES
+
+xkeyval, ltxkeys, skeyval 
+
 LICENSE
 
 Copyright (c) 2010-2012 Ahmed Musa
diff --git a/Master/texmf-dist/doc/latex/keyreader/keyreader-example1.tex b/Master/texmf-dist/doc/latex/keyreader/keyreader-example1.tex
new file mode 100644
index 00000000000..bf8c56d5348
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/keyreader/keyreader-example1.tex
@@ -0,0 +1,68 @@
+\documentclass{article}
+\usepackage{keyreader}
+\usepackage{xcolor}
+\usepackage{graphicx}
+\makeatletter
+\newdimen\shadowsize
+\krddefinekeys*[KV]{ebox}[mp@]{%
+  bool/frame/true;
+  bool/shadow/true;
+  cmd/framecolor/black;
+  cmd/shadecolor/white;
+  cmd/shadowcolor/gray;
+  cmd/framesize/.4pt;
+  cmd/boxsize/.1\columnwidth;
+  cmd/shadowsize/1pt;
+  choice/align/center/
+    center.do=\let\mp@alignright\hfil\let\mp@alignleft\hfil,
+    right.do=\let\mp@alignright\hfill\let\mp@alignleft\relax,
+    left.do=\let\mp@alignright\relax\let\mp@alignleft\hfill,
+    justified.do=\let\mp@alignright\relax\let\mp@alignleft\relax
+    //\@@warning{Invalid value for 'align'};
+}
+\savevaluekeys[KV]{ebox}{frame,framecolor,framesize}
+\krdpresetkeys[KV]{ebox}{%
+  frame,framecolor=black,shadecolor=white,framesize=0.5pt,boxsize,align
+}
+\krdpostsetkeys[KV]{ebox}{%
+  shadow=\usevalue{frame},shadowcolor=\usevalue{framecolor}!40,
+  shadowsize=\usevalue{framesize}*4
+}
+\newcommand*\ebox[2][]{%
+  \krdsetkeys[KV]{ebox}{#1}%
+  \begingroup
+  \ifmp@frame
+    \fboxrule=\dimexpr\mp@framesize\relax
+  \else
+    \fboxrule=0pt
+  \fi
+  \ifmp@shadow
+    \shadowsize=\dimexpr\mp@shadowsize\relax
+  \else
+    \shadowsize=0pt
+  \fi
+  \setbox0=\hbox{%
+    \fcolorbox{\mp@framecolor}{\mp@shadecolor}{%
+      \hbox to\mp@boxsize{%
+        \mp@alignright #2\mp@alignleft
+      }%
+    }%
+  }%
+  \hskip\shadowsize
+  \color{\mp@shadowcolor}%
+  \rule[-\dp0]{\wd0}{\the\dimexpr\ht0+\dp0\relax}%
+  \llap{\raisebox{\shadowsize}{\box0\hskip\shadowsize}}%
+  \endgroup
+}
+\makeatother
+
+\begin{document}
+\parindent-60pt
+\scalebox{2}{%
+  \ebox[shadecolor=brown!70]{ebox1}%
+  \ebox[framecolor=magenta,boxsize=2cm,align=right]{ebox2}%
+  \ebox[shadow=false,framesize=1pt,framecolor=red,boxsize=1.5cm,align=left]{ebox3}%
+  \ebox[framesize=1pt,framecolor=green,shadowcolor=blue]{ebox4}%
+  \ebox[frame=false,shadow,shadowcolor=yellow,framesize=.5pt]{ebox5}%
+}
+\end{document}
diff --git a/Master/texmf-dist/doc/latex/keyreader/keyreader-guide.cfg b/Master/texmf-dist/doc/latex/keyreader/keyreader-guide.cfg
new file mode 100644
index 00000000000..af803ae50e3
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/keyreader/keyreader-guide.cfg
@@ -0,0 +1,61 @@
+\ProvidesFile{keyreader-guide.cfg}%
+  [2012/10/10 v0.5 Configuration file for keyreader-guide (AM)]
+
+\amltxoptions{%
+  geometryoptions       = {left=3cm,right=3cm,top=2.5cm,%
+                          bottom=2.5cm,includeheadfoot},
+  reviewdocument        = false,
+  parindent             = false,
+  toc                   = false,
+  frontpagestyle        = empty,
+  pretitleskip          = 0ex,
+  posttitleskip         = 1ex,
+  presuptitleskip       = 0ex,
+  postsuptitleskip      = 0ex,
+  presubtitleskip       = 0ex,
+  postsubtitleskip      = 0ex,
+  natbiboptions         = {numbers,sort&compress},
+  cmdcolor              = xmagenta1,
+  stylecolor            = xgreen1,
+  speccolor             = teal,
+  sectionheadcolor      = blue
+}
+
+\fancypagenos[%
+  textalign         = center,
+  show-on-page-one  = false,
+  show-page-numbers = true,
+  show-headrule     = true,
+  show-footrule     = false,
+  y-position        = -.44\paperheight,
+  x-position        = 0,
+  scale             = 1,
+  angle             = 0,
+  style             = \textsc{Page~\thepage~of~\pageref{xwmlastpage}},
+  left-header       = The \textcolor{macrocolor}{keyreader} package,
+  right-header      = \ttcl{black}{\today}
+]
+
+\newwatermark[page=1,fontfamily=phv,fontsize=11pt,fontseries=m,align=center,
+  coordunit=pc,width=.978\paperwidth,angle=0,scale=1,xpos=-.62,ypos=31.2]{%
+  \xwmcolorbox[framesep=5pt,framerule=2pt,fillcolor=white,
+    outerframecolor=Orange,innerframecolor=brown,textalign=justified,
+    width=.978\paperwidth]{%
+    \normalfont\small\color{black}\vspace*{-1ex}%
+    \parbox{.95\paperwidth}{%
+      \vspace*{2ex}%
+      \begin{center}%
+      \sffamily\bfseries
+      \scalebox{4}{The \textcolor{blue}{keyreader} Package\titleref{t1,t2}}%
+      \endgraf\vspace*{1ex}%
+      \scalebox{2}{A robust interface to \pkg'{xkeyval}}%
+      \endgraf\vspace*{1ex}%
+      {\normalsize\normalfont\sffamily
+      \copyright\ Ahmed Musa 2010-\number\year}%
+      \end{center}%
+      \vspace*{2ex}%
+    }%
+  }%
+}
+
+\endinput
diff --git a/Master/texmf-dist/doc/latex/keyreader/keyreader-guide.pdf b/Master/texmf-dist/doc/latex/keyreader/keyreader-guide.pdf
index 899cb1c32bc..2dd2392b7c4 100644
--- a/Master/texmf-dist/doc/latex/keyreader/keyreader-guide.pdf
+++ b/Master/texmf-dist/doc/latex/keyreader/keyreader-guide.pdf
diff --git a/Master/texmf-dist/doc/latex/keyreader/keyreader-guide.tex b/Master/texmf-dist/doc/latex/keyreader/keyreader-guide.tex
index 6f8ce6b1319..23eaf5618f5 100644
--- a/Master/texmf-dist/doc/latex/keyreader/keyreader-guide.tex
+++ b/Master/texmf-dist/doc/latex/keyreader/keyreader-guide.tex
@@ -29,7 +29,7 @@
 \title{}
 \titlenotes[t1,t2]{%
   The package is available at \url{\titleurltext}.\sep
-  This user manual corresponds to version~0.4b of the package.
+  This user manual corresponds to version~0.5 of the package.
 }
 \subtitle{}
 \titleurl{http://mirror.ctan.org/macros/latex/contrib/keyreader/}
@@ -39,7 +39,8 @@
 }
 \def\abstractname{\textsf{Summary}}
 \begin{abstract}
-  The \pkg'{keyreader} provides robustness and some extensions to the \pkg'{xkeyval}. It preserves braces in key values throughout parsing and saves estate when defining keys. Also, the command \fx{\krdsetkeys} allows unbalanced conditionals to be parsed as values of keys. Furthermore, when the command \fx{\krddefinekeys} is used, keys are initialized as soon as they are defined, and, unlike in the \pkg'{xkeyval}, admissible alternate values of choice keys can have individual callbacks. The looping macros of the \pkg'{xkeyval} are redefined, to increase robustness. The command \fx{\define@key} of the \pkg'{xkeyval} has had two of its subordinate commands redefined, to offset a complaint about the grabbing of the key's callback when defining keys with \fx{\define@key}. This user manual assumes that the reader is familiar with some of the functions and user interfaces of the \pkg'{xkeyval}.
+  \small
+  The \pkg{keyreader} bundle is platform independent and provides robustness and some extensions to the \pkg'{xkeyval}. However, it is completely independent of the \pkg'{xkeyval}. It preserves braces in key values throughout parsing and saves estate when defining keys. Also, the command \fx{\krdsetkeys} allows unbalanced conditionals to be parsed as values of keys. Furthermore, when the command \fx{\krddefinekeys} is used, keys are initialized as soon as they are defined, and, unlike in the \pkg'{xkeyval}, admissible alternate values of choice keys can have individual callbacks. The looping macros of the \pkg'{xkeyval} are redefined, to increase robustness. The command \fx{\define@key} of the \pkg'{xkeyval} has had two of its subordinate commands redefined, to offset a complaint about the grabbing of the key's callback when defining keys with \fx{\define@key}. This user manual assumes that the reader is familiar with some of the functions and user interfaces of the \pkg'{xkeyval}. The \fx{\krdkeys} command ... Unlike the \pkg'{xkeyval}, the \pkg'{keyreader} can be loaded before \hx{\documentclass} and this feature doesn't affect its ability to later filter class options-list for options that have values.
 \end{abstract}
 
 \let\licensename\relax
@@ -72,9 +73,10 @@ The \pkg'{keyreader} has been used as a development platform for the \pkg'{ltxke
 shortcomings not withstanding. Has the user ever tried to pass to \pkg'{xkeyval}'s \fx{\setkeys} an unbalanced conditional as the value of a key? He/she will quickly be hit by the error message \quoted{! Incomplete \hx{\ifx}; all text was ignored after line \ldots}, or something similar. This limitation has been removed by the \pkg'{keyreader}.
 
 
-\docsection(sec:user-commands)<user commands>{User commands}
+The packages in the \pkg{keyreader} bundle are ...
 
-\docsubsection(sec:definingkeys){Defining keys}
+
+\docsection(sec:definingkeys){Defining keys}
 
 The syntax for defining keys is:
 
@@ -83,7 +85,18 @@ The syntax for defining keys is:
 \finish{newmacro}
 \fxim*{\krddefinekeys}
 
-The optional \ang{kprefix} and mandatory \ang{kfamily} have unambiguous connotations. The optional \ang{mprefix} is the macro prefix, in the parlance of the \pkg'{xkeyval}. The default values of \ang{kprefix} and \ang{mprefix} are \ffx'{KRD,krdmp@}, respectively.
+The optional \ang{kprefix} and mandatory \ang{kfamily} have unambiguous connotations. The optional \ang{mprefix} is the macro prefix, in the parlance of the \pkg'{xkeyval}. The default values of \ang{kprefix} and \ang{mprefix} are \ffx'{KV,krdmp}, respectively.
+
+\start'{macro}[Syntax of key keylist]
+\krddefinekeys[<pref>]{<fam>}[<mp>]{
+  ord/<key>/<dft>/<f1>;
+  cmd/<key>/<dft>/<f1>;
+  bool/<key>/<dft>/<f1>;
+  bool+/<key>/<dft>/<f1>/<f2>;
+  choice/<key>/<dft>/<nominations>/<f1>;
+  choice+/<key>/<dft>/<nominations>/<f1>/<f2>;
+}
+\finish{macro}
 
 In the case of ordinary, command and boolean keys, \ang{keylist} has the syntax
 
@@ -126,7 +139,7 @@ The star (\redstar*) sign on \fx{\krddefinekeys} is an optional suffix. If it is
 Choice keys defined by \fx{\krddefinekeys} are of the \stform of choice keys (see the \pkg'{xkeyval} guide). Hence they will always convert the user input into lowercase before matching it against the alternate/admissible list of values specified at key definition time. The matching, as done by \fx{\krdsetkeys}, is catcode-agnostic.
 
 
-\docsubsection(sec:settingkeys){Setting keys}
+\docsection(sec:settingkeys){Setting keys}
 
 The command \fx{\krdsetkeys} is a more robust counterpart of the \pkg'{xkeyval}'s \fx{\setkeys}, in the sense that it preserves all outer braces in the values of keys and allows the parsing of key values with unbalanced conditionals. The new command \fx{\krdsetkeys} has the same syntax as the original \fx{\setkeys} of the \pkg'{xkeyval}, namely
 
@@ -139,10 +152,33 @@ As usual, the star (\redstar) and plus sign (\redplus) are optional suffixes. Th
 
 The command \fx{\krdsetkeys} isn't exactly \pkg'{xkeyval}'s \fx{\setkeys}, since the former is more robust and avoids the selective sanitization of \keyval list that is done by \fx{\setkeys}. The macro \fx{\krdsetkeys} \quoted{normalizes} the \keyval or comma-separated key list. Therefore, users of the \pkg'{keyreader} should always call the command \fx{\krdsetkeys} instead of \fx{\setkeys}. Both have the same user interface. The \fx{\setkeys} command of the \pkg'{xkeyval}'s remains unchanged.
 
-The \pkg'{xkeyval}'s command \fxi{\setrmkeys}, which sets \quoted{remaining keys}, has also been modified to \fxi{\krdsetrmkeys}, while keeping \fx{\setrmkeys} unchanged. Users of the \pkg'{keyreader} should use \fx{\krdsetrmkeys} in place of \fx{\setrmkeys}.
+The \pkg'{xkeyval}'s command \fxi{\setrmkeys}, which sets \quoted{remaining keys}, has been replaced by \fxi{\krdsetrmkeys}, while keeping \fx{\setrmkeys} unchanged. Users of the \pkg'{keyreader} should use \fx{\krdsetrmkeys} in place of \fx{\setrmkeys}.
+
+\start*+{example}[\ifkrdnovalue]
+\krdordkey[KV]{fam}{keya}[default]{%
+  \ifkrdnovalue
+    \krd@err{No user value supplied for key `keya'}
+      {Key `KV/fam/keya' requires a user value.}%
+  \else
+    \edef\userinput{\unexpanded{#1}}%
+  \fi
+}
+\krdsetkeys[KV]{fam}{keya}
+\krdsetkeys[KV]{fam}{keya=value}
+\finish{example}
+
+
+\docsection(sec:disable-keys)<disabling keys>{Disabling keys}
+
+The command \fxim{\krddisablekeys} has the same use syntax as the \fxi{\disable@keys} command of the \pkg'{xkeyval}, but will issue an error (instead of a warning) when an attempt is made to set a disabled key.
+
+
+\docsection(sec:options-processing)<options processing>{Options processing}
 
+The commands \ffxi'{\krdDeclareOption, \krdExecuteOptions, \krdProcessOptions} are replacements for \ffxi'{\DeclareOptionX, \ExecuteOptionsX, \ProcessOptionsX} of the \pkg'{xkeyval}.
 
-\docsubsection(sec:examples)<examples>{Examples}
+
+\docsection(sec:examples)<examples>{Some examples}
 
 \start*+{example}[\krddefinekeys, \krdsetkeys]
 \krddefinekeys*[KV]{fam}[pnt@]{%
@@ -155,7 +191,7 @@ The \pkg'{xkeyval}'s command \fxi{\setrmkeys}, which sets \quoted{remaining keys
     left.do=\def\vcp@align{flushleft},
     right.do=\def\vcp@align{flushright},
     justified.do=\def\vcp@align{relax}/
-    \ifkrddef\else
+    \ifkrdindef\else
       \def\xa##1{#1##1}
     \fi;
   ord/keye/{keye-default}/\def\y##1{#1##1}
@@ -163,9 +199,24 @@ The \pkg'{xkeyval}'s command \fxi{\setrmkeys}, which sets \quoted{remaining keys
 \krdsetkeys[KV]{fam}[keyb]{keya={green},keyb=\@iden,keyc=false,keyd=left}
 |com(Setting keys with values having unbalanced conditionals:)
 \krdsetkeys[KV]{fam}{keye={\iffalse keye-value}}
+
+\let\warning\@latex@warning@no@line
+\krddefinekeys*[KV]{fam}[mp@]{%
+  ord/keya/default-a/\def\x##1{#1*##1};
+  bool/keyb/true/;
+  bool+/keyc/true//\@latexerr{Invalid value for keyc};
+  cmd/keyd/black;
+  choice+/keye/center/
+    center.do=\let\mp@alignright\hfil\let\mp@alignleft\hfil,
+    right.do=\let\mp@alignright\hfill\let\mp@alignleft\relax,
+    left.do=\let\mp@alignright\relax\let\mp@alignleft\hfill,
+    justified.do=\let\mp@alignright\relax\let\mp@alignleft\relax
+    //\warning{Invalid value for keye};
+}
+
 \finish{example}
 
-The braces around \quoted{green}, the value of \fx{keya}, will be preserved throughout parsing. It should be remembered that keys are automatically set as soon as they are defined by \fx{\krddefinekeys}. The boolean \fx{\ifkrddef} is true when \fx{\krddefinekeys} is defining keys, and false otherwise. The essence of it is that since keys are set as soon as they are defined by \fx{\krddefinekeys}, some actions should not be executed at this time, until the keys are being set by the user.
+The braces around \quoted{green}, the value of \fx{keya}, will be preserved throughout parsing. It should be remembered that keys are automatically set as soon as they are defined by \fx{\krddefinekeys}. The boolean \fx{\ifkrdindef} is true when \fx{\krddefinekeys} is defining keys, and false otherwise. The essence of it is that since keys are set as soon as they are defined by \fx{\krddefinekeys}, some actions should not be executed at this time, until the keys are being set by the user.
 
 Using the keys defined in the above example, let us make \qcomma and \qequal active and see how the \pkg'{keyreader} will deal with them.
 
@@ -221,10 +272,10 @@ The output of the following example is shown in \sref{fig:1}:
   shadowsize=\usevalue{framesize}*4
 }
 \newcommand*\ebox[2][]{%
-  \setkeys[KV]{ebox}{#1}%
-  |com(What happens if we use the following, instead of the above \setkeys?)
+  \krdsetkeys[KV]{ebox}{#1}%
+  |com(What happens if we use the following, instead of the above \krdsetkeys?)
   |com(Preset and postset keys wouldn't be set when `#1' is empty:)
-  |com(\krdifblank{#1}{}{\setkeys[KV]{ebox}{#1}})
+  |com(\krdifblank{#1}{}{\krdsetkeys[KV]{ebox}{#1}})
   \begingroup
   \ifmp@frame
     \fboxrule=\dimexpr\mp@framesize\relax
@@ -270,22 +321,14 @@ The output of the following example is shown in \sref{fig:1}:
 \end{figure}
 
 
-\docsubsection(sec:disable-keys)<disabling keys>{Disabling keys}
-
-The command \fxim{\krddisablekeys} has the same use syntax as the \fxi{\disable@keys} command of the \pkg'{xkeyval}, but will issue an error (instead of a warning) when an attempt is made to set a disabled key.
-
-
-\docsubsection(sec:options-processing)<options processing>{Options processing}
-
-The commands \ffxi'{\krdDeclareOption, \krdExecuteOptions, \krdProcessOptions} are aliases for
-\ffxi'{\DeclareOptionX, \ExecuteOptionsX, \ProcessOptionsX} of the \pkg'{xkeyval}.
-
-
 \docsection(sec:version-hist){Version history}
 
 The following change history highlights significant changes that affect user utilities and interfaces; changes of technical nature are not documented in this section.
 
 \begin{versionhist}
+  \begin{version}{0.5}{2012/10/10}
+  \item The \pkg'{keyreader} can now be loaded before \fx{\documentclass}.
+  \end{version}
   \begin{version}{0.4b}{2012/01/14}
   \item The command \fx{\krdsetkeys} can now parse key values with unbalanced conditionals.
   \end{version}
@@ -293,7 +336,7 @@ The following change history highlights significant changes that affect user uti
   \item The key list in \fx{\krddefinekeys} shouldn't have been normalized with respect to forward slash (/).
   \end{version}
   \begin{version}{0.4}{2011/12/20}
-  \item Several of the former functions of the package have been transferred to the \pkg'{ltxkeys} with even more robustness. The package now provides mainly a compact and robust interface to the features of the \pkg'{xkeyval}.
+  \item Several of the former functions of the package have been transferred to the independent \pkg'{ltxkeys} with even more robustness. The package now provides mainly a compact and robust interface to the features of the \pkg'{xkeyval} for users of \pkg'{xkeyval}.
   \end{version}
   \begin{version}{0.3}{2011/03/26}
   \item Bug fix.