diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/ltxkeys')
| -rw-r--r-- | Master/texmf-dist/doc/latex/ltxkeys/README | 46 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/ltxkeys/ltxkeys-guide.txt | 530 |
2 files changed, 576 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/ltxkeys/README b/Master/texmf-dist/doc/latex/ltxkeys/README new file mode 100644 index 00000000000..a0d9804f9e3 --- /dev/null +++ b/Master/texmf-dist/doc/latex/ltxkeys/README @@ -0,0 +1,46 @@ +This is the README file for the ltxkeys package. + +SUMMARY + +The ltxkeys package provides facilities for creating and managing +keys in the sense of the keyval and xkeyval packages, but it +is intended to be more robust and faster. Its robustness emanates +from its ability to preserve braces in key values throughout +parsing. The need to preserve braces in key values emerges often +in parsing keys. This is often the case in, eg, the xwatermark +package. The package is faster than the xkeyval package because, +among other features, it avoids character-wise parsing of key +values (which is called selective sanitization by the xkeyval +package). + +It also provides additional functionalities for defining and +managing keys. + +In the ltxkeys package, the notion of 'presetting' keys differs +from that of the xkeyval package. Only 'launched keys' are +preset in the ltxkeys package. + +AUTHOR + +Ahmed Musa (amusa22@gmail.com) + +RELATED PACKAGES + +xkeyval.sty + +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. + +VERSION + +Version 0.1.0, July 2011 + + diff --git a/Master/texmf-dist/doc/latex/ltxkeys/ltxkeys-guide.txt b/Master/texmf-dist/doc/latex/ltxkeys/ltxkeys-guide.txt new file mode 100644 index 00000000000..f6428e5d497 --- /dev/null +++ b/Master/texmf-dist/doc/latex/ltxkeys/ltxkeys-guide.txt @@ -0,0 +1,530 @@ +This is ltxkeys-guide.tex, a minimal guide to the ltxkeys package. + +Version 0.1.0, July 2011 + +Ahmed Musa (amusa22@gmail.com) + + +SUMMARY + +The ltxkeys package provides facilities for creating and managing keys in the sense of the keyval and xkeyval packages, but it is intended to be more robust and faster than these earlier packages. Its robustness emanates from, inter alia, its ability to preserve braces in key values throughout parsing. The need to preserve braces in key values emerges often in parsing keys. This is the case in, eg, the xwatermark package. The package is faster than the xkeyval package because it avoids character-wise parsing of key values (which is called 'selective sanitization' by the xkeyval package). + +Anyone familiar with the implementation of the xkeyval package would have noticed that the macro \XKV@srstate, which (in order to allow \setkeys to be re-entrant) pushes and pops the states of some important functions in the package, loops over all the functions both when pushing and popping. In the ltxkeys package, pushing and popping functions together involve only one loop. And, unlike in the xkeyval package, higher order functions are undefined as soon as they are no longer needed, to avoid clogging up the stack. + +In setting keys, the ltxkeys package loops over not only families, as in the xkeyval package, but also over key prefixes. The same strategy applies when the xkeyval package tries to establish if a key is defined or not. + +Note: While many aspects of the ltxkeys package are similar to those of the xkeyval package, there are important differences in several areas of syntax, semantics, and internal implementation. + +The ltxkeys package also provides additional facilities (beyond the xkeyval package) for defining and managing keys. Several types of keys (including ordinary keys, command keys, style keys, choice keys, boolean and biboolean keys) can be efficiently created and managed. + +In the ltxkeys package, the notion of 'presetting' keys differs from that of the xkeyval package. Only 'initialized' or 'launched' keys (see \autoref{sec:xxx})' are preset in the ltxkeys package. + +What is the origin of 'ltxkeys'? Well, I decided to write this package as I grabbled with some practical problems of key parsing while developing version 1.5.0 of the xwatermark package. The tasks proved more challenging than I had predicted and, despite its commendable facilities, I found the xkeyval package inadequate in some respects. As mentioned earlier, the functionalities of the ltxkeys can be employed for general key management in \latex beyond the xwatermark package. + + +NOTE + +This user manual doesn't describe the full range of features of the ltxkeys package. +I will produce a pdf version of this guide with suitable markups in the near future, especially if someone informs me that he/she is using, or intends to use, this package. This sounds unconventional but there is no point in spending precious time now preparing a documentation that no one has a need for or is unlikely to be needed. The reason why I am releasing this documentation now is that users of the xwatermark package need an update immediately, to address some shortcomings of the current public version. But the new version of the xwatermark package relies on the ltxkeys package. + + +DEFINING KEYS + + In the following, quantities in square brackets --- eg '[yyy]' --- and those in parenthesis --- eg (yyy) --- are optional. + +1. Ordinary keys: + + \ltxkeys@ordkey[<pref>]{<fam>}{<key>}[<default>]{<callback>} + + This defines a macro of the form \<pref>@<fam>@<key> of one argument that holds the key function <callback>. The default value for <pref> is always KV, as in the xkeyval package. When <key> is used in a \ltxkeys@setkeys command (see \autoref{sec:}) containing key=value, the macro \<pref>@<fam>@<key> takes the value as its argument and is then executed. The given argument or key value can be accessed in <callback> by using #1 inside the function. The optional <default>, if available, will be used by \<pref>@<fam>@<key> when the user hasn't provided a value for the key at \ltxkeys@setkeys. If <default> was absent at key definition and the key user hasn't provided a value for the key, an error message will be flagged. + + +2. Command keys: + + \ltxkeys@cmdkey[<pref>]{<fam>}[<mp>]{<key>}[<default>]{<callback>} + + The optional <mp> is called the 'macro prefix' (in the parlance of the xkeyval package). If <mp> is given, the command \<mp><key> will hold the current user input; otherwise (if <mp> is absent) the user input will be available in \cmd<pref>@<fam>@key. The command \<pref>@<fam>@key, called the \quoted{key macro} by the xkeyval package, will hold the <callback>. + + +3. Style keys (keys with dependant keys): + + \ltxkeys@stylekey[<pref>]{<fam>}[<mp>]{<key>}[<default>](<dependants>){<callback>} + + \ltxkeys@stylekey*[<pref>]{<fam>}[<mp>]{<key>}[<default>](<dependants>){<callback>} + + The <dependants> have the syntax: + + {<keytype>/<keyname>/<default>/<callback>; another set of dependant; etc} + + <default> and <callback> can be absent. <keytype> can be 'ord' (ordinary key), 'cmd' (command key), 'bool' (boolean key), or 'choice' (choice key). + + Dependants keys always share the same key prefix <pref>, family <fam>, and macro prefix <mp> with the parent key. + + If <mp> is given, the command \<mp><key> will hold the current user input for the parent key; otherwise the user input will be available in \style<pref>@<fam>@key. The command \<pref>@<fam>@key will always hold the <callback>. + + If the *-form is used, all undefined dependants will be defined and set on the fly as the parent is being set. If the *-form isn't used and undefined dependants occur, then an error message will be flagged at the time the parent is being set. + + At most times it is possible to access the parent key's current value with \parentval. Within <default> and <callback> of <dependants>, it is possible to refer to the parent key's callback with its full macro name (ie, \<pref>@<fam>@<key>). \parentval is always available for use as the default value of dependant keys, but it may be lost in the callbacks of dependant keys, because a dependant key, once defined, may be set independent of, and long after, the parent key has been executed. It is therefore more reliable to refer to the macro \<pref>@<fam>@<key>@value, which is recorded for only the parent key of style keys and which holds the current user input for the parent key. The macro \<pref>@<fam>@<key>@value is recorded only if it appears at least once in the attributes of dependant keys. The macro \<pref>@<fam>@<key>@value has a more unique name than \<mp>@<key> but they always contain the same value of a style key. As mentioned above, if <mp> is not given, the user input for a style key will be available in the macro \style<pref>@<fam>@key, instead of \<mp>@<key>. + + Note: '#1' in the callback of parent key refers to the current value of the parent key, while '#1' in the callback of any dependant key refers to the current value of that dependant key. + + Example (define and set all undefined dependants on the fly): + + \ltxkeys@stylekey*[KV]{fam}[mp@]{keya}[{left}](% + % '#1' here refers to the value of the DEPENDANT key + % at the time it is being set. Use \parentkey and \parentval + % here to access the parent key name and its current value: + ord/keyb/{right}/\def\y##1{#1##1}; + % The default of keyc is the current value of parent (keya): + cmd/keyc/\parentval; + % Because \KV@fam@keya@value appears below, it will be saved + % when the parent key (keya) is being set, otherwise it would be + % unavailable: + bool/keyd/true/\ifmp@keyd\edef\x##1{##1\KV@fam@keya@value}\fi + ){ + % '#1' here refers to the value of the PARENT key + % at the time it is being set: + \def\x##1{##1xx#1xx}% + % Check the value of parent key: + \ltxkeys@checkchoice[\val\nr]{#1}{left,right,center}% + } + + \ltxkeys@setkeys[KV]{fam}{keya={right}} + + The braces in the values are just to exemplify the fact that braces in key values are preserved throughout key parsing. This is essential in, for example, the xwatermark package. + + +4.1 Boolean keys: + + \ltxkeys@boolkey[<pref>]{<fam>}[<mp>]{<key>}[<default>]{<callback>} + + \ltxkeys@boolkey+[<pref>]{<fam>}[<mp>]{<key>}[<default>]{<callback>}{<fn>} + + If <mp> is given, the command \<mp><key> will hold the current user input for the key at key setting time; otherwise the user input will be available in \bool<pref>@<fam>@key\footnote{This differs from the system in the xkeyval package.}. If <mp> is specified, a boolean of the form \if<mp><key> will be created at key definition, which will be set by \ltxkeys@setkeys according to the user input. If <mp> is not specified, a boolean of the form \ifbool<pref>@<fam>@key will instead be created. + + The user input for boolean keys must be in the set {true | false}. The command \<pref>@<fam>@key will always hold the <callback>, which will be executed if the user input is valid. + + The +-form of \ltxkeys@boolkey will execute <fn> in place of <callback> if the user input isn't in {true | false}; the plain form will issue an error in this case. + + +4.2 Biboolean keys: + + \ltxkeys@biboolkeys[<pref>]{<fam>}[<mp>]{<bool1>,<bool2>} + [<default>]{<callback1>}{<callback2>} + + \ltxkeys@biboolkeys+[<pref>]{<fam>}[<mp>]{<bool1>,<bool2>} + [<default>]{<callback1>}{<callback2>}{<fn>} + + Biboolean keys always assume opposite states: when one is true, the other is automatically toggled to false; and vice versa. Think of the options 'draft' and 'final' in a document class. Note: this is currently not the case with traditional document classes. + + <callback1> belongs to the boolean key <bool1>, while <callback2> belongs to <bool2>. + + The +-form of \ltxkeys@biboolkeys will execute <fn> in place of <callback1> or <callback2> if the input is not in {true | false}; the plain form will issue an error in this case. + + Biboolean keys have equal symmetry (ie, they can call each other with equal propensity) and they won't bomb out in an infinite reentrance. They normally would know if they're calling each other. + + Example: + + \ltxkeys@biboolkeys+[KV]{fam}[mp@]{keya,keyb}[true]{% + \ifmp@keya\def\x##1{##1x#1x##1}\fi + }{% + \ifmp@keyb\def\y##1{##1y#1y##1}\fi + }{% + \@latex@error{Invalid value '\string#1' for keya or keyb}\@ehc + } + + +5. Choice keys (with macro prefix, unlike in xkeyval package): + + \ltxkeys@choicekey[<pref]{<fam>}[<mp>]{<key>}[<bin>]{<alt>}[<default>]{<callback>} + + \ltxkeys@choicekey*+[<pref]{<fam>}[<mp>]{<key>}[<bin>]{<alt>}[<default>]{<callback>}{<fn>} + + If <mp> is absent, then \ltxkeys@choicekey uses \chc<pref>@<family>@<key> to hold the user input. + + <alt> is the list of nominations for the key value, ie, admissible values of the key. When <alt> has no /.code in it, it has the familiar syntax: + + {choice1, choice2, etc} + + while if it has /.code in it, it has the syntax: + + {choice1/.code=callback1; choice2/.code=callback2; etc} + + It is possible to refer to the current value of <key> as '#1' in <alt>. + + The *-form will convert the user input to lowercase before checking <alt> and executing the callbacks. + + The +-form will execute <fn> in place of <callback> if the user input isn't in <alt>. + + <bin> has, eg, the syntax [\val\nr], where \val will hold the user input (in lowercase if the *-form of \ltxkeys@choicekey is called), and \nr will hold the serial number of the value in the list of nominations <alt>, starting from 0. If the input isn't valid, \val will still hold the user input, but \nr will be -1. + + Example (defining choice key): + + \ltxkeys@choicekey*+[KV]{fam}[mp@]{keya}[\val\nr]{% + % There are no callbacks for these simple nominations: + center,right,left,justified + }[center]{% <- default value + \def\x##1##2{==##1++#1++##2==}% + }{% + \@latex@error{Inadmissible value '\string#1' for keya}\@ehc + } + + \ltxkeys@choicekey*+[KV]{fam}[mp@]{keyb}[\val\nr]{% + % There are callbacks for these nominations: + center/.code=\def\x##1{*##1*#1*##1}; + right/.code=\edef\z{\expandcsonce\ltxkeys@tval}; + left/.code=\edef\userinput{\cpttrimspaces{#1}}; + justified/.code=\letcsntocs{#1@align}\relax + }[center]{% + \def\x##1##2{==##1++#1++##2==}% + }{% + \@latex@error{Inadmissible value '\string#1' for keya}\@ehc + } + + +6. Defining boolean and command keys with one command: + + More than one boolean and command keys can be defined simultaneously by the following command: + + \ltxkeys@definekeys[pref]<fam>[macro-pref]{% + <key>=<default>/<callback>; another set of key; etc + } + + \ltxkeys@definekeys*[pref]<fam>[macro-pref]{% + <key>=<default>/<callback>; another set of key; etc + } + + <default> can be absent in the case of command keys, and <callback> can be absent for the two types of key. Boolean keys must, however, have default values {true | false}, to be distinguishable from command keys. + + You can use \CheckInput in <callback> to introduce choice keys as command keys (see example below). + + Ordinary keys and conventional choice keys can't be introduced directly by this command (use \ltxkeys@declarekeys instead). + + The *-form can be used to define new keys (in the sense of \newcommand). + + Note: Keys defined by \ltxkeys@definekeys are automatically set instantly, to provide default values for immediate use. Boolean keys are set with 'false', so that they aren't turned 'true' prematurely. + + In \ltxkeys@definekeys and \ltxkeys@declarekeys every line is assumed to end with a comment sign. + + Example (*-form -> new keys): + + \ltxkeys@definekeys*[KV]<fam>[mp@]{% + % command key with callback: + keya={keepbraced}/\def\x##1{##1*#1*##1}; + % boolean key: + keyb=true/\def\y##1{##1yyy#1}; + % command key with no callback: + keyc=xxx; + % choice-like key: + keyd=center/\CheckInput{#1}{left,right,center} + \ifinputvalid + \edef\myval{\expandcsonce\userinput} + \edef\numberinlist{\number\nr} + \else + \@latex@error{Input '#1' not valued}\@ehd + \fi; + } + + +7. Defining all types of key with one command: + + \ltxkeys@declarekeys[pref]<fam>[macro-pref]{% + <keytype>/<keyname>/<default>/<callback>; another set of key; etc + } + \ltxkeys@declarekeys*[pref]<fam>[macro-pref]{% + <keytype>/<keyname>/<default>/<callback>; another set of key; etc + } + + Here, <default> and <callback> can be absent in all cases. + + <keytype> may be any one of + + <ord> | <cmd> | <sty> | <sty*> | <bool> | <choice> + + The star (*) in <sty*> has the same meaning as in \ltxkeys@stylekey above. + + Choice keys must have their names associated with their admissible <alt> values in the format <keyname.{<alt>}> (see example below). + + The *-form can be used to define new keys (in the sense of \newcommand). + + Note: Keys defined by \ltxkeys@declarekeys are automatically set instantly, to provide default values for immediate use. Boolean keys are always initialized in this sense with 'false', so that they aren't turned 'true' prematurely. + + Example: + + \ltxkeys@declarekeys*[KV]<fam>[mp@]{% + cmd/keya/mm/\def\x##1{##1*#1*##1}; + bool/keyb; + sty/keyc/xxx/\def\y##1{##1yyy#1}; + sty*/keyd/blue/\def\y##1{##1#1}/ + cmd>keye>\parentval>\def\z####1{####1+##1+####1}; + choice/keyf.{left,right,center}/ + \ifcase\nr\def\shoot{0}\or\def\shoot{1}\or\def\shoot{2}\fi; + } + + Notice the >...> used for the dependant key ('keye') attributes of style key 'keyd'. The default value of the dependant key keye will in this example be whatever is submitted for keyd. + + +6. Need-value keys: + + Sometimes you may want to create keys for which the user must always supply his/her own values, even if the keys originally have default values. The default values of keys may not always be suitable. Take, for example, the height and width of a graphics image. For functions that are meant to handle generic images, it would certainly be inappropriate to relieve the user of the need to call picture height and width without corresponding values. + + To make a key a need-value key, simply attach the pointer \needvalue to the key at definition time. This pointer can be used only when defining keys, and not when setting keys. + + Example: + + \ltxkeys@cmdkey[KV]{fam}[mp@]{\needvalue{keya}}[blue]{% + \def\x##1{##1x#1x##1}% + } + \ltxkeys@setkeys[KV]{fam}{keya} + % -> Error: the author of 'keya' designed it to require a user value needed + + See more about key pointers in Section \autoref{sec:xxx}. + + +SETTING KEYS + + Keys can be set by the following utilities: + +1. Set defined keys: + + \ltxkeys@setkeys[<pref>]{<fam>}[<na>]{<key-val>} + \ltxkeys@setkeys*+[<prefs>]{<fams>}[<na>]{<key-val>} + + Keys in <na> are ignored. The *-form will save all undefined keys with prefix <pref> and in family <fam> in \<pref>@<fam>@rmkeys, to be set later, perhaps with \ltxkeys@setrmkeys. The +-form will search in all the prefixes in <prefs> and all families in <fams> for a key before logging the key in \<pref>@<fam>@rmkeys (if the *+-form is used) or reporting it as undefined. + + +2. Set 'remaining' keys after defined keys have been set: + + The command \ltxkeys@setrmkeys, which has both star (*) and plus (+) variants is the counterpart of \setrmkeys of the xkeyval package: + + \ltxkeys@setkeys[<pref>]{<fam>}[<na>] + \ltxkeys@setkeys*+[<prefs>]{<fams>}[<na>] + + +3. Set a 'main' (master) key from its 'alias' (slave): + + Aliased/alias keys differ from style keys. Two keys may be aliased to each other, such that when one is set, the alias is automatically set with the same or a different value. The concept is similar to, but not identical with, that of style keys. The two aliases must all be in the same family and have the same key and macro prefixes. + + \ltxkeys@setmnkey{<key>}[<value>] + + Here, <value> is optional; if it is not given, <key> will be set with the current value of its alias. The commands \setmnkey and \setaliaskey are a shortened variants of \ltxkeys@setmnkey. + + Example: + + \ltxkeys@definekeys*[KV]<fam>[mp@]{% + printsign=true; + printmark=true/\ltxkeys@setmnkey{printsign}[false]; + keya=$+++$; + keyb=star/\ltxkeys@setmnkey{keya}[$***$] + } + \ltxkeys@definekeys*[KV]<fam>[mp@]{% + keya=sun/\CheckInput{#1}{star,sun,moon} + \ifinputvalid + \edef\givenval{\userinput} + \edef\found{\ifcase\nr star@\or sun@\or moon@\fi} + \else + \@latex@error{Input '#1' not valid}\@ehd + \fi; + keyb=star/\ltxkeys@setmnkey{keya}; + } + + The macro \userinput is the value given by the user at the time of calling/using the key, always converted internally to lower case; and \nr is the serial number of the user input in the nominations, starting from 0. 'inputvalid' is an internal boolean, available to the user. + + The example of 'printsign' and 'printmark' is similar, but not equivalent, to the notion of biboolean keys. Biboolean keys have equal symmetry (ie, they can call each other with equal + propensity) and they won't bomb out in an infinite reentrance. This is not the case with aliased keys: only slave/alias can set or call master/main key. If they both call each other, the user will be alerted to the fact that there is an infinite reentrance of keys. The notion of 'slave' and 'master' used in the ltxkeys package may be counterintuitive but in reality it is quite logical. + + +4. Using key pointers: + + The \savevalue and \usevalue pointers of the xkeyval package are still available at key setting time, but with increased robustness and optimization. Curly braces in values are preserved throughout, and instead of saving the value of each key tagged with \savevalue in a separate macro, we save all such keys and their values in only one macro (for each combination of <pref> and <fam>) and use a fast search technique to find the values when they are needed later (by any key tagged with \usevalue). + + Here is an interesting example (and test) of use of pointers: + + \ltxkeys@stylekey*[KV]{fam}{\needvalue{keya}}[{left}](% + % #1 here refers to the value of the dependant key + % at the time it is being set. + ord/\needvalue{keyb}/\parentval/\edef\y##1{##1xx\unexpanded{#1}}; + cmd/keyc/{center} + ){% + % #1 here refers to the value of the parent key + % at the time it is being set: + \def\x##1{##1xx#1} + } + \ltxkeys@setkeys[KV]{fam}{\savevalue{keya}={\def\y##1{##1}}, + \savevalue{keyb}=\usevalue{keya},keyc=\usevalue{keyb}} + + +5. Accessing the saved value of a key: + + As mentioned earlier, the pointers \savevalue and \usevalue are available only within \ltxkeys@setkeys. But suppose you have used \savevalue within \ltxkeys@setkeys to set the value of a key, how do you access that value outside of \ltxkeys@setkeys? You can do this by using the following \ltxkeys@storevalue command: + + \ltxkeys@storevalue[<pref>]{<fam>}{<key>}<cs> + \ltxkeys@storevalue+[<pref>]{<fam>}{<key>}<cs><fallback> + + Here, <cs> is the macro (defined or undefined) that will receive the saved value of <key>. The plain variant of this command will raise an error message if the value of the key wasn't previously saved, while the +-form will resort to the user-supplied function <fallback>. Only saved key values can be recovered by this command. + + Examples: + + \ltxkeys@cmdkey[KV]{fam}{\needvalue{keya}}[{left}]{% + \def\x##1{##1xx#1} + } + \ltxkeys@setkeys[KV]{fam}{\savevalue{keya}={\def\y##1{##1}}} + \ltxkeys@storevalue[KV]{fam}{keya}\tempa + \ltxkeys@storevalue+[KV]{fam}{keya}\tempb{% + \@latex@error{No value saved for key 'keya'}\@ehc + } + + + +INITIALIZING KEYS + + \ltxkeys@initializekeys[<prefs>]{<fams>}[<na>] + + This presets ALL keys previously defined in families <fams> with their default values; it ignores keys listed in <na>. If <na> is a list of key-value pairs, the key names are extracted from the list before the family keys are initialized. Any key-value pairs in <na> are not set at all. All keys defined by \ltxkeys@definekeys and \ltxkeys@declarekeys are automatically instantly initialized, except slave/alias and dependant keys. + + The command \ltxkeys@initializekeys can be used to save estate when listing keys in \ltxkeys@executeoptions. + + +LAUNCHING KEYS + + \ltxkeys@launchkeys[<pref>]{<fam>}[<curr>] + + This presets ALL keys defined in family <fam> with their default values; it ignores keys listed in <curr>. <curr> is actually the list of key-value pairs that the user wants to use as current values of keys. Their keys are to be ignored when setting up defaults, ie, when initializing the family keys. One major difference between \ltxkeys@launchkeys and \ltxkeys@initializekeys is that in \ltxkeys@launchkeys the key-value pairs in <curr> are immediately set after the family keys are initialized. + + Note: Keys with multiple prefixes and from multiple families can't be launched at the same time. + + +HANDLING UNDEFINED OR UNKNOWN KEYS + + You can use the macro \ltxkeys@unknownkeyhandler declare to the ltxkeys package the course of action to take if, while setting keys, it discovers that a key is undefined or unknown. The syntax of this command is + + \ltxkeys@unknownkeyhandler[<prefs>]{<fams>}{<callback>} + + where <callback> signifies the action to take. The default <callback> is to log the keys and warn the user, in each run, of the presence of unknown keys. The same <callback> can be used across key prefixes <prefs> and families <fams>. You can use #1 (or \CurrentPref) in this macro to represent the current key prefix, #2 (or \CurrentFam) for the current family, #3 (or \CurrentKey) for the current key name, and #4 (or \CurrentVal) for the value of the current key. If \CurrentVal contains undefined macros or active characters, then attempting to print it may cause problems. Therefore, when making entries in the transcript file, it will sometimes be preferable to use \InnocentVal instead of \CurrentVal. However, \InnocentVal will give only the first eight characters of a key's value. + + Example: + + \ltxkeys@unknownkeyhandler[KVA,KVB]{fam1,fam2}{% + \@expandtwoargs\in@{,#3,}{,\myspecialkeylist,}% + \ifin@ + % The reader may want to investigate what the parameter + % characters ##1 and ####1 here stand for: + \ltxkeys@ordkey[#1]{#2}{#3}[#4]{\def\x####1{####1xx##1}}% + \else + \@ltx@warn{Unknown key `#3' with value `#4' in family `#2' ignored}\@ehd + % \@ltx@warn{Unknown key `\CurrentKey' with value + % `\InnocentVal' in family `\CurrentFam' ignored}\@ehd + \fi + } + + The macro \myspecialkeylist in the above example doesn't actually exist; it is only meant for illustration here. But 'handled keys' may be introduced in this way. This will be the set of keys for which a special action may apply at key setting time. + + Similar to \ltxkeys@unknownkeyhandler (which applies to keys), there is also the \ltxkeys@unknownoptionhandler (which applies to package or class options---see \autoref{sec:}). + + +CHECKING IF A KEY IS DEFINED + + \ltxkeys@ifkeydefTF[<prefs>]{<fams>}{<key>}{<true>}{<false>} + \ltxkeys@ifkeydefFT[<prefs>]{<fams>}{<key>}{<false>}{<true>} + + These check if <key> is defined with a prefix in <prefs> and in family in <fams>. + + + +DISABLING KEYS + + \ltxkeys@disablekeys[<prefs>]{<fams>}{<keys>} + \ltxkeys@disablekeys*[<prefs>]{<fams>}{<keys>} + + The command \ltxkeys@disablekeys causes an error to be issued when a disabled key is invoked. If the package option 'verbose' is true, undefined keys are highlighted by \ltxkeys@disablekeys with a warning message. Because it is possible to mix prefixes and families in \ltxkeys@disablekeys, undefined keys may be readily encountered. To see those undefined keys, enable the package option 'verbose'. + + The plain form of \ltxkeys@disablekeys disables the given keys instantly, while the starred (*) variant disables the keys at \AtBeginDocument. Authors can use this command to bar users of their keys from calling those keys after a certain point. + + +OPTION AND NON-OPTION KEYS + + Sometimes you want to create keys that can only appear in \documentclass, \RequirePackage or \usepackage, and at other times you may not want the user to submit a certain set of keys via these commands. The xwatermark package, for example, uses this concept. + + \option@keys[<pref>]{<fam>}{<keys>} + \option@keys*[<pref>]{<fam>}{<keys>} + \notoption@keys[<pref>]{<fam>}{<keys>} + + Keys listed in \option@keys can appear only in arguments of \documentclass, \RequirePackage or \usepackage, while keys list in \notoption@keys can't appear in these macros. The *-form of \option@keys is equivalent to \notoption@keys. Only defined keys may appear in \option@keys and \notoption@keys. + + \makeoption@keys[<pref>]{<fam>} + \makeoption@keys*[<pref>]{<fam>} + + The command \makeoption@keys makes all the keys with prefix <pref> and in family <fam> options keys. The *-form of \makeoption@keys is equivalent to \makenotoption@keys. + + +DECLARING AND PROCESSING OPTIONS + + \ltxkeys@declareoption[<pref>]<<fam>>{<key>}[<default>]{<callback>} + \ltxkeys@declareoption*[<pref>]<<fam>>{<key>}[<default>]{<callback>} + + The command \ltxkeys@declareoption is simply a form of \ltxkeys@ordkey, with the difference that the key family <fam> is now optional and, when specified, must be given in angled brackets. The default family name is '\@currname.\@currext', ie, the name of the class file or package and its file extension. + + The starred (*) form of \ltxkeys@declareoption prescribes the default action to be taken when undefined options with prefix <pref> and in family <fam> are passed to class or package. You may use \CurrentKey and \CurrentVal within this macro to pass the unknown option and its value to another class or package or to specify other actions. In fact, you can use #1 in this macro to represent the current key prefix, #2 for the current family, #3 for the current key name, and #4 for the value of the current key. The command \ltxkeys@unknownoptionhandler is equivalent to the *-form of \ltxkeys@declareoption. + + Note: The *-form of \ltxkeys@declareoption differs from the *-form of LaTeX's \DeclareOption and the *-form of xkeyval package's \DeclareOptionX. + + +++ + Examples (of use of *-form of \ltxkeys@declareoption): + + \ltxkeys@declareoption*[KV]<mypackage>{% + \PackageWarning{mypackage}{% + Unknown option `\CurrentKey' with value `\CurrentVal' ignored}% + } + + \ltxkeys@declareoption*{\PassOptionsToClass{#3}{article}} + + \ltxkeys@unknownoptionhandler[KV]<mypackage>{% + % The macro \myextraoptions doesn't actually exist; + % it is only meant for illustration here: + \@expandtwoargs\in@{,#3,}{,\myextraoptions,}% + \ifin@ + % The reader may want to investigate what the parameter characters + % ##1 and ####1 here stand for: + \ltxkeys@ordkey[#1]{#2}{#3}[#4]{\def\x####1{####1xx##1}}% + \else + \PassOptionsToClass{#3}{myclass}% + \fi + } + +++ + + \ltxkeys@declarecmdoption[<pref>]<<fam>>[<mp>]{<key>}[<default>]{<callback>} + \ltxkeys@declarebooloption[<pref>]<<fam>>[<mp>]{<key>}[<default>]{<callback>} + \ltxkeys@declarechoiceoption[<pref>]<<fam>>[<mp>]{<key>}[<default>]{<callback>} + + These are equivalent to \ltxkeys@cmdkey, \ltxkeys@boolkey and \ltxkeys@choicekey, respectively, but now the family <fam> is optional and, when specified, must be given in angled brackets. The default family name is '\@currname.\@currext'. + + + \ltxkeys@executeoptions[<pref>]<<fams>>[<na>]{<key-val>} + + This executes/sets the key-value pairs given in <key-val>. The optional <na> specifies the list of keys (without values) to be ignored. <fams> signifies families in which the keys suggested in <key-val> have been defined. The command \ltxkeys@executeoptions can thus be used to process keys from several families. + + + \ltxkeys@processoptions[<pref>]<<fams>>[<na>] + \ltxkeys@processoptions*[<pref>]<<fams>>[<na>] + + The command \ltxkeys@processoptions processes the keys and values passed by the user to the class or package. The optional argument <na> can be used to specify keys that should be ignored. The optional argument <fams> can be used to specify the families that have been used to define the keys. This macro doesn't protect expandable macros in the user inputs unless the catoptions package is loaded before \documentclass, in which case it might be better using the command \XProcessOptions of the catoptions package. When used in a class file, the macro \ltxkeys@processoptions will ignore unknown keys or options. This allows the user to use global options in the \documentclass command which can be inherinted by packages loaded afterwards. + + The starred (*) version \ltxkeys@processoptions works like the plain variant except that it also copies user input from the \documentclass command. When the user specifies an option in the \documentclass which also exists in the local family or families of the package issuing \ltxkeys@processoptions*, the local key too will be set. In this case, #1 in the \ltxkeys@declareoption (or a similar command) will be the value entered in the \documentclass command for this key. First the global options from \documentclass will set local keys and afterwards the local options, specified with \usepackage, \RequirePackage or \LoadClass, will set local keys, which could overwrite the global options, depending on the way the options sections are constructed. + +NOTES + + Wherever semicolon ';' is indicated as a list parser in this guide, it can be replaced by any user-specified one character parser via the package option 'keyparser'. It is advisable to enclose the chosen character in curly braces, eg, as in + + \documentclass[verbose,keyparser={|}]{article} + + or + + \usepackage[keyparser={|}]{ltxkeys} + + +TO-DO + + Patching the callback of an existing key. Sometimes you might want to modify the callback of a key defined in another style file. Rather than redefine the key with another callback, it may be possible to simply patch the callback of the key, provided the key's callback is patchable. This facility has been delayed because I am still experimenting the scannability of callbacks with doubled hash character. + + +% End of ltxkeys-guide.tex %
\ No newline at end of file |