Colophon

Détails techniques sur l'écriture, l'édition, la publication et la diffusion de mon livre "L’écriture académique au format texte avec Markdown et Pandoc".

(Merci à @ThierryStoehr@framapiaf.org de m'avoir suggéré la rédaction de cette page de making off et d'en avoir proposé le titre.)

Les choix posés dès le départ pour la réalisation de ce projet :

• uniquement (autant que possible en tout cas) des logiciels libres et des formats ouverts
• des solutions que je comprends et que je maîtrise (et que je peux expliquer)
• une réflexion low-tech :
  • accessible (pour toutes les personnes concernées),
  • utile (pourquoi changer si ce n'est pour faire mieux ?)
  • durable (techniquement mais aussi écologiquement)
• le choix systématique de la solution la plus simple et la plus ouverte

Niveaux compétences je me situe à mi-chemin entre l'utilisateur de base qui se laisse guider (et qui a totalement perdu le contrôle) et le geek compétent jusqu'au dernier point-virgule. Donc, un utilisateur averti qui se débrouille mais dont ses limites sont fixées par la compréhension et la maîtrise. Je me pose systématiquement la question de ma légitimité dans mes projets. Hanté régulièrement par le syndrome de l'imposteur, j'ai quand même réussi à avancer...

Le projet

Après mon départ à la retraite en juin 2024, il m'a semblé nécessaire de revoir le manuel "Markdown & vous", publié via e-publish en 2023. Il a été régulièrement mis à jour mais un travail était nécessaire pour le compléter, le revoir en profondeur.

Ce travail de révision a débuté par la création, avec Quarto, d'un site compagnon (aujourd'hui fermé), avec l'évaluation et l'intégration, dans le code Markdown, de nombreuses commandes LaTeX et plusieurs exemples pratiques.

(Le site compagnon de "Markdown & vous")

Parallèlement, j'ai entrepris, sur mon site perso (voir les archives du site infolit.be), la rédaction de plusieurs pages liées à la science ouverte, à l'édition numérique et au développement durable, associé à un gros travail bibliographique dans ces trois domaines et sur Markdown.

Avec en plus le besoin d'un nouveau support pour les ateliers de formation à l'utilisation de Markdown que je continue à donner dans les formations transversales ULiège à destination des doctorants, le projet d'un nouveau manuel a rapidement germé.

Je suis bien conscient qu'apprendre Markdown (ou un autre format) ce n'est pas juste apprendre un nouveau langage mais c'est avant tout adhérer à de nouvelles méthodes et à de nouveaux outils, c'est décider de reprendre le contrôle. Il fallait donc aussi convaincre.

Rédiger

Sur base de tout le matériel rassemblé ("Markdown & vous", le site compagnon, les pages web sur la science ouverte, l'édition numérique et le développement durable), j'ai construit la structure d'un nouveau manuel en cinq parties :

• reprendre le contrôle de son numérique et la genèse de Markdown ;
• le Pandoc-Markdown ;
• l'utilisation de LaTeX dans les fichiers Markdown ;
• des exemples pratiques ;
• quelques compléments dont des liens et un aide-mémoire, une conclusion et la bibliographie.

Pour faciliter la gestion du projet, tous les chapitres et parties on fait l'objet d'un fichier à part. Les fichiers (Markdown) ont été numérotés pour être traités, dans le bon ordre, par Pandoc, en une seule commande :

Pandoc --citeproc *.md -o livre.pdf

Le nom du fichier de l'entête YAML (dans un fichier séparé donc) débute par 00 (00yaml.md), l'intro et les compléments commencent par 01, puis 02 et ainsi de suite. Pour la première partie, les noms des fichiers commencent par 10, 20 pour la deuxième, 30 pour la troisième etc.

Un système simple qui évite de se prendre la tête. Cela représente en définitive 31 fichiers Markdown auxquels sont ajoutés les deux fichiers pour la bibliographie (un fichier csl et un fichier bib) et un dossier avec 61 images.

Il est intéressant à ce stade de décrire l'infrastructure informatique qui m'a permis la création du manuel.

L'ensemble repose sur un espace Nextcloud hébergé par Zaclys.

Point de vue matériel, je dispose d'un PC portable Dell (xps13 de 2019 avec une batterie toute neuve qui m'a fait passer de 7 minutes d'autonomie à 7h) tournant sous Debian, d'un PC fixe (un MacBook pro 2017 avec écran cassé) tournant sous Linux Mint, d'une tablette 9' Lenovo bon marché et d'un Fairphone 3+, tous deux degooglisés au max (pas de compte gmail associé, toutes les applis Google désactivées, tout particulièrement les applis Google play et Gboard, particulièrement intrusives, remplacées par Fdroid et Aurora store pour les magasins d'applications et Helliboard pour le clavier à l'écran).

Pour Linux et pour Android, il y a des applis spécifiques pour accéder aux données sous Nextcloud.

Sous Linux, l'application intègre de façon transparente le disque distant dans le navigateur de fichiers avec une synchronisation dont on peut régler l'étendue et la fréquence. Les applications sous Linux ne font pas la différence entre le répertoire Nextcloud et les autres dossiers qui sont sur le disque dur. Donc pas de souci avec Pandoc.

(Le listing, sous Linux, des fichiers utilisés)

Sous Linux, c'est l'éditeur de texte de base qui a été utilisé. La coloration syntaxique qu'il propose est très pratique pour éditer les fichiers Markdown.

(L'éditeur de texte sous Linux)

Pour Android, l'application donne accès à tous les contenus Nextcloud avec un éditeur intégré pour tous les fichiers au format texte.

(Deux captures d'écran de l'application Nexcloud sous Android)

Donc quatre outils différents, totalement synchronisés, pour écrire.

Pour travailler à plusieurs ou pour simplement partager, Nextcloud est très efficace. Nextcloud gère aussi un historique des fichiers et donc permet de revenir en arrière.

Éditer

Pour des raisons de visibilité mais aussi pour sortir un peu de l'Université de Liège où je travaillais depuis août 1997, mon premier manuscrit a dans un premier temps été soumis successivement à trois éditeurs français sensibles au numérique, qui, pour de bonnes raisons à chaque fois, ont décliné.

Je me suis dès lors retrouvé devant le choix de faire de l'auto-édition (avec Quarto par exemple) ou de me tourner vers mon ancien employeur, l'Université de Liège, avec d'une part ULiège Library et la plateforme e-publish (qui tourne sous Pressbooks) et d'autre part les Presses universitaires de Liège (PUL).

Le second choix était probablement le plus raisonnable et me permettait de ne pas travailler seul, de valider mon projet et de bénéficier d'infrastructures que je connaissais bien. En effet, j'ai été pendant plus leurs années co-directeur (pour Gembloux) des PUL et c'est votre serviteur qui a créé e-publish en 2019 (voir la présentation).

En 2020, j'ai déjà eu l'occasion de piloter la publication, en co-édition (e-publish & PUL), de trois essais. Cette aventure a été présentée une première fois lors des rencontres Medici de 2023 à Liège.

Donc, après un premier accord de principe de la part des deux responsables, le manuscrit a été soumis au processus de peer reviewing qui a permis de confirmer l'accord de publication.

J'ai alors importé le manuscrit dans e-publish. Plusieurs options ont été testées mais c'est en définitive l'importation de l'ensemble via un fichier ePub (crée avec Pandoc) qui a été l'option la plus "propre" et permis de conserver la structure, les niveaux de titre, le formatage du texte, les liens, les notes, les images et leur légende et les tableaux.

(La gestion de la structure du livre dans e-publish)

Après l'intégration des corrections demandées par le reviewer, des phases de relecture successives (par mon entourage et moi-même), quelques corrections et améliorations (ajouts de liens internes, scan complet avec Grammalecte, vérifications diverses...), l'équipe e-publish a exporté (en pdf) une première épreuve et l'a transmise aux PUL.

Le retour concernait des corrections sur le fond et sur la forme (surtout). Ça a donc été un travail collectif pour d'une part retravailler le texte et d'autre part le formatage du pdf. Un gros travail sur la css (utilisée par PrinceXML pour produire le pdf) a été nécessaire pour que le lay-out corresponde au mieux à la feuille de style des PUL (police, tailles, format des notes, titres courants, pagination...).

(L'écran de mofidifaction de la CSS)

Ce travail a été jugé suffisamment efficace pour que la seconde et dernière épreuve ne nécessite que quelques corrections mineures.

Publier et diffuser

Une fois ce travail terminé, le site e-publish.uliege.be/md2 a été rendu public et c'est ULiège Library qui s'est chargé de la notice dans le DOAB et l'ajout d'un DOI via Crossref (10.25518/978-2-87019-340-2). De mon côté, j'ai créé une entrée dans ORBi (le répertoire institutionnel de l'université de Liège) pour y déposer le fichier pdf et le fichier ePub qui peuvent être appelés depuis la page acheter/télécharger dans e-publish.

Les PUL ont pris en charge l'impression du livre avec le fichier pdf imprimeur créé par e-publish et par la suite intégré le livre dans leur catalogue, dans la collection "manuels". Ils se sont chargés des opérations habituelles de diffusion (Électre, banque du livre...).

Commentaires

Le processus de co-edition décrit ci-dessus, est à mon avis original pour deux raisons.

La première est la répartition des rôles entre un éditeur traditionnel (les PUL) et un opérateur numérique (ULiège Library). D'une manière générale, le processus s'est déroulé de manière fluide, chacun connaissant bien son rôle (pour rappel, ce n'est pas le premier projet). L'idéal serait à terme de créer une collection spécifique avec une feuille de style spécifique et un contrat d'auteur adapté à la licence CC-BY (ce qui n'a pas été le cas ici).

La seconde spécificité est l'implication de l'auteur dans le projet. e-publish a dès le départ été pensé pour associer l'auteur autant que possible. Pressbooks le permet grâce aux rôles spécifiques qu'il prévoit et grâce à l'éditeur intégré de WordPress, assez facile à prendre en main.

(L'éditeur intégré de Wordpress pour PressBooks)

Étant à la base du projet, je n'ai eu aucune difficulté. Les projets futurs prévoient d'inclure une formation des auteurs (avec un accompagnement de l'équipe ULiège Library).

En définitive, l'ensemble du processus repose autant que possible sur des outils libres. Côté e-publish, l'export pdf est réalisé avec le logiciel PrinceXML, qui est la seule brique logicielle propriétaire. Des alternatives existent mais les ressources humaines sont nécessaires pour avancer de ce côté.

Côté PUL, les pages liminaires et la couverture ont été composées avec des produits Adobe. Cette situation est spécifique à l'édition traditionnelle et risque de perdurer un certain temps...

Le projet AcOBE a bien analysé tous les processus en cours et proposé des solutions.

On peut néanmoins affirmer que ce projet est un vrai projet numérique 😄

Bernard Pochet (octobre 2025)