summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/xargs
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2008-03-24 23:37:37 +0000
committerKarl Berry <karl@freefriends.org>2008-03-24 23:37:37 +0000
commite996780144392d1f7a4f820e9ba64b75f50bf30c (patch)
tree1a6e87f8ff69e65aa170e8a64d2625fd96c8196b /Master/texmf-dist/source/latex/xargs
parent7bdb10a58dfbc89f6d492904dbb9b346215191f4 (diff)
xargs update (24mar08)
git-svn-id: svn://tug.org/texlive/trunk@7129 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/xargs')
-rw-r--r--Master/texmf-dist/source/latex/xargs/xargs.dtx1217
1 files changed, 738 insertions, 479 deletions
diff --git a/Master/texmf-dist/source/latex/xargs/xargs.dtx b/Master/texmf-dist/source/latex/xargs/xargs.dtx
index ce584408a2b..a8eb4cb8a4b 100644
--- a/Master/texmf-dist/source/latex/xargs/xargs.dtx
+++ b/Master/texmf-dist/source/latex/xargs/xargs.dtx
@@ -30,11 +30,11 @@
%<*package>
% \fi
% \ProvidesFile{xargs.dtx}
- [2008/03/08 1.09 \space extended macro definitions \space (mpg)]
+ [2008/03/22 v1.1 \space extended macro definitions \space (mpg)]
% \iffalse
%</package>
% \fi
-% \CheckSum{786}
+% \CheckSum{782}
% \CharacterTable
% {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
% 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
@@ -91,10 +91,14 @@ This is a generated file. See xargs.dtx for license information.
\usepackage[lmargin=4.5cm, rmargin=3cm]{geometry}
\OnlyDescription
\usepackage[english, frenchb]{babel}
-\FrenchFootnotes
+\FrenchFootnotes \AddThinSpaceBeforeFootnotes
\newcommand*\eng[1]{\emph{\foreignlanguage{english}{#1}}}
-\usepackage[bookmarks=false, colorlinks=true,
- linkcolor=black, urlcolor=black]{hyperref}
+\usepackage[colorlinks=true, bookmarks=true,
+ bookmarksnumbered=true, bookmarksopen=true, bookmarksopenlevel=3,
+ pdfauthor={Manuel Pégourié-Gonnard},
+ pdftitle={L'extension xargs},
+ pdfsubject={Définitions de macros étendues pour LaTeX2e},
+ ]{hyperref}
%</pilote>
%<*gobble>
\else
@@ -102,17 +106,33 @@ This is a generated file. See xargs.dtx for license information.
%<*driver>
\AlsoImplementation
\usepackage[english]{babel}
-\usepackage[bookmarks=true, colorlinks=true,
- linkcolor=black, urlcolor=black]{hyperref}
-\usepackage[nohints, undotted, english]{minitoc}
+\usepackage[colorlinks=true, bookmarks=true,
+ bookmarksnumbered=true, bookmarksopen=true, bookmarksopenlevel=3,
+ pdfauthor={Manuel Pégourié-Gonnard},
+ pdftitle={The xargs package},
+ pdfsubject={Extended macro definitions for LaTeX2e},
+ ]{hyperref}
+\settowidth\MacroIndent{\rmfamily\scriptsize 000\ }
+\setlength\MacroTopsep{0pt}
+\usepackage[nohints, english]{minitoc}
+\mtcsetpagenumbers{secttoc}{off}
+\mtcsetrules{secttoc}{off}
+\mtcsetdepth{secttoc}{3}
+\setlength{\stcindent}{0pt}
+\mtcsetfont{secttoc}{subsection}{\normalfont}
+\newcommand\tocwithmini{%
+ \dosecttoc[n]
+ \setcounter{tocdepth}{1}\tableofcontents
+ \setcounter{tocdepth}{3}\faketableofcontents}
%</driver>
%<*gobble>
\fi
%</gobble>
%<*driver|pilote>
\newcommand\pf{\textsf}
-\settowidth\MacroIndent{\rmfamily\scriptsize 000\ }
-\setlength\MacroTopsep{0pt}
+\newcommand\optstar{\meta{$*$}}
+\newcommand\topcs[1]{\texorpdfstring{\cs{#1}}{#1}}
+\newcommand\eTeX{$\varepsilon$-\TeX}
\begin{document}
\DocInput{xargs.dtx}
\end{document}
@@ -128,11 +148,12 @@ This is a generated file. See xargs.dtx for license information.
% \date{\fileversion\ (\filedate)}
%
% \maketitle
-% \iffrenchdoc\else
-% \dosecttoc
-% \mtcsetrules{*}{off}
-% {\setcounter{tocdepth}{1}\tableofcontents}
-% {\setcounter{tocdepth}{2}\faketableofcontents}
+% \iffrenchdoc\else \tocwithmini \fi
+%
+% \iffrenchdoc\else
+% \medskip
+% \emph{Important note for French users}: a French version of the user
+% documentation is included in the \nolinkurl{xargs-fr.pdf} file.
% \fi
%
% \section{Introduction}
@@ -143,35 +164,46 @@ This is a generated file. See xargs.dtx for license information.
% optionel. Cependant, il y a deux restrictions : il peut y avoir au plus un
% argument optionel, et ce doit être le premier. L'extension \pf{xargs}
% fournit des versions étendues de \cs{newcommand} et de ses analogues
-% standard, qui ne présentent pas ces restrictions.
-%
-% Vous connaissez peut-être des astuces pour définir des commandes avec
-% plusieurs arguments optionels, ou avec l'argument optionel en dernier. Mais
-% utiliser ces astuces vous force à résoudre certains problèmes (ordre
-% d'utilisation des arguments, gestions des espaces) qui peuvent s'avérer
-% délicats. C'est n'est de toute façon pas le genre de choses auxquelles vous
-% devriez avoir à réfléchir quand vous rédigez un document.
+% standard, qui ne présentent pas ces restrictions : il est désormais
+% facile de définir des commandes avec plusieurs arguments optionnels,
+% placés où l'on veut, par une syntaxe agréable du style
+% \meta{clé}=\meta{valeur}. Par exemple, voici comment définir une
+% commande avec deux arguments optionnels.
%
-% L'extension \pf{xargs} vous fournit donc un moyen pratique et (je l'espère)
-% robuste de définir de telles commandes, avec une syntaxe intuitive de la
-% forme \meta{clé}=\meta{valeur}.
+% \begin{center}
+% |\newcommandx*\coord[3][1=1, 3=n]{(#2_{#1},\ldots,#2_{#3})}|
+% \newcommandx*\coord[3][1=1, 3=n]{(#2_{#1},\ldots,#2_{#3})}
+% \par\medskip
+% \begin{tabular}{ll}
+% |$\coord{x}$| & $\coord{x}$ \\
+% |$\coord[0]{y}$| & $\coord[0]{y}$ \\
+% |$\coord{z}[m]$| & $\coord{z}[m]$ \\
+% |$\coord[0]{t}[m]$| & $\coord[0]{t}[m]$ \\
+% \end{tabular}
+% \end{center}
%
% \else
%
-% Defining commands with an optional argument is easy in \LaTeXe{}. There is,
-% however, two limitations: there can be at most one optional argument and it
-% must be the first one. The \pf{xargs} package provide extended variants of
-% \cs{newcommand} \& friends, for which these limitations no longer hold.
-%
-% You may know some tricks in order to define commands with many optional
-% arguments, or with last argument optional, etc. Theses tricks are subject to
-% a few problems (using arguments in arbitrary order can be difficult,
-% sometimes space is gobbled where it should not), which can be difficult to
-% solve. Anyway, you don't want to worry about such tricky things while
-% writing a document.
+% Defining commands with an optional argument is easy in \LaTeXe{}.
+% There is, however, two limitations: you can make only one argument
+% optional and it must be the first one. The \pf{xargs} package provide
+% extended variants of \cs{newcommand} \& friends, for which these
+% limitations no longer hold: It is now easy to define commands with
+% many (and freely placed) optional arguments, using a nice
+% \meta{key}=\meta{value} syntax. For example, the following defines a
+% command with two optional arguments.
%
-% The \pf{xargs} package provides you with an easy and (hopefully) robust way
-% to define such commands, using a nice \meta{key}=\meta{value} syntax.
+% \begin{center}
+% |\newcommandx*\coord[3][1=1, 3=n]{(#2_{#1},\ldots,#2_{#3})}|
+% \newcommandx*\coord[3][1=1, 3=n]{(#2_{#1},\ldots,#2_{#3})}
+% \par\medskip
+% \begin{tabular}{ll}
+% |$\coord{x}$| & $\coord{x}$ \\
+% |$\coord[0]{y}$| & $\coord[0]{y}$ \\
+% |$\coord{z}[m]$| & $\coord{z}[m]$ \\
+% |$\coord[0]{t}[m]$| & $\coord[0]{t}[m]$ \\
+% \end{tabular}
+% \end{center}
%
% \fi
%
@@ -179,150 +211,234 @@ This is a generated file. See xargs.dtx for license information.
%
% \iffrenchdoc
%
+% \subsection{Les bases}
+%
% L'extension \pf{xargs} fournit des analogues de toutes les macros de
% \LaTeXe{} relatives à la définition de macros. Les macros de \pf{xargs} ont
% le même nom que leur analogue standard, mais avec un |x| supplémentaire à la
-% fin : par exemple, \cs{newcommandx}, \cs{renewcommandx} ou encore
-% \cs{newenvironmentx}. Elles ont par ailleurs toutes la même syntaxe. Je ne
-% présenterai donc que \cs{newcommandx}.
+% fin. En voici la liste complète.
+%
+% \begin{center}
+% \begin{tabular}{ll}
+% \cs{newcommandx} & \cs{renewcommandx} \\
+% \cs{newenvironmentx} & \cs{renewenvironmentx} \\
+% \cs{providecommandx} & \cs{DeclareRobustCommandx} \\
+% \cs{CheckCommandx}
+% \end{tabular}
+% \end{center}
+%
+% Si vous ne connaissez pas toutes ces commandes, ne vous inquiétez pas.
+% Vous pouvez utiliser seulement les analogues des macros que vous
+% connaissez ; ou apprendre les autres par exemple dans le livre de
+% \bsc{Lamport}, le \LaTeX{} Companion, ou tout autre manuel sur \LaTeXe.
+%
+% \medskip
+%
+% Ces commandes partageant toutes la même syntaxe, je parlerai seulement
+% de |\newcommandx| par la suite, mais gardez à l'esprit que les
+% explications sont valables pour les autres commandes. (Bien sûr, pour
+% les environnements, il y a un dernier argument en plus, pour la
+% définition de fin.) Voici la syntaxe complète de |\newcommand|.
%
-% Commençons par un exemple. Après la définition
% \begin{center}
-% |\newcommandx*\vect[3][1=1, 3=n]{(#2_{#1},\ldots,#2_{#3})}|
+% \cs{newcommandx}\optstar\marg{commande}\oarg{nombre}\oarg{liste}^^A
+% \marg{définition}
% \end{center}
-% \newcommandx*\vect[3][1=1, 3=n]{(#2_{#1},\ldots,#2_{#3})}%
-% vous pouvez utiliser la macro \cs{vect} d'une des façons suivantes :
+%
+% Rappelons brièvement tout ce qui est commun avec la syntaxe usuelle, à
+% savoir tout sauf \meta{liste}. Si une $*$ est présente, elle signifie
+% que la macro crée est \emph{courte} au sens de \TeX{}, c'est-à-dire
+% que ses arguments ne peuvent pas contenir de saut de paragraphe
+% (\cs{par} ou ligne vide). La \meta{commande} est n'importe quelle
+% séquence de contrôle, que vous pouvez ou non entourer d'accolades
+% suivant vos goûts. Le \meta{nombre} définit le nombre total d'argument
+% de la \meta{commande}, c'est un entier compris entre $0$ et $9$. La
+% \meta{définition} est un texte équilibré en accolades, et où chaque
+% caractère |#| est suivi soit d'un chiffre représentant un des
+% arguments, soit d'un autre caractère |#|. Les arguments \meta{nombre}
+% et \meta{liste} sont optionnels.
+%
+% \medskip
+%
+% La partie intéressante maintenant. La \meta{liste} est une\ldots{}
+% liste (!) d'éléments de la forme \meta{chiffre}=\meta{valeur}, séparés
+% par des virgules. Le \meta{chiffre} doit être un entier compris entre
+% $1$ et le nombre d'arguments, donné par \meta{nombre}. La
+% \meta{valeur} est n'importe quelle texte équilibré en accolades. Il
+% peut être vide si vous le souhaitez : le signe égal qui le précède
+% peut alors être omis. Tous les arguments dont le numéro figure en tant
+% que \meta{chiffre} dans la \meta{liste} seront optionnels, avec pour
+% valeur par défaut celle donnée par la \meta{valeur} correspondante.
+%
+% Quelques remarques supplémentaires sur la syntaxe de la \meta{liste},
+% que vous pouvez sauter si vous êtes familiers avec la syntaxe fournie
+% par \pf{xkeyval}. Vu que les éléments sont séparés par des virgules,
+% si une \meta{valeur} doit contenir une virgule, il faut entourer la
+% valeur par des accolades pour protéger la virgule. (Cette précaution
+% est également indispensable si la \meta{valeur} contient une accolade
+% fermante.) Ne vous inquiétez pas, cette parie d'accolade sera retirée
+% ultérieurement. D'ailleurs, jusqu'à trois paires d'accolades seront
+% retirées ainsi, et si vous voulez vraiment que votre valeur reste
+% entourée d'accolades, il vous faudra écrire quelque chose
+% comme~|1={{{{\large blabla}}}}|.
+%
+% \medskip
+%
+% C'est tout pour les bases : vous en savez maintenant assez pour
+% utiliser \pf{xargs}, et vous pouvez laisser la fin de la documentation
+% pour plus tard si vous voulez. Si, au contraire, vous vous demandez ce
+% qui se passe avec plusieurs arguments optionnels à la suite, que vous
+% voulez effectuer des définitions globales, ou que vous aves besoin de
+% connaître les limites précises de \pf{xargs}, vous pouvez lire les
+% sections suivantes.
+%
+% \subsection{La clé \texttt{usedefault}}
+%
+% Voyons donc se qui se passe quand plusieurs arguments optionnels se
+% suivent. Le comportement par défaut est calqué sur celui de commandes
+% \LaTeX{} comme \cs{makebox} et \cs{parbox} : on ne peut spécifier une
+% valeur pour le troisième argument optionnel que si on l'a fait pour
+% les deux premiers. Par exemple, dans l'exemple du début, remarquez
+% comment j'avais pris soin de placer l'argument obligatoire au milieu
+% pour séparer les arguments optionnels.
+%
+% Cependant, ce n'est pas très pratique, et on aimerait pouvoir choisir
+% l'ordre des arguments plutôt selon leur sens, sans se poser de
+% questions. Bien, la clé |usedefault| est justement là pour ça :
+% incluez-la dans la \meta{liste}, et vous pouvez désormais utiliser
+% |[]| pour sauter un argument optionnel, en utilisant sa valeur par
+% défaut.
+%
% \begin{center}
+% |\newcommandx*\coord[3][2=1,3=n,usedefault]{(#2_{#1},\ldots,#2_{#3})}|
+% \newcommandx*\coord[3][2=1, 3=n, usedefault]{(#2_{#1},\ldots,#2_{#3})}
+% \par\medskip
% \begin{tabular}{ll}
-% |$\vect{x}$| & $\vect{x}$ \\
-% |$\vect[0]{y}$| & $\vect[0]{y}$ \\
-% |$\vect{z}[m]$| & $\vect{z}[m]$ \\
-% |$\vect[0]{t}[m]$| & $\vect[0]{t}[m]$ \\
+% |$\coord{x}$| & $\coord{x}$ \\
+% |$\coord{y}[0]$| & $\coord{y}[0]$ \\
+% |$\coord{z}[][m]$| & $\coord{z}[][m]$ \\
+% |$\coord{t}[0][m]$| & $\coord{t}[0][m]$ \\
% \end{tabular}
% \end{center}
%
-% Vous avez sans doute compris qu'il s'agit d'une macro prenant trois
-% arguments au total, mais dont le premier et le troisième argument sont
-% optionnels. Ils ont chacun une valeur par défaut (respectivement |1| et |n|
-% ici). Vous pouvez également remarquer que la syntaxe de \cs{newcomandx} est
-% très proche de celle de \cs{newcommand}, la seule différence étant qu'au
-% lieu d'indiquer la valeur par défaut de l'unique argument optionel, vous
-% indiquez ici le numéro de chaque argument à rendre optionel, suivi de sa
-% valeur par défaut.
-%
-% Détaillons maintenant la syntaxe de \cs{newcommandx}, qui, répétons-le, est
-% aussi la syntaxe de toutes les autres commandes de l'extension \pf{xargs}.
-% (Pendant qu'on est dans les détails, voici la liste complète de ces
-% commandes : \cs{newcommandx} et \cs{renewcommandx} pour les macros simples,
-% \cs{providecommandx} pour s'assurer qu'une macro existe,
-% \cs{DeclareRobustCommandx} pour (re)définir une macro robuste,
-% \cs{CheckCommandx} pour vérifier le sens d'une macro, \cs{newenvironmentx}
-% et \cs{renewenvironmentx} pour les environnements.)
+% Bien sûr, sur cet exemple simple, c'est surtout une histoire de goût,
+% mais parfois |usedefault| peut vous épargner pas mal de frappe
+% inutile, car la valeur par défaut d'un argument est parfois longue, et
+% qu'on a pas toujours assez d'arguments obligatoires pour séparer les
+% arguments optionnels comme plus haut.
+%
+% Cette utilisation simple de |usedefault| présente un inconvénient :
+% vous ne pouvez plus spécifier la valeur vide pour un argument
+% optionnel. En fait, il faut nécessairement une valeur spéciale de
+% l'argument pour dire \og utiliser la valeur par défaut \fg{}, mais ce
+% n'est pas nécessairement la chaîne vide : en fait, on peut choisir
+% cette valeur en disant |usedefault=|\meta{valeur}. L'exemple suivant
+% ne sert à rien, à part illustrer ceci.
%
% \begin{center}
-% \cs{newcommandx} \meta{|*|} \marg{commande} \oarg{nombre} \oarg{liste}
-% \marg{définition}
+% |\newcommandx*\test[2][1=A, 2=B, usedefault=@]{(#1,#2)}|
+% \newcommandx*\test[2][1=A, 2=B, usedefault=@]{(#1,#2)}
+% \par\medskip
+% \begin{tabular}{ll}
+% |\test[b]| & \test[b] \\
+% |\test[][b]| & \test[][b] \\
+% |\test[@][b]| & \test[@][b] \\
+% \end{tabular}
% \end{center}
%
-% Rappellons brièvement tout ce qui est commun avec la syntaxe usuelle, à
-% savoir tout sauf \meta{liste}. Si une |*| est présente, elle signifie que la
-% macro crée est \emph{courte} au sens de \TeX{}, c'est-à-dire que ses
-% arguments ne peuvent pas contenir de saut de paragraphe (\cs{par} ou ligne
-% vide). La \meta{commande} est n'importe quelle séquence de contrôle, que
-% vous pouvez ou non entourer d'accolades suivant vos goûts. Le \meta{nombre}
-% définit le nombre total d'argument de la \meta{commande}, c'est un entier
-% compris entre $0$ et $9$. La \meta{définition} est un texte équilibré en
-% accolades, et où chaque caractère |#| est suivi soit d'un chiffre
-% représentant un des arguments, soit d'un autre caractère |#|. Les arguments
-% entre crochets sont optionnels.
-%
-% La partie intéressante maintenant. La \meta{liste} est une\ldots{} liste (!)
-% d'éléments de la forme \meta{chiffre}=\meta{valeur}, séparés par des
-% virgules. Le \meta{chiffre} doit être un entier compris entre $1$ et le
-% nombre d'arguments, donné par \meta{nombre}. La \meta{valeur} est n'importe
-% quelle texte équilibré en accolades. Il peut être vide si vous le souhaitez
-% : le signe égal qui le précède est alors optionel. Tous les arguments dont
-% le numéro figure en tant que \meta{chiffre} dans la \meta{liste} seront
-% optionnels, avec pour valeur par défaut celle donnée par la \meta{valeur}
-% correspondante.
-%
-% Concernant l'usage des commandes, notez que, si les arguments $1$ et $2$
-% (par exemple) sont optionnels, vous ne pouvez spécifier de valeur pour
-% l'argument $2$ si vous n'en avez pas spécifié pour l'argument $1$. Ce
-% comportement est cohérent avec celui de commandes \LaTeX{} existantes, comme
-% \cs{makebox}. Il ne provient pas d'une limitation technique mais surtout de
-% mon incapacité à imaginer une situation où il est vraiment gênant et une
-% syntaxe intelligente pour le contourner. À ce sujet, observez comment j'ai
-% pris soin de séparer les deux arguments optionels par l'argument obligatoire
-% dans le définition de \cs{vect} ci-dessus.
-%
-% Quelques remarques supplémentaires sur la syntaxe de la \meta{liste}, que
-% vous pouvez sauter si vous êtes familiers avec la syntaxe fournie par
-% \pf{xkeyval}. Vu que les éléments sont séparés par des virgules, si une
-% \meta{valeur} doit contenir une virgule, il faut entourer la valeur par des
-% accolades pour protéger la virgule. (Cette précaution est également
-% indispensable si la \meta{valeur} contient une accolade fermante.) Ne vous
-% inquiétez pas, cette parie d'accolade sera retirée ultérieurement.
-% D'ailleurs, jusqu'à trois paires d'accolades seront retirées ainsi, et si
-% vous voulez vraiment que votre valeur reste entourée d'acollades, il vous
-% faudra écrire quelque chose comme~|1={{{{\large blabla}}}}|.
-%
-% La dernière particularité de la \meta{liste} que vous devez connaître, est
-% qu'elle ne doit pas contenir de |\par| (ou de ligne vide). C'est le seul
-% point (à ma connaissance) sur lequel les macros d'\pf{xargs} diffèrent des
-% macros standard. Cette limitation est liée à un choix dans l'implémentation
-% d'\pf{xkeyval}, que j'ai eu un peu la flemme de contourner (en fait, je ne
-% suis pas pleinement satisfait de la fiabilité des contournements que je
-% connais). Vous pouvez utiliser \cs{endgraf} à la place de \cs{par} en cas de
-% besoin. Si cette limitation vous gêne, merci de me le faire savoir.
-%
-% Parlons maintenant de trois fonctionnalités d'\pf{xargs} qui sont plus ou
-% moins cachées mais que j'espère pratiques. La première est que les macros
-% sont crées si possible de façon économique : si vous utilisez
-% \cs{newcommandx} pour définir un macro que vous auriez pu définir avec
-% \cs{newcommand}, \pf{xargs} le détectera et utilisera automatiquement
-% \cs{newcommand} à la place. Ainsi, vous n'avez à vous soucier de rien et
-% vous pouvez utiliser tout le temps \cs{newcommandx} sans vous poser de
-% questions.
-%
-% La deuxième fonctionnalité est elle aussi transparente, mais comme j'ai pris
-% la peine de la coder, il faut bien que j'en parle. Une macro crée par
-% \pf{xargs} n'avalera pas les espaces qui la suivent, même si le dernier
-% argument est optionel et n'est pas spécifié. C'est un des avantages
-% d'\pf{xargs} sur les astuces classiques. Comparez les deux sur l'exemple
-% (idiot) suivant :
+% \subsection{Ajouter un préfixe}
+%
+% La commande |\newcommand| standard permet de définir au choix des
+% macros \og longues \fg{} (dont les arguments peuvent contenir des
+% \cs{par}) ou \og courtes \fg{} (les \cs{par} ou lignes vides sont
+% interdits dans les arguments) au moyen de l'étoile optionnelle. C'est
+% une partie de ce que \TeX{} appelle un préfixe, plus précisément la
+% composante \cs{long}. Les autres composantes d'un préfixe peuvent être
+% \cs{global}, \cs{outer}, ou (avec \eTeX) \cs{protected}. Il n'y a pas
+% de moyen d'utiliser ces composantes avec \cs{newcommand}, bien que,
+% par exemple, \cs{global} puisse être utile pour qu'une définition
+% faite à l'intérieur d'un groupe (comme un environnement) ne soit pas
+% \og oubliée \fg{} à la fin. (Pour des détails sur les autres, voir le
+% \TeX book ou le manuel d'\eTeX.)
+%
+% Avec \pf{xargs}, vous pouvez utiliser la clé |addprefix|, \emph{sauf}
+% pour la composante \cs{outer}, qui n'est pas et ne sera pas supportée
+% (et, à ma connaissance n'est jamais utilisée dans \LaTeXe). Remarquons
+% que cette clé \emph{ajoute} une préfixe à celui en cours, elle
+% n'écrase rien. Au début, le préfixe par défaut est \cs{long}, ou vide
+% si une étoile a été utilisée. Par exemple, les deux instructions
+% suivantes ont exactement le même effet.
+%
% \begin{quote}
-% |\newcommand\compliment[1]{#1 est gentil\complinterne}|\\
-% |\newcommand\complinterne[1][le]{#1}|\\
-% |\newcommandx\complimentx[2][2=le]{#1 est gentil#2}|
+% |\newcommandx*\truc[0][addprefix=\global, addprefix=\long,|\\
+% | addprefix=\protected]{machin}|\\
+% |\newcommandx\truc[0][addprefix=\global\protected]{machin}|
% \end{quote}
-% \newcommand\compliment[1]{#1 est gentil\complinterne}
-% \newcommand\complinterne[1][le]{#1}
-% \newcommandx\complimentx[2][2=le]{#1 est gentil#2}
-% \begin{center}\begin{tabular}{ll}
-% |\compliment{Clothilde} et\ldots| &
-% \compliment{Clothilde} et\ldots \\
-% |\complimentx{Clothilde} et\ldots| &
-% \complimentx{Clothilde} et\ldots \\
-% \end{tabular}\end{center}
-% Observez comme l'espace a été avalé de façon indésirable dans le premier
-% cas.
-%
-% Enfin, les macros d'\pf{xargs} essayent de se comporter en tous points comme
-% leurs homoloques standard. Il y a deux exceptions : la première est que vous
-% ne vous pouvez pas utiliser \cs{par} comme vous voulez, je l'ai dit plus
-% haut, et je le regrette. La deuxième réside dans certains comportements de
-% \cs{CheckCommandx}. En effet, à l'heure où j'écris ces lignes,
-% \cs{CheckCommand} souffre de deux bugs (voir
-% \href{http://www.latex-project.org/cgi-bin/ltxbugs2html?pr=latex/3971}
-% {PR/3971}) que j'espère avoir évités dans \cs{CheckCommandx}.
+%
+% En passant, les macros avec au moins un argument optionnel sont
+% définies de façon robuste au sens que \LaTeXe{} donne à ce mot, je ne
+% sais donc pas si le préfixe \cs{protected} est très utile. Je pense
+% que la possibilité d'effectuer des définitions globales est l'usage
+% principale de la clé |usedefault|.
+%
+% \subsection{Compatibilité et limitations connues}
+%
+% La mauvaise nouvelle (les limitations) en premier. Il y en a
+% essentiellement une : on ne peut pas utiliser dans la \meta{liste}
+% certaines choses, qui ne sont pas gérées correctement par
+% \pf{xkeyval}. Précisément, il s'agit des signes |#| (les lexèmes de
+% \cs{catcode} $6$) et des lexèmes \cs{par}. Aussi, aucune composante
+% de la \meta{liste} ne doit avoir l'air mal équilibrée en \cs{if}s aux
+% yeux de \TeX. Seule la première de ces limitations est partagée pas le
+% \cs{newcommand} standard, qui n'accepte pas non plus de |#| dans les
+% valeurs par défaut. Autrement, vous pouvez utiliser ce que vous
+% voulez, où vous voulez (autant que je sache).
+%
+% Maintenant les bonnes nouvelles. J'ai pris grand soin que les macros
+% définies avec \pf{xargs} ressemblent autant que possibles à celles
+% définies avec les commandes standard de \LaTeX. En fait, quand on
+% demande à \cs{newcommandx} d'effectuer une définition que
+% \cs{newcommand} aurait pu faire, la commande sera définie exactement
+% comme si on avait utilisé ce dernier. Plus précisément, le code
+% suivant (et les tests similaires) ne renvoie pas d'avertissement.
+%
+% \begin{quote}
+% |\newcommandx\truc[2][1=default]{def-truc}|\\
+% |\CheckCommand\truc[2][default]{def-truc}|\\
+% |\newcommand\chose{def-chose}|\\
+% |\CheckCommandx*\chose[0][addprefix=\long]{def-chose}|
+% \end{quote}
+%
+% De plus, il y a seulement trois points (à ma connaissance) sur
+% lesquels les commandes d'\pf{xargs} diffèrent de celles de \LaTeX{}.
+% Le premier a déjà été évoqué, c'est la limitation sur le \meta{liste}
+% due à \pf{xkeyval}. Les deuxièmes et troisièmes points, par contre,
+% sont censés être positifs. Le deuxième est donc, que j'ai essayé
+% d'éviter de reproduire dans \cs{CheckCommandx} deux
+% problèmes\footnote{%
+% \url{http://www.latex-project.org/cgi-bin/ltxbugs2html?pr=latex/3971}}
+% dont souffre l'implémentation actuelle de \cs{CheckCommand} dans
+% \LaTeX.
+%
+% Le dernier point concerne la gestion des espaces, lors de la recherche
+% du prochain caractère, pour déterminer s'il s'agit ou non d'un crocher
+% carré, quand on teste la présence d'un argument optionnel. Pour ceci,
+% je n'utilise ni la version du noyau, ni celle d'\pf{amsmath}, de
+% \cs{@ifnextchar}, mais la mienne, qui a le comportement suivant : elle
+% avale les espaces jusqu'à trouver le prochain caractère, puis les
+% restitue si ce n'était pas le début d'un argument optionnel. Je ne
+% suis plus tout à fait sûr que ce soit la bonne façon de faire, et il
+% est probable que je ferai une option à ce sujet dans une prochaine
+% version, afin que l'utilisateur puisse choisir son comportement
+% préféré.
+%
% \bigskip
%
% \begin{quote}
-% Vous savez maintenant tout ce qu'il y a à savoir sur l'utilisation de
-% \pf{xargs}. Si vous souhaitez vous pencher sur son implémentation, il vous
-% faudra lire les commentaires en anglais car je n'ai pas eu le courage de
-% commenter mon code en deux langues.
+% Vous savez maintenant absolument tout ce qu'il y a à savoir sur
+% l'utilisation de \pf{xargs}. Si vous souhaitez vous pencher sur son
+% implémentation, il vous faudra lire les commentaires en anglais car je
+% n'ai pas eu le courage de commenter mon code en deux langues.
% \end{quote}
%
% \begin{center}\large
@@ -332,119 +448,215 @@ This is a generated file. See xargs.dtx for license information.
%
% \else
%
-% The \pf{xargs} package defines an extended variant for every \LaTeX{} macro
-% related to macro definition. \pf{xargs}'s macro are named after their
-% \LaTeX{} couterparts, just adding an |x| at end, e.g. \cs{newcommandx},
-% \cs{renewcommandx} or \cs{newenvironmentx}. Since they all share the same
-% syntax (closely ressembling \cs{newcommand}'s one), I will only explain with
-% \cs{newcommandx}.
+% \subsection{Basics}
+%
+% ^^A \DescribeMacro{\newcommandx}
+% ^^A \DescribeMacro{\renewcommandx}
+% ^^A \DescribeMacro{\newenvironmentx}
+% ^^A \DescribeMacro{\renewenvironmentx}
+% ^^A \DescribeMacro{\providecommandx}
+% ^^A \DescribeMacro{\DeclareRobustCommandx}
+% ^^A \DescribeMacro{\CheckCommandx}
+% The \pf{xargs} package defines an extended variant for every \LaTeX{}
+% macro related to macro definition. \pf{xargs}'s macro are named after
+% their \LaTeX{} counterparts, just adding an |x| at end (see the list
+% in the margin). Here is the complete list:
+%
+% \begin{center}
+% \begin{tabular}{ll}
+% \cs{newcommandx} & \cs{renewcommandx} \\
+% \cs{newenvironmentx} & \cs{renewenvironmentx} \\
+% \cs{providecommandx} & \cs{DeclareRobustCommandx} \\
+% \cs{CheckCommandx}
+% \end{tabular}
+% \end{center}
+%
+% If you are not familiar with all of them, you can either just keep
+% using the commands you already know, or check Lamport's book or the
+% \LaTeX{} Companion (or any \LaTeXe{} manual) to learn the others.
+%
+% \medbreak
+%
+% Since these commands all share the same syntax, I'll always use
+% \cs{newcommandx} in the following, but remember it works the same for
+% all seven commands. (Of course, command about environments take one
+% more argument, for the end definition.) Here is |\newcommandx|'s
+% complete syntax.
%
-% Let's begin with an example. After the following definitions,
% \begin{center}
-% |\newcommandx*\vect[3][1=1, 3=n]{(#2_{#1},\ldots,#2_{#3})}|
+% \cs{newcommandx}\optstar\marg{command}\oarg{number}\oarg{list}^^A
+% \marg{definition}
% \end{center}
-% \newcommandx*\vect[3][1=1, 3=n]{(#2_{#1},\ldots,#2_{#3})}
-% you can use \cs{vect} like this:
+%
+% Everything here is the same as the usual \cs{newcommand} syntax,
+% except \meta{list}. Let's recall this briefly. The optional $*$ make
+% \LaTeX{} define a ``short'' macro, that is a macro that won't accept a
+% paragraph break (\cs{par} or an empty line) inside its argument; if
+% you don't put it, the macro will be long. \meta{command} is any
+% control sequence, and can but need not be enclosed in braces, as you
+% like. The \meta{number} specifies how many arguments your macro will
+% take (including optional ones): it should be a non-negative integer,
+% and at most $9$. The macro's \meta{definition} is a balanced text,
+% where every |#| sign must be followed by a number, thus representing
+% an argument, or by another |#| sign. The two arguments \meta{number}
+% and \meta{list} are optionals.
+%
+% \medskip
+%
+% Now comes the new and funny part. \meta{list} is a coma-separated list
+% of element \meta{digit}=\meta{value}. Here, \meta{digit} should be
+% non-zero, and at most \meta{number} (the total number of arguments).
+% The \meta{value} is any balanced text, and can be empty. If so, the
+% |=| sign becomes optional: You only need to write \meta{digit} if you
+% want the \meta{digit}th argument to be optional, with empty default
+% value. Of course, every argument whose number is a \meta{digit} in the
+% \meta{list} becomes optional, with \meta{value} as its default value.
+%
+% If you are not very familiar with some aspects of the syntax provided
+% by the \pf{xkeyval} package, you may be interested in the following
+% remarks about the syntax of \meta{list}. Since \meta{list} is
+% coma-separated, if you want to use a coma inside a \meta{value}, you
+% need to enclose it (either the coma or the whole \meta{value}) in
+% braces. The same applies if you want to use a closing square bracket
+% inside the \meta{list}. Don't worry about those unwanted braces, they
+% will be removed later. Actually, \pf{xkeyval} removes up to $3$ braces
+% set: If you really want braces around a value, you need to type
+% something like |1={{{{\large stuff}}}}|.
+%
+% \medskip
+%
+% That's all for the basics: you are now ready to use \pf{xargs}, and
+% can stop reading this doc now if you want. If, however, you are
+% wondering about what happens if you have many successive optional
+% arguments, or care about doing global definitions, or even need to
+% know precisely the limitations of \pf{xargs}, go on with the next
+% subsections.
+%
+% \subsection{The \texttt{usedefault} key}
+%
+% So, what happens with many successive optional arguments? The default
+% behaviour is that of \LaTeX's commands like \cs{makebox} or
+% \cs{parbox}: you can't specify the third argument if you didn't
+% specify the first two ones. For example, in my first example, please
+% notice how I used the mandatory argument to separate the two optional
+% ones.
+%
+% However, maybe you don't like this and prefer choosing your argument's
+% order as you want, according to their logical meaning. Ok. That's
+% exactly what the |usedefault| key is for. Just include it in the
+% \meta{list}, and you can now use |[]| to skip one optional argument
+% (using its default value) and go to the next one.
+%
% \begin{center}
+% |\newcommandx*\coord[3][2=1,3=n,usedefault]{(#2_{#1},\ldots,#2_{#3})}|
+% \newcommandx*\coord[3][2=1, 3=n, usedefault]{(#2_{#1},\ldots,#2_{#3})}
+% \par\medskip
% \begin{tabular}{ll}
-% |$\vect{x}$| & $\vect{x}$ \\
-% |$\vect[0]{y}$| & $\vect[0]{y}$ \\
-% |$\vect{z}[m]$| & $\vect{z}[m]$ \\
-% |$\vect[0]{t}[m]$| & $\vect[0]{t}[m]$ \\
+% |$\coord{x}$| & $\coord{x}$ \\
+% |$\coord{y}[0]$| & $\coord{y}[0]$ \\
+% |$\coord{z}[][m]$| & $\coord{z}[][m]$ \\
+% |$\coord{t}[0][m]$| & $\coord{t}[0][m]$ \\
% \end{tabular}
% \end{center}
%
-% You surely understood \cs{vect} is now a macro with 3 arguments, the first
-% and third being optional. They both have their own default value (resp.
-% |1| and |n|). You maybe noticed how \cs{newcommandx}'s syntax closely
-% ressembles \cs{newcommand}'s syntax: the only difference is that, instead of
-% the default value of the only optional argument, you have to specifiy the
-% number of the optional arguments, followed by a = and their default value.
-%
-% Now let's have a closer look at \cs{newcommandx}'s syntax, shared by all
-% other \pf{xargs} commands. (While dealing with details, here is the complete
-% list of those: \cs{newcommandx} and \cs{renewcommandx} for simple macros,
-% \cs{providecommandx} to make sure a macro exists, \cs{DeclareRobustCommandx}
-% to (re)define a robust macro, \cs{CheckCommandx} to check if a macro has the
-% correct meaning, \cs{newenvironmentx} and \cs{renewenvironmentx} for
-% environments.)
+% Of course, on this simple example, this is merely a matter of
+% taste, but sometimes the |usedefault| key can save you a lot of
+% typing, since the optional value for an argument can be rather long,
+% and you don't always have enough mandatory arguments to separate the
+% optional ones.
+%
+% This simple way of using |usedefault| has one problem: you can no more
+% specify an empty value for an optional argument. Of course you need a
+% special value of the argument to mean ``please use the default value
+% there'', but it doesn't need to be always the empty string. Actually,
+% you can say |usedefaut=|\meta{flag} to choose this special value. The
+% following example has no other purpose that illustrating this.
%
% \begin{center}
-% \cs{newcommandx} \meta{|*|} \marg{command} \oarg{number} \oarg{list}
-% \marg{definition}
+% |\newcommandx*\test[2][1=A, 2=B, usedefault=@]{(#1,#2)}|
+% \newcommandx*\test[2][1=A, 2=B, usedefault=@]{(#1,#2)}
+% \par\medskip
+% \begin{tabular}{ll}
+% |\test[b]| & \test[b] \\
+% |\test[][b]| & \test[][b] \\
+% |\test[@][b]| & \test[@][b] \\
+% \end{tabular}
% \end{center}
%
-% Everything here is the same as usual \cs{newcommand} syntax, except
-% \meta{list}. Let's recall this briefly. The optional |*| make \LaTeX{}
-% define a ``short'' macro, that is a macro that won't accept a paragraph
-% break (\cs{par} or an empty line) inside its argument, otherwise the macro
-% will be long. \meta{command} is any control sequence, and can but need not
-% be enclosed in braces, as you like. The \meta{number} specifies how many
-% arguments your macro will take (including optional ones): It should be a
-% non-negative integer, and at most $9$. The macro's \meta{definition} is a
-% balanced text, where every |#| sign must be followed with a number, thus
-% representing an argument, or with another |#| sign. The two arguments
-% \meta{number} and \meta{list} are optionals.
-%
-% Now comes the new and funny part. \meta{list} is a coma-separated list of
-% element \meta{digit}=\meta{value}. Here, \meta{digit} should be non-zero,
-% and at most \meta{number} (the total number of arguments). The \meta{value}
-% is any balanced text, and can be empty. If so, the |=| sign becomes
-% optional: You only need to write \meta{digit} if you want the \meta{digit}th
-% argument to be optional, with empty default value. Of course, every argument
-% whose number is a \meta{digit} in the \meta{list} becomes optional, with
-% \meta{value} as its default value.
-%
-% While using a macro with many optional arguments, keep in mind the following
-% fact. If arguments, say $1$ and $2$, are optional, then if you specify a
-% value for only one optional argument, it will be used for argument $1$, and
-% argument $2$ will be considered non-specified (thus its default value will
-% be used). This behaviour is consistent with existing \LaTeX{}'s command,
-% like \cs{makebox}. It isn't a technical limitation, I just couldn't imagine
-% a better way to do. By the way, please notice the way I separated the two
-% optional arguments from the example above in order to be able to use them
-% independantly.
-%
-% If you are not very familiar with some aspects of the syntax provided by the
-% \pf{xkeyval} package, you may be interested in the following remarks about
-% the syntax of \meta{list}. Since \meta{list} is coma-separated, if you want
-% to use a coma inside a \meta{value}, you need to enclose it (either the coma
-% or the whole \meta{value}) in braces. The same applies if you want to use a
-% closing square bracket inside the \meta{list}. Don't worry about those
-% unwanted braces, they will be removed later. Actually, \pf{xkeyval} removes
-% up to $3$ braces set: If you really want braces around a value, you need to
-% type something like |1={{{{\large stuff}}}}|.
-%
-% The last thing you (maybe) need to know about \meta{list} is a little
-% limitation of \pf{xargs}, inherited from \pf{xkeyval}, which I didn't
-% managed to work around (actually, I know a way to do it, but it fails in
-% rare cases involving \cs{let}ing an active character equal to a brace, so I
-% decided not to include it). So what is this problem? It's just you cannot
-% use \cs{par} (or an empty line) in the \meta{list}. If you need a paragraph
-% break in a \meta{value}, try \cs{endgraf}. If this issue really bothers you,
-% please let me know.
-%
-% There's only three features of \pf{xargs} not yet discussed. Since they are
-% all ``good'' features, you may not need to read the end of the
-% documentation, but since I made the effort to implement it, I want to talk
-% about it. First one is that macros are made in a minimalistic way: If you
-% use \cs{newcommandx} to create a macro you could have made with
-% \cs{newcommand}, \pf{xargs} will notice and use \cs{newcommand} internally.
-% So, you can allways use \cs{newcommandx} without bothering.
-%
-% Second feature consist in avoiding a possible problem with spaces after a
-% macro whose last argument is optional. If defined in a naive way, such
-% macros would gobble spaces after them when the optional argument is not
-% specified, but macros created with \pf{xargs} don't, so you don't need to
-% take any special care about spaces.
-%
-% Last, \pf{xargs} macros try to behave exactly as standard \LaTeX{} macros
-% do. As far as I know, there are only two exceptions. I allready mentionned
-% the first, which is the problem with \cs{par} in default value, due to
-% \pf{xkeyval}. The other one is that, right now, the current implementation
-% of \cs{CheckCommand} has some problems (see
-% \href{http://www.latex-project.org/cgi-bin/ltxbugs2html?pr=latex/3971}
-% {PR/3971}). I tried not to reproduce them in \cs{CheckCommandx}.
+% \subsection{Using a prefix}
+%
+% Standard |\newcommand| allows you to define so-called ``long'' (i. e.
+% the arguments may contain a \cs{par} token) or ``short'' (they
+% may not) macros with the optional star. This is part of what \TeX{}
+% calls a ``prefix'' for the definition, namely the \cs{long} prefix.
+% Other components of the prefix are \cs{global}, \cs{outer}, and
+% \eTeX's \cs{protected}. There is no way to use them with
+% |\newcommand|, though \cs{global} can be specially interesting in
+% order to avoid definitions made inside a group (e. g. an environment)
+% ``disappear'' at the end of the group. (For details about the other
+% possible components, see the \TeX book and \eTeX's manual.)
+%
+% With \pf{xargs}, you can use the |addprefix| key, \emph{except} for
+% the \cs{outer} prefix, which is not and will not be supported (and not
+% used anywhere I know in \LaTeXe, either). Please note that it
+% \emph{adds} a prefix to the current one, which by default is \cs{long}
+% for the unstarred form, and empty for the starred form. You can also
+% use this key many times: all prefixes will be merged together. For
+% example, the following two instructions do the exactly the same thing.
+%
+% \begin{quote}
+% |\newcommandx*\foo[0][addprefix=\global, addprefix=\long,|\\
+% | addprefix=\protected]{bar}|\\
+% |\newcommandx\foo[0][addprefix=\global\protected]{bar}|
+% \end{quote}
+%
+% By the way, macros with at least one optional argument are already
+% robust in \LaTeXe's meaning of the word, so I don't know if the
+% \cs{protected} prefix is very interesting there. Maybe the ability to
+% perform global definitions is the main use of the |addprefix| key.
+%
+% \subsection{Compatibility and known limitations}
+%
+% Okay, let's see the bad things (the limitations) first. There is
+% essentially one: you cannot use in the \meta{list} some elements,
+% because \pf{xkeyval} won't handle them properly. Namely, hash signs
+% (tokens with \cs{catcode} $6$), and \cs{par} tokens are forbidden, and
+% any part of the list should look properly \cs{if}-balanced to \TeX.
+% Only the first limitation is shared by the standard \cs{newcommand}:
+% it accepts no hash signs in a default value. Apart from this, you can
+% use anything you want, everywhere you want, as far as I know.
+%
+% Now the ``good'' features. I've tried hard to make macros defined with
+% \pf{xargs} as much similar as possible with those defined with
+% standard \LaTeX's commands. Actually, when \cs{newcommandx} is asked
+% to perform a definition which \cs{newcommand} can do, the resulting
+% macro will be defined exactly as the latter would have done. More
+% precisely, the following code (and similar tests) issues no warning.
+%
+% \begin{quote}
+% |\newcommandx\foo[2][1=default]{def-foo}|\\
+% |\CheckCommand\foo[2][default]{def-foo}|\\
+% |\newcommand\baz{def-baz}|\\
+% |\CheckCommandx*\baz[0][addprefix=\long]{def-baz}|
+% \end{quote}
+%
+% Moreover, there are only three points (to my knowledge) where
+% \pf{xargs}'s commands differ from the kernel ones. The first one was
+% already mentioned, it is due to using \pf{xkeyval} for precessing the
+% \meta{list}. The second and third points are meant to be good one.
+% Second point is: There is a bug\footnote{%
+% \url{http://www.latex-project.org/cgi-bin/ltxbugs2html?pr=latex/3971}}
+% in the current implementation of \cs{CheckCommand}, that I obviously
+% tried to avoid.
+%
+% Last, I don't use kernel's (nor \pf{amsmath}'s) version of
+% \cs{@ifnextchar}. Indeed, a problem arises when the last argument of a
+% command is optional: we have to make a choice about what to do with
+% spaces while scanning ahead for a left square bracket. I chose to scan
+% over them, and the put them back in the text in there were no
+% optional argument. I'm no more sure it is the right thing to do, and
+% I'll probably make an option to let the user decide in a future
+% version.
%
% \fi
%
@@ -452,52 +664,34 @@ This is a generated file. See xargs.dtx for license information.
%
% \section{Implementation}
%
-% \begingroup \def\leaders#1#2{}
-% \secttoc[n]
-% \endgroup
-%
-% If you are familiar with the way \LaTeXe{} manages macros with an optional
-% argument, then you will probably not be surprised by the \pf{xargs} way.
-% Indeed, with \LaTeXe{}, a command \cs{foo} defined with, say
+% First, I'd like to recall the way \LaTeXe{} handles optional
+% arguments. For example, a command \cs{foo} defined with
% |\newcommand*\foo[2][bar]{baz}| is implemented as the pair:
% \begin{quote}
% |\foo=macro:->\@protected@testopt\foo\\foo{bar}| \\
% |\\foo=macro:[#1]#2->baz|
% \end{quote}
-% With \pf{xargs}'s \cs{newcommandx}, a macro \cs{vect} as above is
-% implemented as:
-% \begin{quote}
-% |\vect=macro:->\@protected@testopt@xargs\vect\\vect|\\
-% \hspace*{1em}|{\xargs@test@opt{0},\xargs@put@arg,\xargs@test@opt{n},}|\\
-% |\\vect=macro:[#1]#2[#3]->(#2_{#1},\ldots ,#2_{#3})|
-% \end{quote}
-%
-% This is very similar: the ``real'' macro is the one whose name begins with a
-% \cs{} and the macro called by the user just checks the protection context
-% and collects the arguments for the internal macro, using the default value
-% if none is given for the optional argument(s). However, the analogy ends
-% here, since in ``normal'' \LaTeX{} there is only one optional argument, but
-% \pf{xargs} commands need more information about optional arguments,
-% namely their position, and not only the default values.
-%
-% This information is stored as a coma-separated list of ``actions'', each
-% action consisting of either the single command \cs{xargs@put@arg}, which
-% denotes a mandatory argument and makes \LaTeX{} grab it and add it to the
-% list of arguments to be passed to the internal macro, or \cs{xargs@test@opt}
-% with argument the default value, which denotes an optional argument. In the
-% later case, the presence of the optional argument is checked in a way
-% slightly differing from \LaTeXe's \cs{@ifnextchar}, then the relevant value
-% added to the arguments list.
-%
-% \subsection{Parser}
+% There is one ``external'' macro \cs{foo}, which is merely an argument
+% grabber or a parser, and an internal macro \cs{\string\foo}, which is
+% the ``real'' one. In \pf{xargs} this is quite the same, except that
+% the external macro is a bit more sophisticated. This idea of the
+% external macro being a parser, giving the arguments to the internal
+% one in a standard form, reflects in the name of \LaTeX3's experimental
+% package for extended argument syntax: \pf{xparse}.
+%
+% Here the approach is a bit different. Of course, the idea is still to
+% build a parser for the specified syntax, but since \cs{newcommandx}
+% user syntax is based on \pf{xkeyval}, we also have to care about keys
+% and there default values, and to put the whole thing in the correct
+% order before we build up the parser. We also seek for compatibility
+% with existing \LaTeXe{} commands, which adds a few tests. The
+% organisation is as follows.
%
-% All this argument grabing job is done with a loop that read and executes
-% each action from the originating list, and concurrently builds an argument
-% list such as |[0]{x}[m]| to be passed to |\\vect| for example. The first
-% part of the code consists of those macros used for the argument grabbing and
-% execution of internal command process.
+% \begingroup \def\leaders#1#2{}
+% \secttoc[n]
+% \endgroup
%
-% \medskip
+% Before we really begin, just a few preliminaries.
% First, load the \pf{xkeyval} package for it's nice key=value syntax.
% \begin{macrocode}
\RequirePackage{xkeyval}
@@ -524,10 +718,36 @@ This is a generated file. See xargs.dtx for license information.
% \end{macro}
% \end{macro}
% \end{macro}
+%
+% \subsection{Parser}
+%
+% Let's begin with a simple, concrete example. Recall that we defined a
+% command \cs{vect} with
+% |\newcommandx\vect[3]{1=0,3=n}{(#2_{#1},\ldots,#2_{#3}}| and have a
+% look at its implementation.
+% \begin{quote}
+% |\vect=macro:->\@protected@testopt@xargs\vect\\vect|\\
+% \hspace*{1em}|{\xargs@test@opt{0},\xargs@put@arg,\xargs@test@opt{n},}|\\
+% |\\vect=macro:[#1]#2[#3]->(#2_{#1},\ldots ,#2_{#3})|
+% \end{quote}
+%
+% As you can see, the parser is stored as a coma-separated list of
+% ``actions''. Here the only actions are to grab a mandatory argument or
+% to check for the presence of of an optional one. In this case, special
+% care is taken about spaces. Actually, there can be one more action,
+% associated with the |usedefaut| user key: \cs{xargs@setdefflag}, which
+% specifies the flag that says ``use the default value''.
+%
+% The parsing is done by a loop that read and executes each action from
+% the originating list, and concurrently builds an argument list such as
+% |[0]{x}[m]| to be passed to |\\vect| for example. All of this happens
+% inside a group.
+%
% \begin{macro}{\@protected@testop@xargs}
% This first macro closely resembles kernel's \cs{@protected@testopt}
-% (similarity in their names is intentional, see \cs{CheckCommandx}). It just
-% checks the protection context and call the real argument grabbing macro.
+% (similarity in their names is intentional, see \cs{CheckCommandx}). It
+% just checks the protection context and call the real argument grabbing
+% macro.
% \begin{macrocode}
\newcommand*\@protected@testopt@xargs[1]{%
\ifx\protect\@typeset@protect
@@ -538,9 +758,9 @@ This is a generated file. See xargs.dtx for license information.
% \end{macrocode}
% \end{macro}
% \begin{macro}{\xargs@read}
-% Initiate the loop. \cs{xargs@toksa} will become the call to the internal macro
-% with all arguments, \cs{xargs@toksb} contains the actions list for arguments
-% grabbing.
+% Initiate the loop. \cs{xargs@toksa} will become the call to the
+% internal macro with all arguments, \cs{xargs@toksb} contains the
+% actions list for arguments grabbing.
% \begin{macrocode}
\newcommand*\xargs@read[2]{%
\begingroup
@@ -551,10 +771,11 @@ This is a generated file. See xargs.dtx for license information.
% \end{macro}
% \begin{macro}{\xargs@continue}
% \begin{macro}{\xargs@pick@next}
-% Each iteration of the loop consist of two steps: pick the next action (and
-% remove it from the list), and execute it. When there is no more action in
-% the list, it means the arguments grabbing stage is over, and it's time to
-% execute the internal macro by expanding the contents of \cs{xargs@toksa}.
+% Each iteration of the loop consist of two steps: pick the next action
+% (and remove it from the list), and execute it. When there is no more
+% action in the list, it means the arguments grabbing stage is over, and
+% it's time to execute the internal macro by expanding the contents of
+% \cs{xargs@toksa}.
% \begin{macrocode}
\newcommand\xargs@continue{%
\expandafter\xargs@pick@next\the\xargs@toksb,\@nil
@@ -569,12 +790,15 @@ This is a generated file. See xargs.dtx for license information.
\def\xargs@temp{\expandafter\endgroup\the\xargs@toksa}%
\fi}}
% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \begin{macro}{\xargs@set@defflag}
+% Let's begin with the most simple action.
% \begin{macrocode}
\newcommand*\xargs@set@defflag[1]{%
\def\xargs@default@flag{#1}}
% \end{macrocode}
% \end{macro}
-% \end{macro}
% \begin{macro}{\xargs@put@arg}
% \begin{macro}{\xargs@test@opt}
% \begin{macro}{\xargs@put@opt}
@@ -619,13 +843,11 @@ This is a generated file. See xargs.dtx for license information.
% \begin{macro}{\xargs@ifnextchar}
% \begin{macro}{\xargs@ifnch}
% \begin{macro}{\xargs@xifnch}
-% You probably noticed that \cs{xargs@testopt} doesn't use kernel's
-% \cs{@ifnextchar}. The reason is, I don't want macros to gobble space if
-% their last argument is optional and not specified. Indeed, it would be
-% strange to have spaces after |\vect[0]{x}| gobbled. So the modified version
-% of \cs{@ifnextchar} below works like kernel's one, except that it remembers
-% how many spaces it gobbles and restitutes them in case the next non-space
-% character isn't a match.
+% Here comes a modified version of \cs{@ifnextchar}, that works like
+% kernel's one, except that it remembers how many spaces it gobbles and
+% puts them back in case the next non-space character isn't a match. Not
+% sure whether this is the better way to do, may change in future
+% versions.
% \begin{macrocode}
\newcommand\xargs@ifnextchar[3]{%
\let\xargs@temp\empty
@@ -659,26 +881,27 @@ This is a generated file. See xargs.dtx for license information.
%
% \subsection{Keys}
%
-% Okay, we are done with the execution related macros. Now let's start with
-% stuff for the definition of macros. In this part we use \pf{xkeyval}.
-% Let's start with the particular keys for options addprefix and default. Like
-% all \pf{xargs} key, we use prefix |xargs| and familly |key|. The addprefix
-% key can be used many times : each value is appended at the end of the
-% current prefix. Actually, we also construct a ``short'' prefix (without any
-% \cs{long}), for the external macro. We define them globally, since key
-% processing will happen inside a group, and the definition outside.
-% \begin{macrocode}
-\@ifdefinable\xargs@key@prefix{%
+% Okay, we are done with the parsing related macros. Now define stuff
+% for the definition of macros. In this part we use \pf{xkeyval}. Let's
+% start with the particular keys for options |addprefix| and |default|.
+% Like all \pf{xargs} key, we use the prefix |xargs| and the familly
+% |key|. The |addprefix| key can be used many times : each value is
+% appended at the end of the current prefix. Actually, we also construct
+% a ``short'' prefix (without any \cs{long}), for the external macro. We
+% define them globally, since key processing will happen inside a group,
+% and the definition outside.
+% \begin{macrocode}
+\@ifdefinable\xargs@key@addprefix{%
\define@key[xargs]{key}{addprefix}[]{%
\global\expandafter\def\expandafter\xargs@prefix\expandafter{%
\xargs@prefix#1}%
\xargs@makeshort#1\long\@nil}}
% \end{macrocode}
-% The \cs{long} tokens are removed from the prefix in a fast and easy way,
-% assuming the input is a correct prefix. (It will crash e.g. if the input
-% contains an undefined CS or braces, but this will make all crash later
-% anyway. By the way, we also assume the prefix contains no macro parameter
-% token\ldots)
+% The \cs{long} tokens are removed from the prefix in a fast and easy
+% way, assuming the input is a correct prefix. (It will crash e.g. if
+% the input contains an undefined CS or braces, but this will make all
+% crash later anyway. By the way, we also assume the prefix contains no
+% macro parameter token\ldots)
% \begin{macrocode}
\@ifdefinable\xargs@makeshort{%
\def\xargs@makeshort#1\long#2{%
@@ -688,32 +911,32 @@ This is a generated file. See xargs.dtx for license information.
\expandafter\xargs@makeshort\expandafter#2%
\fi}}
% \end{macrocode}
-% The initial prefixes will be fixed by \cs{newcommandx} and its friends when
-% they check the star: empty in the stared version, \cs{long} otherwise. For
-% this, they use \pf{xargs}'s variant or \cs{@star@or@long}:
+% The initial prefixes will be fixed by \cs{newcommandx} and its friends
+% when they check the star: empty in the stared version, \cs{long}
+% otherwise. For this, they use \pf{xargs}'s variant or
+% \cs{@star@or@long}:
% \begin{macrocode}
\newcommand\xargs@star@or@long[1]{%
\global\let\xargs@shortpref\@empty
\@ifstar{\gdef\xargs@prefix{}#1}{\gdef\xargs@prefix{\long}#1}}
% \end{macrocode}
%
-% Now, another particular key is the |usedefault| key. When used, it just sets
-% \cs{xargs@default@flag} and the corresponding boolean. Later on, this
-% will be used to possibly introduce a \cs{xargs@set@default} action at
-% the beginning of the actions list.
+% Now, another particular key is the |usedefault| key. When used, it
+% just sets \cs{xargs@default@flag} and the corresponding boolean. Later
+% on, this will be used to possibly introduce a \cs{xargs@set@default}
+% action at the beginning of the actions list.
% \begin{macrocode}
\define@key[xargs]{key}{usedefault}[]{%
\xargs@toksa{#1}\edef\xargs@default@flag{\the\xargs@toksa}}
% \end{macrocode}
%
+% \medskip
%
-% Let's continue with the more important keys. The idea is to collect through
-% \pf{xkeyval} at most 9 actions numbered 1 to \cs{xargs@max} (the total
-% number of arguments) of the type seen above, then structure them in a
-% coma-separated list for use in the definition of the user macro. Special
-% care is taken to define simpler macros in the two special cases where all
-% arguments, possibly except the first one, are mandatory (standard \LaTeXe{}
-% cases).
+% Let's continue with the more important keys. We have to collect
+% through \pf{xkeyval} at most 9 actions numbered 1 to \cs{xargs@max}
+% (the total number of arguments), each of them being
+% \cs{xargs@test@opt} or \cs{xargs@put@arg}. Latter, we will use them to
+% build up the parser.
%
% \begin{macro}{\@namenewc} \begin{macro}{\xargs@action@1}
% \begin{macro}{\xargs@action@2} \begin{macro}{\xargs@action@3}
@@ -744,15 +967,15 @@ This is a generated file. See xargs.dtx for license information.
% \end{macro} \end{macro}
% \end{macro} \end{macro}
% \begin{macro}{\xargs@def@key}
-% The next macro will define the keys for us. Its first argument is the key's
+% The next macro will define the keys. Its first argument is the key's
% number. The second argument will be discussed later.
% \begin{macrocode}
\newcommand*\xargs@def@key[2]{%
\expandafter\@ifdefinable\csname xargs@key@#1\endcsname{%
\define@key[xargs]{key}{#1}[]{%
% \end{macrocode}
-% The first thing do to, before setting any action, is to check wether this
-% key can be used for this command, and complain if not.
+% The first thing do to, before setting any action, is to check whether
+% this key can be used for this command, and complain if not.
% \begin{macrocode}
\ifnum\xargs@max<#1
\PackageError{xargs}{%
@@ -765,9 +988,9 @@ This is a generated file. See xargs.dtx for license information.
demand will be ignored.}%
\else
% \end{macrocode}
-% If the key number is correct, it may be that the user is trying to use it
-% twice for the same command. Since it's probably a mistake, issue a warning
-% in such case.
+% If the key number is correct, it may be that the user is trying to use
+% it twice for the same command. Since it's probably a mistake, issue a
+% warning in such case.
% \begin{macrocode}
\expandafter\expandafter\expandafter
\ifx\csname xargs@action@#1\endcsname\xargs@put@arg \else
@@ -776,8 +999,9 @@ This is a generated file. See xargs.dtx for license information.
Previous value will be overriden.\MessageBreak}%
\fi
% \end{macrocode}
-% If everything looks okay, define the action to be \cs{xargs@test@opt} with
-% the given value, and execute the (for now) mysterious second argument.
+% If everything looks okay, define the action to be \cs{xargs@test@opt}
+% with the given value, and execute the (for now) mysterious second
+% argument.
% \begin{macrocode}
\@namedef{xargs@action@#1}{\xargs@test@opt{##1}}%
#2%
@@ -791,11 +1015,12 @@ This is a generated file. See xargs.dtx for license information.
% \begin{macro}{\xargs@key@4} \begin{macro}{\xargs@key@5}
% \begin{macro}{\xargs@key@6} \begin{macro}{\xargs@key@7}
% \begin{macro}{\xargs@key@8} \begin{macro}{\xargs@key@9}
-% The second argument just consist in setting the value for some \cs{if} wich
-% will keep track of the existence of an optional argument other than the
-% first one, and the of the possibly otpional nature of the first. Such
-% information will be usefull when we will have to decide if we use the
-% \LaTeXe{} standard way or \pf{xargs} custom one to define the macro.
+% The second argument is used to set the value for some \cs{if} which
+% will keep track of the existence of an optional argument other than
+% the first one, and the of the possibly optional nature of the first.
+% Such information will be useful when we will have to decide if we use
+% the \LaTeXe{} standard way or \pf{xargs} custom one to define the
+% macro.
% \begin{macrocode}
\newif\ifxargs@firstopt@
\newif\ifxargs@otheropt@
@@ -814,9 +1039,9 @@ This is a generated file. See xargs.dtx for license information.
% \end{macro} \end{macro}
% \begin{macro}{\xargs@setkeys}
% \begin{macro}{\xargs@check@keys}
-% We set the keys with the starred version of \cs{setkeys}, so we can check if
-% there were some strange keys we cannot handle, and issue a meaningfull
-% warning if there are some.
+% We set the keys with the starred version of \cs{setkeys}, so we can
+% check if there were some strange keys we cannot handle, and issue a
+% meaningful warning if there are some.
% \begin{macrocode}
\newcommand\xargs@setkeys[1]{%
\setkeys*[xargs]{key}{#1}%
@@ -827,10 +1052,11 @@ This is a generated file. See xargs.dtx for license information.
\ifx\XKV@rm\empty \else
\xargs@toksa\expandafter{\XKV@rm}%
\PackageError{xargs}{%
- Illegal argument label in\MessageBreak
+ Illegal key or argument label in\MessageBreak
optional arguments description%
}{%
You can only use non-zero digits as argument labels.\MessageBreak
+ Other allowed keys are usedefault and addprefix.\MessageBreak
You wrote: "\the\xargs@toksa".\MessageBreak
I can't understand this and I'm going to ignore it.}%
\fi}
@@ -841,14 +1067,15 @@ This is a generated file. See xargs.dtx for license information.
% \subsection{Definition}
%
% \begin{macro}{\xargs@add@args}
-% Now our goal is to build two lists from our up to nine actions macros. The
-% first is the coma-separated list of actions allready discussed. The second
-% is the parameter text for use in the definition on the internal macro, for
-% example |[#1]#2[#3]|. The next macro takes the content of a
-% \cs{xargs@action@X} macro for argument and adds the corresponding items to
-% this lists. It checks if the first token of its parameter is
-% \cs{xargs@testopt} in order to know if the |#n| has to be enclosed in square
-% brackets.
+% Now our goal is to build two lists from our up to nine argument
+% grabbers, the special action |\xargs@setdefflag| and not forgetting
+% the prefix. The first list is the coma-separated list of actions
+% already discussed. The second is the parameter text for use in the
+% definition on the internal macro, for example |[#1]#2[#3]|. The next
+% macro takes the content of a \cs{xargs@action@X} macro for argument
+% and adds the corresponding items to this lists. It checks if the first
+% token of its parameter is \cs{xargs@testopt} in order to know if the
+% |#n| has to be enclosed in square brackets.
% \begin{macrocode}
\newcommand\xargs@add@args[1]{%
\xargs@toksa\expandafter{\the\xargs@toksa #1,}%
@@ -864,27 +1091,30 @@ This is a generated file. See xargs.dtx for license information.
% \end{macrocode}
% \end{macro}
% \begin{macro}{\xargs@process@keys}
-% Here comes the main input processing macro, which prepares the information
-% needed to define the final macro, and expands it to the defining macro.
+% Here comes the main input processing macro, which prepares the
+% information needed to define the final macro, and expands it to the
+% defining macro.
% \begin{macrocode}
\@ifdefinable\xargs@process@keys{%
\long\def\xargs@process@keys#1[#2]{%
% \end{macrocode}
-% Some initialisations. We work inside a group so that the default values for
-% the \cs{xargs@action@X} macros and the \cs{xargs@XXXopt@} be automatically
-% restored for the next time.
+% Some initialisations. We work inside a group so that the default
+% values for the \cs{xargs@action@X} macros and the \cs{xargs@XXXopt@}
+% be automatically restored for the next time.
% \begin{macrocode}
\begingroup
\xargs@setkeys{#2}%
\xargs@toksa{}\xargs@toksb{}%
% \end{macrocode}
-% Now the |usedefault| part.
+% Let's begin with the |usedefault| part.
% \begin{macrocode}
\@ifundefined{xargs@default@flag}{}{%
\xargs@toksa\expandafter{%
- \expandafter\xargs@set@defflag\expandafter{\xargs@default@flag}}}
+ \expandafter\xargs@set@defflag\expandafter{%
+ \xargs@default@flag}}}
% \end{macrocode}
-% Then the main loop actually builds up the two lists in the correct order.
+% Then the main loop actually builds up the two lists in the correct
+% order.
% \begin{macrocode}
\count@\z@
\@whilenum\xargs@max>\count@ \do{%
@@ -894,11 +1124,12 @@ This is a generated file. See xargs.dtx for license information.
\csname xargs@action@\the\count@\endcsname}}%
% \end{macrocode}
% Then we need to address a special case: if only the first argument is
-% optional, we use \LaTeXe's standard \cs{newcommand} construct, and we dont
-% need an actions list like the one just build, but only the default value for
-% the first argument. In this case, we extract this value from
-% \cs{xargs@action@1} by expanding it three times with a modified
-% \cs{xargs@testopt}.
+% optional, we use \LaTeXe's standard \cs{newcommand} construct, and we
+% dont need an actions list like the one just build, but only the
+% default value for the first argument. In this case, we extract this
+% value from \cs{xargs@action@1} by expanding it two times with a
+% modified \cs{xargs@testopt} (and one more expansion step for the
+% |\csname| gives $3$, hence the $2^3-1 = 7$ \cs{expandafter}s).
% \begin{macrocode}
\ifxargs@otheropt@ \else
\ifxargs@firstopt@
@@ -909,13 +1140,6 @@ This is a generated file. See xargs.dtx for license information.
\fi
\fi
% \end{macrocode}
-% Before we do the definitions, remember to execute \cs{xargs@drc@hook},
-% since the next macros will only define the internal macro(s) with a
-% \cs{DeclareRobustCommandx}, and the hook defines the user macro, with
-% the correct prefix now.
-% \begin{macrocode}
- \xargs@drc@hook
-% \end{macrocode}
% Finally expand the stuff to the next macro and, while we're at it,
% choose the next macro : depending of the existence and place of an
% optional argument, use \LaTeX's or \pf{xargs}'s way. In the \LaTeX{}
@@ -933,12 +1157,21 @@ This is a generated file. See xargs.dtx for license information.
% \end{macrocode}
% Now we can close the group and forget all about key values, etc. Time
% to conclude and actually define the macro. (The only thing not passed
-% as an argument is the prefix, which is globally set.)
+% as an argument is the prefix, which is globally set.) We also take
+% care to execute \cs{xargs@drc@hook} just outside the group.
% \begin{macrocode}
\expandafter\endgroup
+ \expandafter\xargs@drc@hook
\xargs@temp}}
% \end{macrocode}
% \end{macro}
+% \begin{macro}{\xargs@argdef}
+% \begin{macro}{\xargs@xargdef}
+% \begin{macro}{\xargs@xargsdef}
+% The first two next macros are modified versions of kernel's
+% \cs{@argdef} and \cs{@xargdef}, that do the same work, but use the
+% prefix we built, and also are simpler since they get the internal name
+% as an argument. The last one is the only new macro.
% \begin{macrocode}
\newcommand\xargs@argdef[5]{%
\@ifdefinable#1{%
@@ -956,14 +1189,18 @@ This is a generated file. See xargs.dtx for license information.
\xargs@shortpref\def#1{\@protected@testopt@xargs#1#2{#3}}%
\xargs@prefix\def#2#4{#5}}}
% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
%
% \subsection{User macros}
%
% \begin{macro}{\newcommandx}
% \begin{macro}{\xargs@newc}
-% All the internal macros are ready. It's time to define the user commands,
-% beginning with \cs{newcommandx}. Like its standard version, it just checks
-% the star and call the next macro wich grabs the number of arguments.
+% All the internal macros are ready. It's time to define the user
+% commands, beginning with \cs{newcommandx}. Like its standard version,
+% it just checks the star and call the next macro wich grabs the number
+% of arguments.
% \begin{macrocode}
\newcommand\newcommandx{%
\xargs@star@or@long\xargs@newc}
@@ -987,9 +1224,9 @@ This is a generated file. See xargs.dtx for license information.
% \end{macrocode}
% \end{macro}
% \begin{macro}{\xargs@check@max}
-% To avoid possible problems later, check right now that \cs{xargs@max} value
-% is valid. If not, warn the user and treat this value as zero. Then begin the
-% key processing.
+% To avoid possible problems later, check right now that \cs{xargs@max}
+% value is valid. If not, warn the user and treat this value as zero.
+% Then begin the key processing.
% \begin{macrocode}
\newcommand\xargs@check@max{%
\ifcase\xargs@max \or\or\or\or\or\or\or\or\or\else
@@ -1001,33 +1238,38 @@ This is a generated file. See xargs.dtx for license information.
\xargs@process@keys}
% \end{macrocode}
% \end{macro}
-% The other macros (\cs{renewcommand} etc) closely resemble their kernel
-% couterpart, since they are mostly wrappers around some call to
-% \cs{xargs@newc}. There is however an exception, \cs{CheckCommand}, which I
-% will treat first. Here my way differs from the kernel's one, since current
-% implemetation of \cs{CheckCommand} in the kernel suffers from two bugs (see
+%
+% \medskip
+%
+% The other macros (\cs{renewcommandx} etc.) closely resemble their kernel
+% homologues, since they are mostly wrappers around some call to
+% \cs{xargs@newc}. There is however two exceptions: \cs{CheckCommand}
+% and \cs{DeclareRobustCommandx}. Indeed, the current implementation of
+% \cs{CheckCommand} in the kernel suffers from two bugs (see
% \href{http://www.latex-project.org/cgi-bin/ltxbugs2html?pr=latex/3971}
-% {PR/3971}).
+% {PR/3971}) which I'm trying to avoid. For \cs{DeclareRobustCommandx},
+% the problem is to handle the prefix correctly: for that we use a hook,
+% in order to delay the external macro's definition until we get the
+% prefix right. So, let's see those two commands first.
+%
% \begin{macro}{\CheckCommandx}
% We begin as usual detecting the possible star.
% \begin{macrocode}
-\@ifdefinable\CheckCommandx{%
- \def\CheckCommandx{%
- \xargs@star@or@long\xargs@CheckC}}
+\newcommand\CheckCommandx{%
+ \xargs@star@or@long\xargs@CheckC}
\@onlypreamble\CheckCommandx
% \end{macrocode}
% \end{macro}
% \begin{macro}{\xargs@CheckC}
% \begin{macro}{\xargs@check@a}
% \begin{macro}{\xargs@check@b}
-% First, we don't use the |#2#| trick from the kernel, since it can fail if
-% there are braces in the default values. Instead, we follow the argument
-% grabing method used for \cs{new@environment}, ie calling
+% First, we don't use the |#2#| trick from the kernel, since it can fail
+% if there are braces in the default values. Instead, we follow the
+% argument grabing method used for \cs{new@environment}, ie calling
% \cs{kernel@ifnextchar} explicitly.
% \begin{macrocode}
-\@ifdefinable\xargs@CheckC{%
- \def\xargs@CheckC#1{%
- \@testopt{\xargs@check@a#1}0}}
+\newcommand\xargs@CheckC[1]{%
+ \@testopt{\xargs@check@a#1}0}
\@onlypreamble\xargs@CheckC
% \end{macrocode}
% \begin{macrocode}
@@ -1039,7 +1281,7 @@ This is a generated file. See xargs.dtx for license information.
\@onlypreamble\xargs@check@a
% \end{macrocode}
% \begin{macrocode}
-\@ifdefinable\xargs@chech@b{%
+\@ifdefinable\xargs@check@b{%
\def\xargs@check@b#1[#2][#3]{%
\xargs@check@c{#1}{[#2][{#3}]}}}
\@onlypreamble\xargs@check@b
@@ -1048,10 +1290,10 @@ This is a generated file. See xargs.dtx for license information.
% \end{macro}
% \end{macro}
% \begin{macro}{\xargs@CheckC}
-% Here comes the major difference with the kernel version. If |\\reserved@a| is
-% defined, we not only check that it is equal to |\\foo| (assuming \cs{foo} is
-% the macro being tested), we also check that \cs{foo} makes something
-% sensible, with \cs{xargs@check@d}.
+% Here comes the major difference with the kernel version. If
+% |\\reserved@a| is defined, we not only check that it is equal to
+% |\\foo| (assuming \cs{foo} is the macro being tested), we also check
+% that \cs{foo} makes something sensible, with \cs{xargs@check@d}.
% \begin{macrocode}
\newcommand\xargs@check@c[3]{%
\xargs@toksa{#1}%
@@ -1072,17 +1314,17 @@ This is a generated file. See xargs.dtx for license information.
\@onlypreamble\xargs@check@c
% \end{macrocode}
% \end{macro}
-% So, what do we want \cs{foo} to do? If |\\foo| is defined, \cs{foo} should
-% begin with one of the followings:
+% So, what do we want \cs{foo} to do? If |\\foo| is defined, \cs{foo}
+% should begin with one of the followings:
% \begin{quote}
% |\@protected@testopt \foo \\foo| \\
% |\@protected@testopt@xargs \foo \\foo|
% \end{quote}
-% Since I'm to lazy to really check this, the \cs{xargs@check@d} macro only
-% checks if the \cs{meaning} of \cs{foo} begins with \cs{@protected@test@opt}
-% (without a space after it). It does this using a macro with delimited
-% argument. Here are preliminaries to this definition: We need to have this
-% string in \cs{catcode} 12 tokens.
+% Since I'm to lazy to really check this, the \cs{xargs@check@d} macro
+% only checks if the \cs{meaning} of \cs{foo} begins with
+% \cs{@protected@test@opt} (without a space after it). It does this
+% using a macro with delimited argument. Here are preliminaries to this
+% definition: We need to have this string in \cs{catcode} 12 tokens.
% \begin{macrocode}
\def\xargs@temp{\@protected@testopt}
\expandafter\xargs@toksa\expandafter{\meaning\xargs@temp}
@@ -1091,15 +1333,15 @@ This is a generated file. See xargs.dtx for license information.
% \end{macrocode}
% \begin{macro}{\xargs@check@d}
% \begin{macro}{\xargs@check@e}
-% Now, \cs{xargs@check@c} just pass the \cs{meaning} of the command \cs{foo}
-% being checked to the allready mentionned macro with delimited arguments,
-% which will check if its first argument is empty (ie, if \cs{foo}'s
-% \cs{meaning} starts with what we want) and complain otherwise.
-% \begin{macrocode}
-\@ifdefinable\xargs@check@d{%
- \expandafter\newcommand\expandafter\xargs@check@d\expandafter{%
- \expandafter\expandafter\expandafter\xargs@check@e
- \expandafter\meaning\expandafter\reserved@a\xargs@temp\@nil}}
+% Now, \cs{xargs@check@c} just pass the \cs{meaning} of the command
+% \cs{foo} being checked to the allready mentionned macro with delimited
+% arguments, which will check if its first argument is empty (ie, if
+% \cs{foo}'s \cs{meaning} starts with what we want) and complain
+% otherwise.
+% \begin{macrocode}
+\expandafter\newcommand\expandafter\xargs@check@d\expandafter{%
+ \expandafter\expandafter\expandafter\xargs@check@e
+ \expandafter\meaning\expandafter\reserved@a\xargs@temp\@nil}
\@onlypreamble\xargs@check@d
% \end{macrocode}
% \begin{macrocode}
@@ -1123,16 +1365,61 @@ This is a generated file. See xargs.dtx for license information.
\@onlypreamble\xargs@check@complain
% \end{macrocode}
% \end{macro}
+%
+% \begin{macro}{\DeclareRobustCommandx}
+% \begin{macro}{\xargs@DRC}
+% The \pf{xargs} version of \cs{DeclareRobustCommand}, and related
+% internal macros.
+% \begin{macrocode}
+\newcommand\DeclareRobustCommandx{%
+ \xargs@star@or@long\xargs@DRC}
+% \end{macrocode}
+% \begin{macrocode}
+\newcommand*\xargs@DRC[1]{%
+ \ifx#1\@undefined\else\ifx#1\relax\else
+ \PackageInfo{xargs}{Redefining \string#1}%
+ \fi\fi
+ \edef\reserved@a{\string#1}%
+ \def\reserved@b{#1}%
+ \edef\reserved@b{\expandafter\strip@prefix\meaning\reserved@b}%
+% \end{macrocode}
+% Here is the difference from kernel's code: instead of doing the
+% definition of the user macro now, we just set the hook to do it
+% latter, when the correct prefix will be set, then disable itself for
+% next time.
+% \begin{macrocode}
+ \edef\xargs@drc@hook{%
+ \noexpand\xargs@shortpref\def\noexpand#1{%
+ \ifx\reserved@a\reserved@b
+ \noexpand\x@protect
+ \noexpand#1%
+ \fi
+ \noexpand\protect
+ \expandafter\noexpand\csname
+ \expandafter\@gobble\string#1 \endcsname}%
+ \expandafter\let\noexpand\xargs@drc@hook\relax}%
+ \let\@ifdefinable\@rc@ifdefinable
+ \expandafter\xargs@newc\csname
+ \expandafter\@gobble\string#1 \endcsname}
+% \end{macrocode}
+% And finally set a default empty hook.
+% \begin{macrocode}
+\let\xargs@drc@hook\relax
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
% \medskip
%
-% From now on, there is absolutely nothing to comment on, since the next
-% macros are mainly wrappers around \cs{xargs@newc}, just as kernel's ones are
-% wrappers around \cs{new@command}. So the code below is only copy/paste with
-% search\&replace from the kernel code.
+% From now on, there is absolutely nothing to comment, since the next
+% macros are mainly wrappers around \cs{xargs@newc}, just as kernel's
+% ones are wrappers around \cs{new@command}. So the code below is only
+% copy/paste with search\&replace from the kernel code.
%
% \begin{macro}{\renewcommandx}
% \begin{macro}{\xargs@renewc}
-% The \pf{xargs} version of \cs{renewcommand}, and related internal macro.
+% The \pf{xargs} version of \cs{renewcommand}, and it's related internal
+% macro.
% \begin{macrocode}
\newcommand\renewcommandx{%
\xargs@star@or@long\xargs@renewc}
@@ -1152,9 +1439,11 @@ This is a generated file. See xargs.dtx for license information.
% \end{macrocode}
% \end{macro}
% \end{macro}
+%
% \begin{macro}{\providecommandx}
% \begin{macro}{\xargs@providec}
-% The \pf{xargs} version of \cs{providecommand}, and related internal macro.
+% The \pf{xargs} version of \cs{providecommand}, and the related
+% internal macro.
% \begin{macrocode}
\newcommand\providecommandx{%
\xargs@star@or@long\xargs@providec}
@@ -1171,45 +1460,14 @@ This is a generated file. See xargs.dtx for license information.
% \end{macrocode}
% \end{macro}
% \end{macro}
-% \begin{macro}{\DeclareRobustCommandx}
-% \begin{macro}{\xargs@DRC}
-% The \pf{xargs} version of \cs{DeclareRobustCommand}, and related internal
-% macro.
-% \begin{macrocode}
-\newcommand\DeclareRobustCommandx{%
- \xargs@star@or@long\xargs@DRC}
-% \end{macrocode}
-% \begin{macrocode}
-\newcommand*\xargs@DRC[1]{%
- \ifx#1\@undefined\else\ifx#1\relax\else
- \PackageInfo{xargs}{Redefining \string#1}%
- \fi\fi
- \edef\reserved@a{\string#1}%
- \def\reserved@b{#1}%
- \edef\reserved@b{\expandafter\strip@prefix\meaning\reserved@b}%
- \edef\xargs@drc@hook{%
- \noexpand\xargs@shortpref\def\noexpand#1{%
- \ifx\reserved@a\reserved@b
- \noexpand\x@protect
- \noexpand#1%
- \fi
- \noexpand\protect
- \expandafter\noexpand\csname
- \expandafter\@gobble\string#1 \endcsname}%
- \expandafter\let\noexpand\xargs@drc@hook\relax}%
- \let\@ifdefinable\@rc@ifdefinable
- \expandafter\xargs@newc\csname
- \expandafter\@gobble\string#1 \endcsname}
-\let\xargs@drc@hook\relax
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
+%
% \begin{macro}{\newenvironment}
% \begin{macro}{\xargs@newenv}
% \begin{macro}{\xargs@newenva}
% \begin{macro}{\xargs@newenvb}
% \begin{macro}{\xargs@new@env}
-% The \pf{xargs} version of \cs{newenvironment}, and related internal macros.
+% The \pf{xargs} version of \cs{newenvironment}, and related internal
+% macros.
% \begin{macrocode}
\newcommand\newenvironmentx{%
\xargs@star@or@long\xargs@newenv}
@@ -1245,10 +1503,11 @@ This is a generated file. See xargs.dtx for license information.
% \end{macro}
% \end{macro}
% \end{macro}
+%
% \begin{macro}{\renewenvironment}
% \begin{macro}{\xargs@renewenv}
-% The \pf{xargs} version of \cs{renewenvironment}, and related internal
-% macro.
+% The \pf{xargs} version of \cs{renewenvironment}, and the related
+% internal macro.
% \begin{macrocode}
\newcommand\renewenvironmentx{%
\xargs@star@or@long\xargs@renewenv}