Environnements

TeX lui-même n'a pas de commande \begin. Le plain TeX de Knuth ne définit que \beginsection ; la forme \begin{...} … \end{...} a été ajoutée par LaTeX. Pourquoi l'avoir ajoutée ? La réponse tient en une seule promesse : dès que \end est franchi, tout ce qui a été modifié à l'intérieur revient à son état antérieur. Ce mécanisme, l'environnement, a donné la même forme aux listes, aux équations hors texte, aux figures, aux citations, et jusqu'au corps du document lui-même. Cette page expose ce qu'un environnement LaTeX garantit, comment les environnements s'imbriquent, et comment lire le message \begin{...} ended by \end{...} lorsque les deux noms ne concordent pas.

Ce que \begin et \end garantissent

Ce qu'un environnement garantit, c'est un groupe. \begin{name} ouvre un groupe TeX avant même d'avoir déterminé ce que l'environnement est censé faire, et \end{name} le referme. Ainsi, quoi que l'on modifie à l'intérieur — police, marges, n'importe quoi —, rien n'en subsiste à la ligne suivant \end. L'environnement center centre son contenu, itemize en fait une liste à puces, quote élargit les deux marges, et chacun de ces effets s'achève à l'intérieur de sa propre portée. Autrement dit, un environnement ne fournit pas un ornement mais une garantie de remise en état, et c'est précisément pourquoi la règle est de commencer par un environnement.

Les noms de \begin{name} et de \end{name} doivent coïncider exactement : on ne peut pas ouvrir \begin{center} et fermer avec \end{flushleft}. En coulisses, LaTeX accomplit le travail ingrat de retenir le nom de l'environnement actuellement ouvert — c'est pourquoi son message d'erreur peut citer les deux noms et le numéro de la ligne d'ouverture. Le document ne fait pas exception : \begin{document} … \end{document} est un véritable environnement, et la règle de base voulant que le corps du texte s'y trouve n'est que le constat banal qu'il se trouve dans l'environnement le plus extérieur.

\begin{center}
This paragraph is centred; the line after \end is not.
\end{center}

\begin{quote}
  {\itshape Everything inside is a group,}
  so this italic never escapes the environment.
\end{quote}

Imbriquer : fermer dans l'ordre inverse de l'ouverture

Les environnements peuvent s'imbriquer, mais on les ferme exactement dans l'ordre inverse de leur ouverture : si \begin{b} est ouvert à l'intérieur de \begin{a}, on écrit d'abord \end{b}, puis \end{a}. Les portées ne peuvent pas se chevaucher, comme dans \begin{a}\begin{b}...\end{a}\end{b}. La raison est la garantie de la section précédente : un environnement étant un groupe, les groupes ne peuvent que s'emboîter comme des boîtes, et la forme à moitié chevauchante n'existe tout simplement pas. Une liste dans une citation, un tableau dans une figure, une équation dans un théorème : toutes les combinaisons rencontrées en pratique s'écrivent naturellement comme une telle imbrication.

\begin{quote}
  A bulleted list inside a quotation:
  \begin{itemize}
    \item first
    \item second
  \end{itemize}
\end{quote}

Une seule habitude vaut la peine ici : quand vous ouvrez un environnement, écrivez la ligne de fermeture avant le contenu. Indentez ensuite l'intérieur de deux ou quatre espaces, et les appariements — un tabular dans un figure, un itemize dans un quote — deviennent visibles dans la forme même de la source. Plus l'imbrication est profonde, plus il est facile de se tromper d'\end en remplaçant le contenu plus tard, et comme le montre la section suivante, cet accident-là ne se manifeste pas là où il a été commis.

Les environnements rencontrés en premier, classés par usage

Les environnements fournis par LaTeX standard s'éclairent si on les considère en cinq familles : alignement du texte, listes, mathématiques, flottants et matière tabulaire. Le détail de chacun relève de sa propre page, mais la forme est partout identique : ouvrir avec \begin, fermer avec \end, et l'intérieur est un groupe. Devant un environnement inconnu, se demander d'abord « quelle portée délimite-t-il ? » mène généralement au but.

Trois couples de cette liste prêtent régulièrement à confusion. quote et quotation : tous deux indentent la citation à gauche et à droite, mais quotation indente en plus la première ligne de chaque paragraphe, ce qui convient aux longues citations sur plusieurs paragraphes. figure/table et tabular : ce sont des choses entièrement différentes — le premier couple est « un conteneur flottant portant légende et numéro », le second « la grille elle-même ». Si un tableau a besoin d'un numéro et de renvois, on place le tabular dans un table. Et verbatim imprime son contenu en chasse fixe exactement comme il a été saisi, refusant d'interpréter même \ ou { comme des commandes : la façon classique de montrer du code source.

Certains environnements prennent des arguments, donnés dans les {...} ou [...] qui suivent directement \begin. tabular, par exemple, exige une spécification de colonnes : le {cc} de \begin{tabular}{cc} donne l'alignement de chaque colonne (c centré, l à gauche, r à droite) ; à l'intérieur, & sépare les colonnes et chaque ligne se termine par \\. De même, figure reçoit une préférence de placement en option, comme dans \begin{figure}[htbp]. Les arguments viennent toujours juste après le nom de l'environnement ; on n'écrit jamais rien du côté \end.

\begin{figure}[htbp]
  \centering
  \begin{tabular}{ll}
    input  & output \\
    source & PDF    \\
  \end{tabular}
  \caption{A tabular grid inside a floating table}
  \label{tab:demo}
\end{figure}

align et align* : l'astérisque fait partie du nom

Un nom terminé par * est la version qui ne numérote rien. align numérote chaque ligne ; \begin{align*} … \end{align*} n'en numérote aucune. equation* suit la même idée : une équation hors texte sans numéro. Le point piquant est que ce * n'est ni une option ni un argument, mais une partie du nom lui-même. \begin assemble directement la chaîne reçue en un nom de commande, si bien qu'une commande réellement nommée align* — astérisque compris — voit le jour. Comme l'a montré la page précédente, le nom d'un mot de contrôle s'arrête au premier caractère non alphabétique : cette commande ne peut donc jamais être appelée en tapant \align*, et le seul accès reste \begin{align*}.

\begin{align}          % every line gets an equation number
  a &= b + c \\
  d &= e + f
\end{align}

\begin{align*}         % same layout, no numbers at all
  a &= b + c \\
  d &= e + f
\end{align*}

Quand apparaît \begin{...} ended by \end{...}

Ce message ne dit pas « vous avez mal fermé » mais « voici ce qui était ouvert ». Quand les noms divergent, LaTeX s'arrête sur quelque chose comme ! LaTeX Error: \begin{center} on input line 5 ended by \end{flushleft}., en citant le nom de l'environnement ouvert et son numéro de ligne. C'est la première moitié qu'il faut lire, pas le \end de la seconde : la ligne signalée est presque toujours celle du \end, tandis que l'endroit à corriger est la ligne indiquée par la première moitié. Un \end oublié produit la même forme de message, avec \end{document} pour vis-à-vis : ! LaTeX Error: \begin{itemize} on input line 2 ended by \end{document}. signifie que l'itemize ouvert à la ligne 2 n'a jamais été fermé.

Un nom mal orthographié se comporte un peu différemment. Écrivez un nom non défini comme \begin{itemzie} et vous obtenez d'abord ! LaTeX Error: Environment itemzie undefined., puis ! LaTeX Error: \begin{document} ended by \end{itemzie}. Deux erreurs apparaissent parce que \begin ouvre le groupe avant de vérifier si l'environnement existe. Le groupe reste ouvert et le \end correspondant ne s'apparie plus avec personne. D'où une règle pratique : corriger les erreurs une à une en partant du haut et recompiler, en ignorant tout ce qui suit la première. Autour des environnements en particulier, la première erreur est très souvent la cause de la seconde.

Un dernier indice distingue les deux cas. Une accolade non fermée produit un message de TeX lui-même, non de LaTeX. Vers la fin du journal, on ne trouve que (\end occurred inside a group at level 1), sans numéro de ligne. C'est un groupe ordinaire et sans nom qui est resté ouvert : TeX n'a rien pour répondre au « où ». Lu à l'envers, cela devient un diagnostic : un message avec numéro de ligne signale une discordance d'environnement, celui-ci seul signale une accolade. Pour restreindre le champ, extraire l'environnement suspect dans un fichier séparé et le compiler seul reste la voie la plus rapide.

Choisir un environnement par le sens, non par l'apparence

Un environnement n'est pas une boîte visuelle : c'est le nom d'une partie du manuscrit. Choisir quote parce qu'il s'agit d'une citation, itemize parce que c'est une liste d'éléments, tabular parce que c'est une grille, figure ou table parce qu'un numéro et des renvois sont nécessaires — et légendes, numérotation, références et tables des figures suivront naturellement. À l'inverse, choisir toujours d'après l'apparence — « center parce que je veux centrer », « quote parce que je veux de la marge » — et, six mois plus tard, on ne saura plus à quoi servait telle boîte, ni changer la mise en forme d'un seul geste. Si l'on ne veut qu'un changement visuel, recourir à une déclaration ou à une commande d'espacement est plus honnête qu'à un environnement.

• Le contenu est une citation — utiliser quote ou quotation, et citer la source dans le texte ou en note.
• Le contenu est une liste logique — utiliser itemize, enumerate ou description ; ne pas simuler des puces avec \\.
• Une figure ou un tableau a besoin de numéro et de renvois — placer \caption et \label dans figure ou table, et laisser la grille à tabular.
• La même combinaison revient sans cesse — plutôt que de copier des commandes locales de mise en forme, la nommer avec \newenvironment et en fixer le sens.

Comme le suggère ce dernier point, les environnements ne se contentent pas d'être utilisés : ils se définissent aussi. \newenvironment reçoit le code à exécuter au début et celui à exécuter à la fin ; \renewenvironment remanie un nom déjà existant. Les détails — comment les arguments sont transmis, pourquoi le côté \end ne peut pas les utiliser, et l'interface moderne NewDocumentEnvironment — sont réunis sur la page consacrée aux environnements personnels. Ce qu'il faut retenir ici tient en une phrase : un environnement que vous définissez hérite exactement de la garantie de groupe décrite dans cette section, sans effort supplémentaire.