summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/keyval2e
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2011-08-15 23:03:35 +0000
committerKarl Berry <karl@freefriends.org>2011-08-15 23:03:35 +0000
commitc94e2deaaa21a46bcd63069cb63f3f6a807139a9 (patch)
treeaa4780c69b79091b8e7dde5806fde7dbea26e216 /Master/texmf-dist/doc/latex/keyval2e
parent73c5698f2b0b279e6ecb2a486f71dc70ba1d2340 (diff)
keyval2e (15aug11)
git-svn-id: svn://tug.org/texlive/trunk@23565 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/keyval2e')
-rw-r--r--Master/texmf-dist/doc/latex/keyval2e/README85
-rw-r--r--Master/texmf-dist/doc/latex/keyval2e/keyval2e-examples.tex39
-rw-r--r--Master/texmf-dist/doc/latex/keyval2e/keyval2e-guide.pdfbin0 -> 272378 bytes
-rw-r--r--Master/texmf-dist/doc/latex/keyval2e/keyval2e-guide.tex205
4 files changed, 247 insertions, 82 deletions
diff --git a/Master/texmf-dist/doc/latex/keyval2e/README b/Master/texmf-dist/doc/latex/keyval2e/README
index 6930b8fc2e7..960feb21869 100644
--- a/Master/texmf-dist/doc/latex/keyval2e/README
+++ b/Master/texmf-dist/doc/latex/keyval2e/README
@@ -2,7 +2,7 @@ This is the README file for the keyval2e package.
VERSION
-Version 0.0.1, August 2011
+Version 0.0.1a, August 2011
SUMMARY
@@ -16,7 +16,7 @@ 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
+the command \kve@setdefaults) as soon as they are created or later. 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
@@ -37,88 +37,9 @@ warranties of merchantability and fitness for any particular purpose.
RELATED PACKAGES
-keyval.sty, xkeyval.sty, ltxkeys
+keyval.sty, xkeyval.sty, ltxkeys.sty
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
diff --git a/Master/texmf-dist/doc/latex/keyval2e/keyval2e-examples.tex b/Master/texmf-dist/doc/latex/keyval2e/keyval2e-examples.tex
new file mode 100644
index 00000000000..6af05f802a4
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/keyval2e/keyval2e-examples.tex
@@ -0,0 +1,39 @@
+\documentclass{minimal}
+\usepackage{keyval2e,color}
+\makeatletter
+\kve@definekeys[KV]{fam}[mp@]{%
+ keyone/+/\ifstrcmpTF{#1}{+}{\def\userinput{#1}}{\def\userinput{???}},
+ keytwo/+,
+ keythree/+,
+ keyfour/+
+}
+\def\fourplus{+,+,+,+}
+\newcommand*\putmany[2][*]{%
+ \@tempcnta\z@
+ \loop
+ \advance\@tempcnta\@ne#1%
+ \ifnum\@tempcnta<#2\relax
+ \repeat
+}
+\newcommand{\testa}[2]{%
+ \kve@setafterdefaults[KV]{fam}{#2}%
+ \edef\tempa{\mp@keyone,\mp@keytwo,\mp@keythree,\mp@keyfour}%
+ Test #1: \textcolor{red}{*} \texttt{\tempa} \textcolor{red}{*}%
+ \space\ifxTF\tempa\fourplus{All values are defaults\putmany[\space]{2}}%
+ {At least one value is set}%
+ \@spaces\textcolor{red}{||} keyone's value: \userinput
+}
+\newcommand{\testb}[2][]{\testa{#2}{#1}}
+\begin{document}
+
+\ttfamily\noindent
+\testa{Aa}{}\\
+\testa{Ba}{keyone=+,keythree=+}\\
+\testa{Ca}{keytwo= +,keythree=a}\\
+\testa{Da}{keyone=b,keythree=a,keyfour=+}\\
+\testb{Ab}\\
+\testb[keyone= +,keythree=+]{Bb}\\
+\testb[keytwo=+,keythree=a]{Cb}\\
+\testb[keyone=b,keytwo=+,keythree=a]{Db}\\
+
+\end{document} \ No newline at end of file
diff --git a/Master/texmf-dist/doc/latex/keyval2e/keyval2e-guide.pdf b/Master/texmf-dist/doc/latex/keyval2e/keyval2e-guide.pdf
new file mode 100644
index 00000000000..fc2af6ccbc2
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/keyval2e/keyval2e-guide.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/keyval2e/keyval2e-guide.tex b/Master/texmf-dist/doc/latex/keyval2e/keyval2e-guide.tex
new file mode 100644
index 00000000000..d0c7e7898d0
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/keyval2e/keyval2e-guide.tex
@@ -0,0 +1,205 @@
+\documentclass[
+ use-a4-paper,
+ use-10pt-font,
+ final-version,
+ use-UK-English,
+ fancy-section-headings,
+ frame-section-numbers,
+ para-abstract-style,
+ input-config-file,
+ no-hyperref-messages
+]{amltxdoc}
+
+\hfuzz1pt
+\makeatletter
+\WrapQuotes
+\makeindex
+
+\begin{document}
+
+\begin{frontmatter}
+\title{The \texttt{\color{blue}keyval2e} Package\titleref{t1}}
+\titlenotes[t1]{%
+ The package is available at \iftogTF{pdf}{\url{\@titleurl}}
+ {\url{\@shorttitleurl}}. This user manual corresponds to version~0.0.1a.
+}
+\subtitle{Robust and fast key parser}
+\titleurl{http://www.ctan.org/tex-archive/macros/latex/contrib/keyval2e/}
+\shorttitleurl{http://www.ctan.org/}
+\author{Ahmed Musa \Email{amusa22@gmail.com}\\Preston, Lancashire, UK}
+
+\end{frontmatter}
+
+\begin{xwmshade}[fillcolor=white,framecolor=orange,framerule=1pt,framesep=2pt,
+ width=1.0\hsize]\tableofcontents
+\end{xwmshade}
+
+
+\docsection{Introduction}
+
+The \pkg'{keyval2e} provides lightweight and robust facilities for creating and managing keys. Its machinery isn't as extensive as that of, \eg, \pkg'{ltxkeys} 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 \pkg'{ltxkeys}. This package was prompted by a subscriber's post on \comptexttex in August 2011.
+
+In the \pkg'{keyval2e}, ordinary, boolean, and choice keys can be created using only one command (\fx{\kve@definekeys}). Keys can be initialized with their default values (with the command \fx{\kve@setdefaults}) as soon as they are created, or at any time. 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 \fx{\kve@setafterdefaults}, meaning \quoted{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 \fx{\kve@setkeys}.
+
+The \pkg'{keyval2e} has no service for processing package or class options. See the \pkg'{ltxkeys} for this service. I have seen users who require the services of keys only in documents, and not in package or class files. And some package authors still use \latex's native option processing schemes. For those authors, the \pkg'{keyval2e} may be used to process keys (but not options) in package and class files.
+
+The \pkg'{keyval} provides a simple and widely used interface, but it is not robust, in the sense that it strips off outer curly braces in key values. Also, it has no means to automatically call up default key values after the keys have been defined. Moreover, it automatically redefines existing keys.
+
+
+\docsection{Package options}
+
+The \pkg'{keyval2e} currently has no options.
+
+
+\docsection{User commands}
+
+\start+{newmacro}[\kve@definekeys, \kve@setkeys, etc]
+\kve@definekeys[|A(pref)]{|A(fam)}[|A(mp)]{%
+ |A(key-1)/|A(defa-1)/|A(callback-1),
+ ...,
+ |A(key-n)/|A(defa-n)/|A(callback-n)
+}
+
+\kve@definekeys|*[|A(pref)]{|A(fam)}[|A(mp)]{%
+ |A(key-1)/|A(defa-1)/|A(callback-1),
+ ...,
+ |A(key-n)/|A(defa-n)/|A(callback-n)
+}
+
+\kve@setkeys[|A(pref)]{|A(fam)}[na]{|A(keyval)}
+
+\kve@setdefaults[|A(pref)]{|A(fam)}[|A(na)]
+
+\kve@setafterdefaults[|A(pref)]{|A(fam)}[|A(na)]{|A(keyval)}
+\finish{newmacro}
+\fxim*{\kve@definekeys,\kve@setkeys,\kve@setdefaults,\kve@setafterdefaults}
+
+Here, \ang{pref} is the optional key prefix (default \fx{KV}), \ang{fam} is the mandatory family, \ang{mp} is the key-value-holding macro prefix (default \fx{kvmp@}), \ang{defa-i} is the default value of key \quotedfx{i}, \ang{callback-i} is the callback (\ie, the function that will be executed when the key is set) of key \quotedfx{i}, and \ang{keyal} is a list of \keyval pairs.
+
+\ang{na} is a comma-separated list of keys that should be ignored, ie, not set in the current run of setting keys\footnote{When setting keys, undefined keys are reported by the \pkg'{keyval2e} as undefined and are not saved as \quoted{remaining keys}. Moreover, there are no \quoted{undefined key handlers} and no \quoted{handled keys} in this package. Please see the \pkg'{ltxkeys} for these facilities.}. \mpkey will hold the current value of \ang{key}. The key macro (\ie, the one that holds the key's callback) is always \preffamkey.
+
+The \stform of the command \fx{\kve@definekeys} will define only definable keys, in the sense of \latex's \hx{\newcommand}. In that case the commands \mpkey must also be unique, \ie, not previously defined. The plain form \fx{\kve@definekeys} will always define the key, whether or not the key already exists; existing keys will thus be overwritten in this case.
+
+You can use \fx{#1} in \ang{callback} to access the value of the current key. Also the macros \ffx'{\currpref, \currfam, \currkey, \currval, \currkeyval} are always available when setting keys and may be called in \ang{callback}.
+
+The command \fx{\kve@setdefaults} will set all the keys in the given family \ang{fam} and prefix \ang{pref} with their default values. All boolean keys (\ie, those with a default in the set \boolset) will be initialized with a default value of \fx{false}. This is to avoid premature toggling of the state of such keys. The command \fxis{\kve@setwithdefaults}{\kve@setdefaults} is an alias for \fx{\kve@setdefaults}.
+
+\Note After the keys have been defined, they are automatically set with their default values using the command \fx{\kve@setdefaults}. This provides default definitions for immediate use.
+
+The command \fx{\kve@setafterdefaults} will set the given \keyval pairs after initializing to default values all those keys (in the given family and prefix) that are not listed in the accompanying \keyval list. This provides a mechanism for (re)initialing to default values those keys that don't have values in \keyval. This type of (re)initialization is often required in the deployment of keys, and it is useful to have a handy way of accomplishing this semi-automatically.
+
+
+\docsubsection{Utility macros}
+
+The following macros are utilities.
+
+\start{newmacro}[\kve@checkchoice]
+\kve@checkchoice{|A(teststring)}{|A(nominations)}{|A(nomatch)}
+\finish{newmacro}
+\fxim*{\kve@checkchoice}
+
+The \ang{nominations} have the syntax
+
+\start'{macro}[Nominations and callbacks]
+|A(nom-1)|R(:)|A(callback-1),...,|A(nom-n)|R(:)|A(callback-n)
+\finish{macro}
+
+Here, please note the \qcolon, which separates \ang{nom} from \ang{callback}. \ang{callback-i} will be executed if \ang{nom-i} matches \ang{teststring}. The first match found takes priority over subsequent matches. The fallback \ang{nomatch} will be executed if \ang{teststring} doesn't match any of the \ang{nom}'s.
+
+\start{newmacro}[\kve@checkbool]
+\kve@checkbool{|A(val)}{|A(true)}{|A(false)}
+\finish{newmacro}
+\fxim*{\kve@checkbool}
+
+This checks if \ang{val} is an admissible value of a boolean, namely, if it is in the set \boolset. If \ang{val} is valid, the text \ang{true} will be executed; otherwise \ang{false} will be executed.
+
+\start{newmacro}[\kve@keyvalerr]
+\kve@keyvalerr
+\finish{newmacro}
+\fxim*{\kve@keyvalerr}
+
+This is a parameterless command that uses \ffx'{\currkey,\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 key value that is invalid.
+
+
+\docsection{Examples}
+
+\start{example}[\kve@definekeys]
+|R(\kve@definekeys)[KV]{fam}[mp@]{%
+ |com(keya and keyb are boolean keys:)
+ keya/true/|R(\kve@checkbool){#1}{\def\result{OK}}{|R(\kve@keyvalerr)},
+ keyb/false/|R(\kve@checkbool){#1}{%
+ \usename{@tempswa#1}%
+ \if@tempswa\def\x{found}\else\def\x{not-found}\fi
+ }{%
+ \kve@keyvalerr
+ },
+ |com(keyc is a choice key:)
+ keyc/left/|R(\kve@checkchoice){#1}{left:\let\x\flushleft,
+ right:\let\x\flushright}{|R(\kve@keyvalerr)},
+ keyd/right/\def\x##1{#1xx##1},
+ |com(keyone has an empty default value:)
+ keyone//\ifx\\#1\\\def\x{no-val}\else\def\x{#1}\fi,
+ |com(keytwo has no callback:)
+ keytwo/+,
+ |com(keythree has a braced default value:)
+ keythree/{left}/|R(\kve@setkeys)[KV]{fam}{keyone=#1}
+}
+\finish{example}
+
+Remember that after the keys have been defined, they are automatically set with their default values using the command \fx{\kve@setdefaults}.
+
+The following command says \quoted{set the current keys with their current values, after the defaults have been set up}. Keys with current values will not be set with their default values:
+
+\start{example}[\kve@setafterdefaults]
+\kve@setafterdefaults[KV]{fam}{keyone=+,keytwo=abc,keythree=+,keyfour=xax}
+\finish{example}
+
+Please see the example file for the fuller version of the following example:
+
+\start+{example}[Creating a key command]
+\documentclass{minimal}
+\usepackage{keyval2e}
+\makeatletter
+|R(\kve@definekeys)[KV]{fam}[mp@]{%
+ keyone/+,
+ keytwo/+,
+ keythree/+,
+ keyfour/+
+}
+\def\fourplus{+,+,+,+}
+\newcommand{\test}[2]{%
+ |R(\kve@setafterdefaults)[KV]{fam}{#2}%
+ \edef\tempa{\mp@keyone,\mp@keytwo,\mp@keythree,\mp@keyfour}%
+ Test #1: *\texttt{\tempa}*%
+ \ifxTF\tempa\fourplus{All values are defaults}{At least one value is set}%
+}
+\begin{document}
+\ttfamily\noindent
+\test{A}{}\\
+\test{B}{keythree=+}\\
+\test{C}{keythree=a}\\
+\end{document}
+\finish{example}
+
+
+\docsection(sec:version-hist){Version history}
+
+The \stsign on the right-hand side of the following lists means the subject features in the package but is not reflected anywhere in this user guide.
+
+\begin{versionhist}
+ \begin{version}{0.0.1}{2011/08/13}
+ \item First public release.\vsecref*
+ \end{version}
+ \begin{version}{0.0.1a}{2011/08/14}
+ \item Completed the user guide.\vsecref*
+ \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