Votre premier document

Votre premier document LaTeX peut tenir sur une seule ligne, et il compilera : \documentclass{article}\begin{document}Hi\end{document}. Passez-la dans pdflatex et vous obtenez bel et bien un PDF d'une page de 11 529 octets. La plupart de ceux qui calent sur leur premier document ont sauté ce que fait cette ligne pour recopier un long modèle. Cette page part de ce minimum et l'élargit : où finit le préambule et où commence le corps, comment lancer le compilateur, ce que sont vraiment les fichiers .aux et .log apparus de nulle part, pourquoi deux passes sont parfois nécessaires, et les pièges de % et de $ que tout débutant rencontre le premier jour — avec la sortie réelle du terminal à chaque étape.

Le plus petit document LaTeX qui compile (hello world)

Trois commandes, pas une de plus. \documentclass{article} déclare de quel type de document il s'agit, \begin{document} ouvre le corps, \end{document} le referme. Qu'il en manque une et vous n'obtenez pas de PDF ; avec les trois, cela fonctionne même si rien ne les sépare. Enregistrez la version lisible ci-dessous sous le nom hello.tex. Le fichier doit être en UTF-8 et porter l'extension .tex.

\documentclass{article}
\begin{document}
This is my first document.
\end{document}

Le article de \documentclass{article} est la classe. Une classe est le plan de l'ensemble du document : largeur des marges, taille des titres et espace autour, existence ou non de chapitres. Sont fournies en standard article (articles, rapports courts, notes techniques — sans \chapter), report (rapports plus longs, avec chapitres), book (livres, pensés pour l'impression recto verso) et letter (lettres). Pour le japonais, on prend jlreq ou jsarticle. Si une revue ou un éditeur fournit son propre fichier de classe, utilisez-le sans hésiter : toute la discussion sur les normes de présentation disparaît.

Préambule et corps : les deux mondes que sépare \begin{document}

Tout ce qui précède \begin{document} est le préambule ; tout ce qui suit est le corps. Le préambule est l'endroit où l'on décide comment le document sera composé, et rien de ce qui y est écrit n'atteint la page. Dans le corps, à l'inverse, ce qu'on écrit est en gros ce qu'on obtient. Cette frontière n'est pas une lubie de LaTeX mais une nécessité : avant de composer le moindre caractère, LaTeX doit avoir arrêté le format du papier, la justification, les fontes et tous les packages à charger. Voilà pourquoi \usepackage ne peut figurer que dans le préambule. Placé dans le corps, il arrête la compilation avec ! LaTeX Error: Can be used only in preamble.

L'erreur inverse est tout aussi fréquente : mettez de la prose ordinaire dans le préambule et vous obtenez ! LaTeX Error: Missing \begin{document}. C'est déroutant la première fois — vous avez bien écrit \begin{document} — mais LaTeX veut dire « du texte est arrivé avant le début du corps », c'est-à-dire qu'il y a du texte en amont du début du corps. Commentez avec % les notes laissées dans le préambule.

Compiler en PDF avec pdflatex et latexmk

Tapez pdflatex hello.tex dans un terminal. Dans un éditeur ou sur Overleaf, le bouton « compiler » fait exactement cela. Le signe de réussite, ce sont les deux dernières lignes : Output written on hello.pdf et Transcript written on hello.log. Si vous les voyez, le PDF existe. Le mur de chemins qui défile avant est la liste des fichiers de classe et des fontes chargés ; c'est une sortie normale, inutile de la lire.

$ pdflatex hello.tex
This is pdfTeX, Version 3.141592653-2.6-1.40.26 (TeX Live 2024)
(./hello.tex
LaTeX2e <2023-11-01> patch level 1
(/usr/local/texlive/2024/texmf-dist/tex/latex/base/article.cls
Document Class: article 2023/05/17 v1.4n Standard LaTeX document class
...
Output written on hello.pdf (1 page, 31014 bytes).
Transcript written on hello.log.

En cas de problème, pdflatex peut afficher ? et attendre une saisie. N'écrasez pas la touche Entrée : tapez x puis Entrée pour interrompre. Si vous préférez n'avoir jamais cette conversation, pdflatex -interaction=nonstopmode hello.tex va jusqu'au bout malgré les erreurs et consigne tout dans le journal. Et il vaut la peine d'apprendre tôt latexmk -pdf hello.tex : il relance le compilateur autant de fois que le document l'exige, si bien que le problème des « deux passes » de la section suivante cesse d'en être un.

Ces nouveaux fichiers, c'est quoi ? .aux, .log, .toc, .out

Une seule compilation et le dossier compte quatre fichiers de plus. Rien n'a échoué : LaTeX se laisse des notes à lui-même. Passez dans pdflatex un document avec table des matières et une section, et vous obtenez, outre hello.tex, les fichiers hello.aux (132 octets), hello.log (3 250 octets), hello.pdf (31 014 octets) et hello.toc (59 octets). Le cœur du mécanisme, c'est .aux. Ouvert, il contient exactement trois lignes.

% hello.aux, written by the first run
\relax
\@writefile{toc}{\contentsline {section}{\numberline {1}Introduction}{1}{}\protected@file@percent }
\gdef \@abspage@last{1}

À voix haute : « la section numéro 1, Introduction, est en page 1 » et « la dernière page est la page 1 ». Autrement dit, .aux est un carnet de numéros et de positions de page, relu au passage suivant. .toc est la table des matières provisoire qui en découle, .log l'enregistrement complet de la compilation, et .out n'apparaît qu'avec hyperref : il contient les signets du PDF.

La règle pratique est courte. Ne versionnez que le .tex et vos images, et mettez les fichiers auxiliaires dans la liste d'exclusion. latexmk -c fait le ménage en une commande. Mais ne les supprimez pas par habitude : ils existent pour épargner du travail, et les effacer chaque fois revient à choisir sciemment le chemin le plus long. On sort le balai seulement quand un problème persiste sans explication.

Pourquoi il faut compiler deux fois : ?? et l'avertissement de relance

Parce qu'au premier passage LaTeX ne connaît pas encore la réponse. Quand vous écrivez « voir la section 1 », LaTeX n'apprend le numéro et la page de cette section qu'après l'avoir effectivement composée — et les renvois précèdent presque toujours ce qu'ils désignent. Le premier passage compose donc ce qu'il peut tout en écrivant les réponses dans .aux ; le second les relit et comble les trous. Même histoire pour la table des matières : \tableofcontents figure en tête du document, mais son contenu n'est connu qu'à la fin. Voici l'enregistrement réel des deux passages.

$ pdflatex ref.tex          # first run, from a clean directory
No file ref.aux.
No file ref.toc.
LaTeX Warning: Reference `sec:intro' on page 1 undefined on input line 5.
LaTeX Warning: There were undefined references.
LaTeX Warning: Label(s) may have changed. Rerun to get cross-references right.
Output written on ref.pdf (1 page, 33009 bytes).

# the PDF now reads:  "See Section ?? on page ??."

$ pdflatex ref.tex          # second run
Output written on ref.pdf (1 page, 34613 bytes).

# the PDF now reads:  "See Section 1 on page 1."

Trois choses à repérer. Le premier passage annonce No file ref.aux. : le carnet n'existe pas encore. Les renvois s'impriment en ??, et l'on obtient LaTeX Warning: Label(s) may have changed. Rerun to get cross-references right. Le mot « Rerun » est l'instruction : relancez. Au second passage l'avertissement a disparu et ?? est devenu 1. La table des matières se comporte pareil : au premier passage seul son titre s'imprime, et ce n'est qu'au second que la liste apparaît. Un ?? dans le PDF ne signale pas une casse : c'est une demande de passage supplémentaire.

Si compter les passages vous ennuie, confiez-le à latexmk. Dans un répertoire vierge, latexmk -pdf ref.tex affiche Run number 1 of rule 'pdflatex', Run number 2 of rule 'pdflatex', puis Latexmk: All targets (ref.pdf) are up-to-date : il effectue exactement les deux passages nécessaires et s'arrête. Bibliographies (BibTeX/biber) et index (makeindex) font monter le compte, et latexmk s'en occupe aussi. LaTeX Workshop dans VS Code, TeXShop et Overleaf appellent de toute façon latexmk en coulisses.

Les caractères qui ne s'impriment pas comme on les tape : %, &, _, #, $

LaTeX compte dix caractères qui signifient autre chose lorsqu'on les tape tels quels : # $ % & ~ _ ^ \ { }. Celui qui piège le plus de monde le premier jour est %, et s'il piège, c'est parce qu'il ne déclenche aucune erreur. Écrivez Only 50% of the sample survived. avec The rest did not. à la ligne suivante, et le PDF imprime « Only 50The rest did not. » Tout ce qui va de % à la fin de la ligne est jeté comme un commentaire, et la fin de ligne disparue raccroche simplement la ligne suivante au même paragraphe. Aucune erreur n'est signalée, donc rien ne prévient — et les pourcentages foisonnent dans les textes scientifiques. La forme correcte est 50\%.

Deux autres habitudes sont pénibles justement parce qu'elles ne provoquent aucune erreur. La première : une commande avale l'espace qui la suit. \LaTeX is a macro package. donne « LATEXis a macro package. », car LaTeX consomme l'espace suivant pour déterminer où finit le nom de la commande. On corrige avec des accolades vides, \LaTeX{} is, ou avec \LaTeX\ is. La seconde : les guillemets. Taper "hello" produit un guillemet fermant aux deux extrémités (”hello”). L'ouvrant s'écrit avec deux accents graves et le fermant avec deux apostrophes : la forme correcte est ``hello''.

Lire ses premières erreurs : ! Missing $ inserted. et compagnie

Ne lisez que la première ligne commençant par ! et la ligne l. qui la suit. l. abrège « line » ; le nombre qui suit est le numéro de ligne, le contenu de cette ligne est imprimé avec lui, et il est coupé en deux exactement là où TeX a trébuché. Le point de coupure est la scène du crime. Voici ce que donne un x_1 écrit dans du texte ordinaire. Comme TeX s'obstine après la première erreur, celles qui suivent relèvent le plus souvent d'une réaction en chaîne. Corrigez seulement la première et relancez.

$ pdflatex e2.tex      # line 3 of the source reads: The value of x_1 is small.
! Missing $ inserted.
<inserted text>
                $
l.3 The value of x_
                   1 is small.

$ pdflatex e3.tex      # line 3 reads: Smith & Jones wrote it.
! Misplaced alignment tab character &.
l.3 Smith &
            Jones wrote it.

$ pdflatex sc.tex      # line 3 reads: Issue #42 and more.
! You can't use `macro parameter character #' in horizontal mode.
l.3 Issue #
           42 and more.

$ pdflatex e5.tex      # \begin{itemize} was never closed
! LaTeX Error: \begin{itemize} on input line 3 ended by \end{document}.

$ pdflatex e4.tex      # \end{document} is missing entirely
*** (job aborted, no legal \end found)
!  ==> Fatal error occurred, no output PDF file produced!

! Missing $ inserted. signifie : « quelque chose qui ne fonctionne qu'en mode mathématique est apparu dans le texte, donc TeX a inséré un $ ». La cause est presque toujours _ ou ^ : soit on en fait une vraie formule, $x_1$, soit on l'échappe, x\_1. ! LaTeX Error: \begin{itemize} on input line 3 ended by \end{document}. signale un environnement non refermé, et c'est l'une des erreurs les plus aimables car elle indique la ligne où l'environnement s'est ouvert. La plus effrayante en apparence, ! ==> Fatal error occurred, no output PDF file produced!, veut souvent simplement dire qu'il manque \end{document}. Enfin ! Undefined control sequence. est une faute de frappe (\sectoin) ou un package oublié.

Ajouter un titre et des sections pour en faire un rapport

À partir d'ici, il ne reste qu'à ajouter. Mettez \title, \author et \date dans le préambule et appelez \maketitle en tête du corps : le titre est composé. Les titres créés avec \section et \subsection sont numérotés automatiquement, et \tableofcontents construit la table des matières (qui, on l'a vu, n'apparaît qu'au second passage). \date{\today} devient la date de compilation, et un titre qu'on ne veut pas numéroter prend un astérisque : \section*{...}.

\documentclass{article}
\title{My First Report}
\author{Taro Yamada}
\date{\today}
\begin{document}
\maketitle
\tableofcontents

\section{Introduction}
Blank lines start new paragraphs. Line breaks in the source do not.

\section{Method}
\subsection{Setup}\label{sec:setup}
Only 50\% of the sample survived. See Section~\ref{sec:setup}.
\end{document}

Cet exemple contient aussi la règle la plus importante pour écrire le corps : les sauts de ligne de la source sont ignorés, et une ligne vide commence un nouveau paragraphe. Coupez après chaque phrase ou laissez trois lignes vides : la sortie est identique. LaTeX fixe les coupures définitives en considérant le paragraphe entier. N'insérez une ligne vide que là où vous voulez réellement un nouveau paragraphe.

Ajouter des fonctions avec les packages : \usepackage

Les fonctions manquantes viennent des packages, et en ajouter un tient en une ligne \usepackage{...} dans le préambule. Les images demandent graphicx, les mathématiques sérieuses amsmath, d'autres marges geometry, les liens et signets PDF hyperref. Des milliers de packages accompagnent une distribution comme TeX Live, et l'archive dont ils proviennent tous s'appelle CTAN, le Comprehensive TeX Archive Network. Mais n'en empilez pas d'emblée. Ne gardez que ceux dont vous pouvez justifier la présence : quand deux packages entrent en conflit et produisent un Option clash for package ..., le travail d'identification croît avec le nombre chargé.

\documentclass[a4paper,11pt]{article}
\usepackage{graphicx}                  % include images
\usepackage{amsmath}                   % proper math environments
\usepackage[margin=25mm]{geometry}     % page margins
\usepackage{hyperref}                  % links and PDF bookmarks; load it last
\begin{document}
\section{Results}
Text, images and equations go here.
\end{document}

Par convention, hyperref se charge en dernier. Il fonctionne en réécrivant les commandes d'autres packages ; chargé trop tôt, un package suivant écrase ses modifications. Et voilà tout le premier jour : le document minimal, la séparation préambule/corps, la compilation, les fichiers auxiliaires, le second passage, les caractères spéciaux et vos premières erreurs. À partir de là, écrivez ce que vous voulez vraiment écrire et ajoutez les fonctions une à une, au fur et à mesure des besoins.