Relecture (proofread)

Si un relecteur vous a déjà renvoyé une remarque du type « page 12, troisième paragraphe, quatrième ligne », vous savez déjà ce dont la relecture en LaTeX a d'abord besoin : des numéros de ligne, fournis par le package lineno. Beaucoup de revues exigent un manuscrit numéroté dès la soumission, et avec des numéros en marge une remarque tient en un mot — « L412 ». Cette page suit un cycle de relecture complet : numéroter les lignes, épingler des tâches en marge, colorer les interventions de chaque co-auteur, utiliser latexdiff pour montrer ce qui a changé depuis la version précédente, et lâcher trois analyseurs — chktex, lacheck et nag — sur la source. Chaque étape est accompagnée de la sortie d'une exécution réelle.

Numéroter les lignes d'une version de relecture : le package lineno

Chargez \usepackage{lineno}, écrivez \linenumbers, et chaque ligne de texte courant reçoit dès lors un numéro dans la marge de gauche. Des options changent la présentation : modulo ne numérote qu'une ligne sur cinq, ce qui apaise la marge ; pagewise recommence le compte à 1 sur chaque page ; switch place les numéros dans la marge extérieure en recto-verso. \nolinenumbers les désactive et l'environnement linenumbers en numérote une portion. Ne numéroter qu'une partie d'un document — le corps sans l'annexe, par exemple — est une demande quotidienne.

\usepackage[modulo]{lineno}   % number every 5th line only
% \usepackage[pagewise]{lineno} % restart the count on each page
% \usepackage[switch]{lineno}   % outer margin, for twoside
\linenumbers
...
\nolinenumbers                % stop numbering (e.g. before the appendix)

Voici le piège qui fait dérailler une discussion de relecture. Par défaut, les formules hors-texte ne sont pas numérotées. Mesuré sur un document contenant une equation et un align d'amsmath, le texte courant a défilé 1, 2, 3 — en enjambant purement et simplement les mathématiques. Ajoutez \usepackage[mathlines]{lineno} au même document et la numérotation va de 1 à 6, chaque ligne de chaque formule recevant elle aussi un numéro. Autrement dit, la présence de mathlines change ce que désigne « L4 » ; si relecteur et auteur regardent des PDF compilés avec des réglages différents, la discussion ne se recoupera pas. Pour un manuscrit riche en formules, activer mathlines est plus sûr.

lineno est un outil ancien, qui remonte à 1995 ; la version de TeX Live 2024 est la v5.3, datée du 20 mai 2023. La mention de copyright en tête du package aligne trois générations de mainteneurs : Stephan I. Böttcher pour 1995–2003, Uwe Lück pour la série 4.x, et Karl Wette, qui a repris la série 5.x en 2021. Trente ans de travail de compatibilité laissent des traces, et le package ne s'accorde pas toujours sans heurt avec les autres. L'ordre de chargement peut compter : si les numéros refusent d'apparaître, essayez de charger lineno en dernier.

Utiliser latexdiff : montrer à un co-auteur ce qui a changé

Lancez latexdiff old.tex new.tex > diff.tex puis compilez le diff.tex obtenu avec pdflatex comme d'habitude. C'est toute la procédure, et elle produit un PDF où les ajouts et les suppressions se distinguent visuellement. Lors d'une exécution réelle, latexdiff enfile dans le texte des marqueurs — \DIFaddbegin, \DIFadd{...}, \DIFdelbegin, \DIFdel{...} — et complète le préambule par \RequirePackage[normalem]{ulem} et des définitions de couleurs. Ce qui en fait l'outil le plus précieux de tout l'attirail de relecture, c'est qu'il épargne à votre interlocuteur la lecture du LaTeX : la différence apparaît sur une page composée, non dans un diff git.

# the whole workflow
latexdiff old.tex new.tex > diff.tex
pdflatex diff.tex

# one file made of many \input files: flatten first
latexdiff --flatten old/main.tex new/main.tex > diff.tex

# diff straight against a git revision (produces main-diffHEAD~1.tex)
latexdiff-vc --git --flatten -r HEAD~1 main.tex

# a different visual style, e.g. bold instead of underline
latexdiff --type=CFONT old.tex new.tex > diff.tex

L'apparence par défaut est un peu plus précise que la description courante « ajouts soulignés, suppressions barrées ». La version de TeX Live 2024 est la v1.3.3 — latexdiff --version se présente comme « (c) 2004-2022 F J Tilmann » — et le préambule qu'elle injecte définit \DIFadd par {\protect\color{blue}\uwave{#1}} et \DIFdel par {\protect\color{red}\sout{#1}}. Donc : les ajouts sont un soulignement ondulé bleu, les suppressions un barré rouge. Ce réglage porte un nom, --type=UNDERLINE, et les variantes sont CTRADITIONAL, TRADITIONAL, CFONT, FONTSTRIKE, INVISIBLE, CHANGEBAR, CCHANGEBAR, CULINECHBAR, CFONTCHBAR, BOLD et PDFCOMMENT. Pour un relecteur qui imprimera en noir et blanc, FONTSTRIKE ou BOLD se lit bien mieux.

% What latexdiff actually writes into diff.tex (excerpt of a real run):
\RequirePackage[normalem]{ulem}
\providecommand{\DIFadd}[1]{{\protect\color{blue}\uwave{#1}}}
\providecommand{\DIFdel}[1]{{\protect\color{red}\sout{#1}}}
...
The measured value was \DIFdelbegin \DIFdel{3.2}\DIFdelend
  \DIFaddbegin \DIFadd{3.4}\DIFaddend \,mm.

Deux situations lui font gagner sa place. La première est la version révisée d'un article : beaucoup de revues réclament, à côté de la version propre, une version annotée — et la sortie de latexdiff est ce livrable. La seconde est l'envoi aux co-auteurs. Pour un document réparti en plusieurs fichiers, --flatten développe les \input avant la comparaison, et latexdiff-vc --git --flatten -r HEAD~1 main.tex compare directement l'arbre de travail à un commit antérieur en écrivant main-diffHEAD~1.tex. Une réserve : latexdiff traite le LaTeX comme du texte, non comme une syntaxe, si bien que des modifications à l'intérieur des tableaux et des figures peuvent casser le balisage. Le cas échéant, ajoutez la commande fautive à la liste sûre avec --append-safecmd, ou excluez l'environnement avec --exclude-textcmd.

Une couleur par co-auteur : le package changes

Là où latexdiff compare deux versions de l'extérieur, changes consigne les modifications à l'intérieur de la source. On déclare les auteurs — \definechangesauthor[name={Ada Lovelace}, color=blue]{AL} — puis on annote avec \added[id=AL]{...}, \deleted[id=AL]{...}, \replaced[id=AT]{nouveau}{ancien} et \comment[id=AT]{...}. Ajoutez \listofchanges et vous obtenez une « List of changes » ; lors d'une exécution réelle, on y lisait Added (AL): ..., Replaced (AT): ..., Deleted (AL): ... et Commented (AT): ..., chacun attribué à son auteur. La version de TeX Live 2024 est la v4.2.1 (2021/07/15).

\usepackage[markup=underlined]{changes}   % draft look; the default
\definechangesauthor[name={Ada Lovelace}, color=blue]{AL}
\definechangesauthor[name={Alan Turing},  color=orange]{AT}
\begin{document}
\listofchanges
The engine \added[id=AL]{weaves algebraical patterns} and
\replaced[id=AT]{computes}{calculates} the numbers.
\deleted[id=AL]{This sentence is redundant.}
\comment[id=AT]{Check the citation here.}

Le geste final compte. Passez à \usepackage[final]{changes} et le package ne se contente pas de masquer le balisage : il applique les modifications. Lors d'une exécution réelle, le texte de \added est resté, \replaced n'a conservé que la version nouvelle, et la phrase \deleted comme le \comment ont disparu, laissant la phrase nette « The engine weaves algebraical patterns and computes the numbers. Ordinary text. » Il n'est donc jamais nécessaire de retirer les commandes à la main pour produire une version finale. Corollaire : le PDF avant et après la bascule ne dit pas la même chose ; recompilez toujours en mode final et relisez avant de soumettre.

Épingler des tâches en marge : todonotes et \todo

Un commentaire écrit avec % disparaît à la compilation : votre co-auteur ne le verra donc jamais. todonotes sert à garder les tâches dans la sortie. \todo{check this number} dessine un pense-bête en marge, \todo[inline]{...} insère un bandeau dans le fil du texte, et \missingfigure{plot of the residuals} trace un cadre indiquant qu'une figure manque ici. \listoftodos produit une « Todo list » en tête ; lors d'une exécution réelle, chaque élément y figurait avec son numéro de page — on voit d'un coup d'œil ce qui reste à faire.

\usepackage[textwidth=3cm]{todonotes}
% \usepackage[disable]{todonotes}   % final version: hides notes AND the list
\begin{document}
\listoftodos
Some text.\todo{check this number}
More text.\todo[inline,color=green!30]{rewrite this paragraph}
\missingfigure{plot of the residuals}

Pour la version finale, remplacez par \usepackage[disable]{todonotes}. À la mesure, cela supprime les notes en marge, les cadres \missingfigure et aussi la « Todo list » en tête — tandis que les commandes restent dans la source, si bien qu'ôter disable à la révision suivante ramène toutes les tâches. C'est la différence décisive avec un commentaire % : la note est masquée, pas détruite. Le risque est de soumettre avec disable encore actif sans que personne ne remarque les points en suspens. Faites de « désactiver disable une fois et lire \listoftodos » une étape fixe juste avant la soumission.

chktex et lacheck : attraper ce dont pdflatex ne dit rien

Ces deux-là attrapent des fautes typographiquement mauvaises mais parfaitement compilables — car pdflatex ne s'intéresse qu'à la réussite du passage. Cas concret : passez la ligne As shown in Fig. 1 and in Table \ref{tab:one}, see also \cite{knuth1984}. dans pdflatex et vous n'obtenez que LaTeX Warning: Reference 'tab:one' on page 1 undefined, une remarque sur les renvois. Passez la même ligne dans chktex et cet avertissement se déclenche deux fois :

$ chktex -q ref.tex
Warning 2 in ref.tex line 3: Non-breaking space (`~') should have been used.
As shown in Fig. 1 and in Table \ref{tab:one}, see also \cite{knuth1984}.
                               ^
Warning 2 in ref.tex line 3: Non-breaking space (`~') should have been used.
As shown in Fig. 1 and in Table \ref{tab:one}, see also \cite{knuth1984}.
                                                       ^

Une rectification s'impose ici. On dit souvent que chktex réprimande le ~ manquant dans Fig. 1. Avec la configuration d'origine, il n'en fait rien. Le contrôle du ~ — l'avertissement 2 — ne surveille que ce qui figure sous Linker dans chktexrc : \ref, \vref, \pageref, \eqref et \cite. Une chaîne nue comme Fig. 1 n'est pas couverte. Pour que Fig. soit repéré, il faut l'ajouter soi-même à la liste Abbrev. Cela fait, une nouvelle passe sur le même fichier donne Warning 12 in ref.tex line 3: Interword spacing should perhaps be used. pointant sur Fig. — le reproche étant que le point recevra sinon l'espace large de fin de phrase.

# The messages exactly as chktex prints them (one run, one bad file):
Warning 18 in bad.tex line 4: Use either `` or '' as an alternative to `"'.
Warning 11 in bad.tex line 4: You should use \ldots to achieve an ellipsis.
Warning 26 in bad.tex line 4: You ought to remove spaces in front of punctuation.
Warning 29 in bad.tex line 5: $\times$ may look prettier here.
Warning  8 in bad.tex line 7: Wrong length of dash may have been used.
Warning  9 in mm.tex  line 5: `itemize' expected, found `enumerate'.

lacheck est bien plus taciturne, et son rôle en est d'autant plus net. Là où chktex surveille les habitudes d'écriture à coups d'expressions régulières, lacheck vérifie la cohérence structurelle du document. Donnez-lui un fichier qui referme \begin{itemize} par \end{enumerate} et il signale les deux extrémités en paire : "mm.tex", line 5: <- unmatched "\end{enumerate}" et "mm.tex", line 3: -> unmatched "\begin{itemize}". chktex attrape la même faute sous le nom Warning 9, mais ne désigne que la fermeture. Dans un long document, quand la question est où l'imbrication a d'abord dérapé, lacheck y mène plus vite. La bonne réponse est de lancer les deux.

$ lacheck mm.tex
"mm.tex", line 5: <- unmatched "\end{enumerate}"
"mm.tex", line 3: -> unmatched "\begin{itemize}"

# chktex exits with the number of warnings, so CI can gate on it
$ chktex -q ref.tex >/dev/null; echo $?
2
# mute one check by number and it passes
$ chktex -q -n2 ref.tex >/dev/null; echo $?
0
# teach it your abbreviations via a local rc file
$ printf 'Abbrev { Fig. Eq. Sec. }\n' > my.chktexrc
$ chktex -q -l my.chktexrc ref.tex

Que chktex sorte avec le nombre d'avertissements lui-même est ce qui le rend utile en intégration continue. Dans l'exécution ci-dessus, chktex -q ref.tex est sorti avec 2 — deux avertissements — et couper le contrôle numéro 2 par -n2 a ramené la valeur à 0. Une politique du type « nous tolérons exactement ce contrôle » peut donc s'écrire dans la configuration du dépôt. Les réglages par projet vont dans un fichier chargé par -l my.chktexrc ; localement, on supprime avec des directives dans la source telles que % chktex-file 26.

Réprimander les commandes obsolètes et les étiquettes inutilisées : nag et refcheck

nag signale les constructions qui fonctionnent encore mais sont depuis longtemps périmées, et il le fait à la compilation. Placez \RequirePackage[l2tabu,orthodox]{nag} avant \documentclass, compilez, et le journal se remplit de doléances : Package nag Warning: Command \bf is an old LaTeX 2.09 command. suivi de Use \bfseries or \textbf instead on input line 5., puis $$...$$ is obsolete. Use \[...\] et al. instead, Command \centerline is TeX. Use \centering or center environment instead, Package epsf is obsolete. Use the graphicx package instead., et pour finir Package nag Warning: 5 complaints in total. L'outil se rentabilise dès le premier manuscrit hérité d'un modèle vieux de plusieurs décennies.

Un autre outil qui mérite un passage avant la soumission est refcheck (v1.9.1 dans TeX Live 2024). Ajoutez \usepackage{refcheck}, compilez deux fois, et il énumère les étiquettes que personne n'appelle : lors d'une exécution réelle, il a produit Package refcheck Warning: Unused label 'sec:unused' on input line 5. et Package refcheck Warning: Unused label 'eq:never' on input line 7. Une équation numérotée mais jamais citée est en général une équation qui ne devrait pas porter de numéro — et c'est la première chose à couper quand on vous demande de raccourcir l'article.

\RequirePackage[l2tabu,orthodox]{nag}   % MUST come before \documentclass
\documentclass{article}
\usepackage{refcheck}                   % lists labels nobody refers to
% Then: pdflatex paper.tex && grep -E "nag Warning|refcheck Warning" paper.log

Dérouler le cycle de relecture de bout en bout

Le choix de l'outil se décide selon qui verra quoi. Les tâches qui ne concernent que vous et vos co-auteurs : todonotes. Les modifications qui doivent porter un nom : changes. Montrer à un relecteur ce qui a bougé depuis la version précédente : latexdiff. Et la chasse aux fautes qu'une machine peut mener : chktex, lacheck et nag. Les quatre ne se marchent pas dessus. Les enchaîner dans cet ordre évite de reprendre deux fois le même manuscrit.

• Pendant la rédaction, laisser des tâches avec todonotes — \todo{...}, \missingfigure{...} — et compter ce qui reste avec \listoftodos.
• Avant de faire circuler, lancer chktex, lacheck et nag pour que les fautes détectables par machine aient disparu. Ne pas y dépenser d'attention humaine.
• Pour l'envoi, compiler une version avec lineno et \linenumbers activés. Ajouter mathlines si l'article est riche en formules.
• Réintégrer les annotations via changes — \added, \replaced, \deleted — et utiliser \listofchanges pour ne rien laisser en souffrance.
• À chaque version remise, joindre une compilation issue de latexdiff --flatten old.tex new.tex > diff.tex. Le lecteur n'a qu'à ouvrir le diff.
• Juste avant la soumission, nettoyer les étiquettes inutilisées avec refcheck, puis recompiler avec todonotes en disable et changes en final.