diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/skeyval/skeyval-guide.tex')
| -rw-r--r-- | Master/texmf-dist/doc/latex/skeyval/skeyval-guide.tex | 389 |
1 files changed, 250 insertions, 139 deletions
diff --git a/Master/texmf-dist/doc/latex/skeyval/skeyval-guide.tex b/Master/texmf-dist/doc/latex/skeyval/skeyval-guide.tex index 82a59f63d18..919ebfc7d9e 100644 --- a/Master/texmf-dist/doc/latex/skeyval/skeyval-guide.tex +++ b/Master/texmf-dist/doc/latex/skeyval/skeyval-guide.tex @@ -1,5 +1,6 @@ \documentclass[a4paper,10pt,final,language=UKenglish,fancysec,fancyfnote]{amltxdoc} \makeatletter +\let\sectionbreak\medbreak \begin{document} @@ -8,12 +9,12 @@ \title{The \texttt{\color{blue}skeyval} Package\titleref{t1,t2}} \titlenote[t1]{The \pkgm{skeyval} was formerly called the \pkgm{keyreader} until version~0.5. The \asty{keyreader} is now obsolete and no longer supported.} -\iftog{pdf}{% +\iftogon{pdf}{% \titlenote[t2]{The package is available at \url{\@titleurl}.}% }{% \titlenote[t2]{The package is available at \url{\@shorttitleurl}.}% } -\subtitle{Version 0.6} +\subtitle{Version 0.7} \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} @@ -29,12 +30,12 @@ version~0.5. The \asty{keyreader} is now obsolete and no longer supported.} } \end{abstract} -\NewLet\licename\licensename +\NewLet\licname\licensename \SKV@redef*\licensename{\vspace{-\baselineskip}} \begin{license} \frameshade[width=\hsize,fillcolor=white,framesep=2pt,framerule=2pt, framecolor=brown]{\small - \vspace{1ex}\centerline{\licename}\endgraf + \vspace{1ex}\centerline{\licname}\endgraf This work (\ie, all the files in the \asty{skeyval} bundle) may be distributed and/or modified under the conditions of the \lppl (LPPL), either version~1.3 of this license or any later version. \endgraf 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. @@ -53,7 +54,7 @@ version~0.5. The \asty{keyreader} is now obsolete and no longer supported.} \section{Motivation} \label{sec:motivation} -\lletter{T}oggle switches or booleans were introduced by the \pkgm{etoolbox} and have proved attractive mainly for two reasons: unlike the legacy/native \tex switches which require three commands per switch, toggles require only one command per switch, and toggles occupy their own separate namespace, thereby avoiding clashes with other macros. So we can effectively have both the following sets in the same file: +\lletter{T}oggle booleans were introduced by the \pkgm{etoolbox} and have proved attractive mainly for two reasons: unlike the legacy/native \tex switches which require three commands per switch, toggles require only one command per switch, and toggles occupy their own separate namespace, thereby avoiding clashes with other macros. So we can effectively have both the following sets in the same file: \begin{example} |comm(Knuth/native switch:) \newif\ifmyboolean |tto 3 separate commands: @@ -62,22 +63,22 @@ version~0.5. The \asty{keyreader} is now obsolete and no longer supported.} |comm(Toggle switch:) \newtog{myboolean} |tto only 1 command and no clash with - commands in other namespaces. + commands in other namespaces \end{example} \Note A toggle is also a boolean or switch. We refer to it here as \emph{toggle} or \emph{toggle switch} or \emph{toggle boolean}. The term \emph{Knuth/native switch} is reserved here for \tex's legacy boolean or switch. -The \pkg{xkeyval} can't be used to define and set toggle keys. The present package provides facilities for defining and setting toggle keys. The work relies on some of the macros from the \pkg{xkeyval}. +The \pkg{xkeyval} can't be used to define and set toggle keys. The present package provides facilities for defining and setting toggle keys. The work relies on some of the internal macros from the \pkg{xkeyval}. Secondly, the \pkg{xkeyval} can't be used to define and set complementary (bipolar and unipolar) keys, which can be handy in the case of native boolean and toggle keys. Complementary bipolar keys are mutually exclusive keys, \ie, they never assume the same state of a two-valued logic, and they switch states automatically, depending on the state of any one of them. So whenever one of them assumes one of the two states of a two-valued logic, the other one automatically switches its state from whatever state it was previously, such that the two are never in the same state. Simple examples of complementary bipolar keys would be the options \acmd{draft} and \acmd{final} in a document; they are mutually exclusive. Complementary bipolar keys carry equal charge, \ie, each one can equally toggle the other with identical propensity, but the one that represents the default state of a two-valued logic is usually considered the primary, while the other is secondary. In many document classes, for instance, \acmd{final} is considered a default document option and \acmd{draft} would have to be explicitly selected by the user to toggle \acmd{final} to false. 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 are introduced as well. +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 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. -Fourthly, macros are introduced for defining all key types without the fear of inadvertently redefining existing keys in the same family and with the same key prefix. This has a philosophy similar to the \acmd{\newcommand} concept in \LaTeX. +Fourthly, macros are introduced for defining all key types without the fear of inadvertently redefining existing keys in the same family and with the same key prefix. This has a philosophy akin to the \acmd{\newcommand} concept in \LaTeX. The package also provides facilities for disabling, suspending, restoring and removing keys across multiple families of keys. The pointer system of the \pkg{xkeyval} is also extended by the \pkg{skeyval}, and the notion of ``user-value'' keys is introduced. @@ -87,7 +88,7 @@ The new macros can be used together with the machinery from the \pkg{xkeyval} fo The \pkg{xkeyval} strips off up to three levels of braces in the value part of the \acmd{key-value} pair: one by using the \pkgm{keyval}'s leading and trailing space removal command and two in internal parsings (at some known commands). The \asty{keyval} strips off only two levels of braces: one in using its space removal routine and one in internal parsings. The \pkgm{kvsetkeys} strips off only one level of braces. The matter of these differences has not yet been shown to have serious implications for existing or new packages, although it is apparently of concern to the \pkgm{keycommand}. -The \pkg{skeyval} internally uses a space removal scheme that doesn't strip off braces from its arguments, but since the present package relies, to a good extent, on the engine of the \pkg{xkeyval}, the brace stripping effect has remained.\footnote{We have had to redefine some of the internal macros of the \pkg{xkeyval}, but getting rid of the brace-stripping issue would require even more substantial revision of the internal macros of the \pkg{xkeyval}.} It can easily be solved but there is currently no sufficient reason to do so. If, odd enough, you want at least one level of braces to persist in the value part of the \acmd{key-value} pair throughout parsing, you simply surround the value with four levels of braces in the \acmd{\setkeys} command. If the users of this, or the \pkg{xkeyval}, feel that this issue is of significant concern, then it can be addressed in the future. +The \pkg{skeyval} internally uses a space removal scheme that doesn't strip off braces from its arguments, but since the present package relies, to a good extent, on the engine of the \pkg{xkeyval}, the brace stripping effect has remained. We have had to redefine a significant number of the internal macros of the \pkg{xkeyval}, but getting rid of the brace-stripping issue would require even more substantial revision of the internal macros of the \pkg{xkeyval}. It can easily be solved but there is currently no sufficient reason to do so. If, odd enough, you want at least one level of braces to persist in the value part of the \acmd{key-value} pair throughout parsing, you simply surround the value with four levels of braces in the \acmd{\setkeys} command. If the users of this, or the \pkg{xkeyval}, feel that this issue is of significant concern, then it can be addressed in the future. \section{The \texttt{skeyval} package options} \label{sec:loading-package} @@ -123,6 +124,7 @@ The \pkg{skeyval} issues a fatal error if it is loaded before (or run without) \ \label{sec:comp-boolkeys} \subsection{Bipolar native-boolean keys} +\label{sec:biboolkeys} As mentioned in \cref{sec:motivation}, complementary bipolar keys are keys that depend inversely on each other: when one of them is in a particular state of a two-valued logic, the other one automatically assumes the opposite or complementary state. For each pair of bipolar keys, one is normally assumed to be the primary key and the other the secondary. The primary boolean key will usually represent the default state of a two-valued logic. Whenever one bipolar key (primary or secondary) is true, its complement is automatically set false; and vice versa: when one bipolar key (primary or secondary) is false, its complement is automatically set true. Generally, the transition of the state of a key from negative (false) to positive (true) is associated with the execution of the key's macro. @@ -134,12 +136,24 @@ The syntax for creating bipolar native-boolean keys is {|cang(func for secondary boolean)} \end{macro} \acmdm*{\define@biboolkeys} -This command is robust and can be used in expansion contexts, but expandable commands may need to be protected. When the user doesn't supply the \aang{keyprefix} and/or \aang{macroprefix}, the package will use \aang{KV} and \aang{mp@}, respectively. When the default value for the primary boolean is not supplied, the package will use \acmd{true}. Infinite loops, which are possible in back-linked key settings, are avoided in the \pkg{skeyval}. The machinery of the \pkg{xkeyval}, such as \acmd{\setkeys}, \acmd{\presetkeys}, \acmd{\savekeys}, \acmd{\savevalue}, \acmd{\usevalue}, \etc, are all applicable to complementary bipolar keys. +This command is robust and can be used in expansion contexts, but expandable commands may need to be protected. When the user doesn't supply the \aang{keyprefix} and/or \aang{macroprefix}, the package will use \aang{KV} and \aang{mp@}, respectively. When the default value for the primary boolean is not supplied, the package will use \acmd{true}. Infinite loops, which are possible in back-linked key settings, are avoided in the \pkg{skeyval}. The machinery of the \pkg{xkeyval}, such as \acmd{\setkeys}, \acmd{\presetkeys}, \acmd{\savekeys}, \acmd{\savevalue}, \acmd{\usevalue}, \etc, are all applicable to all complementary keys. As an example, we define below two bipolar native-boolean keys \aang{draft} and \aang{final} with different key macros: \begin{example} \define@biboolkeys[KV]{fam}[mp@]{draft}[true]{final}% - {\def\noneofone##1{}}{\def\oneofone##1{##1}} +{% + \ifmp@draft + \def\noneofone##1{}% + \else + \def\oneofone##1{##1}% + \fi +}{% + \ifmp@final + \def\noneoftwo##1##2{}% + \else + \def\oneoftwo##1##2{##1}% + \fi +} \end{example} The key prefix (default \fx{KV}), macro prefix (default \fx{mp@}), key macros (no default), and the default value of the primary boolean (\fx{true}) can all be empty: \begin{example} @@ -148,15 +162,29 @@ The key prefix (default \fx{KV}), macro prefix (default \fx{mp@}), key macros (n The defined complementary bipolar keys \aang{draft} and \aang{final} can now be set separately as follows: \begin{example} -\setkeys[KV]{fam}{draft=true} +\setkeys[KV]{fam}{draft=true |makered(or) on} -\setkeys[KV]{fam}{final=true} +\setkeys[KV]{fam}{final=true |makered(or) on} \end{example} The second statement above reverses the boolean \aang{draft} to \aang{false}, which had been set in the first statement to \aang{true}. There is no apparent meaning to the following: \begin{example} \setkeys[KV]{fam}{draft=true,final=true}. \end{example} +\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: +\begin{macro} +\NewIfs[|cang(optional prefix)]{|cang(boolean list)}[|cang(optional state)] +\end{macro} +\acmdm*{\NewIfs} +This provides, for each member of the comma-separated list \bang{boolean list}, a new native-boolean register if the register didn't already exist, otherwise an error is flagged. Each member of \bang{boolean list} is prefixed with \aang{prefix} upon definition. The optional \aang{state} can be either \fx{true}, \fx{false}, \fx{on} or \fx{off}; the default is \fx{false}. \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. + \subsection{Unipolar native-boolean keys} Unipolar boolean keys are two keys that are always in the same state: when one is true (or false), the other one is also true (or false). In this regard, the key macro is always executed when a key transits to the ``true'' state. The syntax for creating unipolar native-boolean keys is exactly as that for defining bipolar native-boolean keys: @@ -169,10 +197,24 @@ Unipolar boolean keys are two keys that are always in the same state: when one i \acmdm*{\define@uniboolkeys} This command is robust and can be used in expansion contexts, but expandable commands may need to be protected. Again, if the user doesn't supply the \aang{keyprefix} and/or \aang{macroprefix}, the package will use \aang{KV} and \aang{mp@}, respectively. When the default value for the primary boolean is not supplied, the package will assume it to be \fx{true}. -The following example constructs two unipolar boolean keys: +The following example constructs two unipolar native-boolean keys: \begin{example} +\NewToks[temptoks]{a,b} + \define@uniboolkeys[KV]{fam}[mp@]{pdfmode}[true]{microtype}% -{\temptoks{Yes, in `pdfmode'}}{\def\temp{`microtype' loaded}} +{% + \ifmp@pdfmode + \temptoksa{Yes, in `pdfmode'}% + \else + \temptoksa{No, not in `pdfmode'}% + \fi +}{% + \ifmp@microtype + \temptoksb{Yes, `microtype' loaded}% + \else + \temptoksb{No, `microtype' not loaded}% + \fi +} \end{example} \subsection{Biunipolar native-boolean keys} @@ -198,7 +240,10 @@ The syntax for establishing biuni boolean keys is exactly like that for creating As an example, consider the arbitrary package or class options \fx{review} and \fx{preprint}. The option \fx{preprint} can automatically toggle \fx{review} to true, but possibly not vice versa: not every \fx{preprint} is a manuscript for \fx{review}. This is depicted below: \begin{example} -\define@biuniboolkeys[KV]{fam}[mp@]{preprint}[true]{review}{}{% +\define@biuniboolkeys[KV]{fam}[mp@]{preprint}[true]{review}{% + |comm(No key macro for preprint; otherwise, it would) + |comm(have come in here.) +}{% \ifmp@review \SKV@BeforeDocumentStart{% \linespread{1.5}\selectfont @@ -229,7 +274,7 @@ As another example, consider the following biuni keys, each with its own macro: \end{example} \acmd*{\SKV@AfterDocumentStart} -\section{Toggle booleans and keys} +\section{Toggle booleans and toggle keys} \label{sec:toggles} In the following \crefrange{sec:toggle-booleans}{sec:toggle-keys} we define toggle booleans/switches and use them to introduce toggle-boolean keys. @@ -237,72 +282,77 @@ In the following \crefrange{sec:toggle-booleans}{sec:toggle-keys} we define togg \subsection{Toggle booleans} \label{sec:toggle-booleans} -The following toggle switches are defined in the \pkg{skeyval}. They largely mimic those in the \pkg{etoolbox}, except for the commands \acmdm{\deftog} and \acmd{\requiretog}. There is no fear that the commands in this package will interfere with those from the \pkg{etoolbox}, since the internal control sequences and user interfaces of the two packages are different. +The following toggle switches are defined in the \pkg{skeyval}. They largely mimic those in the \pkg{etoolbox}, except for the commands \acmdm{\deftog} and \acmd{\requiretog}. The internal control sequences and user interfaces of the two packages are, however, different, thus avoiding clashes. -All the commands in this section are robust and can be used in expansion or moving contexts, but fragile arguments would need to be protected in those settings. +All the commands in this section are robust and can be used in expansion or moving contexts without fear of premature expansion, but fragile arguments would need to be protected in those settings. \begin{macro} -\deftog{|cang(toggle)} +\deftog[|cang(optional prefix)]{|cang(toggle)}[|cang(optional state)] \end{macro} -This defines a new \aang{toggle} whether or not \aang{toggle} is already defined. If \aang{toggle} is already defined, a warning message is logged in the transcript file (if the package option \fx{verbose} is selected) and the new definition is effected. +This defines a new \aang{toggle}, prefixed with \aang{prefix} upon definition, whether or not \aang{toggle} (with its prefix) is already defined. If \aang{toggle} is already defined, a warning message is logged in the transcript file (if the package option \fx{verbose} is selected) and the new definition is effected. The optional \aang{state} can be either \fx{true}, \fx{false}, \fx{on} or \fx{off}. \begin{macro} -\newtog{|cang(toggle)} +\newtog[|cang(optional prefix)]{|cang(toggle)}[|cang(optional state)] \end{macro} \acmdm*{\newtog} -This defines a new \aang{toggle} if \aang{toggle} is not already defined; otherwise the package issues a fatal error. You can define a set of toggles by the following command: +This defines a new \aang{toggle}, prefixed with \aang{prefix} upon definition, if \aang{toggle} (with its prefix) is not already defined; otherwise the package issues a fatal error. The optional \aang{state} can be either \fx{true}, \fx{false}, \fx{on} or \fx{off}. + +You can define a set of toggles by the following command: \begin{macro} \NewTogs[|cang(optional prefix)]{|cang(toggles)}[|cang(optional state)], \end{macro} \acmdm*{\NewTogs} -where \aang{toggles} is a comma-separated list. Each member of \aang{toggles} is prefixed with \aang{prefix} upon definition. The optional \aang{state} can be either \fx{true} or \fx{false}. For example, we may define new toggles \fx{x}, \fx{y}, \fx{z} by the following: +where \aang{toggles} is a comma-separated list. Each member of \aang{toggles} is prefixed with \aang{prefix} upon definition. The optional \aang{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[skv@]{x,y,z}[true] +\NewTogs[tog]{x,y,z}[true] \end{example} - \begin{macro} \providetog{|cang(toggle)} \end{macro} \acmdm*{\providetog} -This defines a new \aang{toggle} if \aang{toggle} is not already defined. If \aang{toggle} is already defined, the command does nothing. +This defines a new \aang{toggle} if \aang{toggle} is not already defined. If \aang{toggle} is already defined, the command does nothing. Please note that there are no tog prefix here, and that the default state is \fx{false}. \begin{macro} \requiretog{|cang(toggle)} \end{macro} -\acmdm{\requiretog} takes arguments like \fx{\newtog} and behaves like \fx{\providetog} with the difference: if the toggle is already defined, the command \fx{\requiretog} calls \LaTeX's \acmdm{\CheckCommand} to make sure that the new and existing definitions are identical, whereas \fx{\providetog} assumes that if the toggle is already defined, the existing definition should persist. \fx{\requiretog} assures that a toggle will have the given definition, but (if the package option \fx{verbose} is selected) \fx{\requiretog} also warns the user if there was a previous and different existing definition. For example, if the toggle \aang{toga} is currently \aang{true}, then since all new toggles start out as \aang{false}, a call \fx{\requiretog{toga}} will, if the package option \fx{verbose} is selected, issue a warning in the log file that the new and old definitions of \aang{toga} don't agree and the new definition, therefore, can't go ahead. +\acmdm{\requiretog} takes arguments like \fx{\newtog} and behaves like \fx{\providetog} with the difference: if the toggle is already defined, the command \fx{\requiretog} calls \LaTeX's \acmdm{\CheckCommand} to make sure that the new and existing definitions are identical, whereas \fx{\providetog} assumes that if the toggle is already defined, the existing definition should persist. \fx{\requiretog} assures that a toggle will have the given definition, but (if the package option \fx{verbose} is selected) \fx{\requiretog} also warns the user if there was a previous and different existing definition. For example, if the toggle \aang{toga} is currently \aang{true}, then since all new toggles start out as \aang{false}, a call \fx{\requiretog{toga}} will, if the package option \fx{verbose} is selected, issue a warning in the log file that the new and old definitions of \aang{toga} don't agree and the new definition, therefore, can't go ahead. Note that there are no tog prefix here, and that the default state is \fx{false}. The \pkg{skeyval} also provides the command \acmd{\requirecmd}, which has the same logic as \fx{\requiretog} but can be used for general \latex commands, including those with optional arguments (see \cref{sec:misce-commands}). \begin{macro} -\settog{|cang(toggle)}{|cang(true |amdvert false)} +\settog{|cang(toggle)}{|cang(true |amdvert false |amdvert on |amdvert off)} \end{macro} \acmdm*{\settog} -This command sets \aang{toggle} to \aang{value}, where \aang{value} may be either \aang{true} or \aang{false}. This statement will issue an error if \aang{toggle} wasn't previously defined. +This command sets \aang{toggle} to \aang{value}, where \aang{value} may be either \fx{true}, \fx{false}, \fx{on} or \fx{off}. This statement will issue an error if \aang{toggle} wasn't previously defined. \begin{macro} +\togon{|cang(toggle)} \togtrue{|cang(toggle)} \end{macro} -\acmdm*{\togtrue} -This sets \aang{toggle} to \aang{true}. It will issue an error if \aang{toggle} wasn't previously defined. +\acmdm*{\togon, \togtrue} +These set \aang{toggle} to \aang{true} or \fx{on}. They will issue an error if \aang{toggle} wasn't previously defined. \begin{macro} +\togoff{|cang(toggle)} \togfalse{|cang(toggle)} \end{macro} -\acmdm*{\togfalse} -This sets \aang{toggle} to \aang{false}. It will issue an error if \aang{toggle} wasn't previously defined. +\acmdm*{\togoff, \togfalse} +These set \aang{toggle} to \aang{false} or \fx{off}. They will issue an error if \aang{toggle} wasn't previously defined. \begin{macro} -\iftog{|cang(toggle)}{|cang(true)}{|cang(false)} +\iftogon{|cang(toggle)}{|cang(true)}{|cang(false)} +\iftogtrue{|cang(toggle)}{|cang(true)}{|cang(false)} \end{macro} -\acmdm*{\iftog} -This yields the \aang{true} statement if the boolean \aang{toggle} is currently \aang{true}, and \aang{false} otherwise. It will issue an error if \aang{toggle} wasn't previously defined. +\acmdm*{\iftogon, \iftogtrue} +These yield the \aang{true} statement if the boolean \aang{toggle} is currently \aang{true}, and \aang{false} otherwise. They will issue an error if \aang{toggle} wasn't previously defined. \begin{macro} -\ifnottog{|cang(toggle)}{|cang(not true)}{|cang(not false)} +\iftogoff{|cang(toggle)}{|cang(not true)}{|cang(not false)} +\iftogfalse{|cang(toggle)}{|cang(not true)}{|cang(not false)} \end{macro} -\acmdm*{\ifnottog} -This behaves like \fx{\iftog} but reverses the logic of the test. It will issue an error if \aang{toggle} wasn't previously defined. +\acmdm*{\iftogoff, \iftogfalse} +These behave like \fx{\iftogon} and \fx{\iftogtrue} but reverse the logic of the test. They will issue an error if \aang{toggle} wasn't previously defined. \subsection{Toggle-boolean keys} \label{sec:toggle-keys} @@ -330,7 +380,7 @@ If the plus (\RedPlus) version of the macro is used, the user can specify two ke As an example, consider the following: \begin{example} \define@togkey{fam}[my@]{frame}{% - \iftog{my@frame}{% + \iftogon{my@frame}{% \PackageInfo{mypack}{Turning frames on}% }{% \PackageInfo{mypack}{Turning frames off}% @@ -338,7 +388,7 @@ As an example, consider the following: } \define@togkey|redplus{fam}{shadow}{% - \iftog{KV@fam@shadow}{% + \iftogon{KV@fam@shadow}{% \PackageInfo{mypack}{Turning shadows on}% }{% \PackageInfo{mypack}{Turning shadows off}% @@ -374,7 +424,7 @@ This is an abbreviation for Now we can do \begin{example} \define@togkey{fam}[my@]{book}{% - \iftog{my@book}{\setkeys[KV]{fam}{togc=true}}{}% + \iftogon{my@book}{\setkeys[KV]{fam}{togc=true}}{}% } \setkeys[KV]{fam}{book=true} \end{example} @@ -424,9 +474,10 @@ The defined bipolar toggle keys \aang{xdraft} and \aang{xfinal} can now be set a \acmd*{\setkeys} The second statement above reverses the toggle \aang{xdraft} to \aang{false}, which had been set in the first statement to \aang{true}. -Toggle keys may easily be confused with the conventional (native) boolean keys, especially at the time of key setting. It is, therefore, always safer to use the syntaxes in \cref{sec:redef-keys} for defining keys; they avoid interference between new and existing keys. +\Note +Toggle keys may easily be confused with the conventional boolean keys, especially at the time of key setting. It is, therefore, always safer to use the syntaxes in \cref{sec:redef-keys} for defining keys; they avoid interference between new and existing keys. -\Note If we were to use the key names \acmd{draft} and \acmd{final} as toggle keys above, instead of \fx{xdraft} and \fx{xfinal}, there would have been a clash with the keys \acmd{draft} and \acmd{final} defined as (complementary) native-boolean keys in \cref{sec:comp-boolkeys}---because they share the same family \aang{fam} and prefix \aang{KV}. The names \acmd{draft} and \acmd{final} can be used as toggles only if the family \aang{fam} or prefix \aang{KV} is changed. See \cref{sec:avoiding-redef} for further details. +If we were to use the key names \acmd{draft} and \acmd{final} as toggle keys above, instead of \fx{xdraft} and \fx{xfinal}, there would have been a clash with the keys \acmd{draft} and \acmd{final} defined as (complementary) native-boolean keys in \cref{sec:comp-boolkeys}---because they share the same family \aang{fam} and prefix \aang{KV}. The names \acmd{draft} and \acmd{final} could safely be used as toggles only if the family \aang{fam} or prefix \aang{KV} is changed. See \cref{sec:avoiding-redef} for further details. \subsection{Unipolar toggle-boolean keys} @@ -459,11 +510,11 @@ The interface for creating biuni toggle keys is exactly like that for creating o \begin{example} \define@biunitogkeys|redplus[KV]{fam}[mp@]{preprint}[true]{review}{% - \iftog{mp@preprint}{% + \iftogon{mp@preprint}{% \def\banner{\fbox{\textsf{This is a preprint copy}}}% }{}% }{% - \iftog{mp@review}{% + \iftogon{mp@review}{% \SKV@AtDocumentStart{\linespread{1.5}\selectfont}% \def\banner{\fbox{\textit{This is a review article}}}% }{% @@ -485,7 +536,7 @@ The interface for defining multiple keys of all kinds in one go is the command \ \end{macro} There are five key types: 1 (ordinary key), 2 (command key), 3 (native-boolean key), -4 (toggle-boolean key), and 5 (choice/menu key). The key types can be indicated either in numeral format (\fx{1}~to~\fx{5}) or in alphabetic format (\fs{ord}, \fx{cmd}, \fx{bool}, \fx{tog}, \fx{choice}, \fx{menu}). ``Choice'' and ``menu'' key types imply the same thing (key type~5): the user can pick the name he prefers. The key and its attributes are separated by commas; they constitute one ``object'' or ``instance''. The objects are separated by the \aang{keyparser}, which is the semicolon in the above example. +4 (toggle-boolean key), and 5 (choice/menu key). The key types can be indicated either in numeral format (\fx{1}~to~\fx{5}) or in alphabetic format (\fx{ord}, \fx{cmd}, \fx{bool}, \fx{tog}, \fx{choice}, \fx{menu}). ``Choice'' and ``menu'' key types imply the same thing (key type~5): the user can pick the name he prefers. The key and its attributes are separated by commas; they constitute one ``object'' or ``instance''. The objects are separated by the \aang{keyparser}, which is the semicolon in the above example. If the key list is available in a macro, say, \begin{example} @@ -518,9 +569,9 @@ is being defined via \fx{\define@keylist}. Its syntax is \choicekeyvalues|redstar[|cang(prefix)][|cang(family)]{|cang(key)}{|cang(list)}, \end{macro} where \aang{list} is a comma-separated list of admissible key values. Unless the key prefix or family changes, the unstarred variant of \fx{\choicekeyvalues} wouldn't allow you to set two \fx{\choicekeyvalues} for the same choice key. The starred variant \fx{\choicekeyvalues}\unskip\redstar, on the other hand, allows you to overwrite admissible choice values for a key within a specified family and with the given key prefix. The arguments \aang{prefix} and \aang{family} are optional, provided the key prefix and family have been specified before calling \fx{\choicekeyvalues}, using \fx{\skvoptions}. If \aang{prefix} and \aang{family} are not given, the prevailing key prefix and key family are used internally by \fx{\choicekeyvalues} to build distinct alternate values list for the choice key. Therefore, any number of choice keys are allowed to appear in one \acmd{\define@keylist} or \acmd{\define@keylist}\unskip\redstar\ statement, if their lists of alternate/admissible values have been set by \fx{\choicekeyvalues}. -It doesn't matter which choice key first gets a \fx{\choicekeyvalues}. +It doesn't matter which choice key first gets a \fx{\choicekeyvalues}. -To further save tokens, the macro \fx{\choicekeyvalues} may be abbreviated by \acmdm{\CKVS}. It has to be provided for each choice key that is being defined. +To further save tokens, the macro \fx{\choicekeyvalues} may be abbreviated by \acmdm{\CKVS}. It has to be provided for each choice key that is being defined. For example, if we want to define two choice keys \fx{align} and \fx{shootingmodes}, then before the call to \acmd{\define@keylist}, we have to set \begin{example} @@ -549,7 +600,6 @@ Suppose that the key family and other attributes have been set as \end{example} \acmd*{\skvoptions} Further, suppose we wish to define a set of keys \fx{{color,angle,scale,align}}. The key \fx{color} will be defined as ordinary key, the keys \fx{angle} and \fx{scale} will de defined as command keys, while the key \fx{align} will be defined as a choice key. Assume that the \fx{align} key can only assume one of the values \leftbrace\fx{center} \amdvert\ \fx{right} \amdvert\ \fx{left} \amdvert\ \fx{justified}\rightbrace, where the first three values would further imply \fx{\centering}, \fx{\flushright}, and \fx{\flushleft}, respectively. Moreover, we assume that the key \fx{scale} will be associated with a macro called \fx{\mydo}, which depends on a previously defined macro \fx{\do}. Together with \fx{align}, we would also like to define another choice key: \fx{weather}. The key \fx{color} isn't associated with any macro. Then we can do: -\acmd*{\CKVS} \begin{example} |comm(We use space freely in these examples for the sake) |comm(of illustration:) @@ -579,6 +629,7 @@ Further, suppose we wish to define a set of keys \fx{{color,angle,scale,align}}. } \setkeys[KV]{fam}{angle=45,scale=1cm,weather=cloudy} \end{example} +\acmd*{\CKVS} Note the number of parameter characters in the definition of \fx{\mydo}. We will return to this matter in \cref{sec:macros-in-keymacros}. The \acmdm{\nr} and \acmdm{\val} macros are bin parameters for choice keys, as defined by the \pkg{xkeyval}. \fx{\val} contains the user input for the current key and \fx{\nr} contains the numeral corresponding to the numerical order of the user input in the \acmd{\CKVS} list, starting from~0 (zero). For example, in the \fx{\CKVS{align}} list, the \fx{\nr} values are \fx{center}~(0), \fx{right}~(1), \fx{left}~(2), and \fx{justified}~(3). These parameters thus refresh with the choice key and its user-supplied value. @@ -623,7 +674,7 @@ Hundreds of keys can be defined efficiently in this way, using very few tokens. cmd,textheight,\textheight,\funcfortextheight; cmd,textwidth,\textwidth,\funcfortextwidth; ord,evensidemargin,\evensidemargin,; - tog,togvar,true,\iftog{mp@togvar}{\def\catch####1{####1}}% + tog,togvar,true,\iftogon{mp@togvar}{\def\catch####1{####1}}% {\def\gobble####1{}}; choice,align,center,\funcforalign; choice,election,congress,\def\electiontype{##1}; @@ -645,7 +696,7 @@ The same set of keys can be defined via the starred form of \acmd{\define@keylis cmd,textheight,\textheight,\funcfortextheight; cmd,textwidth,\textwidth,\funcfortextwidth; ord,evensidemargin,\evensidemargin,; - tog,togvar,true,\iftog{mp@togvar}{\def\catch####1{####1}}% + tog,togvar,true,\iftogon{mp@togvar}{\def\catch####1{####1}}% {\def\gobble####1{}}; choice,align,center,\funcforalign; choice,election,congress,\def\electiontype{##1}; @@ -688,7 +739,7 @@ Instead of using macros to pass key macros and functions, it is also possible to \expandafter\expandafter\expandafter{\expandafter##1% \expandafter}\expandafter{##2}}}\fi} -\temptoksb{\iftog{mp@toga}{\def\order#1{Use `#1' now!}}% +\temptoksb{\iftogon{mp@toga}{\def\order#1{Use `#1' now!}}% {\def\altorder#1{Don't use `#1' now!}}} \define@keylist{3,boola,true,\the\temptoksa; @@ -711,7 +762,7 @@ The examples in \cref{sec:multkeys-examples} would have provided some glimpse of \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}. \begin{example} \define@keylist{% - tog,toga,true,\iftog{mp@toga}{% + tog,toga,true,\iftogon{mp@toga}{% \def\swear####1{Repeat after me: `####1'!}% }{% \let\swear\@gobble @@ -804,7 +855,7 @@ The examples in \cref{sec:multkeys-examples} would have provided some glimpse of \def#1##1##2{\expandafter\expandafter\expandafter\in@ \expandafter\expandafter\expandafter{\expandafter##1% \expandafter}\expandafter{##2}}}\fi} -\temptoksb{\iftog{mp@togb}{\def\tempa#1{Use #1}}% +\temptoksb{\iftogon{mp@togb}{\def\tempa#1{Use #1}}% {\def\tempb#1{Don't use #1}}} \define@keylist{3,boolc,true,\the\temptoksa; 4,togb,true,\the\temptoksb} @@ -823,39 +874,61 @@ The examples in \cref{sec:multkeys-examples} would have provided some glimpse of \setkeys[KV]{fam}{boold=true} \end{example} -\subsection{The keycommand interface} +\subsection{Key commands} \label{sec:keycommand} \acmdm*{keycommand} -The \fx{\define@keylist} macro provides an interface for defining commands in the manner of the \pkg{keycommand}. We haven't developed this interface well enough but the following example shows what is currently obtainable and the possibilities for future enhancements. It is hoped that further work in this direction will be undertaken in the future. I do foresee that the user interface will be made lighter in the future. For now, the \fx{\skvoptions} command needs be reissued only when the key family changes, and in that case we simply have to do \fx{\skvoptions{keyfamily=name}}. Any future enhancement should seek to hide the \fx{\setkeys} command from the user. +The \fx{\define@keylist} macro provides an interface for defining commands using keys, in the manner of the \pkg{keycommand}, but the user interfaces differ between here and the \pkg{keycommand}. Our interface for introducing new key commands is as follows +\begin{macro} +\DeclareKeyCommand|redstar|cang(cmd)[|cang(keyval)][|cang(narg)]{|cang(content)} +\end{macro} +\acmdm*{\DeclareKeyCommand} +Here, \aang{cmd} is the new key command being declared, \aang{keyval} are the default key-value pairs, and \aang{narg} is the number of arguments in \aang{content} plus one. The quantity \aang{narg} has nothing to do with the number of admissible keys, and may also have no relation to the keys themselves. The first argument (\ie, \angledhash{1}) is the \aang{keyval} pairs: this is the reason why in \aang{narg} you have to add one to your number of arguments. In \aang{content} (\ie, the replacement text) the parameter number one \angledhash{1} refers to the \aang{keyval} pairs. You refer to your arguments using parameter number two \angledhash{2} onwards, up to a maximum of \angledhash{9}. This means that \fx{\DeclareKeyCommand} accepts no optional arguments. This is not a limitation, since optional arguments can be entered as keys. Using keys is preferable to using parameters: you don't have to match parameters to arguments and, in principle, there is no limit to the number of keys that are permissible. + +The unstarred variant of \fx{\DeclareKeyCommand} gives long macros, as is usual in \latex. + +In \aang{content}, you refer to the values of the keys using macros whose first three characters (after the escape character) are the first three letters of the declared key command. The fourth character of the key-value macros is the ``at'' sign (\fx{@}), which should have catcode 11. The family name of the keys defined via a key command is the key command name itself (without the escape character). The key prefix is always ``KV''. The ``at'' sign only serves to visually aid the separation of the macro prefix from the key name and may be deprecated in future versions of the package. + +The following examples illustrate these points: \begin{example} -\skvoptions{keyparser=;,macroprefix=mp,keyprefix=KV, - keyfamily=rule} -\define@keylist{cmd,raise,.5ex,;cmd,width,1em,; - cmd,thick,.4pt,;bool,proclaim,true,} -\setkeys[KV]{rule}{raise,width,thick,proclaim=false} -\newcommand*\Rule[2][Hello]{% - \setkeys[KV]{rule}{#2}% - \rule[\mpraise]{\mpwidth}{\mpthick}% - #1% - \rule[\mpraise]{\mpwidth}{\mpthick}\hspace*{1em}% - \ifmpproclaim \color{red}\fi\textdaggerdbl +|makered(\DeclareKeyCommand*)\demomacro[name=Dummy,height=1.6m, + wieght=60kg,employed=false][3]{% + \edef\x{\dem@name}\def\y{#2}\def\z{#3}} + +|comm(Instruct the user to supply value of `name' in) +|comm(\demomacro key command:) +\uservaluekeys[KV]{demomacro}{name} + +|comm(Now you can use \demomacro. If you don't supply a key value) +|comm(here, the macro will use the above defaults:) +\demomacro[name=John,height=1.55m,wieght=55kg,employed=true] + {data1}{data2} + +|makered(\DeclareKeyCommand)\Rule[raise=.5ex,width=1em,thick=2pt, + proclaim=false][2]{\rule[\Rul@raise]{\Rul@width}{\Rul@thick}% + #2% + \rule[\Rul@raise]{\Rul@width}{\Rul@thick}\hspace*{1em}% + \ifRul@proclaim \color{red}\fi\textdaggerdbl } + |makered(\begin{document}) \parindent\z@ \begin{tabular*}\textwidth{rr} -\verb+\Rule[width=2em]{hello}+:|ampersand - \Rule[Hello World]{width=2em,proclaim}\cr -\verb+\Rule[thick=1pt,width=2em]{hello}+:|ampersand - \Rule{thick=2pt,width=2em}\cr -\verb+\Rule{hello}+:|ampersand - \Rule[Hello World]{proclaim}\cr -\verb+\Rule[thick=1pt,raise=1ex]{hello}+:|ampersand - \Rule[Hello World]{thick=1pt,raise=1ex} +\verb+\Rule[width=2em,thick=4pt]{Hello World}+:|ampersand + \Rule[width=2em,thick=4pt]{Hello World}\cr +\verb+\Rule[width=2em,thick=.5pt,proclaim=true]{Hello}+:|ampersand + \Rule[width=2em,thick=.5pt,proclaim=true]{Hello}\cr +\verb+\Rule[thick=2pt,proclaim=true]{Hello World}+:|ampersand + \Rule[thick=2pt,proclaim=true]{Hello World}\cr +\verb+\Rule[raise=1ex,width=2em,thick=1pt]{Hello World}+:|ampersand + \Rule[raise=1ex,width=2em,thick=1pt]{Hello} \end{tabular*} |makered(\end{document}) \end{example} +\acmd*{\begin\{document\}} + +The corresponding \fx{\DeclareKeyEnviron} easily follows. \subsection{Input error} \label{sec:input-error} @@ -917,7 +990,7 @@ Token list registers can be used here economically instead of macros. Below we d \expandafter\expandafter\expandafter{\expandafter##1% \expandafter}\expandafter{##2}}}\fi} -\temptoksb{\iftog{mp@toga}{\def\order#1{Use `#1' now!}}{}} +\temptoksb{\iftogon{mp@toga}{\def\order#1{Use `#1' now!}}{}} \define@keylist{3,boola,true,\the\temptoksa; 4,toga,true,\the\temptoksb} @@ -953,11 +1026,11 @@ where the key prefix \fx{KV}, key family \fx{fam}, and the macro prefix \fx{mp@} \end{example} \acmdm*{\skif,\skifx,\skelse,\skfi} \acmd*{\skifcase,\skor,\define@keylist} -Here we have used \fx{\skif{mp@mybool}}, \fx{\skifx}, \fx{\skelse} and \fx{\skfi} for the commands \fx{\ifmp@mybool}, \fx{\ifx}, \fx{\else} and \fx{\fi}, respectively, to hide the latter four from \TeX's scanning and skipping mechanism. It should be noted that \fx{\skif{mp@mybool}} requires that the argument \aang{mp@mybool} be enclosed in braces. Something like \fx{\skifmp@mybool} will be interpreted by \tex as an undefined control sequence when the key \fx{mybool} is being set. Defining the command \fx{\skif{mp@mybool}} to be \fx{\ifmp@mybool} before hand would have failed because \tex's scanner would then get the hint of the assignment. +Here we have used the pseudo-primitives \fx{\skif{mp@mybool}}, \fx{\skifx}, \fx{\skelse} and \fx{\skfi} for the commands \fx{\ifmp@mybool}, \fx{\ifx}, \fx{\else} and \fx{\fi}, respectively, to hide the latter four from \TeX's scanning and skipping mechanism. It should be noted that \fx{\skif{mp@mybool}} requires that the argument \aang{mp@mybool} be enclosed in braces. Something like \fx{\skifmp@mybool} will be interpreted by \tex as an undefined control sequence when the key \fx{mybool} is being set. Defining the command \fx{\skif{mp@mybool}} to be \fx{\ifmp@mybool} before hand would have failed because \tex's scanner would then get the hint of the assignment. -\Note We haven't found any package that has defined \fx{\skif}, \fx{\skifx}, \fx{\skelse}, \fx{\skfi}, \fx{\skifcase} or \fx{\skor}. The \pkgm{xifthen} uses \fx{\OR}, not \fx{\skor}. If the situation changes in the future (\ie, if a package is observed to have defined any of these commands), they will be appropriately modified in the \pkg{skeyval}. Information and feedback from package users is solicited in this regard. +\Note We haven't found any package that has defined \fx{\skif}, \fx{\skifx}, \fx{\skelse}, \fx{\skfi}, \fx{\skifcase} or \fx{\skor}. The \pkgm{xifthen}, for example, uses \fx{\OR}, not \fx{\skor}. If the situation changes in the future (\ie, if a package is observed to have defined any of these commands), they will be appropriately modified in the \pkg{skeyval}. Information and feedback from package users is solicited in this regard. -We have redefined the \fx{\setkeys} command of the \pkg{xkeyval} to recognize that \fx{\skif{boolean}}, \fx{\skifx}, \fx{\skelse}, \fx{\skfi}, \fx{\skifcase} and \fx{\skor} stand for \fx{\ifboolean}, \fx{\ifx}, \fx{\else}, \fx{\fi}, \fx{\ifcase} and \fx{\or}, respectively. The redefined \fx{\setkeys} command has the same syntax as as in \pkg{xkeyval}: +We have redefined the \fx{\setkeys} command of the \pkg{xkeyval} to recognize that \fx{\skif{boolean}}, \fx{\skifx}, \fx{\skelse}, \fx{\skfi}, \fx{\skifcase} and \fx{\skor} stand for \fx{\ifboolean}, \fx{\ifx}, \fx{\else}, \fx{\fi}, \fx{\ifcase} and \fx{\or}, respectively. The redefined \fx{\setkeys} command has the same syntaxes as as in \pkg{xkeyval}: \begin{macro} \setkeys[|cang(prefix)]{|cang(families)}[|cang(na)]{|cang(keys=values)} \setkeys|redstar[|cang(prefix)]{|cang(families)}[|cang(na)]{|cang(keys=values)} @@ -995,24 +1068,37 @@ The key \fx{focus} can now be readily set: \fx{\setkeys[KV]{fam}{focus=left}}. \subsubsection[Using switches]{Using switches to submit the conditionals} \label{sec:switches} -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 a different semantics. +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: + \begin{macro} -\newswitch{|cang(switch)}{|cang(value/state)} +\newswitch[|cang(optional prefix)]{|cang(boolean)}[|cang(optional state)] \end{macro} -There should be no \fx{\if} in \aang{switch} when using \fx{\newswitch}. Valid values/states of switches are `true' (or `on') and `false' (or `off'). With this definition you can issue \fx{\if}\unskip\aang{switch}, \bs\aang{switch}\unskip\fx{true}, and \bs\aang{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} +This provides a new native-boolean register \fx{\if}\unskip\aang{prefix}\unskip\aang{boolean} if the register didn't already exist; if the register already existed, an error is flagged. The optional \aang{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\aang{switch}, \bs\aang{switch}\unskip\fx{true}, and \bs\aang{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 + +\newswitch[bool]{b}[true] |tto \newif\ifboolb \boolbtrue + +\newswitch[bool]{c}[on] |tto \newif\ifboolc \boolctrue + +\newswitch[bool]{d}[off] |tto \newif\ifboold \booldfalse +\end{example} You can define many switches in a row by the following command: \begin{macro} \NewSwitches[|cang(optional prefix)]{|cang(switches)}[|cang(optional state)] \end{macro} -Each member of \aang{switches} is prefixed with \aang{prefix} upon definition. The optional \aang{state} can be either \fx{true} or \fx{false}. +\acmdm*{\NewSwitches} +Each member of \aang{switches} is prefixed with \aang{prefix} upon definition. The optional \aang{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} +\NewSwitches{x,y,z}[off] |tto \newswitch{x}{false} \newswitch{y}{false} \newswitch{z}{false} @@ -1040,7 +1126,7 @@ Switches may be set and tested using the following commands: \ifswitchfalse{|cang(switch)}{|cang(not true)}{|cang(not false)} \end{macro} -\acmdm*{\newswitch,\NewSwitches,\setswitch,\switchon,\switchoff,\ifswitchon, +\acmdm*{\newswitch,\setswitch,\switchon,\switchoff,\ifswitchon, \ifswitchoff,\switchtrue,\switchfalse,\ifswitchtrue, \ifswitchfalse} @@ -1057,16 +1143,23 @@ Switches may be set and tested using the following commands: \ifswitchoff{y}{\def\yy{Off}}{\def\yy{On}} \end{example} -Suppose the key prefix is \fx{KV}, the key family is \fx{fam}, and the key macro is \fx{mp@}. The the following works: +\begin{macro} +\defswitch[|cang(optional prefix)]{|cang(boolean)}[|cang(optional state)] +\end{macro} +\acmdm*{\defswitch} +This is similar to \fx{\newswitch} but raises no errors even if the register \aang{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,switcha,true, - |makered(\ifswitchon){mp@switcha}{\def\say{Swtich `a' is true}} +\define@keylist{3,swa,true, + |makered(\ifswitchon){mp@swa}{\def\say{Swtich `a' is true}} {\def\say{Swtich `a' is false}}} -\setkeys[KV]{fam}{switcha=true |makered(or) false} +\setkeys[KV]{fam}{swa=true |makered(or) false |makered(or) on |makered(or) off} \end{example} +\acmd*{\define@keylist} -\Note Please note that switch keys are boolean keys (type~`3' key). As yet, when setting switch keys you must supply either \fx{true} or \fx{false}, not \fx{on} or \fx{off}. +\Note Please note that ``switch keys'' are actually native-boolean keys (\fx{bool} or type~\fx{3} key). When setting native-boolean and toggle-boolean keys you can supply either \fx{true}, \fx{false}, \fx{on} or \fx{off} as values. We have modified the relevant internal macros of the \pkg{xkeyval} to make this possible for the native-boolean keys as well. \subsubsection[Using toggles]{Using toggles to submit the conditionals} \label{sec:using-toggles} @@ -1074,12 +1167,12 @@ Suppose the key prefix is \fx{KV}, the key family is \fx{fam}, and the key macro Toggle booleans, described in \cref{sec:toggles}, can also be used to circumvent the problem of matching \fx{\if} and \fx{\fi} in difficult circumstances, since toggles aren't \tex primitives, and, as noted in \cref{sec:toggles}, toggles are very economical. For example, the following works: \begin{example} \define@keylist{4,toga,true, - |makered(\iftog){mp@toga}{\def\say{Toggle `a' is true}}% + |makered(\iftogon){mp@toga}{\def\say{Toggle `a' is true}}% {\def\say{Toggle `a' is false}}} \setkeys[KV]{fam}{toga= true |makered(or) false} \end{example} -\acmd*{\define@keylist,\iftog} +\acmd*{\define@keylist,\iftogon} where the key prefix, key family, and macro prefix are still assumed to be \fx{KV}, \fx{fam}, \fx{mp@}, respectively. Recall that toggle keys are type~`4' keys. \section{Checking and redefining keys} @@ -1431,12 +1524,12 @@ Instead of using the macro \fx{\uservaluekeys} to accumulate user-value keys, th \define@togkey|redplus[KV]{fam}[mp@]{|makered(\guservalue{|makemac(toga)})}[true]% {% - \iftog{mp@toga}{\def\x{#1}}{}% + \iftogon{mp@toga}{\def\x{#1}}{}% }{% \@latex@error{Value `#1' not valid}\@ehc } \end{example} -\acmd*{\newordkey,\define@togkey,\iftog} +\acmd*{\newordkey,\define@togkey,\iftogon} As these examples show, the newly introduced pointers (namely, \fx{\uservalue} and \fx{\guservalue}) can be used to dynamically build a list of user-value keys. See \cref{sec:pointer-mech} for more comments on pointer systems. @@ -1492,9 +1585,9 @@ The following provide examples of new pointer features enabled by the \pkg{skeyv \newtogkey|redplus[KV]{fam}[mp@]{|makered(\savevalue\uservalue{|makemac(toga)})}[true]% { - \iftog{mp@toga}{\def\x{#1}}{}% + \iftogon{mp@toga}{\def\x{#1}}{}% }{% - \@latex@error{Value '#1' not valid}\@ehc + \@latex@error{Value `#1' not valid}\@ehc } \define@cmdkey[KV]{fam}[mp@]{|makered(\uservalue\savevalue{|makemac(keyc)})}% @@ -1504,7 +1597,7 @@ The following provide examples of new pointer features enabled by the \pkg{skeyv [true]{% \ifmp@boola\def\x{#1}\fi }{% - \@latex@error{Value '#1' not valid}\@ehc + \@latex@error{Value `#1' not valid}\@ehc } \define@cmdkey[KV]{fam}[mp@]{|makered(\guservalue\savevalue{|makemac(keyd)})}% @@ -1527,7 +1620,7 @@ The following provide examples of new pointer features enabled by the \pkg{skeyv \setkeys[KV]{fam}{keya=Hello World,keyb=|makered(\usevalue{|makemac(keya)})} \end{example} \acmd*{\define@key,\define@cmdkey,\newchoicekey,\newordkey, -\newtogkey,\setkeys,\iftog} +\newtogkey,\setkeys,\iftogon} With the new mechanism of the \pkg{skeyval}, the \acmd{\gsavevalue} pointer in the command on \macref{mac:pointers:a} will ensure that \fx{\global{keyb}} (not \fx{keyb}) is inserted in the container \fx{\XKV@KV@fam@save} and that this container is updated globally after \fx{\global{keyb}} has been inserted. At \acmd{\setkeys}, in view of the entry \fx{\global{keyb}}, the value of \fx{keyb} will be saved globally. The same applies to keys \fx{boola} and \fx{align}. This thus has a double effect. Keys \fx{keyc} and \fx{keyd} will be saved locally. @@ -1619,16 +1712,16 @@ This can be used to test whether or not one is using the \fx{\newdef} (or any ot New definable variables can be introduced in sets by the following commands. \begin{macro} -\NewIfs[|cang(optional prefix)]{|cang(boolean list)}[|cang(optional state)] +\NewBooleans[|cang(optional prefix)]{|cang(boolean list)}[|cang(optional state)] \end{macro} -\acmdm*{\NewIfs} -This provides, for each member of the comma-separated list \bang{boolean list}, a new native-boolean register if the register didn't already exist, otherwise an error is flagged. Each member of \bang{boolean list} is prefixed with \aang{prefix} upon definition. The optional \aang{state} can be either \fx{true} or \fx{false}. +\acmdm*{\NewBooleans} +This provides, for each member of the comma-separated list \bang{boolean list}, a new native-boolean register if the register didn't already exist, otherwise an error is flagged. Each member of \bang{boolean list} is prefixed with \aang{prefix} upon definition. The optional \aang{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}. \begin{example} -\NewIfs[bool]{a,b,c}[true] +\NewBooleans[bool]{a,b,c}[true] |tto \newif\ifboola \newif\ifboolb \newif\ifboolc \boolatrue \boolbtrue \boolctrue -\NewIfs{boold} |tto \newif\ifboold +\NewBooleans{boold} |tto \newif\ifboold \end{example} Notice that members of the list \bang{boolean list} don't have \fx{\if} in their names. @@ -1636,11 +1729,11 @@ Notice that members of the list \bang{boolean list} don't have \fx{\if} in their \NewTogs[|cang(optional prefix)]{|cang(tog list)}[|cang(optional state)] \end{macro} \acmdm*{\NewTogs} -This provides a new toggle register for each member of the comma-separated list \bang{tog list} if the register didn't already exist, otherwise an error is flagged. Each member of \bang{tog list} is prefixed with \aang{prefix} upon definition. The optional \aang{state} can be either \fx{true} or \fx{false}. +This provides a new toggle register for each member of the comma-separated list \bang{tog list} if the register didn't already exist, otherwise an error is flagged. Each member of \bang{tog list} is prefixed with \aang{prefix} upon definition. The optional \aang{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}. \begin{example} \NewTogs[tog]{a,b,c}[true] |tto \newtog{toga} \newtog{togb} \newtog{togc} - \togtrue{toga} \togtrue{togb} \togtrue{togc} + \togon{toga} \togon{togb} \togon{togc} \NewTogs{togd} |tto \newtog{togd} \end{example} @@ -1694,7 +1787,7 @@ This allocates a new output stream for each member of the comma-separated list \ \NewWrites{writed} |tto \newwrite\writed \end{example} -All the macros \fx{\NewIfs}, \fx{\NewToks}, \fx{\NewCounts}, \fx{\NewDimens}, \fx{\NewBoxes}, and \fx{\NewWrites} are non-outer, unlike their primitive counterparts. +The macros \fx{\NewBooleans}, \fx{\NewToks}, \fx{\NewCounts}, \fx{\NewDimens}, \fx{\NewBoxes}, and \fx{\NewWrites} are non-outer, unlike their primitive counterparts. \macrosection{Defining new names} @@ -1705,9 +1798,7 @@ All the macros \fx{\NewIfs}, \fx{\NewToks}, \fx{\NewCounts}, \fx{\NewDimens}, \f \SKV@csxdef|redplus{|cang(name)}{|cang(definition)} \end{macro} \acmdm*{\SKV@csdef,\SKV@csgdef,\SKV@csedef,\SKV@csxdef} -The unsigned variants of these turn \aang{name} into a control sequence in terms of \aang{definition} whether or not the control was already defined. No error or warning messages are issued. The plus (\RedPlus) variants turn \aang{name} into a control sequence if it wasn't already defined; if it is already defined, an error message is flagged. These derive from a concept based on that of \acmd{\newcommand}, but (i)~\relaxed\ commands are considered undefined in this regard, and (ii)~these commands retain the powerful machinery of plain \tex. - -\Note The \pkg{skeyval} contains other undocumented tools for defining new commands. +The unsigned variants of these turn \aang{name} into a control sequence in terms of \aang{definition} whether or not the control was already defined. No error or warning messages are issued. The plus (\RedPlus) variants turn \aang{name} into a control sequence if it wasn't already defined; if it is already defined, an error message is flagged. These derive from a concept based on that of \acmd{\newcommand}, but (i)~\relaxed\ commands are considered undefined in this regard, and (ii)~these commands retain the powerful machinery of plain \tex.\footnote{The \pkg{skeyval} contains other undocumented tools for defining new commands.} \macrosection{Name use} @@ -1762,6 +1853,7 @@ The plus sign (\RedPlus) means that \fx{\SKV@dimdef} takes a control sequence na \begin{macro} \SKV@ifdefinable|cang(cs){|cang(function)} +\SKV@csifdefinable|cang(cs name){|cang(function)} \end{macro} \acmdm*{\SKV@ifdefinable} \latex kernel's \fx{\@ifdefinable} fills up the hash table and also considers commands that are \fx{\relax}'ed as defined. Moreover, if the command being tested (\aang{cs} in the above example) is definable, the \fx{\@ifdefinable} macro begins executing \aang{function} while still in the \fx{\if} \textellipsis \fx{\fi} conditional. You can't do \fx{\let\ifabc\iftrue} in such conditionals. The command \fx{\SKV@ifdefinable}, which is robust, seeks to avoid these problems. @@ -1895,7 +1987,7 @@ This is similar to \fx{\SKV@exptx} but accepts control sequence name \aang{name} \item If \aang{n} is 1, then both \aang{arg1} and \aang{arg2} are nonempty but only \aang{arg2} will be expanded before \aang{function} is executed. \item When \aang{n} is 2, then both \aang{arg1} and \aang{arg2} are nonempty and both will be expanded before \aang{function} is executed. This is equivalent to \LaTeX's \fx{\@expandtwoargs}. \item If \aang{n} is 3, then both \aang{arg1} and \aang{arg2} are nonempty but only \aang{arg1} is expanded before \aang{function} is executed. -\item If \aang{n} isn't in the list \sx{0,1,2,3}, then an error message is flagged. +\item If \aang{n} isn't in the list \hv{0,1,2,3}, then an error message is flagged. \end{enum} Because \aang{arg2} is delimited, it can be empty. The command \fx{\SKV@expargs} can be used to save \fx{\expandafter}'s, but caution should be exercised in deploying it: for example, the \fx{\edef} it uses may expand too deeply in some cases. Also, precaution may be necessary when the expanded arguments (\aang{arg1} and/or \aang{arg2}) involve the \tex primitive \fx{\if}. When invoking \fx{\SKV@expargs}, the macros \fx{\SKV@expox} and \fx{\SKV@exptx} can be used to control the level of expansion. @@ -1949,28 +2041,34 @@ The reader may wish to do \fx{\show\tempa} to see what \fx{\tempa} gets upon set \SKV@in@{|cang(substring)}{|cang(string)} \end{macro} \acmdm*{\SKV@in@} -This is similar to the \latex kernel's \sz{\in@}{substring}{string} which tests if \aang{substring} is in \aang{string}, but the present test avoids the problem of false result, which is typified by the following test: +This is similar to the \latex kernel's \hy{\in@}{substring}{string} which tests if \aang{substring} is in \aang{string}, but the present test avoids the problem of false result, which is typified by the following test: \begin{example} \in@{aa}{ababba} \end{example} This incorrectly returns \acmdm{\ifin@} as \fx{\iftrue}. The macro \fx{\SKV@in@}, on the other hand, correctly gives \fx{\ifin@} as \fx{\iffalse} in this case. The command \fx{\SKV@in@} is robust. \begin{macro} +\SKV@in@o{|cang(substring)}{|cang(string)}{|cang(true text)}{|cang(false text)} +\end{macro} +\acmdm*{\SKV@in@o} +This is similar to \fx{\SKV@in@} but the returned result has a different syntax. + +\begin{macro} \in@tog{|cang(substring)}{|cang(string)} \end{macro} \acmdm*{\in@tog} In this case the returned boolean is the toggle switch \aang{in@} instead of the kernel's \aang{in@} switch which is used as \fx{\ifin@}. The toggle \aang{in@} can be used in the following way and in other manners that toggles can be employed: \begin{example} -\iftog{in@}{|cang(true)}{|cang(false)}. +\iftogon{in@}{|cang(true text)}{|cang(false text)}. \end{example} -\acmd*{\iftog} +\acmd*{\iftogon} The command \fx{\in@tog} is robust. \begin{macro} \in@tok{|cang(substring)}{|cang(string)} \end{macro} \acmdm*{\in@tok} -Sometimes you want to use the \latex kernel's \sz{\in@}{substring}{string} to test if \aang{substring} is in \aang{string} irrespective of their catcodes. The robust command \sz{\in@tok}{substring}{string} makes this possible, and eliminates the tokens that would have been necessary if the user was required to first detokenize the two arguments. It returns the same switch \fx{\ifin@} as the kernel's \sz{\in@}{substring}{string}. Actually, it calls \fx{\SKV@in@} to avoid false returns. +Sometimes you want to use the \latex kernel's \hy{\in@}{substring}{string} to test if \aang{substring} is in \aang{string} irrespective of their catcodes. The robust command \hy{\in@tok}{substring}{string} makes this possible, and eliminates the tokens that would have been necessary if the user was required to first detokenize the two arguments. It returns the same switch \fx{\ifin@} as the kernel's \hy{\in@}{substring}{string}. Actually, it calls \fx{\SKV@in@} to avoid false returns. \macrosection{Testing equality of strings} @@ -2011,15 +2109,15 @@ These macros test if the argument is blank or not. The first of these is from \p \SKV@ifnotdraft{|cang(not true)}{|cang(not false)} \SKV@iffinal{|cang(true)}{|cang(false)} \SKV@ifnotfinal{|cang(not true)}{|cang(not false)} -\iftog{draft}{|cang(true)}{|cang(false)} -\ifnottog{draft}{|cang(not true)}{|cang(not false)} -\iftog{final}{|cang(true)}{|cang(false)} -\ifnottog{final}{|cang(not true)}{|cang(not false)} +\iftogon{draft}{|cang(true)}{|cang(false)} +\iftogoff{draft}{|cang(not true)}{|cang(not false)} +\iftogon{final}{|cang(true)}{|cang(false)} +\iftogoff{final}{|cang(not true)}{|cang(not false)} \end{macro} -\acmdm*{\SKV@ifdraft,\SKV@ifnotdraft,\SKV@iffinal,\SKV@ifnotfinal,\iftog\{draft\}, -\ifnottog\{draft\},\iftog\{final\},\ifnottog\{final\}} +\acmdm*{\SKV@ifdraft,\SKV@ifnotdraft,\SKV@iffinal,\SKV@ifnotfinal,\iftogon\{draft\}, +\iftogoff\{draft\},\iftogon\{final\},\iftogoff\{final\}} -These execute \aang{true} or \aang{false} depending on whether \fx{draft} or \fx{final} appears as \fx{true} in the options list of \acmd{\documentclass} or \sxx{\usepackage}{skeyval}. +These execute \aang{true} or \aang{false} depending on whether \fx{draft} or \fx{final} appears as \fx{true} in the options list of \acmd{\documentclass} or \hx{\usepackage}{skeyval}. The default is that \fx{final} is true, which implies that \fx{draft} is false by default. The keys \fx{draft} and \fx{final} are complementary native-boolean keys (see \cref{sec:comp-boolkeys}), which reduces the risk of mixing them. These commands are robust. \begin{macro} @@ -2036,10 +2134,10 @@ These are also defined in the \pkg{skeyval}, but because packages such as \pkgm{ \begin{macro} \SKV@ifpdf{|cang(true)}{|cang(false)} \SKV@ifnotpdf{|cang(not true)}{|cang(not false)} -\iftog{pdf}{|cang(true)}{|cang(false)} -\ifnottog{pdf}{|cang(not true)}{|cang(not false)} +\iftogon{pdf}{|cang(true)}{|cang(false)} +\iftogoff{pdf}{|cang(not true)}{|cang(not false)} \end{macro} -\acmdm*{\SKV@ifpdf,\SKV@ifnotpdf,\iftog\{pdf\},\ifnottog\{pdf\}} +\acmdm*{\SKV@ifpdf,\SKV@ifnotpdf,\iftogon\{pdf\},\iftogoff\{pdf\}} These execute \aang{true} or \aang{false} depending on whether \fx{dvi} or \fx{pdf} output is being produced. These commands are robust and may be used in expansion contexts. \begin{macro} @@ -2049,7 +2147,7 @@ These execute \aang{true} or \aang{false} depending on whether \fx{dvi} or \fx{p \acmdm*{\ifpdf,\ifnotpdf} These are available only if they haven't been previously defined by another package. If they existed outside the \pkg{skeyval}, a warning is logged in the transcript log file (if the package option \fx{verbose} is selected), but only once, and the commands are not redefined. In particular, the above \fx{\ifpdf} is available only at \acmd{\AtBeginDocument} and is defined only if it doesn't already exist. The reason is that the popular \pkg{hyperref} loads the \pkg{ifpdf} and the \pkg{ifpdf} will abort if it detects that \fx{\ifpdf} has been defined by a package loaded earlier. -\Note The \fx{\ifpdf} command of the \pkg{ifpdf} is used in the \fx{\if} \ldots \fx{\else} \ldots \fx{\fi} conditional, while the above \fx{\ifpdf} command is used as indicated above. You can use the \acmd{\TestProvidedCommand} macro to check the version of the \fx{\ifpdf} that you are using. +\Note The \fx{\ifpdf} command of the \pkg{ifpdf} is used in the \fx{\if} \ldots \fx{\else} \ldots \fx{\fi} conditional, while the above \fx{\ifpdf} command is used as indicated above. You can use the \acmd{\TestProvidedCommand} macro to check the version of the \fx{\ifpdf} command that you are using. \macrosection{Tests related to package loading} @@ -2100,7 +2198,7 @@ The function \fx{\SKV@onlypackage} may be used to restrict commands to packages \end{macro} \acmdm*{\SKV@aftergroup,\SKV@aftergroup*,\SKV@afterassignment,\SKV@afterassignment*} -\tex's \fx{\aftergroup} and \fx{\afterassignment} don't accept arbitrary code. These commands execute the arbitrary \aang{code} after a group or assignment. The starred variants expand \aang{code} once before the assignment or before exiting the group. These commands don't accumulate the group and assignment counters indefinitely: the counters are initialized after each group or each assignment. +\tex's \fx{\aftergroup} and \fx{\afterassignment} don't accept arbitrary code. The commands \fx{\SKV@aftergroup} and \fx{\SKV@afterassignment} execute the arbitrary \aang{code} after a group or assignment. The starred variants expand \aang{code} once before the assignment or before exiting the group. These commands don't accumulate the group and assignment counters indefinitely: the counters are initialized after each group or each assignment. Some examples follow: \begin{example} @@ -2127,8 +2225,8 @@ Some examples follow: \endgroup \endgroup |makered(\end{document}) - \end{example} +\acmd*{\begin\{document\}} \macrosection{List processing} @@ -2137,13 +2235,13 @@ Some examples follow: \SKV@for@b|cang(listcmd)|cang(cmd){|cang(function)} \end{macro} \acmdm*{\SKV@for@a,\SKV@for@b} -These are fast for-loops that accept general list parsers and allow for list breaks, as well as give the remainder of the list if a break occurs within the list. Elements of \aang{list} are stored in \aang{cmd}, and \aang{function} is executed for each element of \aang{list}. The \aang{list}, which is populated by parser-separated elements, is not expanded before the iteration, but \aang{listcmd} is expanded once before the commencement of the loop. The list parser is dynamically declarable via +These are fast for-loops that accept general list parsers and allow for list breaks, as well as give the remainder of the list if a break occurs within the list. Elements of \aang{list} are stored in \aang{cmd}, and \aang{function} is executed for each element of \aang{list}. \aang{list}, which is populated by parser-separated elements, is not expanded before the iteration; \aang{listcmd}, on the other hand, is expanded once before the commencement of the loop. The list parser is dynamically declarable via \begin{macro} \SKV@CommandGenParser{|cang(parser)} |orr -\skvoptions{genparser=|cang(parser)}, +\skvoptions{genparser=|cang(parser)} \end{macro} \acmdm*{\SKV@CommandGenParser} -Also, these iteration macros use the more powerful \acmd{\SKV@ifblank} to check whether or not \aang{list} is empty or blank. The commands \fx{\SKV@for@a} and \fx{\SKV@for@b} are robust, but in expansion contexts, both \aang{cmd} and \aang{function} will need to be protected. In the \fx{\SKV@for@b} command, \aang{listcmd} is expanded once before the iteration commences. The \aang{parser} persists in effect until it is changed by another call to \fx{\SKV@CommandGenParser} or \acmd{\skvoptions} as above. +Also, these iteration macros use the more powerful \acmd{\SKV@ifblank} to check whether or not \aang{list} is empty or blank. The commands \fx{\SKV@for@a} and \fx{\SKV@for@b} are robust, but in expansion contexts, both \aang{cmd} and \aang{function} will need to be protected. The \aang{parser} persists in effect until it is changed by another call to \fx{\SKV@CommandGenParser} or \acmd{\skvoptions} as above. \Note One snag with a generic list parser like \fx{\SKV@CommandGenParser} is that the user must always remember to call it and set the right parser before beginning an iteration, otherwise there might be unpleasant results, since a previous call to \fx{\SKV@CommandGenParser} might have set a parser that is no longer valid. To obviate this type of situation, the following commands are also provided in the \pkg{skeyval}: \begin{macro} @@ -2329,7 +2427,7 @@ The following change history highlights significant changes that affect user uti \begin{versionhist} \begin{version}{0.1}{2010/01/01} - \item First public release under the name \pkg{keyreader}\xecref + \item First public release under the name \pkg{keyreader}\xsecref \item Introduced complementary native-boolean keys \secref{sec:comp-boolkeys} \item Provided machinery for reading multiple keys of all kinds from just one command \secref{sec:multiplekeys} \end{version} @@ -2347,7 +2445,7 @@ The following change history highlights significant changes that affect user uti \end{version} \begin{version}{0.5}{2010/02/23} - \item Changed the name of the package from \pkg{keyreader} to \pkg{skeyval}\xecref + \item Changed the name of the package from \pkg{keyreader} to \pkg{skeyval}\xsecref \item Introduced the following macros\secref{sec:status-keys} \begin{veritem} \ifkeydefined, \ifkeyreserved, \ifkeysuspended @@ -2363,6 +2461,7 @@ The following change history highlights significant changes that affect user uti \define@biuniboolkeys, \newbiuniboolkeys, \define@biunitogkeys, \newbiunitogkeys \end{veritem} + \acmd*{\newordkey,\newcmdkey,\newboolkey,\newchoicekey,\newtogkey, \define@biboolkeys,\newbiboolkeys,\define@bitogkeys,\newbitogkeys, \define@uniboolkeys,\newuniboolkeys,\define@unitogkeys,\newunitogkeys, @@ -2370,7 +2469,7 @@ The following change history highlights significant changes that affect user uti \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 + \item Redefined a few of \pkg{xkeyval}'s internal macros \xsecref \item Normalization of key-value lists before parsing \secref{sec:list-normal} @@ -2384,6 +2483,7 @@ The following change history highlights significant changes that affect user uti \ReserveMacroPrefixNames, \ReserveMacroPrefixNames|redstar, \ReserveFamilyNames, \ReserveFamilyNames|redstar \end{veritem} + \acmd*{\ReserveKeyPrefixNames,\ReserveMacroPrefixNames,\ReserveFamilyNames, \ReserveKeyPrefixNames*,\ReserveMacroPrefixNames*,\ReserveFamilyNames*} @@ -2396,8 +2496,9 @@ The following change history highlights significant changes that affect user uti \SKV@AfterDocumentEnd, \SKV@onlypreamble, \SKV@onlypackage, \SKV@ifdraft, \SKV@iffinal, \SKV@ifpdf, \@ensurepackageloaded, \InputFileOnce, - \newswitch, etc. + \newswitch, \defswitch, etc. \end{veritem} + \acmd*{\SKV@AtPackageEnd,\SKV@BeforePackageEnd,\SKV@AfterPackageEnd, \SKV@AtDocumentEnd,\SKV@BeforeLastPage,\SKV@AfterLastPage,\InputFileOnce, \SKV@AfterDocumentEnd,\SKV@onlypreamble,\SKV@ifdraft,\SKV@iffinal,\SKV@ifpdf, @@ -2408,13 +2509,23 @@ The following change history highlights significant changes that affect user uti \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} are nested in a class file, gives non-empty \acmdm{\@unusedoptionlist} even if all the options of \acmd{\documentclass} have been used \xecref + \item Corrected a bug in the \pkg{xkeyval} which, if \acmd{\setkeys} are 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} + + \item Replaced the former \acmd{\NewIfs} with \acmd{\NewBooleans} and redefined \fx{\NewIfs} \secref{sec:biboolkeys} + + \item Introduced \acmd{\DeclareKeyCommand} \secref{sec:keycommand} + \end{version} \end{versionhist} \IndexPreamble{Index numbers refer to page numbers.} -\IndexPreambleAlign{\centering} +\IndexPreambleFormat{\centering} \IndexColumns\tw@ \printindex \end{document} |