summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/catoptions
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2011-09-19 23:49:57 +0000
committerKarl Berry <karl@freefriends.org>2011-09-19 23:49:57 +0000
commit68c8eb6d0ad58860c28d19dcfc1f98fbe818512d (patch)
treef4a33a08c7084dd60c1956fa70fc2d2bec4b0e3f /Master/texmf-dist/doc/latex/catoptions
parenta2e40347ce33680ff47dd43b61a93e38559de7e6 (diff)
catoptions (19sep11)
git-svn-id: svn://tug.org/texlive/trunk@24027 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/catoptions')
-rw-r--r--Master/texmf-dist/doc/latex/catoptions/catoptions-guide.pdfbin447426 -> 452170 bytes
-rw-r--r--Master/texmf-dist/doc/latex/catoptions/catoptions-guide.tex138
2 files changed, 88 insertions, 50 deletions
diff --git a/Master/texmf-dist/doc/latex/catoptions/catoptions-guide.pdf b/Master/texmf-dist/doc/latex/catoptions/catoptions-guide.pdf
index 0952cd13491..cb85c28fa4b 100644
--- a/Master/texmf-dist/doc/latex/catoptions/catoptions-guide.pdf
+++ b/Master/texmf-dist/doc/latex/catoptions/catoptions-guide.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/catoptions/catoptions-guide.tex b/Master/texmf-dist/doc/latex/catoptions/catoptions-guide.tex
index 41002076fdb..5037a01e1bb 100644
--- a/Master/texmf-dist/doc/latex/catoptions/catoptions-guide.tex
+++ b/Master/texmf-dist/doc/latex/catoptions/catoptions-guide.tex
@@ -21,14 +21,12 @@
\begin{frontmatter}
\title{The \texttt{\color{blue}catoptions} Package\titleref{t1,t2}}
\titlenotes[t1,t2]{%
- The package is available at \iftogTF{pdf}{\url{\@titleurl}}
- {\url{\@shorttitleurl}}.\sep
+ The package is available at \url{\titleurltext}.\sep
This manual doesn't, as yet, explain all the currently available features and commands of
the \pkg'{catoptions}. This manual continues to evolve, but many of the available functions will appear in the user guide of the forthcoming \pkg'{ltxtools}.
}
-\version{0.2.5}
+\version{0.2.6}
\titleurl{http://www.ctan.org/tex-archive/macros/latex/contrib/catoptions/}
-\shorttitleurl{http://www.ctan.org/}
\author{Ahmed Musa \Email{amusa22@gmail.com}\\Preston, Lancashire, UK}
\def\abstractname{\textsf{Summary}}
@@ -43,7 +41,7 @@
\xwmcolorbox[textalign=justified, outerframecolor=blue, innerframecolor=orange,
width=.985\hsize]{%
This work (\ie, all the files in the \pkg'{catoptions} bundle) may be distributed and/or modified under the conditions of the \lppl, either version~1.3 of this license or any later version.
- 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.
+ The \lppl maintenance status of this software is \quoted{author-maintained}. This software is provided \quoted{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.
\endgraf
\centerline{\makered{\CopyrightYear}}\vspace{-.8\baselineskip}\relax
}
@@ -60,6 +58,16 @@
\lletter{M}{y motivation} for turning to the \pkgg'{pcatcode} was to save myself the trouble of declaring category codes at the beginning of my packages. After spending some time on the \pkgg'{pcatcode}, I discovered I had learnt enough to make changes and additions to some of its macros and functionality. After completing the catcode stuff in the \pkg'{catoptions}, I wanted to pass options to the package. If the package is to be loaded on top of other packages, as intended, then its options parsing scheme should be independent of other packages. But realizing the trouble with passing expandable option values to packages and classes via the \latex kernel's scheme, I decided to implement modifications to the kernel's options parser. Apart from the problem of premature expansion of options and values by the \latex kernel, outer curly braces in option values are lost during parsing. Indeed, the kernel's option parsing scheme doesn't recognize option values indicated with the equality sign.
+\docsection(sec:packageloading){Loading the package}
+
+\deffnote{1}{%
+ The user interfaces of \ffx'{\XDeclareOption, \XExecuteOptions, \XProcessOptions} are similar to those of \hhx'{\DeclareOption, \ExecuteOptions, \ProcessOptions} but they aren't the same. See \amref{sec:options-parse}.
+}
+The \pkg'{catoptions} can be loaded in class and style files and in documents (before or after \hx{\documentclass}) with the options described in \amref{sec:pkg-options}. If the package is loaded before \hx{\documentclass}, it will, by default, use the options parser of the package in place of \latex's options parsing scheme (namely, the more robust commands \ffx'{\XDeclareOption, \XExecuteOptions, \XProcessOptions} in place of \latex's native commands \hhx'{\DeclareOption, \ExecuteOptions, \ProcessOptions})\usefnote{1}. In that case, the legacy commands \hhx'{\DeclareOption, \ExecuteOptions, \ProcessOptions} are aliased to \ffx'{\XDeclareOption, \XExecuteOptions, \XProcessOptions}, respectively. The latter set of commands do immediately recognize that they have to deal with option functions that are based on the kernel's syntax and semantics. This allows expandable options and option values (together with options with spaces in their names) to be passed via \hx{\documentclass}---if \pkg{catoptions} is loaded before \hx{\documentclass}. This also implies that existing packages can use the options parsing scheme of \pkg'{catoptions} without modifying the packages.
+
+However, if after loading \pkg'{catoptions} before \hx{\documentclass} the user still wants to use the legacy commands \hhx'{\DeclareOption, \ExecuteOptions, \ProcessOptions}, the package option \fx{usepox} (see \amref{sec:pkg-options}) can be toggled to \texttt{false}. In this case, option values can't be passed via \hx{\documentclass}. More precisely, option values passed via \hx{\documentclass} are stripped off internally by \pkg{catoptions} so that they may be processed by \hx{\ProcessOptions}.
+
+
\docsection(sec:pkg-options)<Package options>{Package options}
\lletter{T}{he} \pkg'{catoptions} has the options shown in \amref{tab:pkgoptions}. The boolean option \fxim{verbose} instructs the package to enter information onto the log file when some events happen (\eg, when commands are redefined by means of, say, the command \fx{\robust@redef}, which has the same syntax with \tex's legacy \hx{\def}; and when an option from the same family is multiply submitted to, say, \fx{\XExecuteOptions}). This option may be used in the future to provide debugging features for the package.
@@ -81,16 +89,13 @@
\endlastfoot
\fx{verbose} & \hx{false} & The global boolean switch that determines if information should be logged for some tasks in the package.\\\hline
\fx{usepox} & \hx{true} & The boolean switch that determines if the options parser of \pkgg{catoptions} should be used for all options processing of packages loaded after \hx{\documentclass} even if those packages are based on \usecsn{latex2e}'s native options processing scheme.\\\hline
-\fx{kernelifnextchar} & \hx{true} & The boolean option that determines if the package uses \fxim{\ifnextcharTF} or \hxi{\kernel@ifnextchar}; the former is based on an idea of Donald Arseneau, which allows even active characters to appear \quoted{as the next character}, but it is costlier than the latter.\\\hline
\end{tabularx}
-If the \pkg'{catoptions} is loaded before \hx{documentclass}, it will invariably use the options processing mechanism of the package (namely, the more robust commands \ffx'{\XDeclareOption, \XExecuteOptions, \XProcessOptions} in place of \latex's native commands \hhx'{\DeclareOption, \ExecuteOptions, \ProcessOptions})\footnote{The user interfaces of \ffx'{\XDeclareOption, \XExecuteOptions, \XProcessOptions} are similar to those of \hhx'{\DeclareOption, \ExecuteOptions, \ProcessOptions} but they aren't the same. See \amref{sec:options-parse}.}. In that case, the legacy commands \hhx'{\DeclareOption, \ExecuteOptions, \ProcessOptions} are aliased to \ffx'{\XDeclareOption, \XExecuteOptions, \XProcessOptions}, respectively. The latter set of commands do immediately recognize that they have to deal with option functions that are based on the kernel's semantics. This allows expandable options and option values (together with options with spaces in their names) to be passed via \hx{\documentclass}---if \pkg{catoptions} is loaded before \hx{\documentclass}. This also implies that existing packages can use the options parsing scheme of \pkg'{catoptions} without modifying the packages.
+As noted in \amref{sec:packageloading}, if the \pkg'{catoptions} is loaded before \hx{\documentclass} it will invariably use the options processing mechanism of the package. In that case (of the package being loaded before \hx{\documentclass}), the option \fxim{usepox} directs the package to use the \pkg{catoptions}'s options processing scheme for all the packages loaded after \hx{\documentclass}, instead of \latex's native options parsing procedures. This allows \pkg{catoptions}'s options parsing scheme to be used for existing packages loaded after \hx{\documentclass} without modifying the packages.
-The option \fxim{usepox} directs the package to use the \pkg{catoptions}'s options processing scheme for all the packages loaded after \hx{\documentclass}, instead of \latex's native options parsing procedures. This allows \pkg{catoptions}'s options parsing scheme to be used for existing packages loaded after \hx{\documentclass} without modifying the packages.
+Assuming that the options \quotedtt{textstyle} and \quotedtt{name} belong to an existing package (say, \quotedtt{mypackage}) to be loaded later, then the following example demonstrates one feature of the \pkg'{catoptions}, in the case in which the package is loaded before \hx{\documentclass}:
-Assuming that the options \quotedtt{textstyle} and \quotedtt{name} belong to an existing package (say, \quotedtt{mypackage}) to be loaded later, then the following example demonstrates one feature of the \pkg'{catoptions}:
-
-\start{example}[]
+\start{example}[Loading catoptions before \documentclass]
\RequirePackage[verbose, usepox]{catoptions}
\documentclass[textstyle=\ttfamily,name={Mr X\"avier Sanchez},a4paper,
draft,10pt]{article}
@@ -98,6 +103,8 @@ Assuming that the options \quotedtt{textstyle} and \quotedtt{name} belong to an
\finish{example}
\fxim*{\RequirePackage,\usepackage,\documentclass}
+If the \pkg'{catoptions} wasn't loaded before \hx{\documentclass} then the above example would fail, because \latex's option parser can't handle options with values (much less values with expandable tokens).
+
\docsection(sec:saving-catcodes){Saving and restituting category codes}
@@ -114,11 +121,13 @@ There are the following user commands for saving and returning category codes of
\fxim*{\UseNormalCatcodes,\cptpushcatcodes,\cptpopcatcodes,
\cptnormalcatcodes,\cptfutureletsetup,\GetCurrentCatcodeSubset}
-The command \fx{\cptnormalcatcodes} simply resets the category codes of all \otherchars together with those of the space character and \fx{\^^I} and \fx{\^^J} to their standard values. The command \fx{\cptpushcatcodes} pushes the current category codes for restitution later with \fx{\cptpopcatcodes}. The command \fx{\UseNormalCatcodes} works only in packages and does more than one thing: it calls \ffx'{\cptpushcatcodes, \cptnormalcatcodes,\cptfutureletsetup} in that order. At the end of the package, it automatically issues \fx{\cptpopcatcodes} to recover all the category codes earlier pushed. The command \fx{\UseNormalCatcodes} can conveniently be issued at the start of the package and the developer can be assured of access to the standard category codes of all \otherchars together with those of the space character and \fx{\^^I} and \fx{\^^J}. It should be called only once in a package: subsequent calls will have no effect.
+The command \fx{\cptnormalcatcodes} simply resets the category codes of all \otherchars together with those of the space character and \fx{\^^I} and \fx{\^^J} to their standard values. The \hx{\endlinechar} is also reset to its normal value by this command. The command \fx{\cptpushcatcodes} pushes the current category codes for restitution later with \fx{\cptpopcatcodes}.
+
+The command \fx{\UseNormalCatcodes} works only in packages and does more than one thing: it calls \fx{\cptpushcatcodes} (to save the prevailing category codes) and then \fx{\cptnormalcatcodes} (to enforce the standard category codes). At the end of the class file or package, it automatically issues \fx{\cptpopcatcodes} to recover all the category codes earlier pushed. The command \fx{\UseNormalCatcodes} can conveniently be issued at the start of the package and the developer can be assured of access to the standard category codes of all \otherchars together with those of the space character and \fx{\^^I} and \fx{\^^J}. It should be called only once in a package: subsequent calls within the same package will have no effect.
After issuing the command \fx{\GetCurrentCatcodeSubset}, you can do
-\start{example}[]
+\start{example}[\currentcatcodesubset]
\show\currentcatcodesubset
\finish{example}
\fxim*{\currentcatcodesubset}
@@ -130,22 +139,37 @@ to see the current catcode setup. The command \fx{\cptfutureletsetup} is describ
\NeedsTeXFormat{LaTeX2e}[1995/12/01]
\RequirePackage[verbose, usepox]{catoptions}
\UseNormalCatcodes
+|com(At the end of `mypackage' all the category codes pushed by)
+|com(\UseNormalCatcodes will automatically be popped.)
\finish{example}
\dummyfxi*{\UseNormalCatcodes}
-\docsection(sec:future-letting){Future-letting of \headq{other} characters}
+\docsection(sec:future-letting){Future-letting of \headqtd{other} characters}
The command \fx{\cptfutureletsetup} defines canonical control sequences to represent the following characters:
-\start'{example}[Futurelet characters]
-space|R(|textvisiblespace) exclam|R(!) dblquote|R(") hash|R(#) dollar|R($) ampersand|R(|ampersand)
-lrquote|R(') lparen|R(|() rparen|R(|)) star|R(*) plus|R(+) comma|R(,) hyphen|R(-) period|R(.)
-slash|R(/) colon|R(:) semicolon|R(;) less|R(<) equal|R(=) greater|R(>) question|R(?) lbracket|R([)
-rbracket|R(]) hat|R(^) underscore|R(_) lquote|R(`) lbrace|R({) vert|R(|rv) rbrace|R(}) tilde|R(~)
-bslash|R(\)
-\finish{example}
-\dummyfxim*{\cptfutureletsetup}
+$$\vbox{%
+ \def\newvrule{%
+ \ifnum\@tempcnta<\@vpt
+ \global\@tempcnta\numexpr\@tempcnta+1\relax
+ \textcolor{blue}{\vrule}%
+ \fi
+ }%
+ \noindent\everycr{\noalign{\global\@tempcnta\z@}}%
+ \@tempcnta\z@\tabskip=1em
+ \halign{%
+ &\strut#\hfil&\hfil\textcolor{red}{\tt#}\hskip.25em\newvrule\cr
+ space&\textvisiblespace& exclam&!&dblquote&"&hash&\#& dollar&\$&
+ ampersand&\&\cr
+ lquote&`& rquote&'& lparen&(& rparen&)& star&$*$& plus&+\cr
+ comma&,& hyphen&-&period&.&slash&/& colon&:& semicolon&;\cr
+ less&<&greater&>&equal&=& question&?& lbracket&[& rbracket&]\cr
+ hat&\char`\^& underscore&\char`\_& bslash&\char`\\&
+ lbrace&\char`\{& rbrace&\char`\}& vert&|\cr
+ tilde&\char`~\cr
+ }%
+}$$
However, for efficiency reasons, the canonical control sequences will be defined for only the characters (or their names) appearing in the user-supplied list \fx{\declarefutureletset}, whose syntax is
@@ -171,10 +195,10 @@ For instance, with the choices
we have the following commands on hand for testing after \fx{\futurelet}:
-\start+{newmacro}[Futurelet commands]
+\start+{example}[Futurelet commands]
\fl@space \fl@star \fl@lbracket
\iffl@space \iffl@star \iffl@lbracket
-\finish{newmacro}
+\finish{example}
\aidx*{Futurelet commands}
If any of the commands emanating from concatenating \ang{stub} with the name of the character is already defined, an error message is flagged. It should be noted that these commands are available only after issuing the command \fx{\cptfutureletsetup}, which isn't called automatically anywhere by the \pkg'{catoptions}. Normally, at \hx{\AtBeginDocument} the \pkg'{catoptions} calls the command \fx{\cptrestorecatcodes}, without calling \fx{\cptfutureletsetup}. Calling \ffx'{\declarefutureletset, \cptfutureletsetup} is the user's duty.
@@ -212,7 +236,7 @@ where \quotedtt{all} means that control sequences should be defined for all the
This will yield control sequences that may never be needed. While such a facility does exist, using it will be inefficient despite the large capacities of many modern \tex engines.
-The use syntaxes for the commands \fnl{{stub}{char}} and \fnl{{if}{stub}{char}} are as follows:
+The use syntaxes for the commands \fnl*'\bs{stub,char} and \fnl*'{\bs if}{stub,char} are as follows:
\start{example}[Futurelet characters]
\futurelet\next\cmd |textbf(|R(*))
@@ -285,20 +309,24 @@ The \unstform of the macro \fx{\XDeclareOption} declares an option that can be u
\start{example}[\XDeclareOption]
\ProvidesPackage{mypackage}[\StyleFileInfo]
-\newif\ifmybool
+\cptnewbool{mybool}
\XDeclareOption{mybool}[true]{\@nameuse{mybool#1}}
\XDeclareOption{leftmargin}[.5\hsize]{\setlength\leftmargin{#1}}|xwmlabel(mac:leftmargin)
\finish{example}
-The options \ffx'{mybool,leftmargin} could then be called via any of the following statements:
+\deffnote{2}{%
+ The commands \ffx'{\XDeclareBooleanOption, \XDeclareBooleanOptions, \XDeclareBiBooleanOptions} allow the user to define new boolean options without the need to first initialize the booleans with \hx{\newif} or \fx{\cptnewbool} as seen here.
+}
+
+The user would have noticed the use \fx{\cptnewbool} in the above example\usefnote{2}. The options \ffx'{mybool,leftmargin} could then be called via any of the following statements:
\start{example}[\XDeclareOption]
|com(Inside class or package files:)
-\RequirePackage[mybool=true,leftmargin=20\p@]{mypackage}
+\RequirePackage[mybool=true,leftmargin=20pt]{mypackage}
|com(Inside document file:)
-\usepackage[mybool=false,leftmargin=20\p@]{mypackage}
+\usepackage[mybool=false,leftmargin=20pt]{mypackage}
|com(Via document class:)
-\documentclass[mybool,leftmargin=20\p@]{myclass}
+\documentclass[mybool,leftmargin=20pt]{myclass}
\finish{example}
The \stform of the macro \fx{\XDeclareOption} can be used to process unknown options. It is similar to \latex's \hx{\DeclareOption}\RedStar, but it has additional features. You can deploy \hx{\CurrentOption} within the \ang{fn} of this macro to access the option name and value for which the option is unknown. These values (possibly including an option) could, for example, be passed on to another class or package or could be used as an extra class or package option that, for instance, specifies a style that should be loaded. Moreover, you can use \fx{#1}, \fx{#2} and \fx{#3} within \ang{fn} to refer to the current family, current option (without its value), and current value, respectively.
@@ -310,7 +338,11 @@ The \stform of the macro \fx{\XDeclareOption} can be used to process unknown opt
\finish{newmacro}
\fxim*{\XUnknownOptionHandler}
-The command \fx{\XUnknownOptionHandler} can be used in place of \xdecs to specify default action(s) for options undefined in any family in \ang{fams}\footnote{Declaring a default handler for each unknown option is, of course, inefficient. We have therefore provided provisions for declaring such handers for only families of options.}. \ang{handler} refers to the default function that should be executed if undeclared options are called from families \ang{fams} by the user. \hx{\CurrentOption} can be deployed within \ang{handler} to access the option name (coupled with its current value) for which the option name is unknown. As mentioned above in the case of \xdecs, you can use \fx{#1}, \fx{#2} and \fx{#3} within \ang{handler} to access the current family, current option (uncoupled from its current value), and current value, respectively. \ang{na} is the list of options for which \ang{handler} shouldn't apply; for these options, the kernel's unknown option handler (\ie, \hx{\default@ds}) would apply.
+\deffnote{3}{%
+ Declaring a default handler for each unknown option is, of course, inefficient.
+ We have, therefore, provided provisions for declaring such handers for only families of options.
+}
+The command \fx{\XUnknownOptionHandler} can be used in place of \xdecs to specify default action(s) for options undefined in any family in \ang{fams}\usefnote{3}. \ang{handler} refers to the default function that should be executed if undeclared options are called from families \ang{fams} by the user. \hx{\CurrentOption} can be deployed within \ang{handler} to access the option name (coupled with its current value) for which the option name is unknown. As mentioned above in the case of \xdecs, you can use \fx{#1}, \fx{#2} and \fx{#3} within \ang{handler} to access the current family, current option (uncoupled from its current value), and current value, respectively. \ang{na} is the list of options for which \ang{handler} shouldn't apply; for these options, the kernel's unknown option handler (\ie, \hx{\default@ds}) would apply.
If the \ang{handler} contains the special literal form \fx{define/.code=} as in
@@ -417,7 +449,7 @@ The command \fx{\XInvalidOptionHandler} defines, for each family \ang{fam} in \a
\finish{newmacro}
\fxim*{\XDeclareCommandOption}
-The command \fx{\XDeclareCommandOption} will, apart from declaring the option \ang{opt}, also create a macro \fnl{{pref}{opt}} to hold the user-supplied value of the option. The macro so created can be used in \ang{fn} or in any other place. The default value of the optional \ang{pref} is \quotedFx{\@currname @} prefixed with the letters \fx{cmd}.
+The command \fx{\XDeclareCommandOption} will, apart from declaring the option \ang{opt}, also create a macro \fnl*'\bs{pref,opt} to hold the user-supplied value of the option. The macro so created can be used in \ang{fn} or in any other place. The default value of the optional \ang{pref} is \quotedFx{\@currname @} prefixed with the letters \fx{cmd}.
\start{newmacro}[\XDeclareCommandOptions]
\XDeclareCommandOptions<|nang(fam)>{|nang(opts)}[|nang(default)]|(|nang(pref)|){|nang(fn)}
@@ -432,7 +464,7 @@ The command \fx{\XDeclareCommandOptions} is similar to \fx{\XDeclareCommandOptio
\finish{newmacro}
\fxim*{\XDeclareBooleanOption}
-The command \fx{\XDeclareBooleanOption} will, apart from declaring the option \ang{opt}, also create a boolean \fnl{{if}{pref}{opt}}. It will automatically toggle this boolean (to \hx{true} or \hx{false}) when the option is set and the input is valid, depending on the user-supplied value of the option. The macros so created can be used in \ang{fn} or in any other place. The default value of the optional \ang{pref} is \quotedFx{\@currname @} with no additional prefix. Only \hx{true} or \hx{false} may be submitted as the value of a boolean option.
+The command \fx{\XDeclareBooleanOption} will, apart from declaring the option \ang{opt}, also create a boolean \fnl*'{\bs if}{pref,opt}. It will automatically toggle this boolean (to \hx{true} or \hx{false}) when the option is set and the input is valid, depending on the user-supplied value of the option. The macros so created can be used in \ang{fn} or in any other place. The default value of the optional \ang{pref} is \quotedFx{\@currname @} with no additional prefix. Only \hx{true} or \hx{false} may be submitted as the value of a boolean option.
\start{newmacro}[\XDeclareBooleanOptions]
\XDeclareBooleanOptions<|nang(fam)>{|nang(opts)}[|nang(default)]|(|nang(pref)|){|nang(fn)}
@@ -463,7 +495,10 @@ In the parlance of the \pkg'{catoptions,ltxtools}, a switch can assume only one
\finish{newmacro}
\fxim*{\ifswitchTF,\ifswitchFT}
-Note that here \ang{switch} has no escape character, unless it evaluates to a switch name. So, after defining \fx{\def\swa{00}} we could then do \fx{\ifswitchTF{swa}{true}{false}}. It is somewhat risky to introduce new switches with \hx{\def} or \hx{\let}\footnote{Because of the need to do, \eg, \fx{\let\swa\cpttrue} and \hx{\if}\unskip\fx{\swa} for any given switch \fx{\swa}, switches, unlike toggles, don't have their own separate name space and it is all too easy to redefine an existing switch.}. It is advisable to use \fx{\newswitch} instead. It has the syntax
+\deffnote{4}{%
+ Because of the need to do, \eg, \fx{\let\swa\cpttrue} and \hx{\if}\unskip\fx{\swa} for any given switch \fx{\swa}, switches, unlike toggles, don't have their own separate namespace and it is all too easy to redefine an existing switch.
+}
+Note that here \ang{switch} has no escape character, unless it evaluates to a switch name. So, after defining \fx{\def\swa{00}} we could then do \fx{\ifswitchTF{swa}{true}{false}}. It is somewhat risky to introduce new switches with \hx{\def} or \hx{\let}\usefnote{4}. It is advisable to always use \fx{\newswitch} instead. It has the syntax
\start{newmacro}[\newswitch]
\newswitch{|nang(switch)}[|nang(state)]
@@ -484,7 +519,7 @@ It is possible to toggle the state of a switch by simply using the commands:
\finish{newmacro}
\fxim*{\setswitchtrue,\setswitchfalse}
-The command \fx{\XDeclareSwitchOption} will, apart from declaring the option \ang{opt}, also create a switch \fnl{{pref}{opt}}. It will automatically toggle this switch to \hx{true} (equivalent to \fx{00}) or \hx{false} (equivalent to \fx{01}) when the option is set and the input is valid, depending on the user-supplied value of the option. The macros so created can be used in \ang{fn} or in any other place. The default value of the optional \ang{pref} is again \quotedFx{\@currname @} with no additional prefix. Only \hx{true} or \hx{false} may be submitted as the value of a switch option.
+The command \fx{\XDeclareSwitchOption} will, apart from declaring the option \ang{opt}, also create a switch \fnl*'\bs{pref,opt}. It will automatically toggle this switch to \hx{true} (equivalent to \fx{00}) or \hx{false} (equivalent to \fx{01}) when the option is set and the input is valid, depending on the user-supplied value of the option. The macros so created can be used in \ang{fn} or in any other place. The default value of the optional \ang{pref} is again \quotedFx{\@currname @} with no additional prefix. Only \hx{true} or \hx{false} may be submitted as the value of a switch option.
\start{newmacro}[\XDeclareSwitchOptions]
\XDeclareSwitchOptions<|nang(fam)>{|nang(opts)}[|nang(default)]|(|nang(pref)|){|nang(fn)}
@@ -697,8 +732,8 @@ Here are some points to note about these list processors:
\item Since \ffx'{\csv@@loop,\kv@@loop} don't call the normalizer, they preserve outer/surrounding spaces in the entries. Empty entries in \ang{list} or \ang{listcmd} will be processed by \ffx'{\csv@@loop,\kv@@loop} if the boolean \fx{cpt@useempty} is true. You may thus issue the command \fx{\UseEmptyEntry} or \fx{\DiscardEmptyEntry}, which are based on the boolean \fx{cpt@useempty}, before commencing the iteration. If empty entries are important to the task at hand, then issuing \fx{\UseEmptyEntry} or \fx{\DiscardEmptyEntry} prior to the commencement of the loop is recommended, because a previous call to either \fx{\csv@@loop} or \fx{\kv@@loop} (perhaps by another package) could have set \fx{cpt@useempty} to a state that is no longer valid or desired.
\item The commands \ffx'{\csv@@loop,\csv@@parse,\kv@@loop,\kv@@parse} will execute at least once for empty \ang{list} or \ang{listcmd}.
\item The commands \ffx'{\csv@@loop,\csv@@parse,\kv@@loop,\kv@@parse} can be nested to any level and can be mixed.
-\item In the commands \ffx'{\csv@@loop,\csv@@parse,\kv@@loop,\kv@@parse}, it is always possible to break out of the loop prematurely at any level of nesting, simply by issuing the command \fx{\loopbreak} (see the example below). Breaking an inner loop doesn't affect the continuation of the outer loop, and vice versa; that is, loop breaks are nesting level-dependent.
-\item The user can insert \fx{\csvbreak} as an element in \ang{list} for any of the commands \ffx'{\csv@@loop, \csv@@parse, \kv@@loop, \kv@@parse, \dofunclist} with the hope of automatically breaking out of the list processing prematurely (\ie, before the list is exhausted). The tokens \ffx'{\listbreak, \breaklist} are not defined or used by the \pkg'{catoptions}, to avoid name clashes with other packages. The \pkg'{catoptions} instead uses \fx{\csvbreak}, which is an unexpandable token; if it were to be expandable, then experience has shown that a chaotic infinite loop could arise in an expansion context. Breaking out of the loop prematurely on the current nesting level doesn't affect the continuation of the loop on the other levels.
+\item In the commands \ffx'{\csv@@loop,\csv@@parse,\kv@@loop,\kv@@parse}, it is always possible to break out of the loop prematurely at any level of nesting, simply by issuing the command \fx{\loopbreak} (see the example below). Breaking an inner loop doesn't affect the continuation of the outer loop, and vice versa; that is, loop breaks are nest-level-dependent.
+\item The user can insert \fx{\csvbreak} as an element in \ang{list} for any of the commands \ffx'{\csv@@loop, \csv@@parse, \kv@@loop, \kv@@parse, \dofunclist} with the hope of automatically breaking out of the list processing prematurely (\ie, before the list is exhausted). The tokens \ffx'{\listbreak, \breaklist} are not defined or used by the \pkg'{catoptions}, to avoid name clashes with other packages. The \pkg'{catoptions} instead uses \fx{\csvbreak}, which is an unexpandable token; if it were to be expandable, then experience has shown that a chaotic infinite loop could arise in an expansion context. Breaking out of the loop prematurely on the current nest level doesn't affect the continuation of the loop on the other levels.
\end{enum}
\start{example}[\csv@@parse]
@@ -788,22 +823,22 @@ Empty entries in \ang{list} will be ignored by the normalizer called by \fx{\dof
|com(Let us load many packages compactly here. This is just an example of)
|com(|fx(\dofunclist); you can instead use the more appropriate command)
|com(|fx(\cptloadpackages) to load packages (see |amref(mac:loadpkg)):)
-\def\do#1#2[#3]{%
+\def\do#1.#2[#3]{%
\@ifpackageloaded{#1}{%
\@ifpackagelater{#1}{#2}{}{%
\cpt@warn{Older version of package `#1' loaded earlier}%
}%
}{%
- \usepackage[#3]{#1}[#2]%
+ \cptexpandsecond\usepackage{[\cpttrimspaces{#3}]}{#1}[#2]%
}%
}
|com(The default parser |(,|) is implied below:)
\dofunclist{%
- {yfonts}{2003/01/08}[],
- {pifont}{2005/04/12}[],
- {helvet}{2005/04/12}[scaled=0.9],
- {zref}{2008/10/01}[user,lastpage],
- {xcolor}{2007/01/21}[table,hyperref]
+ yfonts.2003/01/08[],
+ pifont.2005/04/12[],
+ helvet.2005/04/12[scaled=0.9],
+ zref.2008/10/01[|R({)user,lastpage|R(})],
+ xcolor.2007/01/21[|R({)table,hyperref|R(})]
}
|com(An example of nested loops follows. Here outer braces in the)
@@ -822,7 +857,7 @@ Empty entries in \ang{list} will be ignored by the normalizer called by \fx{\dof
\dofunclist[,]{a,{b},c,d,e}
\finish{example}
-While \fx{\dofunclist} allows the user to define and call multi-parametered \fx{\do} functions, outer curly braces in the \emph{individual} arguments of \fx{\do} may, in some rare cases, be lost in parsing (but only if the number of arguments exceeds one). This possibility depends on how the parameters and arguments of the user-supplied command \fx{\do} are arranged. If preserving braces is essential to the user's need, then he/she might consider using the more robust commands \ffx'{\csv@@loop, \csv@@parse, \kv@@loop, \kv@@parse}. It is possible to robustly build a multi-parametered callback in the user-defined commands \ffx'{\csv@do,\kv@do} required by \ffx'{\csv@@loop, \csv@@parse, \kv@@loop, \kv@@parse}. Admittedly, only experienced \texnicians may be able to do that.
+While \fx{\dofunclist} allows the user to define and call multi-parametered \fx{\do} functions, outer curly braces in the \emph{individual} arguments of \fx{\do} may, in some rare cases, be lost in parsing (but only if the number of arguments exceeds one). This possibility depends on how the parameters and arguments of the user-supplied command \fx{\do} are arranged. If preserving braces is essential to the user's need, then he/she might consider using the more robust commands \ffx'{\csv@@loop, \csv@@parse, \kv@@loop, \kv@@parse}. It is possible to robustly build a multi-parametered callback in the user-defined commands \ffx'{\csv@do,\kv@do} required by \ffx'{\csv@@loop, \csv@@parse, \kv@@loop, \kv@@parse}. In fact, this is what \fx{\dofunclist} does internally. Admittedly, only experienced \texnicians may be able to do that.
\docsubsection(sec:indris){Looking ahead in csv lists}
@@ -839,11 +874,11 @@ Imagine an instance in which, while processing a csv list, you need not only the
The \fx{\indrisloop} command can be used to iterate over a \ang{parser}-separated \ang{list} or \ang{listcmd} and execute the user-supplied one-parameter command \ang{fn} for every item in the list, passing the item as an argument and preserving outer braces.
-The \fx{\indrisloop} iterator is of particular interest. The loop provides the macros \ffx'{\indrisdepth, \currindris, \currindris@i, \nextindris, \nextindris@i, \indrisnr, \iflastindris, \ifloopbreak}, which mean, respectively, the current nesting depth/level, the current item on the current level, the current item on an arbitrary level \quotedfx{i}, the next item on the current level, the next item on an arbitrary level \quotedfx{i}, the numerical order of the current item on the current level, the boolean that indicates that the last item of the list has been reached on the current level of nesting, and the boolean that can be used to break the loop prematurely (before the list is exhausted) on any level.
+The \fx{\indrisloop} iterator is of particular interest. The loop provides the macros \ffx'{\indrisdepth, \currindris, \currindris@i, \nextindris, \nextindris@i, \indrisnr, \iflastindris, \ifloopbreak}, which mean, respectively, the current nested depth/level, the current item on the current level, the current item on an arbitrary level \quotedfx{i}, the next item on the current level, the next item on an arbitrary level \quotedfx{i}, the numerical order of the current item on the current level, the boolean that indicates that the last item of the list has been reached on the current level of nesting, and the boolean that can be used to break the loop prematurely (before the list is exhausted) on any level.
You can do \fx{\iflastindris...\fi} on any level. On any given level, it is possible to break out of the current loop by simply issuing \fx{\loopbreak}. This would not affect the progress of the loops on other levels. When \fx{\iflastindris} is true on a given level \quotedfx{i}, then \ffx'{\nextindris,\nextindris@i} are empty on that level, but not necessarily the macros \ffx'{\currindris,\currindris@i}.
-The following provides a simple application of \fx{\indrisloop}, which I posted on \href{https://groups.google.com/forum/#!forum/comp.text.tex}{comp.text.tex} in July~2011.
+The following provides a simple application of \fx{\indrisloop}, which I posted on \comptexttex in July~2011 in response to a posted question.
\start{example}[\indrisloop]
\makeatletter
@@ -894,7 +929,7 @@ The following provides a simple application of \fx{\indrisloop}, which I posted
\finish{example}
%\bigskip
-\docsection(sec:tsvparse)<Iterating tokenwise>{Parsing \headq{tsv} lists}
+\docsection(sec:tsvparse)<Iterating tokenwise>{Parsing \headqtd{tsv} lists}
\start+{newmacro}[\tsv@@parse,\tsv@@loop]
\tsv@@loop{|nang(list)}
@@ -934,6 +969,9 @@ In the commands \ffx'{\tsv@loop,\tsv@@parse}, it is always possible to break out
The following change history highlights significant changes that affect user utilities and interfaces; mutations of technical nature are not documented in this section. The numbers on the right-hand side of the following lists are section numbers; the \stsign means the subject features in the package but is not reflected anywhere in this user guide.
\begin{versionhist}
+ \begin{version}{0.2.6}{2011/09/10}
+ \item Bug fix in the command \fx{\UseNormalCatcodes} \vsecref{sec:saving-catcodes}
+ \end{version}
\begin{version}{0.2.5}{2011/07/20}
\item Enlarged the command \fxi{\newvariables} to include \hx{\newwrite} and \fx{\newswitch} \vsecref*
\end{version}
@@ -945,7 +983,7 @@ The following change history highlights significant changes that affect user uti
\end{version}
\begin{version}{0.2b}{2011/04/02}
- \item The following commands have been introduced \vsecref{sec:options-parse}
+ \item The following commands were introduced \vsecref{sec:options-parse}
\start{veritem}
\XDeclareInvalidOptions \XUnknownOptionHandler \XDisableOptions
\XLogDisabledOptions \ifoptdisabledTF \ifoptdefTF
@@ -954,7 +992,7 @@ The following change history highlights significant changes that affect user uti
\begin{version}{0.2a}{2011/02/15}
\item For efficiency reasons, canonical control sequences for futurelet characters are no longer defined automatically. The user is now responsible for specifying the canonical control sequences that should be defined \vsecref{sec:future-letting}
- \item The following plural-form commands have been introduced \vsecref{sec:options-parse}
+ \item The following plural-form commands were introduced \vsecref{sec:options-parse}
\start{veritem}
\XDeclareOptions \XDeclareCommandOptions
\XDeclareBooleanOptions \XDeclareBiBooleanOptions