CTAN et documentation

Installer LaTeX, c’est installer une bibliothèque. En comptant la documentation sous texmf-dist/doc dans TeX Live 2024 — elle provient entièrement de CTAN, le Comprehensive TeX Archive Network —, on trouve 10 099 PDF dans une arborescence de 3,7 Go, et la plupart ne seront jamais ouverts. La clé des copies déjà présentes sur le disque tient en une commande d’un seul mot : texdoc. Cette page explique le fonctionnement de cette archive et, plus utile encore, comment lire la documentation que l’on possède déjà : texdoc, kpsewhich, tlmgr info, et la reconstruction d’un manuel à partir de sa source .dtx.

texdoc <package> : ouvrir le manuel que l’on possède déjà

Taper texdoc booktabs ouvre le manuel du booktabs réellement installé. Pas une recherche en ligne : un fichier présent sur le disque. Cela compte, car ce qui s’ouvre est la documentation de la version installée : un article trouvé sur le web décrit peut-être une pratique vieille de deux versions, alors que le PDF fourni par texdoc décrit la machine sous les doigts. Le mode par défaut est le mode view, qui ouvre l’unique résultat jugé le meilleur. Les options modifient ce comportement : -l énumère les candidats et laisse en choisir un par son numéro, -m ouvre directement s’il n’y a qu’un bon résultat et propose sinon le menu, et -s affiche même les résultats mal notés, normalement masqués.

texdoc booktabs        # open the manual for the version you have installed
texdoc -l siunitx      # list every candidate, then pick one by number
texdoc -I -l booktabs  # plain list, no interactive prompt
texdoc -M -l lshort    # machine-readable: name, score, path, language
texdoc bootabs         # a typo still finds booktabs (fuzzy search)

L’intelligence de texdoc tient à ce qu’il ne se contente pas de comparer des noms de fichiers. En plus de parcourir les arbres de documentation (le chemin TEXDOCS), il interroge la base de données de TeX Live, texlive.tlpdb, et peut donc remonter jusqu’au package qui contient <nom>.sty ou <nom>.cls. C’est pourquoi texdoc shortvrb ouvre correctement le doc.pdf du package latex, celui qui fournit shortvrb.sty : le fichier de configuration livré contient la ligne alias shortvrb = base/doc. Les candidats reçoivent ensuite une note chiffrée : un fichier nommé <nom>.pdf obtient beaucoup, un Makefile est rétrogradé de -1000. Et si rien ne correspond, une passe approximative cherche le nom de package le plus proche, si bien que texdoc bootabs atteint quand même le manuel de booktabs. Lorsque même cela échoue, le message est Unfortunately, there are no good matches for "...", suivi d’un renvoi vers le même document sur texdoc.org.

Un dernier mécanisme compte pour qui lit en plusieurs langues : texdoc déduit la langue de la locale du système et bonifie <nom>-<code de langue>.pdf. Un texdoc -l booktabs fait apparaître, à côté du booktabs.pdf anglais, les répertoires booktabs-de et booktabs-fr — des manuels traduits que TeX Live livre lui-même. Pour la même raison, texdoc -l lshort renvoie plus de soixante résultats, les éditions linguistiques en tête, marquées [fr], [zh], [ko], etc. Si la détection automatique se trompe, une ligne lang = fr dans le fichier de configuration personnel suffit à la fixer ; texdoc --files en indique l’emplacement, ~/Library/texmf/texdoc/texdoc.cnf sous macOS. Une ligne mode = list dans le même fichier fait que chaque appel se comportera désormais comme si -l avait été saisi.

Où se trouve ce .sty ? kpsewhich et tlmgr info

Un kpsewhich booktabs.sty renvoie en une ligne le chemin absolu du fichier que LaTeX lira réellement. Quand un document se comporte autrement que ne le décrit son manuel, le premier soupçon ne devrait pas porter sur la version mais sur la possibilité que le fichier lu ne soit pas celui que l’on croit — et cette commande tranche immédiatement. Avec --all, tous les candidats apparaissent, dans l’ordre de recherche. Un kpsewhich --all article.cls renvoie deux lignes : texmf-dist/tex/latex/base/article.cls et texmf-dist/tex/latex-dev/base/article.cls. Le masquage — une copie qui en cache une autre située plus loin — devient visible. Si l’on a un jour écrit son propre .sty et déposé dans l’arbre personnel, il faut soupçonner le répertoire indiqué par kpsewhich -var-value=TEXMFHOME (~/Library/texmf sous macOS). Lorsque rien n’est trouvé, kpsewhich n’affiche rien et se termine avec le code 1, ce qui permet de l’employer dans une condition de shell.

kpsewhich booktabs.sty          # which file will TeX actually read?
kpsewhich --all article.cls     # every copy, in search order
kpsewhich -var-value=TEXMFHOME  # your personal tree

tlmgr info booktabs             # version, licence, collection, sizes
tlmgr info --list booktabs      # run / source / doc files, one by one

tlmgr info booktabs répond à une autre question : non pas où, mais ce que dit le catalogue. On obtient la description en une ligne, la description longue, la collection d’appartenance, la licence (lppl1.3c), la taille des parties src, doc et run, ainsi que la version. Des champs comme cat-contact-bugs et cat-contact-repository peuvent aussi figurer : ce sont les adresses du gestionnaire de tickets du package. Un tlmgr info --list booktabs affiche les fichiers eux-mêmes en trois groupes — et ces trois groupes sont l’organisation des répertoires de TeX Live : tex/latex/booktabs/booktabs.sty (le code chargé à l’exécution), doc/latex/booktabs/booktabs.pdf (le manuel qu’ouvre texdoc) et source/latex/booktabs/booktabs.dtx avec son .ins (l’origine des deux).

Le couple .dtx / .ins : une source qui est son propre manuel

Un fichier .dtx fait cohabiter le code et son commentaire dans un même fichier, et ce même fichier se traite de deux façons. Un tex <package>.ins fait jeter la prose par docstrip, qui écrit le .sty ; un pdflatex <package>.dtx compose au contraire le code, annoté ligne à ligne, sous forme de manuel PDF. Essayé localement sur multirow : tex multirow.ins a produit trois fichiers — multirow.sty, bigstrut.sty et bigdelim.sty — et pdflatex multirow.dtx a donné une source annotée de 30 pages. L’intérêt est de pouvoir suivre un comportement dont le manuel ouvert par texdoc ne dit rien : l’implémentation est là, et la question « pourquoi cette option fait-elle cela ? » se lit jusqu’au bout.

# copy the two source files out of the tree first, then:
tex multirow.ins        # docstrip: writes multirow.sty, bigstrut.sty, bigdelim.sty
pdflatex multirow.dtx   # the same .dtx typeset as an annotated source PDF
pdflatex multirow.dtx   # run twice so the cross-references settle

Le cas extrême de ce montage est LaTeX lui-même. Un texdoc source2e ouvre The LaTeX 2ε Sources : 1 308 pages de noyau annoté, signées Johannes Braams, David Carlisle, Alan Jeffrey, Leslie Lamport, Frank Mittelbach et d’autres. Et dès que lire la documentation devient une habitude, on remarque des détails. La version que rapporte tlmgr info booktabs est 1.61803398 : les décimales du nombre d’or φ = 1,618033988…, allongées d’un chiffre à chaque publication — et booktabs.dtx l’écrit noir sur blanc, « (converging to phi, the golden ratio) ». Un numéro de version qui est en réalité une suite relève de la plaisanterie, mais on ne peut le vérifier qu’en ouvrant le .dtx.

Ce qu’est CTAN : une adresse unique, construite en 1992

CTAN (le Comprehensive TeX Archive Network, ctan.org) existe pour qu’il y ait un seul endroit où déposer le matériel TeX. Il a été construit en 1992 par Rainer Schöpf et Joachim Schrod en Allemagne, Sebastian Rahtz au Royaume-Uni et George Greenwade aux États-Unis — c’est Greenwade qui en a trouvé le nom — puis officiellement annoncé à la conférence EuroTeX d’Aston, au Royaume-Uni, en 1993 ; l’idée elle-même remonte à une discussion de 1991. Auparavant, macros et polices se dispersaient sur quantité de serveurs FTP, et différentes personnes recollectaient sans cesse le même matériel chacune de son côté. Le problème que CTAN a résolu n’était donc pas l’absence d’un lieu de dépôt : c’était qu’il y en avait trop.

L’entrée dans CTAN, aujourd’hui, est une page de package, ctan.org/pkg/<nom>. Elle affiche Sources, Documentation (le PDF), Version, Licenses, Copyright, Maintainer, Contained in (TeX Live et MiKTeX le fournissent-ils ?) et Topics. En pratique, ce sont les deux derniers champs qui rapportent. Contained in dit d’un coup d’œil si tlmgr install ira chercher le package ou s’il faudra l’installer à la main. Topics est la porte d’entrée du « je ne connais pas son nom mais je sais ce qu’il doit faire » : pour du code de tableau, on passe par le sujet table. Le champ de licence indique presque toujours LPPL, la LaTeX Project Public License, les conditions standard du monde TeX pour la redistribution et la modification.

Le mot « Network » n’est pas décoratif. CTAN se compose d’un site central et de miroirs officiels répartis dans le monde, qui se synchronisent automatiquement (en tenir un demande actuellement une cinquantaine de gigaoctets). C’est pourquoi écrire mirror.ctan.org dans une adresse de téléchargement redirige vers un miroir proche — le guide officiel de TeX Live précise que le dépôt de packages par défaut est un miroir CTAN choisi automatiquement via https://mirror.ctan.org. Pour se fixer sur un miroir précis, la liste se trouve sur ctan.org/mirrors. Le trafic circule aussi en sens inverse : les auteurs téléversent les packages nouveaux ou mis à jour dans la zone de réception du site central, l’équipe CTAN les traite, et les miroirs les reprennent. Les outils de cet envoi figurent eux aussi dans TeX Live : ctanify construit une archive dans la structure que CTAN préfère, et ctan-o-mat valide une soumission avant l’envoi. Et TeX Live est lui-même un instantané de CTAN : les 3,7 Go de documentation sur le disque sont une copie de cette archive.

Documentation locale ou en ligne : à laquelle se fier

Ce qui décide si un document compile, c’est la documentation présente sur votre disque. Quand la question est « pourquoi cela ne marche-t-il pas ? », ouvrez donc texdoc en premier. Quand elle est « cette fonction a-t-elle été ajoutée ? », il faut au contraire regarder la page CTAN du package ou texdoc.org : ces sources-là sont toujours à jour. Les deux divergent réellement. Chaque édition de TeX Live finit par être gelée et les mises à jour ultérieures partent avec l’édition suivante ; il est donc courant que la version ou le classement thématique rapportés par tlmgr info soient plus anciens que ce qu’affiche CTAN. Devant un écart, l’ordre prudent est : confirmer sa propre version avec tlmgr info <package>, puis la lire en regard de la fiche CTAN. Quand du code trouvé sur le web refuse de fonctionner, ce n’est bien souvent pas l’article qui a vieilli — c’est simplement que votre environnement diffère du sien.