Communauté

Quand LaTeX vous met en échec, la personne qui détient la réponse se trouve le plus souvent sur tex.stackexchange.com. Mais cette communauté fait payer un droit d’entrée, et ce droit n’est pas la politesse : c’est un exemple minimal complet, un MWE. À quel point est-ce sérieux ? Assez pour que TeX Live livre un package nommé mwe dont l’unique fonction est de rendre les exemples minimaux plus faciles à partager, et pour que texdoc minexample ouvre un opuscule de 21 pages consacré uniquement à la fabrication d’un tel exemple. Cette page indique où porter une question LaTeX — TeX Stack Exchange, l’héritage du groupe Usenet comp.text.tex, TUG et les groupes d’utilisateurs nationaux, les gestionnaires de tickets des packages — et comment demander pour qu’une réponse revienne : l’art de ramener un document de 300 pages à vingt lignes.

Chercher sur tex.stackexchange.com avant de demander

La plupart des questions LaTeX ont déjà été posées, avec les mêmes mots. TeX Stack Exchange (tex.stackexchange.com) a été créé en août 2010 — et cette date n’est pas un ouï-dire : elle figure dans le bulletin de l’équipe LaTeX elle-même. LaTeX3 News numéro 5 (janvier 2011), livré avec TeX Live, note que le site de questions-réponses TeX Stack Exchange venait d’être créé et croissait vite : au moment de la rédaction, quelque 2 800 personnes avaient posé 2 600 questions pour 5 600 réponses au total, et 2 200 utilisateurs s’y rendaient chaque jour. Un texdoc l3news ouvre la même page sur votre machine. Plus d’une décennie plus tard, les chiffres ont pris deux ordres de grandeur, mais ce qui a vraiment grandi, c’est le stock de questions anciennes. Une astuce rend la recherche efficace : ne décrivez pas le problème avec vos mots, collez le message d’erreur tel quel. Une ligne comme ! Undefined control sequence ou ! Missing $ inserted est la meilleure clé de recherche qui soit.

Pendant les trois décennies précédentes, le centre de gravité des discussions TeX était le groupe Usenet comp.text.tex (l’espace germanophone avait de.comp.text.tex). À quel point il était central ? Les remerciements des livres de l’époque le disent. Dans TeX by Topic (Addison-Wesley, 1991), Victor Eijkhout remercie les participants des listes de discussion TeXhax, de la néerlandaise TeX-nl et de comp.text.tex, en écrivant que leurs questions et leurs réponses lui ont donné beaucoup à réfléchir. Ce livre est livré avec TeX Live — texdoc texbytopic l’ouvre, remerciements compris, de sorte que le déplacement du centre de gravité se lit directement. Le groupe existe toujours, mais pour une question LaTeX, la première adresse est aujourd’hui TeX Stack Exchange. D’anciens messages remontent encore dans les recherches : quand cela arrive, vérifiez systématiquement leur année.

Ce qu’est vraiment un exemple minimal complet (MWE)

Un MWE est le plus court document complet qui reproduise encore le problème — et « complet » s’entend strictement. Creating a LaTeX Minimal Example de Nicola L C Talbot (2014, livré avec TeX Live, texdoc minexample) commence en rappelant qu’un exemple minimal ne doit contenir aucun package ni aucun code qui ne contribue au problème, mais qu’il doit comporter une classe de document et l’environnement document. Ce n’est donc pas un fragment : c’est quelque chose que l’on peut enregistrer tel quel et passer à pdflatex — voilà le sens du « working » dans le nom. Coller trois lignes sans \begin{document} conduit à une première réponse qui réclame un exemple complet, soit un aller-retour perdu.

% A minimal working example: complete, compilable, and as short as it can be.
% Nothing here that does not bear on the problem being reported.
\documentclass{article}
\usepackage{booktabs}
\begin{document}
\begin{tabular}{ll}
  \toprule
  left & right \\
  \bottomrule
\end{tabular}
\end{document}

Les exemples réclamant une figure sont le point de blocage : on ne peut pas envoyer sa propre photo, et l’aurait-on fait que le lecteur ne la posséderait pas. C’est à cela que sert le package mwe. Un \usepackage{mwe} charge graphicx et rend disponibles, depuis l’arbre TeX, une série d’images types — example-image, example-image-a, example-image-16x9, example-grid-100x100bp et d’autres. Toute personne ayant TeX Live les possède déjà, si bien qu’un exemple contenant \includegraphics{example-image} se compile sur n’importe quelle machine. Pour la même raison, quand il faut du texte au kilomètre, on emploie \lipsum[1-3] de lipsum ou \blindtext de blindtext (mwe charge lipsum de lui-même s’il est installé). Un exemple qui n’exige aucune pièce jointe obtient une réponse plus vite, rien que pour cela.

Ramener 300 pages à vingt lignes : building up et hacking down

Il n’existe que deux chemins, et Talbot les nomme building up et hacking down. La construction part de \documentclass{article} et d’un environnement document vide, puis ajoute un élément à la fois jusqu’à ce que le problème surgisse. Le dégrossissage part d’une copie du document réel et retire jusqu’à ce que le problème disparaisse. La construction convient à un texte court ; le dégrossissage va plus vite sur 300 pages — mais il ne faut pas dégrossir ligne à ligne. Supprimez la moitié. Commentez la première moitié du préambule : si le problème persiste, cette moitié est innocente, et une seule compilation l’a établi. Coupez en deux ce qui reste, puis encore : une douzaine de tours transforment des centaines de lignes en une poignée. C’est une recherche dichotomique, et le même geste s’applique aux chapitres appelés par \include.

• Travailler sur une copie. Ne jamais entamer le .tex d’origine : chaque suppression se fait sur un double.
• Jeter le corps du texte en premier. Retirer les chapitres appelés par \include, les figures, les tableaux et la bibliographie, et ne laisser après \begin{document} que la ligne fautive.
• Supprimer le préambule par moitiés. Si le problème persiste, la moitié retirée est innocente ; s’il disparaît, c’est ce qui vient d’être retiré qui devient suspect, et on le coupe à son tour en deux.
• Développer ses propres macros. Remplacer un \newcommand par son corps distingue « le bogue vient de ma macro » de « le bogue vient du package ».
• Essayer de remplacer la classe par article. Si le problème s’évanouit alors, la classe en est la cause — c’est un vrai résultat, à mentionner dans le message.
• Recompiler après chaque coupe. L’échec le plus fréquent consiste à continuer sans s’apercevoir que le problème avait cessé de se reproduire plusieurs suppressions plus tôt.

Une fois l’exemple réduit, joignez enfin les informations de version. Nul besoin de les recopier à la main : placez la seule ligne \listfiles avant \documentclass, compilez, et la fin du .log se dote d’une section *File List* qui énumère chaque fichier chargé avec sa date et sa version. Ajoutez le moteur (pdflatex, xelatex ou lualatex) et la distribution (TeX Live 2024, MiKTeX, Overleaf) et l’on pourra pratiquement reconstituer votre installation. Ne résumez pas l’erreur : collez telle quelle la ligne qui commence par ! et les quelques lignes suivantes. Une formule du type « j’ai une espèce d’erreur » contient toujours moins d’information que la ligne d’origine.

% \listfiles before \documentclass, then look at the end of the .log:
 *File List*
 article.cls    2023/05/17 v1.4n Standard LaTeX document class
  size10.clo    2023/05/17 v1.4n Standard LaTeX file (size option)
booktabs.sty    2020/01/12 v1.61803398 Publication quality tables
 ***********

Au-delà de Stack Exchange : TUG, groupes nationaux, gestionnaires de tickets

Le TUG, TeX Users Group, est une association internationale à but non lucratif fondée en 1980. Il soutient le développement, TeX Live compris, publie la revue TUGboat et organise une conférence annuelle. Que TUGboat ne soit pas seulement une lecture se vérifie sur son propre disque : la classe de soumission ltugboat.cls est livrée avec TeX Live — sa ligne de copyright indique « Copyright 1994-2023 TeX Users Group » et le TUG en est lui-même le mainteneur — et texdoc tugboat ouvre ltubguid.pdf, les instructions aux auteurs. Autrement dit, si l’envie vient de rédiger ce que l’on a appris sur TeX, l’outil de composition pour le publier est déjà installé.

Le monde TeX repose aussi sur des groupes d’utilisateurs organisés par pays. Le guide officiel de TeX Live remercie le TUG, le DANTE e.V. germanophone, le NTG néerlandais et le GUST polonais d’avoir fourni l’infrastructure technique et administrative nécessaire, ajoute « rejoignez le groupe d’utilisateurs TeX près de chez vous » et renvoie à tug.org/usergroups.html. Le groupe hispanophone CervanTeX contribue lui aussi une FAQ à TeX Live ; tlmgr info es-tex-faq le confirme. Côté japonais, la Japanese TeX Development Community (texjporg) maintient pLaTeX et upLaTeX, jsclasses (à l’origine de Haruhiko Okumura), le support japonais de dvipdfmx, gentombow et ptex2pdf, et administre le TeX Wiki (texwiki.texjp.org) ; le forum TeX d’Okumura (okumuralab.org/tex/) est de fait l’endroit où poser une question en japonais. Ailleurs, il y a le forum latex.org, la liste de diffusion [email protected] et r/LaTeX sur Reddit.

Lorsqu’il est acquis qu’il ne s’agit pas d’une question mais d’un bogue, la destination change. Un défaut propre à un package va au gestionnaire de tickets de son auteur — et l’adresse n’est pas à chercher, elle se trouve déjà sur votre machine. Si la sortie de tlmgr info <package> comporte une ligne cat-contact-bugs ou cat-contact-repository, c’est là qu’il faut signaler (tlmgr info mwe, par exemple, renvoie une page d’issues GitHub). Un défaut de LaTeX lui-même, du noyau, va au LaTeX Project (latex-project.org), et l’on emploie alors le package latexbug. Il sert à classer les bogues, et l’équipe LaTeX demande qu’il soit chargé dans tout fichier de test joint à un rapport : ce chargement détermine si le bogue relève réellement du noyau ou d’un package tiers. Un rapport envoyé à la mauvaise adresse n’arrive nulle part.

Comment rédiger une question qui obtient une réponse

Quatre éléments suffisent : un bref énoncé du symptôme, le MWE, le message d’erreur littéral et ce que l’on a déjà essayé. Dans l’opuscule cité plus haut, Talbot conseille de rester bref dans la description, d’énumérer les méthodes essayées pour localiser le problème et de ne pas se lancer dans un long récit de son projet — trop d’information décourage la lecture. Elle formule aussi une prémisse qu’on oublie volontiers : personne n’est payé et personne n’est tenu de répondre, de sorte qu’un message ne doit pas sonner comme une exigence ou un reproche. Que ce conseil, écrit en 2014, voyage encore tel quel dans TeX Live en dit long sur le climat de cette communauté. Un ajout : précisez ce que vous cherchez réellement à obtenir. Si l’on ne montre que l’approche qui a échoué, personne ne pourra proposer la voie plus simple à laquelle vous n’aviez pas pensé.