skeyval (6nov12)

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

9 files changed, 402 insertions, 166 deletions

diff --git a/Master/texmf-dist/doc/latex/skeyval/README b/Master/texmf-dist/doc/latex/skeyval/README
index fe6e31d7d37..5a43e018146 100644
--- a/Master/texmf-dist/doc/latex/skeyval/README
+++ b/Master/texmf-dist/doc/latex/skeyval/README
@@ -6,7 +6,7 @@ Ahmed Musa
 
 VERSION
 
-Version 1.1, October 2012.
+Version 1.1a, October 16, 2012.
 
 LOCATION ON CTAN
 
@@ -47,8 +47,8 @@ Plain TeX users can do
 
     \input skeyval-core
 
-Users of pre-version-1.0  of skeyval package can access former
-versions by entering the option 'compatibility' in <options> above.
+Users of pre-version-1.0  of skeyval package can access the former
+version by entering the option 'compatibility' in <options> above.
 This option will automatically load version 0.73 (the version
 just before 1.0) of skeyval package. From version 1.0, the package
 has changed radically.
@@ -84,11 +84,11 @@ The skeyval package also maintains and, in fact, greatly extends the
 functionality and syntaxes of the ltxkeys package. Very few examples
 of the functionality of skeyval package are
 
-1.  The callbacks of keys can be readily modified using commands
+**  The callbacks of keys can be readily modified using commands
     like \skvaddtocallback, \skvprependtocallback, \skvappendtocallback,
     or the handlers .prepend code, .append code, .add code.
 
-2.  Apart from the usual keys in xkeyval and ltxkeys packages, it is
+**  Apart from the usual keys in xkeyval and ltxkeys packages, it is
     now possible to define a rather weird key like
 
     \skvpntkey[KV]{fam}{evaluate (?) as (?) using (?)}{\edef#2{#3}}
@@ -112,12 +112,44 @@ of the functionality of skeyval package are
       evaluate (\x) as (\pgfmathresult) using (\pgfmathparse{\x^10})
     }
 
-3.  The parameters/arguments of callbacks of keys can be easily changed.
-    For example, to change the argument of keya, one way is via
-    the magical command \directkeys:
+** Handlers
+
+    The skeyval package has many handlers. The handlers of
+    start with a dot (.), as in pgfkeys package.
+
+    Unlike in pgfkeys package, when 'expand' or 'expanded'
+    is found in a handler, the expansion will invariably be done
+    when the key is set, not when it's being defined.
+
+
+**  Subject-observer keys (called 'style keys' in pgfkeys) can be readily
+    introduced.
+
+    \skvappendstyles[KV]{fam}{key1,key2}{keya=.expanded{\vala},keyb=valb}
+     [defaultof 1&2]{\def\y##1{#1*##1}}
+
+    Here the subjects are key1 and key2, while the observers are keya and
+    keyb. For now, the only thing the subject does is to set the given values
+    of the observers on the current path. In the future, we intend to extend
+    the subject-observer functionality to include more features of the
+    observer pattern found in other programming paradigms. We foresee that
+    subjects will be able to publish their services, and observer keys will be
+    able to subscribe for notification from subjects. And rather than 'notify
+    messages' simply setting observer keys with prior prescribed observer
+    values, as is currently the obtainable, observers may be able to do more
+    with such messages (such as change observer state patterns).
+
+**  The parameters/arguments of callbacks of keys can be easily changed
+    by calling \skvdefinekeys, \skvmakekeys, \skvassignargs or \directkeys.
+
+    \skvordkeys[KV1]{fam2}{keya,keyb}[default-a]{\def\x##1{#1*##1}}
+    \skvassignargs[KV1,KV2]{fam1,fam2}[x1]{keya,keyb}{#1/#2}
+    \skvsetkeys[KV1]{fam2}{keya=vala/valb}
+
+    'x1' here means expand argument once at setting keys.
 
     \directkeys{%
-      .exec=\def\avalue{a+b},
+      .exec code=\def\avalue{a+b},
       .prefixes={KV1,KV2},
       .families={fam1,fam2},
       .holder prefix=mp@,
@@ -134,12 +166,18 @@ of the functionality of skeyval package are
       .set keys={
           keya=.expanded{\avalue}
         },
-      % Nested \directkeys. The current path is put on stack
-      % and restored later, so that the nest is independent
-      % of its surrounding topology:
+
+**  Nested \directkeys. The current path is put on stack
+    and restored later, so that the nest is independent
+    of its surrounding topology (prefix and family). But
+    the default prefix survives outside \directkeys.
+
       \directkeys{
-          .path=KV3/fam3,
+          .default prefix=KV,
+          % The prefix for 'famx' will be 'KV'.
+          .paths={KV3/fam3,famx},
           .new keys={
+            .initialize keys after define=false,
             .ord/keya/defa/\def\ya##1{#1*##1*#2},
             .arg/keya/#1+#2,
             .choice/keyc/center/{right,left,center,justified},
@@ -150,9 +188,9 @@ of the functionality of skeyval package are
         },
       .try set keys={
           .paths={KV1/fam1,KV3/fam3},
-          .try=2, .goal=1
-        }{
-          keyc=left,keyd=false
+          .try=2,
+          .goal=1,
+          .kv list={keyc=left,keyd=false},
         },
       .ignore path=KV1/fam1,
       .exec=\def\cvalue{center},
@@ -160,8 +198,7 @@ of the functionality of skeyval package are
           .add prefix=KV3,
           .add families={fam3,fam4},
           .max attempts=4, .goal=2,
-        }{
-          keyc=.expand once{\cvalue}
+          .kv list={keyc=.expand once{\cvalue}},
         },
       .append values={
           keya=\def\y##1{#1+##1},
@@ -182,14 +219,24 @@ of the functionality of skeyval package are
         },
     }
 
-    Unlike in pgfkeys package, when we use 'expand' or 'expanded'
-    in a handler, the expansion will invariably be done when the
-    key is set, not when it's being defined.
+**  Prepending and appending to key names and callbacks at
+    definition time:
+
+    \directkeys*{
+      .path=claudio/color,
+      .hp=claudio@col@,
+      .define keys={
+        .prepend to every key name=X@,
+        .append to every key name=@Y,
+        .prepend to every callback=\def\X##1{#1*##1},
+        .append to every callback=\def\Y##1{##1**#1},
+        .ord/{1,2,3,4,5,6}/red,
+      }
+    }
+    \skvusekeys[.path=claudio/color]{X@1@Y,X@2@Y}
 
-    The handlers of skeyval package start with a dot (.),
-    as in pgfkeys package.
 
-4.  Several new features are introduced by the skeyval package. For
+**  Several new features are introduced by the skeyval package. For
     example, we now have 'style' and 'link' keys in the context of
     ltxkeys syntax. For example, to link keys via .link or .style
     handler:
@@ -200,23 +247,79 @@ of the functionality of skeyval package are
       .append style expand twice={key3, key4}/keyf=\valuea,
       .prepend style expanded={key5, key6}/{keyc=#1, keyd=#1},
       .prepend style={key7, key8}/{keyd=#1, keye=#1},
+      .allowed values expanded=keye/{
+        center.do=\def\curralign##1{\hfil##1\hfil},
+        right.do=\def\curralign##1{\hfill##1},
+        left.do=\def\curralign##1{##1\hfill},
+        justified.do=\let\curralign\@iden
+      },
+    }
+
+**  Bipolar boolean keys
+
+    \skvbiboolkeys[KV]{fam}[mp@]{.forbid value{keya},keyb}[true]{%
+      \ifmp@keya\def\xa##1{##1}\fi
+    }{%
+      \ifmp@keyb\def\xb##1{##1}\fi
+    }%
+    \skvsetkeys[KV]{fam}{keya}
+
+    The value of keya is frozen as 'true'. Hence whenever keya is called,
+    the value 'true' will be used for it. Since keya and keyb are bipolar,
+    the value of keyb will be 'false' whenever keya is called.
+
+    \skvbiboolkeys+[KV]{fam}[mp@]{keya,keyb}[true]{%
+      \ifmp@keya\def\xa##1{##1}\fi
+    }{%
+      \ifmp@keyb\def\xb##1{##1}\fi
+    }{%
+      \skv@warn{Value '#1' is invalid}%
     }
+    \skvsetkeys[KV]{fam}{keya=xtrue}
 
-5.  The concepts of 'trying' to set a key with 'goals' is introduced.
+
+**  The concepts of 'trying' to set a key with 'goals' is introduced.
     The handler '.goal' can be interpreted in the sense of \pagegoal,
-    but applied to setting a key.
-    See an example above. Then there is 'search also' set keys.
+    but applied to setting a key. See an example above. Then there
+    is 'search also' set keys.
+
+**  'Quick keys' are a new concept. They're quite fast to define and set,
+    but they can't carry pointers.
+
+    \quickkeys.define{<family>}[<holder.prefix>]{<list>}
+    \quickkeys.set{<family>}[<na>]{<kvlist>}
+
+    When defining keys, the syntax of <list> is:
+
+    {<keya-1,...,keya-n>}/{<default>}/{<callback>}/{<nominations>}/{<arg>}
+                           ;...;
+    {<keyx-1,...,keyx-n>}/{<default>}/{<callback>}/{<nominations>}/{<arg>}
+
+    Example:
+
+    \quickkeys.define{fam}[mp@]{%
+      keya/true/\def\x##1{#1*##1}/true,false;
+      keyb;
+      keyc,keyd/aaa+bbb/\def\y##1{#1*##1*#2}/.na/#1+#2;
+    }
 
-6.  'Quick keys' are a new concept. They're quite fast to define and set.
+    '.na' means a missing entry that isn't empty but should be ignored.
 
-7.  Keys can be 'made', as in
+    <nominations> can be used to restrict the user-values of the key
+    or keys.
+
+    <arg> means the argument pattern for the key or keys.
+
+
+**  Keys can be 'made', as in
 
     \skvmakekeys[
       .prefix=KVA, .families={fam1,fam2}, .holder prefix=mp@,
       .all are new, .define in all families, .initialize after define
     ]{%
-      .ords/{keya,keyb}/{default-a},
-      .cmds/{keyc,keyd}/,
+      .ord/{keya,keyb}/{default-a},
+      .arg/keyb/{#1+#2},
+      .cmd/{keyc,keyd}/,
       .zcmd/key e/\def\cmde##1{##1}/
         \edef\y{\detokenize\expandafter{\thp@keye}}\def\x##1{#1*key e*##1},
       .choice/keyf/center/{center.do=\def\x##1{#1*##1},left,right},
@@ -228,7 +331,7 @@ of the functionality of skeyval package are
     without spaces in their names, while maintaining key names with
     spaces.
 
-8.  Keys can be set using \skvsetkeys, \directkeys (with the handlers
+**  Keys can be set using \skvsetkeys, \directkeys (with the handlers
     .set keys, .try, etc.), or \skvusekeys:
 
     \krdusekeys[
@@ -240,14 +343,41 @@ of the functionality of skeyval package are
       keya,keyb
     }
 
-9.  Keys defined in families can be viewed in files using the package
+    \directkeys*{
+      .path=user/color,
+      .hp=user-col-,
+      .define keys={
+        .cmd/{1,2,3,4,5,6}/red
+      }
+    }
+    \newcommand*\setcolorlist[1]{\skvusekeys[.path=user/color]{#1}}
+    \setcolorlist{1=red,2=blue,3=cyan,4=green,5=magenta,6=purple}
+    \newcommand*\usecolor[1]{%
+      \skvifcsname user-col-#1\then
+        \csname user-col-#1\endcsname
+      \else
+        black%
+      \fi
+    }
+    \newcommand*\drawcoloredarrows[1]{%
+      \foreacfox {#1}{%
+        \draw[\usecolor{##1},-stealth] (0,-##1)--(2,-##1);
+      }
+    }
+    \begin{document}
+    \begin{tikzpicture}
+    \drawcoloredarrows{1,...,4}
+    \end{tikzpicture}
+    \end{document}
+
+**  Keys defined in families can be viewed in files using the package
     'skeyval-view'. The functionality of 'skeyval-view' is greater than
     that of xkeyval-view package.
 
-10. Files skeyval-pstkey.sty and skeyval-pstkey.tex are provided for
+** Files skeyval-pstkey.sty and skeyval-pstkey.tex are provided for
     PSTricks developers and users, as did xkeyval package.
 
-11. Some new and versatile looping macros are introduced in the
+**  Some new and versatile looping macros are introduced in the
     skeyval package. In fact, the powerful \newforeach list
     processor of the 'loops' package has its roots in the 'skeyval-for'
     module. It is a generalization of PGF's \foreach macro for
diff --git a/Master/texmf-dist/doc/latex/skeyval/skeyval-pokayoke1.pdf b/Master/texmf-dist/doc/latex/skeyval/skeyval-pokayoke1.pdf
index 5efe8797009..aad9d8e117d 100644
--- a/Master/texmf-dist/doc/latex/skeyval/skeyval-pokayoke1.pdf
+++ b/Master/texmf-dist/doc/latex/skeyval/skeyval-pokayoke1.pdf
diff --git a/Master/texmf-dist/doc/latex/skeyval/skeyval-pokayoke1.tex b/Master/texmf-dist/doc/latex/skeyval/skeyval-pokayoke1.tex
index 2617d621840..2be16f1aa95 100644
--- a/Master/texmf-dist/doc/latex/skeyval/skeyval-pokayoke1.tex
+++ b/Master/texmf-dist/doc/latex/skeyval/skeyval-pokayoke1.tex
@@ -1,4 +1,4 @@
-
+\makeatletter
 \RequirePackage{skeyval-ltxpatch}
 
 % With 'skeyval-ltxpatch' loaded, class options will not be zapped and
@@ -12,6 +12,8 @@
   watermarkcolor=brown!80!yellow
 ]{skeyval-testclass}
 
+%\show\@unusedoptionlist
+
 \skvifpackageloaded{xcolor}{}{\usepackage[dvipsname]{xcolor}}
 \usepackage{lipsum}
 
@@ -27,8 +29,6 @@
   unknown-option,
 ]{skeyval-testpkg}
 
-\makeatletter
-
 % Keys whose names are zapped internally:
 \skvzcmdkeys[KV]{fam}[mp@]{provide value,give value}[true]{}
 \skvzboolkeys[KV]{fam}[mp@]{provide value,give value}[true]{}
@@ -39,7 +39,7 @@
 \skvpntkey[KV]{fam}{evaluate (?) as (?) using (?)}[\x\y{\numexpr\x*2}]{%
   \def\argone{#1}\def\argtwo{#2}\def\argthree{#3}%
   % '\detokenize{\pgfmath}' won't work here!
-  \skvxifin{\relax\string\pgfmath}{\relax\detokenize{#3}}{%
+  \skvxifinTF{\relax\string\pgfmath}{\relax\detokenize{#3}}{%
     #3%
   }{%
     \edef#2{#3}%
@@ -62,7 +62,7 @@
 % comma (,), it should be enclosed in braces.
 
 \directkeys*{
-  .exec=\skvsratchcnt\z@,
+  .exec=\skvtestcnt\z@,
   .prefix = KV1,
   .family = fam1,
   .holder prefix = mp@,
@@ -73,8 +73,7 @@
   .initialize keys after define=false,
   .new keys = {
     .ord/keya/{dfta,dftb}/
-      \def\cmda##1{#1*##1*#2}
-      \logsetting
+      \def\cmda##1{#1*##1*#2}\logsetting
       ,
     .arg/keya/{#1,#2},
     .cmd/keyb/{1cm,2cm}/
@@ -84,7 +83,7 @@
     .bool/keyd/true,
     .cmd/keye/dfte/\def\cmde##1{##1#1},
     .cmd/keyf/dftf/\def\cmdf##1{##1#1},
-    .ord/.value required{keyg}/dftg,
+    .ord/.need value{keyg}/dftg,
     .ord/.forbid value{keyh}/dfth,
   },
   .args={
@@ -101,7 +100,9 @@
     keyd,keye,keyf,keyg
   },
   .restore keys = keye,
-  .choice=keye/{
+  .link={keye2/keye},
+  % Choices for keye can be declared directly:
+  .estate pattern={keye,keye2}/{
     center.do=\def\curralign##1{\hfil##1\hfil},
     right.do=\def\curralign##1{\hfill##1},
     left.do=\def\curralign##1{##1\hfill},
@@ -143,19 +144,17 @@
     .add families={fam3,fam4},
     .try=14,
     .upper goal=12,
-    .success list=\mysuccesslist
-  }{
-    keya={val1,val2},keyb={1cm,2cm}
+    .success list=\mysuccesslist,
+    .kv={keya={val1,val2},keyb={1cm,2cm}}
   },
 %  .exec code={\show\mysuccesslist},
   \directkeys*{
-    .exec=\skvsratchcnt\z@\def\mysuccesslist{},
+    .exec=\skvtestcnt\z@\def\mysuccesslist{},
     .paths={KUA/fam1,KUB/fam2},
     .define keys={
-      .ords/{keya,keyb,keyc}/.na/
+      .ord/{keya,keyb,keyc}/.na/
         \def\y##1{#1*##1}
-        \typeout{***}
-        \logsetting
+        \typeout{***}\logsetting
       ,
     }
   },
@@ -167,9 +166,59 @@
     .upper goal=4,
     .lower goal=2,
     .ignore keys={keyb,keyc},
-    .success list=\mysuccesslist
-  }{
-    keya=vala,keyb=valb,keyc=valc
+    .success list=\mysuccesslist,
+    .kv={keya=vala,keyb=valb,keyc=valc}
+  },
+%  .exec code={\show\mysuccesslist},
+}
+
+\dirkeys*{
+  .exec=\skvtestcnt\z@\def\mysuccesslist{},
+  .paths={KUA/fam1,KUB/fam2},
+  .hp=mp@,
+  .ignore keys={keyd},
+  .define keys={
+    .initialize keys after define=true,
+    .save initial values of keys,
+    .exec code/\skvtestcnt\z@,
+    % keya has no default but has a complex callback:
+    .ord/keya/.na/{
+        \skvtestcnt\z@\def\mysuccesslistb{}
+        \dirkeys{
+          .path={KVX/famx},
+          .sa set keys={%
+            .prefixes={KUA,KUB},
+            .families={fam1,fam2},
+            .try=8,
+            .upper goal=4,
+            .lower goal=1,
+            .success list=\mysuccesslistb,
+            .kv={keyb=valb}
+          },
+%          .exec code=\show\mysuccesslistb,
+        }
+      }
+    ,
+    % No default:
+    .ord/{keyb,keyc,keyd}/.na/\def\x##1{#1*##1}\logsetting,
+    .exec code=\def\cmda#1{\if0#1\fi},
+    % No callback:
+    .choice/keye/center/{center,left,right},
+    .choice/keye2/center/{
+        center.do=\def\giv@c{#1},
+        left.do=\def\giv@l{#1},
+        right.do=\def\giv@r{#1}
+      }/.na/\@@warning{Invalid value '\detokenize{#1}' for keye2},
+  },
+  .try set keys={%
+    .prefixes={KUA,KUB},
+    .families={fam1,fam2,fam3,fam4},
+    .try=1,
+    .upper goal=1,
+    .lower goal=1,
+    .ignore keys={keyc,keyd},
+    .success list=\mysuccesslist,
+    .kv={keya=vala,keyc=valc,keyd=vald}
   },
 %  .exec code={\show\mysuccesslist},
 }
@@ -179,7 +228,7 @@
 \begin{document}
 
 \title{The \texttt{\textcolor{blue}{skeyval}} Package\\[1ex]
-  Version 1.1\\[1ex]
+  Version 1.1a\\[1ex]
   \textsf{Test document 1}}
 \author{Ahmed Musa}
 \maketitle
@@ -194,7 +243,7 @@ encouraged to create it on a computer file and submit it on magnetic tape.
 \par\bigskip
 
 \begin{\mpfalign}
-\skvxifstrcmp\mpfalign{justified}{\noindent}{}
+\skvxifstrcmpTF\mpfalign{justified}{\noindent}{}
 \mpftextstyle
 The printer should refuse to employ wandering men, foreigners who,
 after having committed some grievous error, can easily disappear and
@@ -224,6 +273,7 @@ on their deeds.
 \begin{center}
 \hrule
 \par\bigskip
+
 \newshadowbox{test 1}
 \newshadowbox[framecolor=magenta,shadecolor=cyan,shadowsize=8pt,
   align=left]{test 2}
@@ -313,15 +363,15 @@ on their deeds.
 %%+++++++++++++++++++++ Examples of \skvmakekeys +++++++++++++++++++%%
 
 \skvmakekeys[
-  prefix=KVA,
-  families={fam1,fam2},
-  hp=thp@,
-  all new,
-  define in all families,
-  initialize=true
+  .prefix=KVA,
+  .families={fam1,fam2},
+  .hp=thp@,
+  .all new,
+  .define in all families,
+  .initialize=true
 ]{%
-  .ords/{keya,keyb}/{default-a},
-  .cmds/{keyc,keyd}/,
+  .ord/{keya,keyb}/default-a,
+  .cmd/{keyc,keyd}/.na/\def\y##1{#1**##1},
   .choice/keyf/center/{center.do=\def\x##1{#1*##1},left,right},
   .zbool/show center/true/\edef\cmd{\ifthp@showcenter Yes\else No\fi},
 }
@@ -380,10 +430,15 @@ on their deeds.
 \skvsaveinitialvaluekeys[KV]{fam}{keya,keyb,keyc}
 %\skvshowcs{KV/fam/.@needini}
 \skvmakekeys[
-  prefix=KV, family=fam, hp=thp@, all new,initialize,save initial values
+  .prefix=KV,
+  .family=fam,
+  .hp=thp@,
+  .all new,
+  .initialize,
+  .save initial values
 ]{%
   .ord/keya/defa-a/\def\keyay##1{##1*#1*##1},
-  .cmds/{keyb,keyc}/defa-b/\def\keyby##1{##1*#1*##1},
+  .cmd/{keyb,keyc}/defa-b/\def\keyby##1{##1*#1*##1},
   .cmd/keyd,
 }
 %\skvshowcs{KV/fam/.@inikv}
@@ -394,9 +449,9 @@ on their deeds.
 
 %++++++++++++++++++ Evaluating boolean expressions +++++++++++++++++++%
 
-\skvifexpr{%
-  not ( expr { \skvifdef\xa } and expr { \skvifempty\xa } )
-  or ( expr { \skvifdef\xb } or expr { \skvifx\xa\xb } )
+\skvifexprTF{%
+  not ( expr { \skvifdefTF\xa } and expr { \skvifemptyTF\xa } )
+  or ( expr { \skvifdefTF\xb } or expr { \skvifxTF\xa\xb } )
 }{%
   \def\x{T}%
 }{%
@@ -406,20 +461,20 @@ on their deeds.
 %++++++++++++++++++++++++++++ \cicadaloop +++++++++++++++++++++++++++%
 
 \makeatletter
-\@tempcnta\z@
+\skvtestcnt\z@
 \def\blist{{X};\fi;{Y};Z}
 \def\stack{}
 \let\romn\romannumeral
 \cicadaloop{{a},\if,{b},c}\if01\fi{%
-  \advance\@tempcnta by\@ne
+  \advance\skvtestcnt by\@ne
   \@tempcntb\z@\@tempswafalse
   \cicadaloop*[;]\blist\if@tempswa\fi{%
     \advance\@tempcntb by\@ne
-    \typeout{Doing \romn\@tempcnta, \romn\@tempcntb:
+    \typeout{Doing \romn\skvtestcnt, \romn\@tempcntb:
       \detokenize{#1, ##1}}%
     \edef\stack{%
       \unexpanded\expandafter{\stack}\noexpand\do
-      {\romn\@tempcnta,\romn\@tempcntb}{\unexpanded{#1;##1}}%
+      {\romn\skvtestcnt,\romn\@tempcntb}{\unexpanded{#1;##1}}%
     }%
     \ifnum\@tempcntb>\tw@\@tempswatrue\fi
   }%
diff --git a/Master/texmf-dist/doc/latex/skeyval/skeyval-pokayoke2.pdf b/Master/texmf-dist/doc/latex/skeyval/skeyval-pokayoke2.pdf
index a81a562fef7..7e995aab364 100644
--- a/Master/texmf-dist/doc/latex/skeyval/skeyval-pokayoke2.pdf
+++ b/Master/texmf-dist/doc/latex/skeyval/skeyval-pokayoke2.pdf
diff --git a/Master/texmf-dist/doc/latex/skeyval/skeyval-pokayoke2.tex b/Master/texmf-dist/doc/latex/skeyval/skeyval-pokayoke2.tex
index 84696094258..57195061611 100644
--- a/Master/texmf-dist/doc/latex/skeyval/skeyval-pokayoke2.tex
+++ b/Master/texmf-dist/doc/latex/skeyval/skeyval-pokayoke2.tex
@@ -1,11 +1,11 @@
 \documentclass[
-  insertwatermark,
+  insertwatermark,watermarkcolor=blue!55,
   firstpagenumber=2,
   maketitlepage,
   unknown-key
 ]{skeyval-testclass}
 
-\setskeyvaltestclass{%
+\setupskvtestclass{%
   watermarktext={skeyval-test2\\[.25ex]Page~\thepage}
 }
 
@@ -22,9 +22,9 @@
 
 \title{%
   The \texttt{\textcolor{blue}{skeyval}} Package\\[2ex]
-  Version 1.1\\[1ex]
+  Version 1.1a\\[1ex]
   \textsf{Test document 2}
-  \footnote{Made by \texttt{skeyval-testclass, Version~1.1.}}%
+  \footnote{Made by \texttt{skeyval-testclass, Version~1.1a.}}%
 }
 \author{Ahmed Musa\footnote{\texttt{amusa22@gmail.com}.}}
 
diff --git a/Master/texmf-dist/doc/latex/skeyval/skeyval-testclass.cls b/Master/texmf-dist/doc/latex/skeyval/skeyval-testclass.cls
index 02de214caa0..c81c535c0ef 100644
--- a/Master/texmf-dist/doc/latex/skeyval/skeyval-testclass.cls
+++ b/Master/texmf-dist/doc/latex/skeyval/skeyval-testclass.cls
@@ -1,5 +1,5 @@
 %++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++%
-% This is file 'skeyval-testclass.cls', version 1.1, 2012/10/15.           %
+% This is file 'skeyval-testclass.cls', version 1.1a, 2012/10/16.          %
 %                                                                          %
 % This package and accompanying files may be distributed and/or            %
 % modified under the conditions of the LaTeX Project Public License,       %
@@ -27,14 +27,15 @@
 %++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++%
 
 \ProvidesClass{skeyval-testclass}
-  [2012/10/15 v1.1 skeyval test class (AM)]
+  [2012/10/16 v1.1a skeyval test class (AM)]
 \NeedsTeXFormat{LaTeX2e}[2011/06/27]
 \@ifpackageloaded{skeyval}{}{\RequirePackage{skeyval}}
 \@ifpackageloaded{xcolor}{}{\RequirePackage{xcolor}}
 \@ifpackageloaded{pifont}{}{\RequirePackage{pifont}}
 \@ifpackageloaded{tikz}{}{\RequirePackage{tikz}}
 
-\skvAtBeginEveryPage{\skvcl@maybewm}
+\ifdefined\skvtestcnt\else\newcount\skvtestcnt\fi
+\skvatbegineverypage{\skvcl@maybewm}
 \let\skvcl@maybewm\relax
 \def\skvcl@watermark{%
   \tikz[overlay,remember picture]{%
@@ -112,7 +113,7 @@
     .cmd/color/red,
     .bool/make-textemphasis-inactive/true/
       \ifskvindef\else
-        \skvifbooltrue xem@make-textemphasis-inactive\then
+        \skvifbool xem@make-textemphasis-inactive\then
           \PackageInfo{skeyval-testclass}
             {Extended text emphasis has been made inactive}
           \let\xem\emph
@@ -134,7 +135,7 @@
     .cmd/datefont/\large,
     .bool/clearpage/true,
     .bool/maketitlepage/true/
-      \skvifbooltrue skvcl@maketitlepage\then
+      \skvifbool skvcl@maketitlepage\then
         \ifskvindef\else
           \PassOptionsToClass{titlepage}{article}
         \fi
@@ -156,7 +157,7 @@
     ,
     .cmd/pagenumberstyle/\@nil/
       \ifx\skvcl@pagenumberstyle\@nnil\else
-        \skvAfterBeginDocument{\pagenumbering{#1}}%
+        \skvafterbegindocument{\pagenumbering{#1}}%
       \fi
     ,
     .cmd/pretitleskip/10pt,
@@ -164,7 +165,7 @@
     .cmd/authorfont/\large,
     .cmd/titlefont/\huge,
     .bool/insertwatermark/true/
-      \skvifbooltrue skvcl@insertwatermark\then
+      \skvifbool skvcl@insertwatermark\then
         \ifskvindef\else
           \let\skvcl@maybewm\skvcl@watermark
         \fi
@@ -178,7 +179,7 @@
     .cmd/fontsize/{14.4,17}/
       \def\skvcl@fontsize@a{#1}\def\skvcl@fontsize@b{#2}
     ,
-    .args/fontsize/{#1,#2},
+    .arg/fontsize/{#1,#2},
     .cmd/watermarkscale/5,
     .cmd/watermarkcolor/gray!55,
   },
@@ -187,16 +188,21 @@
     first-page-number/firstpagenumber=#1,
     titlepage/maketitlepage=#1,
   },
-  % Options execution & processing:
+  % Options execution and processing:
   .families = {textemphasis,title},
+  % Ececute the options in all the prevailing families. If any of
+  % the options isn't found in at least one family, report error (ie,
+  % don't save the key to the list of 'remaining keys'). Unknown options
+  % should be flagged immediately.
   .execute options+={
     useitalic,usebold,usecolor,color,
     make-textemphasis-inactive=false,putdate,datefont,
     clearpage=false,pretitleskip,posttitleskip,
     authorfont,titlefont,watermarkscale,firstpagenumber,
     insertwatermark=false,watermarkxshift,watermarkyshift,
-    watermarktext,fontsize
+    watermarktext,watermarkcolor,fontsize
   },
+  % Use '.mega process options*' or '.copy class options and process...':
 %  .mega process options*={
 %    prefix=SKVC,
 %    families={textemphasis,title},
@@ -204,7 +210,7 @@
   .copy class options and process options in all families,
 }
 
-\skvrobustdef*\setskeyvaltestclass{%
+\skvrobustdef*\setupskvtestclass{%
   \skvsetkeys*+[SKVC]{textemphasis,title}%
 }
 
@@ -212,21 +218,21 @@
 \skvrobustdef*\setuptextemphasis#1{\skvsetkeys[SKVC]{textemphasis}{#1}}
 \newcommand*\xem[1]{\xem@emph{\xem@bold{\xem@colortext{\xem@color}{#1}}}}
 \newcommand*\xem@emph{%
-  \skvifbooltrue xem@useitalic\then
+  \skvifbool xem@useitalic\then
     \expandafter\emph
   \else
     \expandafter\@firstofone
   \fi
 }
 \newcommand*\xem@bold{%
-  \skvifbooltrue xem@usebold\then
+  \skvifbool xem@usebold\then
     \expandafter\textbf
   \else
     \expandafter\@firstofone
   \fi
 }
 \newcommand*\xem@colortext{%
-  \skvifbooltrue xem@usecolor\then
+  \skvifbool xem@usecolor\then
     \expandafter\textcolor
   \else
     \expandafter\@secondoftwo
@@ -258,7 +264,7 @@
           \end{tabular}\par
         }%
         \vskip1.5em\relax
-        \skvifbooltrue skvcl@putdate\then{{\skvcl@datefont\@date}}\fi
+        \skvifbool skvcl@putdate\then{{\skvcl@datefont\@date}}\fi
       \end{center}\par
       \@thanks
       \vfil\null
@@ -301,7 +307,7 @@
         \end{tabular}\par
       }%
       \vskip1em\relax
-      \skvifbooltrue skvcl@putdate\then{\skvcl@datefont\@date}\fi
+      \skvifbool skvcl@putdate\then{\skvcl@datefont\@date}\fi
     \end{center}%
     \par
     \vskip1.5em\relax
diff --git a/Master/texmf-dist/doc/latex/skeyval/skeyval-testpkg.sty b/Master/texmf-dist/doc/latex/skeyval/skeyval-testpkg.sty
index eae0c324f7d..30de37acd89 100644
--- a/Master/texmf-dist/doc/latex/skeyval/skeyval-testpkg.sty
+++ b/Master/texmf-dist/doc/latex/skeyval/skeyval-testpkg.sty
@@ -1,5 +1,5 @@
 %++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++%
-% This is file 'skeyval-testpkg.sty', version 1.1, 2012/10/15.             %
+% This is file 'skeyval-testpkg.sty', version 1.1a, 2012/10/16.            %
 %                                                                          %
 % This package and accompanying files may be distributed and/or            %
 % modified under the conditions of the LaTeX Project Public License,       %
@@ -27,7 +27,7 @@
 %++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++%
 
 \ProvidesPackage{skeyval-testpkg}
-  [2012/10/15 v1.1 skeyval test package 1 (AM)]
+  [2012/10/16 v1.1a skeyval test package 1 (AM)]
 \NeedsTeXFormat{LaTeX2e}
 \@ifpackageloaded{skeyval}{}{\RequirePackage{skeyval}}
 \RequirePackage{graphicx}
@@ -36,30 +36,12 @@
 
 %%++++++++++++++++ Passing options to packages +++++++++++++++++++%%
 
-\skvdeclarebooloption[SKVT]<passoptions>[skvtp@]{verbose}[true]{}
+\skvdeclarebooloption[SKVT]<testpkg>[skvtp@]{verbose}[true]{}
 
 % Declare options with default values that will be used when the options
-% are called without user values:
-% \DeclarePassedOptions{<option>=<default>,...}
-\skvrobustdef*\skvDeclarePassedOptions#1{%
-  \skvkvparse{#1}\skv@tempa{%
-    \def\do##1=##2=##3\@nil{%
-      \skvdeclareoption{##1}[##2]{%
-        \skvifcsdef{ver@##1.sty}{%
-          \skv@warn{Package '##1' has been loaded and
-            \MessageBreak now you've asked for it to be loaded}%
-        }{%
-          \skvAfterProcessOptions{%
-            \RequirePackage[####1]{##1}%
-          }%
-        }%
-      }%
-    }%
-    \expandafter\do\skv@tempa==\@nil
-  }%
-}
-
-\skvDeclarePassedOptions{%
+% are called without user values.
+%
+\skvDeclarePassedOptionsLoadPackage[SKVT]{testpkg}{%
   hyperref={colorlinks,breaklinks},xcolor=svgnames
 }
 
@@ -69,7 +51,7 @@
 % 'shadowbox' family below.
 \newcommand*\justified{}
 \skvordkey[SKVT]{abrtext}{align}[right]{%
-  \skvifcase\skvxifstrcmp{#1}
+  \skvifcase\skvxifstrcmpTF{#1}
     {left}{\def\mpfalign{flushleft}}
     {right}{\def\mpfalign{flushright}}
     {center}{\def\mpfalign{center}}
@@ -169,7 +151,7 @@
   .cmd/framecolor/black,
   .cmd/shadecolor/white,
   .cmd/shadowcolor/gray!55,
-  .cmd/boxwidth/2cm,
+  .cmd/boxwidth/1.5cm,
   .ord/framesize/.5pt/\def\currfboxrule{#1},
   .ord/shadowsize/2pt/\shadowspread=\dimexpr#1\relax,
   .choice/align/center/{%
@@ -187,28 +169,32 @@
 
 \skvdisablekeys[SKVT]{testfam}{put shadow, shade color}
 
-% 'Presetting keys' means set the following keys whenever \setkeys is called.
-% These keys should be set BEFORE the keys listed in the current argument of
-% \setkeys are set, provided that these keys aren't listed in the current
-% argument of \setkeys. If these keys appear in the current argument of \setkeys,
-% then obviously the user has new values for them or he wants the keys to be
-% set with their default values.
-
-% 'Postsetting keys' means set the following keys whenever \setkeys is called.
-% These keys should be set AFTER the keys listed in the current argument of
-% \setkeys are set, provided that these keys aren't listed in the current
-% argument of \setkeys.
-
-% The command \presetkeys of the xkeyval package expects both 'head' and 'tail'.
-% The skeyval package splits \presetkeys into two, hopefully less confusing,
-% commands: \skvpresetkeys and \skvpostsetkeys.
-
-% There is also command \skvpreposetkeys, which combines \skvpresetkeys and
-% \skvpostsetkeys. This expects both head and tail and is equivalent to
-% xkeyval's \presetkeys.
+% Presetting and posetting keys.
+%
+% 1. 'Presetting keys' means set the following keys whenever
+%    \setkeys is called. These keys should be set BEFORE the keys
+%    listed in the current argument of \setkeys are set, provided
+%    that these keys aren't listed in the current argument of \setkeys.
+%    If these keys appear in the current argument of \setkeys,
+%    then obviously the user has new values for them or he wants
+%    the keys to be set with their default values.
+%
+% 2. 'Postsetting keys' means set the following keys whenever
+%    \setkeys is called. These keys should be set AFTER the keys
+%    listed in the current argument of \setkeys are set, provided
+%    that these keys aren't listed in the current argument of \setkeys.
+%
+% 3. The command \presetkeys of the xkeyval package expects both
+%    'head' and 'tail'. The skeyval package splits \presetkeys into two,
+%    hopefully less confusing, commands: \skvpresetkeys and
+%    \skvpostsetkeys.
+%
+% 4. There is also command \skvpreposetkeys, which combines
+%    \skvpresetkeys and \skvpostsetkeys. This expects both head and
+%    tail and is equivalent to xkeyval's \presetkeys.
 
 \skvpresetkeys[SKVT]{shadowbox}{%
-  put frame,framecolor=black,framesize=.8pt,boxwidth=2cm,align=center,
+  put frame,framecolor=black,framesize=.8pt,boxwidth=1.5cm,align=center,
   shadecolor=gray!15
 }
 
@@ -240,13 +226,18 @@
 
 % The following are meant to demonstrate the use of the macro \directkeys:
 
-\newcount\skvsratchcnt
+\ifdefined\skvtestcnt
+  \skvtestcnt\z@
+\else
+  \newcount\skvtestcnt
+\fi
 \def\logsetting{%
-  \advance\skvsratchcnt\@ne
+  \advance\skvtestcnt\@ne
   \typeout{'\skvcurrentkey' set: no.
-    \ifnum\skvsratchcnt<10 0\fi\the\skvsratchcnt, %
+    \ifnum\skvtestcnt<10 0\fi\the\skvtestcnt, %
     path: \skvcurrentprefix/\skvcurrentfamily}%
 }
+
 \directkeys{%
   % #1 will be the user-value of the handler 'some handler'.
   .new handlers = {
@@ -284,29 +275,37 @@
   .ignore prefixes = {KVA,KVD},
   .ignore families = {fama,famb,famc},
   .restore families = {fama,famb},
-  .restore roots = {KVA/fama,KVD/famc},
+  .restore paths = {KVA/fama,KVD/famc},
 %  .ignore keys = {keyb,keyc},
   .new keys = {
     .ord/keya/keya-default,
     .cmd/keyb/keyb-default/\def\x##1{##1#1},
     .cmd/keyc/keyc-default,
-    .choice/keyd/center/{right,left,center},
+    .choice*/keyd/center
+      /{  right.do=\def\val@r{#1},
+          left.do=\def\val@l{#1},
+          center.do=\def\val@c{#1}
+        }
+      /\def\yes{value accepted}
+      /\def\no{value rejected},
     .bool/keye/true/
-      \ifskvindef\else
-        \logsetting
-      \fi
+      \ifskvindef\else\logsetting\fi
       \ifmp@keye\def\y##1{##1#1}\fi
     ,
     .bool/keyf/true/,
     .bool/keyg/true/
   },
+  .push path,
+  .path = KV/fam1,
+  .set keys = {keyd},
+  .pop path,
   .ignore keys = {keyb,keyc},
   % Stop processing this list:
   % .list break,
   .restore keys = {keyb,keyc},
   .preset keys  = {keyb,keyc},
   .postset keys = {keyb,keyc},
-  % save unknown keys in the default macro \<pref>@<fam>@rmkeys:
+  % Save unknown keys in the default macro \<pref>@<fam>@rmkeys:
   .save unknown keys = true,
   .save unknown keys in = \macroa,
   .set keys = {keya,keyb,keyc,keyd,keye},
@@ -317,11 +316,12 @@
   .set rmkeys*,
   % Execute arbitrary code:
   .exec code=\def\x#1{#1},
-  % Nesting of \directkeys is possible. At the end of the nest, prevailing
-  % variables of \directkeys revert to their previous (door) values:
+  % Nesting of \directkeys is possible. Pre-entry and post-entry
+  % topologies are independent. At the end of the nest,
+  % prevailing variables of \directkeys revert to their previous
+  % (pre-door) values:
   \directkeys{
-    .prefixes = {KVA,KVB},
-    .family = fam3,
+    .paths = {KVA/fam3,KVB/fam3},
     .holder prefix = hp@,
     .define keys = {
       .cmd/keya/keya-default/\def\x##1{##1#1},
@@ -332,12 +332,14 @@
   .exec code = \def\keycval{true},
   % Prepend style keye to key1 and key2:
   .prepend style={key1/{keye=.expanded{\keycval}},key2/{keye=false}},
-  .prepend style={{key3,key4}/{keye=true,keyf=true}, key5/{keye=false}},
+  % Multi-prepend styles:
+  .prepend style={{key3,key4}/{keye=true,keyf=true},key5/{keye=false}},
   % Prepend style keyd to key6:
   .prepend style={key6/{keyd=right}},
-  % Append styles keye and keyf to key7 and key8:
+  % Append styles keye and keyf to key7 and key8.
+  % '.styles' and '.style' are equivalent to '.append styles'
+  % and '.append style'.
   .append style={key7/{keye=true},key8/{keyf=false}},
-  %
   % The next two link keyb and keyc to key9. #1 here refers to the
   % current value of key9. The same effect can be achieved directly
   % via the '.link' handler:
@@ -347,7 +349,7 @@
   % Link keye and keyf to key10 and key11. The values of key10 and
   % key11 are used to set keye and keyf. key10 and key11 are hence
   % 'parent keys'.
-  .link={key10/keye, key11/keyf},
+  .link = {key10/keye, {key11,key12}/{keyf,keyg}},
   .set keys = {key10=true},
   .ignore key = keyf,
   .save unknown keys in = \macrob,
@@ -394,7 +396,7 @@
 %%+++++++++++++++++++++ Changing the key parser ++++++++++++++++++++%%
 
 \setupskeyval{key parser={;}}
-\AfterDefineKeys{\setupskeyval{keyparser={,}}}
+\skvafterdefinekeys{\setupskeyval{keyparser={,}}}
 \skvdefinekeys*[SKVT]{example}[exm@]{%
   .zbool/put frame/true;
   .cmd/shadecolor/green;
@@ -406,13 +408,12 @@
     justified.do=\let\curralign\@iden
   };
 }
-%\setupskeyval{keyparser={,}}
 
 %%++++++++++++++++++++++++++ Options section ++++++++++++++++++++++%%
 
 \def\skvtp@unknownoptions{}
 
-\skvunknownoptionhandler[SKVT]<abrtext,shadowbox,citation,passoptions>{%
+\skvunknownoptionhandler[SKVT]<abrtext,shadowbox,citation,testpkg>{%
   \edef\skvtp@unknownoptions{%
     \skvtp@unknownoptions\ifx\skvtp@unknownoptions\@empty\else,\fi
     #3%
@@ -425,9 +426,10 @@
   }%
 }
 \skvexecuteoptions[SKVT]<abrtext>{align=.expanded{\alignval},
-  text style=.expand once{\stextstyle},author,show author}
+  text style=.expand once{\stextstyle},author,show author
+}
 
-\skvprocessoptions*+[SKVT]<abrtext,shadowbox,citation,passoptions>\relax
-%\skvrestrictedprocessoptions*+[SKVT]<abrtext,shadowbox,citation,passoptions>\relax
+\skvprocessoptions*+[SKVT]<abrtext,shadowbox,citation,testpkg>\relax
+%\skvrestrictedprocessoptions*+[SKVT]<abrtext,shadowbox,citation,testpkg>\relax
 
 \endinput
diff --git a/Master/texmf-dist/doc/latex/skeyval/skeyval-view-pokayoke1.pdf b/Master/texmf-dist/doc/latex/skeyval/skeyval-view-pokayoke1.pdf
index 320b74097e2..fc4c8014215 100644
--- a/Master/texmf-dist/doc/latex/skeyval/skeyval-view-pokayoke1.pdf
+++ b/Master/texmf-dist/doc/latex/skeyval/skeyval-view-pokayoke1.pdf
diff --git a/Master/texmf-dist/doc/latex/skeyval/skeyval-view-pokayoke1.tex b/Master/texmf-dist/doc/latex/skeyval/skeyval-view-pokayoke1.tex
index c29448d04b5..9ad80b2a5c5 100644
--- a/Master/texmf-dist/doc/latex/skeyval/skeyval-view-pokayoke1.tex
+++ b/Master/texmf-dist/doc/latex/skeyval/skeyval-view-pokayoke1.tex
@@ -1,17 +1,22 @@
 \documentclass{skeyval-testclass}
 \usepackage[xcolor-options=dvipsnames]{skeyval-view}
+\usetikzlibrary[topaths]
 
 \makeatletter
 
 \setupviewkeys{length of default=30}
 
 \skvdefinekeys[KV]{fam1}[vhp@]{%
-  .ord/keya/default-a,
+  .initialize after define,
+  .ord/{keya,keya2}/default-a,
   .cmd/keyb,
   .zcmd/key c/\def\cmdc##1{##1}/
     \edef\y{\detokenize\expandafter{\vhp@keyc}}\def\x##1{#1*key c*##1},
-  .choice/keyd/center/
-    {center.do=\def\x##1{#1*##1},left.do={\def\ans{#1}},right},
+  % No default for keyd:
+  .choice/keyd/.na
+    /{center.do=\def\x##1{#1*##1},left.do={\def\ans{#1}},right}
+    /\def\z##1{#1*##1}
+    /\@warning{Invalid value for keyd},
   .bool/show shadow/true,
   .zbool/show center/true/\edef\cmd{\ifvhp@showcenter Yes\else No\fi},
   .ord/keye,
@@ -44,7 +49,7 @@
 \begin{document}
 
 \title{The \texttt{\textcolor{blue}{skeyval-view}} Package\\[.25ex]
-  Version 1.1\\[1ex]
+  Version 1.1a\\[1ex]
   \textsf{Test document}}
 \author{Ahmed Musa}
 \maketitle
@@ -89,6 +94,44 @@
 }
 
 \newpage
+
+\skvtestcnt0\relax
+\skvrecurse
+  \advance\skvtestcnt1\relax
+  \vskip\baselineskip\noindent
+  \textcolor{blue!\the\numexpr10*\skvtestcnt!red!%
+  \the\numexpr100/\skvtestcnt}{%
+    The play was a great success, but the audience was a disaster.
+    \endgraf{\small Oscar Wilde, 1854--1900}
+  }%
+\while
+  \ifnum\skvtestcnt<8\relax
+\fi
+
+% Credit: Quintin Jean-Noël
+\newcount\mycount
+\begin{center}
+\begin{tikzpicture}[scale=.5,transform shape]
+\newforeach \nr in {1,...,8}{
+  \mycount=\numexpr(\nr-1)*45\relax
+  \node[draw,circle,inner sep=0.25cm] (N-\nr) at (\the\mycount:5.4cm) {};
+}
+\newforeach \nr in {9,...,16}{
+  \mycount=\numexpr(\nr-1)*45+22\relax
+  \node[draw,circle,inner sep=0.25cm] (N-\nr) at (\the\mycount:5.4cm) {};
+}
+\newforeach \nr in {1,...,15}{
+  \mycount=\numexpr\nr+1\relax
+  \newforeach \nra in {\the\mycount,...,16}{
+    \path (N-\nr) edge[->,bend right=3] (N-\nra) edge[<-,bend left=3]
+      (N-\nra);
+  }
+}
+\end{tikzpicture}
+\end{center}
+
+
+\bigskip
 Find more information about the \textcolor{red}{\texttt{show shadow}} option on page~\pageref{KV/fam1/show shadow}.
 
 \end{document}