Outils de compilation

Quand on dit avoir installé LaTeX, ce qui arrive réellement sur le disque n’est pas un programme mais un répertoire rempli d’outils en ligne de commande. Sur cette machine équipée de TeX Live 2024, ce répertoire contient près de 490 commandes, et lors d’une session d’écriture ordinaire on en tape une ou deux. Les quelque quatre cent quatre-vingts autres constituent la réserve que la distribution garde pour le jour où un document cesse de coopérer : kpsewhich pour demander où se trouve vraiment un package, texdoc pour ouvrir son manuel, tlmgr pour installer ce qui manque, pdfcrop pour rogner une figure. Cette page dresse la carte de cette réserve, classée selon la question à laquelle chaque outil répond. Les pilotes de compilation qui se placent au-dessus — latexmk, llmk, arara — ont leur propre page ; ici on reste un cran en dessous.

« Chez moi ça compile » : la première commande à lancer est kpsewhich

Le même fichier .tex compile sur votre machine et échoue sur celle d’un co-auteur. Presque toujours, il s’agit de savoir où sont les fichiers, et kpsewhich tranche en une ligne. Sa réponse fait autorité parce qu’il ne cherche pas de son côté : toutes les moteurs de TeX Live 2024 sont liés à kpathsea, la bibliothèque de recherche de fichiers (version 6.4.0 dans cette édition), et kpsewhich n’est que cette même bibliothèque exposée comme commande autonome. Le chemin affiché est donc le fichier que le moteur ouvrira réellement, et non une supposition. Si kpsewhich amsmath.sty n’affiche rien, le package est tout simplement absent et la compilation produira ! LaTeX Error: File amsmath.sty not found. S’il affiche quelque chose, le problème n’est pas l’absence mais le fait que ce soit le mauvais fichier qui soit visible.

kpsewhich amsmath.sty
# /usr/local/texlive/2024/texmf-dist/tex/latex/amsmath/amsmath.sty

kpsewhich article.cls          # classes are found the same way
kpsewhich --all texmf.cnf      # every match, in search order
kpsewhich --progname=xelatex --format=tfm cmr10.tfm

Avec --all, on obtient toutes les correspondances dans l’ordre de recherche, et non la seule première. C’est là que se cache la panne la plus vicieuse, pire qu’un fichier manquant. TeX retient le premier résultat : un vieux .sty copié dans le dossier du manuscrit il y a des années masque donc discrètement la version courante de la distribution. Rien d’anormal n’apparaît dans le journal ; seul le comportement change d’une machine à l’autre. Un kpsewhich --all rend la chose visible, le même nom apparaissant deux fois. kpsewhich ne se limite pas non plus aux .sty : les classes (article.cls), les métriques de fontes et les fichiers de configuration passent par le même mécanisme. Si la recherche diffère selon le moteur, on peut interroger sous un autre nom avec --progname=xelatex, et restreindre par type de fichier avec --format=tfm (kpsewhich --help-formats en donne la liste).

--var-value et --show-path : lire ce que le moteur tient pour vrai

kpsewhich --var-value=TEXMFHOME n’imprime qu’une variable de configuration ; kpsewhich --show-path=tex imprime toute la liste ordonnée des répertoires explorés pour les fichiers .tex. Le premier répond au « où », le second au « dans quel ordre ». Une fois ces deux commandes connues, on cesse de se fier aux généralités de la documentation pour lire les valeurs que la machine utilise réellement. Quatre variables comptent avant tout, car les arbres de recherche de TeX sont séparés par rôle : personnel, site, distribution, fichiers engendrés. L’ordre a lui aussi un sens — l’arbre personnel précède la distribution, et c’est exactement pour cela qu’un .sty maison peut remplacer un .sty standard.

kpsewhich --var-value=TEXMFHOME
# /Users/you/Library/texmf

kpsewhich --show-path=tex      # the whole ordered search list
kpsewhich --expand-var='$TEXMFDIST/tex/latex'

Où placer ses propres .sty : l’arbre texmf personnel

Un .sty ou un .cls écrit soi-même, ou un package téléchargé à la main depuis le CTAN, se place dans TEXMFHOME. Ne devinez pas l’emplacement : demandez-le à kpsewhich --var-value=TEXMFHOME. Sous macOS avec MacTeX, la réponse est ~/Library/texmf ; une installation TeX Live sous Linux répond généralement ~/texmf. Un piège attend ici : ce répertoire n’existe le plus souvent pas encore. kpsewhich indique l’emplacement configuré, pas un emplacement existant ; la première étape consiste donc à créer le chemin affiché. À l’intérieur, on suit la TDS (TeX Directory Structure) : un package LaTeX va dans TEXMFHOME/tex/latex/<nom>/<nom>.sty.

mkdir -p "$(kpsewhich --var-value=TEXMFHOME)/tex/latex/mystyle"
cp mystyle.sty "$(kpsewhich --var-value=TEXMFHOME)/tex/latex/mystyle/"
kpsewhich mystyle.sty          # found immediately, no texhash needed

texhash et mktexlsr : un seul programme sous deux noms

texhash et mktexlsr font la même chose — plus exactement, ce sont le même fichier. En regardant dans le répertoire bin de TeX Live 2024, texhash se révèle être un lien symbolique vers mktexlsr. Tous deux reconstruisent ls-R, la base de données des noms de fichiers. L’arbre de la distribution est énorme : sur cette machine, texmf-dist/ls-R pèse à lui seul plus de 5 Mo. Parcourir le disque à chaque fois serait bien trop lent ; les arbres système sont donc consultés via ls-R, au prix d’un marché : il faut reconstruire la base chaque fois que l’on ajoute des fichiers. C’est pourquoi la réponse à « j’ai mis quelque chose dans TEXMFLOCAL et il reste introuvable » est sudo mktexlsr. L’arbre TEXMFHOME de la section précédente, lui, est relu sur le disque à chaque fois : un .sty qu’on y dépose est trouvé immédiatement — créez-en un, interrogez kpsewhich, et la réponse arrive sans que texhash ait jamais tourné. C’est un argument de plus en faveur de l’arbre personnel.

texdoc : le manuel du package est déjà sur votre disque

Tapez texdoc geometry et le manuel PDF du package geometry s’ouvre dans votre lecteur. Sans réseau : quand le package est arrivé du CTAN, sa documentation l’accompagnait. Là réside tout l’intérêt de la commande — le manuel de la version réellement installée est plus fiable que n’importe quel tutoriel vieillissant remonté par un moteur de recherche. Plusieurs documents peuvent porter le même nom ; en cas de doute, texdoc -l geometry en dresse la liste : sur cette machine, le geometry.pdf anglais et aussi un geometry-de.pdf allemand. L’option -s (showall) élargit la pêche aux résultats plus lointains, et -M produit une sortie lisible par une machine. La version livrée avec TeX Live 2024 est Texdoc 4.1 (2024-03-10), dont la ligne de copyright cite Manuel Pégourié-Gonnard, Takuto Asakura et la TeX Live Team.

texdoc geometry            # open the manual
texdoc -l geometry         # list every candidate first
texdoc texdoc              # the manual for texdoc itself

tlmgr install, update, info — et ce que signifie « TeX Live 2024 is frozen »

tlmgr est le gestionnaire de packages de TeX Live, et trois sous-commandes suffisent au quotidien : tlmgr info NOM pour interroger un package, tlmgr install NOM pour l’ajouter, tlmgr update --self --all pour tout mettre à jour. La sortie d’info est la plus utile des trois : installed: Yes dit s’il est présent, revision: de quelle version il s’agit, collection: à quel ensemble il appartient. Un détail fait ici gagner une demi-journée : le nom d’une commande et celui d’un package TeX Live ne coïncident pas toujours. À tlmgr info llmk, la réponse commence par tlmgr: cannot find package llmk — puis le programme cherche de lui-même dans les descriptions et les noms de fichiers et propose light-latex-make. La commande llmk ne réside tout simplement pas dans un package du même nom.

tlmgr info amsmath             # installed? which revision? which collection?
sudo tlmgr install siunitx     # a system-wide tree needs root
sudo tlmgr update --self --all
tlmgr --version                # also prints which installation is in use

L’autre surprise, la première fois, c’est l’avis de gel. Sur TeX Live 2024, la plupart des sous-commandes de tlmgr commencent par afficher TeX Live 2024 is frozen puis and will no longer be routinely updated. Il s’agit d’un avis, non d’une erreur. Le message décrit simplement le fonctionnement de TeX Live : dès qu’une nouvelle édition annuelle paraît, le dépôt de l’année précédente cesse de recevoir des mises à jour régulières. La commande s’exécute normalement en dessous — tlmgr info amsmath affiche la bannière puis, comme d’habitude, l’information complète sur le package. Le remède n’est donc pas de réessayer mais d’installer l’édition annuelle plus récente. Par ailleurs, dans une installation standard comme MacTeX, le répertoire /usr/local/texlive/2024/texmf-dist appartient à root : tlmgr install et tlmgr update réclament donc sudo. Sur une machine où l’on n’a pas les droits d’administration, déposer le fichier à la main dans TEXMFHOME, comme à la section précédente, va souvent plus vite.

pdfcrop : rogner la marge blanche d’une figure PDF

Lancer pdfcrop figure.pdf produit figure-crop.pdf, dont les marges ont été calculées et retirées page par page. C’est l’outil qu’il faut lorsqu’une figure TikZ a été composée dans un fichier à part, ou lorsqu’un autre logiciel a exporté un PDF sous la forme « un petit dessin au milieu d’une feuille A4 ». Inclure cela tel quel avec \includegraphics revient à coller le papier, pas l’image. Pour conserver volontairement une marge, --margins "5 5 5 5" indique les quatre côtés ; l’unité est le bp (big point). Le piège tient à la dépendance : pdfcrop ne découpe pas lui-même — par défaut il pilote Ghostscript (gs, modifiable avec --gscmd) ainsi qu’un moteur TeX. La quasi-totalité des « pdfcrop est installé mais ne marche pas » se ramène à l’absence de Ghostscript. La version incluse dans TeX Live 2024 est pdfcrop 1.42 (2023/04/15, de Heiko Oberdiek).

pdfcrop figure.pdf                       # -> figure-crop.pdf
pdfcrop --margins "5 5 5 5" figure.pdf   # keep 5bp on every side
pdfcrop --luatex figure.pdf              # drive lualatex instead of pdftex

Regarder dans un PDF terminé — pdftotext n’est pas une commande TeX

Pour extraire du texte d’un PDF terminé, la plupart des guides dégainent pdftotext. Il faut toutefois savoir que pdftotext ne fait pas partie de TeX Live. On ne le trouve nulle part dans le répertoire bin de TeX Live 2024 ; l’exemplaire présent sur ce Mac y a été déposé par le paquet poppler de Homebrew. Il en va de même pour pdfinfo. Rien n’interdit de s’en servir, mais un pdftotext: command not found sur une machine où TeX fonctionne parfaitement n’est pas une panne : il s’agit simplement d’un autre logiciel. Ce que TeX Live livre, en revanche, c’est pdftosrc, dont la ligne d’usage indique pdftosrc <PDF-file> [<stream-object-number>] : un outil pour extraire un objet de flux d’un PDF. Pour l’inspection quotidienne, lire le fichier .log va généralement plus vite que fouiller le PDF ; et les outils voisins — texfot pour condenser le journal, Ghostscript pour opérer sur les PDF, dvisvgm pour la sortie vectorielle — sont rassemblés sur une page dédiée.

Quelle commande pour quel symptôme

Ce qui mérite de devenir une habitude, c’est l’ordre des questions. Dès que quelque chose cloche, vérifiez l’emplacement avec kpsewhich et la spécification avec texdoc avant d’interroger qui que ce soit : ni l’un ni l’autre n’exige de réseau ou de droits d’administration, et tous deux répondent en quelques secondes. C’est seulement lorsque cela révèle une véritable absence que tlmgr entre en scène ; et en cas d’hésitation sur l’endroit où déposer un fichier, choisissez TEXMFHOME. La couche qui automatise le nombre et l’ordre des passes du moteur — latexmk et ses proches — n’est pas celle-ci, faite de recherche, de lecture et d’installation. Aussi soigneusement que l’on règle la première, les divergences entre machines ne disparaîtront que lorsque la seconde sera solide.