12.8 \newenvironment & \renewenvironment

Ces commandes définissent ou redéfinissent un environnement env, c.-à-d., \begin{env} corps \end{env}.

Synopsis :

  \newenvironment{env}[nargs][argoptdéfaut]{défdébut}{déffin}
  \newenvironment*{env}[nargs][argoptdéfaut]{défdébut}{déffin}
\renewenvironment{env}[nargs]{défdébut}{déffin}
\renewenvironment*{env}[nargs]{défdébut}{déffin}

La forme étoilée de ces commandes exige que les arguments (à ne pas confondre avec le corps de l’environnement) ne contiennent pas de paragraphes de texte.

env

Obligatoire ; le nom de l’environnement. Il est constitué seulement de lettres ou du caractère astérisque *, et donc ne commence pas par une controblique \. Il ne doit pas commencer par la chaîne end. Pour \newenvironment, env ne doit pas être le nom d’un environnement déjà existant, et la commande \env ne doit pas être définie. Pour \renewenvironment, env doit être le nom d’un environnement déjà existant.

nargs

Optionnel ; un entier de 0 à 9 indiquant le nombre d’arguments que l’environnement attend. Quand l’environnement est utilisé, ces arguments apparaissent après le \begin, comme dans \begin{env}{arg1}…{argn}. Si cet argument n’est pas présent, alors par défaut l’environnement n’attend pas d’argument. Lorsqu’on redéfinit un environnement, la nouvelle version peut prendre un nombre différent d’arguments que la précédente.

argoptdéfaut

Optionnel ; si cet argument est présent alors le premier argument de l’environnement en définition est optionnel, et sa valeur par défaut est argoptdéfaut (éventuellement une chaîne vide). Si cet argument n’est pas présent alors l’environnement ne prend pas d’argument optionnel.

c.-à-d. que si [argoptdéfaut] est présent dans la définition de l’environnement alors vous pouvez commencer l’environnement avec des crochets, comme dans \begin{env}[valopt]{...} ... \end{env}. Dans ce cas, au sein de défdébut, le paramètre #1 est réglé à la valeur de valopt. Si par contre \begin{env} est appelé sans être suivi de crochet, alors, au sein de défdébut, le paramètre #1 est réglé à la valeur par défaut optargdéfaut. Dans les deux cas, le premier paramètre obligatoire, s’il en est, est #2.

Omettre [valopt] dans l’appel est différent d’avoir des crochets sans contenu, comme dans []. Dans le premier cas #1 se développe en argoptdéfaut, et dans le second en une chaîne vide.

défdébut

Obligatoire ; le texte qui est développé à toute occurrence de \begin{env} ; au sein de défdébut, le nième paramètre positionnel, (c.-à-d. #n), est remplacé au sein de défdébut par le texte du nième argument.

déffin

Obligatoire ; le texte développé à toute occurrence de \end{env}. Il ne doit contenir aucun paramètre positionnel, ainsi #n ne peut pas être utilisé ici (mais voyez l’exemple final ci-après).

Tous les environnements, c’est à dire le code de défdébut, le corps de l’environnement, et le code déffin, sont traités au sein d’un groupe. Ainsi, dans le premier exemple ci-dessous, l’effet de \small est limité à la citation et ne s’étend pas à la matière qui suit l’environnement.

Cet exemple dont un environnement semblable à quotation de LaTeX à ceci près qu’il sera composé dans une taille de police plus petite :

\newenvironment{smallquote}{%
  \small\begin{quotation}
}{%
  \end{quotation}
}

Celui-ci montre l’utilisation des arguments ; cela donne un environnement de citation qui affiche l’auteur :

\newenvironment{citequote}[1][Corneille]{%
  \begin{quotation}
  \noindent\textit{#1}:
}{%
  \end{quotation}
}

Le nom de l’auteur est optionnel, et vaut par défaut ‘Corneille’. Dans le document, utilisez l’environnement comme ceci :

\begin{citequote}[Clovis, roi des Francs]
  ...
\end{citequote}

Ce dernier exemple montre comment sauvegarder la valeur d’un argument pour l’utiliser dans déffin, dans ce cas dans une boîte (voir \sbox & \savebox).

\newsavebox{\quoteauthor}
\newenvironment{citequote}[1][Corneille]{%
  \sbox\quoteauthor{#1}%
  \begin{quotation}
}{%
  \hspace{1em plus 1fill}---\usebox{\quoteauthor}
  \end{quotation}
}