Markdown et traitement de texte : une méthode pour collaborer
Dans le cadre de mon travail, j’essaie autant que possible de tout rédiger dans le même format d’écriture. L’idée est de pouvoir circuler sans trop de frictions (comprenez : pouvoir copier-coller librement) entre mes notes, mes supports de cours, mon site, mes articles de recherche.
Pour faire cela, j’ai choisi une technique simple et robuste, adaptée à mes besoins : le format texte. Dans mes fichiers texte, je rédige en Markdown, c’est-à-dire qu’au fur et à mesure que j’écris, j’utilise des caractères « spéciaux » (dièse, astérisque, tirets…) pour indiquer qu’une ligne correspond à un titre, qu’un mot doit être en italique, ou que ce paragraphe est une citation, etc. C’est une alternative aux logiciels de traitement de texte dans lesquels on clique par exemple sur un bouton pour mettre du texte en gras ou sur le style « Titre 1 » pour transformer un paragraphe en titre.
Voici un petit exemple de texte en Markdown. C’est une fiche de lecture, avec quelques métadonnées au début (entre les ---), des titres (commençant par #) pour indiquer différentes sections, un peu d’italique (les mots entre *) et une citation (commençant par >) :
---
title: As We May Link
date: 2022-04-01
type: fiche de lecture
---
# Résumé
« As We May Link » est un article de Jeremy Keith pour le magazine *The Manual*. Je le trouve remarquable pour l'originalité du récit qu'il fait de l’hypertexte. D'abord, c’est un texte anglophone non-scientifique postérieur à la redécouverte d’Otlet qui reconnaît l'importance de ce dernier et le positionne avant Vannevar Bush. Et ensuite, au lieu de parler de lien hypertexte à partir de Bush ou de Ted Nelson, il parle d'abord de lien tout court : il procède par abstraction, pour évoquer le principe sous-jacent – la connexion, l'association, la mise en relation. Ceci lui permet d'aller chercher des références historiques antérieures à Bush et même à Otlet : Leibniz (1666), Wilkins (1668).
# Lien avec Otlet
Selon Jeremy Keith, le travail d'Otlet et La Fontaine sur la Classification décimale universelle mérite qu'on les qualifie d'architectes de l'information :
> « *The Dewey Decimal Classification was later expanded by the Belgians Paul Otlet and Henri La Fontaine into a Universal Decimal Classification that used punctuation symbols to unlock further subdivisions of categorization. These people could legitimately be granted the title of true information architects* » [@keith2012, 62].Markdown a été conçu pour être relativement lisible tel quel. Je dirais que c’est plutôt réussi.
La fonction initiale de Markdown était de faciliter la création de contenus destinés au Web : on écrit en Markdown et un programme s’occupe de transformer notre texte en HTML.
Dans le monde scientifique, Markdown est également utilisé comme format d’écriture commun à différents outils. Ceci facilite la collaboration entre auteurs et permet de fédérer certains efforts entre développeurs.
En particulier, le logiciel de conversion Pandoc fait de Markdown une sorte de format pivot pour l’écriture scientifique. Pandoc définit quelques conventions d’écriture qui rendent Markdown viable pour des scientifiques, en ajoutant la possibilité d’intégrer facilement citations, tableaux complexes, notes de bas de page, formules mathématiques, etc. Par exemple, on met [@keith2012, 62] dans son texte et à la sortie on obtient un appel de citation du type (Keith 2012, p. 62), avec la référence complète en fin de texte. On a ainsi le même résultat que dans un traitement de texte avec un plugin qui traite les citations. Et surtout, Pandoc permet de convertir ses fichiers Markdown en différents formats de sortie (docx, pdf, html, xml, epub…). C’est ce qui permet de tout écrire dans un seul format, quel que soit le type de fichier qu’on doit produire à la fin.
Le problème
Le point le plus épineux dans ce système, c’est la collaboration, et notamment quand on doit travailler avec des personnes qui utilisent des logiciels de traitement de texte (comme Microsoft Word ou LibreOffice Writer).
Imaginons la situation suivante. Je suis doctorant, j’ai écrit un chapitre de ma thèse en Markdown (chapitre-1.md). Mon directeur ou ma directrice de thèse me demande une version pour traitement de texte afin de relire mon travail. Je crée donc un fichier docx (ou odt) via Pandoc, que je nomme par exemple chapitre-1-2022-10-25.docx pour faciliter le suivi des versions. Je l’envoie ; la personne qui me relit active le suivi des modifications dans son logiciel de traitement de texte, et me renvoie un fichier chapitre-1-2022-10-25-relu.docx avec des commentaires et des corrections.
Comment puis-je intégrer les corrections, faire d’autres changements et renvoyer une version corrigée qui affiche le suivi des modifications, le tout sans abandonner mon fichier texte en Markdown ?
La solution
Étape 1 : modifications
L’objectif étant de ne pas abandonner notre workflow basé sur un unique fichier texte, on ne va pas faire les modifications dans chapitre-1-2022-10-25-relu.docx mais dans chapitre-1.md. Ce dernier doit rester le fichier « maître ». Si on souhaite en conserver les différentes versions, on peut en faire des copies ou des exports datés, ou bien utiliser un logiciel de versionnement adapté au format texte, comme Git.
En pratique, on va donc ouvrir côte-à-côte chapitre-1-2022-10-25-relu.docx et chapitre-1.md, et modifier ce dernier d’après les remarques présentes dans le premier.
Étape 2 : nouvel export
Une fois les modifications effectuées, on exporte à nouveau le chapitre au format docx via Pandoc. On indique bien sûr dans le nom du fichier ainsi créé qu’il correspond à une nouvelle version. Si on utilise la date, le nouvel export s’intitulera par exemple chapitre-1-2022-11-16.docx.
Pour l’export lui-même, si vous utilisez un éditeur de texte qui intègre Pandoc sous le capot pour générer des exports, comme Zettlr, il suffit de cliquer sur le bouton prévu à cet effet. Si vous utilisez plutôt Pandoc en exécutant une commande vous-même dans un terminal, ça ressemble à ça :
pandoc chapitre-1.md -o chapitre-1-2022-11-16.docxEn fait, ça ressemble probablement plutôt à ça, car qui dit thèse dit modèle de document à respecter et citations à traiter : Dans l’exemple de commande ci-contre, les \ permettent d’écrire une commande sur plusieurs lignes. D’ordinaire, un retour à la ligne est interprété par le terminal comme le signal que la commande est terminée et qu’il doit l’exécuter. Mais mettre une option par ligne améliore la lisibilité de la commande et facilite la modification des options. D’où le recours aux \, qui permettent de faire des retours à la ligne sans interrompre la commande.
pandoc chapitre-1.md \
--reference-doc=gabarit.docx \
--citeproc \
--bibliography=references.json \
--csl=iso690-author-date-fr.csl \
-o chapitre-1-2022-11-16.docxÉtape 3 : faire apparaître les modifications
Une fois le fichier chapitre-1-2022-11-16.docx créé, on l’ouvre dans Word ou LibreOffice. On va alors utiliser la fonctionnalité qui permet de fusionner deux documents en intégrant les différences sous forme de modifications suivies. En clair, on ouvre la « v2 » du fichier et on demande au logiciel de traitement de texte d’y créer un suivi des modifications par rapport à la « v1 ».
Dans LibreOffice : Édition → Suivi des modifications → Fusionner le document (voir l’aide en ligne). Dans Word : Révision → Comparer → Combinaison (voir l’aide en ligne).
Dans les deux cas, il faut alors sélectionner le premier export docx (chapitre-1-2022-10-25.docx), pas le fichier relu (chapitre-1-2022-10-25-relu.docx). Ceci crée un suivi des modifications dans chapitre-1-2022-11-16.docx, qui montre les différences entre ce nouvel export et la version précédente.
Il n’y a plus qu’à envoyer le fichier chapitre-1-2022-11-16.docx à la personne qui nous relit et qui peut ainsi apprécier les changements effectués, le tout en ayant préservé notre workflow basé sur le format texte.
Wordless
J’ai précédemment écrit deux billets intitulés « Wordless », au contenu désormais tout à fait obsolète mais dont je voudrais rappeler l’esprit, car il s’applique ici.
L’idée était de montrer qu’on pouvait « faire du Word » sans Word. D’abord, rien ne m’oblige à utiliser Word pour produire du docx : LibreOffice Writer fait ça très bien. Mais si on veut écrire autrement, par exemple en Markdown, on peut aussi se passer complètement du traitement de texte et utiliser Pandoc pour créer des fichiers docx ou odt de manière triviale.
Mais ma position n’est pas d’être anti-traitement de texte. Je me sens obligé de le mentionner, parce qu’il y a un discours anti-WordDehut, « En finir avec Word ! », 2018.
, voire anti-traitement de texteVitali-Rosati, « Les chercheurs en SHS savent-ils écrire ? », 2018.
, que je rejoins globalement sur le fond mais moins sur la forme. Je crains en effet que le ton de ces discours fasse du tort aux techniques que nous essayons de promouvoir. Je ne voudrais pas que Markdown aujourd’hui soit défendu comme LaTeX hier, c’est-à-dire depuis un Aventin de technophiles éclairés, conduisant de fait à la marginalisation du format texte dans les pratiques d’écriture en SHS.
On ne peut pas nier que le traitement de texte répond à des préférences et besoins précis en matière d’interface d’écriture : voir le nombre de pages qu’on est en train d’écrire ; surligner avec différentes couleurs ; commenter des suggestions de modification ; etc. Il n’existe pas toujours d’équivalent fonctionnel à cela dans l’écosystème du format texte. Et quand cela existe, ce n’est pas toujours sous une forme pratique, mature, fiable.
Par conséquent, si on trouvera toujours quelques collègues pour s’essayer à de nouvelles formes d’éditorialisation, il n’est pas simple d’embarquer derrière soi toutes les autres personnes avec qui on doit collaborer. C’est pourquoi il me semble crucial de disposer de techniques qui permettent une coexistence pacifique et productive entre traitement de texte et format texte, en attendant que l’écosystème qui se développe autour du second ait suffisamment progressé pour constituer une alternative complète au premier.
La méthode que je présente dans ce billet s’inscrit dans cette perspective. Je l’ai utilisée pour organiser la relecture et la correction de ma thèse, ce qui a parfaitement fonctionné. Il me tenait à cœur de prouver que ma pratique était compatible avec les attentes de mes directeurs de thèse ; de montrer qu’il ne s’agissait pas d’une excentricité de ma part ni d’une expérimentation discutable mais d’une alternative fonctionnelle ; de défendre le format texte comme un choix pragmatique et non pas dogmatique.
De façon plus large, l’écriture de ma thèse m’a permis de mettre à l’épreuve la promesse du format texte, c’est-à-dire la libre circulation entre les formats. J’ai vraiment l’impression d’avoir eu le beurre et l’argent du beurre : la relecture collaborative du manuscrit en docx ; l’impression et l’archivage du mémoire en pdf ; la publication en html pour l’accessibilité et la valorisation sur le Web ; le tout à partir d’un unique format d’écriture qui m’a aidé à me concentrer et qui m’a fait gagner un temps fou au moment d’intégrer mes notes de travail dans le manuscrit. J’ai d’autant plus envie que d’autres puissent s’en saisir, et ça commence avec des astuces simples comme celle présentée ici.