Classe de document et préambule

Le 1er juin 1994, LaTeX a scindé une commande en deux, et depuis, tout document LaTeX commence de la même façon : une ligne \documentclass, puis un préambule de déclarations \usepackage. Auparavant on écrivait \documentstyle[12pt,twoside]{article}, en entassant options et styles additionnels entre les mêmes crochets. Séparer la classe de document des packages n'était pas une affaire de rangement. La classe décide ce qu'est le document — article, rapport, livre, jeu de diapositives — et le préambule décide ce qu'il sait faire. Cette frontière bien tracée, une revue recompose tout le manuscrit en modifiant une seule ligne ; mal tracée, la soirée prévue pour écrire passe à traquer Option clash for package geometry.

Ce que \documentclass décide vraiment

\documentclass[options]{class} est la seule commande qui doit venir en premier dans un document ; rien ne peut la précéder, sauf un commentaire commençant par %. Les accolades contiennent le nom de la classe, les crochets les options — et ce nom entre accolades désigne un fichier bien réel. Écrire article charge article.cls, quelques centaines de lignes de définitions qui ne contiennent que des règles. Un titre \section, par exemple, se compose en \Large\bfseries avec 3.5ex d'espace au-dessus et 2.3ex en dessous ; ces trois valeurs sont écrites telles quelles dans article.cls. Du texte de l'auteur, il n'y a pas un seul caractère.

Cette division du travail n'a rien d'accidentel. Au début des années 1980, Leslie Lamport commençait un livre, jugea insuffisant le paquet de macros alors en circulation et se dit qu'avec un peu d'effort supplémentaire les macros dont il avait besoin pourraient servir à d'autres. Dans un entretien de janvier 2000 pour les DMV-Mitteilungen, il présente cela comme l'origine de LaTeX. Une classe, c'est donc la séparation de la structure et de l'apparence coulée dans un fichier. Dans le corps on écrit \section{Introduction} — le sens, rien d'autre — et c'est à la classe de le composer en gras et en grand, de le numéroter et de ménager l'espace au-dessus. C'est exactement pour cela que sociétés savantes et éditeurs diffusent leurs propres classes : amsart, IEEEtran, elsarticle, revtex4-2 et acmart existent bel et bien et sont imposées par certaines consignes de soumission. Lamport avait lui-même défendu l'idée à la fin des années 1980, en proposant à l'ACM de produire des styles de document standard pour TeX/LaTeX, troff et Scribe afin d'accélérer les soumissions électroniques — un éditeur de l'ACM refusa.

% Only the first line changes; the body stays as it is.
\documentclass[11pt,a4paper]{article}  % top level heading is \section
% \documentclass[11pt,a4paper]{book}   % \chapter becomes available

\begin{document}
\section{Introduction}
The source carries the structure; the class supplies the appearance.
\end{document}

article, report, book : ce qui change vraiment

En pratique, la différence tient à deux choses : y a-t-il des chapitres et le recto verso est-il supposé. article.cls ne définit aucun \chapter, si bien que \section en est le niveau supérieur ; report.cls et book.cls en définissent un. Les valeurs par défaut figurent sur la ligne \ExecuteOptions de chaque fichier de classe : article utilise letterpaper,10pt,oneside,onecolumn,final, report y ajoute openany, et seul book passe à twoside et openright. Le piège, c'est le format du papier : les trois supposent letterpaper, donc pour de l'A4 il faut demander a4paper explicitement. Le titre diffère également : dans article il s'enchaîne en haut de la première page, tandis que report et book lui réservent une page entière.

book dispose d'un mécanisme supplémentaire : \frontmatter / \mainmatter / \backmatter, qui traduisent les usages du livre imprimé en une ligne chacun ou presque. \frontmatter appelle \pagenumbering{roman} : préface et table des matières passent en chiffres romains minuscules (i, ii, iii…) et les chapitres ne sont plus numérotés. \mainmatter appelle \pagenumbering{arabic}, repart de 1 et rétablit la numérotation des chapitres. \backmatter conserve la pagination arabe mais supprime de nouveau les numéros de chapitre, afin que l'index ne s'intitule pas « Chapitre 12 Index ». Tout livre dont la préface est paginée i, ii, iii et dont le texte reprend à 1 est le produit de ces trois lignes.

Quand les quatre classes standard ne suffisent pas, CTAN en propose une pour presque chaque usage. Pour un exposé, beamer est le choix par défaut : un environnement frame donne une diapositive, avec affichage progressif (overlays) et thèmes fournis. Si la typographie par défaut des classes standard paraît datée, les classes KOMA-Script scrartcl / scrreprt / scrbook correspondent à article / report / book et offrent une interface de réglage bien plus riche. Pour la composition japonaise, les options sont jsarticle / jsbook (les jsclasses, maintenues par Haruhiko Okumura et l'équipe texjporg) sous pLaTeX / upLaTeX, leurs équivalents LuaTeX-ja ltjsarticle / ltjsbook sous LuaLaTeX, et jlreq, fondée sur les Requirements for Japanese Text Layout (JLReq), qui détecte le moteur automatiquement et bascule vers un comportement de type report ou book via les options report et book. Dans tous les cas la première question est la même : la classe correspond-elle au moteur utilisé ?

Ce que signifient les options de \documentclass

Les options sont des interrupteurs séparés par des virgules, placés entre crochets et valables pour tout le document, comme dans \documentclass[11pt,a4paper,twoside]{article}. L'ordre est indifférent, et si deux options d'une même famille sont données (oneside et twoside, par exemple), la dernière l'emporte. Le tableau ci-dessous recense celles qui servent réellement, mais ce sont les valeurs par défaut qu'il faut retenir : texte à 10pt, papier letterpaper, mise en page onecolumn. Pour imprimer en A4, a4paper doit être écrit à chaque fois.

Un mécanisme piège ici tout le monde au moins une fois. Les options écrites dans \documentclass n'appartiennent pas qu'à la classe : elles sont transmises à chaque package chargé ensuite comme options globales. Dans la terminologie de clsguide, ce qui est donné directement à \usepackage[...] est une option locale, ce qui est donné à \documentclass[...] une option globale, et un package récupère dans les deux sources les noms qu'il reconnaît. Ainsi \documentclass[twocolumn]{article} bascule silencieusement en deux colonnes tous les packages qui savent le gérer. Ce même mécanisme est aussi le remède à ! LaTeX Error: Option clash for package geometry., qui surgit lorsqu'un package est chargé deux fois avec des options différentes, le plus souvent parce qu'une classe ou un modèle l'a déjà chargé. Le conseil que LaTeX donne lui-même dans le journal est de remonter l'option dans la déclaration \documentclass, car une option globale n'entre pas en conflit avec un second chargement.

Ce qui va dans le préambule et ce qui va dans le corps

Le préambule va de la ligne suivant \documentclass jusqu'à juste avant \begin{document}, et ne peut contenir que des déclarations — pas un seul caractère de texte courant. Une phrase ordinaire à cet endroit arrête la compilation sur ! LaTeX Error: Missing \begin{document}. Le nom induit en erreur ; le sens est : « quelque chose d'imprimable est arrivé avant le début du corps ». La même ligne apparaît quand un commentaire % du préambule reste inachevé ou qu'une espace insécable ou pleine chasse s'y glisse. Le cas symétrique est l'appel de \usepackage dans le corps, qui donne ! LaTeX Error: Can be used only in preamble. — tous les packages doivent être là avant la composition de la première page.

• Chargement des packages — \usepackage[options]{package}. On peut les regrouper en \usepackage{amsmath,amssymb}, mais cette forme ne peut pas porter d'options.
• Métadonnées de titre — \title{...}, \author{...}, \date{...}. Ce qui les compose réellement, c'est \maketitle dans le corps ; par convention, ces trois déclarations restent dans le préambule.
• Commandes et environnements personnels — \newcommand, \renewcommand, \newenvironment, pour les constructions utilisées dans tout le document.
• Longueurs et compteurs — \setlength{\parindent}{0pt}, \setcounter{tocdepth}{2} et autres valeurs valables pour tout le document.
• Style de page et configuration des packages — \pagestyle{headings}, \hypersetup{...}, \graphicspath{{figures/}} : les réglages faits après le chargement.
• Ce qui n'a rien à y faire — titres, paragraphes, figures, tableaux ; tout ce qui apparaît dans la sortie va après \begin{document}.

Dans quel ordre charger les packages ?

La plupart des packages se moquent de l'ordre, mais les exceptions méritent d'être retenues. La plus célèbre est hyperref, dont le manuel indique sans détour qu'il doit venir en dernier parmi les packages chargés. La raison est brutale : le travail de hyperref consiste à redéfinir quantité de commandes LaTeX ; le charger trop tôt permet à un package suivant d'écraser ces redéfinitions, et les liens comme les signets PDF se cassent en silence. Le manuel assortit ce conseil d'une note de bas de page : un travail a commencé pour réduire le nombre de redéfinitions et, avec lui, la dépendance à l'ordre de chargement. C'est donc un contournement actuel plutôt qu'une loi définitive.

Et ce « dernier » connaît une exception célèbre : cleveref doit être chargé après hyperref. cleveref construit ses commandes de référence en détectant ce que hyperref a défini ; l'ordre inverse ne fonctionne tout simplement pas. Si varioref s'y ajoute, l'ordre prescrit par son manuel est varioref → hyperref → cleveref. Ce piège est redoutable parce qu'il échoue en silence : le manuel de cleveref avertit qu'avec un mauvais ordre, les renvois pointeront vers tout autre chose sans le moindre avertissement dans la sortie ni dans le journal. Si des numéros de référence sont déjà sortis mystérieusement décalés d'une unité, commencez par vérifier l'ordre de ces trois lignes dans le préambule.

\documentclass[11pt,a4paper]{article}

% 1. encoding and fonts
\usepackage[T1]{fontenc}
% 2. language
\usepackage[english]{babel}
% 3. page geometry
\usepackage[margin=25mm]{geometry}
% 4. mathematics
\usepackage{amsmath,amssymb}
% 5. graphics and colour
\usepackage{graphicx}
\usepackage{xcolor}
% 6. hyperref near the end: it redefines many commands
\usepackage{hyperref}
% 7. cleveref is the exception, it must come after hyperref
\usepackage{cleveref}

% document-wide settings and definitions
\newcommand{\R}{\mathbb{R}}
\setlength{\parindent}{0pt}
\title{A Short Note}
\author{Ada Lovelace}
\date{\today}

\begin{document}
\maketitle

\section{Setup}\label{sec:setup}
For all $x \in \R$ we have $x^2 \ge 0$.

\section{Result}
The argument of \cref{sec:setup} applies unchanged.
\end{document}

Garder le préambule plus petit que le document

Dans ce même entretien, on demande à Lamport de citer trois erreurs LaTeX que les gens devraient cesser de commettre. Ses trois réponses n'en font qu'une : trop se soucier de la mise en forme et pas assez du contenu. La répétition était le propos. Le préambule est précisément l'endroit où ce piège est tendu — retouches visuelles ponctuelles, packages essayés une fois et jamais retirés, abréviations employées deux fois, tout cela s'accumule. Le coût n'est pas la laideur : c'est que le jour où une erreur surgit, le coupable se cache quelque part dans ces dizaines de lignes. Ne garder que ce qui vaut pour tout le document : classe, langue et polices, mathématiques, figures et tableaux, liens. Réserver \newcommand aux constructions qui se sont réellement répétées à l'écriture. Et quand un modèle de soumission entre en jeu, respecter d'abord son préambule : remplacer un package que la classe présuppose revient généralement sous forme d'un Option clash, ou sous une forme nettement moins lisible.

• Un nouveau rapport — commencer par article. Retoucher la mise en page peut attendre que le texte soit à peu près écrit.
• Une thèse — utiliser telle quelle la classe distribuée par l'université et garder les réglages de marges ou de titres pour la fin ; ne pas toucher au préambule du modèle est le chemin le plus court.
• Une soumission à une revue — placer d'abord la classe de l'éditeur (elsarticle, IEEEtran, revtex4-2…), puis n'ajouter par-dessus que le strict minimum de préambule personnel.
• Imprimer en A4 — les classes standard supposent letterpaper, il faut donc écrire explicitement \documentclass[a4paper]{...} ; avec geometry chargé, cela se règle aussi de ce côté.
• Quand une erreur survient — soupçonner d'abord le dernier \usepackage ou \newcommand ajouté ; sinon, couper le préambule en deux et dichotomiser.