Pandoc pour des articles d’informatique théorique ?

TL;DR :¹¹ Pandoc est un outil de conversion de documents écrit en Haskell. Il est très utile pour convertir des documents écrits en Markdown en d’autres formats, comme LaTeX, HTML, Word, Open Document, ou PDF. Cet article explique pourquoi il n’est pas actuellement possible de l’utiliser pour écrire des articles d’informatique théorique.

LaTeX pour l’écriture d’articles scientifiques

Écrire un article scientifique, au moins en informatique théorique et en mathématiques, répond à des contraintes explicites et implicites de forme et de fond qui permettent une détection rapide (mais parfois erronée) de la qualité du document. Sans même parler de relecture par les pairs, un processus relativement coûteux, il est possible de rendre automatique ou semi automatique la détection de « faux/mauvais » articles, et c’est ce qui est déployé en pratique par l’archive en ligne de arXiv, maintenue par Cornell University Library. Un exemple simple est le respect de certaines conventions d’écritures et règles de typographie, et en mathématiques/informatique, cela commence par l’utilisation du système de génération de documents LaTeX. Je suis assez confiant dans l’idée qu’un article de mathématiques écrit avec un autre système d’écriture part avec un handicap certain.²²

Mais pourquoi est-ce que ce système est hégémonique ? Et d’ailleurs, pourquoi seulement dans certaines matières techniques ? Sans faire un historique complet de cette technologie, on peut déjà faire remarquer qu’elle remonte à un programme plus ancien, TeX conçu par Donald Knuth dans les années 70, avec comme objectif explicite de permettre l’écriture d’articles utilisant des équations complexes. L’idée était d’écrire un document textuel « simple » (en utilisant les caractères ASCII de l’époque) qui serait ensuite transformé en un document imprimable. Cette étape de transformation permettait au système de gérer automatiquement la mise en page, les numéros de référence, les tables des matières, etc. Ainsi, il suffit d’écrire \tableofcontents pour que dans le document final, une table des matières soit générée en lieu et place de cette commande. De même, pour écrire une formule comme \(\sum_{i = 0}^n \binom{n}{k} x^k y^{n-k}\), on peut écrire $\sum_{i = 0}^n \binom{n}{k} x^k y^{n-k}$. À mon sens, ce qui a fait le succès de TeX et des variantes basées sur lui sont les propriétés suivantes :

1. Les documents sont éditables. C’est-à-dire qu’il est possible d’utiliser n’importe quel éditeur de texte, ou programme qui manipule du texte pour modifier le document. De plus, la syntaxe est relativement légère ce qui rend l’édition possible sans béquille logicielle. J’invite le lecteur à essayer de modifier en utilisant uniquement des outils standards un document Word, qui est une archive contenant des fichiers XML à la syntaxe complexe et peu lisible.
2. Un corollaire non négligeable de la première propriété et que ces documents sont alors versionnables et facilement archivables.
3. Un système dédié d’écriture d’équations, qui s’intègre parfaitement au reste de la syntaxe et qui permet d’écrire essentiellement toutes les mathématiques connues.
4. Un système de gestion de bibliographie, bibtex, permet de facilement citer un article, un livre, une conférence, et ce bien avant l’apparition de moteurs comme Zotero ou Mendeley. Pour citer un article, il suffit d’écrire \cite{nom_de_l_article} et la citation sera écrite au format approprié dans le document final.
5. Un système de gestion de références croisées, qui permet de dire « voir la figure XX page YY », sans se préoccuper de la page (elle est calculée) ou du numéro de la figure (aussi calculé).
6. Le système de macro commandes intégré à LaTeX / TeX permet aux éditeurs de définir le style du document, sans que les auteurs aient à se préoccuper de la forme (ou presque). Ainsi, le format des titres, le nombre de colonnes, les marges, la rédaction des citations n’est pas à la charge de l’auteur.

Ces arguments en faveur de LaTeX sont suffisamment forts pour que la communauté de mathématiciens et d’informaticiens s’en emparent. Ne pas pouvoir écrire les mathématiques étant un frein majeur. De plus, la familiarité avec les notions de fichiers texte et de compilation a supprimé le principal défaut de ce système d’écriture : ce qui est écrit n’est pas ce qui sera imprimé. C’est ce qui explique que, malgré des avantages indéniables, ce système est délaissé pour des modèles « WYSIWYG » (What You See Is What You Get) comme Word ou Libre Office lorsque la majorité du document est précisément du texte et des images, sans formules mathématiques ou de nombreuses références croisées.

Malgré le développement de nombreux outils pour écrire des documents scientifiques dans des logiciels comme Word ou Libre Office, l’écriture des mathématiques reste douloureuse avec un éditeur graphique, et la modification de formules est en général un cauchemar. Les systèmes un peu pragmatiques ont directement intégré la syntaxe introduite par LaTeX dans leur propre système, un exemple typique étant MathJax pour les pages web, car personne n’écrit directement des formules en MathML.

Le « Markup » et les langages modernes

Le markup (en Français, le balisage) est une technique qui consiste à ajouter à un document textuel des annotations qui décrivent une structure arborescente. Le langage de balisage le plus utilisé au monde est probablement le HTML, qui est utilisé pour décrire des pages web. Un exemple typique de fragment HTML est le suivant :

<p>Je suis dans une balise de paragraphe. <strong>Je suis en gras.</strong>
Et maintenant, <em>je suis en italique</em>.</p>

L’utilisation de balises <p>, <strong>, <em> permet de décrire la structure du document, qui sera ensuite interprétée par un navigateur web pour afficher le texte en gras, en italique, etc. Bien entendu, le HTML contient d’autres balises et des possibilités supplémentaires pour décrire des agencements plus complexes de texte, des images, des liens, etc. C’est ce qui donne des pages web comme celle que vous êtes probablement en train de lire.

Cette manière d’écrire textuellement des indications sur la structure d’un document en vue d’une future interprétation n’est pas sans rappeler ce qui a été décrit plus haut au sujet de TeX et de LaTeX. En effet, bien que LaTeX ne soit pas techniquement un langage de balisage,³³ c’est la manière dont il est utilisé en pratique par la plupart des auteurs de documents. L’équivalent du fragment HTML précédent en LaTeX pourrait être le code suivant :

Je suis dans un paragraphe. \textbf{Je suis en gras.} Et maintenant,
\textit{je suis en italique}.

Pourquoi ne pas utiliser l’omniprésent HTML pour écrire des articles scientifiques ? Une première réponse est simple : aucune des fonctionnalités qui justifient l’utilisation d’un système aussi complexe que LaTeX pour écrire des documents n’est disponible en HTML. Même les références croisées, qui sont la force de HTML,⁴⁴ ne sont pas destinées à la lecture mais à la navigation.⁵⁵ Les formules mathématiques sont un problème ouvert depuis une vingtaine d’années maintenant, et je ne parle même pas des référence bibliographiques. Enfin, le HTML est un langage déclaratif qui ne permet pas de définir de nouvelles balises au sein du document, et cela veut dire qu’écrire un article scientifique en HTML serait très rapidement cauchemardesque.

Une seconde réponse est plus subtile : le HTML est un langage de balisage qui spécifie comment afficher un document à l’écran. En particulier, il est conçu pour être lisible sur des tailles d’écrans différentes, pour être accessible aux personnes handicapées, pour être indexable par les moteurs de recherche, etc. En revanche, il n’est pas (encore) adapté pour construire des documents imprimables qui respectent les standards de la publication scientifique.

Mais alors, pourquoi ne pas simplement utiliser LaTeX pour écrire des articles d’informatique théorique ? La réponse est simple : LaTeX n’est pas un langage de balisage, mais un langage de programmation. En plus de cela, c’est un mauvais langage de programmation. Cela pose tout un tas de problèmes plus ou moins graves. Les principaux reproches étant selon moi

1. L’absence de grammaire ou même de syntaxe au langage. En réalité, considérer LaTeX comme un langage à balisage est une erreur grossière. À tout moment dans le document, on peut écrire une commande qui a pour effet que « la lettre a devient la lettre c ». Cela fait qu’il est impossible de détecter une erreur de syntaxe, et donc

   • Les outils qui aident à écrire le code sont très imparfaits
   • Lorsque LaTeX n’arrive pas à générer un document correct, il est extrêmement difficile de savoir pourquoi, et la meilleure technique reste de supprimer des bouts de document pour isoler la ligne où une faute de frappe s’est glissée.
   • Il n’y a pas de prévisualisation rapide possible : pour savoir ce qui sera globalement affiché à la page 6, il faut écrire l’intégralité du document, ce qui peut-être très long si celui-ci est une thèse de 200 pages avec des images.

2. Le langage de programmation lui-même est terrible. Les programmes écrits sont simultanément très lents et illisibles.

3. L’écosystème autour du langage est riche mais du même temps incohérent. Par exemple, on peut être en contact avec 3 systèmes de gestion des citations différents — bibtex, natbib, biblatex —, relativement compatibles, mais pas toujours.

4. Les fonctionnalités un peu avancées (bibliographie, index, etc.) utilisent plusieurs passes de compilation. C’est un argument un peu technique, mais pour le néophyte, cela veut dire qu’en fonction du document à écrire, le temps de composition du rendu final peut être multiplié par 3 ou 4.

5. Le format de sortie, au départ, était DVI, qui n’est pas utilisé ou presque. Le format PDF s’est imposé comme standard et est maintenant bien géré, mais il est étrange que la quasi intégralité de la connaissance mondiale soit sous forme de HTML sur un internet mondiale sauf la recherche académique qui pourtant repose crucialement sur les citations de ressources pré-existantes. Cela veut aussi dire que tablettes, téléphones et ordinateurs de différentes tailles sont inadaptés comme médiums de lecture d’article, et d’ailleurs beaucoup de chercheurs impriment les articles pour les lire (et les annoter).

Markdown et Pandoc

Le Markdown est un langage de balisage léger qui a été conçu pour être lisible par un humain, et qui est facilement convertible en HTML. L’idée de base est de limiter les possibilités de balisage pour se concentrer sur le contenu, et non sur la forme, au point où le mark-up fait simplement partie du document lisible par un humain, d’où le jeu de mot mark-down. Par exemple, le fragment suivant est un exemple de Markdown :

Je suis dans un paragraphe. **Je suis en gras.** Et maintenant,
*je suis en italique*.

- Je suis dans une liste
- avec 
- plusieurs
- items

En tant que format de fichier texte destiné à être converti en HTML, le Markdown est un format de fichier encore moins adapté à l’écriture d’articles scientifiques. Cependant, il a plusieurs avantages :

• Il est facilement lisible par un humain, ce qui n’est pas le cas du HTML ou du LaTeX, et est un atout considérable pour la conservation des documents et leur archivage,
• Il est facilement convertible en HTML, ce qui permet de publier des articles sur le web sans effort.

L’histoire pourrait s’arrêter là : si le format est inadapté, alors il ne faut tout simplement pas l’utiliser. Toutefois, il existe un projet nommé Pandoc qui permet de convertir des documents écrits en Markdown en d’autres formats, comme LaTeX, HTML, Word, Open Document, ou PDF. Cette interopérabilité permet de placer le format Markdown comme un format de fichier qui est une sorte de plus petit dénominateur commun entre les différents formats de fichier représentant du texte. Plutôt que de vouloir convertir des documents entre HTML et LaTeX, pourquoi ne pas directement écrire en Markdown, et utiliser ce fichier pour générer différents documents ? Le gain potentiel est significatif : écrire un article une seule fois et pouvoir le soumettre à différentes conférences (qui utilisent des formats légèrement différents pour les soumissions), le publier sur le web, et en extraire une présentation pour un exposé semble tout bonnement miraculeux.

La raison qui pousse à croire que cela est possible est que Pandoc vient avec un système de filtres, qui permet d’enrichir la syntaxe de Markdown en exécutant du code écrit dans de véritables langages de programmation. En réalité, on peut même imaginer écrire simplement du texte « comme dans un courriel » et utiliser des filtres pour annoter correctement le texte dans différents formats. Un exemple que j’ai mis en place récemment est la création d’un site web pour un cours d’informatique, qui permet aussi d’avoir des feuilles de travaux dirigés au format PDF.

Les articles scientifiques ?

L’écriture d’articles scientifiques basés sur le système Pandoc est une sorte de mode qui revient périodiquement sur internet. Selon le créateur de Pandoc lui-même, John MacFarlane, il est possible d’écrire des articles scientifiques en Markdown et de les convertir en LaTeX pour les soumettre à des conférences, comme indiqué dans une présentation donnée à la conférence TUG 2020. Cette idée est séduisante et a été reprise par de nombreux blogueurs et auteurs qui ont tenté de décrire leur méthode pour écrire des articles scientifiques en utilisant Pandoc, j’en liste quelques-uns ici sans ordre particulier :

• https://jaantollander.com/post/scientific-writing-with-markdown/
• https://brainbaking.com/post/2021/02/writing-academic-papers-in-markdown/
• https://blog.kathyreid.id.au/2020/12/27/academic-writing-workflow/
• https://opensource.com/article/18/9/pandoc-research-paper
• https://nextlevel-blog.de/blog/pandoc/
• https://github.com/pandoc-scholar/pandoc-scholar

Au cœur de ces systèmes, on retrouve bien sûr Pandoc et son système de filtres qui agît essentiellement comme un gestionnaire d’effets algébriques pour ceux que cette analogie aide. Ainsi, plusieurs filtres ont trouvé une place centrale, similaire à celle des paquets LaTeX les plus utilisés :

• Pandoc Citeproc utilisé pour gérer les citations bibliographiques
• Pandoc Crossref utilisé pour gérer les références croisées entre les éléments du document

Cependant, il ne semble pas y avoir un consensus sur la manière d’écrire les théorèmes, définitions, preuves et autres éléments d’articles mathématiques en Markdown. De plus, il faut remarquer que le filtre Pandoc Citeproc utilise en réalité une syntaxe qui a été spécialement ajoutée dans l’arbre de syntaxe abstrait de Pandoc pour gérer les citations bibliographiques, et les deux sont tellement liés que le filtre a été directement intégré dans le programme principal. Cela tend à montrer que l’extensibilité est toute relative, et demande en général un couplage très fort avec le programme principal.

En réalité, tous les exemples donnés plus hauts fonctionnent à peu près, mais aucun n’est adapté à une publication d’un véritable article. En particulier, il manque

1. Un système de gestion des équations mathématiques, et particulièrement des macros. Pour le moment, Pandoc est capable de comprendre certaines macros, mais il faut ruser pour les utiliser dans différents formats simultanément, et globalement la solution est écrire du LaTeX directement en espérant que la conversion dans d’autres formats ne casse pas trop de choses.
2. Un système de gestion des références croisées équivalent ou supérieur à celui de LaTeX. En particulier, le fabuleux package Knowledge développé par Thomas Colcombet n’a aucun équivalent pour le moment. Notons d’ailleurs que les références entre des éléments du document et des symboles mathématiques dans une équation sont très difficiles à gérer.
3. Une gestion très manuelle des inclusions de fichiers, une fonctionnalité pourtant cruciale dès que les documents deviennent un peu longs.
4. Cela peut sembler « trivial », mais il faut réellement gérer les formats demandés par les conférences. Que cela soit dans le traitement des méta-données, dans les styles de citations, la liste des paquets utilisés et même la « chaîne de compilation » demandée. Certaines conférences utilisent des styles qui requièrent bibtex, là où Pandoc utilise au choix natbib ou biblatex.
5. Un système de prévisualisation rapide et la capacité de faire des aller-retours entre le code et le rendu final. Dans l’écosystème LaTeX, c’est le projet synctex qui permet de faire cela, et l’essayer c’est l’adopter.

En fait, tout le monde semble passer sous silence le besoin d’écrire des formules mathématiques complexes (et interopérables) dans un article scientifique en déléguant cette tâche. D’ailleurs, certains auteurs vont plus loin et écrivent directement du code LaTeX dans leur document, car il sera conservé tel quel à l’export : mais alors, où est l’intérêt de l’écrire en Markdown, si le seul format où l’export est correct est le LaTeX ?

Un des systèmes le plus avancé que j’ai trouvé est Quarto (anciennement nommé RStudio), qui est un système de publication scientifique basé sur Pandoc et qui permet de suivre un chercheur (en statistiques, économie ou sciences sociales principalement) tout au long de son processus de recherche, de l’analyse des données statistiques avec le langage R jusqu’à la publication de l’article en passant par la rédaction du manuscrit. Il semble y avoir un réel effort pour permettre la rédaction de documents, par exemple en ayant une gestion des figures, théorèmes et des références croisées, avec beaucoup d’options et un outil un peu « clef en main » pour génerer des exports corrects dans plusieurs formats. Cependant, même avec ce système, l’écriture des mathématiques reste un angle mort.

Conclusion

Pour écrire des articles de blog, un peu de mathématiques, et même des feuilles de travaux dirigés, Pandoc est un outil formidable. Mais il n’est pas adapté pour l’écriture d’articles scientifiques (en informatique théorique et en mathématiques), quoi qu’en dise le dernier proof of concept que l’on trouve sur internet.

Si vous n’aimez pas écrire du LaTeX, ce qui est complètement compréhensible, alors le mieux est de simplement… En écrire le plus simplement possible, avec le moins de paquets et de macros possibles. Cela rendra plus facile une éventuelle conversion ultérieure (mais vers quel format ?) et permettra de garder le document lisible par un humain.