| 1 |
% |
| 2 |
% \iffalse /!\ this file contains non-ascii -- encoding is utf-8 /!\ |
| 3 |
% |
| 4 |
% xargs package by Manuel P\'egouri\'e-Gonnard <[email protected]> |
| 5 |
% ------------------------------------------------------------- |
| 6 |
% |
| 7 |
% This work may be distributed and/or modified under the conditions of |
| 8 |
% the LaTeX Project Public License, either version 1.3c of this license |
| 9 |
% or (at your option) any later version. The latest version of this |
| 10 |
% license is in: |
| 11 |
% |
| 12 |
% http://www.latex-project.org/lppl.txt |
| 13 |
% |
| 14 |
% and version 1.3c or later is part of all distributions of LaTeX |
| 15 |
% version 2006/05/20 or later. |
| 16 |
% |
| 17 |
% This work has the LPPL maintenance status `maintained'. |
| 18 |
% |
| 19 |
% The current maintainer of this work is Manuel P\'egouri\'e-Gonnard. |
| 20 |
% |
| 21 |
% This work consists of the file xargs.dtx and the derived files |
| 22 |
% xargs.sty, xargs.pdf and xargs-fr.pdf. |
| 23 |
% |
| 24 |
% |
| 25 |
%<*gobble> |
| 26 |
\ProvidesFile{xargs.dtx} |
| 27 |
%</gobble> |
| 28 |
%<package>\NeedsTeXFormat{LaTeX2e} |
| 29 |
%<package>\ProvidesPackage{xargs} |
| 30 |
%<*package> |
| 31 |
% \fi |
| 32 |
% \ProvidesFile{xargs.dtx} |
| 33 |
[2008/03/22 v1.1 \space extended macro definitions \space (mpg)] |
| 34 |
% \iffalse |
| 35 |
%</package> |
| 36 |
% \fi |
| 37 |
% \CheckSum{782} |
| 38 |
% \CharacterTable |
| 39 |
% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z |
| 40 |
% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z |
| 41 |
% Digits \0\1\2\3\4\5\6\7\8\9 |
| 42 |
% Exclamation \! Double quote \" Hash (number) \# |
| 43 |
% Dollar \$ Percent \% Ampersand \& |
| 44 |
% Acute accent \' Left paren \( Right paren \) |
| 45 |
% Asterisk \* Plus \+ Comma \, |
| 46 |
% Minus \- Point \. Solidus \/ |
| 47 |
% Colon \: Semicolon \; Less than \< |
| 48 |
% Equals \= Greater than \> Question mark \? |
| 49 |
% Commercial at \@ Left bracket \[ Backslash \\ |
| 50 |
% Right bracket \] Circumflex \^ Underscore \_ |
| 51 |
% Grave accent \` Left brace \{ Vertical bar \| |
| 52 |
% Right brace \} Tilde \~} |
| 53 |
% \iffalse |
| 54 |
%<*gobble> |
| 55 |
\begingroup |
| 56 |
%</gobble> |
| 57 |
%<*batchfile> |
| 58 |
\input docstrip |
| 59 |
\keepsilent |
| 60 |
\preamble |
| 61 |
|
| 62 |
xargs package by Manuel P\string\'egouri\string\'e-Gonnard % |
| 63 |
<[email protected]> |
| 64 |
This is a generated file. See xargs.dtx for license information. |
| 65 |
|
| 66 |
\endpreamble |
| 67 |
\askforoverwritefalse |
| 68 |
%\generate{\file{xargs.ins}{\from{xargs.dtx}{batchfile}}} |
| 69 |
%\generate{\file{xargs.drv}{\from{xargs.dtx}{driver}}} |
| 70 |
\generate{\file{xargs.sty}{\from{xargs.dtx}{package}}} |
| 71 |
\generate{\file{xargs-fr.drv}{\from{xargs.dtx}{pilote}}} |
| 72 |
%</batchfile> |
| 73 |
%<*gobble> |
| 74 |
\endgroup |
| 75 |
%</gobble> |
| 76 |
%<*driver|pilote> |
| 77 |
\documentclass[oneside, a4paper]{ltxdoc} |
| 78 |
\usepackage[utf8]{inputenc} |
| 79 |
\usepackage[T1]{fontenc} |
| 80 |
\usepackage{lmodern} |
| 81 |
\usepackage{fixltx2e, mparhack} |
| 82 |
\usepackage[babel=true, expansion=false]{microtype} |
| 83 |
\usepackage{xargs} |
| 84 |
\expandafter\newif\csname iffrenchdoc\endcsname % cachez ce if que je ne... |
| 85 |
%<pilote>\frenchdoctrue |
| 86 |
%</driver|pilote> |
| 87 |
%<*gobble> |
| 88 |
\iffrenchdoc |
| 89 |
%</gobble> |
| 90 |
%<*pilote> |
| 91 |
\usepackage[lmargin=4.5cm, rmargin=3cm]{geometry} |
| 92 |
\OnlyDescription |
| 93 |
\usepackage[english, frenchb]{babel} |
| 94 |
\FrenchFootnotes \AddThinSpaceBeforeFootnotes |
| 95 |
\newcommand*\eng[1]{\emph{\foreignlanguage{english}{#1}}} |
| 96 |
\usepackage[colorlinks=true, bookmarks=true, |
| 97 |
bookmarksnumbered=true, bookmarksopen=true, bookmarksopenlevel=3, |
| 98 |
pdfauthor={Manuel Pégourié-Gonnard}, |
| 99 |
pdftitle={L'extension xargs}, |
| 100 |
pdfsubject={Définitions de macros étendues pour LaTeX2e}, |
| 101 |
]{hyperref} |
| 102 |
%</pilote> |
| 103 |
%<*gobble> |
| 104 |
\else |
| 105 |
%</gobble> |
| 106 |
%<*driver> |
| 107 |
\AlsoImplementation |
| 108 |
\usepackage[english]{babel} |
| 109 |
\usepackage[colorlinks=true, bookmarks=true, |
| 110 |
bookmarksnumbered=true, bookmarksopen=true, bookmarksopenlevel=3, |
| 111 |
pdfauthor={Manuel Pégourié-Gonnard}, |
| 112 |
pdftitle={The xargs package}, |
| 113 |
pdfsubject={Extended macro definitions for LaTeX2e}, |
| 114 |
]{hyperref} |
| 115 |
\settowidth\MacroIndent{\rmfamily\scriptsize 000\ } |
| 116 |
\setlength\MacroTopsep{0pt} |
| 117 |
\usepackage[nohints, english]{minitoc} |
| 118 |
\mtcsetpagenumbers{secttoc}{off} |
| 119 |
\mtcsetrules{secttoc}{off} |
| 120 |
\mtcsetdepth{secttoc}{3} |
| 121 |
\setlength{\stcindent}{0pt} |
| 122 |
\mtcsetfont{secttoc}{subsection}{\normalfont} |
| 123 |
\newcommand\tocwithmini{% |
| 124 |
\dosecttoc[n] |
| 125 |
\setcounter{tocdepth}{1}\tableofcontents |
| 126 |
\setcounter{tocdepth}{3}\faketableofcontents} |
| 127 |
%</driver> |
| 128 |
%<*gobble> |
| 129 |
\fi |
| 130 |
%</gobble> |
| 131 |
%<*driver|pilote> |
| 132 |
\newcommand\pf{\textsf} |
| 133 |
\newcommand\optstar{\meta{$*$}} |
| 134 |
\newcommand\topcs[1]{\texorpdfstring{\cs{#1}}{#1}} |
| 135 |
\newcommand\eTeX{$\varepsilon$-\TeX} |
| 136 |
\begin{document} |
| 137 |
\DocInput{xargs.dtx} |
| 138 |
\end{document} |
| 139 |
%</driver|pilote> |
| 140 |
%<*package> |
| 141 |
% \fi |
| 142 |
% |
| 143 |
% \GetFileInfo{xargs.dtx} |
| 144 |
% |
| 145 |
% \title{\iffrenchdoc L'extension \pf{xargs}\else The \pf{xargs} package\fi} |
| 146 |
% \author{Manuel Pégourié-Gonnard\\ |
| 147 |
% \href{mailto:[email protected]}{[email protected]}} |
| 148 |
% \date{\fileversion\ (\filedate)} |
| 149 |
% |
| 150 |
% \maketitle |
| 151 |
% \iffrenchdoc\else \tocwithmini \fi |
| 152 |
% |
| 153 |
% \iffrenchdoc\else |
| 154 |
% \medskip |
| 155 |
% \emph{Important note for French users}: a French version of the user |
| 156 |
% documentation is included in the \nolinkurl{xargs-fr.pdf} file. |
| 157 |
% \fi |
| 158 |
% |
| 159 |
% \section{Introduction} |
| 160 |
% |
| 161 |
% \iffrenchdoc |
| 162 |
% |
| 163 |
% \LaTeXe{} permet de définir facilement des commandes ayant un argument |
| 164 |
% optionel. Cependant, il y a deux restrictions : il peut y avoir au plus un |
| 165 |
% argument optionel, et ce doit être le premier. L'extension \pf{xargs} |
| 166 |
% fournit des versions étendues de \cs{newcommand} et de ses analogues |
| 167 |
% standard, qui ne présentent pas ces restrictions : il est désormais |
| 168 |
% facile de définir des commandes avec plusieurs arguments optionnels, |
| 169 |
% placés où l'on veut, par une syntaxe agréable du style |
| 170 |
% \meta{clé}=\meta{valeur}. Par exemple, voici comment définir une |
| 171 |
% commande avec deux arguments optionnels. |
| 172 |
% |
| 173 |
% \begin{center} |
| 174 |
% |\newcommandx*\coord[3][1=1, 3=n]{(#2_{#1},\ldots,#2_{#3})}| |
| 175 |
% \newcommandx*\coord[3][1=1, 3=n]{(#2_{#1},\ldots,#2_{#3})} |
| 176 |
% \par\medskip |
| 177 |
% \begin{tabular}{ll} |
| 178 |
% |$\coord{x}$| & $\coord{x}$ \\ |
| 179 |
% |$\coord[0]{y}$| & $\coord[0]{y}$ \\ |
| 180 |
% |$\coord{z}[m]$| & $\coord{z}[m]$ \\ |
| 181 |
% |$\coord[0]{t}[m]$| & $\coord[0]{t}[m]$ \\ |
| 182 |
% \end{tabular} |
| 183 |
% \end{center} |
| 184 |
% |
| 185 |
% \else |
| 186 |
% |
| 187 |
% Defining commands with an optional argument is easy in \LaTeXe{}. |
| 188 |
% There is, however, two limitations: you can make only one argument |
| 189 |
% optional and it must be the first one. The \pf{xargs} package provide |
| 190 |
% extended variants of \cs{newcommand} \& friends, for which these |
| 191 |
% limitations no longer hold: It is now easy to define commands with |
| 192 |
% many (and freely placed) optional arguments, using a nice |
| 193 |
% \meta{key}=\meta{value} syntax. For example, the following defines a |
| 194 |
% command with two optional arguments. |
| 195 |
% |
| 196 |
% \begin{center} |
| 197 |
% |\newcommandx*\coord[3][1=1, 3=n]{(#2_{#1},\ldots,#2_{#3})}| |
| 198 |
% \newcommandx*\coord[3][1=1, 3=n]{(#2_{#1},\ldots,#2_{#3})} |
| 199 |
% \par\medskip |
| 200 |
% \begin{tabular}{ll} |
| 201 |
% |$\coord{x}$| & $\coord{x}$ \\ |
| 202 |
% |$\coord[0]{y}$| & $\coord[0]{y}$ \\ |
| 203 |
% |$\coord{z}[m]$| & $\coord{z}[m]$ \\ |
| 204 |
% |$\coord[0]{t}[m]$| & $\coord[0]{t}[m]$ \\ |
| 205 |
% \end{tabular} |
| 206 |
% \end{center} |
| 207 |
% |
| 208 |
% \fi |
| 209 |
% |
| 210 |
% \section{Usage} |
| 211 |
% |
| 212 |
% \iffrenchdoc |
| 213 |
% |
| 214 |
% \subsection{Les bases} |
| 215 |
% |
| 216 |
% L'extension \pf{xargs} fournit des analogues de toutes les macros de |
| 217 |
% \LaTeXe{} relatives à la définition de macros. Les macros de \pf{xargs} ont |
| 218 |
% le même nom que leur analogue standard, mais avec un |x| supplémentaire à la |
| 219 |
% fin. En voici la liste complète. |
| 220 |
% |
| 221 |
% \begin{center} |
| 222 |
% \begin{tabular}{ll} |
| 223 |
% \cs{newcommandx} & \cs{renewcommandx} \\ |
| 224 |
% \cs{newenvironmentx} & \cs{renewenvironmentx} \\ |
| 225 |
% \cs{providecommandx} & \cs{DeclareRobustCommandx} \\ |
| 226 |
% \cs{CheckCommandx} |
| 227 |
% \end{tabular} |
| 228 |
% \end{center} |
| 229 |
% |
| 230 |
% Si vous ne connaissez pas toutes ces commandes, ne vous inquiétez pas. |
| 231 |
% Vous pouvez utiliser seulement les analogues des macros que vous |
| 232 |
% connaissez ; ou apprendre les autres par exemple dans le livre de |
| 233 |
% \bsc{Lamport}, le \LaTeX{} Companion, ou tout autre manuel sur \LaTeXe. |
| 234 |
% |
| 235 |
% \medskip |
| 236 |
% |
| 237 |
% Ces commandes partageant toutes la même syntaxe, je parlerai seulement |
| 238 |
% de |\newcommandx| par la suite, mais gardez à l'esprit que les |
| 239 |
% explications sont valables pour les autres commandes. (Bien sûr, pour |
| 240 |
% les environnements, il y a un dernier argument en plus, pour la |
| 241 |
% définition de fin.) Voici la syntaxe complète de |\newcommand|. |
| 242 |
% |
| 243 |
% \begin{center} |
| 244 |
% \cs{newcommandx}\optstar\marg{commande}\oarg{nombre}\oarg{liste}^^A |
| 245 |
% \marg{définition} |
| 246 |
% \end{center} |
| 247 |
% |
| 248 |
% Rappelons brièvement tout ce qui est commun avec la syntaxe usuelle, à |
| 249 |
% savoir tout sauf \meta{liste}. Si une $*$ est présente, elle signifie |
| 250 |
% que la macro crée est \emph{courte} au sens de \TeX{}, c'est-à -dire |
| 251 |
% que ses arguments ne peuvent pas contenir de saut de paragraphe |
| 252 |
% (\cs{par} ou ligne vide). La \meta{commande} est n'importe quelle |
| 253 |
% séquence de contrôle, que vous pouvez ou non entourer d'accolades |
| 254 |
% suivant vos goûts. Le \meta{nombre} définit le nombre total d'argument |
| 255 |
% de la \meta{commande}, c'est un entier compris entre $0$ et $9$. La |
| 256 |
% \meta{définition} est un texte équilibré en accolades, et où chaque |
| 257 |
% caractère |#| est suivi soit d'un chiffre représentant un des |
| 258 |
% arguments, soit d'un autre caractère |#|. Les arguments \meta{nombre} |
| 259 |
% et \meta{liste} sont optionnels. |
| 260 |
% |
| 261 |
% \medskip |
| 262 |
% |
| 263 |
% La partie intéressante maintenant. La \meta{liste} est une\ldots{} |
| 264 |
% liste (!) d'éléments de la forme \meta{chiffre}=\meta{valeur}, séparés |
| 265 |
% par des virgules. Le \meta{chiffre} doit être un entier compris entre |
| 266 |
% $1$ et le nombre d'arguments, donné par \meta{nombre}. La |
| 267 |
% \meta{valeur} est n'importe quelle texte équilibré en accolades. Il |
| 268 |
% peut être vide si vous le souhaitez : le signe égal qui le précède |
| 269 |
% peut alors être omis. Tous les arguments dont le numéro figure en tant |
| 270 |
% que \meta{chiffre} dans la \meta{liste} seront optionnels, avec pour |
| 271 |
% valeur par défaut celle donnée par la \meta{valeur} correspondante. |
| 272 |
% |
| 273 |
% Quelques remarques supplémentaires sur la syntaxe de la \meta{liste}, |
| 274 |
% que vous pouvez sauter si vous êtes familiers avec la syntaxe fournie |
| 275 |
% par \pf{xkeyval}. Vu que les éléments sont séparés par des virgules, |
| 276 |
% si une \meta{valeur} doit contenir une virgule, il faut entourer la |
| 277 |
% valeur par des accolades pour protéger la virgule. (Cette précaution |
| 278 |
% est également indispensable si la \meta{valeur} contient une accolade |
| 279 |
% fermante.) Ne vous inquiétez pas, cette parie d'accolade sera retirée |
| 280 |
% ultérieurement. D'ailleurs, jusqu'à trois paires d'accolades seront |
| 281 |
% retirées ainsi, et si vous voulez vraiment que votre valeur reste |
| 282 |
% entourée d'accolades, il vous faudra écrire quelque chose |
| 283 |
% comme~|1={{{{\large blabla}}}}|. |
| 284 |
% |
| 285 |
% \medskip |
| 286 |
% |
| 287 |
% C'est tout pour les bases : vous en savez maintenant assez pour |
| 288 |
% utiliser \pf{xargs}, et vous pouvez laisser la fin de la documentation |
| 289 |
% pour plus tard si vous voulez. Si, au contraire, vous vous demandez ce |
| 290 |
% qui se passe avec plusieurs arguments optionnels à la suite, que vous |
| 291 |
% voulez effectuer des définitions globales, ou que vous aves besoin de |
| 292 |
% connaître les limites précises de \pf{xargs}, vous pouvez lire les |
| 293 |
% sections suivantes. |
| 294 |
% |
| 295 |
% \subsection{La clé \texttt{usedefault}} |
| 296 |
% |
| 297 |
% Voyons donc se qui se passe quand plusieurs arguments optionnels se |
| 298 |
% suivent. Le comportement par défaut est calqué sur celui de commandes |
| 299 |
% \LaTeX{} comme \cs{makebox} et \cs{parbox} : on ne peut spécifier une |
| 300 |
% valeur pour le troisième argument optionnel que si on l'a fait pour |
| 301 |
% les deux premiers. Par exemple, dans l'exemple du début, remarquez |
| 302 |
% comment j'avais pris soin de placer l'argument obligatoire au milieu |
| 303 |
% pour séparer les arguments optionnels. |
| 304 |
% |
| 305 |
% Cependant, ce n'est pas très pratique, et on aimerait pouvoir choisir |
| 306 |
% l'ordre des arguments plutôt selon leur sens, sans se poser de |
| 307 |
% questions. Bien, la clé |usedefault| est justement là pour ça : |
| 308 |
% incluez-la dans la \meta{liste}, et vous pouvez désormais utiliser |
| 309 |
% |[]| pour sauter un argument optionnel, en utilisant sa valeur par |
| 310 |
% défaut. |
| 311 |
% |
| 312 |
% \begin{center} |
| 313 |
% |\newcommandx*\coord[3][2=1,3=n,usedefault]{(#2_{#1},\ldots,#2_{#3})}| |
| 314 |
% \newcommandx*\coord[3][2=1, 3=n, usedefault]{(#2_{#1},\ldots,#2_{#3})} |
| 315 |
% \par\medskip |
| 316 |
% \begin{tabular}{ll} |
| 317 |
% |$\coord{x}$| & $\coord{x}$ \\ |
| 318 |
% |$\coord{y}[0]$| & $\coord{y}[0]$ \\ |
| 319 |
% |$\coord{z}[][m]$| & $\coord{z}[][m]$ \\ |
| 320 |
% |$\coord{t}[0][m]$| & $\coord{t}[0][m]$ \\ |
| 321 |
% \end{tabular} |
| 322 |
% \end{center} |
| 323 |
% |
| 324 |
% Bien sûr, sur cet exemple simple, c'est surtout une histoire de goût, |
| 325 |
% mais parfois |usedefault| peut vous épargner pas mal de frappe |
| 326 |
% inutile, car la valeur par défaut d'un argument est parfois longue, et |
| 327 |
% qu'on a pas toujours assez d'arguments obligatoires pour séparer les |
| 328 |
% arguments optionnels comme plus haut. |
| 329 |
% |
| 330 |
% Cette utilisation simple de |usedefault| présente un inconvénient : |
| 331 |
% vous ne pouvez plus spécifier la valeur vide pour un argument |
| 332 |
% optionnel. En fait, il faut nécessairement une valeur spéciale de |
| 333 |
% l'argument pour dire \og utiliser la valeur par défaut \fg{}, mais ce |
| 334 |
% n'est pas nécessairement la chaîne vide : en fait, on peut choisir |
| 335 |
% cette valeur en disant |usedefault=|\meta{valeur}. L'exemple suivant |
| 336 |
% ne sert à rien, à part illustrer ceci. |
| 337 |
% |
| 338 |
% \begin{center} |
| 339 |
% |\newcommandx*\test[2][1=A, 2=B, usedefault=@]{(#1,#2)}| |
| 340 |
% \newcommandx*\test[2][1=A, 2=B, usedefault=@]{(#1,#2)} |
| 341 |
% \par\medskip |
| 342 |
% \begin{tabular}{ll} |
| 343 |
% |\test[b]| & \test[b] \\ |
| 344 |
% |\test[][b]| & \test[][b] \\ |
| 345 |
% |\test[@][b]| & \test[@][b] \\ |
| 346 |
% \end{tabular} |
| 347 |
% \end{center} |
| 348 |
% |
| 349 |
% \subsection{Ajouter un préfixe} |
| 350 |
% |
| 351 |
% La commande |\newcommand| standard permet de définir au choix des |
| 352 |
% macros \og longues \fg{} (dont les arguments peuvent contenir des |
| 353 |
% \cs{par}) ou \og courtes \fg{} (les \cs{par} ou lignes vides sont |
| 354 |
% interdits dans les arguments) au moyen de l'étoile optionnelle. C'est |
| 355 |
% une partie de ce que \TeX{} appelle un préfixe, plus précisément la |
| 356 |
% composante \cs{long}. Les autres composantes d'un préfixe peuvent être |
| 357 |
% \cs{global}, \cs{outer}, ou (avec \eTeX) \cs{protected}. Il n'y a pas |
| 358 |
% de moyen d'utiliser ces composantes avec \cs{newcommand}, bien que, |
| 359 |
% par exemple, \cs{global} puisse être utile pour qu'une définition |
| 360 |
% faite à l'intérieur d'un groupe (comme un environnement) ne soit pas |
| 361 |
% \og oubliée \fg{} à la fin. (Pour des détails sur les autres, voir le |
| 362 |
% \TeX book ou le manuel d'\eTeX.) |
| 363 |
% |
| 364 |
% Avec \pf{xargs}, vous pouvez utiliser la clé |addprefix|, \emph{sauf} |
| 365 |
% pour la composante \cs{outer}, qui n'est pas et ne sera pas supportée |
| 366 |
% (et, à ma connaissance n'est jamais utilisée dans \LaTeXe). Remarquons |
| 367 |
% que cette clé \emph{ajoute} une préfixe à celui en cours, elle |
| 368 |
% n'écrase rien. Au début, le préfixe par défaut est \cs{long}, ou vide |
| 369 |
% si une étoile a été utilisée. Par exemple, les deux instructions |
| 370 |
% suivantes ont exactement le même effet. |
| 371 |
% |
| 372 |
% \begin{quote} |
| 373 |
% |\newcommandx*\truc[0][addprefix=\global, addprefix=\long,|\\ |
| 374 |
% | addprefix=\protected]{machin}|\\ |
| 375 |
% |\newcommandx\truc[0][addprefix=\global\protected]{machin}| |
| 376 |
% \end{quote} |
| 377 |
% |
| 378 |
% En passant, les macros avec au moins un argument optionnel sont |
| 379 |
% définies de façon robuste au sens que \LaTeXe{} donne à ce mot, je ne |
| 380 |
% sais donc pas si le préfixe \cs{protected} est très utile. Je pense |
| 381 |
% que la possibilité d'effectuer des définitions globales est l'usage |
| 382 |
% principale de la clé |usedefault|. |
| 383 |
% |
| 384 |
% \subsection{Compatibilité et limitations connues} |
| 385 |
% |
| 386 |
% La mauvaise nouvelle (les limitations) en premier. Il y en a |
| 387 |
% essentiellement une : on ne peut pas utiliser dans la \meta{liste} |
| 388 |
% certaines choses, qui ne sont pas gérées correctement par |
| 389 |
% \pf{xkeyval}. Précisément, il s'agit des signes |#| (les lexèmes de |
| 390 |
% \cs{catcode} $6$) et des lexèmes \cs{par}. Aussi, aucune composante |
| 391 |
% de la \meta{liste} ne doit avoir l'air mal équilibrée en \cs{if}s aux |
| 392 |
% yeux de \TeX. Seule la première de ces limitations est partagée pas le |
| 393 |
% \cs{newcommand} standard, qui n'accepte pas non plus de |#| dans les |
| 394 |
% valeurs par défaut. Autrement, vous pouvez utiliser ce que vous |
| 395 |
% voulez, où vous voulez (autant que je sache). |
| 396 |
% |
| 397 |
% Maintenant les bonnes nouvelles. J'ai pris grand soin que les macros |
| 398 |
% définies avec \pf{xargs} ressemblent autant que possibles à celles |
| 399 |
% définies avec les commandes standard de \LaTeX. En fait, quand on |
| 400 |
% demande à \cs{newcommandx} d'effectuer une définition que |
| 401 |
% \cs{newcommand} aurait pu faire, la commande sera définie exactement |
| 402 |
% comme si on avait utilisé ce dernier. Plus précisément, le code |
| 403 |
% suivant (et les tests similaires) ne renvoie pas d'avertissement. |
| 404 |
% |
| 405 |
% \begin{quote} |
| 406 |
% |\newcommandx\truc[2][1=default]{def-truc}|\\ |
| 407 |
% |\CheckCommand\truc[2][default]{def-truc}|\\ |
| 408 |
% |\newcommand\chose{def-chose}|\\ |
| 409 |
% |\CheckCommandx*\chose[0][addprefix=\long]{def-chose}| |
| 410 |
% \end{quote} |
| 411 |
% |
| 412 |
% De plus, il y a seulement trois points (Ã ma connaissance) sur |
| 413 |
% lesquels les commandes d'\pf{xargs} diffèrent de celles de \LaTeX{}. |
| 414 |
% Le premier a déjà été évoqué, c'est la limitation sur le \meta{liste} |
| 415 |
% due à \pf{xkeyval}. Les deuxièmes et troisièmes points, par contre, |
| 416 |
% sont censés être positifs. Le deuxième est donc, que j'ai essayé |
| 417 |
% d'éviter de reproduire dans \cs{CheckCommandx} deux |
| 418 |
% problèmes\footnote{% |
| 419 |
% \url{http://www.latex-project.org/cgi-bin/ltxbugs2html?pr=latex/3971}} |
| 420 |
% dont souffre l'implémentation actuelle de \cs{CheckCommand} dans |
| 421 |
% \LaTeX. |
| 422 |
% |
| 423 |
% Le dernier point concerne la gestion des espaces, lors de la recherche |
| 424 |
% du prochain caractère, pour déterminer s'il s'agit ou non d'un crocher |
| 425 |
% carré, quand on teste la présence d'un argument optionnel. Pour ceci, |
| 426 |
% je n'utilise ni la version du noyau, ni celle d'\pf{amsmath}, de |
| 427 |
% \cs{@ifnextchar}, mais la mienne, qui a le comportement suivant : elle |
| 428 |
% avale les espaces jusqu'à trouver le prochain caractère, puis les |
| 429 |
% restitue si ce n'était pas le début d'un argument optionnel. Je ne |
| 430 |
% suis plus tout à fait sûr que ce soit la bonne façon de faire, et il |
| 431 |
% est probable que je ferai une option à ce sujet dans une prochaine |
| 432 |
% version, afin que l'utilisateur puisse choisir son comportement |
| 433 |
% préféré. |
| 434 |
% |
| 435 |
% \bigskip |
| 436 |
% |
| 437 |
% \begin{quote} |
| 438 |
% Vous savez maintenant absolument tout ce qu'il y a à savoir sur |
| 439 |
% l'utilisation de \pf{xargs}. Si vous souhaitez vous pencher sur son |
| 440 |
% implémentation, il vous faudra lire les commentaires en anglais car je |
| 441 |
% n'ai pas eu le courage de commenter mon code en deux langues. |
| 442 |
% \end{quote} |
| 443 |
% |
| 444 |
% \begin{center}\large |
| 445 |
% C'est tout pour cette fois ! \\ |
| 446 |
% Amusez-vous bien avec \LaTeX{} ! |
| 447 |
% \end{center} |
| 448 |
% |
| 449 |
% \else |
| 450 |
% |
| 451 |
% \subsection{Basics} |
| 452 |
% |
| 453 |
% ^^A \DescribeMacro{\newcommandx} |
| 454 |
% ^^A \DescribeMacro{\renewcommandx} |
| 455 |
% ^^A \DescribeMacro{\newenvironmentx} |
| 456 |
% ^^A \DescribeMacro{\renewenvironmentx} |
| 457 |
% ^^A \DescribeMacro{\providecommandx} |
| 458 |
% ^^A \DescribeMacro{\DeclareRobustCommandx} |
| 459 |
% ^^A \DescribeMacro{\CheckCommandx} |
| 460 |
% The \pf{xargs} package defines an extended variant for every \LaTeX{} |
| 461 |
% macro related to macro definition. \pf{xargs}'s macro are named after |
| 462 |
% their \LaTeX{} counterparts, just adding an |x| at end (see the list |
| 463 |
% in the margin). Here is the complete list: |
| 464 |
% |
| 465 |
% \begin{center} |
| 466 |
% \begin{tabular}{ll} |
| 467 |
% \cs{newcommandx} & \cs{renewcommandx} \\ |
| 468 |
% \cs{newenvironmentx} & \cs{renewenvironmentx} \\ |
| 469 |
% \cs{providecommandx} & \cs{DeclareRobustCommandx} \\ |
| 470 |
% \cs{CheckCommandx} |
| 471 |
% \end{tabular} |
| 472 |
% \end{center} |
| 473 |
% |
| 474 |
% If you are not familiar with all of them, you can either just keep |
| 475 |
% using the commands you already know, or check Lamport's book or the |
| 476 |
% \LaTeX{} Companion (or any \LaTeXe{} manual) to learn the others. |
| 477 |
% |
| 478 |
% \medbreak |
| 479 |
% |
| 480 |
% Since these commands all share the same syntax, I'll always use |
| 481 |
% \cs{newcommandx} in the following, but remember it works the same for |
| 482 |
% all seven commands. (Of course, command about environments take one |
| 483 |
% more argument, for the end definition.) Here is |\newcommandx|'s |
| 484 |
% complete syntax. |
| 485 |
% |
| 486 |
% \begin{center} |
| 487 |
% \cs{newcommandx}\optstar\marg{command}\oarg{number}\oarg{list}^^A |
| 488 |
% \marg{definition} |
| 489 |
% \end{center} |
| 490 |
% |
| 491 |
% Everything here is the same as the usual \cs{newcommand} syntax, |
| 492 |
% except \meta{list}. Let's recall this briefly. The optional $*$ make |
| 493 |
% \LaTeX{} define a ``short'' macro, that is a macro that won't accept a |
| 494 |
% paragraph break (\cs{par} or an empty line) inside its argument; if |
| 495 |
% you don't put it, the macro will be long. \meta{command} is any |
| 496 |
% control sequence, and can but need not be enclosed in braces, as you |
| 497 |
% like. The \meta{number} specifies how many arguments your macro will |
| 498 |
% take (including optional ones): it should be a non-negative integer, |
| 499 |
% and at most $9$. The macro's \meta{definition} is a balanced text, |
| 500 |
% where every |#| sign must be followed by a number, thus representing |
| 501 |
% an argument, or by another |#| sign. The two arguments \meta{number} |
| 502 |
% and \meta{list} are optionals. |
| 503 |
% |
| 504 |
% \medskip |
| 505 |
% |
| 506 |
% Now comes the new and funny part. \meta{list} is a coma-separated list |
| 507 |
% of element \meta{digit}=\meta{value}. Here, \meta{digit} should be |
| 508 |
% non-zero, and at most \meta{number} (the total number of arguments). |
| 509 |
% The \meta{value} is any balanced text, and can be empty. If so, the |
| 510 |
% |=| sign becomes optional: You only need to write \meta{digit} if you |
| 511 |
% want the \meta{digit}th argument to be optional, with empty default |
| 512 |
% value. Of course, every argument whose number is a \meta{digit} in the |
| 513 |
% \meta{list} becomes optional, with \meta{value} as its default value. |
| 514 |
% |
| 515 |
% If you are not very familiar with some aspects of the syntax provided |
| 516 |
% by the \pf{xkeyval} package, you may be interested in the following |
| 517 |
% remarks about the syntax of \meta{list}. Since \meta{list} is |
| 518 |
% coma-separated, if you want to use a coma inside a \meta{value}, you |
| 519 |
% need to enclose it (either the coma or the whole \meta{value}) in |
| 520 |
% braces. The same applies if you want to use a closing square bracket |
| 521 |
% inside the \meta{list}. Don't worry about those unwanted braces, they |
| 522 |
% will be removed later. Actually, \pf{xkeyval} removes up to $3$ braces |
| 523 |
% set: If you really want braces around a value, you need to type |
| 524 |
% something like |1={{{{\large stuff}}}}|. |
| 525 |
% |
| 526 |
% \medskip |
| 527 |
% |
| 528 |
% That's all for the basics: you are now ready to use \pf{xargs}, and |
| 529 |
% can stop reading this doc now if you want. If, however, you are |
| 530 |
% wondering about what happens if you have many successive optional |
| 531 |
% arguments, or care about doing global definitions, or even need to |
| 532 |
% know precisely the limitations of \pf{xargs}, go on with the next |
| 533 |
% subsections. |
| 534 |
% |
| 535 |
% \subsection{The \texttt{usedefault} key} |
| 536 |
% |
| 537 |
% So, what happens with many successive optional arguments? The default |
| 538 |
% behaviour is that of \LaTeX's commands like \cs{makebox} or |
| 539 |
% \cs{parbox}: you can't specify the third argument if you didn't |
| 540 |
% specify the first two ones. For example, in my first example, please |
| 541 |
% notice how I used the mandatory argument to separate the two optional |
| 542 |
% ones. |
| 543 |
% |
| 544 |
% However, maybe you don't like this and prefer choosing your argument's |
| 545 |
% order as you want, according to their logical meaning. Ok. That's |
| 546 |
% exactly what the |usedefault| key is for. Just include it in the |
| 547 |
% \meta{list}, and you can now use |[]| to skip one optional argument |
| 548 |
% (using its default value) and go to the next one. |
| 549 |
% |
| 550 |
% \begin{center} |
| 551 |
% |\newcommandx*\coord[3][2=1,3=n,usedefault]{(#2_{#1},\ldots,#2_{#3})}| |
| 552 |
% \newcommandx*\coord[3][2=1, 3=n, usedefault]{(#2_{#1},\ldots,#2_{#3})} |
| 553 |
% \par\medskip |
| 554 |
% \begin{tabular}{ll} |
| 555 |
% |$\coord{x}$| & $\coord{x}$ \\ |
| 556 |
% |$\coord{y}[0]$| & $\coord{y}[0]$ \\ |
| 557 |
% |$\coord{z}[][m]$| & $\coord{z}[][m]$ \\ |
| 558 |
% |$\coord{t}[0][m]$| & $\coord{t}[0][m]$ \\ |
| 559 |
% \end{tabular} |
| 560 |
% \end{center} |
| 561 |
% |
| 562 |
% Of course, on this simple example, this is merely a matter of |
| 563 |
% taste, but sometimes the |usedefault| key can save you a lot of |
| 564 |
% typing, since the optional value for an argument can be rather long, |
| 565 |
% and you don't always have enough mandatory arguments to separate the |
| 566 |
% optional ones. |
| 567 |
% |
| 568 |
% This simple way of using |usedefault| has one problem: you can no more |
| 569 |
% specify an empty value for an optional argument. Of course you need a |
| 570 |
% special value of the argument to mean ``please use the default value |
| 571 |
% there'', but it doesn't need to be always the empty string. Actually, |
| 572 |
% you can say |usedefaut=|\meta{flag} to choose this special value. The |
| 573 |
% following example has no other purpose that illustrating this. |
| 574 |
% |
| 575 |
% \begin{center} |
| 576 |
% |\newcommandx*\test[2][1=A, 2=B, usedefault=@]{(#1,#2)}| |
| 577 |
% \newcommandx*\test[2][1=A, 2=B, usedefault=@]{(#1,#2)} |
| 578 |
% \par\medskip |
| 579 |
% \begin{tabular}{ll} |
| 580 |
% |\test[b]| & \test[b] \\ |
| 581 |
% |\test[][b]| & \test[][b] \\ |
| 582 |
% |\test[@][b]| & \test[@][b] \\ |
| 583 |
% \end{tabular} |
| 584 |
% \end{center} |
| 585 |
% |
| 586 |
% \subsection{Using a prefix} |
| 587 |
% |
| 588 |
% Standard |\newcommand| allows you to define so-called ``long'' (i. e. |
| 589 |
% the arguments may contain a \cs{par} token) or ``short'' (they |
| 590 |
% may not) macros with the optional star. This is part of what \TeX{} |
| 591 |
% calls a ``prefix'' for the definition, namely the \cs{long} prefix. |
| 592 |
% Other components of the prefix are \cs{global}, \cs{outer}, and |
| 593 |
% \eTeX's \cs{protected}. There is no way to use them with |
| 594 |
% |\newcommand|, though \cs{global} can be specially interesting in |
| 595 |
% order to avoid definitions made inside a group (e. g. an environment) |
| 596 |
% ``disappear'' at the end of the group. (For details about the other |
| 597 |
% possible components, see the \TeX book and \eTeX's manual.) |
| 598 |
% |
| 599 |
% With \pf{xargs}, you can use the |addprefix| key, \emph{except} for |
| 600 |
% the \cs{outer} prefix, which is not and will not be supported (and not |
| 601 |
% used anywhere I know in \LaTeXe, either). Please note that it |
| 602 |
% \emph{adds} a prefix to the current one, which by default is \cs{long} |
| 603 |
% for the unstarred form, and empty for the starred form. You can also |
| 604 |
% use this key many times: all prefixes will be merged together. For |
| 605 |
% example, the following two instructions do the exactly the same thing. |
| 606 |
% |
| 607 |
% \begin{quote} |
| 608 |
% |\newcommandx*\foo[0][addprefix=\global, addprefix=\long,|\\ |
| 609 |
% | addprefix=\protected]{bar}|\\ |
| 610 |
% |\newcommandx\foo[0][addprefix=\global\protected]{bar}| |
| 611 |
% \end{quote} |
| 612 |
% |
| 613 |
% By the way, macros with at least one optional argument are already |
| 614 |
% robust in \LaTeXe's meaning of the word, so I don't know if the |
| 615 |
% \cs{protected} prefix is very interesting there. Maybe the ability to |
| 616 |
% perform global definitions is the main use of the |addprefix| key. |
| 617 |
% |
| 618 |
% \subsection{Compatibility and known limitations} |
| 619 |
% |
| 620 |
% Okay, let's see the bad things (the limitations) first. There is |
| 621 |
% essentially one: you cannot use in the \meta{list} some elements, |
| 622 |
% because \pf{xkeyval} won't handle them properly. Namely, hash signs |
| 623 |
% (tokens with \cs{catcode} $6$), and \cs{par} tokens are forbidden, and |
| 624 |
% any part of the list should look properly \cs{if}-balanced to \TeX. |
| 625 |
% Only the first limitation is shared by the standard \cs{newcommand}: |
| 626 |
% it accepts no hash signs in a default value. Apart from this, you can |
| 627 |
% use anything you want, everywhere you want, as far as I know. |
| 628 |
% |
| 629 |
% Now the ``good'' features. I've tried hard to make macros defined with |
| 630 |
% \pf{xargs} as much similar as possible with those defined with |
| 631 |
% standard \LaTeX's commands. Actually, when \cs{newcommandx} is asked |
| 632 |
% to perform a definition which \cs{newcommand} can do, the resulting |
| 633 |
% macro will be defined exactly as the latter would have done. More |
| 634 |
% precisely, the following code (and similar tests) issues no warning. |
| 635 |
% |
| 636 |
% \begin{quote} |
| 637 |
% |\newcommandx\foo[2][1=default]{def-foo}|\\ |
| 638 |
% |\CheckCommand\foo[2][default]{def-foo}|\\ |
| 639 |
% |\newcommand\baz{def-baz}|\\ |
| 640 |
% |\CheckCommandx*\baz[0][addprefix=\long]{def-baz}| |
| 641 |
% \end{quote} |
| 642 |
% |
| 643 |
% Moreover, there are only three points (to my knowledge) where |
| 644 |
% \pf{xargs}'s commands differ from the kernel ones. The first one was |
| 645 |
% already mentioned, it is due to using \pf{xkeyval} for precessing the |
| 646 |
% \meta{list}. The second and third points are meant to be good one. |
| 647 |
% Second point is: There is a bug\footnote{% |
| 648 |
% \url{http://www.latex-project.org/cgi-bin/ltxbugs2html?pr=latex/3971}} |
| 649 |
% in the current implementation of \cs{CheckCommand}, that I obviously |
| 650 |
% tried to avoid. |
| 651 |
% |
| 652 |
% Last, I don't use kernel's (nor \pf{amsmath}'s) version of |
| 653 |
% \cs{@ifnextchar}. Indeed, a problem arises when the last argument of a |
| 654 |
% command is optional: we have to make a choice about what to do with |
| 655 |
% spaces while scanning ahead for a left square bracket. I chose to scan |
| 656 |
% over them, and the put them back in the text in there were no |
| 657 |
% optional argument. I'm no more sure it is the right thing to do, and |
| 658 |
% I'll probably make an option to let the user decide in a future |
| 659 |
% version. |
| 660 |
% |
| 661 |
% \fi |
| 662 |
% |
| 663 |
% \StopEventually{} |
| 664 |
% |
| 665 |
% \section{Implementation} |
| 666 |
% |
| 667 |
% First, I'd like to recall the way \LaTeXe{} handles optional |
| 668 |
% arguments. For example, a command \cs{foo} defined with |
| 669 |
% |\newcommand*\foo[2][bar]{baz}| is implemented as the pair: |
| 670 |
% \begin{quote} |
| 671 |
% |\foo=macro:->\@protected@testopt\foo\\foo{bar}| \\ |
| 672 |
% |\\foo=macro:[#1]#2->baz| |
| 673 |
% \end{quote} |
| 674 |
% There is one ``external'' macro \cs{foo}, which is merely an argument |
| 675 |
% grabber or a parser, and an internal macro \cs{\string\foo}, which is |
| 676 |
% the ``real'' one. In \pf{xargs} this is quite the same, except that |
| 677 |
% the external macro is a bit more sophisticated. This idea of the |
| 678 |
% external macro being a parser, giving the arguments to the internal |
| 679 |
% one in a standard form, reflects in the name of \LaTeX3's experimental |
| 680 |
% package for extended argument syntax: \pf{xparse}. |
| 681 |
% |
| 682 |
% Here the approach is a bit different. Of course, the idea is still to |
| 683 |
% build a parser for the specified syntax, but since \cs{newcommandx} |
| 684 |
% user syntax is based on \pf{xkeyval}, we also have to care about keys |
| 685 |
% and there default values, and to put the whole thing in the correct |
| 686 |
% order before we build up the parser. We also seek for compatibility |
| 687 |
% with existing \LaTeXe{} commands, which adds a few tests. The |
| 688 |
% organisation is as follows. |
| 689 |
% |
| 690 |
% \begingroup \def\leaders#1#2{} |
| 691 |
% \secttoc[n] |
| 692 |
% \endgroup |
| 693 |
% |
| 694 |
% Before we really begin, just a few preliminaries. |
| 695 |
% First, load the \pf{xkeyval} package for it's nice key=value syntax. |
| 696 |
% \begin{macrocode} |
| 697 |
\RequirePackage{xkeyval} |
| 698 |
% \end{macrocode} |
| 699 |
% |
| 700 |
% \begin{macro}{\xargs@max} |
| 701 |
% \begin{macro}{\xargs@temp} |
| 702 |
% \begin{macro}{\xargs@toksa} |
| 703 |
% \begin{macro}{\xargs@toksb} |
| 704 |
% Then allocate a few registers and make sure the name of our private scratch |
| 705 |
% macro is free for use. Note that for certain uses, we really need a |
| 706 |
% \cs{toks} register because the string used can possibly contain |#| |
| 707 |
% characters. Sometimes I also use a \cs{toks} register instead of a macro |
| 708 |
% just for ease of use (writing less \cs{expandafter}s). |
| 709 |
% \begin{macrocode} |
| 710 |
\@ifdefinable\xargs@max{\newcount\xargs@max} |
| 711 |
% \end{macrocode} |
| 712 |
% \begin{macrocode} |
| 713 |
\@ifdefinable\xargs@temp\relax |
| 714 |
\@ifdefinable\xargs@toksa{\newtoks\xargs@toksa} |
| 715 |
\@ifdefinable\xargs@toksb{\newtoks\xargs@toksb} |
| 716 |
% \end{macrocode} |
| 717 |
% \end{macro} |
| 718 |
% \end{macro} |
| 719 |
% \end{macro} |
| 720 |
% \end{macro} |
| 721 |
% |
| 722 |
% \subsection{Parser} |
| 723 |
% |
| 724 |
% Let's begin with a simple, concrete example. Recall that we defined a |
| 725 |
% command \cs{vect} with |
| 726 |
% |\newcommandx\vect[3]{1=0,3=n}{(#2_{#1},\ldots,#2_{#3}}| and have a |
| 727 |
% look at its implementation. |
| 728 |
% \begin{quote} |
| 729 |
% |\vect=macro:->\@protected@testopt@xargs\vect\\vect|\\ |
| 730 |
% \hspace*{1em}|{\xargs@test@opt{0},\xargs@put@arg,\xargs@test@opt{n},}|\\ |
| 731 |
% |\\vect=macro:[#1]#2[#3]->(#2_{#1},\ldots ,#2_{#3})| |
| 732 |
% \end{quote} |
| 733 |
% |
| 734 |
% As you can see, the parser is stored as a coma-separated list of |
| 735 |
% ``actions''. Here the only actions are to grab a mandatory argument or |
| 736 |
% to check for the presence of of an optional one. In this case, special |
| 737 |
% care is taken about spaces. Actually, there can be one more action, |
| 738 |
% associated with the |usedefaut| user key: \cs{xargs@setdefflag}, which |
| 739 |
% specifies the flag that says ``use the default value''. |
| 740 |
% |
| 741 |
% The parsing is done by a loop that read and executes each action from |
| 742 |
% the originating list, and concurrently builds an argument list such as |
| 743 |
% |[0]{x}[m]| to be passed to |\\vect| for example. All of this happens |
| 744 |
% inside a group. |
| 745 |
% |
| 746 |
% \begin{macro}{\@protected@testop@xargs} |
| 747 |
% This first macro closely resembles kernel's \cs{@protected@testopt} |
| 748 |
% (similarity in their names is intentional, see \cs{CheckCommandx}). It |
| 749 |
% just checks the protection context and call the real argument grabbing |
| 750 |
% macro. |
| 751 |
% \begin{macrocode} |
| 752 |
\newcommand*\@protected@testopt@xargs[1]{% |
| 753 |
\ifx\protect\@typeset@protect |
| 754 |
\expandafter\xargs@read |
| 755 |
\else |
| 756 |
\@x@protect#1% |
| 757 |
\fi} |
| 758 |
% \end{macrocode} |
| 759 |
% \end{macro} |
| 760 |
% \begin{macro}{\xargs@read} |
| 761 |
% Initiate the loop. \cs{xargs@toksa} will become the call to the |
| 762 |
% internal macro with all arguments, \cs{xargs@toksb} contains the |
| 763 |
% actions list for arguments grabbing. |
| 764 |
% \begin{macrocode} |
| 765 |
\newcommand*\xargs@read[2]{% |
| 766 |
\begingroup |
| 767 |
\xargs@toksa{#1}% |
| 768 |
\xargs@toksb{#2}% |
| 769 |
\xargs@continue} |
| 770 |
% \end{macrocode} |
| 771 |
% \end{macro} |
| 772 |
% \begin{macro}{\xargs@continue} |
| 773 |
% \begin{macro}{\xargs@pick@next} |
| 774 |
% Each iteration of the loop consist of two steps: pick the next action |
| 775 |
% (and remove it from the list), and execute it. When there is no more |
| 776 |
% action in the list, it means the arguments grabbing stage is over, and |
| 777 |
% it's time to execute the internal macro by expanding the contents of |
| 778 |
% \cs{xargs@toksa}. |
| 779 |
% \begin{macrocode} |
| 780 |
\newcommand\xargs@continue{% |
| 781 |
\expandafter\xargs@pick@next\the\xargs@toksb,\@nil |
| 782 |
\xargs@temp} |
| 783 |
% \end{macrocode} |
| 784 |
% \begin{macrocode} |
| 785 |
\@ifdefinable\xargs@pick@next{% |
| 786 |
\def\xargs@pick@next#1,#2\@nil{% |
| 787 |
\def\xargs@temp{#1}% |
| 788 |
\xargs@toksb{#2}% |
| 789 |
\ifx\xargs@temp\empty |
| 790 |
\def\xargs@temp{\expandafter\endgroup\the\xargs@toksa}% |
| 791 |
\fi}} |
| 792 |
% \end{macrocode} |
| 793 |
% \end{macro} |
| 794 |
% \end{macro} |
| 795 |
% \begin{macro}{\xargs@set@defflag} |
| 796 |
% Let's begin with the most simple action. |
| 797 |
% \begin{macrocode} |
| 798 |
\newcommand*\xargs@set@defflag[1]{% |
| 799 |
\def\xargs@default@flag{#1}} |
| 800 |
% \end{macrocode} |
| 801 |
% \end{macro} |
| 802 |
% \begin{macro}{\xargs@put@arg} |
| 803 |
% \begin{macro}{\xargs@test@opt} |
| 804 |
% \begin{macro}{\xargs@put@opt} |
| 805 |
% Now have a look at the argument grabbing macros. The first one, |
| 806 |
% \cs{xargs@put@arg}, just reads an undelimited argument in the input stack |
| 807 |
% and add it to the arguments list. \cs{xargs@testopt} checks if the next |
| 808 |
% non-space token is a square bracket to decide if it have to read an argument |
| 809 |
% from the input or use the default value, and takes care to enclose it in |
| 810 |
% square brackets. |
| 811 |
% \begin{macrocode} |
| 812 |
\newcommand\xargs@put@arg[1]{% |
| 813 |
\xargs@toksa\expandafter{\the\xargs@toksa{#1}}% |
| 814 |
\xargs@continue} |
| 815 |
% \end{macrocode} |
| 816 |
% \begin{macrocode} |
| 817 |
\newcommand*\xargs@test@opt[1]{% |
| 818 |
\xargs@ifnextchar[%] |
| 819 |
{\xargs@grab@opt{#1}}% |
| 820 |
{\xargs@put@opt{#1}}} |
| 821 |
% \end{macrocode} |
| 822 |
% \begin{macrocode} |
| 823 |
\newcommand\xargs@put@opt[1]{% |
| 824 |
\xargs@toksa\expandafter{\the\xargs@toksa[{#1}]}% |
| 825 |
\xargs@continue} |
| 826 |
% \end{macrocode} |
| 827 |
% \begin{macrocode} |
| 828 |
\@ifdefinable\xargs@grab@opt{% |
| 829 |
\long\def\xargs@grab@opt#1[#2]{% |
| 830 |
\toks@{#2}\edef\xargs@temp{\the\toks@}% |
| 831 |
\ifx\xargs@temp\xargs@default@flag |
| 832 |
\expandafter\@firstoftwo |
| 833 |
\else |
| 834 |
\expandafter\@secondoftwo |
| 835 |
\fi{% |
| 836 |
\xargs@put@opt{#1}% |
| 837 |
}{% |
| 838 |
\xargs@put@opt{#2}}}} |
| 839 |
% \end{macrocode} |
| 840 |
% \end{macro} |
| 841 |
% \end{macro} |
| 842 |
% \end{macro} |
| 843 |
% \begin{macro}{\xargs@ifnextchar} |
| 844 |
% \begin{macro}{\xargs@ifnch} |
| 845 |
% \begin{macro}{\xargs@xifnch} |
| 846 |
% Here comes a modified version of \cs{@ifnextchar}, that works like |
| 847 |
% kernel's one, except that it remembers how many spaces it gobbles and |
| 848 |
% puts them back in case the next non-space character isn't a match. Not |
| 849 |
% sure whether this is the better way to do, may change in future |
| 850 |
% versions. |
| 851 |
% \begin{macrocode} |
| 852 |
\newcommand\xargs@ifnextchar[3]{% |
| 853 |
\let\xargs@temp\empty |
| 854 |
\let\reserved@d=#1% |
| 855 |
\def\reserved@a{#2}% |
| 856 |
\def\reserved@b{#3}% |
| 857 |
\futurelet\@let@token\xargs@ifnch} |
| 858 |
% \end{macrocode} |
| 859 |
% \begin{macrocode} |
| 860 |
\newcommand\xargs@ifnch{% |
| 861 |
\ifx\@let@token\@sptoken |
| 862 |
\edef\xargs@temp{\xargs@temp\space}% |
| 863 |
\let\reserved@c\xargs@xifnch |
| 864 |
\else |
| 865 |
\ifx\@let@token\reserved@d |
| 866 |
\let\reserved@c\reserved@a |
| 867 |
\else |
| 868 |
\def\reserved@c{\expandafter\reserved@b\xargs@temp}% |
| 869 |
\fi |
| 870 |
\fi |
| 871 |
\reserved@c} |
| 872 |
% \end{macrocode} |
| 873 |
% \begin{macrocode} |
| 874 |
\@ifdefinable\xargs@xifnch{% |
| 875 |
\expandafter\def\expandafter\xargs@xifnch\space{% |
| 876 |
\futurelet\@let@token\xargs@ifnch}} |
| 877 |
% \end{macrocode} |
| 878 |
% \end{macro} |
| 879 |
% \end{macro} |
| 880 |
% \end{macro} |
| 881 |
% |
| 882 |
% \subsection{Keys} |
| 883 |
% |
| 884 |
% Okay, we are done with the parsing related macros. Now define stuff |
| 885 |
% for the definition of macros. In this part we use \pf{xkeyval}. Let's |
| 886 |
% start with the particular keys for options |addprefix| and |default|. |
| 887 |
% Like all \pf{xargs} key, we use the prefix |xargs| and the familly |
| 888 |
% |key|. The |addprefix| key can be used many times : each value is |
| 889 |
% appended at the end of the current prefix. Actually, we also construct |
| 890 |
% a ``short'' prefix (without any \cs{long}), for the external macro. We |
| 891 |
% define them globally, since key processing will happen inside a group, |
| 892 |
% and the definition outside. |
| 893 |
% \begin{macrocode} |
| 894 |
\@ifdefinable\xargs@key@addprefix{% |
| 895 |
\define@key[xargs]{key}{addprefix}[]{% |
| 896 |
\global\expandafter\def\expandafter\xargs@prefix\expandafter{% |
| 897 |
\xargs@prefix#1}% |
| 898 |
\xargs@makeshort#1\long\@nil}} |
| 899 |
% \end{macrocode} |
| 900 |
% The \cs{long} tokens are removed from the prefix in a fast and easy |
| 901 |
% way, assuming the input is a correct prefix. (It will crash e.g. if |
| 902 |
% the input contains an undefined CS or braces, but this will make all |
| 903 |
% crash later anyway. By the way, we also assume the prefix contains no |
| 904 |
% macro parameter token\ldots) |
| 905 |
% \begin{macrocode} |
| 906 |
\@ifdefinable\xargs@makeshort{% |
| 907 |
\def\xargs@makeshort#1\long#2{% |
| 908 |
\expandafter\gdef\expandafter\xargs@shortpref\expandafter{% |
| 909 |
\xargs@shortpref#1}% |
| 910 |
\ifx#2\@nil \else |
| 911 |
\expandafter\xargs@makeshort\expandafter#2% |
| 912 |
\fi}} |
| 913 |
% \end{macrocode} |
| 914 |
% The initial prefixes will be fixed by \cs{newcommandx} and its friends |
| 915 |
% when they check the star: empty in the stared version, \cs{long} |
| 916 |
% otherwise. For this, they use \pf{xargs}'s variant or |
| 917 |
% \cs{@star@or@long}: |
| 918 |
% \begin{macrocode} |
| 919 |
\newcommand\xargs@star@or@long[1]{% |
| 920 |
\global\let\xargs@shortpref\@empty |
| 921 |
\@ifstar{\gdef\xargs@prefix{}#1}{\gdef\xargs@prefix{\long}#1}} |
| 922 |
% \end{macrocode} |
| 923 |
% |
| 924 |
% Now, another particular key is the |usedefault| key. When used, it |
| 925 |
% just sets \cs{xargs@default@flag} and the corresponding boolean. Later |
| 926 |
% on, this will be used to possibly introduce a \cs{xargs@set@default} |
| 927 |
% action at the beginning of the actions list. |
| 928 |
% \begin{macrocode} |
| 929 |
\define@key[xargs]{key}{usedefault}[]{% |
| 930 |
\xargs@toksa{#1}\edef\xargs@default@flag{\the\xargs@toksa}} |
| 931 |
% \end{macrocode} |
| 932 |
% |
| 933 |
% \medskip |
| 934 |
% |
| 935 |
% Let's continue with the more important keys. We have to collect |
| 936 |
% through \pf{xkeyval} at most 9 actions numbered 1 to \cs{xargs@max} |
| 937 |
% (the total number of arguments), each of them being |
| 938 |
% \cs{xargs@test@opt} or \cs{xargs@put@arg}. Latter, we will use them to |
| 939 |
% build up the parser. |
| 940 |
% |
| 941 |
% \begin{macro}{\@namenewc} \begin{macro}{\xargs@action@1} |
| 942 |
% \begin{macro}{\xargs@action@2} \begin{macro}{\xargs@action@3} |
| 943 |
% \begin{macro}{\xargs@action@4} \begin{macro}{\xargs@action@5} |
| 944 |
% \begin{macro}{\xargs@action@6} \begin{macro}{\xargs@action@7} |
| 945 |
% \begin{macro}{\xargs@action@8} \begin{macro}{\xargs@action@9} |
| 946 |
% So our first task is to define container macros for the at most nine |
| 947 |
% actions which represent arguments parsing, with default value |
| 948 |
% \cs{xargs@put@arg} since every argument is mandatory unless specified. |
| 949 |
% \begin{macrocode} |
| 950 |
\providecommand\@namenewc[1]{% |
| 951 |
\expandafter\newcommand\csname #1\endcsname} |
| 952 |
% \end{macrocode} |
| 953 |
% \begin{macrocode} |
| 954 |
\@namenewc{xargs@action@1}{\xargs@put@arg} |
| 955 |
\@namenewc{xargs@action@2}{\xargs@put@arg} |
| 956 |
\@namenewc{xargs@action@3}{\xargs@put@arg} |
| 957 |
\@namenewc{xargs@action@4}{\xargs@put@arg} |
| 958 |
\@namenewc{xargs@action@5}{\xargs@put@arg} |
| 959 |
\@namenewc{xargs@action@6}{\xargs@put@arg} |
| 960 |
\@namenewc{xargs@action@7}{\xargs@put@arg} |
| 961 |
\@namenewc{xargs@action@8}{\xargs@put@arg} |
| 962 |
\@namenewc{xargs@action@9}{\xargs@put@arg} |
| 963 |
% \end{macrocode} |
| 964 |
% \end{macro} \end{macro} |
| 965 |
% \end{macro} \end{macro} |
| 966 |
% \end{macro} \end{macro} |
| 967 |
% \end{macro} \end{macro} |
| 968 |
% \end{macro} \end{macro} |
| 969 |
% \begin{macro}{\xargs@def@key} |
| 970 |
% The next macro will define the keys. Its first argument is the key's |
| 971 |
% number. The second argument will be discussed later. |
| 972 |
% \begin{macrocode} |
| 973 |
\newcommand*\xargs@def@key[2]{% |
| 974 |
\expandafter\@ifdefinable\csname xargs@key@#1\endcsname{% |
| 975 |
\define@key[xargs]{key}{#1}[]{% |
| 976 |
% \end{macrocode} |
| 977 |
% The first thing do to, before setting any action, is to check whether |
| 978 |
% this key can be used for this command, and complain if not. |
| 979 |
% \begin{macrocode} |
| 980 |
\ifnum\xargs@max<#1 |
| 981 |
\PackageError{xargs}{% |
| 982 |
Illegal argument label in\MessageBreak |
| 983 |
optional arguments description% |
| 984 |
}{% |
| 985 |
You are trying to make optional an argument whose label (#1) |
| 986 |
\MessageBreak is higher than the total number (\the\xargs@max) |
| 987 |
of parameters. \MessageBreak This can't be done and your |
| 988 |
demand will be ignored.}% |
| 989 |
\else |
| 990 |
% \end{macrocode} |
| 991 |
% If the key number is correct, it may be that the user is trying to use |
| 992 |
% it twice for the same command. Since it's probably a mistake, issue a |
| 993 |
% warning in such case. |
| 994 |
% \begin{macrocode} |
| 995 |
\expandafter\expandafter\expandafter |
| 996 |
\ifx\csname xargs@action@#1\endcsname\xargs@put@arg \else |
| 997 |
\PackageWarning{xargs}{% |
| 998 |
Argument #1 was allready given a default value.\MessageBreak |
| 999 |
Previous value will be overriden.\MessageBreak}% |
| 1000 |
\fi |
| 1001 |
% \end{macrocode} |
| 1002 |
% If everything looks okay, define the action to be \cs{xargs@test@opt} |
| 1003 |
% with the given value, and execute the (for now) mysterious second |
| 1004 |
% argument. |
| 1005 |
% \begin{macrocode} |
| 1006 |
\@namedef{xargs@action@#1}{\xargs@test@opt{##1}}% |
| 1007 |
#2% |
| 1008 |
\fi}}} |
| 1009 |
% \end{macrocode} |
| 1010 |
% \end{macro} |
| 1011 |
% \begin{macro}{\ifxargs@firstopt@} |
| 1012 |
% \begin{macro}{\ifxargs@otheropt@} |
| 1013 |
% \begin{macro}{\xargs@key@1} |
| 1014 |
% \begin{macro}{\xargs@key@2} \begin{macro}{\xargs@key@3} |
| 1015 |
% \begin{macro}{\xargs@key@4} \begin{macro}{\xargs@key@5} |
| 1016 |
% \begin{macro}{\xargs@key@6} \begin{macro}{\xargs@key@7} |
| 1017 |
% \begin{macro}{\xargs@key@8} \begin{macro}{\xargs@key@9} |
| 1018 |
% The second argument is used to set the value for some \cs{if} which |
| 1019 |
% will keep track of the existence of an optional argument other than |
| 1020 |
% the first one, and the of the possibly optional nature of the first. |
| 1021 |
% Such information will be useful when we will have to decide if we use |
| 1022 |
% the \LaTeXe{} standard way or \pf{xargs} custom one to define the |
| 1023 |
% macro. |
| 1024 |
% \begin{macrocode} |
| 1025 |
\newif\ifxargs@firstopt@ |
| 1026 |
\newif\ifxargs@otheropt@ |
| 1027 |
% \end{macrocode} |
| 1028 |
% Now actually define the keys. |
| 1029 |
% \begin{macrocode} |
| 1030 |
\xargs@def@key1\xargs@firstopt@true |
| 1031 |
\xargs@def@key2\xargs@otheropt@true \xargs@def@key3\xargs@otheropt@true |
| 1032 |
\xargs@def@key4\xargs@otheropt@true \xargs@def@key5\xargs@otheropt@true |
| 1033 |
\xargs@def@key6\xargs@otheropt@true \xargs@def@key7\xargs@otheropt@true |
| 1034 |
\xargs@def@key8\xargs@otheropt@true \xargs@def@key9\xargs@otheropt@true |
| 1035 |
% \end{macrocode} |
| 1036 |
% \end{macro} \end{macro} \end{macro} |
| 1037 |
% \end{macro} \end{macro} \end{macro} |
| 1038 |
% \end{macro} \end{macro} \end{macro} |
| 1039 |
% \end{macro} \end{macro} |
| 1040 |
% \begin{macro}{\xargs@setkeys} |
| 1041 |
% \begin{macro}{\xargs@check@keys} |
| 1042 |
% We set the keys with the starred version of \cs{setkeys}, so we can |
| 1043 |
% check if there were some strange keys we cannot handle, and issue a |
| 1044 |
% meaningful warning if there are some. |
| 1045 |
% \begin{macrocode} |
| 1046 |
\newcommand\xargs@setkeys[1]{% |
| 1047 |
\setkeys*[xargs]{key}{#1}% |
| 1048 |
\xargs@check@keys} |
| 1049 |
% \end{macrocode} |
| 1050 |
% \begin{macrocode} |
| 1051 |
\newcommand\xargs@check@keys{% |
| 1052 |
\ifx\XKV@rm\empty \else |
| 1053 |
\xargs@toksa\expandafter{\XKV@rm}% |
| 1054 |
\PackageError{xargs}{% |
| 1055 |
Illegal key or argument label in\MessageBreak |
| 1056 |
optional arguments description% |
| 1057 |
}{% |
| 1058 |
You can only use non-zero digits as argument labels.\MessageBreak |
| 1059 |
Other allowed keys are usedefault and addprefix.\MessageBreak |
| 1060 |
You wrote: "\the\xargs@toksa".\MessageBreak |
| 1061 |
I can't understand this and I'm going to ignore it.}% |
| 1062 |
\fi} |
| 1063 |
% \end{macrocode} |
| 1064 |
% \end{macro} |
| 1065 |
% \end{macro} |
| 1066 |
% |
| 1067 |
% \subsection{Definition} |
| 1068 |
% |
| 1069 |
% \begin{macro}{\xargs@add@args} |
| 1070 |
% Now our goal is to build two lists from our up to nine argument |
| 1071 |
% grabbers, the special action |\xargs@setdefflag| and not forgetting |
| 1072 |
% the prefix. The first list is the coma-separated list of actions |
| 1073 |
% already discussed. The second is the parameter text for use in the |
| 1074 |
% definition on the internal macro, for example |[#1]#2[#3]|. The next |
| 1075 |
% macro takes the content of a \cs{xargs@action@X} macro for argument |
| 1076 |
% and adds the corresponding items to this lists. It checks if the first |
| 1077 |
% token of its parameter is \cs{xargs@testopt} in order to know if the |
| 1078 |
% |#n| has to be enclosed in square brackets. |
| 1079 |
% \begin{macrocode} |
| 1080 |
\newcommand\xargs@add@args[1]{% |
| 1081 |
\xargs@toksa\expandafter{\the\xargs@toksa #1,}% |
| 1082 |
\expandafter |
| 1083 |
\ifx\@car#1\@nil\xargs@put@arg |
| 1084 |
\xargs@toksb\expandafter\expandafter\expandafter{% |
| 1085 |
\the\expandafter\xargs@toksb\expandafter##\the\count@}% |
| 1086 |
\else |
| 1087 |
\xargs@toksb\expandafter\expandafter\expandafter{% |
| 1088 |
\the\expandafter\xargs@toksb\expandafter |
| 1089 |
[\expandafter##\the\count@]}% |
| 1090 |
\fi} |
| 1091 |
% \end{macrocode} |
| 1092 |
% \end{macro} |
| 1093 |
% \begin{macro}{\xargs@process@keys} |
| 1094 |
% Here comes the main input processing macro, which prepares the |
| 1095 |
% information needed to define the final macro, and expands it to the |
| 1096 |
% defining macro. |
| 1097 |
% \begin{macrocode} |
| 1098 |
\@ifdefinable\xargs@process@keys{% |
| 1099 |
\long\def\xargs@process@keys#1[#2]{% |
| 1100 |
% \end{macrocode} |
| 1101 |
% Some initialisations. We work inside a group so that the default |
| 1102 |
% values for the \cs{xargs@action@X} macros and the \cs{xargs@XXXopt@} |
| 1103 |
% be automatically restored for the next time. |
| 1104 |
% \begin{macrocode} |
| 1105 |
\begingroup |
| 1106 |
\xargs@setkeys{#2}% |
| 1107 |
\xargs@toksa{}\xargs@toksb{}% |
| 1108 |
% \end{macrocode} |
| 1109 |
% Let's begin with the |usedefault| part. |
| 1110 |
% \begin{macrocode} |
| 1111 |
\@ifundefined{xargs@default@flag}{}{% |
| 1112 |
\xargs@toksa\expandafter{% |
| 1113 |
\expandafter\xargs@set@defflag\expandafter{% |
| 1114 |
\xargs@default@flag}}} |
| 1115 |
% \end{macrocode} |
| 1116 |
% Then the main loop actually builds up the two lists in the correct |
| 1117 |
% order. |
| 1118 |
% \begin{macrocode} |
| 1119 |
\count@\z@ |
| 1120 |
\@whilenum\xargs@max>\count@ \do{% |
| 1121 |
\advance\count@\@ne |
| 1122 |
\expandafter\expandafter\expandafter\xargs@add@args |
| 1123 |
\expandafter\expandafter\expandafter{% |
| 1124 |
\csname xargs@action@\the\count@\endcsname}}% |
| 1125 |
% \end{macrocode} |
| 1126 |
% Then we need to address a special case: if only the first argument is |
| 1127 |
% optional, we use \LaTeXe's standard \cs{newcommand} construct, and we |
| 1128 |
% dont need an actions list like the one just build, but only the |
| 1129 |
% default value for the first argument. In this case, we extract this |
| 1130 |
% value from \cs{xargs@action@1} by expanding it two times with a |
| 1131 |
% modified \cs{xargs@testopt} (and one more expansion step for the |
| 1132 |
% |\csname| gives $3$, hence the $2^3-1 = 7$ \cs{expandafter}s). |
| 1133 |
% \begin{macrocode} |
| 1134 |
\ifxargs@otheropt@ \else |
| 1135 |
\ifxargs@firstopt@ |
| 1136 |
\let\xargs@test@opt\@firstofone |
| 1137 |
\xargs@toksa\expandafter\expandafter\expandafter |
| 1138 |
\expandafter\expandafter\expandafter\expandafter{% |
| 1139 |
\csname xargs@action@1\endcsname}% |
| 1140 |
\fi |
| 1141 |
\fi |
| 1142 |
% \end{macrocode} |
| 1143 |
% Finally expand the stuff to the next macro and, while we're at it, |
| 1144 |
% choose the next macro : depending of the existence and place of an |
| 1145 |
% optional argument, use \LaTeX's or \pf{xargs}'s way. In the \LaTeX{} |
| 1146 |
% case, however, we don't use \cs{@argdef} or \cs{xargdef} since we want |
| 1147 |
% to be able to use a prefix (and we have more work done allready, too). |
| 1148 |
% \begin{macrocode} |
| 1149 |
\edef\xargs@temp{% |
| 1150 |
\ifxargs@otheropt@ \noexpand\xargs@xargsdef \else |
| 1151 |
\ifxargs@firstopt@ \noexpand\xargs@xargdef \else |
| 1152 |
\noexpand\xargs@argdef |
| 1153 |
\fi\fi |
| 1154 |
\noexpand#1% |
| 1155 |
\expandafter\noexpand\csname\string#1\endcsname |
| 1156 |
{\the\xargs@toksa}{\the\xargs@toksb}}% |
| 1157 |
% \end{macrocode} |
| 1158 |
% Now we can close the group and forget all about key values, etc. Time |
| 1159 |
% to conclude and actually define the macro. (The only thing not passed |
| 1160 |
% as an argument is the prefix, which is globally set.) We also take |
| 1161 |
% care to execute \cs{xargs@drc@hook} just outside the group. |
| 1162 |
% \begin{macrocode} |
| 1163 |
\expandafter\endgroup |
| 1164 |
\expandafter\xargs@drc@hook |
| 1165 |
\xargs@temp}} |
| 1166 |
% \end{macrocode} |
| 1167 |
% \end{macro} |
| 1168 |
% \begin{macro}{\xargs@argdef} |
| 1169 |
% \begin{macro}{\xargs@xargdef} |
| 1170 |
% \begin{macro}{\xargs@xargsdef} |
| 1171 |
% The first two next macros are modified versions of kernel's |
| 1172 |
% \cs{@argdef} and \cs{@xargdef}, that do the same work, but use the |
| 1173 |
% prefix we built, and also are simpler since they get the internal name |
| 1174 |
% as an argument. The last one is the only new macro. |
| 1175 |
% \begin{macrocode} |
| 1176 |
\newcommand\xargs@argdef[5]{% |
| 1177 |
\@ifdefinable#1{% |
| 1178 |
\xargs@prefix\def#1#4{#5}}} |
| 1179 |
% \end{macrocode} |
| 1180 |
% \begin{macrocode} |
| 1181 |
\newcommand\xargs@xargdef[5]{% |
| 1182 |
\@ifdefinable#1{% |
| 1183 |
\xargs@shortpref\def#1{\@protected@testopt#1#2{#3}}% |
| 1184 |
\xargs@prefix\def#2#4{#5}}} |
| 1185 |
% \end{macrocode} |
| 1186 |
% \begin{macrocode} |
| 1187 |
\newcommand\xargs@xargsdef[5]{% |
| 1188 |
\@ifdefinable#1{% |
| 1189 |
\xargs@shortpref\def#1{\@protected@testopt@xargs#1#2{#3}}% |
| 1190 |
\xargs@prefix\def#2#4{#5}}} |
| 1191 |
% \end{macrocode} |
| 1192 |
% \end{macro} |
| 1193 |
% \end{macro} |
| 1194 |
% \end{macro} |
| 1195 |
% |
| 1196 |
% \subsection{User macros} |
| 1197 |
% |
| 1198 |
% \begin{macro}{\newcommandx} |
| 1199 |
% \begin{macro}{\xargs@newc} |
| 1200 |
% All the internal macros are ready. It's time to define the user |
| 1201 |
% commands, beginning with \cs{newcommandx}. Like its standard version, |
| 1202 |
% it just checks the star and call the next macro wich grabs the number |
| 1203 |
% of arguments. |
| 1204 |
% \begin{macrocode} |
| 1205 |
\newcommand\newcommandx{% |
| 1206 |
\xargs@star@or@long\xargs@newc} |
| 1207 |
% \end{macrocode} |
| 1208 |
% \begin{macrocode} |
| 1209 |
\newcommand*\xargs@newc[1]{% |
| 1210 |
\@testopt{\xargs@set@max{#1}}{0}} |
| 1211 |
% \end{macrocode} |
| 1212 |
% \end{macro} |
| 1213 |
% \end{macro} |
| 1214 |
% \begin{macro}{\xargs@set@max} |
| 1215 |
% Set the value of \cs{xargs@max}. If no optional arguments description |
| 1216 |
% follows, simply call \cs{argdef} because all the complicated stuff is |
| 1217 |
% useless here. |
| 1218 |
% \begin{macrocode} |
| 1219 |
\@ifdefinable\xargs@set@max{% |
| 1220 |
\def\xargs@set@max#1[#2]{% |
| 1221 |
\kernel@ifnextchar[%] |
| 1222 |
{\xargs@max=#2 \xargs@check@max{#1}}% |
| 1223 |
{\@argdef#1[#2]}}} |
| 1224 |
% \end{macrocode} |
| 1225 |
% \end{macro} |
| 1226 |
% \begin{macro}{\xargs@check@max} |
| 1227 |
% To avoid possible problems later, check right now that \cs{xargs@max} |
| 1228 |
% value is valid. If not, warn the user and treat this value as zero. |
| 1229 |
% Then begin the key processing. |
| 1230 |
% \begin{macrocode} |
| 1231 |
\newcommand\xargs@check@max{% |
| 1232 |
\ifcase\xargs@max \or\or\or\or\or\or\or\or\or\else |
| 1233 |
\PackageError{xargs}{Illegal number, treated as zero}{The total |
| 1234 |
number of arguments must be in the 0..9 range.\MessageBreak |
| 1235 |
Since your value is illegal, i'm going to use 0 instead.} |
| 1236 |
\xargs@max0 |
| 1237 |
\fi |
| 1238 |
\xargs@process@keys} |
| 1239 |
% \end{macrocode} |
| 1240 |
% \end{macro} |
| 1241 |
% |
| 1242 |
% \medskip |
| 1243 |
% |
| 1244 |
% The other macros (\cs{renewcommandx} etc.) closely resemble their kernel |
| 1245 |
% homologues, since they are mostly wrappers around some call to |
| 1246 |
% \cs{xargs@newc}. There is however two exceptions: \cs{CheckCommand} |
| 1247 |
% and \cs{DeclareRobustCommandx}. Indeed, the current implementation of |
| 1248 |
% \cs{CheckCommand} in the kernel suffers from two bugs (see |
| 1249 |
% \href{http://www.latex-project.org/cgi-bin/ltxbugs2html?pr=latex/3971} |
| 1250 |
% {PR/3971}) which I'm trying to avoid. For \cs{DeclareRobustCommandx}, |
| 1251 |
% the problem is to handle the prefix correctly: for that we use a hook, |
| 1252 |
% in order to delay the external macro's definition until we get the |
| 1253 |
% prefix right. So, let's see those two commands first. |
| 1254 |
% |
| 1255 |
% \begin{macro}{\CheckCommandx} |
| 1256 |
% We begin as usual detecting the possible star. |
| 1257 |
% \begin{macrocode} |
| 1258 |
\newcommand\CheckCommandx{% |
| 1259 |
\xargs@star@or@long\xargs@CheckC} |
| 1260 |
\@onlypreamble\CheckCommandx |
| 1261 |
% \end{macrocode} |
| 1262 |
% \end{macro} |
| 1263 |
% \begin{macro}{\xargs@CheckC} |
| 1264 |
% \begin{macro}{\xargs@check@a} |
| 1265 |
% \begin{macro}{\xargs@check@b} |
| 1266 |
% First, we don't use the |#2#| trick from the kernel, since it can fail |
| 1267 |
% if there are braces in the default values. Instead, we follow the |
| 1268 |
% argument grabing method used for \cs{new@environment}, ie calling |
| 1269 |
% \cs{kernel@ifnextchar} explicitly. |
| 1270 |
% \begin{macrocode} |
| 1271 |
\newcommand\xargs@CheckC[1]{% |
| 1272 |
\@testopt{\xargs@check@a#1}0} |
| 1273 |
\@onlypreamble\xargs@CheckC |
| 1274 |
% \end{macrocode} |
| 1275 |
% \begin{macrocode} |
| 1276 |
\@ifdefinable\xargs@check@a{% |
| 1277 |
\def\xargs@check@a#1[#2]{% |
| 1278 |
\kernel@ifnextchar[%] |
| 1279 |
{\xargs@check@b#1[#2]}% |
| 1280 |
{\xargs@check@c#1{[#2]}}}} |
| 1281 |
\@onlypreamble\xargs@check@a |
| 1282 |
% \end{macrocode} |
| 1283 |
% \begin{macrocode} |
| 1284 |
\@ifdefinable\xargs@check@b{% |
| 1285 |
\def\xargs@check@b#1[#2][#3]{% |
| 1286 |
\xargs@check@c{#1}{[#2][{#3}]}}} |
| 1287 |
\@onlypreamble\xargs@check@b |
| 1288 |
% \end{macrocode} |
| 1289 |
% \end{macro} |
| 1290 |
% \end{macro} |
| 1291 |
% \end{macro} |
| 1292 |
% \begin{macro}{\xargs@CheckC} |
| 1293 |
% Here comes the major difference with the kernel version. If |
| 1294 |
% |\\reserved@a| is defined, we not only check that it is equal to |
| 1295 |
% |\\foo| (assuming \cs{foo} is the macro being tested), we also check |
| 1296 |
% that \cs{foo} makes something sensible, with \cs{xargs@check@d}. |
| 1297 |
% \begin{macrocode} |
| 1298 |
\newcommand\xargs@check@c[3]{% |
| 1299 |
\xargs@toksa{#1}% |
| 1300 |
\expandafter\let\csname\string\reserved@a\endcsname\relax |
| 1301 |
\xargs@renewc\reserved@a#2{#3}% |
| 1302 |
\@ifundefined{\string\reserved@a}{% |
| 1303 |
\ifx#1\reserved@a \else |
| 1304 |
\xargs@check@complain |
| 1305 |
\fi |
| 1306 |
}{% |
| 1307 |
\expandafter |
| 1308 |
\ifx\csname\string#1\expandafter\endcsname |
| 1309 |
\csname\string\reserved@a\endcsname |
| 1310 |
\xargs@check@d |
| 1311 |
\else |
| 1312 |
\xargs@check@complain |
| 1313 |
\fi}} |
| 1314 |
\@onlypreamble\xargs@check@c |
| 1315 |
% \end{macrocode} |
| 1316 |
% \end{macro} |
| 1317 |
% So, what do we want \cs{foo} to do? If |\\foo| is defined, \cs{foo} |
| 1318 |
% should begin with one of the followings: |
| 1319 |
% \begin{quote} |
| 1320 |
% |\@protected@testopt \foo \\foo| \\ |
| 1321 |
% |\@protected@testopt@xargs \foo \\foo| |
| 1322 |
% \end{quote} |
| 1323 |
% Since I'm to lazy to really check this, the \cs{xargs@check@d} macro |
| 1324 |
% only checks if the \cs{meaning} of \cs{foo} begins with |
| 1325 |
% \cs{@protected@test@opt} (without a space after it). It does this |
| 1326 |
% using a macro with delimited argument. Here are preliminaries to this |
| 1327 |
% definition: We need to have this string in \cs{catcode} 12 tokens. |
| 1328 |
% \begin{macrocode} |
| 1329 |
\def\xargs@temp{\@protected@testopt} |
| 1330 |
\expandafter\xargs@toksa\expandafter{\meaning\xargs@temp} |
| 1331 |
\def\xargs@temp#1 {\def\xargs@temp{#1}} |
| 1332 |
\expandafter\xargs@temp\the\xargs@toksa |
| 1333 |
% \end{macrocode} |
| 1334 |
% \begin{macro}{\xargs@check@d} |
| 1335 |
% \begin{macro}{\xargs@check@e} |
| 1336 |
% Now, \cs{xargs@check@c} just pass the \cs{meaning} of the command |
| 1337 |
% \cs{foo} being checked to the allready mentionned macro with delimited |
| 1338 |
% arguments, which will check if its first argument is empty (ie, if |
| 1339 |
% \cs{foo}'s \cs{meaning} starts with what we want) and complain |
| 1340 |
% otherwise. |
| 1341 |
% \begin{macrocode} |
| 1342 |
\expandafter\newcommand\expandafter\xargs@check@d\expandafter{% |
| 1343 |
\expandafter\expandafter\expandafter\xargs@check@e |
| 1344 |
\expandafter\meaning\expandafter\reserved@a\xargs@temp\@nil} |
| 1345 |
\@onlypreamble\xargs@check@d |
| 1346 |
% \end{macrocode} |
| 1347 |
% \begin{macrocode} |
| 1348 |
\@ifdefinable\xargs@check@e{% |
| 1349 |
\expandafter\def\expandafter\xargs@check@e |
| 1350 |
\expandafter#\expandafter1\xargs@temp#2\@nil{% |
| 1351 |
\ifx\empty#1\empty \else |
| 1352 |
\xargs@check@complain |
| 1353 |
\fi}} |
| 1354 |
\@onlypreamble\xargs@check@e |
| 1355 |
% \end{macrocode} |
| 1356 |
% \end{macro} |
| 1357 |
% \end{macro} |
| 1358 |
% \begin{macro}{\xargs@check@complain} |
| 1359 |
% The complaining macro uses the name saved by \cs{xargs@check@c} in |
| 1360 |
% \cs{xargs@toksa} in order to complain about the correct macro. |
| 1361 |
% \begin{macrocode} |
| 1362 |
\newcommand\xargs@check@complain{% |
| 1363 |
\PackageWarningNoLine{xargs}{Command \the\xargs@toksa has changed. |
| 1364 |
\MessageBreak Check if current package is valid}} |
| 1365 |
\@onlypreamble\xargs@check@complain |
| 1366 |
% \end{macrocode} |
| 1367 |
% \end{macro} |
| 1368 |
% |
| 1369 |
% \begin{macro}{\DeclareRobustCommandx} |
| 1370 |
% \begin{macro}{\xargs@DRC} |
| 1371 |
% The \pf{xargs} version of \cs{DeclareRobustCommand}, and related |
| 1372 |
% internal macros. |
| 1373 |
% \begin{macrocode} |
| 1374 |
\newcommand\DeclareRobustCommandx{% |
| 1375 |
\xargs@star@or@long\xargs@DRC} |
| 1376 |
% \end{macrocode} |
| 1377 |
% \begin{macrocode} |
| 1378 |
\newcommand*\xargs@DRC[1]{% |
| 1379 |
\ifx#1\@undefined\else\ifx#1\relax\else |
| 1380 |
\PackageInfo{xargs}{Redefining \string#1}% |
| 1381 |
\fi\fi |
| 1382 |
\edef\reserved@a{\string#1}% |
| 1383 |
\def\reserved@b{#1}% |
| 1384 |
\edef\reserved@b{\expandafter\strip@prefix\meaning\reserved@b}% |
| 1385 |
% \end{macrocode} |
| 1386 |
% Here is the difference from kernel's code: instead of doing the |
| 1387 |
% definition of the user macro now, we just set the hook to do it |
| 1388 |
% latter, when the correct prefix will be set, then disable itself for |
| 1389 |
% next time. |
| 1390 |
% \begin{macrocode} |
| 1391 |
\edef\xargs@drc@hook{% |
| 1392 |
\noexpand\xargs@shortpref\def\noexpand#1{% |
| 1393 |
\ifx\reserved@a\reserved@b |
| 1394 |
\noexpand\x@protect |
| 1395 |
\noexpand#1% |
| 1396 |
\fi |
| 1397 |
\noexpand\protect |
| 1398 |
\expandafter\noexpand\csname |
| 1399 |
\expandafter\@gobble\string#1 \endcsname}% |
| 1400 |
\expandafter\let\noexpand\xargs@drc@hook\relax}% |
| 1401 |
\let\@ifdefinable\@rc@ifdefinable |
| 1402 |
\expandafter\xargs@newc\csname |
| 1403 |
\expandafter\@gobble\string#1 \endcsname} |
| 1404 |
% \end{macrocode} |
| 1405 |
% And finally set a default empty hook. |
| 1406 |
% \begin{macrocode} |
| 1407 |
\let\xargs@drc@hook\relax |
| 1408 |
% \end{macrocode} |
| 1409 |
% \end{macro} |
| 1410 |
% \end{macro} |
| 1411 |
% |
| 1412 |
% \medskip |
| 1413 |
% |
| 1414 |
% From now on, there is absolutely nothing to comment, since the next |
| 1415 |
% macros are mainly wrappers around \cs{xargs@newc}, just as kernel's |
| 1416 |
% ones are wrappers around \cs{new@command}. So the code below is only |
| 1417 |
% copy/paste with search\&replace from the kernel code. |
| 1418 |
% |
| 1419 |
% \begin{macro}{\renewcommandx} |
| 1420 |
% \begin{macro}{\xargs@renewc} |
| 1421 |
% The \pf{xargs} version of \cs{renewcommand}, and it's related internal |
| 1422 |
% macro. |
| 1423 |
% \begin{macrocode} |
| 1424 |
\newcommand\renewcommandx{% |
| 1425 |
\xargs@star@or@long\xargs@renewc} |
| 1426 |
% \end{macrocode} |
| 1427 |
% \begin{macrocode} |
| 1428 |
\newcommand*\xargs@renewc[1]{% |
| 1429 |
\begingroup\escapechar\m@ne |
| 1430 |
\xdef\@gtempa{{\string#1}}% |
| 1431 |
\endgroup |
| 1432 |
\expandafter\@ifundefined\@gtempa{% |
| 1433 |
\PackageError{xargs}{\noexpand#1undefined}{% |
| 1434 |
Try typing \space <return> \space to proceed.\MessageBreak |
| 1435 |
If that doesn't work, type \space X <return> \space to quit.}}% |
| 1436 |
\relax |
| 1437 |
\let\@ifdefinable\@rc@ifdefinable |
| 1438 |
\xargs@newc#1} |
| 1439 |
% \end{macrocode} |
| 1440 |
% \end{macro} |
| 1441 |
% \end{macro} |
| 1442 |
% |
| 1443 |
% \begin{macro}{\providecommandx} |
| 1444 |
% \begin{macro}{\xargs@providec} |
| 1445 |
% The \pf{xargs} version of \cs{providecommand}, and the related |
| 1446 |
% internal macro. |
| 1447 |
% \begin{macrocode} |
| 1448 |
\newcommand\providecommandx{% |
| 1449 |
\xargs@star@or@long\xargs@providec} |
| 1450 |
% \end{macrocode} |
| 1451 |
% \begin{macrocode} |
| 1452 |
\newcommand*\xargs@providec[1]{% |
| 1453 |
\begingroup\escapechar\m@ne |
| 1454 |
\xdef\@gtempa{{\string#1}}% |
| 1455 |
\endgroup |
| 1456 |
\expandafter\@ifundefined\@gtempa |
| 1457 |
{\def\reserved@a{\xargs@newc#1}}% |
| 1458 |
{\def\reserved@a{\renew@command\reserved@a}}% |
| 1459 |
\reserved@a} |
| 1460 |
% \end{macrocode} |
| 1461 |
% \end{macro} |
| 1462 |
% \end{macro} |
| 1463 |
% |
| 1464 |
% \begin{macro}{\newenvironment} |
| 1465 |
% \begin{macro}{\xargs@newenv} |
| 1466 |
% \begin{macro}{\xargs@newenva} |
| 1467 |
% \begin{macro}{\xargs@newenvb} |
| 1468 |
% \begin{macro}{\xargs@new@env} |
| 1469 |
% The \pf{xargs} version of \cs{newenvironment}, and related internal |
| 1470 |
% macros. |
| 1471 |
% \begin{macrocode} |
| 1472 |
\newcommand\newenvironmentx{% |
| 1473 |
\xargs@star@or@long\xargs@newenv} |
| 1474 |
% \end{macrocode} |
| 1475 |
% \begin{macrocode} |
| 1476 |
\newcommand*\xargs@newenv[1]{% |
| 1477 |
\@testopt{\xargs@newenva#1}0} |
| 1478 |
% \end{macrocode} |
| 1479 |
% \begin{macrocode} |
| 1480 |
\@ifdefinable\xargs@newenva{% |
| 1481 |
\def\xargs@newenva#1[#2]{% |
| 1482 |
\kernel@ifnextchar[%] |
| 1483 |
{\xargs@newenvb#1[#2]}% |
| 1484 |
{\xargs@new@env{#1}{[#2]}}}} |
| 1485 |
% \end{macrocode} |
| 1486 |
% \begin{macrocode} |
| 1487 |
\@ifdefinable\xargs@newenvb{% |
| 1488 |
\def\xargs@newenvb#1[#2][#3]{% |
| 1489 |
\xargs@new@env{#1}{[#2][{#3}]}}} |
| 1490 |
% \end{macrocode} |
| 1491 |
% \begin{macrocode} |
| 1492 |
\newcommand\xargs@new@env[4]{% |
| 1493 |
\@ifundefined{#1}{% |
| 1494 |
\expandafter\let\csname#1\expandafter\endcsname |
| 1495 |
\csname end#1\endcsname}% |
| 1496 |
\relax |
| 1497 |
\expandafter\xargs@newc |
| 1498 |
\csname #1\endcsname#2{#3}% |
| 1499 |
\xargs@shortpref\expandafter\def\csname end#1\endcsname{#4}} |
| 1500 |
% \end{macrocode} |
| 1501 |
% \end{macro} |
| 1502 |
% \end{macro} |
| 1503 |
% \end{macro} |
| 1504 |
% \end{macro} |
| 1505 |
% \end{macro} |
| 1506 |
% |
| 1507 |
% \begin{macro}{\renewenvironment} |
| 1508 |
% \begin{macro}{\xargs@renewenv} |
| 1509 |
% The \pf{xargs} version of \cs{renewenvironment}, and the related |
| 1510 |
% internal macro. |
| 1511 |
% \begin{macrocode} |
| 1512 |
\newcommand\renewenvironmentx{% |
| 1513 |
\xargs@star@or@long\xargs@renewenv} |
| 1514 |
% \end{macrocode} |
| 1515 |
% \begin{macrocode} |
| 1516 |
\newcommand*\xargs@renewenv[1]{% |
| 1517 |
\@ifundefined{#1}{% |
| 1518 |
\PackageError{xargs}{\noexpand#1undefined}{% |
| 1519 |
Try typing \space <return> \space to proceed.\MessageBreak |
| 1520 |
If that doesn't work, type \space X <return> \space to quit.}}% |
| 1521 |
\relax |
| 1522 |
\expandafter\let\csname#1\endcsname\relax |
| 1523 |
\expandafter\let\csname end#1\endcsname\relax |
| 1524 |
\xargs@newenv{#1}} |
| 1525 |
% \end{macrocode} |
| 1526 |
% \end{macro} |
| 1527 |
% \end{macro} |
| 1528 |
% |
| 1529 |
% \bigskip |
| 1530 |
% \begin{center}\Large |
| 1531 |
% That's all folks!\\ |
| 1532 |
% Happy \TeX ing! |
| 1533 |
% \end{center} |
| 1534 |
% |
| 1535 |
% \Finale |
| 1536 |
% |
| 1537 |
% \iffalse |
| 1538 |
%</package> |
| 1539 |
%<*batchfile> |
| 1540 |
% \fi |
| 1541 |
% \typeout{**************************************************} |
| 1542 |
% \typeout{*} |
| 1543 |
% \typeout{* To finish the installation you have to move the} |
| 1544 |
% \typeout{* following file into a directory searched by TeX:} |
| 1545 |
% \typeout{*} |
| 1546 |
% \typeout{* \space\space\space\space xargs.sty} |
| 1547 |
% \typeout{*} |
| 1548 |
% \typeout{* Documentation is in xargs.dvi or xargs.pdf} |
| 1549 |
% \typeout{*} |
| 1550 |
% \typeout{* To produce french documentation, run} |
| 1551 |
% \typeout{* \space\space \space\space (pdf)latex xargs-fr.drv} |
| 1552 |
% \typeout{*} |
| 1553 |
% \typeout{* Happy TeXing!} |
| 1554 |
% \typeout{*} |
| 1555 |
% \typeout{**************************************************} |
| 1556 |
% \iffalse |
| 1557 |
%</batchfile> |
| 1558 |
% \fi |
| 1559 |
\endinput |