12.1 \newcommand & \renewcommand

Synopsis, l’un parmi (trois formes ordinaires, trois formes étoilées) :

\newcommand{\cmd}{défn}
\newcommand{\cmd}[nargs]{défn}
\newcommand{\cmd}[nargs][optargdéfaut]{défn}
\newcommand*{\cmd}{défn}
\newcommand*{\cmd}[nargs]{défn}
\newcommand*{\cmd}[nargs][optargdéfaut]{défn}

ou toutes les mêmes possibilités avec \renewcommand au lieu de \newcommand :

\renewcommand{\cmd}{défn}
\renewcommand{\cmd}[nargs]{défn}
\renewcommand{\cmd}[nargs][optargdéfaut]{défn}
\renewcommand*{\cmd}{défn}
\renewcommand*{\cmd}[nargs]{défn}
\renewcommand*{\cmd}[nargs][optargdéfaut]{défn}

Définit ou redéfinit une commande (voir aussi \DeclareRobustCommand dans Class and package commands).

La forme étoilée (en *) de ces commandes interdit que les arguments contiennent une multiplicité de paragraphes de texte (la commande n’est pas \long, dans la terminologie de TeX de base). Avec la forme par défaut, il est possible qu’un argument soit une multiplicité de paragraphes.

Description des paramètres (des exemples suivront) :

cmd

Obligatoire ; \cmd est le nom de la commande. Il doit commencer par une controblique, \, et ne doit pas commencer avec la chaîne de 4 caractères \end. Pour \newcommand, il ne doit pas être déjà défini et ne doit pas commencer avec \end ; pour \renewcommand, il doit être déjà défini.

nargs

Optionnel ; un entier compris entre 1 et 9 spécifiant le nombre d’arguments que la commande prend, y compris un éventuel argument optionnel. Si cet argument n’est pas présent, alors la spécification par défaut est que la commande ne prend aucun argument. Lorsque on redéfinit une commande, la nouvelle version peut prendre un nombre différent d’arguments par rapport à l’ancienne.

optargdéfaut

Optionnel ; si cet argument est présent, alors le premier argument de la commande \cmd en définition est optionnel, et sa valeur par défaut est optargdéfaut (qui peut être une chaîne vide). Si cet argument n’est pas présent, alors \cmd ne prend pas d’argument optionnel.

C’est à dire que si \cmd est appelée avec à la suite un argument entre crochets, comme dans \cmd[valopt], alors au sein de défn le paramètre #1 est réglé à valopt. Par contre si \cmd est appelé sans crochet à la suite, alors au sein de défn le paramètre #1 est réglé à optargdéfaut. Dans les deux cas, les arguments obligatoires commencent par #2.

Omettre [optargdéfaut] d’une définition est très différent de mettre des crochets vides, comme dans []. Dans le premier cas on dit que la commande ainsi définie ne prend pas d’argument optionnel, de sorte que #1 est le premier argument obligatoire (à supposer que nargs ≥ 1) ; dans le second cas on règle l’argument optionnel #1 à être une chaîne vide par défaut, c.-à-d. si aucun argument optionnel n’est donné à l’appel.

De même, omettre [valopt] d’un appel est également très différent que de donner des crochets vides, comme dans []. Dans le premier cas on règle #1 à la valeur de valopt (à supposer que la commande a été définie pour prendre un argument optionnel) ; alors que dans le second on règle #1 à la chaîne vide, comme on le ferait pour n’importe quelle autre valeur.

Si une commande n’est pas définie pour prendre un argument optionnel, mais qu’elle est appelée avec un argument optionnel, les résultats sont imprévisibles : il peut y avoir une erreur LaTeX, une sortie incorrectement composée, ou les deux.

défn

Obligatoire ; le texte par lequel substituer chaque occurrence de \cmd. Les paramètres #1, #2, …, #nargs sont remplacés par les valeurs fournies en appelant la commande (ou par optargdéfaut dans le cas d’un argument optionnel non spécifié dans l’appel, comme cela vient d’être expliqué).

TeX ignore les blancs dans le code source à la suite d’un mot de contrôle (voir Control sequences), comme dans ‘\cmd ’. Si vous désirez une espace réellement à cet endroit, une solution est de taper {} après la commande (‘\cmd{} ’), et une autre est d’utiliser un espace de contrôle explicite (‘\cmd\ ’).

Un exemple simple de définition d’une nouvelle commande : \newcommand{\JM}{Jean Martin} a pour effet le remplacement de \JM par le texte plus long de la définition. La redéfinition d’une commande existante est similaire : \renewcommand{\symbolecqfd}{{\small CQFD}}.

Si vous utilisez \newcommand et que le nom de commande a déjà été utilisé alors vous obtenez quelque chose du genre de ‘LaTeX Error: Command \fred already defined. Or name \end... illegal, see p.192 of the manual’. Si vous utilisez \renewcommand et que le nom de commande n’a pas encore été utilisé alors vous obtenez quelque chose du genre de ‘LaTeX Error: \hank undefined’.

Dans l’exemple suivant la première définition crée une commande sans argument, et la seconde, une commande avec un argument obligatoire :

\newcommand{\etudiant}{Melle~O'Leary}
\newcommand{\defref}[1]{Définition~\ref{#1}}

Utilisez la première commande comme dans Je confie \etudiant{} à vos bons soins. La seconde commande a un argument variable, de sorte que \defref{def:base} se développe en Definition~\ref{def:base}, ce qui en fin de compte se développera en quelque chose du genre de ‘Définition~3.14’.

Un exemple avec deux arguments obligatoires : \newcommand{\nbym}[2]{$#1 \times #2$} est invoqué comme \nbym{2}{k}.

Un exemple avec un argument optionnel :

\newcommand{\salutation}[1][Madame, Monsieur]{#1,}

Alors, \salutation donne ‘Madame, Monsieur,’ alors \salutation[Cher Jean] donne ‘Cher Jean,’. Et \salutation[] donne ‘,’.

Cet exemple a un argument optionnel et deux arguments obligatoires.

\newcommand{\avocats}[3][cie]{#2, #3, et~#1}
J'emploie \avocats[Odette]{Devoie}{Trichou}.

En sortie on a ‘J'emploie Devoie, Trichou, et Odette’. L’argument optionnel, c.-à-d. Odette, est associé à #1, alors que Devoie et Trichou le sont à #2 et #3. À cause de l’argument optionnel, \avocats{Devoie}{Trichou} donne en sortie ‘J'emploie Devoie, Trichou, et cie’.

Les accolades autour de défn ne définissent pas un groupe, c.-à-d. qu’elle ne délimitent pas la portée du résultat du développement de défn. Ainsi la définition \newcommand{\nomnavire}[1]{\it #1} est problématique dans cette phrase :

Le \nomnavire{Monitor} rencontra le \nomnavire{Merrimac}.

les mots ‘rencontra le’, et le point, sont mis incorrectement en italique. La solution est de mettre une paire supplémentaire d’accolades au sein de la définition : \newcommand{\nomnavire}[1]{{\it #1}}.