Outils de compilation

Pour terminer un vrai document, il faut souvent lancer latex deux fois, avec biber (bibliographie) ou makeindex (index) entre les deux, puis d’autres commandes dans le bon ordre et le bon nombre de fois. Le faire à la main est pénible et source d’erreurs. Les outils de compilation automatisent cela. Trois sont courants : latexmk, qui détermine seul les passes nécessaires ; llmk, configuré en TOML ; et arara, où les étapes sont écrites explicitement dans la source.

Pourquoi il faut un outil de compilation

Les références croisées et la table des matières nécessitent au moins deux compilations : la première écrit les numéros dans .aux, la seconde les relit. Avec une bibliographie, il faut insérer biber ou bibtex ; avec un index, makeindex ; un glossaire demande encore autre chose. Si l’ordre ou le nombre de passes est faux, les numéros se décalent. Un outil de compilation lance les commandes nécessaires dans le bon ordre, autant de fois qu’il le faut, jusqu’à stabilisation. Pour le rôle de chaque commande, voir « Compile commands ».

latexmk — le standard automatique

latexmk (un script Perl de John Collins) est le standard de fait ; Overleaf l’utilise par défaut. Il surveille des fichiers comme .aux pour décider lui-même si une nouvelle passe est nécessaire, et appelle biber/bibtex ainsi que makeindex au bon moment. Il continue jusqu’à ce que la sortie soit stable : en pratique, il suffit de demander « compile ».

Le plus agréable est -pvc (preview continuously) : à chaque sauvegarde, il reconstruit seulement ce qui est nécessaire et rafraîchit le visualiseur.

latexmk -pdf -pvc document.tex   # 保存のたび自動ビルド / rebuild on every save
latexmk -c                       # 補助ファイルを掃除 / clean aux files

Son comportement se configure dans un fichier .latexmkrc (un latexmkrc/.latexmkrc local, ou ~/.latexmkrc). $pdf_mode choisit la voie de sortie ; dans latexmk actuel, 1 signifie pdfLaTeX, 2 DVI → dvips → ps2pdf, 3 DVI → dvipdf, 4 LuaLaTeX et 5 XeLaTeX. Pour le japonais, la configuration habituelle pointe $latex vers uplatex, $dvipdf vers dvipdfmx, et utilise $pdf_mode = 3 pour produire le PDF via une conversion DVI.

# .latexmkrc
$pdf_mode = 1;   # 1 = pdflatex
$pdflatex = 'pdflatex -synctex=1 -interaction=nonstopmode %O %S';

llmk — une configuration qui voyage avec le document

llmk (Light LaTeX Make, de Takuto Asakura) décrit la compilation déclarativement en TOML. On écrit soit un llmk.toml avec source et les commandes à utiliser, soit les mêmes réglages sous forme de commentaires magiques dans le .tex. Le but est la reproductibilité indépendante de la machine : le même résultat pour tout le monde, partout. Comme la configuration accompagne le document, llmk convient bien à la collaboration et à la distribution.

# llmk.toml
latex  = "lualatex"
source = "main.tex"

Avec les commentaires magiques, on écrit du TOML entre des lignes composées d’au moins trois caractères + (les formats % !TEX et YaTeX sont aussi lus, mais le bloc TOML l’emporte) :

% +++
% latex = "uplatex"
% dvipdf = "dvipdfmx"
% +++
\documentclass{ujarticle}

arara — écrire les étapes dans la source

arara (Island of TeX, par Paulo Cereda et d’autres) adopte l’approche inverse de la déduction par les logs : l’auteur indique explicitement quoi faire. On place des directives en commentaires au début du .tex, puis arara document.tex les exécute de haut en bas ; chaque étape doit réussir avant la suivante. Le fichier source montre clairement ce qui sera lancé.

% arara: pdflatex
% arara: biber
% arara: pdflatex
% arara: pdflatex: { synctex: yes }
\documentclass{article}

Chaque directive correspond à une règle, c’est-à-dire un fichier YAML décrivant comment appeler une commande. La directive pdflatex est associée à la règle pdflatex, et l’on peut transmettre des options comme { synctex: yes }. C’est adapté quand on veut un contrôle complet des étapes ou reproduire exactement un flux particulier.

Lequel choisir

• latexmk — détermine automatiquement les passes ; le plus répandu, avec un aperçu continu confortable grâce à -pvc. Le choix par défaut.
• llmk — TOML déclaratif livré avec le document ; reproductible d’une machine à l’autre. Bon pour la collaboration et la distribution.
• arara — étapes explicites dans la source ; transparent, pour contrôler strictement le flux.

Les trois sont plus sûrs et plus rapides que taper (u)platex → dvipdfmx à la main. En cas d’hésitation, commencez par latexmk -pdf -pvc, puis passez à llmk ou arara lorsque la portabilité de la configuration ou l’explicitation complète devient importante.

Le contrat de projet pour les outils de compilation

Un outil de compilation n’est pas seulement un nom de commande commode : c’est un contrat de projet avec les collaborateurs et la CI. Que vous choisissiez .latexmkrc, llmk.toml ou des directives arara, enregistrez dans des fichiers quel moteur le manuscrit utilise, quel outil traite la bibliographie, si un index est produit et où le PDF est écrit. Rédiger ce contrat de projet d’abord permet de reproduire la même procédure avant soumission du PDF, même si l’éditeur change.

Au quotidien, les boutons de l’éditeur et la CI doivent appeler le même contrat. Si les humains utilisent latexmk -pdf main.tex mais que la CI lance un lualatex brut séparé, des problèmes de polices ou de bibliographie peuvent rester invisibles jusqu’à la soumission. Décidez d’abord d’une commande qui réussit en ligne de commande, puis diffusez-la à l’éditeur, au build en surveillance et à la CI.