diff options
author | Karl Berry <karl@freefriends.org> | 2010-05-25 23:24:12 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2010-05-25 23:24:12 +0000 |
commit | 4f3e4613ddeb2c1d348b92e964efe670915184c8 (patch) | |
tree | 0a13254141e5b110e0f2135730fd054e67e8adff /Master/texmf-dist/doc | |
parent | 30ffebfa9605d5de08c5f6158caa022ac3a8cb4a (diff) |
skeyval update (25may10)
git-svn-id: svn://tug.org/texlive/trunk@18494 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc')
-rw-r--r-- | Master/texmf-dist/doc/latex/skeyval/README | 2 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/skeyval/skeyval-bugreport.tex | 41 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/skeyval/skeyval-guide.pdf | bin | 600300 -> 609972 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/latex/skeyval/skeyval-guide.tex | 244 |
4 files changed, 136 insertions, 151 deletions
diff --git a/Master/texmf-dist/doc/latex/skeyval/README b/Master/texmf-dist/doc/latex/skeyval/README index 0b495132f3d..5dc7d3eae36 100644 --- a/Master/texmf-dist/doc/latex/skeyval/README +++ b/Master/texmf-dist/doc/latex/skeyval/README @@ -1,6 +1,6 @@ %+++++++++++++++++++++++++++++++++++ INTRODUCTION +++++++++++++++++++++++++++++++++++% % % -% This is the Readme file for the skeyval package, version 0.71. % +% This is the Readme file for the skeyval package, version 0.72. % % May 2010 % % % % Copyright (c) 2010 Ahmed Musa (a.musa@rocketmail.com). % diff --git a/Master/texmf-dist/doc/latex/skeyval/skeyval-bugreport.tex b/Master/texmf-dist/doc/latex/skeyval/skeyval-bugreport.tex deleted file mode 100644 index 14256941ea2..00000000000 --- a/Master/texmf-dist/doc/latex/skeyval/skeyval-bugreport.tex +++ /dev/null @@ -1,41 +0,0 @@ -%+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++% -% This is file skeyval-bugreport.tex, the bug report file for the % -% skeyval package, version 0.7. % -% % -% (c) Ahmed Musa 2010 (a.musa@rocketmail.com) % -%+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++% -% % -% IMPORTANT % -% % -% Please fill in the details below, compile the file and email % -% the sample file, the log file, and the auxiliary file to % -% a.musa@rocketmail.com. % -% % -% You can use \traceon ... \traceoff to limit the scope of % -% error tracing. This will be particularly helpful as TeX normally % -% generates very large trace files. % -% % -% % -%+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++% - -\documentclass{article} -\listfiles - -% Load your select packages here (the ones that you suspect are -% associated with your errors), but if bugs exist in those packages, -% I am afraid, I can't do much about them. - -\usepackage[logonly]{trace} % Please don't move! -\traceon - -\usepackage[Put your skeyval options here, if any]{skeyval} - -% Provide other elements of your preamble here: - -\begin{document} -% Provide sample text and problematic segment of your file here, if any: - - -\end{document} - -%\traceoff diff --git a/Master/texmf-dist/doc/latex/skeyval/skeyval-guide.pdf b/Master/texmf-dist/doc/latex/skeyval/skeyval-guide.pdf Binary files differindex a82980a58eb..b13fd223a11 100644 --- a/Master/texmf-dist/doc/latex/skeyval/skeyval-guide.pdf +++ b/Master/texmf-dist/doc/latex/skeyval/skeyval-guide.pdf diff --git a/Master/texmf-dist/doc/latex/skeyval/skeyval-guide.tex b/Master/texmf-dist/doc/latex/skeyval/skeyval-guide.tex index 17345d18950..075ebfb5766 100644 --- a/Master/texmf-dist/doc/latex/skeyval/skeyval-guide.tex +++ b/Master/texmf-dist/doc/latex/skeyval/skeyval-guide.tex @@ -14,7 +14,7 @@ version~0.5. The \asty{keyreader} is now obsolete and no longer supported.} }{% \titlenote[t2]{The package is available at \url{\@shorttitleurl}.}% } -\subtitle{Version 0.71} +\subtitle{Version 0.72} \titleurl{http://www.ctan.org/tex-archive/macros/latex/contrib/skeyval/} \shorttitleurl{http://www.ctan.org/} \author{Ahmed Musa\Email{a.musa@rocketmail.com}\\Preston, Lancashire, UK} @@ -26,7 +26,7 @@ version~0.5. The \asty{keyreader} is now obsolete and no longer supported.} framecolor=brown]{% \frameshade[fillcolor=white,width=2.5cm,framecolor=red,framerule=2pt]% {\centering\abstname}\small - This package supplements the \pkgm{xkeyval}. It introduces toggle keys and complementary (bipolar and unipolar) native-boolean and toggle-boolean keys. It also provides mechanisms for reserving, unreserving, suspending, restoring, and removing keys. Furthermore, it introduces a set of commands for key definition which bar the developer or user from inadvertently redefining existing keys of the same family and prefix. Commands are provided for checking the statuses of keys across multiple key prefixes and families. Also, the package provides a scheme for defining multiple keys of different genres using only one command, thereby making it possible to considerably economize on tokens when defining keys. The package introduces the notion of ``user-value keys'' and provides facilities for managing those keys. The pointer mechanisms of the \asty{xkeyval}, which were only available at key setting time, are now invocable at key definition. Some other general-purpose developer macros and hooks are provided by the package. + This package provides several extensions to the \pkgm{xkeyval}. It introduces toggle keys and complementary (bipolar and unipolar) native-boolean and toggle-boolean keys. It also provides mechanisms for reserving, unreserving, suspending, restoring, and removing keys. Furthermore, it introduces a set of commands for key definition which bar the developer or user from inadvertently redefining existing keys of the same family and prefix. Commands are provided for checking the statuses of keys across multiple key prefixes and families. Also, the package provides a scheme for defining multiple keys of different genres using only one command, thereby making it possible to considerably economize on tokens when defining keys. The package introduces the notion of ``user-value keys'' and provides facilities for managing those keys. The pointer mechanisms of the \asty{xkeyval}, which were only available at key setting time, are now invocable at key definition. Some other general-purpose developer macros and hooks are provided by the package. } \end{abstract} @@ -74,7 +74,7 @@ Secondly, the \pkg{xkeyval} can't be used to define and set complementary (bipol Complementary unipolar keys, on the other hand, are mutually inclusive, \ie, both are always in the same state of a two-valued logic: when one is switched to a particular state, the complement too is automatically toggled to the same state. An example of complementary unipolar keys would be the options \fx{hyperref} and \fx{microtype} in a package or class file. When \pkgm{hyperref} is loaded, we may want \pkgm{microtype} loaded as well, and vice versa. Complementary unipolar keys, like bipolar keys, also carry equal charge, \ie, one can toggle the other with equal propensity, but to the same state for the two keys. For a pair of unipolar keys, the primary key is the one that is associated with the default state. -The present package introduces these concepts of bipolar and unipolar keys and additionally permits the submission of individual/different custom key macros to complementary (bipolar and unipolar) native boolean and toggle keys. Biunipolar keys, which combines the two concepts of bipolar and unipolar keys, are introduced as well. +The present package introduces these concepts of bipolar and unipolar keys and additionally permits the submission of individual and different custom key macros to complementary (bipolar and unipolar) native boolean and toggle keys. Biunipolar keys, which combines the two concepts of bipolar and unipolar keys, are introduced as well. The third motivation for this package relates to economy of tokens in style files. The \pkg{xkeyval} provides \acmd{\define@cmdkeys} and \acmd{\define@boolkeys} for defining and setting multiple command keys and boolean keys, but in each category the keys must have the same default value and no key macro/function. This package seeks to lift these restrictions, so that multiple keys of all categories (ordinary keys, command keys, boolean keys, tog keys, and choice/menu keys) can be defined in one go (using only one command) and those keys can have different default values and functions. This greatly minimizes tokens, as hundreds of keys can, in principle, be issued simultaneously by one command. @@ -176,16 +176,18 @@ The second statement above reverses the boolean \ang{draft} to \ang{false}, whic \Note In the \pkg{skeyval}, the acceptable values for native-boolean and toggle-boolean keys are \fx{true}, \fx{on}, \fx{false}, and \fx{off}. Toggle-booleans (\cref{sec:toggle-booleans}) and switches (\cref{sec:switches}) also accept these values. The value \fx{on} is synonymous with \fx{true}, whilst \fx{off} is an alias for \fx{false}. Being merely aliases, both \fx{on} and \fx{off} don't increase the number of commands per switch: the number remains three. -The \pkg{skeyval} has the \acmdm{\NewIfs} macro which defines five commands per switch: +The \pkg{skeyval} has the \acmdm{\NewIfs} and \acmdm{\DefIfs} macros, both of which define five commands per switch: \begin{macro} \NewIfs[|vang(optional prefix)]{|vang(boolean list)}[|vang(optional state)] +\DefIfs[|vang(optional prefix)]{|vang(boolean list)}[|vang(optional state)] \end{macro} -\acmdm*{\NewIfs} -This provides, for each member of the comma-separated list \ang{boolean list}, a new native-boolean register if the register didn't already exist, otherwise an error is flagged. Each member of \ang{boolean list} is prefixed with \ang{prefix} upon definition. The optional \ang{state} can be either \fx{true}, \fx{false}, \fx{on} or \fx{off}; the default is \fx{false}. The state \fx{on} is synonymous with \fx{true}, whilst \fx{off} is equivalent to \fx{false}. After declaring +The command \fx{\NewIfs} provides, for each member of the comma-separated list \ang{boolean list}, a new native-boolean register if the register didn't already exist. If the boolean register already existed, an error is flagged. Each member of \ang{boolean list} is prefixed with \ang{prefix} upon definition. The command \fx{\DefIfs}, on the other hand, provides, for each member of the comma-separated list \ang{boolean list}, a new native-boolean register whether or not the register already existed. If the boolean register already existed, and the package option \fx{verbose} is enabled, a message is entered in the transcript log file that the boolean has been redefined. + +The optional \ang{state} can be either \fx{true}, \fx{false}, \fx{on} or \fx{off}; the default is \fx{false}. The state \fx{on} is synonymous with \fx{true}, whilst \fx{off} is equivalent to \fx{false}. After declaring \begin{example} \NewIfs[bool]{a,b}[true] \end{example} -you can say \fx{\ifboola}, \fx{\boolaon} and \fx{\boolaoff}, just like you would normally do \fx{\boolatrue} and \fx{\boolafalse}. The disadvantage of \fx{\NewIfs} is that it defines five commands per switch; it should therefore be employed only in special circumstances. +you can say \fx{\ifboola}, \fx{\boolaon} and \fx{\boolaoff}, just like you would normally do \fx{\boolatrue} and \fx{\boolafalse}. The disadvantage of \fx{\NewIfs} and \fx{\DefIfs} is that they define five commands per switch; they should therefore be employed only in special circumstances. \subsection{Unipolar native-boolean keys} @@ -299,11 +301,12 @@ This defines a new \ang{toggle}, prefixed with \ang{prefix} upon definition, whe \acmdm*{\newtog} This defines a new \ang{toggle}, prefixed with \ang{prefix} upon definition, if \ang{toggle} (with its prefix) is not already defined; otherwise the package issues a fatal error. The optional \ang{state} can be either \fx{true}, \fx{false}, \fx{on} or \fx{off}. -You can define a set of toggles by the following command: +You can define a set of toggles by the following commands: \begin{macro} -\NewTogs[|vang(optional prefix)]{|vang(toggles)}[|vang(optional state)], +\NewTogs[|vang(optional prefix)]{|vang(toggles)}[|vang(optional state)] +\DefTogs[|vang(optional prefix)]{|vang(toggles)}[|vang(optional state)] \end{macro} -\acmdm*{\NewTogs} +\acmdm*{\NewTogs,\DefTogs} where \ang{toggles} is a comma-separated list. Each member of \ang{toggles} is prefixed with \ang{prefix} upon definition. The optional \ang{state} can be either \fx{true}, \fx{false}, \fx{on} or \fx{off}. For example, we may define new toggles \fx{togx}, \fx{togy}, \fx{togz} by the following: \begin{example} \NewTogs[tog]{x,y,z}[true] @@ -722,7 +725,7 @@ The macro \fx{\mp@align} holds the value \fx{\flushright}, while \fx{\KV@fam@tes \def\mp@testdim{#1} \long\def\funcfortestdim##1{A test dimension ##1}, \end{example} -where \angledhash{1} is the value (3cm) submitted for the key \fx{testdim}. The number of parameter characters normally increases in the macro \fx{\define@keylist} (see \cref{sec:macros-in-keymacros}). After setting the keys, you can do \fx{\show\mp@align} and \fx{\show\KV@fam@testdim} to confirm the above assertions. +where \fx{#1} is the value (3cm) submitted for the key \fx{testdim}. The number of parameter characters normally increases in the macro \fx{\define@keylist} (see \cref{sec:macros-in-keymacros}). After setting the keys, you can do \fx{\show\mp@align} and \fx{\show\KV@fam@testdim} to confirm the above assertions. The rest of the defined keys can now be set as follows: \begin{example} @@ -749,6 +752,10 @@ Instead of using macros to pass key macros and functions, it is also possible to 4,toga,true,\the\temptoksb} \setkeys[KV]{fam}{boola=true,toga=true} + +|comm(You can now test your new function \do:) +\def\y{x} \def\z{xxx} +\do\x\x\y\z \end{example} \acmd*{\define@keylist} The advantage of using token list registers is that the parameter characters need not be doubled in the token list registers, unlike when using macros. The token list register \fx{\temptoksa} can be reused as soon as the key \fx{boola} has been set. See \cref{sec:condit-in-macros} for more information on using macros and token list registers to parse key functions. @@ -758,11 +765,14 @@ The advantage of using token list registers is that the parameter characters nee The examples in \cref{sec:multkeys-examples} would have provided some glimpse of the rules guiding the use of parameter characters in key macros. The general rules are as follows: \begin{enum} -\item When key macros are parsed through token list registers, the parameter characters shouldn't be doubled. -\item When key macros are parsed via intermediate macros, the parameter characters should be doubled but only once. -\item In all other cases (\ie, when using \fx{\define@keylist} and its starred variant) the parameter characters should be doubled twice. +\item When key macros are parsed through token list registers, the parameter characters shouldn't be doubled (\ie, use \cmdtext{\#1} for outermost parameters). +\item When key macros are parsed via intermediate macros, the parameter characters should be doubled but only once (\ie, use \cmdtext{\#\#1} for outermost parameters). +\item In all other cases (\ie, when using \fx{\define@keylist} or \acmd{\newkeylist} and their starred variants) the parameter characters should be doubled twice (\ie, use \cmdtext{\#\#\#\#1} for outermost parameters). +\item Within \fx{\define@keylist} and \fx{\newkeylist}, you can refer to the user-submitted key value by \cmdtext{\#\#1}. \end{enum} -\tex will flag a fatal error when any of these rules is breached. The following examples illustrate the use of these rules. The commands \fx{\skif}, \fx{\skifx}, \fx{\skelse} and \fx{\skfi} are described in \cref{sec:pseudo-primitives}. +\tex will flag a fatal error when any of these rules is breached. The need to double the parameter character arises from setting keys, not when defining keys. When absorbing their arguments, both \fx{\define@keylist} and \fx{\newkeylist} actually temporarily sanitize the parameter character. + +The following examples illustrate the use of these rules. The commands \fx{\skif}, \fx{\skifx}, \fx{\skelse} and \fx{\skfi} are described in \cref{sec:pseudo-primitives}. \begin{example} \define@keylist{% tog,toga,true,\iftogon{mp@toga}{% @@ -825,8 +835,10 @@ The examples in \cref{sec:multkeys-examples} would have provided some glimpse of \setkeys[KV]{fam}{keyda=xxx,keydb=yyy} |comm(The next one fails. Why?) -\define@keylist{ord,keye,unknown,\def\hold##1% - {\def##1####1{####1}}} +\define@keylist{% + ord,keye,unknown,\def\hold##1{\def##1####1{####1}}% +} +\setkeys[KV]{fam}{keye=yyy} \define@keylist{% ord,keyfa,xxx, @@ -1017,13 +1029,16 @@ The key \fx{focus} can now be readily set: \fx{\setkeys[KV]{fam}{focus=left}}. The approaches of \cref{sec:pseudo-primitives} provide a familiar \tex-like syntax for submitting conditionals to \fx{\define@keylist}. There is yet another approach that we developed. It is related to the native \tex boolean conditional. By \emph{switches} we mean the usual \tex's \fx{\iftrue} and \fx{\iffalse} booleans, but expressed in different syntax and semantics. -A new switch can be introduced by using the following command: +New switches can be introduced by using the following commands: \begin{macro} \newswitch[|vang(optional prefix)]{|vang(boolean)}[|vang(optional state)] +\defswitch[|vang(optional prefix)]{|vang(boolean)}[|vang(optional state)] \end{macro} -\acmdm*{\newswitch} -This provides a new native-boolean register \fx{\if}\unskip\ang{prefix}\unskip\ang{boolean} if the register didn't already exist; if the register already existed, an error is flagged. The optional \ang{state} can be either \fx{true} (or \fx{on}) or \fx{false} (or \fx{off}); the switch will be initialized to that state. With this definition, you can issue \fx{\if}\unskip\ang{switch}, \bs\ang{switch}\unskip\fx{true}, and \bs\ang{switch}\unskip\fx{false}. One advantage of \fx{\newswitch} is that a switch can start off as either \fx{true} (or \fx{on}) or \fx{false} (or \fx{off}), unlike the classical \tex's case in which all booleans start off as \fx{false}. Also, switches can be used where primitive \tex conditionals may prove impossible. For example, we know that you can't do \fx{\let\ifabc\iftrue} within the body of a conditional text without hiding the assignment from \tex's scanning mechanism. +\acmdm*{\newswitch,\defswitch} +The command \fx{\newswitch} provides a new native-boolean register of the form \fx{\if}\unskip\ang{prefix}\unskip\ang{boolean} if the register didn't already exist; if the register already existed, an error is flagged. The command \fx{\defswitch}, on the other hand, doesn't flag any error even if the switch register \ang{boolean} already existed. Instead it makes an entry (warning or information) in the transcript log file if the package option \fx{verbose} is selected. + +The optional \ang{state} can be either \fx{true} (or \fx{on}) or \fx{false} (or \fx{off}); the switch will be initialized to that state. With this definition, you can issue \fx{\if}\unskip\ang{switch}, \bs\ang{switch}\unskip\fx{true}, and \bs\ang{switch}\unskip\fx{false}. One advantage of \fx{\newswitch} is that a switch can start off as either \fx{true} (or \fx{on}) or \fx{false} (or \fx{off}), unlike the classical \tex's case in which all booleans start off as \fx{false}. Also, switches can be used where primitive \tex conditionals may prove impossible. For example, we know that you can't do \fx{\let\ifabc\iftrue} within the body of a conditional text without hiding the assignment from \tex's scanning mechanism. \begin{example} \newswitch{boola} |tto \newif\ifboola @@ -1035,22 +1050,24 @@ This provides a new native-boolean register \fx{\if}\unskip\ang{prefix}\unskip\a \newswitch[bool]{d}[off] |tto \newif\ifboold \booldfalse \end{example} -You can define many switches in a row by the following command: +You can define many switches in a row by the following commands: \begin{macro} \NewSwitches[|vang(optional prefix)]{|vang(switches)}[|vang(optional state)] +\DefSwitches[|vang(optional prefix)]{|vang(switches)}[|vang(optional state)] \end{macro} -\acmdm*{\NewSwitches} +\acmdm*{\NewSwitches,\DefSwitches} Each member of \ang{switches} is prefixed with \ang{prefix} upon definition. The optional \ang{state} can be either \fx{true} (or \fx{on}) or \fx{false} (or \fx{off}). Here are some examples: \begin{example} \NewSwitches{x,y,z}[off] - |tto \newswitch{x}{false} \newswitch{y}{false} - \newswitch{z}{false} + |tto \newswitch{x}[false] \newswitch{y}[false] + \newswitch{z}[false] -\NewSwitches[skv@]{u,w}[true] - |tto \newswitch{skv@u}{true} \newswitch{skv@w}{true} +\DefSwitches[skv@]{u,w}[true] + |tto \defswitch[skv@]{u}[true] \defswitch[skv@]{w}[true] + |tto \defswitch{skv@u}[true] \defswitch{skv@w}[true] \end{example} Switches may be set and tested using the following commands: @@ -1090,12 +1107,6 @@ Switches may be set and tested using the following commands: \ifswitchoff{y}{\def\yy{Off}}{\def\yy{On}} \end{example} -\begin{macro} -\defswitch[|vang(optional prefix)]{|vang(boolean)}[|vang(optional state)] -\end{macro} -\acmdm*{\defswitch} -This is similar to \fx{\newswitch} but raises no errors even if the register \ang{boolean} already exists. - Now how do we use switches in \fx{\define@keylist}? Suppose the key prefix is \fx{KV}, the key family is \fx{fam}, and the key macro is \fx{mp@}. Then the following works: \begin{example} \define@keylist{3,swa,true, @@ -1365,34 +1376,29 @@ Localized keys can be redefined with commands in the \textdefinekey category, bu The \pkg{xkeyval} bars its users from defining new keys with \fx{XKV} as a prefix. The \pkg{skeyval} generalizes this concept via the following three developer macros: \begin{macro} \ReserveKeyPrefixNames{|vang(list)} +\ReserveKeyPrefixNames|redstar{|vang(list)} \end{macro} -\acmdm*{\ReserveKeyPrefixNames} -This allows the package developer to bar the future use of names appearing in \ang{list} as key prefixes when defining, disabling, reserving and suspending keys; but not when setting keys. The \ang{list}, whose members are comma-separated, can be populated by the package developer as required. +\acmdm*{\ReserveKeyPrefixNames,\ReserveKeyPrefixNames*} +This allows the package developer to bar the future use of names appearing in \ang{list} as key prefixes when defining, disabling, reserving and suspending keys; but not when setting keys. The \ang{list}, whose members are comma-separated, can be populated by the package developer as required. The starred variant takes effect at the end of current package; the unstarred one assumes immediate effect. If the developer wants to use any member of \ang{list} in his own package, it may be necessary for him to use the starred version. \begin{macro} \ReserveMacroPrefixNames{|vang(list)} +\ReserveMacroPrefixNames|redstar{|vang(list)} \end{macro} -\acmdm*{\ReserveMacroPrefixNames} -This has a similar functionality to \fx{\ReserveKeyPrefixNames}, but applies to macro prefixes instead of key prefixes. +\acmdm*{\ReserveMacroPrefixNames,\ReserveMacroPrefixNames*} +This has a similar functionality to \fx{\ReserveKeyPrefixNames}, but applies to macro prefixes instead of key prefixes. The starred variant takes effect at the end of current package, while the unstarred one assumes immediate effect. \begin{macro} \ReserveFamilyNames{|vang(list)} +\ReserveFamilyNames|redstar{|vang(list)} \end{macro} -\acmdm*{\ReserveFamilyNames} -This reserves family names \ang{list} and prevents further use of members of \ang{list}. +\acmdm*{\ReserveFamilyNames,\ReserveFamilyNames*} +This reserves family names \ang{list} and prevents further use of members of \ang{list}. The starred variant takes effect at the end of current package, while the unstarred one assumes immediate effect. \textbf{Note:} The lists in these macros are scanned only when defining, disabling, reserving or suspending keys, and not when setting existing keys. If the lists were also to be scanned when keys are being set, then a situation could arise in which existing keys (including those defined by prior packages) couldn't be set. These macros could be used, for instances, to secure against future use the key prefixes, macro prefixes, and key families that have used in a new style or class file. For example, we have used these facilities to bar users of the \pkg{skeyval} from using the key prefix \fx{SKV}, the family name \fx{skeyval}, and the macro prefix \fx{SKV@} to define new keys in their packages. -\begin{macro} -\ReserveKeyPrefixNames|redstar{|vang(list)} -\ReserveMacroPrefixNames|redstar{|vang(list)} -\ReserveFamilyNames|redstar{|vang(list)} -\end{macro} -%\acmd*{\ReserveKeyPrefixNames} -\acmdm*{\ReserveFamilyNames*,\ReserveKeyPrefixNames*,\ReserveMacroPrefixNames*} -These starred variants take effect at end of current package; the unstarred ones above assume immediate effect. If the developer wants to use any member of \ang{list} in his own package, it may be necessary for him to use the starred versions. In addition to the above reservation commands, the \pkg{skeyval} also introduces the following command: \begin{macro} @@ -1671,23 +1677,31 @@ New definable variables can be introduced in sets by the following commands. \begin{macro} \NewBooleans[|vang(optional prefix)]{|vang(boolean list)}[|vang(optional state)] +\DefBooleans[|vang(optional prefix)]{|vang(boolean list)}[|vang(optional state)] \end{macro} -\acmdm*{\NewBooleans} -This provides, for each member of the comma-separated list \ang{boolean list}, a new native-boolean register if the register didn't already exist, otherwise an error is flagged. Each member of \ang{boolean list} is prefixed with \ang{prefix} upon definition. The optional \ang{state} can be either \fx{true}, \fx{false}, \fx{on} or \fx{off}. \fx{on} is synonymous with \fx{true}, whilst \fx{off} is equivalent to \fx{false}. +\acmdm*{\NewBooleans,\DefBooleans} +The function \fx{\NewBooleans} provides, for each member of the comma-separated list \ang{boolean list}, a new native-boolean register if the register didn't already exist; if the boolean already existed, an error is flagged. \fx{\DefBooleans}, on the other hand, provides, for each member of the comma-separated list \ang{boolean list}, a new native-boolean register whether or not the register already existed. If the boolean already existed, a warning message is logged in the transcript file if the package option \fx{verbose} is enabled. + +Each member of \ang{boolean list} is prefixed with \ang{prefix} upon definition. The optional \ang{state} can be either \fx{true}, \fx{false}, \fx{on} or \fx{off}. The state \fx{on} is synonymous with \fx{true}, whilst \fx{off} is equivalent to \fx{false}. \begin{example} \NewBooleans[bool]{a,b,c}[true] |tto \newif\ifboola \newif\ifboolb \newif\ifboolc \boolatrue \boolbtrue \boolctrue \NewBooleans{boold} |tto \newif\ifboold + +\DefBooleans[skv@]{e,f,g}[false] + |tto \newif\ifskv@e \newif\ifskv@f \newif\ifskv@g + \skv@efalse \skv@ffalse \skv@gfalse \end{example} Notice that members of the list \ang{boolean list} don't have \fx{\if} in their names. \begin{macro} \NewTogs[|vang(optional prefix)]{|vang(tog list)}[|vang(optional state)] +\DefTogs[|vang(optional prefix)]{|vang(tog list)}[|vang(optional state)] \end{macro} -\acmdm*{\NewTogs} -This provides a new toggle register for each member of the comma-separated list \ang{tog list} if the register didn't already exist, otherwise an error is flagged. Each member of \ang{tog list} is prefixed with \ang{prefix} upon definition. The optional \ang{state} can be either \fx{true}, \fx{false}, \fx{on} or \fx{off}. \fx{on} is synonymous with \fx{true}, whilst \fx{off} is equivalent to \fx{false}. +\acmdm*{\NewTogs,\DefTogs} +The command \fx{\NewTogs} provides a new toggle register for each member of the comma-separated list \ang{tog list} if the register didn't already exist, otherwise an error is flagged. The command \fx{\DefTogs}, on the other hand, will not raise any error even if the toggle already existed, but (if the package option \fx{verbose} is selected) will instead make an entry in the transcript log file to the effect that the toggle has been redefined. Each member of \ang{tog list} is prefixed with \ang{prefix} upon definition. The optional \ang{state} can be either \fx{true}, \fx{false}, \fx{on} or \fx{off}. The state \fx{on} is synonymous with \fx{true}, whilst \fx{off} is equivalent to \fx{false}. \begin{example} \NewTogs[tog]{a,b,c}[true] |tto \newtog{toga} \newtog{togb} \newtog{togc} @@ -1698,9 +1712,11 @@ This provides a new toggle register for each member of the comma-separated list \begin{macro} \NewToks[|vang(optional prefix)]{|vang(toks list)} +\DefToks[|vang(optional prefix)]{|vang(toks list)} \end{macro} -\acmdm*{\NewToks}\label{page:newtoks} -This provides a new token list register for each member of the comma-separated list \ang{toks list} if the register didn't already exist, otherwise an error is flagged. Each member of \ang{toks list} is prefixed with \ang{prefix} upon definition. +\acmdm*{\NewToks,\DefToks}\label{page:newtoks} +This provides a new token list register for each member of the comma-separated list \ang{toks list} if the register didn't already exist, otherwise an error is flagged. Each member of \ang{toks list} is prefixed with \ang{prefix} upon definition. The command \fx{\DefToks}, on the other hand, will not raise any error even if the token list register already existed, but (if the package option \fx{verbose} is selected) will instead make an entry in the transcript log file to the effect that the register has been redefined. + \begin{example} \NewToks[toks]{a,b,c} |tto \newtoks\toksa \newtoks\toksb \newtoks\toksc @@ -1710,21 +1726,24 @@ This provides a new token list register for each member of the comma-separated l \begin{macro} \NewCounts[|vang(optional prefix)]{|vang(counter list)} +\DefCounts[|vang(optional prefix)]{|vang(counter list)} \end{macro} -\acmdm*{\NewCounts} -This provides a new counter register for each member of the comma-separated list \ang{counter list} if the register didn't already exist, otherwise an error is flagged. Each member of \ang{counter list} is prefixed with \ang{prefix} upon definition. +\acmdm*{\NewCounts,\DefCounts} +This provides a new counter register for each member of the comma-separated list \ang{counter list} if the register didn't already exist, otherwise an error is flagged. Each member of \ang{counter list} is prefixed with \ang{prefix} upon definition. The command \fx{\DefCounts}, on the other hand, will not raise any error even if the counter already existed, but (if the package option \fx{verbose} is selected) will instead make an entry in the transcript log file to the effect that the counter has been redefined. \begin{macro} \NewDimens[|vang(optional prefix)]{|vang(dimen list)} +\DefDimens[|vang(optional prefix)]{|vang(dimen list)} \end{macro} -\acmdm*{\NewDimens} -This provides a new dimension register for each member of the comma-separated list \ang{dimen list} if the register didn't already exist, otherwise an error is flagged. Each member of \ang{dimen list} is prefixed with \ang{prefix} upon definition. +\acmdm*{\NewDimens,\DefDimens} +This provides a new dimension register for each member of the comma-separated list \ang{dimen list} if the register didn't already exist, otherwise an error is flagged. Each member of \ang{dimen list} is prefixed with \ang{prefix} upon definition. The command \fx{\DefDimens}, on the other hand, will not raise any error even if the dimension register already existed, but (if the package option \fx{verbose} is selected) will instead make an entry in the transcript log file to the effect that the register has been redefined. \begin{macro} \NewBoxes[|vang(optional prefix)]{|vang(box list)} +\DefBoxes[|vang(optional prefix)]{|vang(box list)} \end{macro} -\acmdm*{\NewBoxes} -This allocates a new box register for each member of the comma-separated list \ang{box list} if the box register didn't already exist, otherwise an error is flagged. Each member of \ang{box list} is prefixed with \ang{prefix} upon definition. +\acmdm*{\NewBoxes,\DefBoxes} +This allocates a new box register for each member of the comma-separated list \ang{box list} if the box register didn't already exist, otherwise an error is flagged. Each member of \ang{box list} is prefixed with \ang{prefix} upon definition. The command \fx{\DefBoxes}, on the other hand, will not raise any error even if the box register already existed, but (if the package option \fx{verbose} is selected) will instead make an entry in the transcript log file to the effect that the register has been redefined. \begin{example} \NewBoxes[box]{a,b,c} @@ -1735,9 +1754,10 @@ This allocates a new box register for each member of the comma-separated list \a \begin{macro} \NewWrites[|vang(optional prefix)]{|vang(stream list)} +\DefWrites[|vang(optional prefix)]{|vang(stream list)} \end{macro} -\acmdm*{\NewWrites} -This allocates a new output stream for each member of the comma-separated list \ang{stream list} if the stream didn't already exist, otherwise an error is flagged. Each member of \ang{stream list} is prefixed with \ang{prefix} upon definition. +\acmdm*{\NewWrites,\DefWrites} +This allocates a new output stream for each member of the comma-separated list \ang{stream list} if the stream didn't already exist, otherwise an error is flagged. Each member of \ang{stream list} is prefixed with \ang{prefix} upon definition. The command \fx{\DefWrites}, on the other hand, will not raise any error even if the write stream already existed, but (if the package option \fx{verbose} is selected) will instead make an entry in the transcript log file to the effect that the stream has been redefined. \begin{example} \NewWrites[write]{a,b,c} |tto \newwrite\writea \newwrite\writeb \newwrite\writec @@ -1747,12 +1767,13 @@ This allocates a new output stream for each member of the comma-separated list \ \begin{macro} \NewReads[|vang(optional prefix)]{|vang(stream list)} +\DefReads[|vang(optional prefix)]{|vang(stream list)} \end{macro} -\acmdm*{\NewReads} +\acmdm*{\NewReads,\DefReads} -This allocates a new input stream for each member of the comma-separated list \ang{stream list} if the stream didn't already exist, otherwise an error is flagged. Each member of \ang{stream list} is prefixed with \ang{prefix} upon definition. +This allocates a new input stream for each member of the comma-separated list \ang{stream list} if the stream didn't already exist, otherwise an error is flagged. Each member of \ang{stream list} is prefixed with \ang{prefix} upon definition. The command \fx{\DefReads}, on the other hand, will not raise any error even if the read stream already existed, but (if the package option \fx{verbose} is selected) will instead make an entry in the transcript log file to the effect that the stream has been redefined. -The macros \fx{\NewBooleans}, \fx{\NewToks}, \fx{\NewCounts}, \fx{\NewDimens}, \fx{\NewBoxes}, \fx{\NewWrites}, and \fx{\NewReads} are non-outer, unlike their primitive counterparts. +The macros \fx{\NewBooleans}, \fx{\DefBooleans}, \fx{\NewToks}, \fx{\DefToks}, \fx{\NewCounts}, \fx{\DefCounts}, \fx{\NewDimens}, \fx{\DefDimens}, \fx{\NewBoxes}, \fx{\DefBoxes}, \fx{\NewWrites}, \fx{\DefWrites}, \fx{\NewReads}, and \fx{\DefReads} are non-outer, unlike their primitive counterparts. \macrosection{Defining new names} @@ -1781,9 +1802,12 @@ This is similar to \LaTeX's legacy \acmdm{\@nameuse} but returns \fx{\@empty} (i \begin{macro} \SKV@newlet{|vang(cs1)}{|vang(cs2)} \NewLet{|vang(cs1)}{|vang(cs2)} +\SKV@newlet|redstar{|vang(cs1)}{|vang(cs2)} \end{macro} -\acmdm*{\SKV@newlet,\NewLet} -These assign \ang{cs2} to \ang{cs1} if \ang{cs2} exists and if \ang{cs1} isn't already defined, otherwise an error is flagged. The command \fx{\NewLet} is defined in the \pkg{skeyval} only if it hasn't been defined by a previously loaded package; the command \fx{\SKV@newlet}, on the other hand, is always available. You can use \acmd{\TestProvidedCommand} (\macref{mac:testprovide}) to test whether or not you are using the \fx{\NewLet} command of the \pkg{skeyval}. +\acmdm*{\SKV@newlet,\SKV@newlet*,\NewLet} +The first two of these assign \ang{cs2} to \ang{cs1} if \ang{cs2} exists and if \ang{cs1} isn't already defined, otherwise an error is flagged. \fx{\SKV@newlet}\unskip\redstar\ will assign \ang{cs2} to \ang{cs1} whether or not \ang{cs1} is already defined. + +The command \fx{\NewLet} is defined in the \pkg{skeyval} only if it hasn't been defined by a previously loaded package; the command \fx{\SKV@newlet}, on the other hand, is always available. You can use \acmd{\TestProvidedCommand} (\macref{mac:testprovide}) to test whether or not you are using the \fx{\NewLet} command of the \pkg{skeyval}. \begin{macro} \SKV@cslet{|vang(name)}{|vang(cs)} @@ -1804,18 +1828,18 @@ These perform \fx{\let} assignments whether or not the second argument is define \macrosection{Number and dimension expressions} \begin{macro} -\SKV@numdef|redplus|redask{|vang(num)}{|vang(expression)} +\SKV@numdef|redplus|redclam{|vang(num)}{|vang(expression)} \end{macro} \acmdm{\SKV@numdef} defines \ang{num} from \ang{expression} using \etex's \acmd{\numexpr}. If \ang{num} was previously undefined, it is first initialized with \acmd{\newcount} before the expression is built. If you do \fx{\SKV@numdef\x{1+2+3}}, you would need to prefix \fx{\x} with \fx{\the} or \acmd{\number} in expressions. Expressions defined by \fx{\SKV@numdef} can be used with \tex's operators such as \fx{\advance} or \fx{\multiply} and \etex's \acmd{\numexpr} operator. -The plus sign (\RedPlus) means that \fx{\SKV@numdef} takes a control sequence name instead of a control sequence, while the question mark (\RedAsk) implies that the macro \fx{\SKV@numdef} effects a global assignment which can thus escape local groups. +The plus sign (\RedPlus) means that \fx{\SKV@numdef} takes a control sequence name instead of a control sequence, while the exclamation mark (\RedClam) implies that the macro \fx{\SKV@numdef} effects a global assignment which can thus escape local groups. \begin{macro} -\SKV@dimdef|redplus|redask{|vang(dim)}{|vang(expression)} +\SKV@dimdef|redplus|redclam{|vang(dim)}{|vang(expression)} \end{macro} \acmdm{\SKV@dimdef} defines \ang{dim} from \ang{expression} using \etex's \acmd{\dimexpr}. If \ang{dim} was previously undefined, it is first initialized with \acmd{\newdimen} before the expression is built. If you do \fx{\SKV@dimdef\x{1pt+2pt+3pt}}, you would need to prefix \fx{\x} with \fx{\the} in expressions. Expressions defined by \fx{\SKV@dimdef} can be used with \etex's \acmd{\dimexpr} operator. -The plus sign (\RedPlus) means that \fx{\SKV@dimdef} takes a control sequence name instead of a control sequence, while the question mark (\RedAsk) implies that the macro \fx{\SKV@dimdef} effects a global assignment which can thus escape local groups. +The plus sign (\RedPlus) means that \fx{\SKV@dimdef} takes a control sequence name instead of a control sequence, while the exclamation mark (\RedClam) implies that the macro \fx{\SKV@dimdef} effects a global assignment which can thus escape local groups. \macrosection{Verifying definability} @@ -1881,29 +1905,29 @@ These test if \ang{cs} or \ang{name} is defined, relaxed, or undefined. In using \macrosection{Undefining macros} \begin{macro} -\SKV@Undef|redstar|redplus|redask[|vang(optional parser)]{|vang(cs)} +\SKV@Undef|redstar|redplus|redclam[|vang(optional parser)]{|vang(cs)} \end{macro} -\acmdm*{\SKV@Undef,\SKV@Undef*,\SKV@Undef*+,\SKV@Undef*+?} -This undefines the macros or control sequence names in the list \ang{cs} (of nil, one or more elements) such that \tex will subsequently consider each element undefined. The star sign (\RedStar) indicates that \ang{cs} is given as a macro whose \emph{contents} are to be individually undefined, and the plus sign (\RedPlus) shows that \ang{cs} is made up of \emph{control sequence names} instead of control sequences. The question mark (\RedAsk) directs \fx{\SKV@Undef} to \emph{globally} undefine all the control sequences or names in \ang{cs}. Control sequence names are to be separated by the parser; control sequences shouldn't be separated. The default value of the \ang{parser} is ``,'' (comma). The command \fx{\SKV@Undef} is robust (it will thus not expand in expansion contexts), but fragile arguments would need to be protected in expansion contexts.\footnote{Macros such as \acmdm{\@ifnextchar}, \acmdm{\@ifstar}, and those involving optional arguments normally can't be evaluated in expansion contexts. The same applies to the \pkg{skeyval} macros with optional arguments. The \pkgm{etextools} introduced expandable variants of these commands, but in the contexts these commands are employed in the \pkg{skeyval}, the expandable variants aren't particularly advantageous. The main reason is that some of our internal macros (\eg, looping macros) aren't amenable to full expansion anyway. Actually, the \pkg{skeyval} provides the fully expandable variants (\acmdm{\SKV@TestOpt}, \acmdm{\SKV@IfStar}, \acmdm{\SKV@IfPlus}, and \acmdm{\SKV@IfAsk}) of the non-expandable commands \acmdm{\SKV@testopt}, \acmdm{\SKV@ifstar}, \acmdm{\SKV@ifplus}, and \acmdm{\SKV@ifask}. The commands \fx{\SKV@ifask} and \fx{\SKV@IfAsk} look for an optional question mark (\RedAsk).} +\acmdm*{\SKV@Undef,\SKV@Undef*,\SKV@Undef*+} +This undefines the macros or control sequence names in the list \ang{cs} (of nil, one or more elements) such that \tex will subsequently consider each element undefined. The star sign (\RedStar) indicates that \ang{cs} is given as a macro whose \emph{contents} are to be individually undefined, and the plus sign (\RedPlus) shows that \ang{cs} is made up of \emph{control sequence names} instead of control sequences. The exclamation mark (\RedClam) directs \fx{\SKV@Undef} to \emph{globally} undefine all the control sequences or names in \ang{cs}. Control sequence names are to be separated by the parser; control sequences shouldn't be separated. The default value of the \ang{parser} is ``,'' (comma). The command \fx{\SKV@Undef} is robust (it will thus not expand in expansion contexts), but fragile arguments would need to be protected in expansion contexts.\footnote{Macros such as \acmdm{\@ifnextchar}, \acmdm{\@ifstar}, and those involving optional arguments normally can't be evaluated in expansion contexts. The same applies to the \pkg{skeyval} macros with optional arguments. The \pkgm{etextools} introduced expandable variants of these commands, but in the contexts these commands are employed in the \pkg{skeyval}, the expandable variants aren't particularly advantageous. The main reason is that some of our internal macros (\eg, looping macros) aren't amenable to full expansion anyway. Actually, the \pkg{skeyval} provides the fully expandable variants (\acmdm{\SKV@TestOpt}, \acmdm{\SKV@IfStar}, \acmdm{\SKV@IfPlus}, and \acmdm{\SKV@IfAsk}) of the non-expandable commands \acmdm{\SKV@testopt}, \acmdm{\SKV@ifstar}, \acmdm{\SKV@ifplus}, and \acmdm{\SKV@ifask}. The commands \fx{\SKV@ifask} and \fx{\SKV@IfAsk} look for an optional question mark (\RedClam).} \begin{example} \def\unwanted{tempa,tempb,tempc,temp1} -\SKV@Undef|redstar|redplus|redask[,]\unwanted +\SKV@Undef|redstar|redplus|redclam[,]\unwanted \def\unwanted{t1emp,te2mp,tem3p} -\SKV@Undef|redstar|redplus|redask[,]\unwanted +\SKV@Undef|redstar|redplus|redclam[,]\unwanted -\SKV@Undef|redplus|redask[;]{tempd;tempe;tempf} +\SKV@Undef|redplus|redclam[;]{tempd;tempe;tempf} \SKV@Undef\tempe -\SKV@Undef|redask{\tempea\tempeb\tempec\temped} +\SKV@Undef|redclam{\tempea\tempeb\tempec\temped} \SKV@Undef|redplus{tempf} -\SKV@Undef|redask\tempg +\SKV@Undef|redclam\tempg \def\notwanted{\temph\tempi\tempj} @@ -1913,9 +1937,9 @@ This undefines the macros or control sequence names in the list \ang{cs} (of nil The following non-generic variants avoid the above complications of signs, but they don't take lists: \begin{macro} \SKV@undef{|vang(cs)} |tto \SKV@Undef{|vang(cs)} -\SKV@gundef{|vang(cs)} |tto \SKV@Undef|redask{|vang(cs)} +\SKV@gundef{|vang(cs)} |tto \SKV@Undef|redclam{|vang(cs)} \SKV@csundef{|vang(cs name)} |tto \SKV@Undef|redplus{|vang(cs)} -\SKV@csgundef{|vang(cs name)} |tto \SKV@Undef|redplus|redask{|vang(cs)} +\SKV@csgundef{|vang(cs name)} |tto \SKV@Undef|redplus|redclam{|vang(cs)} \end{macro} \acmdm*{\SKV@undef,\SKV@gundef,\SKV@csundef,\SKV@csgundef} @@ -1928,9 +1952,9 @@ The following non-generic variants avoid the above complications of signs, but t This expands its argument \ang{cs} once and forbids further expansion. \begin{macro} -\SKV@expcsox{|vang(name)} +\SKV@csexpox{|vang(name)} \end{macro} -\acmdm*{\SKV@expcsox} +\acmdm*{\SKV@csexpox} This is similar to \fx{\SKV@expox} but accepts control sequence name \ang{name} instead of control sequence. \begin{macro} @@ -1940,9 +1964,9 @@ This is similar to \fx{\SKV@expox} but accepts control sequence name \ang{name} This expands its argument \ang{cs} twice and forbids further expansion. \begin{macro} -\SKV@expcstx{|vang(name)} +\SKV@csexptx{|vang(name)} \end{macro} -\acmdm*{\SKV@expcstx} +\acmdm*{\SKV@csexptx} This is similar to \fx{\SKV@exptx} but accepts control sequence name \ang{name} instead of control sequence. \begin{macro} @@ -2155,13 +2179,14 @@ This will issue an error at start of document if any member of the comma-separat \macrosection{Commands restricted to package and preamble} \begin{macro} -\SKV@onlypreamble{|vang(list)} +\SKV@onlypreamble|redplus{|vang(list)} \SKV@onlypackage \end{macro} \acmdm*{\SKV@onlypreamble,\SKV@onlypackage} -The \latex kernel's macro \fx{\@onlypreamble} accepts only one command at a time (\ie, you can't give it a list of preamble commands in one go), and the error message \acmdm{\@notprerr} is not that precise, since it doesn't indicate the command that has been wrongly placed in the document's body. The use of \fx{\@onlypreamble} in a style or class file can be monotonous if the file has many preamble commands. The macro \fx{\SKV@onlypreamble} takes a no-comma \ang{list} of commands at once and gives precise error messages related to the incorrectly located commands. The \ang{list} may be populated with nil, one, or more control sequences, \eg, +The \latex kernel's macro \fx{\@onlypreamble} accepts only one command at a time (\ie, you can't give it a list of preamble commands in one go), and the error message \acmdm{\@notprerr} is not that precise, since it doesn't indicate the command that has been wrongly placed in the document's body. The use of \fx{\@onlypreamble} in a style or class file can be monotonous if the file has many preamble commands. The macro \fx{\SKV@onlypreamble} takes a comma-separated list \ang{list} of commands at once and gives precise error messages related to the incorrectly located commands. The \ang{list} may be populated with nil, one, or more control sequences. The plus sign~(\RedPlus) means that elements of \ang{list} are control sequence names instead of control sequences. \begin{example} -\SKV@onlypreamble{\macroa \macrob \macroc} +\SKV@onlypreamble{\macroa, \macrob, \macroc} +\SKV@onlypreamble|redplus{macroa, macrob, macroc} \end{example} All preamble commands can be collected together in one \fx{\SKV@onlypreamble}, preferably at the end of the style or class file. @@ -2290,52 +2315,52 @@ These are equivalent to \fx{\SKV@tfor@a} and \fx{\SKV@tfor@b} respectively. \macrosubsection{Hooking to user-defined macros} \begin{macro} -\SKV@appto|redstar|redplus|redask|vang(cs){|vang(content)} +\SKV@appto|redstar|redplus|redclam|vang(cs){|vang(content)} \end{macro} -\acmdm*{\SKV@appto,\SKV@appto*,\SKV@appto*+,\SKV@appto*+?} -This appends \ang{content} to \ang{cs}. If \ang{cs} was previously undefined, it is initialized with \ang{content}. The star (\RedStar) sign directs \fx{\SKV@appto} to expand \ang{content} once before appending \ang{content} to \ang{cs}. The plus (\RedPlus) sign means that \ang{cs} is a control sequence name instead of a control sequence, while the question mark (\RedAsk) instructs \fx{\SKV@appto} to append \ang{content} to \ang{cs} globally (to escape local groups). This command is robust, but fragile arguments must be protected in expansion contexts. +\acmdm*{\SKV@appto,\SKV@appto*,\SKV@appto*+} +This appends \ang{content} to \ang{cs}. If \ang{cs} was previously undefined, it is initialized with \ang{content}. The star (\RedStar) sign directs \fx{\SKV@appto} to expand \ang{content} once before appending \ang{content} to \ang{cs}. The plus (\RedPlus) sign means that \ang{cs} is a control sequence name instead of a control sequence, while the exclamation mark (\RedClam) instructs \fx{\SKV@appto} to append \ang{content} to \ang{cs} globally (to escape local groups). This command is robust, but fragile arguments must be protected in expansion contexts. -Except for the initialization of undefined \ang{cs}, \fx{\SKV@appto}\redask\ is equivalent to \latex's \acmdm{\g@addto@macro}. +Except for the initialization of undefined \ang{cs}, \fx{\SKV@appto}\redclam\ is equivalent to \latex's \acmdm{\g@addto@macro}. The following non-generic, less powerful, forms of \fx{\SKV@appto} are also available, but they don't have the starred (\RedStar) variants: \begin{macro} \apptomac|vang(cs){|vang(content)} |tto \SKV@appto|vang(cs){|vang(content)} \gapptomac|vang(cs){|vang(content)} - |tto \SKV@appto|redask|vang(cs){|vang(content)} + |tto \SKV@appto|redclam|vang(cs){|vang(content)} \csapptomac{|vang(name)}{|vang(content)} |tto \SKV@appto|redplus{|vang(name)}{|vang(content)} \csgapptomac{|vang(name)}{|vang(content)} - |tto \SKV@appto|redplus|redask{|vang(name)}{|vang(content)} + |tto \SKV@appto|redplus|redclam{|vang(name)}{|vang(content)} \end{macro} \acmdm*{\apptomac,\gapptomac,\csapptomac,\csgapptomac} \bigskip \begin{macro} -\SKV@prepto|redstar|redplus|redask|vang(cs){|vang(content)} +\SKV@prepto|redstar|redplus|redclam|vang(cs){|vang(content)} \end{macro} -\acmdm*{\SKV@prepto,\SKV@prepto*,\SKV@prepto*+,\SKV@prepto*+?} -This prepends \ang{content} to \ang{cs}. If \ang{cs} was previously undefined, it is initialized with \ang{content}. The star (\RedStar) sign directs \fx{\SKV@prepto} to expand \ang{content} once before prepending it to \ang{cs}. The plus (\RedPlus) sign means that \ang{cs} is a control sequence name instead of a control sequence, while the question mark (\RedAsk) instructs \fx{\SKV@prepto} to prepend \ang{content} to \ang{cs} globally (to escape local groups). This command is robust, but fragile arguments must be protected in expansion contexts. +\acmdm*{\SKV@prepto,\SKV@prepto*,\SKV@prepto*+} +This prepends \ang{content} to \ang{cs}. If \ang{cs} was previously undefined, it is initialized with \ang{content}. The star (\RedStar) sign directs \fx{\SKV@prepto} to expand \ang{content} once before prepending it to \ang{cs}. The plus (\RedPlus) sign means that \ang{cs} is a control sequence name instead of a control sequence, while the exclamation mark (\RedClam) instructs \fx{\SKV@prepto} to prepend \ang{content} to \ang{cs} globally (to escape local groups). This command is robust, but fragile arguments must be protected in expansion contexts. Again, the following non-generic versions of \fx{\SKV@prepto} are available, but they don't have the starred (\RedStar) variants: \begin{macro} \preptomac|vang(cs){|vang(content)} |tto \SKV@prepto|vang(cs){|vang(content)} \gpreptomac|vang(cs){|vang(content)} - |tto \SKV@prepto|redask|vang(cs){|vang(content)} + |tto \SKV@prepto|redclam|vang(cs){|vang(content)} \cspreptomac{|vang(name)}{|vang(content)} |tto \SKV@prepto|redplus{|vang(name)}{|vang(content)} \csgpreptomac{|vang(name)}{|vang(content)} - |tto \SKV@prepto|redplus|redask{|vang(name)}{|vang(content)} + |tto \SKV@prepto|redplus|redclam{|vang(name)}{|vang(content)} \end{macro} \acmdm*{\preptomac,\gpreptomac,\cspreptomac,\csgpreptomac} \bigskip \begin{macro} -\SKV@addtolist|redplus|redask|redleft[|vang(parser)]|vang(csa)|vang(csb) +\SKV@addtolist|redplus|redclam|redleft[|vang(parser)]|vang(csa)|vang(csb) \end{macro} -\acmdm*{\SKV@addtolist,\SKV@addtolist+,\SKV@addtolist+?,\SKV@addtolist+?<} -This adds the contents of the macro \ang{csb} to the list in the container \ang{csa}. The plus sign~(\RedPlus) means that \ang{csa} is a control sequence name (instead of a control sequence); the question mark~(\RedAsk) directs \fx{\SKV@addtolist} to add the contents of \ang{csb} to \ang{csa} globally (to escape local groups); and the left angle (\RedLeft), if present, instructs \fx{\SKV@addtolist} to prepend the contents of \ang{csb} to the left of the contents of \ang{csa}, instead of appending to the right by default. The optional argument \ang{parser} is the list parser, ie, the separator of the instances in \ang{csa}. Its default value is ``,'' (comma). +\acmdm*{\SKV@addtolist,\SKV@addtolist+,\SKV@addtolist+<} +This adds the contents of the macro \ang{csb} to the list in the container \ang{csa}. The plus sign~(\RedPlus) means that \ang{csa} is a control sequence name (instead of a control sequence); the exclamation mark~(\RedClam) directs \fx{\SKV@addtolist} to add the contents of \ang{csb} to \ang{csa} globally (to escape local groups); and the left angle (\RedLeft), if present, instructs \fx{\SKV@addtolist} to prepend the contents of \ang{csb} to the left of the contents of \ang{csa}, instead of appending to the right by default. The optional argument \ang{parser} is the list parser, ie, the separator of the instances in \ang{csa}. Its default value is ``,'' (comma). \macrosubsection{Package and document hooks} @@ -2450,11 +2475,8 @@ The following change history highlights significant changes that affect user uti \define@biuniboolkeys,\newbiuniboolkeys,\define@biunitogkeys,\newbiunitogkeys} \item Provided mechanisms for disabling, localizing, reserving, unreserving, suspending, restoring, and removing keys \secref{sec:disable-reserv-keys} - \item Redefined a few of \pkg{xkeyval}'s internal macros \xsecref - \item Normalization of key-value lists before parsing \secref{sec:list-normal} - \item Included some developer macros \secref{sec:misce-commands} \end{version} @@ -2487,32 +2509,36 @@ The following change history highlights significant changes that affect user uti \@ensurepackageloaded} \item Alert the user if \pkg{skeyval} is loaded before \acmd{\documentclass} \secref{sec:loading-package} - \item Introduced ``user-value'' keys \secref{sec:uservaluekeys} - \item Extended the pointer system of the \pkg{xkeyval} \secref{sec:pointer-mech} \item Corrected a bug in the \pkg{xkeyval} which, if \acmd{\setkeys} is nested in a class file, gives non-empty \acmdm{\@unusedoptionlist} even if all the options of \acmd{\documentclass} have been used \xsecref \end{version} \begin{version}{0.7}{2010/05/05} \item Native-boolean and toggle-boolean keys now accept \fx{on} and \fx{off} as values, - in addition to \fx{true} and \fx{false} \secref*{sec:toggle-booleans}{sec:switches} - + in addition to \fx{true} and \fx{false} \secref*{sec:toggle-booleans}{sec:switches} \item Replaced the former \acmd{\NewIfs} with \acmd{\NewBooleans} and redefined \fx{\NewIfs} \secref{sec:biboolkeys} - \item Introduced \acmd{\DeclareKeyCommand} \xsecref \end{version} \begin{version}{0.71}{2010/05/06} \item Corrected a bug in one of the internal conditional tests \xsecref - \item Removed \fx{\DeclareKeyCommand} to create a separate \pkg{skeycommand} \xsecref + \end{version} + \begin{version}{0.72}{2010/05/21} + \item The parameter character is made temporarily innocent when the arguments of \fx{\define@keylist} and \fx{\newkeylist} are being absorbed \secref{sec:def-multiple-keys} + \item Debugged why, \eg, \fx{#1} in the following definition would refer to the wrong quantity in the \pkg{xkeyval}: + \xsecref + \begin{veritem} + \define@boolkey[KV]{fam}[mp@]{keya}[true]{\def\x{#1}} + \end{veritem} \end{version} \end{versionhist} +\newpage \IndexPreamble{Index numbers refer to page numbers.} \IndexPreambleFormat{\centering} \IndexColumns\tw@ |