new latex package keyval2e (14aug11)

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

1 files changed, 124 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/latex/keyval2e/README b/Master/texmf-dist/doc/latex/keyval2e/README
new file mode 100644
index 00000000000..6930b8fc2e7
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/keyval2e/README
@@ -0,0 +1,124 @@
+This is the README file for the keyval2e package.
+
+VERSION
+
+Version 0.0.1, August 2011
+
+SUMMARY
+
+The keyval2e package provides lightweight and robust facilities for
+creating and managing keys. Its machinery isn't as extensive as
+that of, eg, ltxkeys package, but it is equally robust. Ease of
+use and speed of processing are the two main motives of this package.
+Some, indeed many, applications of the key-value syntax (while they
+call for robustness) don't require the full armor of key-value
+processing as found in, eg, the ltxkeys package.
+
+Ordinary, boolean, and choice keys can be created using only
+one command (\kve@definekeys). Keys can be initialized (with
+the command \kve@setdefaults) as soon as they are created. And
+in any run the default values of keys can be used to set keys that
+have no current values. The latter task is accomplished by the
+command \kve@setafterdefaults, meaning 'set keys with the current
+values after those without current values have been initialized/set
+with their default values'. Normally, keys are set with the
+re-entrant command \kve@setkeys.
+
+LICENSE
+
+Copyright (c) 2011 Ahmed Musa.
+
+This software is author-maintained. Permission is granted to copy,
+distribute and/or modify this software under the terms of the
+LaTeX Project Public License, version 1.3 or higher. 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 any particular purpose.
+
+RELATED PACKAGES
+
+keyval.sty, xkeyval.sty, ltxkeys
+
+AUTHOR
+
+Ahmed Musa (amusa22@gmail.com)
+
+USER COMMANDS
+
+\kve@definekeys[<pref>]{<fam>}{<key-1>/<defa-1>/<callback-1>,...,
+  <key-n>/<defa-n>/<callback-n>}
+
+\kve@setkeys[<pref>]{<fam>}[na]{<keyval pairs>}
+
+\kve@setdefaults[<pref>]{<fam>}[<na>]
+
+\kve@setafterdefaults[<pref>]{<fam>}[<na>]{<curr-keyval>}
+
+Here, <pref> is the optional key prefix, <fam> is the
+mandatory family, and [<na>] is a comma-separated list
+of keys that should be ignored, ie, not set in the current
+run. Undefined keys are reported as undefined and are not
+saved as 'remaining keys'. There are no 'undefined key
+handlers' and no 'handled keys' (see the ltxkeys package
+for these facilities).
+
+You can use #1 in <callback> to access the value of the current
+key. Also the macros \currpref, \currfam, \currkey, \currval,
+and \currkeyval are always available.
+
+The following macros are utilities:
+
+\kve@checkchoice{<teststring>}{<nominations>}{<nomatch>}
+
+The <nominations> have the syntax
+
+<nom-1>:<callback-1>,...,<nom-n>:<callback-n>
+
+Here, <callback-i> will be executed if <nom-i> matches <teststring>.
+The first match found takes priority over subsequent matches.
+
+The action <nomatch> will be executed if <teststring> doesn't
+match any of the <nom>'s.
+
+\kve@checkbool{<val>}{<true>}{<false>}
+
+This checks if <val> is an admissible value of a boolean,
+namely, if it is in the set {true | false}. The text <true> will
+be executed if <val> is valid; otherwise <false> will be executed.
+
+\kve@keyvalerr
+
+This is a parameterless command that uses \currkey and
+\currval internally. It simply generates an error to indicate
+that the current value of a key is invalid. It will indicate the
+key name and the truncated version of the value that is invalid.
+
+EXAMPLES
+
+\kve@definekeys[KV]{fam}{%
+  % keya and keyb are boolean keys:
+  keya/true/\kve@checkbool{#1}{\def\result{OK}}\kve@keyvalerr,
+  keyb/false/\kve@checkbool{#1}{\usename{@tempswa#1}}\kve@keyvalerr,
+  % keyc is a choice key:
+  keyc/left/\kve@checkchoice{#1}{left:\let\x\flushleft,
+    right:\let\x\flushright}\kve@keyvalerr,
+  keyone/+/\csn@def{mp@keyone}{#1},
+  keytwo/+/\csn@def{mp@keytwo}{#1},
+  keythree/+/\csn@def{mp@keythree}{#1},
+  keyfour/+/\csn@def{mp@keyfour}{#1}
+}
+
+Now that the keys have been defined, set them with their default
+values:
+
+\kve@setdefaults[KV]{fam}
+
+The following command says 'the current keys will be set with
+the current values, after the defaults have been set up'. 
+Keys with current values will not be set with their default values:
+
+\def\mysetkeys#1{%
+  \ifblankTF{#1}{}
+  {\kve@setafterdefaults[KV]{fam}{#1}}%
+}
+\mysetkeys{keyone=+,keytwo=abc,keythree=+,keyfour=+} 
\ No newline at end of file