summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/skeyval/README
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/skeyval/README')
-rw-r--r--Master/texmf-dist/doc/latex/skeyval/README299
1 files changed, 257 insertions, 42 deletions
diff --git a/Master/texmf-dist/doc/latex/skeyval/README b/Master/texmf-dist/doc/latex/skeyval/README
index 5dc7d3eae36..fe6e31d7d37 100644
--- a/Master/texmf-dist/doc/latex/skeyval/README
+++ b/Master/texmf-dist/doc/latex/skeyval/README
@@ -1,42 +1,257 @@
-%+++++++++++++++++++++++++++++++++++ INTRODUCTION +++++++++++++++++++++++++++++++++++%
-% %
-% This is the Readme file for the skeyval package, version 0.72. %
-% May 2010 %
-% %
-% Copyright (c) 2010 Ahmed Musa (a.musa@rocketmail.com). %
-% %
-%+++++++++++++++++++++++++++++++++++++ MOTIVATION +++++++++++++++++++++++++++++++++++%
-% %
-% The xkeyval package introduced many concepts for key definition and %
-% management. The skeyval package extends the functionality of the xkeyval %
-% package in many ways, including introducing: %
-% %
-% 1. Toggle keys %
-% 2. Complementary boolean and toggle keys %
-% 3. Mechanisms for reserving, unreserving, suspending, restoring, %
-% and removing keys %
-% 4. Tools for defining keys such that no existing key is inadvertently %
-% redefined %
-% 5. List normalization when setting keys %
-% 6. A mechanism for defining multiple keys of differing genres using only %
-% one command %
-% 7. Commands for checking the statuses of keys across multiple key prefixes %
-% and families %
-% 8. User-value keys and using pointers in defining keys %
-% 9. Some general-purpose LaTeX programming macros and hooks %
-% %
-%+++++++++++++++++++++++++++++++++++++ LICENSE ++++++++++++++++++++++++++++++++++++++%
-% %
-% This package and accompanying files may be distributed and/or modified under %
-% the conditions of the LaTeX Project Public License, either version 1.3 of %
-% this license or any later version. The latest version of this license is in %
-% http://www.latex-project.org/lppl.txt and version 1.3 or later is part of all %
-% distributions of LaTeX version 2005/12/01 or later. %
-% %
-% The LPPL maintenance status of this software is 'author-maintained'. %
-% %
-% 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 a particular purpose. %
-% %
-%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++% \ No newline at end of file
+This is the README file for the 'skeyval' package.
+
+AUTHOR
+
+Ahmed Musa
+
+VERSION
+
+Version 1.1, October 2012.
+
+LOCATION ON CTAN
+
+macros/latex/contrib/skeyval
+
+LICENSE
+
+Copyright (c) 2010-2012 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.
+
+
+FILES
+
+The following files constitute the skeyval bundle and must be
+distributed as a whole:
+
+ readme, skeyval.sty, skeyval-core.tex, skeyval-for.tex,
+ skeyval-view.sty, skeyval-ltxpatch.sty, skeyval-ltxcmds.tex,
+ skeyval-pstkey.sty, skeyval-pstkey.tex, skeyval-testclass.cls,
+ and skeyval-testpkg.sty.
+
+The skeyval package can be used by LaTeX and non-LaTeX users.
+LaTeX users should load the package via
+
+ \usepackage[<options>]{skeyval}
+
+or, in class files and packages,
+
+ \RequirePackage[<options>]{skeyval}
+
+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.
+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.
+
+
+SUMMARY
+
+The 's' in skeyval means 'skeleton keys' or 'master keys'.
+
+The skeyval package provides commands for compactly defining and
+initializing all types of key (ordinary, command, boolean, style, choice,
+etc). It attempts to combine the features of ltxkeys package (which has
+the syntax of the xkeyval package) and pgfkeys package. One of the powers
+of pgfkeys package lies in its use of handlers. But the way handlers
+are used in pgfkeys package does add to computational complexity and
+overheads. Family or key filtering in pgfkeys is particularly complex
+and inefficient. Nesting of family or key filtering is, in particular,
+not recommended.
+
+In pgfkeys package, handlers come at the end of the key name, so that
+if a key isn't defined, the system tests to find if the key has a
+handler at its end. If a handler is found and defined, the handler's
+callback (called 'code' by pgfkeys package) is executed on the
+current path.
+
+The skeyval package puts handlers at the beginning of the key
+(or a set of keys) and uses the handler to process the key (or a set
+of keys). This speeds up key processing and reduces the computational
+complexity. Key processing, including filtering, can be nested
+naturally and efficiently.
+
+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
+ 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
+ now possible to define a rather weird key like
+
+ \skvpntkey[KV]{fam}{evaluate (?) as (?) using (?)}{\edef#2{#3}}
+
+ The key name here is 'evaluate (?) as (?) by (?)'. It has three
+ arguments, indicated by the closed parenthesis. The mark '?' can be
+ replaced by any character or characters, and the key could have up
+ to 9 arguments. This key can be set as
+
+ \skvsetkeys[KV]{fam}{evaluate (\x) as (\y) using (\numexpr\x*2)}
+
+ We can also define the same key with the default values specified:
+
+ \skvpntkey[KV]{fam}{evaluate (?) as (?) using (?)}[\x\y{\numexpr\x*2}]{%
+ \def\argone{#1}\def\argtwo{#2}\def\argthree{#3}%
+ }
+
+ and set it as follows (if pgfmath package is loaded):
+
+ \skvsetkeys[KV]{fam}{%
+ 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:
+
+ \directkeys{%
+ .exec=\def\avalue{a+b},
+ .prefixes={KV1,KV2},
+ .families={fam1,fam2},
+ .holder prefix=mp@,
+ .initialize keys after define,
+ .define keys={
+ .ord/keya/def-a/\def\xa##1{#1*##1*#2},
+ .arg/keya/#1+#2,
+ .cmd/.value required{keyb}/def-b/\def\cmdb##1{##1@#1},
+ },
+ .initial values={
+ keya=ini-value,
+ },
+ .ignore family=fam2,
+ .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:
+ \directkeys{
+ .path=KV3/fam3,
+ .new keys={
+ .ord/keya/defa/\def\ya##1{#1*##1*#2},
+ .arg/keya/#1+#2,
+ .choice/keyc/center/{right,left,center,justified},
+ .arg expanded/keyc/#1,
+ .bool/keyd/true,
+ .cmd/.forbid value{keye}/defe/\def\ye##1{#1*##1},
+ },
+ },
+ .try set keys={
+ .paths={KV1/fam1,KV3/fam3},
+ .try=2, .goal=1
+ }{
+ keyc=left,keyd=false
+ },
+ .ignore path=KV1/fam1,
+ .exec=\def\cvalue{center},
+ .search also set keys={
+ .add prefix=KV3,
+ .add families={fam3,fam4},
+ .max attempts=4, .goal=2,
+ }{
+ keyc=.expand once{\cvalue}
+ },
+ .append values={
+ keya=\def\y##1{#1+##1},
+ keyb=\def\w##1{#1+##1},
+ },
+ .prepend code={
+ keyb=\def\pre##1{#1+##1},
+ },
+ .styles{
+ key1/keya=value1,
+ key2/keyb=value2
+ },
+ .inherit code={
+ key1/keyb, key2/keyd
+ },
+ .preset keys={
+ key1,key2
+ },
+ }
+
+ 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.
+
+ The handlers of skeyval package start with a dot (.),
+ as in pgfkeys package.
+
+4. 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:
+
+ \directkeys{%
+ .link={key1, key2}/keya,
+ .link={key3, key4}/{keya, keyb},
+ .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},
+ }
+
+5. 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.
+
+6. 'Quick keys' are a new concept. They're quite fast to define and set.
+
+7. 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}/,
+ .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},
+ .zbool/show center/true/\edef\cmd{\ifthp@showcenter Yes\else No\fi}
+ }
+
+ 'z-keys' are keys whose names are zapped (ie, spaces are removed)
+ internally. This is to allow holder/store macros to be used
+ without spaces in their names, while maintaining key names with
+ spaces.
+
+8. Keys can be set using \skvsetkeys, \directkeys (with the handlers
+ .set keys, .try, etc.), or \skvusekeys:
+
+ \krdusekeys[
+ .prefix=KVA,
+ .families={fam1,fam2},
+ .set in all families,
+ .save unknown keys
+ ]{%
+ keya,keyb
+ }
+
+9. 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
+ PSTricks developers and users, as did xkeyval package.
+
+11. 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
+ arbitrary parsers and list separators, including active parsers.
+
+
+% End of readme file \ No newline at end of file