FAQ

Certains problèmes LaTeX s’annoncent par une ligne commençant par !. Les plus coûteux, non. Une référence qui reste ?? quel que soit le nombre de compilations ; une figure qui atterrit deux pages plus loin ; un PDF en A4 alors que la source indique letterpaper ; un manuscrit qui se compile ici et échoue chez le coauteur. Cette foire aux questions ne rassemble que ces questions transversales — celles qui mettent en jeu plusieurs mécanismes à la fois — et y répond en décrivant ce qui se passe réellement pendant l’exécution. Les problèmes que règle un seul message d’erreur ont leur propre page ; l’index final y conduit.

Pourquoi il faut compiler deux fois

Parce que LaTeX lit la source du début à la fin une seule fois et ne peut pas anticiper. Au moment de composer \ref{sec:first} en page 1, le numéro que portera \label n’est pas encore connu. \label écrit donc ce numéro dans le fichier .aux, et \ref lit la .aux laissée par l’exécution précédente. Mesuré sur TeX Live 2024, le premier passage affiche LaTeX Warning: Reference 'sec:first' on page 1 undefined on input line 4. et LaTeX Warning: There were undefined references., et le PDF porte réellement « See Section ?? on page ??. » La .aux contient alors \newlabel{sec:first}{{1}{1}{}{}{}}, que le deuxième passage relit pour donner « See Section 1 on page 1. » Un ?? n’est donc pas une avarie : il signale qu’on est encore au premier tour.

$ pdflatex ref.tex        # run 1
LaTeX Warning: Reference 'sec:first' on page 1 undefined on input line 4.
LaTeX Warning: There were undefined references.
LaTeX Warning: Label(s) may have changed. Rerun to get cross-references right.

$ pdftotext ref.pdf -
See Section ?? on page ??.

$ pdflatex ref.tex        # run 2 — no warnings
$ pdftotext ref.pdf -
See Section 1 on page 1.

L’avertissement qui clôt l’exécution — LaTeX Warning: Label(s) may have changed. Rerun to get cross-references right. — est la déclaration de LaTeX lui-même : la .aux qu’il vient d’écrire diffère de celle qu’il a lue. L’essentiel est que deux passages constituent un plancher, non une règle. Un chiffre de plus peut faire déborder une ligne, ce qui change un numéro de page, donc de nouveau la .aux ; avec une table des matières, une table des figures ou des signets hyperref, trois ou quatre passages sont tout à fait ordinaires. latexmk n’existe que pour cela : il répète jusqu’à ce que la .aux cesse de bouger. Mieux vaut donc lui confier l’itération. À l’inverse, ne jamais poursuivre un ?? avant d’avoir compilé deux fois. S’il survit à deux passages, le \label est mal orthographié, absent, ou une .aux périmée fait obstacle — la supprimer ramène au premier passage.

Pourquoi la bibliographie n’apparaît pas

Parce que la bibliographie est produite par un programme distinct, extérieur à LaTeX, et qu’un cycle complet demande quatre commandes. bibtex ne lit jamais le .tex. Il lit les lignes \citation et \bibdata que LaTeX a écrites dans la .aux, extrait les entrées correspondantes du .bib et produit un .bbl. Mesurées sur TeX Live 2024, les étapes sont sans ambiguïté. Le premier pdflatex affiche LaTeX Warning: Citation 'knuth1984' on page 1 undefined, et le PDF porte « As shown by [?]. » sans la moindre liste. bibtex annonce ensuite ses entrées : The top-level auxiliary file: doc.aux, The style file: plain.bst, Database file #1: refs.bib. Le deuxième pdflatex compose bien la liste References, mais l’appel de citation reste [?]. Il faut le troisième passage pour obtenir [1].

pdflatex doc     # writes \citation and \bibdata into doc.aux; text shows [?]
bibtex   doc     # reads doc.aux + refs.bib, writes doc.bbl
pdflatex doc     # pulls in doc.bbl: the list appears, the mark is still [?]
pdflatex doc     # now the \bibitem labels are in doc.aux: the mark becomes [1]

latexmk -pdf doc # does all four, and repeats until nothing changes

Le troisième passage s’explique par le même aller-retour via la .aux. Les \bibitem du .bbl que lit le deuxième passage inscrivent dans la .aux la correspondance « cette clé vaut [1] » — mais en cours de ce même passage, alors que le \cite du corps a déjà été composé. La correspondance n’est donc exploitable qu’au passage suivant, d’où la nécessité d’un troisième pdflatex, quatrième commande au total. biblatex avec biber suit la même forme ; biber remplace bibtex et lit un .bcf. En pratique, on confie l’ensemble à latexmk et on cesse de compter. Si la liste reste vide, la cause est presque toujours l’une des trois : \bibliography{refs} écrit avec l’extension .bib, aucun \cite dans le corps (ajouter \nocite{*} fait tout apparaître), ou une clé mal tapée. Le dernier cas se lit dans le journal .blg : Warning--I didn't find a database entry for "...".

Pourquoi la figure atterrit sur la mauvaise page

Parce qu’un figure est un flottant : LaTeX le retient jusqu’à ce qu’une page lui fasse de la place. Le point où l’on trébuche le plus souvent est la différence entre \newpage et \clearpage. \newpage se contente de terminer la page courante — il ne vide pas la file des flottants en attente. \clearpage compose d’abord tous les flottants en souffrance, puis termine la page. En compilant sur TeX Live 2024 deux versions d’une même source qui ne diffèrent que par cette commande, et en lisant le résultat page par page avec pdftotext, la conséquence saute aux yeux.

\section{Alpha}
... a page of text ...
\begin{figure}[t]
  \centering \rule{10cm}{16cm}
  \caption{First figure}
\end{figure}

\newpage      % <- only this line differs between the two builds
%\clearpage

\section{Beta}
\begin{figure}[t]
  \centering \rule{6cm}{5cm}
  \caption{Second figure}
\end{figure}
Text of Beta.

La version \newpage fait quatre pages : p. 1 le corps d’Alpha, p. 2 le titre « Beta » et son texte, p. 3 la figure 1, p. 4 la figure 2. La figure 1, qui appartient à Alpha, a enjambé le titre de la section suivante pour ressortir derrière lui. La version \clearpage fait trois pages : p. 1 le corps d’Alpha, p. 2 la seule figure 1, p. 3 la figure 2 avec le titre « Beta » et son texte. La figure ne franchit plus la frontière de section, et le document perd une page au passage. La plupart des cas de « ma figure s’est retrouvée dans le mauvais chapitre » remontent donc à un \newpage placé à une rupture structurelle. Aux ruptures de chapitre et de section, employer \clearpage (\cleardoublepage en impression recto verso). Par ailleurs, écrire [htbp] plutôt qu’un [h] isolé : [h] signifie « ici si cela tient, sinon plus tard », et un flottant plus haut que \textheight ne partagera jamais une page avec du texte. Le réglage fin des flottants relève de la page consacrée aux flottants et au placement.

Pourquoi l’image ne s’affiche pas, ou sort en cadre vide

Si rien n’apparaît, soupçonner un désaccord entre le format de l’image et la chaîne de sortie ; si un cadre vide apparaît, soupçonner draft. pdflatex lit directement PDF, PNG et JPEG et ne lit pas l’EPS — il faut le convertir avec epstopdf ou laisser faire le package epstopdf. La chaîne DVI, platex puis dvipdfmx, accepte en revanche l’EPS. Quand le fichier est introuvable, le message est ! LaTeX Error: File 'fig.eps' not found., et la cause est presque toujours une extension oubliée, un chemin erroné, ou un \graphicspath{{figures/}} privé de sa barre oblique finale. L’autre classique, ! LaTeX Error: Cannot determine size of graphic in xxx.png (no BoundingBox)., survient lorsque graphicx ignore sous quel pilote il tourne — la FAQ de Cloud LaTeX consacre à ce seul message une entrée distincte.

Le cas du cadre vide est presque décevant de simplicité une fois compris. Un document compilé sur TeX Live 2024 avec \documentclass[draft]{article}, puis relu par pdftotext, restitue le nom du fichier sous forme de texte là où l’image devrait se trouver. C’est précisément ce que fait draft : il saute le rendu de l’image et laisse un cadre de mêmes dimensions portant le nom. Oublier un draft dans les options de classe puis en conclure que les images sont corrompues compte parmi les accidents les plus fréquents. Pour la version soumise, retirer impérativement draft ; si seule la vitesse importe, \usepackage[draft]{graphicx} limite l’effet aux illustrations. Et si la figure manque encore après avoir écarté toutes les causes de cette section, elle n’est peut-être pas absente : elle a flotté vers une autre page. Revenir à la section précédente.

Pourquoi cela compile chez moi et pas chez le coauteur

Les écarts entre deux machines se ramènent en pratique à trois choses : le millésime de TeX Live, les versions des paquets installés et les fichiers personnels rangés dans l’arborescence privée. Les deux premiers se révèlent avec une seule ligne. Placer \listfiles avant \documentclass et la .log se termine par un bloc *File List* donnant une ligne par fichier, avec date et version — sur TeX Live 2024, des entrées comme amsmath.sty 2023/05/13 v2.17o AMS math features ou graphicx.sty 2021/09/16 v1.2d Enhanced LaTeX Graphics. Demander le même bloc au coauteur, comparer les deux, et le coupable tient d’ordinaire en une ligne. Le millésime du moteur, lui, vient de pdflatex --version, qui répond pdfTeX 3.141592653-2.6-1.40.26 (TeX Live 2024).

% put this on the very first line of the source
\listfiles

$ pdflatex doc.tex && sed -n '/File List/,/^ \*\*\*/p' doc.log
 *File List*
 article.cls    2023/05/17 v1.4n Standard LaTeX document class
 amsmath.sty    2023/05/13 v2.17o AMS math features
graphicx.sty    2021/09/16 v1.2d Enhanced LaTeX Graphics (DPC,SPQR)

$ kpsewhich -var-value=TEXMFHOME   # macOS, TeX Live 2024
/Users/you/Library/texmf

$ pdflatex --version | head -1
pdfTeX 3.141592653-2.6-1.40.26 (TeX Live 2024)

La troisième cause, l’arborescence personnelle, est la plus difficile à repérer. kpsewhich -var-value=TEXMFHOME renvoie, sous TeX Live 2024 sur macOS, /Users/you/Library/texmf — le texmf.cnf livré avec TeX Live 2024 fixe TEXMFHOME = ~/Library/texmf, alors que la valeur par défaut sous Windows et Linux est ~/texmf. Tout .sty, .bst ou fonte privée qui y réside n’est visible que sur votre machine ; le destinataire du manuscrit obtient ! LaTeX Error: File 'mystyle.sty' not found. Le remède est brutal : garder les fichiers maison dans le dossier du manuscrit et les livrer avec lui. Pour effacer aussi l’écart de millésime de TeX Live, il faut figer l’environnement lui-même, par exemple avec une image Docker. Les usages de la coécriture relèvent de la page sur la collaboration, le figeage de l’environnement de la page Docker et CI.

Pourquoi le PDF sort en A4 alors que la source demande letterpaper

Parce qu’une option de classe modifie l’empagement — le bloc de texte et ses marges — et non le papier du PDF. En compilant tel quel \documentclass[letterpaper]{article} sur TeX Live 2024 puis en interrogeant pdfinfo, la réponse est Page size: 595.276 x 841.89 pts (A4). La raison tient à la configuration de démarrage de pdfTeX. Le pdftexconfig.tex gravé dans le format fixe \pdfpageheight = 297 true mm et \pdfpagewidth = 210 true mm, deux primitives qui déterminent la boîte média du PDF. Une option de classe n’atteint pas cette couche. Ajoutez \usepackage[letterpaper]{geometry} au même document et la réponse devient 612 x 792 pts (letter), car geometry s’occupe à la fois de l’empagement et du format de la feuille.

$ pdflatex letter.tex && pdfinfo letter.pdf | grep "Page size"
Page size:       595.276 x 841.89 pts (A4)      # \documentclass[letterpaper]{article}

# fix 1 — geometry sets the type area AND the sheet
%   \usepackage[letterpaper]{geometry}
Page size:       612 x 792 pts (letter)

# fix 2 — set the pdfTeX primitives before \documentclass
%   \pdfpagewidth=8.5truein \pdfpageheight=11truein
Page size:       612 x 792 pts (letter)

Il existe trois remèdes, et la situation en désigne un. Le plus direct est geometry, qui permet en outre de fixer les marges au même endroit. Pour ne pas alourdir le préambule, écrire avant \documentclass la ligne \pdfpagewidth=8.5truein \pdfpageheight=11truein donne également 612 x 792 pts (letter) — mesuré. Sur la chaîne DVI, c’est dvipdfmx qui fabrique le PDF : la taille se donne donc à la conversion, par exemple avec dvipdfmx -p letter. Il est utile de savoir pourquoi ces longueurs portent true : lorsque le document entier est mis à l’échelle par \mag, seules les dimensions marquées true échappent à cette mise à l’échelle. Les détails du format papier relèvent de la page sur la production du PDF.

Pourquoi le japonais ne s’affiche pas ou sort illisible

C’est presque toujours le mauvais moteur ou le mauvais encodage de fichier. pdflatex ne compose pas du tout le japonais. Deux chaînes fonctionnent : uplatex (avec une classe jsarticle ou jlreq) passant la main à dvipdfmx, ou lualatex avec luatexja. La source se conserve en UTF-8. Ce que l’on néglige, c’est que « prend en charge le japonais » n’est pas univoque : platex et uplatex couvrent des plages de caractères différentes. Sur TeX Live 2024, une ligne contenant 髙 (U+9AD9) arrête platex sur ! LaTeX Error: Unicode character ^^e9^^ab^^99 (U+9AD9) not set up for use with LaTeX., tandis que uplatex compile la même ligne sans le moindre avertissement. Si un document échoue uniquement sur des noms propres ou des variantes de caractères, c’est le moteur qu’il faut soupçonner, pas la fonte.

Si les caractères apparaissent mais sous forme de carrés de substitution ou dans une autre fonte, le problème vient de la configuration des fontes japonaises. Sur la chaîne dvipdfmx, kanji-config-updmap choisit la fonte japonaise incorporée ; sous LuaTeX-ja, on la nomme avec \setmainjfont et ses analogues. Et si le texte n’est illisible que chez le destinataire, soupçonner l’encodage et les fins de ligne : dès qu’un fichier a été enregistré autrement qu’en UTF-8 — Shift_JIS ou EUC-JP —, platex l’interprète différemment selon le réglage -kanji=. Les méthodes de composition elles-mêmes relèvent de la page sur la composition japonaise, l’encodage et les fins de ligne de la page correspondante.

Pourquoi la revue signale des polices non incorporées

On vérifie avec pdffonts, on ne devine pas. Appliqué à une sortie pdfLaTeX ordinaire produite sur TeX Live 2024, il affiche les colonnes emb, sub, uni et une ligne telle que KJJYRX+CMR10 Type 1 Builtin yes yes yes — yes sous emb et un préfixe de sous-ensemble de six lettres devant le nom de la fonte. Ces deux signes réunis signifient : incorporée. Une ligne portant no sous emb, au contraire, bloquera à coup sûr le système de soumission d’une revue ou un contrôle PDF/A. Trois causes couvrent presque tous les cas : des fontes bitmap Type 3 (faute de Type1 installée, ce sont des bitmaps METAFONT), les quatorze fontes de base du PDF (Helvetica et consorts, référencées sans être fournies) et une table dvipdfmx pointant vers une fonte non incorporable.

$ pdffonts document.pdf
name                       type       encoding  emb sub uni object ID
-------------------------- ---------- --------- --- --- --- ---------
KJJYRX+CMR10               Type 1     Builtin   yes yes yes      4  0

# "yes" under emb, plus the six-letter subset prefix, means embedded.
# Any line with "no" under emb will fail a PDF/A or journal check.

Quelle page répond à quel message d’erreur

Aucune des questions précédentes ne tient à un message d’erreur unique. Dès qu’une ligne commence par !, en revanche, le message lui-même indique où chercher. La section des erreurs de ce site consacre une page à chaque message, et ! Missing $ inserted., ! Undefined control sequence., ! LaTeX Error: Missing \begin{document}., Runaway argument?, ! LaTeX Error: Option clash for package ... et Overfull \hbox ont chacun la leur. Le tableau ci-dessous donne le libellé tel qu’il a été reproduit sur TeX Live 2024, et ce que cette seule ligne signifie réellement. Il n’y a qu’une astuce de lecture : corriger d’abord l’erreur la plus haute. Les erreurs de TeX se propagent, et les suivantes ne sont le plus souvent que les répliques de la première.